dsh-agent-hub

Readme

# 智能体协作台 · dsh-agent-hub

> 群聊式多智能体协作控制台 —— 一个群,就是一支可以**自主决策、分工执行、验证返工、迭代优化**的 AI 团队。

![npm version](https://img.shields.io/npm/v/dsh-agent-hub) ![license](https://img.shields.io/npm/l/dsh-agent-hub) ![npm](https://img.shields.io/npm/dt/dsh-agent-hub)

**dsh-agent-hub** 是 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的内嵌插件:把多 Agent 协作组织成一个**群聊房间**——需求进群,交付出群;中间的过程(拆解、派单、执行、验收、沉淀)全部发生在群消息流上,全程可见、可追溯、可随时介入。

安装即用:内置后端随插件分发(自动探测、自动装依赖、无窗口静默运行),**零外部服务依赖、零 npm 运行时依赖**。

---

## 特性

### 🧠 群聊即自主决策
- **统筹大脑**:把任意成员「设为大脑」,大脑按 **决策 → 分派 → 收齐 → 验收 → 沉淀 → 下一轮** 的状态机自主推进;
- **四问决策**:每轮显式回答"目标?现状?可用成员?完成定义(DoD)?",输出结构化 JSON(plan / dispatch / status / memory),杜绝空泛;
- **自动批准持续任务**:授权后大脑无需逐轮人工确认,自主策动任务按轮次进行,直到交付或触及熔断;
- **全局协作章程**(System Charter):角色边界、原子任务、SMART、验收规范,随包分发、可热编辑,每轮注入给大脑与所有成员。

### 📤 多 Agent 任务分发与执行
- **`@成员` 定向派单**,输入时自动弹出成员列表一键选择;
- **原子任务拆分**:一个成员 = 一个原子任务 = 一个交付物 + 一条验收标准;依赖排序、无依赖并行;
- **OpenAI 兼容 API 成员**:填 `base_url / api_key / model` 即可接入任意 OpenAI 兼容模型(DeepSeek / 通义 / Kimi / GPT 等),可混合多个不同模型成员;
- 成果实时回流群消息,阻塞按"卡点 + 已尝试方案 + 需要的帮助"结构化上报。

### ✅ 验证与返工闭环
- 逐条核对验收标准,以**可复现**为最终判据;
- 不合格 → **一次性精确到点的返工清单**,不模糊批评;
- 通过 → 写入**群记忆**,宣布完成;回归问题按新任务重派。

### 🔁 自主优化与长任务
- **群记忆**跨轮次、跨任务持久复用——群是有记忆、会成长的团队;
- 多轮自主迭代:需求 → 方案 → 拆分 → 并行开发 → 集成 → 验收 → 返工 → 复验 → 沉淀 → 下一阶段;
- 三重熔断兜底:最大轮次、单轮超时、人类随时「叫停」/「否决」。

---

## 工作原理

```
┌────────────────────────────── 智能体协作台 ──────────────────────────────┐
│  群聊房间(消息即协作总线)                                                  │
│   ├─ 人类 Owner:需求来源 / 验收裁判 / 随时介入                             │
│   ├─ 统筹大脑:拆解、分工、监督、验收、沉淀(每轮 JSON 决策)                  │
│   └─ 执行成员:OpenAI 兼容 API 成员(@派单、成果回流)                        │
│                                                                           │
│  内置后端(随插件分发):房间 / 成员 / 消息 / 审批 / 任务 / 群记忆            │
│  - 自动探测端口,已有后端自动复用;缺失则 pythonw 无窗口自动拉起              │
│  - 首次自动建 venv + 装依赖;随 DSH 启停、自愈重启                          │
└───────────────────────────────────────────────────────────────────────────┘
```

- **群 = 工作流容器**:每一次协作流程(从目标到可验收交付)都被组织成一次"群内运行";
- **消息 = 状态机输入**:每一条指令、每一条成员回复,都是大脑下一轮决策的依据;
- **章程 = 协作宪法**:约束所有智能体的角色边界与质量标准。

---

## 安装

> 需要 **DeepSeek Harness** 且带 Web profile。推荐 Python 3.10+(内置后端需要;未安装时会显示引导页)。

### 一条命令(推荐,自动挂载)

```sh
dsh plugin --profile <你的profile名> add dsh-agent-hub
```

> 包声明了 `dsh.bundle` manifest,安装后**自动加入 profile 插件层**,无需手动改配置。

### 手动安装

1. 把包放入 `%USERPROFILE%\.dsh\profiles\node_modules\dsh-agent-hub\`;
2. 编辑 `%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml`:

```yaml
- insert:
    - id: dsh-agent-hub
      name: 'dsh-agent-hub'
```

3. 重启 DSH。

### 重启后

左侧边栏底部出现「**智能体协作台**」按钮,点击进入控制台;全新用户打开是欢迎页(附使用指引),无任何预置数据。

---

## 快速开始

1. **建群**:控制台内创建第一个群(或直接用欢迎页的"创建群");
2. **邀请成员**:右侧成员栏「邀请成员」→ 填 `base_url / api_key / model` → 添加成员(OpenAI 兼容 API);
3. **设大脑**:把某成员点「设为大脑」;
4. **发任务**:
   - `@成员名` + 发送 → 定向派单;
   - 「发给大脑」→ 把整个需求交给大脑,自主拆解、分工、监督、验收;
   - 勾选「**自动批准持续任务**」→ 大脑每轮无需人工确认,持续推进;
5. **验收与沉淀**:大脑逐轮核对交付,不合格打回返工,通过后写入群记忆;随时可「叫停」或逐轮「确认/否决」。

---

## 使用场景

| 场景 | 群内协作方式 |
|---|---|
| 完整项目开发(0 → 1) | 需求 → 大脑拆模块 → 多成员并行开发 → 集成 → 逐项验收 → 返工 → 交付 |
| 技术方案选型与实现 | 大脑组织方案对比 → 成员各自调研 → 交叉验证 → 定案 → 落地 |
| 代码审查与修复 | 成员产出 → 大脑按验收标准审查 → 一次性返工清单 → 复验 |
| 批量调研 / 文档撰写 | 并行分派 → 汇总交叉核对 → 成稿 → 按章节验收 |
| 持续优化迭代 | 基于群记忆与反馈,自主发起下一轮改进,直至达标 |

---

## 配置

| 项 | 说明 | 默认 |
|---|---|---|
| 环境变量 `TRD_BASE` | 后端地址(host 与内置后端均读取) | `http://127.0.0.1:8000` |
| 环境变量 `TRD_HOST` / `TRD_PORT` | 内置后端监听(仅内置启动器读取) | `127.0.0.1` / `8000` |
| 内置后端数据目录 | 自动创建于插件 `backend/data/`(SQLite) | — |
| 全局协作章程 | `backend/charter.txt`,运行中可直接编辑、热生效 | 内置章程 |

**说明**:本机已有 TRD/后端在 `TRD_BASE` 运行时,插件自动复用,不会重复启动;缺失时才会用 pythonw 无窗口拉起内置后端。

---

## 常见问题

| 问题 | 处理 |
|---|---|
| 打开控制台提示"正在启动后端 / 首次安装指引" | 首次会自动建 venv + 装依赖(1-2 分钟);缺 Python 时按引导安装 3.10+ |
| 后端未就绪时面板一直转 | 检查 `backend/data/` 权限、端口占用;控制台有「刷新重试」 |
| 会弹出 CMD 窗口? | 不会。0.1.4 起 uvicorn 全程用 `pythonw.exe + CREATE_NO_WINDOW`,物理上无控制台窗口 |
| 群数据存哪里 | 内置后端的 `backend/data/trd.db`(SQLite);卸载/重装插件不会删除它 |
| 如何彻底重置 | 停止 DSH → 删除 `backend/data/` → 重启(新群全新开始) |

---

## 开发与发布

```sh
# 本地开发:插件源码在 lib/(host=index.js / client=client.js)+ backend/(内置 Python 后端)
# 改版本并发布
npm version patch        # 0.1.x → 0.1.x+1
npm publish              # 发布到 npm(需登录 + bypass-2FA 颗粒令牌)
git push                 # 同步 GitHub 仓库
gh release create v0.1.x # 打 Release(可挂 tarball)
```

- 仓库:https://github.com/jax629321/dsh-agent-hub
- npm:https://www.npmjs.com/package/dsh-agent-hub
- 功能特色介绍(中文):[FEATURES.zh.md](FEATURES.zh.md)

---

## 许可证

[MIT](LICENSE)

> ⚠️ 插件运行第三方 Agent 代码,请在使用前审阅源码;本项目按 MIT 提供,不含任何担保。