前言¶
在 DeepSeek Harness (DSH) 的生态中，通过多个智能体协作处理复杂任务时，常面临角色漂移、交接过程无法验证以及死锁等问题。dsh-swarm 是一个 DSH 插件，旨在将这些协作转化为严格的、有证据验证的交付管线。它将一个需求转化为一个严格排序的阶段链，由六个专职角色分别执行，并通过可视化的看板提供实时状态与交付证据。
安装与前置条件¶
该插件由 joekytc 维护，遵循 MIT 许可证。安装前请确保环境满足以下要求：
- DSH 运行时：
@deepseek-ai/*系列 - Node.js 版本：≥ 22.19
- npm 包管理器
安装命令如下：
dsh plugin --profile web add @joekytc/dsh-swarm
如果从源码安装，需先执行构建：
npm install
npm run build
dsh plugin --profile web add .
核心功能¶
dsh-swarm 提供了一套完整的流程控制机制，核心特性包括：
- 蜂群模式（推荐）：主会话转化为只读的“团队负责人”，通过自然语言接收需求、澄清、规划和执行。
- 自动意图识别：根据自然语言输入判断意图（开发请求、复盘、群通知或闲聊），无需记忆特定命令前缀。
- 确认门控：在管线启动前，系统会保存检查清单，需用户回复明确确认词（如“确认”、“开干”、“go”等）后才会开始执行，防止误触。
- 可视化看板：通过 Conversation -> Trajectory -> Kanban 路径，实时流式展示管线状态。
- 机器验证的证据：每个阶段交接均需携带结构化证据，完成后的交付经过机器验证。
- 权限隔离：编排器（Lead）为只读，无法直接操作仓库源码或执行 git 变更，代码编写由执行者（D）在隔离工作区完成。
角色与流程¶
系统定义了六个单职责任的角色，通过权限矩阵和工具面限制，确保职责边界清晰。管线流程为：p -> (pt?) -> w2 -> d -> dt -> w3 -> summary。
| 角色 | 职责 | 禁止操作 |
|---|---|---|
| V (Orchestrator) | 创建阶段卡片，驱动管线，处理阻塞 | 执行 |
| P (Planner) | 读取规范与仓库事实，编写实施计划 | 写代码 |
| PT (Plan Reviewer) | 仅对 P 的计划进行只读审查 | 修改 |
| W (Knowledge Officer) | 在规划与完成阶段同步知识库 | 触碰代码/Git |
| D (Executor) | 唯一编写代码的角色，实施、验证、提交功能分支 | 合并到目标分支 |
| DT (Implementation Reviewer) | 依据测试、构建、类型检查或 Diff 验证 D 的交付 | 对仓库只读 |
使用方法¶
使用蜂群模式时，交互流程如下：
- 陈述需求：直接用自然语言描述需求，例如：“为管理后台添加一个角色管理页面，包含 CRUD 和权限复选框”。
- 确认执行：编排器会进行澄清（如字段定义、权限来源等），列出检查清单。用户回复“确认”或“开干”后，管线启动。
- 实时查询：任何时候询问“进展如何？”，编排器会从看板中查询真实状态并反馈，而非编造回复。
- 交付通知：完成后，可使用
/sms意图进行交付（如“将当前进度发到群里”），系统会基于看板事实生成汇报内容。
注意事项¶
- 权限限制：主会话（Lead）角色被设计为只读，不能修改仓库源码或运行 git mutations（如 push/commit）。代码提交由 D 角色完成。
- 完成门槛：管线完成需要经过审计确认。对于 D 链路，系统会自动合并功能分支，但需在 GUI 中确认所有权后才会执行最终收尾，审计警告会阻塞最终打包。
- 环境依赖：确保 DSH 运行时、Node.js 和 npm 版本符合要求。
