plan_auditor — Claude Code 双模型协作审计工具

人类阅读

使用场景

单个模型在制定实施计划时有天然的”自说自话”盲区 —— 它写出的计划自己审、自己批，容易遗漏边界条件、错误假设、不可执行步骤、安全/数据风险，且不会自我纠偏。

plan_auditor 引入第二个模型对计划做对抗式审计，把单模型自审变成一个简易的多 agent 协作闭环：

Claude (中端/主力,负责规划)      外部 LLM (高端/审计,负责挑刺)
         │                              │
         │   ExitPlanMode ──► 计划全文   │
         │                   ────────►   │  审计
         │   ◄── APPROVED ───── 放行     │
         │   ◄── DENY + 反馈 ── 驳回修订 │
         │       (迭代,最多 N 轮)        │
         │   ◄── MAX_PASSTHROUGH ─ 超轮  │
         │              交用户决策       │

这样可以用中端模型（或低成本模型）做主力规划，配一个更强的模型（如 gpt-5.5）做专项审计，既提升计划质量，又能根据任务复杂度灵活配置模型组合来控制成本。严格来说，这是基于 Claude Code hook 机制实现的一个轻量多 agent 协作工具。

概念

PreToolUse(ExitPlanMode) hook：Claude Code 退出计划模式时，先拦截 ExitPlanMode 工具调用，把计划全文发给外部 LLM 审计，然后根据审计结论决定放行还是驳回。
对抗式审计：审计方是独立模型，不参与规划，只负责找漏洞。
迭代闭环：驳回 → Claude 收到反馈修订 → 再次 ExitPlanMode → 再审，最多 max_rounds 轮。
防死循环：超过 max_rounds 后强制放行，最终决策权始终在用户手里。
fail-open：任何异常（配置缺失、网络错误、JSON 解析失败、LLM 超时）一律放行，不卡死用户。

安全提醒

工具将实施计划全文发给第三方 LLM 端点。不要在计划中放置密钥、凭证或敏感数据。 logs/plan_auditor.log（含计划正文片段 + 端点 URL + 模型名）与 rounds.json （含计划文件绝对路径）属敏感运行产物，切勿提交到仓库，建议加入 .gitignore。

部署建议

推荐在项目级 settings.json 部署，不要挂在用户全局。 每次 ExitPlanMode 都会调用外部 LLM，产生额外的时间（单次约 3~30 秒）与金钱（API 调用费用）开销。挂用户全局的话每次制定计划都会被审计，成本不可控。只在需要审计的重要项目中启用，用完即关。

Agent 阅读

安装（Windows）

AI 部署指令：以下操作在 Windows 环境下执行。含 # 编号的为可直接跟做的步骤。变量 $HOOK_DIR = 本 README 所在目录，$PYTHON = Python 解释器绝对路径。

#1 注册 hook

在项目级 .claude/settings.json 添加 PreToolUse hook。不建议挂在用户级全局配置，否则每次 ExitPlanMode 都触发审计，累积的时间与 API 费用不可控。JSON 模板（路径用占位符，必须替换为实际路径）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:/path/to/python.exe\" \"D:/path/to/.claude/hooks/plan_auditor.py\""
          }
        ]
      }
    ]
  }
}

#2 填写配置

复制 plan_auditor.config.json 到同目录，填写 llm.url / llm.key / llm.model。

#3 首次部署验证

$PYTHON $HOOK_DIR/setup_check.py

逐项检查 6 步：Python → config → 端点 → 鉴权 → 模型 → 全链路。全部通过后脚本自删（DEBUG=0 时）；任一项 FAIL 则保留并给出修复建议。

#4 重启

重启 Claude Code 会话（项目 settings.json 不保证热重载）。

关键参数

字段	说明	默认值	选型建议
`llm.url`	OpenAI 兼容 chat completions 端点	需填写	—
`llm.key`	API Key	需填写	勿提交真实 key，示例用 `sk-xxxxxxxx`
`llm.model`	审计模型名	需填写	reasoning 模型脚本已自动发 `reasoning:{"effort":"none"}` 关思考以避免偶发超时
`audit.max_rounds`	最大审计迭代轮次	3	越小越快放行（0=不审计直接过，1=最多审 1 轮）；调大则更严格但可能多轮迭代
`audit.max_feedback_chars`	回喂给 Claude 的反馈字符上限（超出截断）	2048	—
`audit.timeout`	调审计模型超时秒数	60	reasoning 类模型或网络不稳时建议 ≥60

最小配置示例（脱敏）

{
  "llm": {
    "url": "https://your-gateway.example/v1/chat/completions",
    "key": "sk-xxxxxxxx",
    "model": "gpt-5.5"
  },
  "audit": {
    "max_rounds": 3,
    "max_feedback_chars": 2048,
    "timeout": 60
  }
}

Windows 注意事项

路径含中文或空格时，settings.json command 中路径必须双引号包裹并 JSON 转义反斜杠。
脚本已强制 stdout UTF-8（Windows 默认 cp936 会导致中文反馈乱码）。
所有路径分隔符使用 / 或转义的 \\，不要用裸 \。

AI 排障指南

AI Agent 注意：以下为纯操作条目，出现问题时逐条执行即可定位。

#A1 查日志

日志路径：$HOOK_DIR/../logs/plan_auditor.log。所有运行信息在此。超 1MB 自动清空。

#A2 关键字-原因映射表

读到某关键字时，按右列行动：

在日志中找到	结论	行动
完全没有这个日志文件	hook 从未执行	检查 #1 注册是否正确；settings.json 语法过 `json.tool`；command 中 Python 路径与脚本路径是否存在
`START` 存在但无后续	进程拉起后 stdin/JSON 阶段退出	不是 hook 本身问题，等待 Claude 实际调用 ExitPlanMode 时再看
`STDIN_PARSE_FAIL`	Claude 传入的 payload 不是合法 UTF-8 JSON	检查 Claude Code 版本是否兼容；payload 格式异常——这通常是 Claude Code 内部问题，非本工具 bug
`INVOKED` 存在但无 `call_llm FAIL` 也无 `verdict=`	脚本在调 LLM 前退出（config/key 缺失？）	跑 `setup_check.py` 验证 config 完整性
`call_llm FAIL TimeoutError`	LLM 超时	① 提高 `audit.timeout` 到 90+ ② 换更快的模型 ③ reasoning 模型确认已关思考（`plan_auditor.py` 内置已做）
`verdict=DENY`	正常行为，审计不通过	按反馈修订计划后再次 ExitPlanMode
`verdict=MAX_PASSTHROUGH`	已超 `max_rounds`，强制放行	计划交用户自行决策；若不想再看审计噪声，调小 `max_rounds` 或暂时禁用
反馈中文乱码	stdout 编码异常	确认 `plan_auditor.py` 中 `sys.stdout.reconfigure(encoding="utf-8")` 未被移除

#A3 禁用方法

需求	操作
干净禁用（不发请求）	清空 `plan_auditor.config.json` 的 `llm.key` —— 脚本源码 `call_llm` 在 key 为空时直接 `return None` 不发请求
完全移除	从 settings.json 删除 hook 注册项 → 重启 Claude Code 会话
误 deny 噪声大	调小 `audit.max_rounds`——越小越快强制放行（设为 0 完全不审计）

可移植性

将本目录（plan_auditor.py + plan_auditor.config.json + setup_check.py）拷贝到目标项目的 .claude/hooks/ 下，按 #1~#4 步骤执行即可。前置条件：目标机有 Python 3.8+ （脚本仅用标准库，无第三方依赖）、网络可达所选端点、.claude/logs/ 可写。

文件

.claude/hooks/
├── plan_auditor.py           # 主脚本（PreToolUse hook）
├── plan_auditor.config.json  # 审计端点/参数配置
├── setup_check.py            # 一次性部署验证（DEBUG=1 不自删，推送前改 0）
└── README.md                 # 本文档
.claude/logs/
├── plan_auditor.log          # 运行日志（敏感，勿入库）
└── plan_auditor_rounds.json  # 轮次计数（敏感，勿入库）