AI Dev Harness

AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Codex、Claude Code、Cursor Agent、Gemini CLI 的研发任务变成可审计的执行闭环。

它的核心定位不是替代 Agent，也不是实现 MCP Client，而是：

让大模型知道如何组装上下文、制定计划、执行任务、验证结果，并把整个生命周期记录下来。

核心边界

• Codex / Claude / Cursor / Gemini 负责：理解任务、调用 MCP、调用工具、使用 Skill、修改代码。
• Harness 负责：执行闭环、过程日志、验证命令、审计证据、总结、沉淀建议。
• CodeGraph / Knowledge Graph 是 Agent 侧 MCP 工具源，不是 Harness 内部服务依赖。
• Harness 会记录 MCP source metadata，但不会记录 bearer token 原文。

包内容

• CLI：dist/cli.js
• Claude/Codex/Cursor/Gemini 对话集成安装器
• Claude Skill：.claude/skills/ai-dev-harness/
• Agent 辅助脚本：.harness/ai-dev-harness/scripts/
• Git-native 项目技能：skills/
• 可编辑模板：templates/

线上安装使用手册见 ONLINE_INSTALL_GUIDE.md。 同事试用手册见 COLLEAGUE_TRIAL_GUIDE.md。

快速开始

npm install
npm run build
node dist/cli.js init
node dist/cli.js doctor
node dist/cli.js smoke --agent codex --live

CLI 应在业务 Git 仓库内初始化。init 会创建 harness.yaml、skills/、AGENTS.md、TOOLS.md、SKILLS.md 和 runs/。

命令

node dist/cli.js init
node dist/cli.js init --no-integration
node dist/cli.js doctor
node dist/cli.js smoke --agent claude --live
node dist/cli.js run --task "add refund flow tests" --skill write_tests --agent claude
node dist/cli.js run --task "analyze download startup flow. Do not modify repository files." --skill update_docs --agent claude --live
node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent cursor --live
node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent gemini --live
node dist/cli.js verify --run <run_id_or_path>
node dist/cli.js summarize --run <run_id_or_path>
node dist/cli.js restore --run <run_id_or_path> --iteration 1
node dist/cli.js runs metrics --json
node dist/cli.js replay --run <run_id_or_path> --dry
node dist/cli.js replay --run <run_id_or_path> --agent codex
node dist/cli.js install-integration --agent all --target <repo>

Claude/Codex/Cursor/Gemini 对话触发

harness init 默认安装对话集成。也可以手动刷新：

node "E:\ai native\dist\cli.js" install-integration --agent all --target "C:\path\to\repo"

它会创建：

• .claude/skills/ai-dev-harness/SKILL.md
• AGENTS.md 中的 Harness 规则块
• .cursor/rules/ai-dev-harness.mdc
• GEMINI.md 中的 Harness 规则块
• .harness/ai-dev-harness/scripts/run-harness.ps1
• .harness/ai-dev-harness/scripts/read-evidence.ps1

然后在 Claude Code、Codex、Cursor 或 Gemini 中自然提问：

Use AI Dev Harness to run update_docs: analyze the download startup flow. Do not modify repository files.

或：

Use Harness to run fix_bug: fix the download resume progress issue.

集成脚本默认使用 --live，所以当前对话终端能看到 Harness 阶段日志和 Agent 输出。

MCP Preflight

Harness 不直接调用 MCP。Agent 应在触发 Harness 前使用自己已配置的 MCP 工具，并按以下格式汇报：

如果 CodeGraph 使用的是 colbymchenry/codegraph，默认优先调用 codegraph_explore。用任务里的业务流程、文件路径、函数/类/符号名或错误现象作为 query，并重点读取它返回的 grouped source、line-numbered source、call paths、dynamic dispatch hops 和 blast-radius summary。

如果 Knowledge Graph 使用的是 browser_knowledge_service，推荐读取顺序：

1. 用 list_path、search_docs、search_sections、search_chunks 缩小范围。
2. RAG 场景优先用 answer_context；需要自控排序时用 hybrid_search。
3. 定位 concept_id 后先用 read_doc_outline 看结构。
4. 再用 read_section、read_doc_range、read_chunk、get_related_chunks 精读证据。
5. 需要关系时用 get_backlinks，需要近期变更记录时用 get_audit_log。
6. v1 不直接调用 propose_doc 写入知识库；只生成 persist_suggestions.md。

## MCP Preflight Findings
- CodeGraph tools used:
- CodeGraph primary query:
- Source grouped by file:
- Current line-numbered source:
- Call paths:
- Dynamic dispatch hops:
- Blast-radius summary:
- Knowledge Graph tools used:
- Candidate concept_ids:
- Read tools used:
- Evidence sections/chunks:
- ADRs / decisions:
- Module notes:
- API notes / runbooks:
- Audit/backlink findings:
- Missing context:

关键 MCP 发现应被带入 Harness 的任务文本，进入审计证据。

OKF 知识沉淀

persist_suggestions.md 按 PC 浏览器团队知识库规范生成 OKF 候选内容，不自动写入 Knowledge Graph。

• 候选文档路径应落到 /<project>/overview/、/<project>/features/、/<project>/metrics/、/<project>/api/、/<project>/playbooks/ 或 /<project>/references/。
• 每个候选 concept 应包含 type、title、description、tags、timestamp；API/数据类建议补充 resource。
• ## 相关 必须使用有效 Markdown 链接，推荐 bundle 根相对路径。
• type: API Reference 需要包含 ## 关键实现锚点 和 ### Agent 使用建议。
• 合入知识库前应同步更新对应目录的 index.md 和 log.md，并人工检查敏感信息。

配置

编辑业务仓库里的 harness.yaml：

agents:
  codex:
    command: codex exec --full-auto -
  claude:
    command: claude -p -
  cursor:
    command: cursor-agent
  gemini:
    command: gemini
mcp:
  codegraph:
    type: sse
    url: http://localhost:7331/mcp
    headers: {}
  knowledgeGraph:
    type: http
    url: http://localhost:7332/mcp
    headers:
      Authorization: Bearer ${OKF_TOKEN}
  timeoutMs: 15000
verify:
  defaultCommands:
    - name: git status
      command: git status --short
audit:
  path: runs
loop:
  maxIterations: 1
  stopOn:
    - same_failure_repeated
    - max_iterations_reached
policy:
  protectedPaths:
    - .github/
    - scripts/release/
    - security/
  requireApproval:
    - protected_path_change
    - dependency_change
    - delete_files
    - public_api_change_declared
    - security_change_declared
  approvalMode: file

MCP header 支持环境变量，例如 ${OKF_TOKEN}。不要把真实 token 提交到 Git。

agents.*.command 都可以按团队机器上的实际 CLI 改写。Harness 统一通过 stdin 把最终 prompt 传给执行器，不绑定 Codex、Claude、Cursor 或 Gemini 的内部能力。

自纠偏循环

Harness 会在每轮执行后进入 Evaluate 阶段，判断是否完成目标、Agent 契约是否满足、验证是否通过。

默认 loop.maxIterations: 1，行为等同单轮执行。需要开启低风险自动重做时，在业务仓库 harness.yaml 中调大：

loop:
  maxIterations: 2
  stopOn:
    - same_failure_repeated
    - max_iterations_reached

会自动进入下一轮的典型情况：

• Agent 命令失败。
• Agent 输出缺少 Impact Analysis / Plan / Execution Notes / Verification Notes / Final Report。
• 验证命令失败。

会停止并要求人工评审的典型情况：

• 连续两轮出现同一种失败。
• 达到最大循环轮次。
• Agent 在报告里说明目标不明确、需要扩大范围、要改公共接口或安全策略。

运行证据

每次 run 会创建 runs/<run_id>/：

• intake.json：任务、skill、agent、Git 状态。
• mcp_queries.jsonl：Agent-driven MCP source metadata，不包含 token 原文。
• context_pack.md：上下文组装协议、MCP source 记录、本地兜底上下文。
• agent_prompt.md：发送给当前执行器的最终提示词。
• plan.md：Harness 执行阶段协议。
• execution.log：Agent stdout/stderr。
• agent_contract.json：Agent 必需章节检查结果。
• git_diff.patch：代码变更。
• verify.json：验证结果。
• verify_diagnostics.json：从验证 stdout/stderr 提取的通用失败诊断。
• context_score.json：Agent 是否按协议提供上下文证据的结构化评分。
• approval_required.json：机械审批门禁结果。
• feedback.jsonl：Harness 可见机器反馈事件，不记录 Agent 内部工具调用。
• checkpoint.json：本轮 Git checkpoint 和 restore 支持状态。
• pre_iteration_diff.patch / post_iteration_diff.patch：本轮前后 diff。
• loop_review.json：每轮评估、失败归因和下一步动作。
• loop_report.md：自纠偏循环的人类可读报告。
• summary.md：评审/PR 总结。
• persist_suggestions.md：知识沉淀建议。
• audit.jsonl：完整审计事件流。

Harness 会检查 Agent 输出是否包含以下章节：

• Impact Analysis
• Plan
• Execution Notes
• Verification Notes
• Final Report

检查结果写入 agent_contract.json，并记录到 audit.jsonl。

每轮循环会额外生成 iteration-<n>/ 子目录。根目录同名文件是最后一轮快照，方便旧脚本继续读取。

Checkpoint / Restore

Harness 每轮开始记录 checkpoint。只有运行开始前工作区是 clean，才允许自动 restore：

node dist/cli.js restore --run <run_id_or_path> --iteration 1

如果运行前已有未提交改动，Harness 会拒绝自动恢复，避免覆盖用户手工改动。

Approval Gate

Harness 只做机械门禁，不判断业务方案。默认会在以下情况写入 approval_required.json 并停止：

• 命中 policy.protectedPaths。
• 修改依赖文件，例如 package.json、lockfile。
• 删除文件。
• Agent 最终报告声明 public_api_change_declared 或 security_change_declared。

Metrics / Replay

读取本地 runs/ 证据生成运行指标：

node dist/cli.js runs metrics
node dist/cli.js runs metrics --json

Replay 复用历史 run 的 task 和 skill，创建新的 run，不覆盖旧证据：

node dist/cli.js replay --run <run_id_or_path> --dry
node dist/cli.js replay --run <run_id_or_path> --agent claude

Skill 规范

内置 skill 会通过 context.yaml 告诉 Agent：

• 应该从 CodeGraph MCP 查询什么。
• 应该从 Knowledge Graph MCP 查询什么。
• 什么情况下必须停止，不要猜。
• 本地兜底上下文应包含哪些路径。

示例：

mcp_preflight:
  codegraph:
    required: true
    primary_tool: codegraph_explore
    ask_for:
      - relevant_source_grouped_by_file
      - current_line_numbered_source_for_known_file_or_symbol
      - call_paths_between_related_symbols
      - dynamic_dispatch_hops
      - blast_radius_summary
  knowledgeGraph:
    required: true
    ask_for:
      - search_docs_or_search_chunks_for_defect_terms
      - answer_context_for_direct_rag_context
      - read_doc_outline_for_relevant_concepts
      - read_section_or_read_doc_range_for_evidence
      - get_backlinks_for_related_decisions
stop_conditions:
  - root cause is unclear
  - impact scope cannot be determined

验证

npm test
npm pack --dry-run