华佗
f3880eb8df
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行内嵌)
306 lines
8.5 KiB
Markdown
306 lines
8.5 KiB
Markdown
# 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
|