ai-dev-harness 0.1.0 → 0.1.2

package/COLLEAGUE_TRIAL_GUIDE.md

@@ -0,0 +1,175 @@
+# AI Dev Harness Colleague Trial Guide
+
+## 1. Install
+
+```bash
+npm install -g ai-dev-harness
+```
+
+Check:
+
+```bash
+harness --help
+```
+
+## 2. Initialize In A Business Repository
+
+Run inside a Git repository:
+
+```bash
+harness init
+```
+
+This creates Harness config, project skills, Claude/Codex/Cursor/Gemini conversation integration, and helper scripts.
+
+Check local pilot readiness:
+
+```bash
+harness doctor
+```
+
+## 3. Configure MCP Sources
+
+Configure MCP in the execution agent so it can call the tools directly. Keep the same source metadata in `harness.yaml` for audit:
+
+```yaml
+mcp:
+  codegraph:
+    type: sse
+    url: http://10.41.83.107:7878/mcp
+    headers: {}
+  knowledgeGraph:
+    type: http
+    url: http://10.41.83.107:9200/mcp
+    headers:
+      Authorization: Bearer ${OKF_TOKEN}
+  timeoutMs: 15000
+```
+
+Set secrets outside Git:
+
+```powershell
+$env:OKF_TOKEN="your-token"
+```
+
+The execution agent should call MCP tools before triggering Harness and include important findings in the task text. Harness records MCP source configuration for audit, but does not implement MCP transport itself.
+
+## 4. Run A Smoke Test
+
+```bash
+harness smoke --agent claude --live
+```
+
+With Codex:
+
+```bash
+harness smoke --agent codex --live
+```
+
+Cursor / Gemini:
+
+```powershell
+harness smoke --agent cursor --live
+harness smoke --agent gemini --live
+```
+
+`--live` streams Harness lifecycle logs and agent output in the current terminal.
+
+## 5. Use From Claude/Codex/Cursor/Gemini Conversation
+
+After `harness init`, open Claude Code, Codex, Cursor, or Gemini in the repository and say:
+
+```text
+Use AI Dev Harness to run fix_bug: fix the download resume progress issue.
+```
+
+The agent should:
+
+1. Use configured MCP tools first.
+2. Report MCP preflight findings in the current conversation.
+3. Trigger Harness through `.harness/ai-dev-harness/scripts/run-harness.ps1`.
+4. Stream Harness lifecycle logs.
+5. Read and summarize the evidence directory.
+
+## 6. Expected MCP Preflight Shape
+
+```text
+## 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:
+```
+
+## 7. Evidence Files
+
+Each run writes `runs/<run_id>/`:
+
+```text
+intake.json            Task, skill, agent, Git state
+mcp_queries.jsonl      Agent-driven MCP source records
+context_pack.md        Context assembly protocol and local fallback context
+agent_prompt.md        Final prompt sent to the execution agent
+plan.md                Harness execution-stage protocol
+execution.log          Agent stdout/stderr
+agent_contract.json    Required-section contract check
+git_diff.patch         Code changes
+verify.json            Verification results
+verify_diagnostics.json Verification failure diagnostics
+context_score.json     Context evidence score
+approval_required.json Approval gate result
+feedback.jsonl         Harness-visible machine feedback events
+checkpoint.json        Git checkpoint and restore support
+pre_iteration_diff.patch Diff before the iteration
+post_iteration_diff.patch Diff after the iteration
+loop_review.json       Per-iteration evaluation and failure diagnosis
+loop_report.md         Human-readable correction-loop report
+summary.md             Review/PR summary
+persist_suggestions.md Knowledge persistence suggestions
+audit.jsonl            Full audit event log
+```
+
+Read evidence:
+
+```bash
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/read-evidence.ps1" -Run <run_id>
+```
+
+## 8. Troubleshooting
+
+If `harness` is not found, check npm global bin is in `PATH`.
+
+If `harness run must execute inside a Git repository`, run inside a business Git repository and confirm:
+
+```bash
+git status
+```
+
+If the current Agent cannot see MCP tools, check that Agent's MCP configuration first:
+
+- Wrong MCP URL
+- Missing bearer token
+- Service down
+- Endpoint path is not `/mcp`
+
+Harness can still run with local repository fallback context, but the agent should report missing MCP context.
+
+## 9. Acceptance Checklist
+
+- `harness init` creates config, skills, and Claude/Codex/Cursor/Gemini integration.
+- Claude/Codex/Cursor/Gemini can trigger Harness from conversation.
+- Agent reports MCP preflight findings.
+- `agent_contract.json` shows whether required sections were produced.
+- `verify.json`, `loop_review.json`, `summary.md`, and `audit.jsonl` are generated.

package/ONLINE_INSTALL_GUIDE.md

@@ -0,0 +1,458 @@
+# AI Dev Harness 线上安装使用手册
+
+## 1. 适用对象
+
+本手册面向需要在业务 Git 仓库中使用 AI Dev Harness 的研发同学。
+
+AI Dev Harness 的定位是：
+
+```text
+Codex / Claude / Cursor / Gemini 负责理解任务、调用 MCP、使用 Skill、修改代码。
+Harness 负责执行闭环、日志、验证、审计、总结和知识沉淀建议。
+```
+
+Harness 不是 MCP Client。CodeGraph / Knowledge Graph MCP 由当前执行器自己调用。
+
+## 2. 环境要求
+
+- Node.js >= 20
+- npm
+- Git
+- Claude Code、Codex CLI、Cursor Agent、Gemini CLI 至少安装一个
+- 业务仓库已经是 Git 仓库
+
+检查命令：
+
+```powershell
+node -v
+npm -v
+git status
+claude --version
+codex --version
+cursor-agent --version
+gemini --version
+```
+
+`claude`、`codex`、`cursor-agent`、`gemini` 任一执行器可用即可；具体命令可在 `harness.yaml` 覆盖。
+
+## 3. 线上安装
+
+全局安装：
+
+```powershell
+npm install -g ai-dev-harness
+```
+
+检查是否安装成功：
+
+```powershell
+harness --help
+```
+
+正确入口是：
+
+```powershell
+harness
+```
+
+不要在业务仓库中执行：
+
+```powershell
+node dist/cli.js init
+```
+
+`node dist/cli.js` 只适用于 AI Dev Harness 源码仓，不适用于普通业务仓。
+
+## 4. 在业务仓库初始化
+
+进入业务仓库：
+
+```powershell
+cd C:\yuntun_app\360download_mobile
+git status
+```
+
+初始化 Harness：
+
+```powershell
+harness init
+```
+
+检查本地试点环境：
+```powershell
+harness doctor
+```
+
+`doctor` 只检查 Git、配置、Skill、Agent 命令、MCP source metadata 和验证命令强度，不会连接 MCP，也不会调用 Agent。
+
+初始化后会生成：
+
+```text
+harness.yaml
+AGENTS.md
+TOOLS.md
+SKILLS.md
+skills/
+.claude/skills/ai-dev-harness/SKILL.md
+.cursor/rules/ai-dev-harness.mdc
+GEMINI.md
+.harness/ai-dev-harness/scripts/run-harness.ps1
+.harness/ai-dev-harness/scripts/read-evidence.ps1
+runs/
+```
+
+`harness init` 默认会安装 Claude/Codex/Cursor/Gemini 对话集成。
+
+如果只想初始化 CLI 配置，不安装对话集成：
+
+```powershell
+harness init --no-integration
+```
+
+## 5. 配置 MCP
+
+Claude/Codex 的 MCP 配置示例：
+
+```json
+{
+  "mcpServers": {
+    "okf-360": {
+      "url": "http://10.41.83.107:9200/mcp",
+      "headers": {
+        "Authorization": "Bearer ${OKF_TOKEN}"
+      }
+    },
+    "code-graph": {
+      "type": "sse",
+      "url": "http://10.41.83.107:7878/mcp"
+    }
+  }
+}
+```
+
+业务仓库中的 `harness.yaml` 也保留 MCP source metadata，用于审计记录：
+
+```yaml
+mcp:
+  codegraph:
+    type: sse
+    url: http://10.41.83.107:7878/mcp
+    headers: {}
+  knowledgeGraph:
+    type: http
+    url: http://10.41.83.107:9200/mcp
+    headers:
+      Authorization: Bearer ${OKF_TOKEN}
+  timeoutMs: 15000
+```
+
+设置 token：
+
+```powershell
+$env:OKF_TOKEN="your-token"
+```
+
+长期生效可以使用：
+
+```powershell
+setx OKF_TOKEN "your-token"
+```
+
+注意：不要把真实 token 提交到 Git。
+
+## 6. 命令行使用
+
+推荐先跑只读冒烟：
+
+```powershell
+harness smoke --agent claude --live
+```
+
+这等价于执行一个 `update_docs` 只读任务，用来确认本地闭环、日志和证据目录都正常。
+
+只读分析：
+
+```powershell
+harness run --task "分析下载模块启动流程。Do not modify repository files." --skill update_docs --agent claude --live
+```
+
+修 bug：
+
+```powershell
+harness run --task "修复下载续传进度异常问题" --skill fix_bug --agent claude --live
+```
+
+写测试：
+
+```powershell
+harness run --task "为下载任务状态流转补充测试" --skill write_tests --agent claude --live
+```
+
+使用 Codex：
+
+```powershell
+harness run --task "分析下载模块启动流程。Do not modify repository files." --skill update_docs --agent codex --live
+```
+
+Cursor / Gemini：
+
+```powershell
+harness run --task "修复下载续传进度异常问题" --skill fix_bug --agent cursor --live
+harness run --task "修复下载续传进度异常问题" --skill fix_bug --agent gemini --live
+```
+
+## 7. 在 Claude/Codex/Cursor/Gemini 对话中使用
+
+初始化后，可以直接在 Claude Code、Codex、Cursor 或 Gemini 对话中说：
+
+```text
+Use AI Dev Harness to run update_docs: 分析下载模块启动流程。Do not modify repository files.
+```
+
+或者：
+
+```text
+Use AI Dev Harness to run fix_bug: 修复下载续传进度异常问题。
+```
+
+Agent 应该执行以下流程：
+
+1. 先调用 CodeGraph MCP / Knowledge Graph MCP。
+2. 在当前对话中输出 MCP Preflight Findings。
+3. 调用 Harness CLI。
+4. 实时展示 Harness 生命周期日志。
+5. 读取并总结 `runs/<run_id>/` 证据目录。
+
+## 8. MCP Preflight 输出格式
+
+Agent 在触发 Harness 前，应按以下格式汇报：
+
+如果 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`。
+
+```text
+## 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:
+```
+
+这些发现应写入 Harness 的 task 文本，进入审计证据。
+
+## 9. OKF 知识沉淀建议
+
+`persist_suggestions.md` 只生成可评审的 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`。
+- 不要写入密钥、Token、明文密码、未脱敏用户数据、未公开内网 IP。
+
+## 10. 运行证据目录
+
+每次运行会生成：
+
+```text
+runs/<run_id>/
+```
+
+核心文件：
+
+```text
+intake.json            任务、Skill、Agent、Git 状态
+mcp_queries.jsonl      Agent-driven MCP source metadata
+context_pack.md        上下文组装协议和本地兜底上下文
+agent_prompt.md        发给当前执行器的最终提示词
+plan.md                Harness 执行阶段协议
+execution.log          Agent stdout/stderr
+agent_contract.json    Agent 输出契约检查
+git_diff.patch         代码变更
+verify.json            验证结果
+verify_diagnostics.json 验证失败诊断
+context_score.json     上下文证据评分
+approval_required.json 审批门禁结果
+feedback.jsonl         Harness 可见机器反馈事件
+checkpoint.json        Git checkpoint 和 restore 支持状态
+pre_iteration_diff.patch 本轮前 diff
+post_iteration_diff.patch 本轮后 diff
+loop_review.json       每轮评估、失败归因和下一步动作
+loop_report.md         自纠偏循环报告
+summary.md             评审/PR 总结
+persist_suggestions.md 知识沉淀建议
+audit.jsonl            完整审计事件流
+```
+
+读取证据：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/read-evidence.ps1" -Run <run_id>
+```
+
+## 11. 自纠偏循环
+
+默认只跑 1 轮，行为等同普通执行。需要允许 Harness 在低风险失败后自动 rework，可在 `harness.yaml` 中配置：
+
+```yaml
+loop:
+  maxIterations: 2
+  stopOn:
+    - same_failure_repeated
+    - max_iterations_reached
+```
+
+自动 rework 的典型触发条件：
+
+- Agent 命令失败。
+- Agent 输出不符合固定报告契约。
+- 验证命令失败。
+
+停止并人工评审的典型条件：
+
+- 连续两轮同类失败。
+- 达到最大轮次。
+- 需要扩大范围、修改公共接口、安全策略，或目标本身不明确。
+
+## 12. 重新验证和总结
+
+重新运行验证：
+
+```powershell
+harness verify --run <run_id>
+```
+
+重新生成总结：
+
+```powershell
+harness summarize --run <run_id>
+```
+
+恢复 clean baseline 下的某轮修改：
+
+```powershell
+harness restore --run <run_id> --iteration 1
+```
+
+查看本地 runs 指标：
+
+```powershell
+harness runs metrics
+harness runs metrics --json
+```
+
+回放历史任务：
+
+```powershell
+harness replay --run <run_id> --dry
+harness replay --run <run_id> --agent claude
+```
+
+## 13. 常见问题
+
+### 1. `Cannot find module '...\dist\cli.js'`
+
+原因：在业务仓库里执行了错误命令：
+
+```powershell
+node dist/cli.js init
+```
+
+解决：
+
+```powershell
+harness init
+```
+
+### 2. `harness` 命令不存在
+
+重新安装：
+
+```powershell
+npm install -g ai-dev-harness
+```
+
+检查 npm 全局 bin 是否在 `PATH`。
+
+### 3. `harness run 必须在 Git 仓库内执行`
+
+进入业务 Git 仓库后再执行：
+
+```powershell
+git status
+harness run --task "..." --skill update_docs --agent claude --live
+```
+
+### 4. Claude/Codex 看不到 MCP 工具
+
+优先检查 Claude/Codex 的 MCP 配置，而不是 Harness：
+
+- MCP URL 是否正确
+- token 是否有效
+- 服务是否可访问
+- CodeGraph 是否配置为 `type: sse`
+- Knowledge Graph 是否带 Authorization header
+
+### 5. Agent 输出不符合要求
+
+查看：
+
+```text
+runs/<run_id>/agent_contract.json
+```
+
+Harness 会检查 Agent 是否输出：
+
+- `Impact Analysis`
+- `Plan`
+- `Execution Notes`
+- `Verification Notes`
+- `Final Report`
+
+## 14. 推荐团队使用方式
+
+第一次接入：
+
+```powershell
+npm install -g ai-dev-harness
+cd <business-repo>
+harness init
+harness doctor
+harness smoke --agent claude --live
+```
+
+日常使用：
+
+```text
+在 Claude/Codex 对话中说：
+Use AI Dev Harness to run <skill>: <task>
+```
+
+推荐从只读任务开始：
+
+```text
+Use AI Dev Harness to run update_docs: 分析下载模块启动流程。Do not modify repository files.
+```
+
+确认流程稳定后，再用于 `fix_bug`、`write_tests`、`add_feature`。