harness-engineering-agent 0.1.0 → 0.1.2

package/README.md

@@ -1,21 +1,196 @@
+
+
 # Harness Engineering Agent
 
-面向复杂项目工程的 OpenCode 自动开发插件。
+面向复杂项目工程的 OpenCode 自动开发插件，也是 OpenCode 之上的**确定性控制平面**。
 
-该插件采用全局安装、按项目配置的运行方式，通过专用 primary `harness` Agent 与内部 Harness agent set 协调完成需求拆解、实现、确定性校验、有限重试和最终报告，不依赖 Sisyphus、OMO 或 OpenSpec 运行时。
+插件通过一个专用 primary `harness` Agent 和七个内部 Harness Agent 协调完成需求塑形、规划编排、代码实现、独立验证、最终验收、失败归因与修复规划。插件全局安装，按项目配置运行，不依赖 Sisyphus、OMO 或 OpenSpec 运行时。
 
-## 当前能力
+Harness 是确定性的控制平面，内部 Agent 是受约束的概率执行器。只有 Controller 才能推进全局状态，Agent 输出只是结构化建议，不能绕过 Guard Condition。
+
+## 核心能力
 
 - 选择 `harness` Agent 后，使用自然语言发起 `start`、`status`、`resume`、`pause`、`cancel`、`answer`、`waive`、`report` 生命周期操作。
-- 插件只在当前消息的 `agent === "harness"` 时触发 Harness 协调；普通 Agent 和普通聊天不会自动拦截。
+- 插件只在当前消息的 `agent === "harness"` 时触发 Harness 协调。普通 Agent 和普通聊天不会自动拦截。
 - 自然语言请求先进入内部 Intake Session，转换为严格 JSON intent，再由确定性的 RunController 执行对应操作。
 - `chat.message` 采用两阶段非阻塞流程：前台先返回 synthetic 受理确认，协调工作在后台运行；后台完成后再向同一父会话补发 Harness 内部完成消息，供 `harness` Agent 做最终总结。
-- 所有内部 Session 都显式绑定到 Harness 自有 agent，并同时保留稳定旧 ID 与英文显示名映射。
-- 当前激活链为 `Nuwa -> Fuxi -> Luban -> deterministic verification -> Zhulong -> Yinglong`；失败时经 `Xingtian` 归因，允许自动修复时由 `Jingwei` 生成 Repair Task，再交回 `Luban` 在受限范围内执行。
-- `resume` 会从 `.harness/runs/<run-id>/` 的快照与事件恢复上下文，不会重复已完成 Task 或丢失既有 evidence。
+- 所有内部 Session 显式绑定到 Harness 自有 agent，并同时保留稳定兼容 ID 与英文显示名映射。
 - Git 基线、脏工作区、外部修改、scope drift、merge conflict 与 verification evidence gap 全部由 Controller 的确定性状态机保护，不能被 Agent 自报绕过。
-- 并行仅在依赖、路径范围和验证资源都无冲突时启用，且必须在独立 git worktree 中执行；冲突或集成失败时保留诊断 worktree refs，并让主仓库 `merge --abort` 回到无 unmerged 状态。
-- 验证命令通过结构化 argv、`shell: false`、工作区包含校验、嵌套解释器/包管理器绕过检查和审批元数据约束执行，不接受 Agent 自报“已通过”替代命令证据。
+- 验证命令通过结构化 argv、`shell: false`、工作区包含校验、嵌套解释器/包管理器绕过检查和审批元数据约束执行，不接受 Agent 自报"已通过"替代命令证据。
+- `resume` 会从 `.harness/runs/<run-id>/` 的快照与事件恢复上下文，不会重复已完成 Task 或丢失既有 evidence。
+
+## 正常主链
+
+需求从自然语言开始，经过结构化、规划、执行、验证、验收，最终生成报告：
+
+```
+用户自然语言
+    |
+    v
+  Harness (primary)
+    |
+    v
+  Nuwa (Intake) ── 结构化 HarnessIntent；start 携带 Requirement
+    |
+    v
+  Fuxi (Planner) ── TaskGraph JSON
+    |
+    v
+  Luban (Worker) ── 在 allowedPaths 内实现任务
+    |
+    v
+  确定性验证 (Controller 执行命令)
+    |
+    v
+  Zhulong (Verifier) ── 依据 evidence 判定
+    |
+    v
+  Yinglong (Acceptance) ── 检查 requirement/task/evidence 闭环
+    |
+    v
+  最终报告 (final-report.md)
+```
+
+## 失败修复链
+
+当验证或验收失败时，进入归因与修复闭环：
+
+```
+失败证据
+    |
+    v
+  Xingtian (Failure Analyzer) ── 分类根因，给出恢复建议
+    |
+    v (需要修复时)
+  Jingwei (Repair Worker) ── 生成受限 Repair Task，不直接改代码
+    |
+    v
+  Luban (Worker) ── 在受限范围内执行修复
+    |
+    v
+  重新验证 ──> Zhulong ──> Yinglong ──> 报告或再次归因
+```
+
+每个 Task 拥有有限 retry budget。预算耗尽后进入 `PAUSED` 或 `FAILED`，不会无限循环。
+
+## Agent 总览表
+
+| 英文名 | 中文名 | 稳定 ID | Session role | 写权限 | 主要产物 |
+|---|---|---|---|---|---|
+| Harness | 工程总控 | `harness` | primary | 无（只读呈现） | 用户交互摘要、运行状态展示 |
+| Nuwa | 女娲，需求塑形智能体 | `harness-intake` | `intake` | 只读 | HarnessIntent JSON；start Requirement |
+| Fuxi | 伏羲，规划编排智能体 | `harness-planner` | `planner` | 只读 | TaskGraph JSON |
+| Luban | 鲁班，实现执行智能体 | `harness-worker` | `worker` | edit/write/patch/bash | WorkerOutput JSON、代码变更 |
+| Zhulong | 烛龙，独立验证智能体 | `harness-verifier` | `verifier` | 只读 | VerifierOutput JSON |
+| Yinglong | 应龙，最终验收智能体 | `harness-acceptance` | `acceptance` | 只读 | AcceptanceOutput JSON |
+| Xingtian | 刑天，失败归因智能体 | `harness-failure-analyzer` | `failure-analyzer` | 只读 | FailureAnalyzerOutput JSON |
+| Jingwei | 精卫，修复规划智能体 | `harness-repair-worker` | `repair-worker` | 只读 | RepairTask（结构化修复建议） |
+
+只有 `Luban` 可以 edit/write/patch/bash。其他内部 Agent 全部只读。`Jingwei` 只生成 Repair Task，不直接修改代码。
+
+## Agent 详细说明
+
+### Harness（工程总控）
+
+- **稳定 ID**：`harness`
+- **Session role**：primary
+- **定位**：用户与 Harness 控制平面之间的唯一交互界面。
+- **主要职责**：接收自然语言生命周期请求，将后台协调结果整理为用户可读的总结。
+- **输入**：用户在 OpenCode 中发送的自然语言请求；内部完成消息（带 `<!-- HARNESS_INTERNAL_RESULT -->` 标记的 synthetic result 是唯一权威完成结果）。
+- **输出**：面向用户的运行状态、阻塞原因和下一步操作说明。
+- **权限边界**：`task/edit/write/patch/bash` 全部禁用，不使用任何研究工具。不直接编辑文件、执行 shell、委派子 Agent 或声明未完成的任务已完成。
+- **上下游关系**：接收用户请求后交给 Controller；Controller 完成后再将结果返回给 Harness 做最终总结。
+
+### Nuwa（女娲，需求塑形智能体）
+
+- **稳定 ID**：`harness-intake`
+- **Session role**：`intake`
+- **定位**：将自然语言请求整理为结构化生命周期意图。
+- **主要职责**：识别 `start/status/pause/answer/resume/cancel/waive/report/clarification`；对于 `start`，提炼 title、summary、acceptanceCriteria 形成 Requirement 输入。发现阻塞性歧义时返回 clarification，不会猜测。
+- **输入**：用户自然语言请求（通过 Controller 转发）。
+- **输出**：HarnessIntent JSON；`start` intent 内包含结构化 Requirement 字段。
+- **权限边界**：只读。`task/edit/write/patch/bash` 全部禁用，不调用任何工具。
+- **上下游关系**：上游是 Harness primary；生命周期意图交给 Controller 执行，其中 `start` 的 Requirement 再传给 Fuxi 规划。
+
+### Fuxi（伏羲，规划编排智能体）
+
+- **稳定 ID**：`harness-planner`
+- **Session role**：`planner`
+- **定位**：根据 Requirement 生成可执行、可验证的 TaskGraph。
+- **主要职责**：将 Requirement 拆解为有向无环 Task Graph，每个 Task 包含依赖、allowedPaths、verificationPlan、retryBudget 和 evidenceRefs。
+- **输入**：Requirement JSON + runId。
+- **输出**：TaskGraph JSON。
+- **权限边界**：只读。可使用全部研究工具（Context7、grep.app、LSP），但不编辑文件、不执行 shell、不委派子 Agent。
+- **上下游关系**：上游是 Nuwa，下游是 Luban。Controller 在接受 TaskGraph 前执行结构校验（ID 唯一、依赖存在、图无环、文件范围不冲突）。
+
+### Luban（鲁班，实现执行智能体）
+
+- **稳定 ID**：`harness-worker`
+- **Session role**：`worker`
+- **定位**：唯一被允许修改代码的 Harness Agent。
+- **主要职责**：在 Task 指定的 `allowedPaths` 范围内实现代码变更，输出结构化 WorkerOutput。
+- **输入**：Task JSON + Requirement JSON + allowedPaths。
+- **输出**：WorkerOutput JSON（包含 summary、changedPaths、verificationCommands、evidence）。
+- **权限边界**：`edit/write/patch/bash` 全部允许，`permission.edit=allow`，`permission.bash=allow`。可使用全部研究工具。必须严格遵守 allowedPaths，不得请求父会话完整历史。
+- **上下游关系**：上游是 Fuxi（通过 Controller 分发 Task），下游是确定性验证和 Zhulong。修复链中，Jingwei 生成的 Repair Task 也交回 Luban 执行。
+
+### Zhulong（烛龙，独立验证智能体）
+
+- **稳定 ID**：`harness-verifier`
+- **Session role**：`verifier`
+- **定位**：独立于 Luban 的验证判定者，只依据任务与实际 evidence 判断。
+- **主要职责**：审查 Controller 执行的确定性验证结果和 evidence，输出 passed、failed 或 evidence_gap 判定。
+- **输入**：Task JSON + Requirement JSON + Evidence 列表。
+- **输出**：VerifierOutput JSON（包含 status、summary、evidenceRefs、followUp）。
+- **权限边界**：只读。`task/edit/write/patch/bash` 全部禁用。可使用全部研究工具辅助审查，但不执行修改、不执行 shell。
+- **上下游关系**：上游是 Controller（传递 evidence），下游是 Yinglong（通过时）或 Xingtian（失败时）。Zhulong 不能修改代码。
+
+### Yinglong（应龙，最终验收智能体）
+
+- **稳定 ID**：`harness-acceptance`
+- **Session role**：`acceptance`
+- **定位**：检查需求、任务和 evidence 的闭环完整性。
+- **主要职责**：验证每个需求和验收项是否都有对应 evidence 覆盖，输出 accepted、failed 或 evidence_gap 判定。
+- **输入**：Task JSON + Requirement JSON + Evidence 列表。
+- **输出**：AcceptanceOutput JSON（包含 status、summary、evidenceIds）。
+- **权限边界**：只读。`task/edit/write/patch/bash` 全部禁用。可使用 grep.app 和 LSP 工具辅助审查，不使用 Context7。
+- **上下游关系**：上游是 Zhulong（验证通过后进入验收），下游是 Controller（Controller 再执行确定性 Guard Condition 决定是否进入 COMPLETED）。Yinglong 不能修改代码。
+
+### Xingtian（刑天，失败归因智能体）
+
+- **稳定 ID**：`harness-failure-analyzer`
+- **Session role**：`failure-analyzer`
+- **定位**：根据实际失败证据分类根因并给出结构化恢复建议。
+- **主要职责**：将失败分类为 `context-gap`、`requirement-ambiguity`、`dependency-blocked`、`implementation-defect`、`verification-environment`、`scope-drift`、`merge-conflict`、`model-failure`，并给出对应恢复动作。
+- **输入**：Task JSON + Requirement JSON + Failure + Evidence 列表。
+- **输出**：FailureAnalyzerOutput JSON（包含 action、category、summary、evidenceIds）。
+- **权限边界**：只读。`task/edit/write/patch/bash` 全部禁用。可使用全部研究工具辅助归因，但不执行修改。
+- **上下游关系**：上游是 Controller（传递失败证据），下游是 Jingwei（需要修复时）或 Controller（需要澄清、等待或终止时）。Xingtian 不能修改代码。
+
+### Jingwei（精卫，修复规划智能体）
+
+- **稳定 ID**：`harness-repair-worker`
+- **Session role**：`repair-worker`
+- **定位**：根据失败证据输出结构化修复建议，只建议，不直接修改代码。
+- **主要职责**：分析失败原因和当前 Task 约束，生成受限的 RepairTask，包含修复步骤、影响范围和验证要求。
+- **输入**：Task JSON + Requirement JSON + Failure + Evidence 列表 + allowedPaths + retryBudget。
+- **输出**：RepairWorkerOutput JSON（包含 status、summary、repairTask、evidenceIds）。
+- **权限边界**：只读。`task/edit/write/patch/bash` 全部禁用。可使用全部研究工具辅助分析，但明确禁止直接修改代码或调用写工具。
+- **上下游关系**：上游是 Xingtian（通过 Controller 传递失败上下文），下游是 Luban（Controller 将 RepairTask 交给 Luban 在受限范围内执行）。Jingwei 不直接修改代码。
+
+## 权限矩阵
+
+```
+Luban / harness-worker:
+  task=false, edit/write/patch/bash=true
+  permission.edit=allow, permission.bash=allow
+
+其他全部 Harness agent:
+  task/edit/write/patch/bash=false
+  permission.edit=deny, permission.bash=deny
+```
+
+`harness` primary 同样只读，不使用任何研究工具。
 
 ## 内部工程工具
 
@@ -25,31 +200,142 @@ Harness 自研并注册以下只读工程工具，不依赖 OMO 或用户的 MCP
 - `harness_grep_app_search`：通过自研 Streamable HTTP MCP 客户端调用 grep.app 官方 `searchGitHub`。
 - `harness_lsp_status`、`harness_lsp_diagnostics`、`harness_lsp_definition`、`harness_lsp_references`：通过自研 JSON-RPC stdio 客户端访问 JDT LS 和 TypeScript Language Server。
 
-这些工具在执行边界校验 Agent 身份，普通 OpenCode Agent 无法调用。Planner、Worker、Verifier 和 Failure Analyzer 可以使用全部研究工具；Acceptance 只使用 grep.app 与 LSP；Intake 和主 Harness Agent不使用这些工具。LSP 只提供只读查询，不实现重命名或代码写入。JDT LS 数据目录位于系统临时目录，并在插件释放时清理。
+这些工具在执行时边界校验 Agent 身份，普通 OpenCode Agent 无法调用。工具使用权限按角色分配：
+
+- **全部研究工具**：Fuxi（Planner）、Luban（Worker）、Zhulong（Verifier）、Xingtian（Failure Analyzer）、Jingwei（Repair Worker）。
+- **grep.app + LSP**：Yinglong（Acceptance）。
+- **不使用研究工具**：Harness（primary）、Nuwa（Intake）。
+
+LSP 只提供只读查询，不实现重命名或代码写入。JDT LS 数据目录位于系统临时目录，并在插件释放时清理。
+
+Context7 默认匿名访问，可通过环境变量 `CONTEXT7_API_KEY` 提升限额。JDT LS 命令可通过 `HARNESS_JDTLS_COMMAND` 覆盖。
+
+## 项目架构
+
+本项目采用分层架构设计，主要包含以下核心模块：
+
+### 配置层 (`src/config/`)
+负责 Harness 配置的解析、验证和合并：
+- `config-schema.ts`: 配置模式定义
+- `config-errors.ts`: 配置错误处理
+- `config-merge.ts`: 配置合并逻辑
+- `load-harness-config.ts`: 配置加载器
+
+### 控制器层 (`src/controller/`)
+核心运行控制器，负责执行和协调整个工程流程：
+- `run-controller.ts`: 主运行控制器
+- `task-executor.ts`: 任务执行器
+- `worktree-scheduler.ts`: 工作树调度器
+- `failure-analysis.ts`: 失败分析
+- `repair-loop.ts`: 修复循环
+- `report-factory.ts`: 报告生成
+
+### 领域层 (`src/domain/`)
+定义核心领域模型：
+- `run.ts`: 运行状态管理
+- `task.ts`: 任务模型
+- `requirement.ts`: 需求模型
+- `evidence.ts`: 证据模型
+- `failure.ts`: 失败模型
+
+### 插件层 (`src/plugin/`)
+OpenCode 插件集成：
+- `create-harness-plugin.ts`: 插件入口
+- `harness-coordinator.ts`: 协调器
+- `harness-chat-hook.ts`: 聊天钩子
+- `harness-intent.ts`: 意图解析
+
+### 工具层 (`src/tools/`)
+集成自研工程工具：
+- `context7-client.ts`: Context7 官方 API 客户端
+- `grep-app-client.ts`: grep.app 搜索客户端
+- `lsp-client.ts`: LSP 客户端（JDT LS/TypeScript）
+- `harness-research-tools.ts`: 研究工具统一接口
+
+### 会话层 (`src/session/`)
+会话管理适配器：
+- `opencode-session-adapter.ts`: OpenCode 会话适配器
+- `fake-session-adapter.ts`: 模拟会话适配器（测试用）
+- `harness-agent-names.ts`: Agent 名称映射
+
+### 存储层 (`src/store/`)
+运行状态持久化：
+- `filesystem-run-store.ts`: 文件系统存储实现
+- `run-event.ts`: 运行事件模型
+
+### 验证层 (`src/verification/`)
+验证命令执行与策略：
+- `command-policy.ts`: 命令策略检查
+- `verification-runner.ts`: 验证运行器
+- `node-process-runner.ts`: 进程执行器
+
+### 工作区层 (`src/workspace/`)
+Git 与工作区管理：
+- `git-workspace-adapter.ts`: Git 工作区适配器
+- `git-worktree-adapter.ts`: Git Worktree 管理
+- `git-baseline.ts`: Git 基线捕获
+
+## 功能特性
+
+### Agent 生命周期管理
+- 支持 `start`、`status`、`resume`、`pause`、`cancel`、`answer`、`waive`、`report` 操作
+- 自然语言请求转换为严格 JSON intent
+- 两阶段非阻塞流程：先受理确认，后台协调运行
+
+### 内部 Agent 链
+当前激活链：`Nuwa → Fuxi → Luban → deterministic verification → Zhulong → Yinglong`
+
+失败处理：`Xingtian` 归因 → `Jingwei` 生成修复任务 → `Luban` 有限修复
+
+### 只读工程工具
+- **Context7**: 直连官方 HTTP API
+- **grep.app**: 通过 Streamable HTTP MCP 客户端搜索
+- **LSP**: 自研 JSON-RPC 客户端访问 JDT LS 和 TypeScript LS
+
+### 确定性恢复
+- 快照与事件持久化到 `.harness/runs/<run-id>/`
+- 原子替换写入，追加持久化带幂等键
+- 恢复时重放快照和事件
+
+### 并行执行
+- 依赖、路径范围和验证资源无冲突时启用
+- 独立 git worktree 执行
+- 冲突时保留诊断 worktree refs
+
+## 快速开始
+
+### 环境要求
+
+- Node.js >= 18
+- pnpm >= 8
+- Git
+
+### 安装依赖
 
-Context7 默认匿名访问；可通过环境变量 `CONTEXT7_API_KEY` 提升限额。JDT LS 命令可通过 `HARNESS_JDTLS_COMMAND` 覆盖。
+```bash
+pnpm install
+```
 
-## 构建与全局加载
+### 构建插件
 
 ```bash
-pnpm install
 pnpm build
 ```
 
-OpenCode 会自动加载 `~/.config/opencode/plugins/` 下的插件。开发环境可创建：
+### 配置 OpenCode
+
+OpenCode 会自动加载 `~/.config/opencode/plugins/` 下的插件。开发环境可创建符号链接或文件：
 
 ```typescript
 // ~/.config/opencode/plugins/harness-engineering-agent.ts
-export { server } from "/workspace/CnbProjectSpace/harness-engineering-agent/dist/index.js"
+export { server } from "/path/to/harness-engineering-agent/dist/index.js"
 ```
 
 修改插件或配置后需要重新执行 `pnpm build`，并重启 OpenCode。
 
 ## 发布到 npm
 
-交互式发布脚本会调用 npm 官方登录流程。用户名正常显示，密码由 npm
-隐藏读取，不会作为命令参数、环境变量或脚本变量保存。账号启用 2FA 时，
-npm 会继续提示输入 OTP。
+交互式发布脚本会调用 npm 官方登录流程。用户名正常显示，密码由 npm 隐藏读取，不会作为命令参数、环境变量或脚本变量保存。账号启用 2FA 时，npm 会继续提示输入 OTP。
 
 先执行不发布的完整检查：
 
@@ -63,8 +349,7 @@ pnpm publish:npm -- --dry-run
 pnpm publish:npm
 ```
 
-脚本依次执行登录、版本占用检查、类型检查、Lint、测试、构建、打包预览
-和发布确认。npm 不允许覆盖已有版本，后续发布前先升级版本：
+脚本依次执行登录、版本占用检查、类型检查、Lint、测试、构建、打包预览和发布确认。npm 不允许覆盖已有版本，后续发布前先升级版本：
 
 ```bash
 npm version patch --no-git-tag-version
@@ -76,21 +361,17 @@ npm registry 要求发布者启用双重验证。账号密码登录后先执行
 npm profile enable-2fa auth-and-writes
 ```
 
-重新运行 `pnpm publish:npm`，发布阶段按 npm 提示输入 OTP。另一种方式是
-在 npm 网站创建 granular access token，为目标包授予 `Read and write`
-权限并启用 `Bypass 2FA`。运行脚本时隐藏输入 token：
+重新运行 `pnpm publish:npm`，发布阶段按 npm 提示输入 OTP。另一种方式是在 npm 网站创建 granular access token，为目标包授予 `Read and write` 权限并启用 `Bypass 2FA`。运行脚本时隐藏输入 token：
 
 ```bash
 pnpm publish:npm -- --token-auth
 ```
 
-脚本将 token 临时写入权限为 `600` 的 npmrc，并仅通过
-`NPM_CONFIG_USERCONFIG` 传给 npm 子进程；`pnpm test/build` 不会继承该
-认证文件。脚本结束后自动删除。token 不会写入命令参数、shell 历史、
-项目文件或日志。该参数不能绕过 npm registry 的服务端权限校验。
+脚本将 token 临时写入权限为 `600` 的 npmrc，并仅通过 `NPM_CONFIG_USERCONFIG` 传给 npm 子进程。`pnpm test/build` 不会继承该认证文件。脚本结束后自动删除。token 不会写入命令参数、shell 历史、项目文件或日志。该参数不能绕过 npm registry 的服务端权限校验。
+
+如果 token 曾经出现在日志、聊天或公开文件中，应立即在 npm 网站撤销并重新创建，不要继续使用泄露的 token。
 
-如果 token 曾经出现在日志、聊天或公开文件中，应立即在 npm 网站撤销并
-重新创建，不要继续使用泄露的 token。
+## OpenCode npm 引用
 
 发布后在 `opencode.json` 中通过 npm 包名加载：
 
@@ -101,6 +382,9 @@ pnpm publish:npm -- --token-auth
 }
 ```
 
+OpenCode 会通过包的 `./server` 导出加载专用插件入口；根入口仍保留完整 SDK 导出，供其它
+npm 调用方使用。
+
 ## 项目配置
 
 在目标项目创建 `.harness/config.yaml`：
@@ -130,56 +414,146 @@ maxRunAttempts: 3
 stateDirectory: .harness/runs
 ```
 
-`harness` profile 只用于专用 `harness` Agent 和内部 Intake Session；不要在这里重新引入 `maxSteps` 等 OpenCode Agent 运行时字段。
+`harness` profile 只用于专用 `harness` Agent 和内部 Intake Session。不要在这里重新引入 `maxSteps` 等 OpenCode Agent 运行时字段。
+
+**Profile 继承规则**：
+- `acceptance` 缺省继承 `verifier` 的 provider/model。
+- `failureAnalyzer` 缺省继承 `planner` 的 provider/model。
+- `repair-worker`（Jingwei）当前复用 `worker` profile，而不是单独配置项。
+- 三者都参与实际控制链，不是预留配置。
+
+配置优先级：插件默认值 < 用户全局配置 < 项目 `.harness/config.yaml` < 当前 Run 覆盖。
+
+## 使用指南
+
+### 启动运行
+
+1. 在 OpenCode 中选择 primary `harness` Agent
+2. 发送自然语言请求，例如："启动一个 run，目标是实现用户登录功能"
+
+使用要点：
+- `start` 请求必须能被 Intake 提炼成 title、summary、acceptanceCriteria。如果缺少必要信息，Harness 会返回 clarification 响应而不是猜测。
+- `status`、`resume`、`cancel`、`report` 必须显式提供 `runId`。Harness 不会默认选择"最近一次运行"。
 
-`acceptance` 缺省继承 `verifier`，`failureAnalyzer` 缺省继承 `planner`。`repair-worker` 当前复用 `worker` profile，而不是单独配置项。三者都会参与实际控制链，不再只是预留配置。
+### 基本操作
 
-`stateDirectory`、任务 `allowedPaths` 和验证工作目录只能是项目内相对路径。
+| 操作 | 说明 | 必填参数 |
+|------|------|----------|
+| `start` | 启动新运行 | title, summary, acceptanceCriteria |
+| `status` | 查询状态 | runId |
+| `resume` | 恢复运行 | runId |
+| `pause` | 暂停运行 | runId |
+| `cancel` | 取消运行 | runId |
+| `report` | 生成报告 | runId |
+| `answer` | 回答问题 | runId |
+| `waive` | 放弃要求 | runId, requirementId |
 
-## 使用方式
+### 恢复运行
 
-1. 在 OpenCode 中选择 primary `harness` Agent。
-2. 直接发送自然语言请求，例如“启动一个 run，目标是……”“查询 run-abc 状态”“恢复 run-abc”“取消 run-abc”“生成 run-abc 报告”。
-3. `start` 请求必须能被 Intake 提炼成 title、summary、acceptanceCriteria；如果缺少必要信息，Harness 会返回 clarification 响应而不是猜测。
-4. `status`、`resume`、`cancel`、`report` 必须显式提供 `runId`；Harness 不会默认选择“最近一次运行”。
+```bash
+resume run-abc
+```
 
-## Agent 集与权限矩阵
+将从 `.harness/runs/run-abc/` 快照恢复上下文。
 
-当前独立 Harness agent set 固定为：
+## 验证策略
 
-- primary：`harness`
-- internal：`Nuwa`、`Fuxi`、`Luban`、`Zhulong`、`Yinglong`、`Xingtian`、`Jingwei`
+验证命令执行受严格策略约束：
+- 必须使用结构化 argv
+- `shell: false` 执行
+- 工作区包含校验
+- 嵌套解释器/包管理器绕过检查
+- 审批元数据约束
 
-角色到 agent 的单一映射：
+不允许 Agent 自报"已通过"替代命令证据。
 
-- `intake -> Nuwa`（兼容 ID：`harness-intake`）
-- `planner -> Fuxi`（兼容 ID：`harness-planner`）
-- `worker -> Luban`（兼容 ID：`harness-worker`）
-- `verifier -> Zhulong`（兼容 ID：`harness-verifier`）
-- `acceptance -> Yinglong`（兼容 ID：`harness-acceptance`）
-- `failure-analyzer -> Xingtian`（兼容 ID：`harness-failure-analyzer`）
-- `repair-worker -> Jingwei`（兼容 ID：`harness-repair-worker`）
+## 测试
 
-权限矩阵：
+```bash
+# 运行所有测试
+pnpm test
 
-- `Luban` / `harness-worker`：`task=false`，`edit/write/patch/bash=true`，`permission.edit=allow`，`permission.bash=allow`
-- 其他全部 Harness agent：`task/edit/write/patch/bash=false`，`permission.edit=deny`，`permission.bash=deny`
+# 运行单元测试
+pnpm test:unit
 
-当前确定性生命周期保持为 `intake -> planner -> worker -> deterministic verification -> verifier -> acceptance -> report`。失败路径会进入 `failure-analyzer`，必要时再进入 `repair-worker -> worker -> deterministic verification -> verifier -> acceptance` 修复闭环。
+# 运行集成测试
+pnpm test:integration
 
-## 恢复与证据
+# 运行 E2E 测试
+pnpm test:e2e
+```
+
+## 项目结构
+
+```
+harness-engineering-agent/
+├── src/
+│   ├── config/         # 配置管理
+│   ├── controller/     # 核心控制器
+│   ├── domain/         # 领域模型
+│   ├── plugin/         # 插件集成
+│   ├── session/        # 会话管理
+│   ├── store/          # 状态存储
+│   ├── tools/          # 工程工具
+│   ├── verification/   # 验证执行
+│   ├── workspace/      # 工作区管理
+│   └── index.ts        # 入口文件
+├── tests/              # 测试用例
+│   ├── config/
+│   ├── controller/
+│   ├── domain/
+│   ├── e2e/
+│   ├── integration/
+│   ├── plugin/
+│   ├── session/
+│   ├── store/
+│   ├── tools/
+│   ├── verification/
+│   └── workspace/
+├── harness/            # 设计文档
+├── package.json
+├── tsconfig.json
+└── biome.json
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CONTEXT7_API_KEY` | Context7 API Key | 匿名访问 |
+| `HARNESS_JDTLS_COMMAND` | JDT LS 命令覆盖 | 自动检测 |
+
+## 状态恢复与证据
 
 - `.harness/runs/<run-id>/state.json` 使用原子替换写入，`events.jsonl` 追加持久化并带稳定幂等键。
-- `FilesystemRunStore` 会在读取时重放快照后的事件，并拒绝未知 major schema version。
+- `FilesystemRunStore` 在读取时重放快照后的事件，并拒绝未知 major schema version。
 - Evidence Ledger 记录 requirement、acceptance criterion、task、changed paths、verification command、输出摘要 digest 和 redaction metadata。
-- Bug 修复与 `repairEnabled` Task 要求 RED/GREEN/REFACTOR 三阶段 evidence；Design Bundle 场景要求 requirement / acceptance / tasks / evidence / report 结构可追踪。
-- 最终报告会汇总 `traceability`、`unfinishedTasks`、`verificationSummaries`、`failures`、`evidenceGaps` 和 `residualRisks`，不会因为 run 结束就抹平历史失败记录。
+- Bug 修复与 `repairEnabled` Task 要求 RED/GREEN/REFACTOR 三阶段 evidence。Design Bundle 场景要求 requirement / acceptance / tasks / evidence / report 结构可追踪。
+- 最终报告汇总 `traceability`、`unfinishedTasks`、`verificationSummaries`、`failures`、`evidenceGaps` 和 `residualRisks`，不会因为 run 结束就抹平历史失败记录。
 
-## 设计来源
+## 目录结构
+
+```
+.harness/
+  config.yaml                     # 项目级 Harness 配置
+  runs/<run-id>/
+    requirement.json              # 结构化需求
+    state.json                    # 完整 Run 状态快照（含需求、任务、Agent 结果、失败和 evidence）
+    events.jsonl                  # 不可变事件日志（追加）
+```
 
-- Harness Engineering：将上下文、工具、状态、反馈、验证和恢复构造成模型外部的确定性控制平面。
-- Superpowers：吸收 brainstorming、writing plans、TDD、systematic debugging、subagent development 和 verification before completion 的工程纪律。
-- 自有 Harness 文档：使用 overview、architecture、specs、implementation-plan 分离动机、技术决策、行为契约和实施计划。
+`state.json` 使用临时文件校验后原子替换，`events.jsonl` 使用稳定幂等键追加。`report` 操作根据当前 Run 生成结构化报告并返回给用户；当前实现不自动写入 `final-report.md`。目标项目应将配置的运行状态目录（默认 `.harness/runs/`）和临时 worktree 元数据加入自身 `.gitignore`。
+
+## 验证命令
+
+当前项目验证命令：
+
+```bash
+pnpm typecheck                    # 类型检查
+pnpm lint                         # Biome lint
+pnpm test                         # Vitest 测试（当前 176 个测试全部通过，单 worker 模式）
+pnpm build                        # 构建
+```
 
 ## 设计文档
 
@@ -187,5 +561,8 @@ stateDirectory: .harness/runs
 - [总体架构](harness/architecture.md)
 - [实施计划](harness/implementation-plan.md)
 - [能力规格](harness/specs/)
+- [架构决策记录](harness/adr/)
+
+## 许可证
 
-插件运行时只依赖 OpenCode Plugin/SDK、配置解析库和目标项目自身的构建测试工具。
+本项目采用 [MIT License](LICENSE) 开源协议。