dsh-swarm
> 自主团队协作插件 v0.4.0：领队（Captain）自主拆分任务 → 常驻 Agent 分工执行 → 工件引用传递省 Token → 任务账本看门狗保交付
核心能力
- 常驻 Agent：每个 Agent 是一个独立 Node.js 进程（
agent-runtime.js），循环「读 inbox → 跑任务 → 写 outbox」，无需每次冷启动 - 独立 API：每个 Agent 独立配置模型 / Provider / apiBaseUrl / apiKey（写入各自
state.json） - 工件引用传递（v0.4.0）：长产出自动落盘共享工件库，消息只传
art://<id>引用 + 200 字摘要，需要全文时按引用展开——大幅节省 Token - 任务账本 + 看门狗（v0.4.0）：任务状态机
pending → claimed → done/failed，失败自动重试（最多 3 次），claimed 超 5 分钟无进展自动重派——Agent 崩溃不再丢任务 - 可视化 UI：DSH 界面内置团队面板，可视化创建/删除空白 Agent、查看任务账本进度
- 内置联网：Agent 自带
web_search/web_fetch（jina.ai），无需额外插件
与 agent-teams 的区别
| 维度 | agent-teams | dsh-swarm |
|---|---|---|
| 队员形态 | 同进程 subagent | 独立常驻进程 + 独立 API |
| 结果传递 | 全文经主会话中转 | 工件引用 + 摘要，按需展开 |
| 失败处理 | 任务丢失 | 账本重试 + 看门狗自动重派 |
| 适用场景 | 简单委派 | 复杂多角色协作 / 长任务 |
安装
# 复制到本地插件目录
cp -r dsh-swarm ~/.dsh/local-plugins/dsh-swarm
# 同步到 desktop profile 副本（Windows 下 link: 不生效，是物理拷贝）
robocopy "local-plugins\dsh-swarm" "profiles\desktop\node_modules\dsh-swarm" /MIR
# 重启 DSH（引擎启动时自动加载）快速开始
1. 添加 Agent（对话中说，或在团队面板点「添加」）：
> 添加一个 Agent，ID 叫 researcher1，用 deepseek-chat，API 是 https://api.deepseek.com/v12. 组队干活（复杂任务时领队自动建队）：
> 帮我调研 X 框架和 Y 框架的优劣，写一份对比报告
→ 领队拆分 → researcher1 查资料 → researcher2 补充 → 汇总交付3. 看进度：团队面板实时显示 Agent 状态与任务账本（⏳pending 🔄claimed ✅done 💀dead）
工具列表（10 个）
用户工具
| 工具 | 说明 |
|---|---|
swarm_add_agent | 添加空白 Agent（指定 agent_id / model / provider / api_base_url / api_key） |
swarm_remove_agent | 删除 Agent，停止其进程 |
swarm_list_agents | 查看所有 Agent 状态与角色分配情况 |
Captain 工具
| 工具 | 说明 |
|---|---|
swarm_create_team | 组建团队：自动给空白 Agent 分配角色（researcher/coder/analyst/reviewer），启动进程 |
swarm_set_agent_prompt | 给 Agent 写角色提示词（内置 4 种模板或自定义全文） |
swarm_send_task | 派发任务：写 inbox → 轮询 outbox → 返回结果（长结果返回 art:// 引用） |
swarm_read_results | 非阻塞读取 Agent 已产出的结果 |
swarm_read_artifact | 按 art://<id> 引用展开工件全文（支持 max_chars 分段） |
swarm_status | 团队状态 + 任务账本（触发一次看门狗扫描） |
swarm_disband | 解散团队，停止所有 Agent 进程（不删除 Agent） |
架构
用户 / Captain（DSH 主会话）
│ swarm_add_agent / swarm_create_team / swarm_send_task
↓
┌─ Registry（~/.dsh/swarm/registry.json）
├─ 任务账本（~/.dsh/swarm/tasks/<teamId>/tasks.json）← 看门狗扫描（挂在 UI 轮询心跳上）
└─ 共享工件库（~/.dsh/swarm/artifacts/<sha1>.json，7 天 TTL）
↓ inbox/outbox（JSONL 文件信箱）
┌────────────┬────────────┬────────────┐
│ agent A │ agent B │ agent C │ ← 各自独立 Node.js 常驻进程
│ researcher │ coder │ analyst │ 各自独立模型/API
│ state.json │ state.json │ state.json │
└────────────┴────────────┴────────────┘
↓ 长产出
工件库 art://a1b2c3d4（全文落盘，消息只传引用+摘要）数据流（一次任务的生命周期）：
1. Captain 调 swarm_send_task → 账本记 pending → 投递 inbox → 标 claimed 2. Agent 进程轮询到任务 → 调 LLM（可带 web_search 工具循环）→ 产出 3. 产出 >800 字符 → 落盘工件库 → outbox 只写 {resultRef, summary, size} 4. Captain 轮询到结果 → 账本记 done → 返回引用+摘要给 Captain 5. Captain 需要全文 → swarm_read_artifact 展开 6. 异常路径：API 报错/超时 → 账本 failed → 自动 requeue → 看门狗重投 inbox；重试 3 次仍失败 → dead 留痕
角色模板
| 角色 | 职责 | 触发关键词（Agent ID） |
|---|---|---|
| researcher | 搜索、收集、整理资料 | research / search |
| coder | 写代码、调试、执行命令 | coder / dev / engineer |
| analyst | 数据分析、报告撰写 | analyst / data |
| reviewer | 代码审查、质量把关 | review / check |
空白 Agent 在 swarm_create_team 时按 ID 关键词自动匹配，也可用 swarm_set_agent_prompt 手动指定。
Web UI
插件注册两个 HTTP 端点（dsh-host-webserver）：
GET /__dsh_swarm__/state.json— Agent 快照 + 团队 + 任务账本（客户端 2 秒轮询，同时驱动看门狗心跳）POST /__dsh_swarm__/agents— 创建/删除 Agent（{action: "add"|"remove", ...}）
致谢
本插件参考了以下 MIT 开源项目的架构与接口模式：
- @nanmicoder/dsh-agent-teams — 客户端 UI 面板、webServer 路由模式
- DSH-better-sidebar — 侧边栏/悬浮面板 UI 模式
- @deepseek-ai/dsh-bridge-browser — 工具注册与 TEXT_OUTPUT 模式
- @liustack/modlens — 识图插件集成参考
v0.4.0 的工件引用传递与任务账本看门狗设计思想来自 CogniLink 类多 Agent 系统的共享语义内存与契约式协商理念的简化落地。
License
MIT