第 4 课：代码安全审计 agent

最后一课会回答整条课程里最难的问题： 同一个内核，能不能支撑一个真正严肃的领域 agent，而不坍缩成定制 orchestration？ QitOS 给出的答案是：可以，但前提是你把领域逻辑放对地方。本课对应的示例是 examples/real/code_security_audit_agent.py。

相比第 3 课的变化

设计分支	Claude Code 风格课	安全审计课
目标	修改代码并验证 patch	检查仓库、收集证据并排序 findings
Tool surface	通用 coding preset	安全审计工具 + codebase tools + task board
Prompt policy	编码 workflow discipline	审计协议与证据纪律
State	todos 与 mode	scratchpad 与 ranked findings
成功条件	验证命令通过	高信号 final audit report
qita 作用	调试长时运行行为	产出可供审阅的 review artifact

system prompt 现在在教一种审计协议

这一课使用 SECURITY_AUDIT_SYSTEM_PROMPT，其中通常会明确写出：

Primary objective:
- Audit the repository for meaningful security risk, not just keyword matches.
- Use tools to collect evidence before making strong claims.

Judgment rules:
- Treat tool output as evidence, not proof.
- Separate results into:
  1. confirmed issue
  2. high-value lead
  3. human review needed
- Prefer a small number of high-signal findings over a long noisy list.

这其实就是整条课程里 prompt 设计梯子的最后一级：

第 1 课：parser contract
第 2 课：planner 与 executor contract
第 3 课：workflow discipline
第 4 课：domain judgment protocol

而 runtime 仍然没有变。

parser 与 harness 仍然保持稳定

这个审计 agent 仍然使用：

model_parser=ReActTextParser()

并继续走 text-first 的 OpenAI-compatible harness。这点非常重要，因为它证明了一件事： 领域专门化默认不需要更换 protocol。 只有当领域真正受益于新协议时，才值得升级，例如：

你需要更严格机器可读输出时，改用 JSON / XML
provider 原生 structured tool calls 更可靠时，使用 native tool-call parser
agent 驱动的是交互式终端而不是仓库工具时，使用 Terminus 风格协议

QitOS 支持这些路径，但默认研究路径依然是 provider-agnostic 的文本 ReAct。

按领域组合 tool surface

这一课会组合三类工具：

super().__init__(
    toolset=[
        SecurityAuditToolSet(
            workspace_root=workspace_root,
            include_external=False,
            max_matches=80,
        ),
        CodingToolSet(
            workspace_root=workspace_root,
            include_notebook=False,
            enable_lsp=False,
            enable_tasks=False,
            enable_web=False,
            expose_legacy_aliases=True,
            expose_modern_names=False,
            profile="codebase",
        ),
        TaskToolSet(workspace_root=workspace_root),
    ],
    llm=llm,
    model_parser=ReActTextParser(),
)

这是整条课程关于 tool composition 的收官。此时工具面开始呈现分层：

SecurityAuditToolSet 提供领域审计能力
CodingToolSet(profile="codebase") 提供低层代码库检查能力
TaskToolSet 提供显式进度跟踪

这就是 QitOS 希望你用来专门化 agent 的方式：组合环境，而不是重写 loop。

让 prompt 与 prepare 共同编码审计方法

prompt 负责定义全局审计纪律，而 prepare() 负责定义当前阶段的局部 framing：

lines = [
    f"Audit task: {state.task}",
    f"Workspace: {WORKSPACE}",
    f"Step: {state.current_step}/{state.max_steps}",
    "Suggested flow: inventory -> entrypoints -> sinks/secrets/config/dependencies -> hotspots -> final ranked findings.",
]

这一模式很重要：

system prompt 定义全局方法论
prepare() 定义本步上下文

把 findings 作为一等 state

审计 state 反而应该保持精简：

@dataclass
class SecurityAuditState(StateSchema):
    scratchpad: list[str] = field(default_factory=list)
    findings: list[str] = field(default_factory=list)

对这个领域来说，下一步模型并不需要：

所有 grep 结果
所有文件列表
所有中间工具 payload

它真正需要的是：

最近的审计轨迹
目前最值得保留的候选 findings

让 reduce 负责证据压缩与排名

示例里通常只会从工具输出中抽取最高信号 findings：

if isinstance(first, dict):
    data = (
        first.get("data", {})
        if isinstance(first.get("data", {}), dict)
        else {}
    )
    for item in list(data.get("findings", []) or [])[:3]:
        title = str(item.get("title", "finding"))
        location = f"{item.get('file', '?')}:{item.get('line', '?')}"
        state.findings.append(f"{title} @ {location}")
    if decision.mode == "final":
        state.final_result = str(decision.final_answer or "")

这仍然是在重复整个课程的一条主线：

raw evidence 留在 traces
compact working memory 留在 state

使用 bounded history，而不是无限累积

这一课的示例一般会使用：

history_policy=HistoryPolicy(max_messages=14)

这是一个很强的默认值，因为它既能保留最近 reasoning 与证据，又不会让模型每步都重新阅读大量历史搜索结果。如果你准备把审计扩展成更大的工作流，下一个升级通常是 CompactHistory，而不是无上限 history。

只有当 memory 真能改变结果时再加它

这一课默认仍然不挂载单独 memory adapter。对教程来说，这是正确的：

findings 已经承担了压缩型 state memory 的角色
qita 会保留完整 trace 供后续审阅
额外 retrieval 层只会让课程复杂化

当你真的需要这些能力时，再引入 memory：

跨 run 的长期 findings
对历史审计结果的语义检索
不适合放在即时 prompt 中的持久笔记

把 qita 当成 review artifact，而不只是 debugger

运行：

python examples/real/code_security_audit_agent.py

查看：

qita board --logdir runs

这一课里，qita 的角色已经超过“调试器”：

它帮助你检查 agent 是否先做 inventory 再下结论
它帮助你看哪些 findings 被提升到了 state.findings
它帮助你确认 parser diagnostics 是否稳定
它帮助你判断 context pressure 是否影响了审计质量
它帮助你把 final answer 读成一份 ranked review，而不是一堆原始 grep 命中

这门课程的最终设计规则

到第 4 课结束时，有一条规则应该已经变得很自然： 领域逻辑应该放在：

state 设计
prompt policy
tool composition
reduce() 语义

而不应该藏在另一个隐式 runtime 里。

Whitzard 与 model-native scaffolding

上面这条课程路线始终使用最可迁移的那条路径：

文本优先的 prompt contract
prompt 注入的 tool schema
ReActTextParser

这依然是最好的起点。但 QitOS 并不限于这一种组合。如果你去看 examples/real/whitzard_agent.py，你会看到课程之外的下一个设计点： 有些时候，模型与 scaffolding 应该一起设计。 例如某些模型在 native XML-like tool calls 上有更强先验，这时如果你强迫它始终走纯 JSON 契约，agent 也许还能工作，但贴合度会更差。这也是为什么 QitOS 把这些选择当成协调后的 protocol decision，而不是彼此孤立的 knobs：

parser
tool schema 风格
output contract
repair path

Whitzard 的价值不只是它是一个更强的审计 agent，更在于它让一个更普遍的设计原则变得具体： 当模型有很强的原生 tool-calling prior 时，适配 scaffolding 往往比强迫所有模型走同一协议更合理。

完整示例

完整可运行代码位于：

后续阅读

构建你自己的 Agent

以整条课程里的设计工作表为模板，开始设计自己的 AgentModule

Kit 参考

查询课程中出现过的 parsers、prompts、toolsets、memory 与 history helpers

可观测性

深入掌握 qita 的 replay、export 与研究级分享能力

基准测试

把同一个内核迁移到 GAIA、Tau-Bench 与 CyBench

开始使用

​相比第 3 课的变化

​system prompt 现在在教一种审计协议

​parser 与 harness 仍然保持稳定

​这门课程的最终设计规则

​Whitzard 与 model-native scaffolding

​完整示例

​后续阅读