Skip to content

Commit 7e0b602

Browse files
author
zhangtao
committed
docs(team): 新增多智能体协作 Playbook（项目专属部分）
只记录官方插件给不了的内容，避免与运行时注入的通用协作策略重复： - 前置：先探测当前会话可用工具再选档位（团队组合包与 subagent 互斥） - 两种队形：审计波（5–7 只读角色）/ 交付波（3–4 角色带质量门禁） - 本项目踩过的坑：inScope 逐文件、review 任务需显式 assignee、按文件边界切轨道 （官方无 confinement 与独立工作目录）、verify 先跑通、review≠验证、小改自己做 - 验证命令速查（pytest/ruff/basedpyright/vitest，类型检查前必须先构建） - 不可逆动作需人确认（部署/合并/推送/凭据） - 官方文档本地路径索引
1 parent 1e9e124 commit 7e0b602

1 file changed

Lines changed: 88 additions & 0 deletions

File tree

‎TEAM-PLAYBOOK.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# 多智能体协作 Playbook（FastapiAdmin）
2+
3+
> 本文件只记录**官方插件给不了**的部分。通用协作策略由 DSH 实验性 Agent Teams 运行时自动注入
4+
> （显式委派才建团队、共享 cwd、文件陈旧版本恢复、Bash/formatter/codegen 风险、task/write-scope 协调、
5+
> steer 投递、mailbox 不重发、Lead 必须先等待），此处不重复。
6+
7+
## 1. 前置：先确认工具，再选档位
8+
9+
「智能体团队」组合包（插件页开关）开启时，团队工具会**取代同名的旧 subagent 控件**；关闭后恢复
10+
`subagent` / `subagent_fork`。两者互斥，同一个开关同时控制工具与 Web 成员/任务板 UI。
11+
因此开工第一步是**看当前会话实际有哪些委派工具**，再决定档位：
12+
13+
| 档位 | 适用 | 反例 |
14+
| --- | --- | --- |
15+
| 单会话直接做 | 单文件、≤20 行、需求明确 | 需要跨域并行探索 |
16+
| `subagent` / `subagent_fork` | 独立小任务 / 需要本会话上下文 | 被团队组合包取代时不可用 |
17+
| `workflow` | 几十个互不依赖的同类单元 | 需要人工逐步在环 |
18+
| 团队（Agent Teams） | 多角色并行探索 + 质量门禁 + 可追溯 | 单文件；成员必然改同一批文件 |
19+
20+
判据：**任务能否切成互不重叠的单元**。能并行探索 → 用团队；只能串行改同一批文件 → 退回「1 实现 + 1 复核」。
21+
22+
## 2. 两种队形
23+
24+
### A. 审计波（只读，5–7 人）
25+
角色覆盖端/域：后端架构、前端、测试、安全、运维、产品、UX/UI。
26+
27+
- 每个成员一个 `kind=work` 任务，产出「文件:行号 + 证据 + 优先级」报告
28+
- 任务说明里写明：不得改代码、不得启动服务/装依赖、不得提交 git
29+
- Lead 汇总总报告，并**修正成员的错误表述**——成员结论是材料，不是结论
30+
31+
### B. 交付波（3–4 人，带质量门禁）
32+
`implementation`(+`repair`) → `review`(verdict=pass) → 必要时 `integration`。
33+
34+
- implementation 必须给全 `objective` / `acceptance` / `verify` / `inScope` / `outOfScope`；
35+
review 用 `reviewedTaskId` 指向被复核任务
36+
- 失败 review 会自动加 repair + 下一轮 review，**不要手工重建循环**
37+
- 跨端大改**分两波**：先审计波并归档，再起交付波
38+
39+
## 3. 本项目踩过的坑（版本相关，易复发）
40+
41+
1. **`inScope` 必须逐文件**：目录型条目在完成态校验里逐字匹配不上文件，成员将无法声明 `changedPaths`
42+
2. **quality/review 任务必须显式 `assignee`**：否则调度器可能把「复核后端代码生成」派给前端工程师
43+
3. **并行轨道按文件边界切**：两个任务碰同一文件 = 强制串行。官方不提供 confinement、也不支持独立工作目录
44+
（既不会拦重叠写，也不会做 worktree 隔离），所以这是唯一防线
45+
4. **`verify` 命令先在本地跑通**；`acceptance` 不得引用不存在的基础（例：仓库里没有的「既有 401/403 用例」）
46+
5. **review 通过 ≠ 已验证**：门禁之外保留独立验证（类型检查/测试/线上实测至少两项）；
47+
复核者要用对抗手段（绕过校验层构造脏数据、原始载荷重放）
48+
6. **机械小改（≤20 行、单文件）自己动手**，不要开 implementation+review 两轮
49+
50+
## 4. 验证命令
51+
52+
```bash
53+
# 后端
54+
cd backend && UV_CACHE_DIR=/tmp/uv-cache-test uv run --no-sync pytest -q
55+
cd backend && UV_CACHE_DIR=/tmp/uv-cache-test uv run --no-sync ruff check
56+
cd backend && uv run --with basedpyright basedpyright # 配置：backend/pyrightconfig.json
57+
# 前端
58+
cd frontend/web && pnpm run type-check && pnpm run test
59+
cd frontend/app && pnpm run type-check
60+
```
61+
62+
注意：`frontend/web/src/types/*.d.ts` 由 unplugin-* 在 vite 运行时生成且**不入库**，
63+
所以**类型检查前必须先构建**（`pnpm run build:prod`）——CI 里已按此顺序执行。
64+
65+
## 5. 不可逆动作（必须人确认）
66+
67+
部署、合并到 master、推送远端、轮换凭据、删除团队。
68+
69+
- 部署只走 `./deploy-artifacts.sh`（本机构建成品 → 服务器只收镜像与静态产物；服务器无源码、无构建）
70+
- 推送只推 `origin`（GitHub）；gitee 由 GitHub 同步，不由本地推
71+
- 凭据不进仓库（含文档与示例）；改口令用服务器上的 `/root/fa-set-password.sh`
72+
73+
## 6. 收尾
74+
75+
1. 必需任务全部终态、成员 idle；未完成工作不得丢弃（先问用户）
76+
2. 逐条核对成员交接（`changedPaths` / `commandsRun` / `acceptanceResults`），关键命令自己复跑
77+
3. 交付物落入仓库并提交（走 dev → master PR）
78+
4. 归档团队，并向用户说明覆盖缺口与残余项
79+
80+
## 7. 参考：官方文档在本地
81+
82+
```
83+
…/app.asar.unpacked/node_modules/@deepseek-ai/
84+
dsh-experimental-agent-team/README.zh.md # 领域服务：roster / mailbox / 任务板 / 持久性
85+
dsh-experimental-agent-team-profile/README.zh.md # 组合包：插件页开关、限额（maxMembers=8 等）
86+
dsh-experimental-tool-agent-team/README.zh.md # 9 个工具与内建共享策略
87+
dsh-experimental-client-ui-agent-team/README.zh.md# Web 成员列表 / 任务看板
88+
```

0 commit comments

Comments
 (0)