AI 深度技能之-解读PilotDeck（三）- 多角色协同开发

PilotDeck 的多角色协同和 Hermes Kanban 完全不同：没有 Dispatcher 轮询，没有任务状态机，而是通过 WorkSpace 隔离 + Subagent 派发 + Skills 技能包 + Smart Router 路由，让主 Agent 按流水线顺序调用不同角色的子 Agent。这篇文章用一个"开发用户认证模块"的实际例子，配齐所有配置文件和脚本。

PilotDeck 的多角色方案和 Hermes 有什么不同

维度	Hermes Kanban	PilotDeck Subagent
协调机制	Dispatcher 轮询 + 任务状态机	主 Agent 顺序派发
隔离方式	Profile（独立 config + memory）	WorkSpace（独立文件 + 记忆 + 技能）
角色定义	config.yaml + SOUL.md	SKILL.md + subagentType
任务队列	SQLite 持久化看板	todo_write 内存态
并发调度	多 Worker 并行 pull	主 Agent 串行 dispatch
适合场景	长周期多任务（运维、内容生产）	单项目多阶段（软件开发）

PilotDeck 的优势在 WorkSpace 隔离：每个项目有独立的文件系统、白盒记忆、技能集。4 个角色的 SKILL.md 放在 WorkSpace 的 .pilotdeck/skills/ 下，不串台。Smart Router 按角色选模型：PM 和 Architect 用旗舰模型（规划质量优先），Developer 用轻量模型（编码成本优先），Reviewer 回旗舰模型（验证质量优先）。

架构总览

主 Agent 收到用户指令后，通过 Smart Router 识别任务类型，按流水线顺序派发 4 个 Subagent：

PM Subagent（plan 类型，只读）→ 输出 PRD + todo 列表
Architect Subagent（plan 类型，只读）→ 输出技术方案
Developer Subagent（general-purpose 类型，读写）→ 编码 + 测试
Reviewer Subagent（verify 类型，只读）→ Code Review + 审查报告

所有 Subagent 共享同一个 WorkSpace 的文件和记忆，但各自只能使用 SKILL.md 中定义的工具集。

实际例子：开发用户认证模块

需求：支持邮箱注册、OAuth 登录、JWT 会话管理的认证模块。

阶段 1：PM 分析需求

主 Agent 派发 product-manager subagent：

php 复制代码

// 主 Agent 的工具调用
agent({
  subagent_type: "product-manager",
  prompt: "用户需求: 开发一个用户认证模块, 支持邮箱注册、OAuth 登录、JWT 会话管理\n\n" +
          "分析需求, 输出 PRD 到 docs/prd.md, 并用 todo_write 创建任务列表。"
})

PM Subagent 读取角色指令（roles/pm/SKILL.md），执行三件事：

澄清需求（如果缺少关键信息会反问，本例信息完整，跳过）
写 PRD 到 docs/prd.md
用 todo_write 创建 8 个任务，标注 assignee 和依赖关系

PRD 产出片段：

markdown 复制代码

# PRD: 用户认证模块

## 功能需求
### F1: 邮箱注册
- 输入: email, password
- 规则: 密码 zxcvbn 评分 >= 3, 邮箱唯一
- 输出: user_id, JWT token

### F2: OAuth 登录
- 支持: Google, GitHub
- 流程: 授权码 → 换 access_token → 创建/查找用户 → 发 JWT

### F3: JWT 会话管理
- access_token: 15 分钟过期
- refresh_token: 7 天过期, 一次性使用

## 验收标准
1. 注册接口返回 201 + JWT
2. 重复邮箱注册返回 409
3. OAuth 回调正确创建用户
4. refresh_token 只能使用一次
5. 所有接口有输入校验

todo 列表：

ini 复制代码

todo_1: 写 PRD                    assignee=pm          status=completed
todo_2: 设计技术方案              assignee=architect   status=pending    deps=[todo_1]
todo_3: 实现注册接口              assignee=developer   status=pending    deps=[todo_2]
todo_4: 实现登录接口              assignee=developer   status=pending    deps=[todo_2]
todo_5: 实现 OAuth 回调           assignee=developer   status=pending    deps=[todo_2]
todo_6: 实现 JWT 中间件           assignee=developer   status=pending    deps=[todo_2]
todo_7: Code Review              assignee=reviewer    status=pending    deps=[todo_3,todo_4,todo_5,todo_6]
todo_8: 修复审查问题              assignee=developer   status=pending    deps=[todo_7]

阶段 2：Architect 设计方案

主 Agent 读到 PM 的报告（Scope: 需求分析 / Result: PRD 已写入 docs/prd.md），确认产出后派发 architect subagent：

php 复制代码

agent({
  subagent_type: "architect",
  prompt: "读取 docs/prd.md, 输出技术方案到 docs/architecture.md。\n" +
          "包括: API 定义, 数据模型, 目录结构, 技术选型。"
})

Architect 读取 docs/prd.md，输出技术方案到 docs/architecture.md：

shell 复制代码

# 技术方案: 用户认证模块

## 技术选型
- 后端: FastAPI 0.115 + Python 3.12
- 数据库: PostgreSQL 16 (生产) / SQLite (开发)
- 认证: PyJWT 2.9 + bcrypt 4.2
- OAuth: httpx 0.27 (Google/GitHub OAuth)
- 校验: Pydantic 2.9

## API 定义
### POST /api/auth/register
| 字段 | 类型 | 必填 | 校验 |
|------|------|------|------|
| email | string | 是 | RFC 5322 |
| password | string | 是 | zxcvbn >= 3 |

### POST /api/auth/login
### GET /api/auth/oauth/{provider}/callback
### POST /api/auth/refresh

## 数据模型
### users
| 字段 | 类型 | 约束 |
|------|------|------|
| id | UUID | PK |
| email | VARCHAR(255) | UNIQUE |
| password_hash | VARCHAR(255) | nullable (OAuth 用户无密码) |
| oauth_provider | VARCHAR(50) | nullable |
| oauth_id | VARCHAR(255) | nullable |
| created_at | TIMESTAMP | DEFAULT NOW() |

### refresh_tokens
| 字段 | 类型 | 约束 |
|------|------|------|
| id | UUID | PK |
| user_id | UUID | FK -> users.id |
| token_hash | VARCHAR(255) | UNIQUE |
| expires_at | TIMESTAMP | NOT NULL |
| used_at | TIMESTAMP | nullable |

阶段 3：Developer 编码

主 Agent 读取 todo 列表，找到 4 个 assignee=developer 且 dependencies 已满足的任务，逐个派发 developer subagent。

Smart Router 在这里发挥成本优化作用：Developer 用 DeepSeek-V3.2 而不是 GLM-4.6。DeepSeek-V3.2 在 SWE-bench 得分 70.0，单任务成本 $0.45；GLM-4.6 官方数据对齐 Claude Sonnet 4，74 个真实编程任务实测超过 Sonnet 4。规划和审查用旗舰（GLM-4.6），编码用高性价比模型（DeepSeek-V3.2），在不牺牲质量的前提下压低成本。

每个 Developer subagent 的执行流程：

scss 复制代码

1. memory_read(type="project")     → 获取技术选型 (FastAPI + PyJWT)
2. read_file("docs/architecture.md") → 获取 API 定义和数据模型
3. todo_show()                      → 看当前任务
4. write_file("src/auth/register.py") → 写注册接口
5. write_file("tests/test_register.py") → 写测试
6. bash("python -m pytest tests/test_register.py -v") → 跑测试
7. bash("git add src/auth/register.py tests/test_register.py")
8. bash("git commit -m 'feat(auth): implement register endpoint'")
9. todo_write(id="todo_3", status="completed") → 更新状态

4 个编码任务可以串行也可以并行（PilotDeck 支持主 Agent 同时派发多个 subagent，但同一个 WorkSpace 的文件写入有锁，建议串行）。

阶段 4：Reviewer 审查

所有编码任务完成后，主 Agent 派发 reviewer subagent：

swift 复制代码

agent({
  subagent_type: "reviewer",
  prompt: "对所有新增代码进行 Code Review。\n" +
          "读取 docs/prd.md 获取验收标准, 读取 docs/architecture.md 获取 API 定义。\n" +
          "执行 git diff HEAD~4 查看所有改动, 跑 pytest 确认测试通过。\n" +
          "输出审查报告到 docs/review.md。"
})

Reviewer 按 SKILL.md 中的审查清单逐项检查，输出报告：

shell 复制代码

# Code Review Report

## 结论: 需要修改

## 检查结果
### 功能完整性
| 检查项 | 结果 | 说明 |
|--------|------|------|
| PRD 功能点覆盖 | 通过 | F1/F2/F3 均已实现 |
| API 端点完整 | 通过 | 4 个端点全部实现 |
| 验收标准 | 不通过 | 第4条 refresh_token 未做一次性校验 |

### 安全
| 检查项 | 结果 | 说明 |
|--------|------|------|
| 密码哈希 | 通过 | bcrypt cost=12 |
| SQL 参数化 | 通过 | 全部用 SQLAlchemy ORM |
| JWT 密钥 | 不通过 | src/auth/jwt.py 第15行 hardcode 了密钥 |
| 输入校验 | 通过 | Pydantic 在入口层做了 |

## 需要修改的问题
1. [src/auth/jwt.py:15] JWT 密钥 hardcode, 改为从环境变量读取
2. [src/auth/refresh.py:28] refresh_token 使用后未标记 used_at, 可重复使用

主 Agent 读到 Reviewer 报告中的 Issues 不为空，派发 developer subagent 修复：

swift 复制代码

agent({
  subagent_type: "developer",
  prompt: "Code Review 发现以下问题, 请修复:\n" +
          "1. [src/auth/jwt.py:15] JWT 密钥 hardcode, 改为从环境变量读取\n" +
          "2. [src/auth/refresh.py:28] refresh_token 使用后未标记 used_at, 可重复使用\n" +
          "修复后跑测试确认通过。"
})

修复完成后重新派发 reviewer 审查，直到通过。

配置文件详解

pilotdeck.yaml（全局配置）

核心配置项：

bash 复制代码

agent:
  model:
    id: "glm-4.6"                 # 主 Agent 用旗舰模型
    provider: "zhipuai"

  subagentModels:
    product-manager:               # PM 用旗舰 (规划质量优先)
      id: "glm-4.6"
      provider: "zhipuai"
    architect:                     # Architect 用旗舰
      id: "glm-4.6"
      provider: "zhipuai"
    developer:                     # Developer 用高性价比 (编码成本优先)
      id: "deepseek-v3.2"
      provider: "deepseek"
    reviewer:                      # Reviewer 用旗舰 (验证质量优先)
      id: "glm-4.6"
      provider: "zhipuai"

  subagentTypes:
    product-manager:
      allowedTools: ["read_file", "write_file", "todo_write", "memory_write"]
      isReadOnly: false            # PM 需要写 PRD 文件
    architect:
      allowedTools: ["read_file", "write_file", "todo_write", "memory_write"]
      isReadOnly: false            # Architect 需要写架构文档
    developer:
      allowedTools: ["read_file", "write_file", "edit_file", "bash", "grep", "glob", "todo_write", "memory_write"]
      isReadOnly: false            # Developer 需要完整读写权限
    reviewer:
      allowedTools: ["read_file", "grep", "glob", "bash", "todo_write"]
      isReadOnly: true             # Reviewer 只读, 不改代码

memory:
  enabled: true
  provider: "edgeclaw"
  captureStrategy: "full_session"

完整配置文件见 configs/pilotdeck.yaml。

plugin.json（插件定义）

json 复制代码

{
  "id": "multi-role-dev",
  "name": "多角色协同开发插件",
  "hooks": [
    {
      "event": "PreToolUse",
      "tool": "agent",
      "handler": "hooks/pre-dispatch.js"
    },
    {
      "event": "PostToolUse",
      "tool": "agent",
      "handler": "hooks/post-complete.js"
    },
    {
      "event": "UserPromptSubmit",
      "handler": "hooks/route-prompt.js"
    }
  ],
  "skills": [
    "roles/pm/SKILL.md",
    "roles/architect/SKILL.md",
    "roles/developer/SKILL.md",
    "roles/reviewer/SKILL.md"
  ]
}

Hooks 脚本

3 个 Hook 脚本在不同阶段拦截：

pre-dispatch.js（子任务派发前）

检查 todo 依赖是否满足
按角色注入上下文到子 Agent 的 prompt
如果依赖未满足，block 派发并返回原因

post-complete.js（子任务完成后）

解析子 Agent 的结构化报告（Scope / Result / Key files / Files changed / Issues）
更新 todo 状态（completed 或 blocked）
检查下一个任务是否可以开始，触发自动派发

route-prompt.js（用户提交 prompt 时）

识别用户意图（是否是开发任务）
自动安装缺失的技能
在 prompt 前注入多角色协同指令

角色 SKILL.md

4 个角色的 SKILL.md 放在 roles/ 目录：

bash 复制代码

roles/
├── pm/SKILL.md           # 产品经理: 需求分解、PRD 撰写、验收标准
├── architect/SKILL.md    # 架构师: 技术选型、API 定义、数据模型
├── developer/SKILL.md    # 开发工程师: 编码、测试、git 提交
└── reviewer/SKILL.md     # 代码审查员: Code Review、安全检查、审查报告

每个 SKILL.md 定义三件事：

职责边界（只做什么，不做什么）
工作流程（按什么步骤执行）
输出格式（结构化报告的 5 个必填字段）

编排脚本

scripts/orchestrate.js 是独立的编排脚本，通过 PilotDeck Gateway API 模拟主 Agent 的编排行为。可以在终端直接运行：

ini 复制代码

WORKSPACE=auth-module node scripts/orchestrate.js "开发一个用户认证模块"

脚本按 ROLE_PIPELINE 顺序派发 4 个角色的 subagent，Developer 阶段会循环执行直到所有 todo 完成，Reviewer 打回后自动修复并重新审查。

scripts/setup.sh 是环境初始化脚本：

bash 复制代码

./scripts/setup.sh /path/to/workspace

它会创建目录结构、安装技能、合并配置、安装插件、启动 Gateway。

Smart Router 的成本优化

PilotDeck 的 Smart Router 按任务类型自动选模型：

方案	SWE-bench 得分	单任务成本
DeepSeek-V3.2 单 Agent	70.0	$0.45
GLM-4.6 单 Agent	68.0	约 $1.20
主 GLM-4.6 + 子 DeepSeek-V3.2	~70	约 $0.80

规划和审查用 GLM-4.6（旗舰，推理能力强），编码用 DeepSeek-V3.2（SWE-bench 70 分，成本极低）。主子组合比纯旗舰方案便宜约 33%，得分持平。

在多角色场景下，Router 的分配大致是：

PM / Architect / Reviewer → GLM-4.6（占约 48% 调用量，但 token 量小）
Developer → DeepSeek-V3.2（占约 44% 调用量，token 量最大，单价低）

白盒记忆：跨角色知识传递

PilotDeck 的记忆系统是白盒的，每个角色可以通过 memory_write 和 memory_read 传递知识：

记忆类型	写入者	读取者	内容
project	PM	Architect, Developer	技术栈约束、合规要求
project	Architect	Developer	API 格式偏好、目录结构规范
feedback	Developer	后续 Developer	编码中发现的用户偏好
feedback	Reviewer	后续 Developer	反复出现的问题模式

比如 PM 在 PRD 阶段写入了"API 响应格式统一用 {code, data, message}"，Developer 在编码时读记忆就会自动遵循这个格式，不需要 Architect 在文档里重复说明。

文件清单

完整的配置文件和脚本：

bash 复制代码

pilotdeck_multirole/
├── configs/
│   ├── pilotdeck.yaml              # 全局配置 (模型映射 + 子agent类型 + 记忆 + MCP)
│   ├── plugin.json                 # 插件定义 (hooks + commands + skills)
│   ├── hooks/
│   │   ├── hooks.json              # Hook 注册清单
│   │   ├── pre-dispatch.js         # 派发前拦截: 检查依赖, 注入上下文
│   │   ├── post-complete.js        # 完成后拦截: 解析报告, 更新todo, 触发下一阶段
│   │   └── route-prompt.js         # 用户提交时拦截: 识别意图, 自动安装技能
│   └── commands/
│       ├── dev-workflow.md         # /dev 命令: 启动4角色流水线
│       ├── review-only.md          # /review 命令: 单独触发审查
│       └── fix-issues.md           # /fix 命令: 根据审查报告修复
├── roles/
│   ├── pm/SKILL.md                 # 产品经理角色定义
│   ├── architect/SKILL.md          # 架构师角色定义
│   ├── developer/SKILL.md          # 开发工程师角色定义
│   └── reviewer/SKILL.md           # 代码审查员角色定义
├── scripts/
│   ├── setup.sh                    # 环境初始化脚本
│   └── orchestrate.js              # 编排脚本 (独立运行, 不依赖主Agent)
└── images/
    ├── d1_architecture.png         # 架构总览图
    ├── d2_workflow.png             # 完整工作流时序图
    └── d4_smart_router.png         # Smart Router 路由策略图

快速开始

bash 复制代码

# 1. 安装 PilotDeck (如果没装)
curl -fsSL https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.sh | bash

# 2. 复制配置文件到 WorkSpace
cp -r roles/ configs/ scripts/ /path/to/your/workspace/.pilotdeck/

# 3. 运行初始化脚本
./scripts/setup.sh /path/to/your/workspace

# 4. 设置 API 密钥
export ZHIPUAI_API_KEY=...
export DEEPSEEK_API_KEY=...

# 5. 启动 PilotDeck
pilotdeck

# 6. 在 Web UI 中输入开发指令
/dev 开发一个用户认证模块, 支持邮箱注册和 JWT 会话

或用脚本直接编排：

ini 复制代码

WORKSPACE=auth-module node scripts/orchestrate.js "开发一个用户认证模块"

和 Hermes Kanban 的选型建议

两个方案适合不同场景：

选 PilotDeck 多角色如果：

单项目多阶段开发（软件项目，从需求到交付）
需要白盒记忆（查看和修改 Agent 记了什么）
需要成本优化（Developer 用轻量模型，规划用旗舰）
团队成员需要可视化界面操作

选 Hermes Kanban 如果：

多任务并行（内容生产、运维、数据处理）
任务需要持久化队列（崩溃后恢复）
需要长时间运行的 Worker（跑测试、构建、部署）
多项目隔离（每个项目一个 board）

两者也可以组合：PilotDeck 做 WorkSpace 内的多角色开发，Hermes Kanban 做跨 WorkSpace 的任务调度。但这需要额外的集成工作，一般场景用其中一个就够了。