XiuChengWu
28ae90a6cc
Some checks failed
- Refresh agents STATUS to W22.6 and exclude mailroom from metadata scans - Add mailroom dispatch checklist and defensive rules - Register F-23.D-1 and tag network input validation defense-in-depth - Update network plugin tests for header length limits - Fix LSP test metadata and remove orphan anthropic_internal.hpp Verification: - cmake --build build --config Release: 0 error, 0 warning - ctest --test-dir build --output-on-failure: 10/10 passed - ctest --test-dir build -R dstalk_smoke_test --output-on-failure: passed - python scripts/check_agents_metadata.py --strict: passed Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
208 lines
8.2 KiB
Markdown
208 lines
8.2 KiB
Markdown
# 子代理 Prompt 模板
|
||
|
||
> **版本**: 1.0 (W10.3 朱晴设计)
|
||
> **用途**: CEO 派活给子代理时复制此模板填写。字段标注"必填"的不可省略。
|
||
|
||
---
|
||
|
||
## 模板骨架
|
||
|
||
```
|
||
你扮演 dstalk 团队成员 <姓名> (<agent-id>) — <角色>。读 `agents/<agent-id>/profile.md` 了解你的人设。
|
||
|
||
**W<n>.<m> 任务**：<一句话目标>
|
||
|
||
**背景**：<2-4 句，说明为什么做这个、依赖什么前置工作、不做的后果是什么>
|
||
|
||
**请读**:
|
||
- <文件 1> ← 控制在 6 个以内，超过说明任务拆得不够细
|
||
- <文件 2>
|
||
- ...
|
||
|
||
**前序成果** (必填):
|
||
- `docs/reference/<某文档>` — W<x>.<y> <作者> 产出，<一句话关联>
|
||
- `agents/<id>/profile.md` — 前序任务记录，看历史决策
|
||
- <如无需依赖前序 Wave，写"无"并说明原因>
|
||
|
||
**任务范围** (必填):
|
||
- 必做: <具体、可验证的事情>
|
||
- 可做: <锦上添花但不强制的事>
|
||
- 不做: <明确排除的事情，即使看似相关也不碰>
|
||
|
||
**禁忌** (必填):
|
||
- 不要碰 `<某目录>/<某文件>` — <原因，如 "W<x>.<y> <人名> in-flight">
|
||
- 不要 <某行为> — <原因，如 "与 plugin-abi.md §3.2 冲突">
|
||
- <若当前无 in-flight 冲突，写"当前无 in-flight 工作区冲突"——但不能留空>
|
||
|
||
**交付清单** (必填，每条带验收标准):
|
||
1. <文件路径>: <具体改动内容> — 验收: <可观测的通过条件>
|
||
2. <文件路径>: <具体改动内容> — 验收: <可观测的通过条件>
|
||
3. `agents/<agent-id>/profile.md`: performance_log 追加 W<n>.<m> — 验收: 新条目出现在文件中
|
||
- **Finding 关联**（如有）：Fixes: F-<Wave>-<N>
|
||
|
||
**验证步骤**:
|
||
cmake --build build --config Release && ctest --test-dir build -C Release
|
||
# 期望: 0 error, 0 warning, 100% smoke test pass
|
||
|
||
**字数上限**: 250 字（报告正文不含代码块，统一标准）
|
||
|
||
**profile.md 更新**: 必须追加，rating: <由执行者自评 (A/A-/B+/B/C)>
|
||
```
|
||
|
||
---
|
||
|
||
## 反模式案例
|
||
|
||
以下错误均来源于 Wave 1-9 实战总结：
|
||
|
||
### 反模式 1: "禁忌"为空
|
||
|
||
```
|
||
❌ 案例: W5.1 派陈风改 plugin_loader.cpp，同时派孙码改 host.cpp，
|
||
两人都改了 g_diag_callback 的声明方式，合并冲突导致回滚 40 分钟。
|
||
根因: CEO 没在 prompt 里写"不要碰 host.cpp 的 g_diag_callback"。
|
||
|
||
✅ 修复: 禁忌必须显式列出所有 in-flight 子代理的工作区文件。
|
||
格式: "不要碰 src/host.cpp — W5.1 孙码 in-flight，改 g_diag_callback"
|
||
```
|
||
|
||
### 反模式 2: "请读"列出 30 个文件
|
||
|
||
```
|
||
❌ 案例: W6.1 某次 prompt 列了 30 个文件要子代理读，
|
||
子代理上下文窗口超限，读完文件后只剩 2KB 预算用于实际工作，
|
||
输出质量断崖式下跌。
|
||
|
||
✅ 修复: "请读"控制在 6 个以内。超过说明任务粒度太粗，
|
||
CEO 应先拆成 2-3 个子任务再派。
|
||
```
|
||
|
||
### 反模式 3: "交付"用模糊词
|
||
|
||
```
|
||
❌ 案例: "改善错误处理"、"优化性能"、"增强可维护性"
|
||
— 子代理改了 5 个文件，CEO 验收时发现改的不是 CEO 想要的东西，
|
||
但 prompt 本身无法作为验收依据。
|
||
|
||
✅ 修复: 交付清单必须 numbered list + 每个条目有验收条件。
|
||
格式: "2. src/host.cpp: 增加 timeout 参数校验 — 验收: 传入 0 返回 -1"
|
||
```
|
||
|
||
### 反模式 4: 没说"前序成果"
|
||
|
||
```
|
||
❌ 案例: W8.1 子代理被要求"增加插件版本检查"，
|
||
但 W1.1 林深已实现过类似的 compare_version()，
|
||
子代理重新实现了整个函数，逻辑还比原版少了一个边界检查。
|
||
|
||
✅ 修复: 前序成果字段必填。如果确实没有可依赖的前序工作，写"无"并说明原因。
|
||
```
|
||
|
||
### 反模式 5: 字数上限不统一
|
||
|
||
```
|
||
❌ 案例: W3 上限 200 字, W5.1 上限 300 字, W9.6 无上限,
|
||
子代理每次都要猜 CEO 想要多详细，报告质量波动大。
|
||
|
||
✅ 修复: 统一 250 字。如需更详细的内容（如大量 diff），
|
||
让子代理在报告末尾注明"详见 <文件>"即可。
|
||
```
|
||
|
||
### 反模式 6: 缺"任务范围"
|
||
|
||
```
|
||
❌ 案例: W2.1 陈风接到"修复跨 DLL 堆问题"，任务只说改 plugin_loader.cpp，
|
||
但他顺便重构了 plugins/tools/file-io 的内存分配——
|
||
结果是好的但风险高，若当时 file-io 有 in-flight 子代理就冲突了。
|
||
|
||
✅ 修复: 任务范围给"必做/可做/不做"三档。
|
||
"可做"是子代理的自由发挥区，"不做"是硬边界。
|
||
```
|
||
|
||
### 反模式 7: 缺少 Finding 关联
|
||
|
||
```
|
||
❌ 案例: W14.3 曹武的修复任务修复了 F-13.5-1 (network_plugin TLS 证书验证)，
|
||
但 prompt 和报告均未标注 Fixes: F-13.5-1，
|
||
导致 findings-registry 无法追踪修复进度，发现状态停留在 OPEN。
|
||
|
||
✅ 修复: 所有修复审计发现的任务必须在 prompt 交付清单中标注
|
||
Fixes: F-<Wave>-<N>（对应 findings-registry.md 中的发现 ID）。
|
||
示例：W14.3 曹武的修复任务应标注 `Fixes: F-13.5-1`。
|
||
```
|
||
|
||
---
|
||
|
||
## 正模式示例: W9.4 林深 (回写)
|
||
|
||
以下基于 W9.4 的实际交付成果回写 prompt，展示正确用法：
|
||
|
||
```
|
||
你扮演 dstalk 团队成员 林深 (architect-lin) — 架构师。读 `agents/architect-lin/profile.md` 了解你的人设。
|
||
|
||
**W9.4 任务**：撰写 `docs/reference/plugin-abi.md` Plugin ABI 契约文档
|
||
|
||
**背景**：跨 DLL 堆纪律在 W2.1 暴露问题后靠口头传递，需要一份规范性文档。
|
||
必须覆盖内存所有权、注册契约、生命周期、线程安全、依赖声明，
|
||
让插件作者和 host 维护者有统一的"法律文本"可查。
|
||
|
||
**请读**:
|
||
- dstalk-core/include/dstalk/dstalk_host.h
|
||
- dstalk-core/include/dstalk/dstalk_types.h
|
||
- dstalk-core/src/plugin_loader.cpp
|
||
- dstalk-core/src/host.cpp
|
||
- dstalk-core/src/service_registry.cpp
|
||
- dstalk-core/src/event_bus.cpp
|
||
|
||
**前序成果** (必填):
|
||
- W2.1 陈风: 跨 DLL 堆纪律的代码修复 (plugin_loader.cpp, host.cpp) — 作为 §3 的素材
|
||
- W1.1 林深: g_diag_callback atomic 修复 (host.cpp) — 作为 §6.1 的素材
|
||
- W2.2 曹武: api_key 安全清零模式 — 作为 §5 安全实践的参考
|
||
|
||
**任务范围** (必填):
|
||
- 必做: 覆盖 7 个契约要点 (DSTALK_API_VERSION / 内存所有权 / 跨DLL堆纪律 /
|
||
register_service / on_init-on_shutdown / 回调线程安全 / 依赖声明)，
|
||
每个要点含代码示例 + 反例 + 设计理由
|
||
- 可做: 追加"变更历史"表格，风格参考现有 docs/ 文件
|
||
- 不做: 修改任何 .cpp / .hpp 源码文件。本任务只产出文档。
|
||
|
||
**禁忌** (必填):
|
||
- 不要碰 src/ 目录 — 这是纯文档任务
|
||
- 不要碰 agents/ 目录 — W9.3 杨帆 in-flight 改 WORKFLOW.md
|
||
- 不要改 dstalk_host.h 的 API_VERSION 值 — 这需要单独的 W 提案
|
||
|
||
**交付清单** (必填，每条带验收标准):
|
||
1. `docs/reference/plugin-abi.md`: 新建文件，约 200 行，7 个契约要点 — 验收: 文件存在且每个 § 有代码 snippet + 反例
|
||
2. `docs/README.md`: reference 区新增 plugin-abi.md 入口 — 验收: git diff 显示新增一行链接
|
||
3. `agents/architect-lin/profile.md`: performance_log 追加 W9.4 — 验收: 新条目出现在文件中
|
||
|
||
**验证步骤**:
|
||
cmake --build build --config Release && ctest --test-dir build -C Release
|
||
|
||
**字数上限**: 250 字
|
||
|
||
**profile.md 更新**: 必须追加，rating: <由执行者自评>
|
||
```
|
||
|
||
---
|
||
|
||
## CEO 派活前 5 步检查
|
||
|
||
派活前逐项确认，缺一不可：
|
||
|
||
| # | 检查项 | 操作 | 写入模板字段 |
|
||
|---|--------|------|-------------|
|
||
| 1 | **列 in-flight 工作区** | 查当前有哪些子代理在跑、他们各自改了哪些文件/目录 | `禁忌` |
|
||
| 2 | **找前序 Wave 产出** | 从 `agents/*/profile.md` 的 performance_log 追溯与本任务关联的之前 Wave 的产出文件 | `前序成果` |
|
||
| 3 | **设定任务范围三档** | 把需求拆成"必做/可做/不做"，不做 = 硬边界 | `任务范围` |
|
||
| 4 | **统一字数上限** | 固定 250 字，不再按任务调整 | `字数上限` |
|
||
| 5 | **扫候选执行者 inbox** | 查看 `agents/mailroom/inbox/<agent-id>/` 是否有 pending handoff / blocker；有阻塞先处理阻塞 | `前序成果` / `禁忌` |
|
||
|
||
---
|
||
|
||
## 参考
|
||
|
||
- [WORKFLOW.md §9](./WORKFLOW.md) — 原始模板（历史备份）
|
||
- [plugin-abi.md](../docs/reference/plugin-abi.md) — 完整任务产出示例
|
||
- [architect-lin/profile.md](./architect-lin/profile.md) — W9.4 执行记录
|