feat: 全面整合agentforge-rs + .codex/harness方法论到AI开发规范

RULES.md 420→460行，新增整合内容: - Karpathy编码准则(先想再写/简洁优先/精准修改/目标驱动) - 验证后才宣称完成铁律(Verification Before Completion) - 系统化调试四阶段(Systematic Debugging) - 约束设计原则(可验证/无歧义/优先级/渐进增强) - 持久执行三层状态管理(系统层/执行层/业务层) - 审查与审计三层体系(自审/配对审查/合规审查) - BDT方法论(Bug Driven Testing + Playwright 7种检查模式) - L4/L5分析与AI自主优化机制 - 标准工作循环(Init→Select→Implement→Verify→Cleanup) - Clean State Checklist(会话结束检查) - 新增10条过往教训(含上下文焦虑/过早宣告胜利等) 新增 MD/specs/HARNESS_ENGINEERING.md (305行) — 完整方法论参考: - WalkingLabs 5子系统模型 - 约束/反馈/控制平面/持久执行详解 - Agent协作管线/路由/去重/禅道操作 - BDT测试用例设计/质量标准 - L4量化分析 + L5 AI自优化 7个AI工具配置文件同步更新(470行内嵌)
2026-06-06 10:01:41 +08:00
parent 84ba9a4139
commit f3880eb8df
9 changed files with 1991 additions and 1366 deletions
--- a/MD/specs/HARNESS_ENGINEERING.md
+++ b/MD/specs/HARNESS_ENGINEERING.md
@@ -0,0 +1,305 @@
+# Harness Engineering 完整方法论
+
+> **文档类型**: 技术规范
+> **适用范围**: AI Agent 协作开发
+> **版本**: v1.0
+> **编制日期**: 2026-06-06
+> **最后更新**: 2026-06-06
+
+---
+
+## 一、WalkingLabs 5 子系统模型
+
+```
+┌─────────────────────────────────────────────┐
+│  指令（Instruction）— RULES.md / AGENTS.md  │
+│  工具（Tools）— shell / 文件 / 测试          │
+│  环境（Environment）— 依赖 / 服务 / 版本     │
+│  状态（State）— PROGRESS.md / 功能清单       │
+│  反馈（Feedback）— test / lint / build       │
+└─────────────────────────────────────────────┘
+```
+
+### 1.1 指令子系统
+
+| 文件 | 用途 |
+|------|------|
+| `RULES.md` | 项目铁律、约束、标准工作流 |
+| `AGENTS.md` | 子目录铁律引用 |
+| `.harness/PROGRESS.md` | 会话进度 + 已验证状态 |
+| `.harness/feature_list.json` | 功能状态唯一事实来源 |
+| `.harness/init.sh` | 统一启动入口 |
+| `.harness/clean-state-checklist.md` | 结束时的清洁检查 |
+
+### 1.2 工具子系统
+
+| 层级 | 工具 | 用途 |
+|------|------|------|
+| L0 开发 | `mvn compile/test` / `npm run build` | 编译、测试 |
+| L1 Agent | `agentforge executor --agent <name>` | Agent 主循环 |
+| L2 Pipeline | `agentforge pipeline` | 流水线批量修 Bug |
+| L3 集成 | Zentao REST API | 禅道操作 |
+| L4 辅助 | `rg` / `git blame` | 代码搜索、历史追溯 |
+
+### 1.3 环境子系统
+
+| 组件 | 配置 |
+|------|------|
+| Redis | `redis://127.0.0.1:16379` |
+| PostgreSQL | `192.168.110.252:15432` |
+| Git | `http://192.168.110.253:3000/wangyizhe/his.git` |
+
+### 1.4 状态子系统
+
+| 机制 | 用途 | 持久化 |
+|------|------|--------|
+| `TraceStore` (SQLite) | Agent 活动追踪 | `/var/lib/agentforge/traces.db` |
+| `fix_trajectory` | 修复轨迹 | Redis Hash |
+| `dead_letter` | 失败任务持久化 | Redis List |
+
+### 1.5 反馈子系统
+
+| 层级 | 速度 | 命令 | 失败处理 |
+|------|------|------|---------|
+| L1 编译检查 | <10秒 | `mvn compile` | 立即阻断 |
+| L1 单元测试 | <5分钟 | `mvn test` | 失败回退，重试 |
+| L2 代码质量 | <2分钟 | ESLint / 编译警告 | 警告可忽略，错误阻断 |
+| L3 质量门禁 | <30秒 | `run_quality_gates()` | 编译验证通过才提交 |
+| L4 人工审查 | 5-10分钟 | diff review | 驳回/指导/批准 |
+
+---
+
+## 二、约束系统
+
+### 2.1 四类约束
+
+| 类型 | 内容 | 示例 |
+|------|------|------|
+| 架构约束 | 接口合约、包结构、命名规范 | 包结构 `com.healthlink.his.web.{module}` |
+| 代码质量 | 圈复杂度、风格、类型提示 | 每函数≤50行 |
+| 安全约束 | 敏感信息、权限、输入验证 | 患者信息脱敏 |
+| 业务规则 | 领域逻辑、数据一致性 | 全链路6环验证 |
+
+### 2.2 约束 DSL
+
+```yaml
+constraint:
+  type: "must" | "must_not" | "should" | "may"
+  scope: "file" | "class" | "method" | "project"
+  rule: "具体规则"
+  verification: "如何验证"
+```
+
+### 2.3 约束优先级
+
+```
+安全(1) > 架构(2) > 业务(3) > 质量(4) > 性能(5)
+```
+
+---
+
+## 三、反馈系统
+
+### 3.1 闭环测试
+
+```
+测试失败
+  → 分析失败原因（编译/逻辑/边界/依赖）
+  → 提取可行动反馈（文件:行号:错误类型:修复方向）
+  → Agent 修复
+  → 重测
+  → 持续失败3次 → 上报人类
+```
+
+### 3.2 反馈格式
+
+```
+文件路径:行号 错误类型 错误描述 | 修复建议
+示例:
+src/main/java/com/.../PatientService.java:42 NullPointerException patient name | 添加空值检查
+```
+
+### 3.3 失败原因分析
+
+| 类型 | 占比 | 捕获门禁 |
+|------|------|---------|
+| 架构错误 | 35% | L1 编译 |
+| 业务逻辑 | 25% | L3 单元测试 |
+| 创造性偏差 | 20% | L3 + L5 |
+| Debug残留 | 15% | L2 静态分析 |
+| 其他 | 5% | L5 |
+
+### 3.4 测试覆盖率目标
+
+```yaml
+unit_test_coverage: 90%      # 行覆盖率
+mutation_score: 80%          # 变异测试通过率
+branch_coverage: 85%         # 分支覆盖率
+```
+
+---
+
+## 四、持久执行
+
+### 4.1 检查点策略
+
+**触发时机**：
+- 每完成1个关键步骤
+- 编译通过/失败后
+- 每次代码修改后
+
+**检查点内容**：
+```yaml
+checkpoint:
+  step_id: "string"
+  status: "pending | in_progress | completed | failed"
+  inputs: {}
+  outputs: {}
+  error_message: ""
+  timestamp: "ISO8601"
+```
+
+### 4.2 恢复流程
+
+```
+失败 → 定位最新检查点 → 分析失败原因 → git restore → 从失败点修复 → 继续执行
+```
+
+### 4.3 幂等性模式
+
+| 模式 | 实现 |
+|------|------|
+| 唯一标识 | 每个操作生成唯一ID，已执行则跳过 |
+| 状态检查 | 执行前检查目标是否已达成 |
+| 补偿操作 | 不可逆操作提供 `git restore` 回滚 |
+
+---
+
+## 五、Agent 协作详解
+
+### 5.1 管线路由
+
+```
+fix_done (关羽/赵云)
+  │
+  ▼
+诸葛亮 (分析路由)
+  │── 无DB变更 ──→ 张飞 (Playwright测试)
+  │── 有DB变更 ─→ 荀彧 (DB审查) → 张飞 (测试)
+  │
+  └── 失败 → 回退给修复者重修（最多10次）
+
+张飞(测试) → 华佗(验收) → 陈琳(归档)
+```
+
+### 5.2 去重机制
+
+| 机制 | TTL | 用途 |
+|------|-----|------|
+| `pipeline_sent:{bug_id}` | 24h | 防重复触发管线 |
+| `pipeline_retry:{bug_id}` | — | 重试计数器 |
+| `codex_lock:{agent}` | 1h | Agent 互斥锁 |
+| `fix_active:{agent}:{bug_id}` | 30min | 防重复 fix_start |
+
+### 5.3 禅道操作规则
+
+| 阶段 | 智能体 | 禅道操作 |
+|------|--------|---------|
+| 分析路由 | 诸葛亮 | 添加备注（分析结果） |
+| DB审查 | 荀彧 | 添加备注（审查结果） |
+| 测试 | 张飞 | 添加测试报告 + resolve |
+| 验收 | 华佗 | 添加备注 + resolve + assign |
+| 归档 | 陈琳 | 添加备注（全流程记录） |
+
+---
+
+## 六、审查与审计
+
+### 6.1 三层审查
+
+| 层级 | 内容 | 信任度 |
+|------|------|--------|
+| L1 自审 | Agent 对照约束逐条检查 | 强制 |
+| L2 配对审查 | Agent 变更摘要 + 人类终审 | 按信任度比例 |
+| L3 合规审查 | 审计追踪，记录所有AI操作 | 强制 |
+
+### 6.2 信任度比例
+
+| 信任等级 | 自审 | 配对审查 | 合规审查 |
+|---------|------|---------|---------|
+| L1 怀疑 | 强制 | 逐行 | 强制 |
+| L2 试探 | 强制 | 抽样30% | 强制 |
+| L3 信任 | 强制 | 抽样10% | 按需 |
+
+### 6.3 审计记录格式
+
+```yaml
+audit_record:
+  agent_id: "codex-v4"
+  task_id: "bug-597"
+  timestamp: "2026-05-28T14:30:00Z"
+  actions:
+    - type: "file_modify"
+      path: "AdviceManageAppMapper.xml"
+      diff: "+7 lines, -2 lines"
+  approvals:
+    - reviewer: "human"
+      decision: "approved"
+```
+
+---
+
+## 七、BDT 方法论（Bug Driven Testing）
+
+### 7.1 流程
+
+```
+获取Bug → 设计用例 → 基线测试(应失败) → 修复 → 回归测试(应通过) → 扩展测试 → 提交
+```
+
+### 7.2 测试用例7种检查模式
+
+| # | 模式 | 适用场景 | Playwright写法 |
+|---|------|---------|---------------|
+| 1 | 页面加载 | 所有Bug | `expect(page).not.toHaveURL(/.*login.*/)` |
+| 2 | 元素可见 | 显示/缺失类 | `expect(locator).toBeVisible()` |
+| 3 | 元素可交互 | 按钮/弹窗类 | `await locator.click()` |
+| 4 | 数据正确 | 列表/回显类 | `expect(locator).toHaveText()` |
+| 5 | 无报错 | 所有Bug | `page.on('pageerror')` |
+| 6 | 流程完整 | 交互流程类 | 多步骤操作链 |
+| 7 | 状态变更 | 退回/审核类 | 操作前vs操作后状态对比 |
+
+### 7.3 测试用例质量标准
+
+- ✅ 有 `@bug{N}` 标签（可单独运行）
+- ✅ 有 `@regression` 标签（回归套件）
+- ✅ 操作路径来自禅道复现步骤
+- ✅ 断言覆盖期望结果
+- ✅ 检查无JS错误
+- ✅ 有截图记录
+- ✅ 独立运行（不依赖其他测试）
+
+---
+
+## 八、L4/L5 分析与优化
+
+### 8.1 L4 量化分析
+
+- TraceStore (SQLite): `/var/lib/agentforge/traces.db`
+- 指标：Agent成功率、平均修复耗时、失败模式分布、Pipeline吞吐量
+
+### 8.2 L5 AI 自主优化
+
+| 机制 | 触发条件 | 动作 |
+|------|---------|------|
+| 约束增强 | 成功率<50%（≥3次） | 自动补充专项约束 |
+| 智能路由 | 按bug类型匹配历史最优Agent | `best_agent_for(bug_type)` |
+| 重试策略 | 失败后换提示词/换Agent | 最多10次 |
+| 路由调整 | 某Agent成功率最低 | 减少分配 |
+
+- 评分：成功率(60%) + 速度(20%) + 类型匹配(20%)
+
+---
+
+> **文档版本**: v1.0
+> **最后更新**: 2026-06-06