wangyizhe/his
1
3
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
8b34873430925efe281a8dafd179195d53dd810f
his/MD/specs/HARNESS_ENGINEERING.md
华佗 f3880eb8df 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

8.5 KiB
Raw Blame History

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

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 测试覆盖率目标

unit_test_coverage: 90%      # 行覆盖率
mutation_score: 80%          # 变异测试通过率
branch_coverage: 85%         # 分支覆盖率

四、持久执行

4.1 检查点策略

触发时机：

  • 每完成1个关键步骤
  • 编译通过/失败后
  • 每次代码修改后

检查点内容：

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 审计记录格式

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