YansIlinta/dsh-agent-groups

DSH Agent Groups

Long-running AI teams, natively inside DeepSeek Harness.
让 Claude、Codex 与 DSH Agent 不再只是一次性子任务，而是可以持续协作的长期队友。

CI
License
GitHub stars
TypeScript
Node.js
DeepSeek Harness

快速开始 · 核心能力 · 运行时模型 · 文档 · Architecture

项目简介

DSH Agent Groups 是一个运行在 DeepSeek Harness 内部的多 Agent 协作工作区。

它关注的是让 Coding Agent 在同一个 Group 中拥有持续存在的身份、运行时会话、任务历史和共享工作上下文。Leader 可以把工作派发给 DSH Agent 或任意已配置的 ACP Coding Agent，并在后续继续追问、复用同一个会话。

项目通过 DSH / Cordis 的扩展能力接入，不修改或复制 DeepSeek Harness 源码；Agent Groups 直接出现在原生 DSH shell 中。

User
│
▼
Leader ───────── mission / planning / assignment / verification
│
├── DSH Member    ── persistent DSH session
├── Codex Member  ── codex-acp session
├── Claude Member ── claude-agent-acp session
└── Gemini Member ── native ACP session
│
▼
tasks · channel · workspace · notes · artifacts · activity

[!NOTE]
Agent Groups 仍处于活跃开发阶段。。

它想解决什么

传统的多 Agent 编排很容易退化成：Leader 发出一个 prompt，外部 Agent 运行一次，进程结束，然后把 stdout 当成“任务完成”。这对于长周期 coding workflow 并不够。

Agent Groups 把 Member、Runtime Session、Turn 与 Task 分开建模：

Group
└── Member
└── Runtime Session
├── Turn 1  ← Task A
├── Turn 2  ← Leader follow-up
├── Turn 3  ← correction / review feedback
└── Turn 4  ← Task B

因此同一个 Codex / Claude / DSH Member 可以持续工作：先实现功能，再接受 review，再修复，再继续接下一个相关任务。

核心能力

| 能力 | 说明 |
| --- | --- |
| 长期队友 | 一个 Group Member 持有自己的 runtime session，可跨多个任务继续同一段 provider conversation。 |
| 多运行时团队 | 同一团队可以混合 DeepSeek Harness 与 ACP-compatible Codex、Claude、Gemini 或自定义 Agent。 |
| Leader 编排 | Leader 负责拆解 mission、创建任务、分派成员、跟进结果、重新打开任务和最终验证。 |
| 持久化工作区 | Group、mission、task、消息、runtime metadata、notes、artifacts 与 activity 等状态进入持久层。 |
| DSH 原生界面 | Agent Groups 入口位于 DSH sidebar，并直接在 DSH shell 中渲染，不使用 iframe 或第二套应用壳。 |
| 明确的生命周期 | Process、session、turn 和 task 生命周期彼此区分；进程退出不会被静默等同为任务成功。 |
| 可继续的 Coding Agent | ACP session id 会持久化，并被后续任务、Leader follow-up、修正与 Host 重启继续复用。 |
| 通信边界 | Leader ↔ Member 私聊允许；Member ↔ Member 私聊在 host service 层被限制，而不是仅依赖 prompt 约束。 |
| 实时活动流 | Workspace 通过 API 与 SSE 展示任务、运行时和协作状态变化。 |

运行时模型

不同 provider 的会话机制并不一样，Agent Groups 在上层提供统一的 session / turn 语义，同时保留 provider 自己的 resume 与 steering 能力。

| Runtime | Session identity | 持续协作方式 |
| --- | --- | --- |
| DeepSeek Harness | DSH member session | 原生持久 Member；恢复时保留角色、模型与 reasoning 配置。 |
| Codex (ACP) | ACP session → Codex thread | 官方 codex-acp adapter 负责 App Server 翻译；Host 只使用协商后的 ACP 能力。 |
| Claude (ACP) | ACP session → Claude SDK session | 官方 claude-agent-acp adapter 负责 SDK lifecycle、permissions 与 resume。 |
| Gemini (ACP) | Gemini CLI ACP session | 直接启动 gemini --acp，没有 Gemini-specific Host 分支。 |

Runtime 层还负责归一化事件、中断、pending approval / input，以及 provider-specific resume 行为。更严格的生命周期与完成条件见 Architecture。

原生工作区

Agent Groups 通过 DSH client plugin system 注入：

- sidebar.footer.action：加入 Agent Groups 入口。
- shell.overlay：在保留 DSH shell、主题与导航的前提下承载完整工作区。
- DSH UI primitives 与 --dsw-alias- design tokens：尽可能复用 DSH 现有视觉体系。
- /groups/api/：提供工作区数据 API。
- /groups/api/events：通过 SSE 推送实时变化。

当前工作区包含：

Overview · Tasks · Team · Channel · Leader Chat · Workspace · Activity · Profiles · Team Configuration

实现说明见 Native UI。

快速开始

环境要求

- Node.js 20+（CI 使用 Node.js 22，推荐本地同样使用 22）
- 本地安装的 DeepSeek Harness
- Bash，用于 web profile 安装与 relaunch 脚本
- 可选：已认证的 codex，用于 Codex Member
- 可选：可用的 Claude / Claude Agent SDK 环境，用于 Claude Member

当前 CI 的 DSH 兼容目标为 DeepSeek Harness 0.1.0-rc.6。更新版本需要重新验证后再视为正式支持。

获取与构建

git clone https://github.com/YansIlinta/dsh-agent-groups.git
cd dsh-agent-groups

cd packages/host
npm install
cd ../..

npm run build
npm run typecheck
npm test

安装到 DSH Web Profile

npm run install-web-profile
npm run relaunch-web

安装脚本会构建 native client bundle，将 @dsh-agent-groups/host 安装到本地 DSH profile module tree，写入 group-leader / group-member presets，并把插件加入 web profile patch。

DSH 重启后，在原本的 Web UI sidebar 底部打开 Agent Groups 即可。

可通过 AGENT_GROUPS_ACP_AGENTS_JSON 注册自定义 ACP 命令；值为 definition 数组，例如 [{"id":"opencode","name":"OpenCode","command":"opencode","args":["acp"]}]。命令使用无 shell 的参数数组启动，env 只传给子进程，不进入持久记录或 UI。

也可把 ACP Registry 的 registry.json 放入 AGENT_GROUPS_ACP_REGISTRY_JSON，并用逗号分隔的 AGENT_GROUPS_ACP_REGISTRY_AGENTS 明确允许需要的 agent id。只有 allowlist 中、带固定版本 npx distribution 的条目会成为 acp-registry: runtime；浏览 Registry 本身不会执行或安装任何 agent。

基本使用流程

1. 启动或选择一个 Agent Group · Team Lead session。
2. 打开 Agent Groups，创建新的 Group。
3. 选择 team template、runtime，以及共享目录或每成员独立 Git worktree。
4. 输入整个团队要完成的 mission。
5. Leader 将 mission 拆成任务并分配给不同成员。
6. 在 Tasks、Team、Channel、Leader Chat、Workspace 和 Activity 中查看执行过程。
7. 对进行中的成员追加要求、排队后续任务、处理 approval / input，或在必要时 interrupt 当前 turn。
8. Leader 对完成声明进行验证，再决定是否结束 mission。

文档与开发

如果只是体验项目，README 到这里已经足够。协议、生命周期不变量和开发细节统一放在 docs/，避免首页变成实现日志。

| 文档 | 内容 |
| --- | --- |
| 文档索引 | 文档入口与阅读顺序。 |
| 架构 | Domain model、runtime/session lifecycle、completion rules 与 persistence invariants。 |
| ACP 重建报告 | 实现证据、测试结果、许可边界与剩余限制。 |
| 开发 | 本地开发、build/test、CI 与 DSH 集成方式。 |
| 原生 UI | DSH client slot、theme 与原生工作区接入。 |
| Codex App Server 协议 | Codex persistent runtime transport 的协议记录。 |
| 上游架构研究 | ACP、官方 adapters、DSH UI、Symphony、Kandev 的实证版本与复用边界。 |

从仓库根目录运行：

npm run build
npm run typecheck
npm test
npm run build:native

集成与耐久性验证脚本：

node scripts/verify-durability.mjs
node scripts/demo-v02.mjs

仓库结构

.
├── packages/
│   ├── host/                  # host services, tools, runtime adapters, API, native client
│   └── profiles/              # group-leader / group-member presets and profile fragments
├── scripts/                   # build, install, relaunch, demo, durability helpers
├── docs/                      # architecture, development and provider protocol notes
├── .github/workflows/         # CI
├── AGENTS.md                  # coding-agent rules and repository invariants
├── CONTRIBUTING.md            # contribution workflow
└── README.md                  # product entry point

packages/host/src/ 的主要边界：

src/
├── group-host.ts              # product/service facade + runtime coordination
├── group-service.ts           # durable group behavior
├── task-service.ts            # task lifecycle
├── channel-service.ts         # group communication
├── runtime/                   # DSH / Codex / Claude runtime abstractions
├── native-client/             # DSH-native Agent Groups workspace
├── web/                       # API + SSE
├── persistence.ts             # persistence setup
└── store.ts                   # durable storage layer

项目状态

目前重点不是继续增加更多 provider，而是加固长期运行能力：

- queued turn 在 host restart 后的完整恢复；
- active / queued task 状态保持无歧义；
- transient turn-start failure 后的确定性 retry；
- runtime / task 生命周期之间更严格的完成判定；
- 长周期团队执行下更可靠的恢复与审计。

版本演进与实现历史以 Git history、pull request、issue 和 release 为准，不在 README 中维护不断膨胀的 V0.x changelog。

Contributing

欢迎提交 Bug、runtime compatibility 结果、回归测试以及范围明确的 pull request。

涉及 runtime/session 语义的修改，请先阅读 AGENTS.md、CONTRIBUTING.md 与 Architecture。这些生命周期不变量属于产品行为的一部分，应由测试保护。

致谢

DSH Agent Groups 建立在这些工具与生态之上：

- DeepSeek Harness
- OpenAI Codex
- Anthropic Claude Agent SDK

感谢这些项目提供的 runtime、扩展接口和 agent tooling 基础。

License

本项目基于 MIT License 开源。