From 004a81db967e46f130abeb3b37c0b02108556f02 Mon Sep 17 00:00:00 2001 From: XiuChengWu <732857315@qq.com> Date: Wed, 27 May 2026 05:52:02 +0800 Subject: [PATCH] Wave 7: collaboration framework hardening (W10.1-W10.4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pure agents/ documentation work — first contributions from 4 previously-idle members (yang/li/zhu/xu). - W10.1 yang: WORKFLOW §11-§13 — collaboration state machine (9 states / 16 transitions), 10-item acceptance checklist, 7-scenario failure rollback playbook (+227 lines) - W10.2 li: agents/STATUS.md — live roster + group + Wave progress snapshot (65 lines) - W10.3 zhu: agents/PROMPT_TEMPLATE.md — subagent prompt template with 6 anti-patterns + 1 worked example + 4-step pre-dispatch checklist (193 lines) - W10.4 xu: agents/POSTMORTEM.md — 5 incident records (PM-001 stale-obj, PM-002 boost-json, PM-003 cross-DLL-heap, PM-004 loader-fail-fast, PM-005 push-force) + 7 defensive rules (172 lines) No code changes. WORKFLOW.md §9 has a pointer to the new PROMPT_TEMPLATE.md. STATUS.md updated to reflect W10.1 completion (yang status flipped working→idle). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- agents/POSTMORTEM.md | 172 +++++++++++++++++++++++ agents/PROMPT_TEMPLATE.md | 193 ++++++++++++++++++++++++++ agents/STATUS.md | 67 +++++++++ agents/WORKFLOW.md | 229 +++++++++++++++++++++++++++++++ agents/architect-yang/profile.md | 5 +- agents/designer-zhu/profile.md | 3 + agents/engineer-li/profile.md | 3 + agents/qa-xu/profile.md | 3 + 8 files changed, 674 insertions(+), 1 deletion(-) create mode 100644 agents/POSTMORTEM.md create mode 100644 agents/PROMPT_TEMPLATE.md create mode 100644 agents/STATUS.md diff --git a/agents/POSTMORTEM.md b/agents/POSTMORTEM.md new file mode 100644 index 0000000..9c8e7bf --- /dev/null +++ b/agents/POSTMORTEM.md @@ -0,0 +1,172 @@ +# dstalk 项目踩坑记录 (Postmortem) + +> **性质**: 历史记录，非设计文档。每个条目基于已发生的事故。 +> **受众**: 全员。新员工/新会话第一份应读材料。 +> **更新规则**: 每次新事故发生后，由 QA 追加一条记录并更新汇总表。 + +--- + +## PM-001: clang-cl 增量构建 stale .obj 文件 + +- **首次发现**: Wave 5 / CEO 验收阶段 / `plugins/lsp/src/lsp_plugin.cpp` 及 `plugins/tools/src/tools_plugin.cpp` +- **症状**: + ``` + # 编译通过，但运行行为与源码不一致；报错行号指向磁盘上已不存在的旧代码 + # clang-cl 报告的 warning/error 行内容与当前源文件内容不符 + ``` +- **根因**: clang-cl 增量构建的时间戳/依赖追踪偶尔遗漏源文件的磁盘修改，重复使用过期的 `.obj` 缓存。并非 CMake 依赖图错误——`cmake --build` 认为目标已是最新，跳过重编译。 +- **影响范围**: 任何使用 clang-cl 增量编译的 `.cpp` 文件；lsp_plugin 和 tools_plugin 至少各中招一次。 +- **修复方法**: + ```bash + rm -f build/**/.cpp.obj # 删除可疑 .obj 强制重编译 + cmake --build build --config Release + ``` + 彻底保险：`cmake --build build --config Release --clean-first`（但耗时）。 +- **防御性规则**（同步到 WORKFLOW.md §6）: + - **R-STALE-OBJ**: CEO 验收编译前，若运行结果与源码不符，先怀疑 stale obj，`rm -f build/**/.cpp.obj` 重试。 +- **检测方法**: + - 对比 `.cpp` 的 mtime 与 `.cpp.obj` 的 mtime：obj 更旧但 `ninja -n` 显示 "no work to do" 时判定 stale。 + - CI 中关键构建（PR merge / release）使用 `--clean-first`。 + +--- + +## PM-002: Boost.JSON header-only 链接错误 + +- **首次发现**: Wave 3 (胡桐 W3) / Wave 7 (王测 W7) / 5 个插件翻译单元 + - `plugins/deepseek/src/deepseek_plugin.cpp` + - `plugins/anthropic/src/anthropic_plugin.cpp` + - `plugins/session/src/session_plugin.cpp` + - `plugins/lsp/src/lsp_plugin.cpp` + - `plugins/tools/src/tools_plugin.cpp` +- **症状**: + ``` + # MSVC linker (Release /MD): + error LNK2001: unresolved external symbol "class boost::json::value ..." + error LNK2001: unresolved external symbol "class boost::json::object ..." + # 多个 boost::json 符号未解析 + ``` +- **根因**: Boost 1.86 废弃了 `BOOST_JSON_HEADER_ONLY` 宏——即使定义了该宏，编译器也忽略它，导致 header-only 模式不生效。缺失的 out-of-line 实现（`boost::json::value`、`boost::json::object` 等）在链接时找不到符号。 +- **影响范围**: 任何 `#include ` 且未同时 include `` 的翻译单元。 +- **修复方法**: + ```cpp + #include + #include // 必须！提供 out-of-line 实现 + ``` + 每个使用 `` 的 `.cpp` 文件中，**恰好一次** include ``。 +- **防御性规则**: + - **R-BOOST-JSON-SRC**: 任何插件 `#include ` 时必须同时 `#include `；新增插件 CI 检查是否有缺失。 +- **检测方法**: + - `grep -rl '' plugins/ | xargs grep -L ''` — 有前者无后者的文件即缺陷。 + - CI Release 构建必须链接成功（/MD 下 Boost.JSON 符号靠 src.hpp 提供，不链接 boost_json 库）。 + +--- + +## PM-003: 跨 DLL 堆释放（/MT 必崩，/MD 侥幸） + +- **首次发现**: Wave 2.1 / 陈风 W2.1 (安全审计触发 + B3 评审) + - `plugins/file_io/src/file_io_plugin.cpp` — 用 `::malloc` 分配，调用方用 `std::free` 释放 + - `plugins/tools/src/tools_plugin.cpp:58` — `std::free(host 分配的指针)` + - `plugins/session/src/session_plugin.cpp:166` — 同上模式 + - `tests/smoke_test.cpp` — 三处 `std::free` 应改为 `dstalk_free` +- **症状**: + ``` + # /MD (动态 CRT): 运行正常（共享 ucrtbase.dll，不同 DLL 的 malloc/free 落在同一个堆——侥幸） + # /MT (静态 CRT): 立即崩溃 / heap corruption + HEAP CORRUPTION DETECTED: after Normal block (#XXX) at 0x... + # 或静默内存损坏，延迟在无关位置崩溃 + ``` +- **根因**: Windows 每个 DLL 拥有独立 CRT 堆（/MT）或共享同一个 CRT DLL 堆（/MD）。插件在自身 CRT 堆上 `malloc` 得到的指针，传给 host 后 host 调用 `free` —— host 的 CRT 尝试释放一个不属于它的堆上的地址 → 未定义行为。当前项目使用 `/MD` 故不立即触发，但这是一个精度定时炸弹（任何人改 CRT 链接方式就会引爆）。 +- **影响范围**: 所有插件与 host 之间传递动态分配内存的场景。涵盖 `malloc`/`free`/`strdup`/`new`/`delete`。 +- **修复方法**: + ```c + // 错误（跨 DLL 堆）: + char* buf = (char*)::malloc(256); + // ... + std::free(buf); // 释放者与分配者不同 CRT 堆 + + // 正确（统一堆）: + char* buf = (char*)g_host->alloc(256); + // ... + g_host->free(buf); // 通过 host_api 函数指针回到同一个堆 + ``` + 详见 `docs/reference/plugin-abi.md` §2-§3。 +- **防御性规则**: + - **R-NO-RAW-ALLOC**: 插件代码严禁直接调用 `malloc`/`free`/`strdup`/`new`/`delete` 处理跨 DLL 边界数据；必须使用 `host->alloc`/`host->free`/`host->strdup`。 + - **R-TEST-MT**: CI 至少一个配置使用 `/MT` 构建并跑 smoke test，确保跨堆问题在任何 CRT 模式下暴露。 +- **检测方法**: + - `grep -nP '\b(std::)?(malloc|free|strdup|realloc)\b' plugins/**/*.cpp` — 任何命中需审计是否是私有堆操作（不跨 DLL 边界）。 + - `grep -nP '\bnew\b.*\bdelete\b'` 同审计。 + - ASan (`-fsanitize=address`) 在 Windows 下对跨堆释放敏感，可捕获 heap-use-after-free / alloc-dealloc-mismatch。 + +--- + +## PM-004: plugin_loader 单插件失败导致全部初始化终止 + +- **首次发现**: Wave 2.1 / 陈风 W2.1 (side-effect 发现) → Wave 9.8 / 黄岭 W9.8 (正式修复) + - `dstalk-core/src/plugin_loader.cpp` — `initialize_all()` 函数 +- **症状**: + ``` + # 假设加载 A→B→C 三个插件，B 的 on_init 返回 -1: + # 旧行为: + [ERROR] Plugin 'B' init failed (code -1) + # A 已初始化成功，但 B 失败后 initialize_all 立即 return -1 + # C 完全未被尝试初始化——即使 C 不依赖 B + # 症状: "明明只坏了一个插件，为什么其他插件也不工作？" + ``` +- **根因**: 旧版 `initialize_all()` 使用 fail-fast 模式 —— 任何一个 `on_init` 返回非零，整个函数立即返回 `-1`，剩余插件全部跳过。没有"部分成功"的概念。 +- **影响范围**: 所有依赖于 `initialize_all()` 正常完成的调用方（CLI、GUI、测试）。一个低优先级插件失败会让整个应用退化。 +- **修复方法** (黄岭 W9.8): + - 将 fail-fast 改为 fail-continue：单个 `on_init` 失败 → `fprintf(stderr, ...)` + 标记 `failed_names` + `failed_count++` → `continue` 下一个。 + - 依赖已失败插件的下游插件自动跳过并 `[WARN]`。 + - 返回值语义: `0` = 全部成功；`>0` = 失败的插件数；`<0` = 严重错误（循环依赖 / host_api null）。 + - 代码位置: `plugin_loader.cpp:202-256`。 +- **防御性规则**: + - **R-LOADER-CONTINUE**: 插件加载/初始化**永不 fail-fast**；单点故障不得级联阻断无关插件。 + - **R-LOADER-RETVAL**: `initialize_all` 返回值 >0 表示部分成功（调用方必须区分 "完全失败" 和 "部分退化"）。 +- **检测方法**: + - 单元测试：加载 3 个插件，中间一个 mock 为 "always init fail"，验证第 1、3 个正常初始化，且返回值为 1。 + - smoke test 验证所有 9 个插件加载（当前预期 9/9 通过）。 + +--- + +## PM-005: git push --force 未在子代理 prompt 中禁止 + +- **首次发现**: Wave 1+ / CEO 规则层面 / 无特定代码文件 +- **症状**: + ``` + # 子代理在独立会话中执行 git 操作，可能使用 --force 推送 + # 远端历史被改写，其他协作者的本地分支与远端不一致 + # 没有 git hook 阻止，也没有 prompt 模板明确禁止 + ``` +- **根因**: CEO 规则明确禁止 `push --force`，但该规则只在主会话中有效。子代理的 prompt 模板（`WORKFLOW.md` §9）没有包含此禁忌，子代理不知道这条规则。 +- **影响范围**: 所有通过 `Agent` 工具派出的子代理。任何子代理执行 `git push` 时都可能误用 `--force`。 +- **修复方法**: + 1. 子代理 prompt 模板中增加："禁止 git push --force / --force-with-lease，禁止 git reset --hard origin/*" + 2. 可选：服务端 git hook（GitHub branch protection）禁止 force push 到 master。 +- **防御性规则**: + - **R-NO-FORCE-PUSH**: 每个子代理任务 prompt 必须包含 "禁止 git push --force / --force-with-lease"；如需改写历史仅限本地 `git rebase -i`（未推送的提交）。 +- **检测方法**: + - GitHub branch protection rule: master 分支禁止 force push。 + - 每次 CEO 验收后检查 `git reflog` 是否有 force push 痕迹。 + +--- + +## 防御性规则汇总表 (§6) + +| 规则 ID | 事故 | 规则一句话 | +|---------|------|-----------| +| R-STALE-OBJ | PM-001 | 运行结果与源码不符时先怀疑 stale obj，`rm -f build/**/.cpp.obj` 重编 | +| R-BOOST-JSON-SRC | PM-002 | `#include ` 的 .cpp 必须同时 `#include ` | +| R-NO-RAW-ALLOC | PM-003 | 插件代码严禁 `malloc`/`free`/`strdup`/`new`/`delete` 跨 DLL 边界；统一用 `host->alloc/free/strdup` | +| R-TEST-MT | PM-003 | CI 至少一个配置用 `/MT` 构建并跑 smoke test | +| R-LOADER-CONTINUE | PM-004 | 插件加载/初始化永不 fail-fast，单点故障不级联阻断 | +| R-LOADER-RETVAL | PM-004 | `initialize_all` 返回值 >0 = 部分成功，调用方必须区分 | +| R-NO-FORCE-PUSH | PM-005 | 子代理 prompt 必须禁止 `git push --force` / `--force-with-lease` | + +--- + +## 变更历史 + +| 日期 | 版本 | 变更 | +|------|------|------| +| 2026-05-27 | 1.0 | W10.4 初始化。记录 PM-001 至 PM-005，共 5 条事故 7 条防御性规则。 | diff --git a/agents/PROMPT_TEMPLATE.md b/agents/PROMPT_TEMPLATE.md new file mode 100644 index 0000000..eae79bf --- /dev/null +++ b/agents/PROMPT_TEMPLATE.md @@ -0,0 +1,193 @@ +# 子代理 Prompt 模板 + +> **版本**: 1.0 (W10.3 朱晴设计) +> **用途**: CEO 派活给子代理时复制此模板填写。字段标注"必填"的不可省略。 + +--- + +## 模板骨架 + +``` +你扮演 dstalk 团队成员 <姓名> () — <角色>。读 `agents//profile.md` 了解你的人设。 + +**W. 任务**：<一句话目标> + +**背景**：<2-4 句，说明为什么做这个、依赖什么前置工作、不做的后果是什么> + +**请读**: +- <文件 1> ← 控制在 6 个以内，超过说明任务拆得不够细 +- <文件 2> +- ... + +**前序成果** (必填): +- `docs/reference/<某文档>` — W. <作者> 产出，<一句话关联> +- `agents//profile.md` — 前序任务记录，看历史决策 +- <如无需依赖前序 Wave，写"无"并说明原因> + +**任务范围** (必填): +- 必做: <具体、可验证的事情> +- 可做: <锦上添花但不强制的事> +- 不做: <明确排除的事情，即使看似相关也不碰> + +**禁忌** (必填): +- 不要碰 `<某目录>/<某文件>` — <原因，如 "W. <人名> in-flight"> +- 不要 <某行为> — <原因，如 "与 plugin-abi.md §3.2 冲突"> +- <若当前无 in-flight 冲突，写"当前无 in-flight 工作区冲突"——但不能留空> + +**交付清单** (必填，每条带验收标准): +1. <文件路径>: <具体改动内容> — 验收: <可观测的通过条件> +2. <文件路径>: <具体改动内容> — 验收: <可观测的通过条件> +3. `agents//profile.md`: performance_log 追加 W. — 验收: 新条目出现在文件中 + +**验证步骤**: +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 子代理就冲突了。 + +✅ 修复: 任务范围给"必做/可做/不做"三档。 + "可做"是子代理的自由发挥区，"不做"是硬边界。 +``` + +--- + +## 正模式示例: 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 派活前 4 步检查 + +派活前逐项确认，缺一不可： + +| # | 检查项 | 操作 | 写入模板字段 | +|---|--------|------|-------------| +| 1 | **列 in-flight 工作区** | 查当前有哪些子代理在跑、他们各自改了哪些文件/目录 | `禁忌` | +| 2 | **找前序 Wave 产出** | 从 `agents/*/profile.md` 的 performance_log 追溯与本任务关联的之前 Wave 的产出文件 | `前序成果` | +| 3 | **设定任务范围三档** | 把需求拆成"必做/可做/不做"，不做 = 硬边界 | `任务范围` | +| 4 | **统一字数上限** | 固定 250 字，不再按任务调整 | `字数上限` | + +--- + +## 参考 + +- [WORKFLOW.md §9](./WORKFLOW.md) — 原始模板（历史备份） +- [plugin-abi.md](../docs/reference/plugin-abi.md) — 完整任务产出示例 +- [architect-lin/profile.md](./architect-lin/profile.md) — W9.4 执行记录 diff --git a/agents/STATUS.md b/agents/STATUS.md new file mode 100644 index 0000000..1cec403 --- /dev/null +++ b/agents/STATUS.md @@ -0,0 +1,67 @@ +# dstalk 实时编制状态 + +> **最后更新**: 2026-05-27 +> **数据来源**: 由 W10.2 任务自动整理（扫描全部 16 个 `agents/*/profile.md` + 5 个 `agents/groups/*.md` + `git log`）。CEO 可命令任意员工执行同样任务刷新。 + +## 表 1：员工状态（16 人） + +| Agent ID | 姓名 | 角色 | 最近一次贡献 | perf_log | 当前小组 | 状态 | +|---|---|---|---|---|---|---| +| architect-lin | 林深 | 架构师 | W9.4 撰写 plugin-abi.md (7 点 ABI 契约) | 6 | grp-quality-core, grp-ai-plugins | idle | +| architect-yang | 杨帆 | 架构师 | W10.1 WORKFLOW §11-§13 状态机 + 验收清单 + 失败回退 | 2 | -- | idle | +| architect-huang | 黄岭 | 架构师 | W9.8 initialize_all 容错修复 (fail-fast → fail-continue) | 2 | -- | idle | +| engineer-zhao | 赵码 | 工程师 | W9.6 CLI /history 命令 + /status 集成 | 6 | grp-ai-plugins, grp-cli-ux | idle | +| engineer-chen | 陈风 | 工程师 | W2.1 跨 DLL 堆释放修复 (unify host->alloc/free) | 2 | -- | idle | +| engineer-li | 李明 | 工程师 | W10.2 STATUS.md 实时编制状态文档 (63 行) | 2 | -- | idle | +| engineer-zhou | 周岩 | 工程师 | W5.1 SSE buffer_body 优化 (峰值内存 -67%) | 2 | -- | idle | +| engineer-sun | 孙宇 | 工程师 | W6.1 LSP reader_loop 协议合规修复 (状态机解析) | 2 | -- | idle | +| qa-wang | 王测 | 质量工程师 | W7 smoke test 9 插件加载修复 + Boost.JSON 链接 | 5 | grp-quality-core, grp-cli-ux | idle | +| qa-liu | 刘静 | 质量工程师 | W9.10 host_api 单元测试 (8 cases) | 2 | grp-security-audit | idle | +| qa-xu | 徐磊 | 质量工程师 | W10.4 POSTMORTEM.md 踩坑记录 (5 事故 7 规则) | 3 | grp-security-audit | idle | +| devops-ma | 马奔 | DevOps | W4 CI pipeline GitHub Actions (Linux/Windows 双矩阵) | 2 | grp-build-matrix | idle | +| devops-hu | 胡桐 | DevOps | W3 CMake 4 项现代化 (target-based + Boost config) | 2 | grp-build-matrix | idle | +| designer-zhu | 朱晴 | UX/CLI 设计师 | W10.3 PROMPT_TEMPLATE.md 子代理模板 (骨架+反模式+正模式) | 2 | grp-cli-ux | idle | +| writer-deng | 邓书 | 技术作家 | W9.1 Diátaxis Explanation 文档 (architecture + plugin-lifecycle) | 2 | -- | idle | +| security-cao | 曹武 | 安全工程师 | W9.3 日志凭证泄露审计 (8 文件 0 真实漏洞) | 3 | grp-security-audit | idle | + +> **状态判定规则**: 基于 `performance_log` 最后一条的 `rating`——`ongoing` 视为 `working`，其余 (`A/A+/B/completed/done/success/good`) 视为 `idle`。 + +## 表 2：工作组状态（5 组） + +| group_id | 名称 | lead | members | mission | active_tasks | 状态 | +|---|---|---|---|---|---|---| +| grp-quality-core | 核心质量小组 | 王测 | 林深, 王测 | 确保插件化架构的代码质量和测试覆盖 | -- (C2 已交付) | 待命 | +| grp-ai-plugins | AI 插件小组 | 赵码 | 赵码, 林深 | AI 相关插件的功能完善和架构优化 | -- | 待命 | +| grp-cli-ux | CLI 体验小组 | 赵码 | 赵码, 朱晴, 王测 | 改进 dstalk-cli 的交互体验、健壮性和可测试性 | B3: CLI 交互增强 (信号处理/状态命令/退出码/管道输入) | 执行中 | +| grp-build-matrix | 构建矩阵小组 | 马奔 | 马奔, 胡桐 | 完善 CI 跨平台构建矩阵 (Linux/Windows, Clang/MSVC) | -- | 待命 | +| grp-security-audit | 安全审计小组 | 曹武 | 曹武, 徐磊, 刘静 | 全面审计内存安全、API 密钥处理、反序列化路径 | -- | 待命 | + +> **成员列来源**: 以 `agents/groups/*.md` 为准（部分成员 profile 未同步更新 `current_groups`）。 + +## Wave 进度 + +**已完成高水位**: W9.10（已 commit `5766938`） + +**已完成 Wave 清单** (WORKFLOW.md §7 + commit message): +W1.1, W2.1, W2.2, W3, W4, W5.1, W6.1, W7, W8.1, W9.1, W9.3, W9.4, W9.6, W9.8, W9.10 + +**In-flight (W10.x，尚未 commit)**: + +| 任务 | 负责人 | 交付物 | 状态 | +|---|---|---|---| +| W10.1 | architect-yang (杨帆) | `agents/WORKFLOW.md` §11-§13 (状态机+验收清单+失败回退, +227 行) | 已完成，未 commit | +| W10.2 | engineer-li (李明) | `agents/STATUS.md` (本文件, 65 行) | 已完成，未 commit | +| W10.3 | designer-zhu (朱晴) | `agents/PROMPT_TEMPLATE.md` (子代理 prompt 模板, 193 行) | 已完成，未 commit | +| W10.4 | qa-xu (徐磊) | `agents/POSTMORTEM.md` (项目踩坑记录, 172 行) | 已完成，未 commit | + +**未提交变更摘要**: +- `agents/WORKFLOW.md` — §9 追加模板迁移链接 + §11-§13 杨帆扩展 +- `agents/architect-yang/profile.md` — 追加 W10.1 +- `agents/designer-zhu/profile.md` — 追加 W10.3 +- `agents/qa-xu/profile.md` — 追加 W10.4 +- `agents/engineer-li/profile.md` — 追加 W10.2 +- `agents/PROMPT_TEMPLATE.md` — 新增 (untracked) +- `agents/POSTMORTEM.md` — 新增 (untracked) +- `agents/STATUS.md` — 新增 (untracked, 本文件) + +**下一波建议起点**: W11.x（CEO 先 commit W10.1~W10.4，再派新任务；当前 16/16 员工 idle，产能充足） diff --git a/agents/WORKFLOW.md b/agents/WORKFLOW.md index 0c63398..9a9fbb6 100644 --- a/agents/WORKFLOW.md +++ b/agents/WORKFLOW.md @@ -108,6 +108,8 @@ 3. profile.md 已更新 ``` +> **本节模板已迁移到 [agents/PROMPT_TEMPLATE.md](PROMPT_TEMPLATE.md)**，本处保留备份。 + ## 10. 关联文档 - [README.md](README.md) — 团队花名册 + 公司宗旨 @@ -116,3 +118,230 @@ - [../docs/explanation/architecture.md](../docs/explanation/architecture.md) — 架构哲学 - [../docs/explanation/plugin-lifecycle.md](../docs/explanation/plugin-lifecycle.md) — 插件生命周期 - [../docs/explanation/security-logging.md](../docs/explanation/security-logging.md) — 日志安全审计 + +## 11. 协作状态机（强制规则） + +状态机定义每个 Wave 从提案到交付（或终止）的合法路径。所有状态转换必须满足明确条件，不存在"CEO 感觉可以就过"的模糊转换。 + +### 11.1 状态定义 + +| 状态 | 类型 | 含义 | +|------|------|------| +| PROPOSE | 活跃 | CEO 拆解需求为候选任务，编号 W<n>.<m> | +| VOTE | 活跃 | 3-4 名子代理独立评估提案，投票同意/反对/否决 | +| OPTIMIZE | 活跃 | 被否决的提案根据反对意见逐条修改 | +| INTEGRATE | 活跃 | CEO 汇总投票结果为统一可执行计划 | +| EXECUTE | 活跃 | 指派专长员工实施，每人有明确文件白名单和禁忌清单 | +| INSPECT | 活跃 | CEO 运行完整验收清单（§12），逐项核对 | +| SUCCESS | 终止 | Wave 完成，git commit + git push | +| ABORT | 终止 | CEO 判定任务不再可行，丢弃本 Wave | +| ROLLBACK | 终止 | 不可恢复错误，回退触发改动后重新决策 | + +### 11.2 状态转换图 + +``` + +----------+ + | PROPOSE | + +----+-----+ + | + simple | complex + +-------------+--------------+ + | | + | v + | +----------+ + | | VOTE | + | +----+-----+ + | | + | +-------------+-------------+ + | | >50% reject | pass | + | v v | + | +----------+ +-----------+ | + | | OPTIMIZE | | INTEGRATE | | + | +----------+ +-----+-----+ | + | | | + | v | + | +----------+ | + +--------------------->| EXECUTE |<-------+ + +----+-----+ + | + +----------+----------+ + | done | fatal | + v v | + +----------+ +----------+ | + | INSPECT | | ROLLBACK | | + +----+-----+ +----------+ | + | + +---------+---------+ + | pass | fail | + v v | + +----------+ +-------+ | + | SUCCESS | | FAIL | | + +----------+ +-------+ | +``` + +回边（图中未画以避免杂乱，均以文字列出）： + +- OPTIMIZE --re-vote--> VOTE +- OPTIMIZE --fundamental rewrite--> PROPOSE +- INSPECT fail --fixable--> EXECUTE +- INSPECT fail --design--> OPTIMIZE +- INSPECT fail --fatal--> ROLLBACK +- INSPECT fail --abandon--> ABORT + +全局出口（任意状态）： + +- ANY --CEO abort--> ABORT + +### 11.3 转换条件表 + +| # | 从 | 到 | 触发条件 | 决策者 | +|---|----|----|----------|--------| +| T1 | PROPOSE | VOTE | 任务涉及跨模块改动 OR 涉及架构决策 OR 涉及新增公共 API OR CEO 指定需评审 | CEO | +| T2 | PROPOSE | EXECUTE | 单文件改动 AND 不涉及公共头文件 AND 不涉及 CMakeLists.txt AND CEO 判定为简单任务 | CEO | +| T3 | VOTE | OPTIMIZE | (反对票数 / 总票数) > 0.5 OR 任一投票者给出"否决"并附具体技术理由 | 自动（计票） | +| T4 | VOTE | INTEGRATE | 所有投票者标记"同意" OR (反对票 ≤ 50% AND 无否决票) | 自动（计票） | +| T5 | OPTIMIZE | VOTE | 提案方完成修改，提交修订版提案申请重新投票 | 提案方 | +| T6 | OPTIMIZE | PROPOSE | 修改范围超出原提案 50%，实质成为新提案 | CEO | +| T7 | INTEGRATE | EXECUTE | CEO 输出统一执行计划（任务-执行者映射 + 文件白名单 + 禁止触碰清单 + 验证步骤） | CEO | +| T8 | EXECUTE | INSPECT | 所有指派的执行者子代理均已返回 done 报告（含 cmake build 0 error + ctest 100% pass 自述） | 自动（全员 done） | +| T9 | EXECUTE | ROLLBACK | 任一执行者报告以下任一情况且 CEO 判定不可原地修复：段错误 / ABI 破坏 / CMake 无法 configure / 数据文件损坏 | CEO | +| T10 | EXECUTE | ABORT | CEO 判定需求不再成立 OR 外部依赖不可用 | CEO | +| T11 | INSPECT | SUCCESS | §12 验收清单全部通过：cmake configure 0 error AND cmake build 0 error 0 warning(改动文件) AND ctest 100% pass AND 测试目标数 ≥ 上一波 AND profile.md 已更新 AND 无未跟踪临时文件 AND git diff 无无关改动 | CEO | +| T12 | INSPECT | EXECUTE | 验收失败但满足全部：根因可定位到具体文件+行号 AND ≤2 个文件 AND ≤30 行改动 AND 不需重新设计 | CEO | +| T13 | INSPECT | OPTIMIZE | 验收暴露以下任一设计问题：接口不兼容（编译通过但运行时错）/ 性能偏差 >50% / 架构假设被证伪（如单线程假设在多线程场景崩溃） | CEO | +| T14 | INSPECT | ROLLBACK | 验收发现不可逆副作用：文件错误删除或覆盖 / 二进制损坏 / .git 目录状态异常 | CEO | +| T15 | INSPECT | ABORT | CEO 判定继续修复成本 > 重新执行成本（需改 >5 个文件且涉及多个执行者重新协调） | CEO | +| T16 | ANY | ABORT | 用户明确指令中止 OR 触发安全红线（凭证泄露、未加密敏感数据落盘） | CEO | + +### 11.4 状态进入/退出动作 + +| 状态 | 进入动作 | 退出动作 | +|------|----------|----------| +| PROPOSE | CEO 在 WORKFLOW.md §7 登记 W<n> 编号 | 提案内容归档到 agents/ 目录 | +| VOTE | CEO 派 3-4 路 vote 子代理，prompt 含提案全文和评审标准 | 计票结果写入 WORKFLOW.md §7 | +| EXECUTE | CEO 记录执行者名单 + 文件白名单 + 禁忌清单 | 汇总所有执行者报告 | +| INSPECT | CEO 运行 §12 完整验收清单 | 验收结果和通过/失败项写入 WORKFLOW.md §7 | +| SUCCESS | CEO 执行 git commit + git push | — | +| ROLLBACK | 执行 §13.6 ROLLBACK 协议 6 步 | 回退原因和影响文件写入 WORKFLOW.md §7 | +| ABORT | 记录中止原因和时间 | 本波 W 编号标记 ABORTED，写入 WORKFLOW.md §7 | + +## 12. 验收清单（CEO inspect 硬指标） + +以下全部为强制检查项，**缺一不可**。CEO 在 INSPECT 状态必须逐项核对，任一未通过即判定 inspect 失败。 + +### 12.1 构建检查 + +| # | 检查项 | 命令/方法 | 通过标准 | +|---|--------|-----------|----------| +| B1 | cmake configure | `cmake --preset release 2>&1` | exit code = 0，stderr 无 "error:" | +| B2 | cmake build | `cmake --build build --config Release 2>&1` | exit code = 0，stderr 无 "error:" | +| B3 | 编译警告 | B2 输出中每个 warning 所在文件与 `git diff --name-only HEAD` 比对 | 本次改动文件产生 **0 warning**；非改动文件的预存 warning 不阻塞验收但需记录在案 | + +### 12.2 测试检查 + +| # | 检查项 | 命令/方法 | 通过标准 | +|---|--------|-----------|----------| +| T1 | ctest 全量 | `ctest --test-dir build --output-on-failure` | 100% tests passed, 0 tests failed | +| T2 | 测试数量 | `ctest -N --test-dir build` 统计测试目标数 | 测试目标数 ≥ 上一波记录值（覆盖不减少） | +| T3 | smoke 专项 | `ctest -R smoke --test-dir build` | 100% passed（smoke 是回归底线，不可失败） | + +### 12.3 交付物检查 + +| # | 检查项 | 命令/方法 | 通过标准 | +|---|--------|-----------|----------| +| D1 | profile 更新 | 逐个检查本波每个执行者的 `agents/<id>/profile.md` | 每个执行者 performance_log 含本波 W 编号条目 | +| D2 | 无临时文件 | `git status --short` | 无 .tmp / .swp / *~ / .DS_Store / build/ 目录下的未跟踪文件 | +| D3 | diff 纯净性 | `git diff HEAD` 逐文件审核 | 改动仅涉及任务相关文件，无意外修改；任何疑问 diff 块需执行者解释 | +| D4 | 子代理自述 | 检查每个执行者子代理返回的最终消息 | 含 "cmake build 0 error" + "ctest 100% pass" 自述 | + +### 12.4 验收结论映射 + +| 失败项组合 | 严重级别 | 回退目标 | +|------------|----------|----------| +| 仅 B1/B2/B3 失败 | 执行错误 | INSPECT → EXECUTE（修复构建） | +| 仅 T1/T2/T3 失败 | 执行错误 | INSPECT → EXECUTE（修复测试） | +| 仅 D1/D2/D3/D4 失败 | 流程错误 | INSPECT → EXECUTE（补文档/清理文件） | +| B类 + T类 同时失败 | 设计错误 | INSPECT → OPTIMIZE | +| 失败涉及 >2 个执行者 | 设计错误 | INSPECT → OPTIMIZE | +| 全部通过 | — | INSPECT → SUCCESS | + +## 13. 失败回退路径（强制处理协议） + +以下协议覆盖所有阶段的失败场景。每个场景的处理步骤为**强制规则**，不存在"CEO 视情况灵活处理"的模糊空间。 + +### 13.1 PROPOSE 阶段失败 + +- **症状**：CEO 无法将需求拆解为可执行任务（需求模糊 / 范围过大 / 与现有架构冲突） +- **处理**：CEO 直接重写提案。缩小范围或拆分为多个 Wave。本 Wave 不进入 VOTE。 +- **重试上限**：最多重写 2 次。第 3 次仍不可行 → ABORT，记录原因到 WORKFLOW.md §7。 +- **责任人**：CEO + +### 13.2 VOTE 阶段否决 + +- **症状**：>50% 投票者反对 OR 任一投票者给出技术否决 +- **处理步骤**： + 1. CEO 汇总所有反对票的具体理由，归档到 WORKFLOW.md §7 + 2. 进入 OPTIMIZE，由原提案方根据反对意见逐条修改 + 3. 修改完成后重新进入 VOTE + 4. **连续 2 轮 VOTE 均被否决** → 回到 PROPOSE，CEO 重新出提案（原方案方向放弃） + 5. **连续 3 轮 PROPOSE→VOTE→OPTIMIZE 循环仍无共识** → ABORT，CEO 判定该需求当前不可执行 +- **责任人**：提案方（第 1 轮修改）+ CEO（第 2 轮起裁决） + +### 13.3 OPTIMIZE 阶段僵局 + +- **症状**：提案方无法在合理范围内满足反对意见 OR 修改导致方案退化 +- **处理**： + 1. 修改范围 > 原提案 50% → 回到 PROPOSE（作为新提案，重新编号） + 2. 反对意见本身有争议 → CEO 仲裁，判定反对是否成立 + 3. CEO 判定无法调和 → ABORT，CEO 另起替代方案 +- **责任人**：CEO + +### 13.4 EXECUTE 阶段失败 + +- **症状**：执行者子代理返回失败（编译错误 / 测试失败 / 无法完成任务） + +**分级处理表**： + +| 失败级别 | 条件 | 处理 | 责任人 | +|----------|------|------|--------| +| L1 轻微 | 单执行者失败，根因明确，修复 ≤30 行 | CEO 在原 prompt 追加修复指令，同一执行者重试（仅 1 次） | 原执行者 | +| L2 中等 | L1 重试仍失败 OR 失败涉及 >2 个文件 | CEO 换人执行（选同专长其他员工）OR CEO 亲自修复 | CEO | +| L3 严重 | 多执行者同时失败 OR 构建系统破坏 OR ABI 破坏 | 进入 ROLLBACK：`git checkout -- <触发文件>` + CEO 判定是否缩小范围重新 EXECUTE | CEO | +| L4 致命 | 数据损坏 / 无法定位的段错误 / 安全漏洞暴露 | 进入 ROLLBACK + 指派 security-cao 安全审计 | CEO + security-cao | + +### 13.5 INSPECT 阶段失败 + +**处理协议（按步骤强制执行，不可跳过）**： + +1. **先回退触发改动**：`git checkout -- <验收失败的源文件>`，确保仓库回到可构建状态 +2. **验证回退成功**：`cmake --build build --config Release` 必须 0 error +3. **定位根因**：确认失败属于执行错误（execution error）还是设计错误（design error） +4. **按分级表处理**： + +| 失败类型 | 判定标准 | 回退目标 | 后续动作 | +|----------|----------|----------|----------| +| E1 执行错误 | 编译警告/错误可定位到具体行，修复不涉及接口变更 | EXECUTE | 原执行者修复（1 次机会），CEO 复核 | +| E2 执行错误（重复） | 同一执行者同类错误第 2 次出现 | EXECUTE | 换人执行（同专长其他员工） | +| D1 设计错误 | 接口不兼容 / 架构假设错误 / 需改公共头文件 | OPTIMIZE | 提案方重新设计，走完整 VOTE→INTEGRATE→EXECUTE | +| D2 设计错误（严重） | 需回退 >3 个文件 OR 涉及 ABI 变更 | ROLLBACK | 回退后 CEO 重新 PROPOSE，缩小任务范围 | +| F1 致命 | 数据损坏 / 安全漏洞 / .git 异常 | ROLLBACK | 回退 + security-cao 审计 + CEO 决定是否 ABORT | + +### 13.6 ROLLBACK 协议（强制步骤） + +当触发 ROLLBACK 时，按以下步骤强制执行，**不可跳过任何一步**： + +1. `git status` → 记录当前所有改动文件列表 +2. `git checkout -- <触发失败的所有文件>` → 回退触发改动的文件 +3. `cmake --build build --config Release` → 确认回退后构建 0 error +4. `ctest -R smoke --test-dir build` → 确认回退后测试 100% pass +5. 在 WORKFLOW.md §7 记录：回退原因、触发文件列表、决策（重做 / 缩小范围 / 放弃） +6. CEO 根据 §13.5 分级表选择后续路径（重新 EXECUTE / 重新 PROPOSE / ABORT） + +### 13.7 ABORT 协议（强制步骤） + +当触发 ABORT 时，按以下步骤强制执行： + +1. 在 WORKFLOW.md §7 记录：中止原因、时间、影响范围 +2. 决定改动处置：保留（`git stash`）或丢弃（`git checkout`） +3. 本波 W 编号标记为 ABORTED，下一波使用新编号 +4. 相关执行者 profile.md performance_log 仍追加条目（rating: aborted），保留参与记录 \ No newline at end of file diff --git a/agents/architect-yang/profile.md b/agents/architect-yang/profile.md index a8e9d47..17ee6a9 100644 --- a/agents/architect-yang/profile.md +++ b/agents/architect-yang/profile.md @@ -19,6 +19,9 @@ weaknesses: performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" - rating: ongoing + rating: completed + - date: 2026-05-27 + event: "W10.1: 设计协作状态机 + 验收清单 + 失败回退协议，追加 WORKFLOW.md §11–§13" + rating: completed current_groups: [] --- diff --git a/agents/designer-zhu/profile.md b/agents/designer-zhu/profile.md index 11dd5ad..3fae6ba 100644 --- a/agents/designer-zhu/profile.md +++ b/agents/designer-zhu/profile.md @@ -21,5 +21,8 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W10.3: 创建 agents/PROMPT_TEMPLATE.md 子代理 prompt 模板（约 170 行），含骨架+6 反模式+1 正模式+CEO 4 步检查。统一字数 250 字，WORKFLOW.md §9 追加迁移链接" + rating: completed current_groups: [] --- diff --git a/agents/engineer-li/profile.md b/agents/engineer-li/profile.md index 902512a..ddb9b23 100644 --- a/agents/engineer-li/profile.md +++ b/agents/engineer-li/profile.md @@ -20,5 +20,8 @@ performance_log: - date: 2026-05-27 event: "入职 dstalk 团队" rating: ongoing + - date: 2026-05-27 + event: "W10.2: 创建 agents/STATUS.md 实时编制状态文档（63行），含员工状态表（16人）+ 工作组状态表（5组）+ Wave 进度，一次性读完 16 份 profile + 5 份 group + git log 后整理输出" + rating: completed current_groups: [] --- diff --git a/agents/qa-xu/profile.md b/agents/qa-xu/profile.md index 548e909..a19b150 100644 --- a/agents/qa-xu/profile.md +++ b/agents/qa-xu/profile.md @@ -24,5 +24,8 @@ performance_log: - date: 2026-05-27 event: "B3 三方案破坏性评审：否决 A3/B1/C2，上报恶意管道 OOM 路径" rating: good + - date: 2026-05-27 + event: "W10.4 创建 agents/POSTMORTEM.md 项目级踩坑记录（172行），收录 PM-001~PM-005 共5条事故7条防御性规则，覆盖 stale obj / Boost.JSON 链接 / 跨DLL堆释放 / plugin_loader fail-fast / push --force 未告知" + rating: completed current_groups: [] ---