前言¶

Agent Teams 有一批官方 README 没写、踩过才知道的约束：名册只增不减，名额不可回收；interrupt 不释放成员；写作用域只是提示不是锁；队友默认是 fresh context，看不到你的历史；没有活跃队友时 wait_agent 会立即返回而不是等待。这些约束的共性是：出错时没有报错，只有行为异常，堆栈里找不到原因。

dsh-agent-team-playbook 是 elfgzp 维护的非官方插件，分类工作流。它不改运行时，而是把这些约束写成六条守则，注册成有序的系统提示段落注入每个 agent，让接管 Team 的 agent 在动手前就知道哪些路走不通。下面介绍它的能力、安装步骤和实战细节。

这是什么¶

一句话：一个纯提示注入的 bundle，把 Agent Teams 的操作规则放进 system prompt，而不是新增工具或改变运行时行为。事实依据上游 tag dsh-v0.2.1-rc.3 源码核验；非官方，与 deepseek-ai 无隶属关系。

插件本体很小，打包只含四个运行时文件：lib/index.js、cordis.patch.yml、locale/{zh,en}.json、icon.svg。docs/ 与 examples/ 是随仓库分发的文档，不参与打包。

它做了什么¶

插件注册一个有序系统提示段落 team-playbook:rules，order 650，为每个 agent 注入六条规则：

650 这个位置紧接上游 TEAM_POLICY(600) 之后、PTC_ONLY(800) 之前，读起来是 Team 策略的延续，不会割裂后续工具段落。

它不做什么¶

明确边界，避免误期待：

• 不新增任何工具，纯提示注入，不改 Team 运行时行为。
• 不强制任何流程，软状态标签、写作用域重叠仍然只是提示。
• 不做 UI，没有 client 半边，不加面板或按钮。
• 不修改上游源码，依赖 @deepseek-ai/dsh-experimental-agent-team 原样工作。

安装与启用¶

环境要求¶

DeepSeek Harness >=0.2.1-rc.3 <0.3.0，已实测 0.2.1-rc.3、0.2.1-rc.5。版本约束写在 package.json 的 peerDependencies，DSH 安装时会据此校验。区间写法对 0.2.1-rc.x 与 0.2.x 正式版都成立；0.2.2-alpha.x 这类预发布版按 semver 默认不匹配，遇到时需自行确认 API 未变再放宽。

从本地目录安装¶

先 clone 到持久目录（不要用 /tmp），再 pnpm install –prod，然后自检，最后用 plugin_manager 的 install_bundle 安装。这几步顺序不要调换：自检放在 install_bundle 之前，能让「依赖没装上」当场暴露；跳过自检的症状会变成 application: failed 加 ERR_MODULE_NOT_FOUND，且不提示真实原因，容易被误判成代码 bug。

cd ~/Work
git clone https://github.com/elfgzp/dsh-agent-team-playbook.git
cd dsh-agent-team-playbook

pnpm install --prod

node --input-type=module -e "const m=await import('./lib/index.js'); \
  console.log('deps OK', Object.keys(m), m.inject)"

上面这段是把仓库 clone 到持久目录、装依赖并自检，期望输出 deps OK [ ‘Config’, ‘apply’, ‘inject’ ] [ ‘systemPrompt’, ‘agents’ ]。这一步不依赖 DSH 运行时，只确认插件自己的依赖解析正常。

{
  "action": "install_bundle",
  "target": "/absolute/path/to/dsh-agent-team-playbook"
}

这一段用 plugin_manager 从本地目录安装。安装后在插件详情里应看到标题「Agent Teams 操作守则」与对应描述（来自 locale/*.json）；已有会话的 agent 会立即生效，新创建的 teammate 也会自动获得该段落。卸载用 remove_bundle，或在 set_bundle 里禁用。替换已安装包需要重启，因为要加载新的 JS 模块代际。

三个容易踩的坑¶

上层目录的 pnpm-workspace.yaml。如果 ~ 或 ~/Work 存在该文件，pnpm 会把那个目录认作 workspace 根，在子目录执行 install 时输出 No projects found，什么都不装且退出码是 0，&& 链和 CI 都不会报错。解法之一是 pnpm install –prod –ignore-workspace。注意 –ignore-workspace-root-check 不是这个场景的选项，pnpm 会直接报 Unknown option。

源目录不能删。link: 协议只登记指向该目录的链接，不复制文件。删掉或移动 checkout，下次启动插件失效，报错是 application: failed，且不会提示「源目录已消失」。

不要跳过 pnpm install。本地目录通过 link: 安装时，依赖从插件自己的目录解析，且不会自动装 peerDependencies，必须靠 pnpm install –prod 才能让 lib/index.js 找到它们。

验证是否生效¶

提示注入插件没有按钮可点，需要从提示内容反查：

1. 查已注册段落：调用 Config 的 listConfigs，input.name 填 dsh-agent-team-playbook。
2. 看插件行的 application 字段：applied 才算真正激活；overridden 表示被更高优先级层覆盖，restart-required 表示尚未生效。
3. 会话里端到端确认：新开会话后让 agent 复述「Agent Teams 有几条操作规则」，应答出上表六条。

需要说明的限制：段落已注册不等于用户一定看到预期文本，渲染效果取决于提示组装，本仓库不含自动化断言。

实战细节：什么时候该用 Team¶

Agent Teams 有固定成本（名额不可回收、消息开销、共享 cwd 的写冲突风险），不是免费的并行，所以先做判断，再召人。

任务能否拆成 2+ 个互不依赖、可并行的子问题？如果是，再看子问题之间是否需要共享决策或中途对齐：不需要就各自独立跑完再汇总，Team 是好选择；需要连续高频对齐就消息开销大于并行收益，改用单 agent 串行；只在关键节点对齐则 Team 可行，用共享任务板表达依赖，而不是消息轰炸。

额外否决条件，任一命中就不要用 Team：子任务会写同一批文件；子任务需要跑同一份构建或测试且互相干扰；任务总量小到协调成本占主导；已经用满名额且无可复用的闲置成员。

名额与角色，这是最容易踩的坑。默认上限 16 个 teammate，当前 profile 配置为 8 个；lead 不计入该上限；state.members 数组里只有 teammate；名册没有删除机制，名额不可回收；名字全会话唯一。所以先规划 roster，再召人。

写作用域是提示不是锁。重叠只报 warning，不阻止写入，没有文件锁，并发必须按目录切分；多个 agent 改同一个文件必然冲突。

派活与顺序。队友默认 fresh context，所以派活必须自带完整上下文。blocked_by 是唯一强制的顺序机制，文本状态标签不可强制、不可筛选。

状态解读与报告。inactive 不等于完成，send_message 成功不等于对方已处理；只报告已验证的结果，不能因为队友说成功就认为成功。

配置¶

适用场景与注意事项¶

适合：多角度调研最后汇总成文档、按目录切分的大规模机械改造、一边调研一边实现并用任务板表达阶段依赖、对抗式验证。不适合：单个 bug 的诊断修复、需要频繁对齐的设计工作、多个 agent 改同一个文件、需要精确顺序的数据库迁移。

插件以当前 DSH 进程权限运行，且不新增工具、不改运行时行为。安装前应检查仓库源码与许可证：package.json 标注 license MIT，版本 0.1.0，packageManager 为 pnpm@10.32.1。

结尾¶

这个插件的价值不在于加新能力，而在于把踩坑成本前置：在 agent 动手之前，把「名额不可回收」「写作用域是提示不是锁」「队友是 fresh context」这些没有报错的约束说清楚。规则只有六条，约束的却是 Agent Teams 最容易出问题的地方。

• 目录页：https://www.skillhub.cn/plugins/elfgzp/dsh-agent-team-playbook
• GitHub：https://github.com/elfgzp/dsh-agent-team-playbook