Agent 审核（外部大模型复核）

背景：许多编码 Agent 的主力模型较小（GLM-Flash、Claude Haiku、GPT 小杯档位等），容易在完成任务后自称"完成了、没问题"，但实际存在遗漏或错误。本技能把当前工作交给外部大模型复核，找出小模型没发现的问题。适用于 Claude Code、ZCode 等支持 Agent Skills 的编码工具。

两种模式：

• 工作复核（默认，主模式）：复核当前会话刚完成的工作成果。
• 配置审核：审核 Agent 自身的配置（指令、技能、MCP、Hooks），用户明确要求时使用，见文末。

两种模式都用脚本发起调用——会话内 MCP 工具（mcp__llm-chat__chat）有 30 秒调用超时，大模型生成长回复通常超过它。复核引擎有两个，默认用 codex：

引擎 codex（默认）——本地 Codex CLI（ChatGPT 套餐）：

bash <本技能目录>/scripts/codex_call.sh <prompt文件> <报告输出文件> [被审工作目录] [模型]

Codex 是能动手的 Agent：它会在 read-only 沙箱里自己读文件、自己跑命令做独立验证，不只依赖转述的材料，代码任务尤其占优。走这个引擎时第 2 步的材料可以精简——不必嵌入产出全文，只写【原始要求】+【Agent 的声明】+ 产出文件的路径清单，并注明工作目录让 Codex 自己去读。模型默认取 ~/.codex/config.toml 的配置；沙箱固定 read-only（它只读和跑代码，改不了文件），不要改用 danger-full-access。

引擎 opus——llm-chat 端点的 Opus 5.5，写作、调研、配置等纯文本复核可选用：

python3 <本技能目录>/scripts/audit_call.py --prompt-file <prompt文件> --output <报告输出文件>

凭证来源：环境变量 LLM_API_KEY / LLM_BASE_URL 优先（任意 OpenAI 兼容服务均可）；未设置时从 llm-chat 的 MCP 注册配置（~/.zcode/cli/config.json，回退 ~/.claude.json）读取。默认模型 claude-opus-5-5（脚本失败报模型不存在时改用 --model 换成端点上可用的模型，并在报告注明），网络超时 300 秒、max_tokens 16000，成功后打印 OUT=<报告路径>。不要把密钥打印出来。

用户点名引擎时照办；拿不准或想要交叉验证时，两个引擎都跑一遍对比意见。报告里一律注明用了哪个引擎和模型。

模式一：工作复核（主模式）

第 1 步：确定复核对象

• 用户指定了具体产出（某个文件、某篇文章、某次改动）→ 复核那个。
• 没指定 → 复核当前会话刚完成的最后一件工作。

第 2 步：收集材料，写入 /tmp/opus-review-prompt.md

材料四部分，缺一不可：

1. 【原始要求】：用户的原话，尽量原样引用，不要改写美化。
2. 【Agent 的声明】：Agent 对成果的关键结论原话（"已完成 X""测试通过""没问题"这类）。这些声明是本次复核要检验的对象，逐条列出。
3. 【实际产出】：
   • 文件类产出：把涉及的新建/修改文件逐个读真实内容嵌入（超长截断保留核心）。不要凭记忆转述，小模型的记忆和磁盘上的实际内容可能不一致。
   • 代码任务：先实际运行一遍（测试/编译/主流程），把真实输出嵌入。"声称能跑"和"真能跑"要分开验证。
   • 命令/配置类产出：嵌入实际执行输出或配置文件内容。
4. 【已知风险点】（可选）：会话中出现过但被忽略的警告、被跳过的步骤。

第 3 步：构造复核要求并调用

prompt 末尾附审查要求。通用项（必选）+ 按任务类型选用：

• 通用必选：是否完整满足【原始要求】的每一点？【Agent 的声明】中哪些与材料不符或证据不足？有无遗漏的边界情况与后续风险？
• 代码：逻辑正确性、边界条件、错误处理、安全隐患、测试是否真实验证了行为。
• 写作：结构、逻辑、事实准确性、语病错字、是否符合目标文体和读者。
• 翻译：忠实度、术语一致性、语言自然度。
• 调研/报告：结论是否被材料支撑、有无编造或夸大、数据来源可靠性。

并要求 Opus：只依据材料下结论；材料不足以判断时明确说"材料不足"，禁止猜测；每条问题给证据和具体修改建议。

输出格式：

## 总体结论
（2-3 句：能否认可"完成"的说法）

## 发现的问题
### [P0 或 P1 或 P2] 标题
- 问题：……
- 证据：……（引用材料具体内容）
- 建议：……（具体怎么做）

P0=结论不成立或必须修；P1=应该修；P2=可选优化。

## 确认无误的方面
（简要列出，避免报告只报忧）

调用后先检查报告结尾是否完整：应以「确认无误的方面」收尾。codex 引擎若截断，直接重跑一次；opus 引擎截断说明被 max_tokens 限制，用 --max-tokens 24000 重跑，或把已生成的报告 + 「从截断处继续，不要重复」发过去拼接。

第 4 步：汇报

• 重点汇报与 Agent 声明矛盾的问题——小模型说没问题但大模型发现问题的点，逐条用完整句子说清，别只贴标题。
• 报告存到当前工作目录 docs/opus-review/YYYY-MM-DD-主题.md（开头注明审核时间、审核模型、材料说明）。
• 审核意见是外部模型的观点：忠实转述，意见与自己的判断有出入时两种说法都写明；未经用户确认不要按意见直接修改成果。发现 P0 时明确提醒用户。

模式二：配置审核（用户明确要求时）

1. 运行收集脚本（材料已脱敏：主目录替换为 ~、常见 API Key 打码）：

bash <本技能目录>/scripts/collect_context.sh

材料写入 /tmp/agent-audit-context.md，末行打印 CONTEXT_FILE=<路径>。每个文件超 8000 字符自动截断。

2. 手工在材料末尾补一节【会话级观察】：当前会话模型、实际观察到的 Agent 行为问题。只写有实证的，没观察到就不写。
3. 构造 prompt：审核维度 = 指令质量 / 技能配置 / MCP 与插件 / Hooks 与权限 / 工作流效率；输出格式 = 总体评价 + P0/P1/P2 意见（问题/证据/建议）+ 做得好的地方。
4. 调用与截断处理同模式一。报告存 docs/agent-audit/YYYY-MM-DD-HHMM.md。

注意事项

• 审核材料只发给两个复核引擎之一：llm-chat 内部端点（opus 引擎）或本地 Codex CLI（codex 引擎，走用户自己的 ChatGPT 账号），禁止发给其他外部服务。
• 材料涉及未发表稿件、隐私内容时，发送前先向用户确认。
• 调用失败时层层回退：codex 报未登录 → 提醒用户 codex login；codex 其他失败或纯文本复核不适用 → 改用 opus 引擎（audit_call.py）；opus 也失败 → 回退 mcp__llm-chat__chat（长材料会超时，先精简）；全部失败 → 如实告知用户，不要伪造报告。