Qoder 多角色协同开发：用 Custom Agent 搭一条软件生产线

Qoder 是阿里通义系出品的 AI Coding Agent（原 qwen code，现为独立品牌）。它的多角色方案和 PilotDeck、Hermes 都不同：不需要外部编排脚本，不需要 Kanban 看板，直接在 IDE 的 Chat 面板里通过 Custom Agent .md 文件定义角色，主会话根据 description 字段自动选择合适的子 Agent 委派任务。这篇文章用一个"开发用户认证模块"的实际例子，配齐所有配置文件。

Qoder 的多角色方案和类似Agent有什么不同

维度	Hermes Kanban	PilotDeck Subagent	Qoder Custom Agent
协调机制	Dispatcher 轮询 + 任务状态机	主 Agent 顺序派发	主会话自动委派，或手动 `/agent-name`
角色定义	config.yaml + SOUL.md	SKILL.md + subagentType	`.md` 文件（frontmatter + prompt）
角色文件位置	`~/.hermes/profiles/`	`.pilotdeck/skills/`	`.qoder/agents/`（项目级）或 `~/.qoder/agents/`（用户级）
模型分配	每 Profile 独立 config	subagentModels 映射	`.md` 文件 frontmatter 的 `model` 字段
触发方式	Dispatcher 自动 spawn	主 Agent 串行 dispatch	description 自动匹配，或 `/agent-name` 手动触发
SDK 支持	无	有（TypeScript）	有（`@qoder-ai/qoder-agent-sdk`）
适合场景	长周期多任务	单项目多阶段	IDE 内日常开发

Qoder 的优势在于轻量：不需要装额外服务，不需要配 YAML，在项目里放几个 .md 文件就完成了角色定义。主会话的 Agent Mode 会根据 description 字段自动判断该调用哪个子 Agent，也支持手动 /pm、/architect 这样触发。

架构总览

用户在 Qoder Chat 面板输入需求，Agent Mode 的 Plan 阶段自动生成 todo 列表。主会话通过 Agent 工具委派子 Agent，每个子 Agent 是一个 Custom Agent（.md 文件定义），有独立的上下文窗口、工具权限和模型配置。

4 个角色的文件放在项目级 .qoder/agents/ 目录下：

bash 复制代码

your-project/
├── .qoder/
│   └── agents/
│       ├── pm.md           # 产品经理
│       ├── architect.md    # 架构师
│       ├── developer.md    # 开发工程师
│       └── reviewer.md     # 代码审查员
├── src/
├── tests/
└── docs/

角色模型分配

按 TOOLS.md 的选型标准，全部使用国产模型：

角色	模型	档位	理由
PM	Qwen3.7-Max（阿里）	performance	规划类任务，推理质量优先
Architect	Qwen3.7-Max（阿里）	performance	技术方案设计需要强推理
Developer	DeepSeek-V4-Pro（深度求索）	efficient	编码类任务，Agentic Coding 开源最佳，Agent 体验优于 Sonnet 4.5
Reviewer	Qwen3.7-Max（阿里）	performance	审查需要发现问题的能力，质量优先

Qoder 的模型配置用档位制：efficient（高性价比）、performance（旗舰）、ultimate（极致）。在 .md 文件的 model 字段指定，或在 IDE 的 Quest → Setting → Agents 页面用 Change Model 切换。

第一步：创建 Custom Agent 文件

每个角色是一个 .md 文件，包含 frontmatter 和系统提示词两部分。

pm.md（产品经理）

yaml 复制代码

---
name: pm
description: 产品经理智能体，负责需求分析、PRD撰写、验收标准定义和任务拆分。当用户提出新功能需求或项目目标时自动触发。
tools: Read, Write, Glob, Grep, WebSearch
model: "[Qwen3.7-Max](qwen3.7-max)"
---

你是产品经理。你的工作是把用户的需求变成结构化的文档和任务列表。

## 职责边界

你只做三件事：
1. 写 PRD（产品需求文档），存到 `docs/prd.md`
2. 用 todo 列表拆分任务，标注 assignee 和 dependencies
3. 定义验收标准

你不写代码，不做技术选型，不画架构图。

frontmatter 字段说明：

字段	必填	说明
`name`	是	智能体唯一标识，也是 `/name` 触发命令
`description`	是	功能描述，主会话根据它自动选择是否调用
`tools`	否	允许的工具列表，逗号分隔
`model`	否	指定运行模型，不设置时跟随对话模型
`skills`	否	允许的技能列表
`mcpServers`	否	允许的 MCP 服务列表

Qoder 支持的内置工具：Bash、Edit、Write、Glob、Grep、Read、WebFetch、WebSearch。每个角色只开放需要的工具，比如 Reviewer 只读不写，所以 tools: Read, Glob, Grep, Bash（Bash 用来跑测试）。

完整的 4 个角色文件在 agents/ 目录下，这里不逐个贴了。每个角色的职责边界：

pm.md：需求分析 + PRD + todo 拆分。工具：Read, Write, Glob, Grep, WebSearch
architect.md：技术选型 + API 定义 + 数据模型。工具：Read, Write, Glob, Grep
developer.md：编码 + 测试 + git commit。工具：Read, Edit, Write, Glob, Grep, Bash
reviewer.md：Code Review + 跑测试 + 审查报告。工具：Read, Glob, Grep, Bash（只读 + 跑测试）

第二步：安装角色文件

方式 1：用 create-agent 技能（推荐新手）

在 Qoder Chat 面板输入：

bash 复制代码

/create-agent 代码审查专家

Qoder 会交互式引导你完成名称、描述、工具选择，自动生成 .md 文件到正确位置。

方式 2：手动复制

bash 复制代码

# 在项目根目录创建 agents 目录
mkdir -p .qoder/agents

# 复制 4 个角色文件
cp agents/pm.md .qoder/agents/
cp agents/architect.md .qoder/agents/
cp agents/developer.md .qoder/agents/
cp agents/reviewer.md .qoder/agents/

或直接运行初始化脚本：

bash 复制代码

./scripts/setup.sh /path/to/your/project

文件放好后，Qoder IDE 打开项目时会自动发现这些 Agent。在 CLI 中可以验证：

复制代码

qodercli agents list

第三步：使用

方式 1：自动触发（推荐）

在 Chat 面板用自然语言描述任务，主会话根据 description 自动选择合适的子 Agent：

复制代码

开发一个用户认证模块，支持邮箱注册、OAuth 登录、JWT 会话管理

Agent Mode 会先进入 Plan 阶段，生成 todo 列表。确认后，主会话依次委派：

pm 子 Agent 分析需求、写 PRD
architect 子 Agent 读 PRD、设计技术方案
developer 子 Agent 按方案编码
reviewer 子 Agent 审查代码

方式 2：手动触发

在 Chat 面板输入 /agent-name：

bash 复制代码

/pm 分析这个需求并写 PRD

bash 复制代码

/architect 根据 PRD 设计技术方案

bash 复制代码

/developer 按架构文档实现注册接口

bash 复制代码

/reviewer 审查最近的代码改动

手动触发适合单阶段执行，比如只需要审查代码时直接 /reviewer，不需要走完整流水线。

完整工作流

以"开发用户认证模块"为例，4 个阶段的完整流程：

阶段 1：PM 需求分析

主会话自动识别到"开发用户认证模块"是开发任务，委派 pm 子 Agent。

pm 子 Agent（Qwen3.7-Max）的工作：

读取用户需求，判断是否需要澄清
写 PRD 到 docs/prd.md，包含 3 个功能点（邮箱注册、OAuth、JWT）
定义 5 条验收标准
用 todo 创建 8 个任务，标注 assignee 和 dependencies

完成后返回结构化报告，主会话读取 docs/prd.md 确认产出，进入下一阶段。

阶段 2：Architect 技术方案

主会话委派 architect 子 Agent。

architect 子 Agent（Qwen3.7-Max）的工作：

读取 docs/prd.md
技术选型：FastAPI + PostgreSQL + PyJWT + bcrypt
定义 6 个 API 端点（注册、登录、刷新、登出、OAuth 回调、用户信息）
设计 3 张数据表（users、sessions、oauth_accounts）
输出到 docs/architecture.md
用 todo 为每个端点创建编码任务

阶段 3：Developer 编码

主会话读取 todo 列表，找到 assignee=developer 的任务，委派 developer 子 Agent。

developer 子 Agent（DeepSeek-V4-Pro）按依赖顺序逐个实现：

读取 docs/architecture.md 获取 API 定义和数据模型
创建 src/auth/models.py（数据模型）
创建 src/auth/routes.py（API 路由）
创建 tests/test_auth.py（单元测试）
跑 pytest tests/ -v 确认通过
git commit -m "feat(auth): implement register and login"

DeepSeek-V4-Pro 支持 1M 上下文，Agentic Coding 达到开源最佳水平。编码这类任务不需要旗舰模型的推理能力，轻量模型足够。

阶段 4：Reviewer 审查

主会话委派 reviewer 子 Agent。

reviewer 子 Agent（Qwen3.7-Max）的工作：

读取 docs/prd.md 获取验收标准
读取 docs/architecture.md 获取 API 定义
执行 git diff HEAD~N 查看所有改动
按审查清单逐项检查（功能完整性、代码质量、安全、测试、规范）
跑 pytest tests/ -v 确认测试通过
输出审查报告到 docs/review.md

如果审查不通过，报告中列出需要修改的问题（带文件名和行号）。主会话重新委派 developer 子 Agent 修复，修复后重新审查，直到通过。

SDK 方式：用 TypeScript 编排

除了在 IDE 中使用，Qoder 还提供 Agent SDK，可以用代码编排多角色协同：

php 复制代码

import { query } from "@qoder-ai/qoder-agent-sdk";

const q = query({
  prompt: "开发一个用户认证模块",
  options: {
    allowedTools: ["Agent"],
    agents: {
      pm: {
        description: "产品经理智能体。当需要分析需求、写PRD、拆分任务时使用。",
        prompt: "你是产品经理。负责需求分析、PRD撰写、任务拆分。",
        tools: ["Read", "Write", "Glob", "Grep", "WebSearch"],
        model: "performance",   // Qwen3.7-Max
        effort: "high",
        maxTurns: 10,
      },
      architect: {
        description: "架构师智能体。需要设计技术方案、定义API时使用。",
        prompt: "你是架构师。读取PRD，输出技术方案到docs/architecture.md。",
        tools: ["Read", "Write", "Glob", "Grep"],
        model: "performance",   // Qwen3.7-Max
        effort: "high",
        maxTurns: 10,
      },
      developer: {
        description: "开发工程师智能体。需要编码实现、写测试时使用。",
        prompt: "你是开发工程师。读取架构文档，按方案编码实现并写测试。",
        tools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"],
        model: "efficient",     // DeepSeek-V4-Pro
        effort: "medium",
        maxTurns: 20,
      },
      reviewer: {
        description: "代码审查智能体。需要Code Review、安全检查时使用。",
        prompt: "你是代码审查员。只读代码，输出审查报告，不改代码。",
        tools: ["Read", "Glob", "Grep", "Bash"],
        model: "performance",   // Qwen3.7-Max
        effort: "high",
        maxTurns: 8,
      },
    },
  },
});

for await (const event of q) {
  if (event.type === "text") process.stdout.write(event.text);
  if (event.type === "agent_dispatch") console.log(`\n[Agent] 委派: ${event.agent_name}`);
  if (event.type === "agent_result") console.log(`\n[Agent] 完成: ${event.agent_name}`);
}

SDK 方式适合 CI/CD 集成、批量任务处理。model 字段用档位名（efficient / performance / ultimate）而不是具体模型 ID，Qoder 会根据当前配置自动映射到对应模型。

完整脚本见 scripts/orchestrate.ts。

文件清单

bash 复制代码

qoder_multirole/
├── qoder-multi-role-guide.md       # 本文
├── agents/                          # 4 个角色定义
│   ├── pm.md                        # 产品经理 (Qwen3.7-Max)
│   ├── architect.md                 # 架构师 (Qwen3.7-Max)
│   ├── developer.md                 # 开发工程师 (DeepSeek-V4-Pro)
│   └── reviewer.md                  # 代码审查员 (Qwen3.7-Max)
├── scripts/
│   ├── setup.sh                     # 环境初始化脚本
│   └── orchestrate.ts               # SDK 编排脚本
└── images/
    ├── d1_architecture.png          # 架构总览图
    └── d2_workflow.png              # 完整工作流时序图

快速开始

bash 复制代码

# 1. 安装 Qoder CLI (如果没装)
npm install -g @qoder-ai/qoder-cli

# 2. 复制 agents 文件到项目
./scripts/setup.sh /path/to/your/project

# 3. 在 Qoder IDE 中打开项目

# 4. 在 Chat 面板输入开发指令
#    开发一个用户认证模块, 支持邮箱注册和 JWT 会话

# 或用 SDK 脚本编排
npx tsx scripts/orchestrate.ts "开发一个用户认证模块"

三个方案选型建议

场景	推荐	理由
IDE 内日常开发，快速角色分工	Qoder	最轻量，放几个 .md 文件就完成配置
单项目多阶段，需要白盒记忆	PilotDeck	WorkSpace 隔离 + Smart Router 成本优化
多任务并行，长周期运维	Hermes Kanban	持久化任务队列 + Dispatcher 自动调度

Qoder 的上手门槛最低：不需要装额外服务，不需要写 YAML 配置，不需要学状态机概念。在项目里放 4 个 .md 文件，Chat 面板里说话就行。代价是没有持久化任务队列，关掉 IDE 会话就结束了。如果任务需要跨会话延续，用 PilotDeck 或 Hermes。