pi-dteam：轻量级多智能体编排系统的设计与实践

介绍 pi-dteam 项目，这是一个为 Pi 设计的轻量级多智能体编排扩展包，支持 solo、chain、team 三种执行模式，内置自适应并发控制和实时信号通信机制。

• 原作者/维护者：ssdiwu
• 来源平台：github
• 原始标题：pi-dteam
• 原始链接：https://github.com/ssdiwu/pi-dteam
• 来源发布时间/更新时间：2026-06-02T17:45:44Z

原作者与来源

• 原作者/维护者：ssdiwu
• 来源平台：github
• 原始标题：pi-dteam
• 原始链接：https://github.com/ssdiwu/pi-dteam
• 来源发布时间/更新时间：2026-06-02T17:45:44Z 原作者与来源\n\n- 原作者/维护者：ssdiwu\n- 来源平台：GitHub\n- 原始标题：pi-dteam\n- 原始链接：https://github.com/ssdiwu/pi-dteam\n- 来源发布时间/更新时间：2026-06-02T17:45:44Z\n\n项目概述\n\n在多智能体 AI 系统日益普及的今天，如何高效地编排多个智能体协同工作成为一个关键挑战。pi-dteam 是一个专为 Pi 设计的轻量级多智能体编排扩展包，它通过简洁而强大的抽象，让开发者能够轻松构建复杂的多智能体工作流。\n\n项目的核心理念是"平衡效率与效果"，通过三种执行模式（solo、chain、team）和六种执行角色（explore/design/build/deploy/check/close），为不同场景提供灵活的解决方案。\n\n核心概念解析\n\n任务（Task）\n\n任务是工作流的基本单元，采用 Markdown 格式描述。这种设计使得任务定义既人类可读，又便于程序解析。任务可以包含目标、上下文、约束条件等信息。\n\n工作者（Worker）\n\n工作者是执行单元，支持三种模式：\n\n- solo 模式：单角色执行，适合独立的原子任务\n- chain 模式：串行执行，多个智能体按顺序协作，前一个的输出作为后一个的输入\n- team 模式：并行执行，多个智能体同时工作，适合可以分解为独立子任务的场景\n\n角色（Roles）\n\n项目定义了六种标准执行角色，形成完整的任务生命周期：\n\n1. explore（探索者）：收集内外部信息，理解问题空间\n2. design（设计者）：评估需求，制定执行计划\n3. build（构建者）：执行计划，编写代码，更新文档，编写测试\n4. deploy（部署者）：构建、部署并验证发布\n5. check（审查者）：检查代码质量，验证结果\n6. close（收尾者）：整理、归档、记录经验教训，关闭任务\n\n默认执行链为：explore → design → build → check → close\n\n信号（Signals）\n\n信号是实时通信机制，支持 4 种信号类型 + 5 种策略，共 9 种通信模式。这让智能体之间能够动态协调，处理阻塞、进度报告、资源发现等场景。\n\n工具系统详解\n\n任务管理工具\n\n| 工具 | 功能描述 |\n|------|----------|\n| task_create | 创建新任务 |\n| task_read | 读取任务特定章节 |\n| task_update | 更新任务特定章节 |\n| task_complete | 标记检查项完成 |\n| task_archive | 归档已完成任务 |\n| task_list | 列出所有任务 |\n| task_search | 搜索任务 |\n\n工作者管理工具\n\n| 工具 | 功能描述 |\n|------|----------|\n| worker_create | 创建工作者实例 |\n| worker_start | 启动工作者执行 |\n| worker_sendSignal | 向工作者发送信号 |\n| worker_cancel | 取消后台工作者 |\n| worker_status | 获取工作者状态 |\n\nDteam 调度工具\n\ndteam 工具是调度入口，支持四种 action：\n\n| Action | 说明 | 输入 | 输出 |\n|--------|------|------|------|\n| list | 列出所有角色 | 无 | 角色列表 |\n| plan | 生成执行计划 | goal, agents?, mode? | 执行计划 |\n| run | 创建并启动工作者 | goal, agents?, mode?, style? | workerId, plan |\n| status | 查询工作者状态 | workerId | 运行状态 |\n\n自适应并发控制\n\n这是 pi-dteam 最具特色的功能之一。在 team 模式下，系统能够根据系统资源（CPU、内存）和任务吞吐量动态调整并发度。\n\n工作模式\n\n- 静态模式：显式传入 concurrency 参数，使用固定并发度\n- 自适应模式（默认）：根据系统负载自动调整并发度\n\n状态机设计\n\n\ncoldStart → exploring → steady → overload\n ↑ ↓ ↑ ↓\n └───────────┘ └────────┘\n\n\n系统从冷启动开始，经过探索阶段进入稳态。当检测到资源紧张时进入过载状态，降低并发度；资源恢复后重新回到稳态。\n\n过载保护机制\n\n- 当 CPU > 85% 或内存 < 500MB 时自动降级\n- 当 CPU < 70% 且内存 > 1GB 时自动恢复\n\n配置选项\n\njson\n{\n \"type\": \"team\",\n \"task\": \"并行执行多个子任务\",\n \"style\": \"explore\",\n \"options\": [\n { \"type\": \"concurrencyMode\", \"value\": \"adaptive\" },\n { \"type\": \"minConcurrency\", \"value\": 2 },\n { \"type\": \"maxConcurrency\", \"value\": 6 }\n ]\n}\n\n\nLLM 执行器（v0.4.0+）\n\n从 v0.4.0 开始，worker_start 默认通过 Pi SDK 调用真实的 LLM。执行流程如下：\n\n1. 加载 agents/.md 获取 systemPrompt 和 tools\n2. 按优先级解析 model：WorkerConfig.model → role frontmatter model → sessionModel\n3. 如果主模型不可用，遍历 fallbackModels 链（最多 5 个）\n4. 通过 onUpdate 流式返回响应，累积 text_delta 事件\n5. 返回包含 exitCode、output、usage、model、stopReason 等信息的完整结果\n\n工作者状态可视化（v0.4.2+）\n\n项目在 TUI 中提供了优雅的多工作者状态显示：\n\n\n● build Implement feature T:3 · edit 5.0s 📡\n ↳ step1/3 explore Analysis 2.1s ✓\n● check Review T:1 1.2s\n\n\n显示特性\n\n- 多工作者并行显示（每行一个）\n- team/chain 子任务缩进 2 空格 + ↳ 标记\n- 信号徽章：📡（进度）/ 🚧（阻塞）/ 🔍（发现）/ 🆘（求助）\n- 状态栏最小计数器：N workers · M running\n- 1 秒刷新频率\n- Ctrl+O 切换全屏详情\n\n内存管理工具\n\n项目提供了完整的共享内存管理方案：\n\n| 工具 | 功能 |\n|------|------|\n| memory_get | 从共享内存获取值 |\n| memory_set | 在共享内存设置值 |\n| memory_keys | 列出命名空间所有键 |\n| memory_has | 检查键是否存在 |\n| memory_delete | 删除键 |\n| memory_clear | 清空命名空间 |\n| memory_save | 保存共享内存到文件 |\n| memory_load | 从文件加载共享内存 |\n\n这让多个智能体能够共享状态、传递中间结果，实现真正的协作。\n\n国际化支持\n\npi-dteam 内置了 Pi 压缩和分支摘要输出的本地化支持。使用 /compact 或 /tree 时，摘要标题会自动适配用户语言。\n\n支持的语言包括：简体中文、繁体中文、日语、韩语、德语、法语、西班牙语、葡萄牙语、俄语、阿拉伯语、英语等。\n\n语言自动检测顺序：PI_LOCALE → LC_ALL → LANG\n\n安装与使用\n\n安装\n\nbash\n通过 git 安装（推荐）\npi install git:github.com/ssdiwu/pi-dteam\n\n或通过本地路径安装\npi install /path/to/pi-dteam\n\n\n基础命令\n\n\n/explore 任务描述 探索者：收集信息\n/design 任务描述 设计者：制定计划\n/build 任务描述 构建者：执行计划\n/deploy 任务描述 部署者：发布验证\n/check 任务描述 审查者：质量检查\n/close 任务描述 收尾者：归档关闭\n\n\n设计哲学与启示\n\n1. 角色分离 vs 端到端\n\n与一些端到端的智能体系统不同，pi-dteam 采用明确的角色分离。这种设计的好处是：\n\n- 每个角色可以专门优化，使用最适合的模型和提示词\n- 便于人工介入和审查特定阶段\n- 更容易调试和优化特定环节\n\n2. 自适应并发的工程智慧\n\n自适应并发控制体现了对生产环境的深刻理解。固定并发度在资源波动时要么浪费资源，要么导致系统崩溃。动态调整是更稳健的方案。\n\n3. 信号机制的灵活性\n\n信号系统让智能体之间能够超越简单的输入输出关系，实现真正的协作。进度报告、阻塞协调、资源发现等场景都需要这种机制。\n\n应用场景\n\n场景一：代码生成流水线\n\n使用 chain 模式串联 explore → design → build → check，让 AI 先理解需求，再设计方案，然后实现代码，最后自我审查。\n\n场景二：批量数据处理\n\n使用 team 模式并行处理多个独立的数据文件，自适应并发确保系统稳定。\n\n场景三：多方案探索\n\n使用 team 模式让多个智能体并行探索不同的解决方案，然后通过信号机制协调，选出最优方案。\n\n结语\n\npi-dteam 展示了多智能体编排系统的一种优雅实现方式。它不追求最复杂的功能，而是在简洁性和实用性之间找到平衡。对于希望构建可靠多智能体工作流的开发者来说，这是一个值得参考的开源项目。\n\n随着 AI 智能体生态的发展，类似 pi-dteam 这样的编排工具将成为基础设施的重要组成部分。