195 lines
4.3 KiB
Markdown
195 lines
4.3 KiB
Markdown
# Optimization Method
|
||
|
||
本文件记录更稳的多 Agent 协作方法，目标是减少“开发声称完成但复测不过”的循环成本。
|
||
|
||
## 1. 先把验收写成可观测信号
|
||
|
||
不要只写“页面可用”“体验更好”。每个任务至少写三类信号：
|
||
|
||
| 类型 | 示例 |
|
||
|------|------|
|
||
| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
|
||
| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
|
||
| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
|
||
|
||
好的验收：
|
||
|
||
```text
|
||
点击“预览变更”后，页面必须出现 API 返回的 diff 行：
|
||
- title
|
||
- 修改前值
|
||
- 修改后值
|
||
- coverChanged 提示
|
||
```
|
||
|
||
不好的验收：
|
||
|
||
```text
|
||
预览功能正常。
|
||
```
|
||
|
||
## 2. worker_done 必须带证据，不带结论
|
||
|
||
Developer Worker 的 `worker_done` 应该报告：
|
||
|
||
- 改了哪些文件。
|
||
- 跑了哪些命令。
|
||
- 自己如何复现验收路径。
|
||
- 仍可能有的风险。
|
||
|
||
不要让 Developer Worker 写：
|
||
|
||
```text
|
||
已完成，应该可以了。
|
||
```
|
||
|
||
要写：
|
||
|
||
```text
|
||
修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
|
||
手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
|
||
风险：未执行真实写文件 apply。
|
||
```
|
||
|
||
## 3. Product/Test 只信自己的复测
|
||
|
||
即使 worker_done 写了“全部通过”，Coordinator 仍必须重新：
|
||
|
||
1. 确认 worktree。
|
||
2. 构建或重启服务。
|
||
3. 执行验收命令。
|
||
4. 浏览器或 API 复测。
|
||
5. 更新任务板。
|
||
|
||
这可以避免三类假通过：
|
||
|
||
- 测错服务实例。
|
||
- 测到旧构建产物。
|
||
- 开发只验证静态文本，没有验证真实交互。
|
||
|
||
## 4. 三轮失败策略
|
||
|
||
每个任务最多自动派发三轮。
|
||
|
||
```text
|
||
round 1: 常规修复
|
||
round 2: 带复测失败证据的定向修复
|
||
round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
|
||
failed after round 3: 标记 leftover，继续下一个任务
|
||
```
|
||
|
||
三轮失败后不要继续消耗同一个 worker。常见原因是：
|
||
|
||
- 验收标准需要重新设计。
|
||
- Worker 对问题模型理解错了。
|
||
- UI 自动化与实际浏览器状态有差异。
|
||
- 需要人工观察或调试工具介入。
|
||
|
||
留档字段建议：
|
||
|
||
```yaml
|
||
status: leftover
|
||
leftoverReason: "failed after 3 supervised developer rounds"
|
||
attempts:
|
||
- round: 1
|
||
result: failed
|
||
evidence: "<why failed>"
|
||
- round: 2
|
||
result: failed
|
||
evidence: "<why failed>"
|
||
- round: 3
|
||
result: failed
|
||
evidence: "<why failed>"
|
||
```
|
||
|
||
## 5. 任务排序
|
||
|
||
推荐排序：
|
||
|
||
1. P0 阻塞主流程。
|
||
2. P1 高频用户路径。
|
||
3. P1/P2 体验改进。
|
||
4. 重构和内部质量。
|
||
|
||
三轮失败的 P0 可以留档，但最终发布前需要人工决策：
|
||
|
||
- 降级范围。
|
||
- 改验收标准。
|
||
- 换新 Agent / 新 worktree 重做。
|
||
- 人工修复。
|
||
|
||
## 6. 每轮派发只修一个明确问题
|
||
|
||
不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因。推荐：
|
||
|
||
```text
|
||
one dispatch = one bug = one acceptance path
|
||
```
|
||
|
||
优点：
|
||
|
||
- 复测更快。
|
||
- 失败原因更清楚。
|
||
- 三轮失败留档更准确。
|
||
|
||
## 7. 复测前强制记录运行环境
|
||
|
||
每轮复测前记录：
|
||
|
||
```text
|
||
repo:
|
||
worktree:
|
||
branch:
|
||
commit:
|
||
server command:
|
||
BASE_URL:
|
||
frontendDir:
|
||
test commands:
|
||
```
|
||
|
||
如果服务是长跑进程，确认它加载的是最新构建产物。静态前端项目尤其要注意是否重新 `build`。
|
||
|
||
## 8. 把失败证据写给下一轮 worker
|
||
|
||
第二轮以后，派发 prompt 不应重复原始描述为主，而应突出“上一轮为什么没过”。
|
||
|
||
模板：
|
||
|
||
```text
|
||
上一轮不是完全失败，以下部分已通过：
|
||
- <passed checks>
|
||
|
||
仍失败：
|
||
- <missing checks>
|
||
|
||
直接 API/底层验证：
|
||
- <api result>
|
||
|
||
请重点排查：
|
||
- <suspected area>
|
||
```
|
||
|
||
## 9. 优先让测试可执行化
|
||
|
||
如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。优先级：
|
||
|
||
1. API smoke。
|
||
2. 浏览器脚本或 case 文档。
|
||
3. 单元测试。
|
||
4. 人工检查清单。
|
||
|
||
目标不是所有东西都自动化，而是把最容易反复误判的路径自动化。
|
||
|
||
## 10. 结束条件
|
||
|
||
一轮闭环结束时，必须能回答：
|
||
|
||
- 哪些任务 verified？
|
||
- 哪些任务 leftover？
|
||
- 每个 leftover 失败了几轮？
|
||
- 最后一轮失败证据是什么？
|
||
- 当前工作树有哪些未提交改动？
|
||
- 是否还有 open / failed_retest 未处理？
|
||
|
||
如果这些问题答不清楚，闭环还没有结束。
|