dteam

半自动多角色编排引擎，作为 Pi 扩展运行。

v1 状态：信号通路 + 后台运行 + 链式/team 模式落地，16 个测试文件通过，重构完成（orchestrator 562→197 行）。

v0.4.2（当前版本）重点：把 dteam 收敛成稳定的后台任务系统——run 只返回 runId（任务编号），实时进度主要看 /dteam 面板，完成后再向主对话发送结果消息。

一句话

dteam 把"派一个 worker 干一件事"做成一棵二维编排的 worker 树——组织形式（solo / chain / team）× 执行策略（direct / build_check / adaptive），每个 step 选 5 个角色之一（explore / design / build / check / close）执行。

叶子之间通过 4 种信号（progress/found/blocked/help）实时通信，根自动收集并转发、注入上下文，整棵 worker 树自协调。

快速开始

# 1. 安装依赖
npm install

# 2. 编译
npm run build

# 3. 运行测试
npm test

# 4. 安装到 Pi
pi install "$(pwd)"

# 5. 在 Pi 里按 /reload 重载

# 6. 调 dteam 工具
# 后台执行：dteam(action="run", goal="你的目标")
# 用户回复继续：dteam(action="continue", runId="...", message="你的回复")

# 7. /dteam 命令
# 在 Pi 里输 /dteam 打开实时进度面板

用法

工具 API

dteam 暴露 1 个工具，2 个 action：

// 后台启动（立即返回，不阻塞前台）
dteam(action="run", goal="你的目标")
// → { status: "running", runId: "run-xxx" }

// 人类回复后继续（叶子在等人类输入时）
dteam(action="continue", runId="run-xxx", message="你的回复")
// → { content: "已注入到 run-xxx" }

后台任务模型（v0.4.1）

dteam(action="run") 现在明确采用后台任务模式：

1. 启动时立即返回 runId
2. 后台继续执行，不阻塞主对话
3. 实时进度主要看 /dteam 面板 / widget（小组件）/ status（状态栏）
4. 完成后通过 dteam-report（结果报告）消息回到主对话
5. 不再依赖已结束工具调用的 onUpdate（流式更新回调）推送后台进度

/dteam 命令

在 Pi 里输入 /dteam：

• 第一次：打开面板（实时显示 worker 进度、信号、策略记录）
• 第二次：关闭面板

4 种信号

叶子在跑过程中可以发信号上报：

信号	何时发	根的行为
progress	完成一个动作/步骤	UI 更新 + 转发给其他正在跑的叶子
found	发现计划外信息	UI 更新 + 转发 + 链式注入到下一步
blocked	已停住/失败	UI 更新 + step 标记 failed
help	自己解决不了	第 1 次：派 explore 收集补充第 2 次：升级到人类，等 dteam(continue)

工具名 worker_sendSignal（已注入到所有 worker 角色）。

文档

当前仓库建议按 4 层理解：index.ts + src/ + agents/ 是运行核心，tests/ 是验证层，doc/ 是当前说明层，archive/ 是历史归档层。重构时优先修改运行核心与当前说明，避免直接从归档倒推实现。

• 设计文档总览
• 系统架构（二维编排模型）
• 角色系统（5 个角色职责）
• 工具 API 参考
• v2 设计与实施现状
• 项目路线图
• v0.4.1 后台任务稳定性实施方案
• Agent Teams 借鉴实施方案
• 工具动态加载方案
• src/ 内部架构
• CHANGELOG.md

目录结构

.
├── index.ts                 # Pi 扩展入口（注册 dteam 工具 + /dteam 命令）
├── src/
│   ├── orchestrator.ts     # 编排主入口（197 行：plan → execute → report）
│   ├── planner.ts          # Phase 1: 规则判断 + LLM 兜底生成 ExecutionPlan
│   ├── leaf.ts             # Phase 2: 用角色调 LLM 执行（thin coordinator）
│   ├── pool.ts             # 任务池（write/claimNext/update/getAll/read/search/list/complete）
│   ├── session.ts          # createWorkerSession 工厂（78 行 thin coordinator）
│   ├── tools.ts            # 类型中心（编排/角色/ADR 类型 + re-export 4 类 types/*）
│   ├── reference-data.ts   # reference_architecture 工具（12 模式 + ADR 模板）
│   ├── reporter.ts         # Reporter 接口 + defaultReporter（业务/UI 解耦）
│   ├── config.ts           # DTEAM_CONFIG 集中常量
│   ├── signals/            # 信号系统
│   │   ├── index.ts        # 统一导出
│   │   ├── signal-bus.ts   # 内存 Map<workerId, Signal[]> + on() listener
│   │   └── runs-store.ts   # 内存 Map<runId, Map<workerId, WorkerRun>>
│   ├── types/              # 拆出的类型（4 文件）
│   │   ├── signal.ts       # SignalType + 4 payload + Signal
│   │   ├── run.ts          # WorkerRun + ISignalBus + IRunsStore
│   │   ├── role.ts         # RoleName
│   │   └── context.ts      # DteamContext
│   ├── ui/                 # UI 模块
│   │   ├── index.ts        # 统一导出
│   │   ├── store.ts        # UIStore 单例（workers/strategies/signals）
│   │   ├── panel.ts        # /dteam 面板（widget + overlay）
│   │   └── helpers.ts      # 状态/信号图标 + duration 格式化
│   ├── session/            # session.ts 拆 5 子文件
│   │   ├── resource-loader.ts
│   │   ├── role-config.ts
│   │   ├── role-prompt.ts
│   │   ├── model-resolver.ts
│   │   └── signal-tool.ts
│   ├── leaf/               # leaf.ts 拆 3 子文件
│   │   ├── worker-id.ts
│   │   ├── extract.ts
│   │   └── supplement.ts
│   └── orchestrator/       # orchestrator.ts 拆 7 子文件
│       ├── signal-handlers.ts
│       ├── help-self-heal.ts
│       ├── peer-forwarder.ts
│       ├── history-context.ts
│       └── strategies/
│           ├── direct.ts
│           ├── build-check.ts
│           ├── adaptive.ts
│           └── index.ts
├── agents/                 # 5 个角色定义（explore / design / build / check / close）
├── tests/                  # 16 个测试文件
├── doc/                    # 所有文档（中文名）
└── archive/                # v0 历史归档

业务能力

功能	状态	文档
4 种信号（progress/found/blocked/help）	✅	src/signals/signal-bus.ts
叶子 help → 根派 explore 自愈	✅	src/orchestrator/help-self-heal.ts
help 第 2 次 → 升级到人类 + 阻塞等回复	✅	src/index.ts action="continue"
后台运行（action="run" 立即返回 runId）	✅	src/index.ts
后台运行不再依赖 onUpdate（流式更新回调）	✅	index.ts
dteam-report 自动注入主对话（triggerTurn）	✅	src/index.ts
链式继承（前序发现自动注入到下一步 prompt）	✅	src/orchestrator/history-context.ts
实时转发（叶子发的 found/progress 自动转发到其他正在跑的叶子）	✅	src/orchestrator/peer-forwarder.ts
reference_architecture 工具（design 角色可用，12 模式 + ADR 模板）	✅	src/reference-data.ts
3 种 strategy（direct/build_check/adaptive）	✅	src/orchestrator/strategies/
/dteam 面板（实时信号 + 策略记录）	✅	src/ui/panel.ts

设计哲学

• 半自动：人通过 Pi 主对话用 dteam，dteam 不替你拍板
• 二维编排：组织形式（solo/chain/team）× 执行策略（direct/build_check/adaptive），9 种组合
• 5 个角色：explore / design / build / check / close，分工明确（build 唯一能改代码）
• 规则优先：planner 用规则判断（零 LLM 成本），复杂情况才调 LLM
• 信号驱动：叶子 → 4 种信号 → SignalBus → 根 listener → 实时响应（自愈/转发/链式）
• 后台不卡前台：dteam 工具立即返回，前台继续工作；完成后自动注入报告
• 人类在环：help 信号升级到人类，等用户回复后继续
• MiniMax-M3 优先：主模型找不到自动降级到 M2.7

验证状态

• ✅ v1 核心代码落地 + 重构完成（orchestrator 562→197，session 299→78）
• ✅ npm run build 通过
• ✅ npm test 可作为当前单元测试基线
• ✅ 4 个真实任务实测通过（solo/chain/team/adaptive 全部命中）
• ✅ 代码主干与历史归档已分层：运行核心 / 说明层 / 归档层边界清晰
• ✅ 信号通路实测通过（progress/found/blocked/help 都能在面板看到）
• ✅ 后台运行 + dteam-report 注入实测通过
• ⏳ 实时转发需更多 task 验证（单元测过）
• ⏳ v1.1：分支层（v2+）

相关链接

• v0 历史归档：archive/v0-pre-rewrite/README-archive.md
• Pi 扩展开发：https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/doc/extensions.md