# 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