项目地址：https://github.com/18534516725/Agent-Doctor

使用 Codex、Claude Code 处理短任务时，问题通常比较直观：代码能不能运行、测试能不能通过，一眼就能判断。

但任务一旦变长，情况就不一样了。Agent 可能连续修改同一段代码，换几个方案后又回到原点；上下文越来越大，最初的目标和限制却越来越模糊；最危险的是，它刚写完代码就宣布任务完成，没有构建、测试或真实结果作为证据。

这些问题很难只靠聊天窗口发现。为此，我开源了一个本地 AI Coding Agent 可观测与指导工具：Agent Doctor。

Agent Doctor 解决什么问题？

Agent Doctor 不负责生成代码，也不是另一个用来监督当前模型的大模型。

Codex、Claude Code 等工具继续执行原任务，Agent Doctor 在本地收集客户端允许提供的运行证据，并判断任务是否出现以下情况：

• 重复相同失败，开始原地循环
• 上下文增长，但目标或关键约束逐渐丢失
• 没有验证证据，却准备结束任务
• Token 与费用增加，但缺少可解释的原因
• 从 Codex 切换到 Claude Code 后，项目状态无法连续传递

它的指导引擎采用确定性规则，本地运行，不会额外调用一个模型。这样可以避免为了“监督 Agent”再次引入模型费用、延迟和新的不确定性。

整体架构

Agent Doctor 的核心数据流可以简化为：

客户端公开接口
    ↓
Hook / MCP / Skill / 本地捕获代理
    ↓
数据脱敏与统一事件格式
    ↓
本地 SQLite + 证据指纹
    ↓
确定性诊断规则
    ↓
Task Guardian / 费用分析 / 项目记忆 / 下一步指导

这里有两个关键点。

第一，它只使用客户端公开或明确配置的接口，不读取客户端私有数据库，也不绕过客户端权限。

第二，没有数据就显示“不可用”，不会把缺失数据伪装成 0，更不会为了让报表完整而补一个看似合理的结果。

本地安装

建议先 Clone 仓库检查源码，再运行本地安装脚本：

git clone https://github.com/18534516725/Agent-Doctor.git
cd Agent-Doctor
./scripts/install-local.sh

这个脚本会安装依赖、构建并测试项目、安装命令行程序、配置由 Agent Doctor 管理的集成文件，然后启动本地服务与 Dashboard。

安装完成后，可以先检查环境：

agent-doctor doctor --json

启动本地看板：

agent-doctor start

如果只想打印本地地址，不自动打开浏览器：

agent-doctor start --no-open

捕获 Codex 或 Claude Code 任务

Agent Doctor 不会附加到已经运行的任意进程，也不会重写你的凭据。需要通过它提供的包装命令启动客户端：

agent-doctor run -- codex

或者：

agent-doctor run -- claude

这种方式只把本地捕获配置注入子进程，不需要修改整个终端环境。

任务运行后，可以直接查看当前诊断与成本状态：

agent-doctor diagnose --json
agent-doctor costs --json
agent-doctor dashboard --no-open

Dashboard 包含 Task Guardian、任务证据、费用、项目记忆、对比、趋势、客户端集成和隐私状态等页面。

如何识别“没有验证就完成”？

Agent Doctor 不是根据回复中有没有出现“完成”两个字做判断，而是检查当前客户端能够提供的证据。

例如，一个任务要求修复构建错误，但 Agent 只修改了文件，没有新的构建结果；或者任务要求补充测试，但没有对应测试执行记录。此时 Task Guardian 可以把任务标记为等待验证，并给出范围明确的下一步提示。

它提供四种控制级别：

模式	作用
observe	仅记录，不提供干预
guide	根据证据提供指导，默认模式
guard	在客户端支持时执行高置信规则
autopilot	启用当前客户端可支持的最强本地控制

需要注意：不同客户端的控制能力并不相同。

Claude Code 的官方 Hook 能在部分节点执行真正的拦截；Codex 当前主要通过 MCP 与 Skill 接收证据化建议，客户端仍然可以忽略这些文字。因此，“提供指导”和“确定性阻止”必须分开描述。

跨客户端项目记忆

很多项目不会从头到尾只使用一个 AI 编程工具。

当捕获过的 Codex 任务结束后，再在同一个仓库打开 Claude Code，Agent Doctor 可以提供一份有边界的交接信息，包括最近目标与结果、已经确认的项目事实、来源和明确限制。

它不会把完整聊天记录全部塞进新上下文。这样既能保留项目状态，也能减少无关历史不断占用上下文。

Token 与成本为什么分三种状态？

不同客户端和调用方式提供的计费证据并不一致。Agent Doctor 把成本分成三种口径：

• exact：来自兼容计费来源的实际费用
• estimated：本地 Token 使用量乘以版本化公开价格目录
• unavailable：缺少完成计算所需的证据

这些数据不会被合并成一个容易误解的总额。对于排查“任务为什么突然变贵”，这种区分比一个看似精确的数字更重要。

本地隐私边界

Agent Doctor 的 Dashboard 只绑定本机回环地址，SQLite 数据库保存在当前用户的配置目录中。

启用实时捕获时，完整的用户、助手、系统和工具消息会存储在本机，供用户检查真实任务过程；API Key、Authorization Header、Cookie 和传输请求头只在内存中转发，不写入 SQLite。

需要删除本地数据时，可以执行：

agent-doctor forget --yes --json

当前支持范围与限制

项目目前为 Codex、Claude Code、Cline、OpenCode、Cursor、Windsurf、Roo Code、Continue、Aider、Cherry Studio 和通用命令行工具声明了能力契约。

但“支持”不代表每个客户端都能暴露相同信号，也不代表所有客户端都能被强制拦截。当前公开版本仍处于 Beta，更适合愿意检查诊断结果、反馈真实边界的开发者使用。

项目采用 Apache-2.0 许可证。如果诊断、费用状态、客户端能力或跨端交接出现错误，欢迎通过 Issue 提供最小化复现；不要上传完整数据库、完整聊天记录、凭据、私有源码或请求头。

GitHub：https://github.com/18534516725/Agent-Doctor

如果你也遇到过 Agent 原地循环、上下文越跑越偏，或者没有验证就宣布完成，可以在评论区留下具体场景。真实项目中的失败样本，正是完善诊断规则最需要的数据。