ai-dev-harness 0.1.0 → 0.1.1

package/COLLEAGUE_TRIAL_GUIDE.md

@@ -0,0 +1,147 @@
+# 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 conversation integration, and helper scripts.
+
+## 3. Configure MCP Sources
+
+Configure MCP in Claude/Codex so the agent 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"
+```
+
+Claude/Codex 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 run --task "Smoke test only. Analyze repository context and do not modify repository files." --skill update_docs --agent claude --live
+```
+
+With Codex:
+
+```bash
+harness run --task "Smoke test only. Analyze repository context and do not modify repository files." --skill update_docs --agent codex --live
+```
+
+`--live` streams Harness lifecycle logs and agent output in the current terminal.
+
+## 5. Use From Claude/Codex Conversation
+
+After `harness init`, open Claude Code or Codex 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:
+- Related files:
+- Related symbols:
+- Callers / dependencies:
+- Impact scope:
+- Knowledge Graph tools used:
+- ADRs / decisions:
+- Module notes:
+- API notes / runbooks:
+- 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 Claude/Codex
+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
+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 Claude/Codex cannot see MCP tools, check the Claude/Codex 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 integration.
+- Claude/Codex can trigger Harness from conversation.
+- Agent reports MCP preflight findings.
+- `agent_contract.json` shows whether required sections were produced.
+- `verify.json`, `summary.md`, and `audit.jsonl` are generated.

package/README.md

@@ -1,16 +1,30 @@
 # AI Dev Harness
 
-Auditable TypeScript CLI harness that wraps Codex CLI or Claude Code, retrieves context from CodeGraph and Knowledge Graph MCP services, verifies changes, and writes local run evidence.
+AI Dev Harness 是一个可分发的 TypeScript CLI，用来把 Claude Code / Codex 的研发任务变成可审计的执行闭环。
 
-This repository is a distributable Harness package:
+它的核心定位不是替代 Agent，也不是实现 MCP Client，而是：
 
-- CLI: `dist/cli.js`
-- Claude/Codex conversation integration installer
-- Claude Skill package installed into `.claude/skills/ai-dev-harness/`
-- Agent helper scripts installed into `.harness/ai-dev-harness/scripts/`
-- Git-native project skills installed into `skills/`
+> 让大模型知道如何组装上下文、制定计划、执行任务、验证结果，并把整个生命周期记录下来。
 
-## Quick Start
+## 核心边界
+
+- Claude / Codex 负责：理解任务、调用 MCP、调用工具、使用 Skill、修改代码。
+- Harness 负责：执行闭环、过程日志、验证命令、审计证据、总结、沉淀建议。
+- CodeGraph / Knowledge Graph 是 Agent 侧 MCP 工具源，不是 Harness 内部服务依赖。
+- Harness 会记录 MCP source metadata，但不会记录 bearer token 原文。
+
+## 包内容
+
+- CLI：`dist/cli.js`
+- Claude/Codex 对话集成安装器
+- Claude Skill：`.claude/skills/ai-dev-harness/`
+- Agent 辅助脚本：`.harness/ai-dev-harness/scripts/`
+- Git-native 项目技能：`skills/`
+- 可编辑模板：`templates/`
+
+同事试用手册见 `COLLEAGUE_TRIAL_GUIDE.md`。
+
+## 快速开始
 
 ```bash
 npm install
@@ -19,13 +33,13 @@ node dist/cli.js init
 node dist/cli.js run --task "fix a small bug" --skill fix_bug --agent codex
 ```
 
-The CLI is intended to be installed inside a business Git repository. `init` creates `harness.yaml`, `skills/`, `AGENTS.md`, `TOOLS.md`, `SKILLS.md`, and `runs/`.
-`harness run` must execute inside a Git repository; if it is launched elsewhere, the harness writes intake/audit evidence and exits nonzero.
+CLI 应在业务 Git 仓库内初始化。`init` 会创建 `harness.yaml`、`skills/`、`AGENTS.md`、`TOOLS.md`、`SKILLS.md` 和 `runs/`。
 
-## Commands
+## 命令
 
 ```bash
 node dist/cli.js init
+node dist/cli.js init --no-integration
 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 verify --run <run_id_or_path>
@@ -33,50 +47,58 @@ node dist/cli.js summarize --run <run_id_or_path>
 node dist/cli.js install-integration --agent both --target <repo>
 ```
 
-## Claude/Codex Conversation Trigger
+## Claude/Codex 对话触发
 
-Install conversation integration into a business repository:
+`harness init` 默认安装对话集成。也可以手动刷新：
 
 ```bash
 node "E:\ai native\dist\cli.js" install-integration --agent both --target "C:\path\to\repo"
 ```
 
-This creates:
+它会创建：
 
-- `.claude/skills/ai-dev-harness/SKILL.md` for Claude Code.
-- An `AGENTS.md` Harness section for Codex.
+- `.claude/skills/ai-dev-harness/SKILL.md`
+- `AGENTS.md` 中的 Harness 规则块
 - `.harness/ai-dev-harness/scripts/run-harness.ps1`
 - `.harness/ai-dev-harness/scripts/read-evidence.ps1`
 
-Then, inside Claude Code or Codex, ask naturally:
+然后在 Claude Code 或 Codex 中自然提问：
 
 ```text
 Use AI Dev Harness to run update_docs: analyze the download startup flow. Do not modify repository files.
 ```
 
-or:
+或：
 
 ```text
 Use Harness to run fix_bug: fix the download resume progress issue.
 ```
 
-The generated integration uses `--live`, so the current conversation terminal can see Harness stages and agent output as the run progresses.
+集成脚本默认使用 `--live`，所以当前对话终端能看到 Harness 阶段日志和 Agent 输出。
 
-The installed Skill prefers the helper script:
+## MCP Preflight
 
-```bash
-powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill fix_bug -Agent claude -Live
-```
-
-The direct CLI command remains available as a fallback:
+Harness 不直接调用 MCP。Agent 应在触发 Harness 前使用自己已配置的 MCP 工具，并按以下格式汇报：
 
-```bash
-node "E:\ai native\dist\cli.js" run --task "<task>" --skill fix_bug --agent claude --live
+```text
+## MCP Preflight Findings
+- CodeGraph tools used:
+- Related files:
+- Related symbols:
+- Callers / dependencies:
+- Impact scope:
+- Knowledge Graph tools used:
+- ADRs / decisions:
+- Module notes:
+- API notes / runbooks:
+- Missing context:
 ```
 
-## Configuration
+关键 MCP 发现应被带入 Harness 的任务文本，进入审计证据。
+
+## 配置
 
-Edit `harness.yaml` in the business repository:
+编辑业务仓库里的 `harness.yaml`：
 
 ```yaml
 agents:
@@ -86,9 +108,14 @@ agents:
     command: claude -p -
 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:
@@ -98,34 +125,71 @@ audit:
   path: runs
 ```
 
-The agent command receives the generated prompt on stdin. CodeGraph and Knowledge Graph MCP are queried first; if either service is unavailable, the run is marked degraded and the harness falls back to local Git/file context.
-If the agent command or verification fails, the run still writes all evidence files and then exits nonzero so CI can treat the run as failed.
+MCP header 支持环境变量，例如 `${OKF_TOKEN}`。不要把真实 token 提交到 Git。
 
-## Run Evidence
+## 运行证据
 
-Each `run` creates `runs/<run_id>/` with:
+每次 `run` 会创建 `runs/<run_id>/`：
 
-- `intake.json`
-- `mcp_queries.jsonl`
-- `context_pack.md`
-- `agent_prompt.md`
-- `plan.md`
-- `execution.log`
-- `git_diff.patch`
-- `verify.json`
-- `summary.md`
-- `persist_suggestions.md`
-- `audit.jsonl`
+- `intake.json`：任务、skill、agent、Git 状态。
+- `mcp_queries.jsonl`：Agent-driven MCP source metadata，不包含 token 原文。
+- `context_pack.md`：上下文组装协议、MCP source 记录、本地兜底上下文。
+- `agent_prompt.md`：发送给 Claude/Codex 的最终提示词。
+- `plan.md`：Harness 执行阶段协议。
+- `execution.log`：Agent stdout/stderr。
+- `agent_contract.json`：Agent 必需章节检查结果。
+- `git_diff.patch`：代码变更。
+- `verify.json`：验证结果。
+- `summary.md`：评审/PR 总结。
+- `persist_suggestions.md`：知识沉淀建议。
+- `audit.jsonl`：完整审计事件流。
 
-Knowledge Graph updates are not applied automatically in v1. Review `persist_suggestions.md` before writing them back.
+Harness 会检查 Agent 输出是否包含以下章节：
 
-## Engineering Prompt Contracts
+- `Impact Analysis`
+- `Plan`
+- `Execution Notes`
+- `Verification Notes`
+- `Final Report`
 
-Generated skills and agent prompts use a company-grade execution contract:
+检查结果写入 `agent_contract.json`，并记录到 `audit.jsonl`。
 
-- Analysis Contract: restate the task, list assumptions, affected areas, risks, and missing context.
-- Execution Contract: make only task-relevant minimal changes; no opportunistic refactors or broad cleanup.
-- Verification Contract: run configured verification or record why checks could not run.
-- Report Contract: summarize intent or root cause, changed files, verification, residual risk, and knowledge suggestions.
+## Skill 规范
 
-The test suite verifies that initialized skills and run evidence include these contracts.
+内置 skill 会通过 `context.yaml` 告诉 Agent：
+
+- 应该从 CodeGraph MCP 查询什么。
+- 应该从 Knowledge Graph MCP 查询什么。
+- 什么情况下必须停止，不要猜。
+- 本地兜底上下文应包含哪些路径。
+
+示例：
+
+```yaml
+mcp_preflight:
+  codegraph:
+    required: true
+    ask_for:
+      - related_files
+      - related_symbols
+      - callers
+      - dependencies
+      - impact_scope
+  knowledgeGraph:
+    required: true
+    ask_for:
+      - adr
+      - module_notes
+      - api_notes
+      - runbooks
+stop_conditions:
+  - root cause is unclear
+  - impact scope cannot be determined
+```
+
+## 验证
+
+```bash
+npm test
+npm pack --dry-run
+```

package/dist/agent.js

@@ -1,54 +1,67 @@
 import { appendFile, readFile, writeFile } from "node:fs/promises";
 import { git, runCommand, truncate } from "./utils.js";
 function renderPrompt(input, contextPack) {
-    return `You are running inside an auditable AI development harness. Treat this as a company engineering task, not a casual chat.
+    return `你正在一个可审计的 AI 研发 Harness 中执行任务。请把它当作公司级研发任务，而不是随意聊天。
 
-Task:
+任务:
 ${input.task}
 
 Skill:
 ${input.skill.name}
 
-Execution Contract:
-1. Analysis first.
-   - Restate the task in one or two sentences.
-   - Identify assumptions, affected files/modules, relevant CodeGraph context, relevant Knowledge Graph context, and risks.
-   - If required context is missing or confidence is low, stop and report what is missing instead of guessing.
-2. Plan before editing.
-   - Provide a minimal step-by-step plan.
-   - Keep the plan limited to the requested task.
-3. Safe execution.
-   - Make the smallest task-relevant change.
-   - Do not perform opportunistic refactors, formatting-only sweeps, dependency upgrades, broad renames, or unrelated cleanup.
-   - Preserve public interfaces and backward compatibility unless explicitly instructed otherwise.
-   - Do not update Knowledge Graph directly.
-4. Verification discipline.
-   - Harness will run configured verification after you finish.
-   - Only run extra commands when needed to understand or validate the task.
-   - Report any verification you could not run and why.
-5. Required final report.
-   - Root cause or implementation intent.
-   - Files changed.
-   - Verification performed or deferred.
-   - Residual risk.
-   - Knowledge persistence suggestions.
+执行契约:
+1. 先分析。
+   - 用一两句话复述任务。
+   - 识别假设、受影响文件/模块、CodeGraph 上下文、Knowledge Graph 上下文和风险。
+   - 如果关键上下文缺失或信心不足，停止并说明缺什么，不要猜。
+2. 先计划再修改。
+   - 给出最小步骤计划。
+   - 计划必须限定在当前任务范围内。
+3. 安全执行。
+   - 只做和任务相关的最小变更。
+   - 不做机会主义重构、纯格式化清扫、依赖升级、大范围重命名或无关清理。
+   - 除非任务明确要求，否则保持公共接口和向后兼容。
+   - 不直接写入 Knowledge Graph。
+4. 验证纪律。
+   - Harness 会在你完成后运行配置的验证命令。
+   - 只有在理解或验证任务确实需要时才额外运行命令。
+   - 说明无法执行的验证及原因。
+5. 必须输出最终报告。
+   - 根因或实现意图。
+   - 修改文件。
+   - 已执行或延后的验证。
+   - 残余风险。
+   - 知识沉淀建议。
 
-Output Format:
+必须使用以下输出格式，标题不要改名:
 ## Impact Analysis
 ## Plan
 ## Execution Notes
 ## Verification Notes
 ## Final Report
 
-Project Rules:
-- Respect AGENTS.md, TOOLS.md, and SKILLS.md when present.
-- Work inside this repository only.
-- Leave an auditable, reviewable result.
+项目规则:
+- 遵守 AGENTS.md、TOOLS.md 和 SKILLS.md。
+- 只在当前仓库内工作。
+- 留下可审计、可复查的结果。
 
-Context pack:
+Context Pack:
 ${contextPack}
 `;
 }
+export function checkAgentContract(output) {
+    const required = ["Impact Analysis", "Plan", "Execution Notes", "Verification Notes", "Final Report"];
+    const requiredSections = required.map((name) => ({
+        name,
+        present: new RegExp(`^##\\s+${name}\\s*$`, "im").test(output)
+    }));
+    const missingSections = requiredSections.filter((section) => !section.present).map((section) => section.name);
+    return {
+        status: missingSections.length ? "failed" : "passed",
+        requiredSections,
+        missingSections
+    };
+}
 async function executeAgent(input) {
     const contextPack = await readFile(input.contextPackPath, "utf8");
     const prompt = renderPrompt(input, contextPack);