task-orchestration

资源

scripts/
  validate-orchestration.sh
references/
  agent-assignment-guide.md

任务编排协议

任务编排协议定义了 GoodVibes 编排器如何将功能请求分解为 Agent 任务、分配 Agent 和技能、管理并行执行，以及与运行时引擎的 WRFC 链系统交互。这是编排器交付多 Agent 功能的主要工作流。

何时使用此技能

在以下情况下使用此技能：

• 用户提出需要多个工作流的功能请求
• 请求涉及多个领域（后端、前端、数据库等）
• 请求可以并行拆分为相互独立的子任务
• 请求需要多个 Agent 协同配合

以下情况不要使用此技能：

• 简单的单文件编辑（直接处理）
• 不涉及代码更改的纯分析任务
• 用户已经完成任务拆分

运行时引擎和 WRFC 链

运行时引擎会自动管理工作-审查-修复-完成（WRFC）链。编排器的职责是：

1. 分解任务并分配给工作 Agent
2. 启动最初的工作 Agent
3. 执行运行时引擎发出的 <gv> 指令——机械地、立即地执行，不作判断

运行时引擎负责所有审查、修复和完成决策。编排器不会手动启动审查 Agent 或修复 Agent。这些 Agent 仅由每个工作 Agent 完成后发出的运行时指令启动。

指令类型

运行时引擎通过包含 <gv> 标签的系统消息向编排器发出指令：

{"action":"spawn","wid":"wrfc_xxx","type":"reviewer","task":"Review the code..."}
{"action":"spawn","wid":"wrfc_xxx","type":"engineer","task":"Fix the issues..."}
{"action":"complete","wid":"wrfc_xxx"}
{"action":"escalate","wid":"wrfc_xxx","reason":"Max fix attempts reached"}

指令遵循规则

以下 4 条规则绝对不可违背：

1. 立即执行：指令一到达就立即执行。绝不可延后、排队或拖延。
2. 优先执行：先执行指令，再进行任何其他操作。期间不得调用工具、启动其他 Agent，也不得先向用户发送消息。
3. 自主权终止：WRFC 链收到第一条指令后，编排器不再对该链作出任何判断。链的执行完全由指令驱动。
4. 运行时优先：运行时工作流逻辑始终优先于编排器的判断。如果指令要求审查，就进行审查；如果要求完成，就完成。

可配置阈值

运行时会读取 goodvibes.json 中的以下配置：

• score_threshold（默认值：9.9）——PASS 的分数阈值
• max_fix_attempts（默认值：3）——升级处理前的最大修复轮数

编排器绝不硬编码这些值。运行时引擎会强制执行这些设置。

分解流程

第 1 步：对请求分类

开始分解前，先将请求归入以下类别之一：

功能实现——添加新功能

• 识别方式：“添加 X 功能”“实现 Y”“创建 Z 能力”
• 分解策略：按领域拆分（API、UI、数据库、类型）
• 并行度：高（大多数工作流相互独立）

错误修复——解决现有问题

• 识别方式：“修复 X 无法工作”“解决 Y 错误”“纠正 Z 行为”
• 分解策略：先查明根本原因，再逐步实施修复
• 并行度：低（必须先完成诊断，才能开始修复）

重构——改进代码结构，但不改变行为

• 识别方式：“重构 X”“调整 Y 的结构”“提取 Z”
• 分解策略：先分析，再逐个文件修改
• 并行度：中（按顺序分析，并行修改）

集成——连接现有系统

• 识别方式：“将 X 与 Y 集成”“将 A 连接到 B”
• 分解策略：了解双方，再设计适配层
• 并行度：中（并行调研，按顺序集成）

功能增强——改进现有功能

• 识别方式：“改进 X”“为现有 Z 添加 Y”
• 分解策略：了解当前状态，规划渐进式增补
• 并行度：中（按顺序了解现状，并行增补）

步骤 2：确定可并行的工作

分类后，确定可并行执行的工作：

独立领域：

• API 路由 + React 组件（前提是预先定义好契约）
• 类型定义 + 数据库架构
• 使用共享类型的多个 UI 组件
• 使用共享中间件的多个 API 端点

独立文件：

• 在不同目录中创建新文件
• 编辑没有导入关系的文件
• 为不同模块编写测试

独立研究：

• 查阅多个文档来源
• 分析多个文件以查找模式
• 在不同目录中发现模式

不应并行执行的情况：

• 实现使用类型定义前，必须先定义好类型
• API 查询数据库前，必须先定义好数据库架构
• 子组件导入父组件前，必须先创建父组件
• 必须先完成探索，再进行规划

步骤 3：定义 Agent 任务

对于每个可并行的工作流，定义一个任务，包含：

任务结构：

task_id: unique-task-identifier
agent: engineer | reviewer | tester | architect | deployer | integrator-ai | integrator-services | integrator-state | planner
skills: [skill-1, skill-2]
description: Brief description of what this task accomplishes
scope:
  files: [list of files to create/modify]
  directories: [directories to work within]
constraints:
  - Must use TypeScript
  - Follow existing patterns in src/features/
blocking: [list of task_ids this task blocks]
blocked_by: [list of task_ids blocking this task]
expected_outcome: What success looks like

示例：

task_id: create-user-types
agent: engineer
skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
description: Create TypeScript type definitions for User domain
scope:
  files: [src/types/user.ts, src/types/auth.ts]
  directories: [src/types]
constraints:
  - Use Zod for runtime validation
  - Export all types from src/types/index.ts
blocking: [create-user-api, create-user-components]
blocked_by: []
expected_outcome: Type files exist, export User, AuthContext, and validation schemas

步骤 4：分配 Agent 和技能

对于每个任务，使用下表为其分配合适的 Agent 类型和技能：

Agent 类型选择：

工作类型	Agent 类型	原因
实现 API、组件、功能	engineer	创建和实现代码
审查代码质量、标准	reviewer	确保代码质量和标准得到遵循
编写测试、提升测试覆盖率	tester	测试和验证
规划架构、设计决策	architect	高层设计和规划
部署应用、基础设施	deployer	部署和基础设施
集成 AI/ML 服务	integrator-ai	AI/ML 集成
集成外部服务	integrator-services	外部服务集成
管理状态和数据流	integrator-state	状态管理
协调复杂工作流	planner	高层编排

技能分配：

默认情况下，所有 Agent 都会获得协议技能：

• gather-plan-apply（GPA 循环）
• precision-mastery（工具使用）
• error-recovery（错误处理）
• goodvibes-memory（记忆集成）

按工作类型分配的其他技能：

工作类型	其他技能
API 实现	trpc、prisma、nextauth、rest-api-design
前端组件	react、nextjs、tailwindcss、shadcn-ui
数据库架构	prisma、postgresql、drizzle
身份验证	clerk、nextauth、lucia
类型定义	（无——协议技能已足够）
代码审查	review-scoring + 特定领域的审查技能

完整的分配表请参阅 references/agent-assignment-guide.md。

Agent 提示词模板

生成 Agent 时，提示词中始终要包含以下要素：

## Task
[Specific, actionable description of what to accomplish]

## Scope
**Files to create:**
- path/to/file.ts - Brief description

**Files to modify:**
- path/to/existing.ts - What changes to make

**Directories in scope:**
- src/features/auth/ - Work within this directory

## Constraints
- [Technical constraint 1]
- [Pattern to follow]
- [Dependency requirement]

## Skills Available
- skill-name - When to use it
- skill-name - When to use it

## Expected Outcome
[Concrete definition of success]

## Blocking/Blocked By
**This task blocks:** [list of downstream tasks waiting for this]
**This task is blocked by:** [list of upstream tasks this waits for]

关键要素：

1. 明确指定范围（文件路径，而非模糊描述）
2. 列出技能及其使用指南
3. 预期结果具体且可验证
4. 输出格式包含 <gv> 标签（由运行时钩子自动发出；编排器无需指示 Agent 输出此标签）

**注意：**不要在 Agent 提示词中添加 WRFC 参与说明。Agent 只需完成工作并发出 <gv> 标签。运行时引擎会自动处理 WRFC 链。

监控与协调

跟踪活跃 Agent

维护任务跟踪结构：

active_tasks:
  task-1:
    agent_id: agent_abc123
    status: running | completed | blocked | failed
    started_at: ISO-8601 timestamp
    last_update: ISO-8601 timestamp
    blocking: [task-2, task-3]
    blocked_by: []
  task-2:
    agent_id: agent_def456
    status: waiting
    blocked_by: [task-1]

Agent 并发限制

硬性限制：最多 6 个并发 Agent 链（来自输出样式配置中的 max_parallel_agent_chains）

一个“链”包含工作 Agent 及其完整的 WRFC 链（审查、修复、重新审查）。每次启动一个初始工作 Agent 都会创建一条链。统计链的数量，而不是单个 Agent 的数量。

当任务超过 6 个时：

1. 按依赖顺序确定优先级（优先解除下游任务的阻塞）
2. 将剩余任务排入队列
3. 在链完成时启动新的 Agent（运行时发出 complete 指令时）

任务优先级公式：

priority = (number of tasks it blocks) - (number of tasks blocking it)

优先级越高，越先启动

执行 <gv> 指令

当运行时引擎发出指令时：

1. 立即停止一切操作——不要继续处理其他任务中尚未完成的推理
2. 阅读指令——识别 action、wid、type 和 task 字段
3. 立即执行：
   • spawn：使用提供的任务提示词生成指定类型的 Agent
   • complete：将 WRFC 链标记为已完成，解除所有依赖任务的阻塞，并在有空位时生成下一个排队任务
   • escalate：向用户报告升级原因，不要为该链继续生成 Agent
4. 然后恢复其他编排工作

**无一例外。**绝不能跳过、重排或以其他事件为条件而延后执行指令。

WRFC 生成规则

1. 仅生成初始 Agent：编排器只能从任务分解结果中生成初始工作 Agent。所有审核和修复 Agent 均由运行时指令生成。
2. 尽可能并行：同时生成同一依赖阶段中的所有任务
3. 等待阻塞项：阻塞任务收到 complete 指令之前，切勿生成依赖任务
4. 遵守限制：并发链数不得超过 6
5. 处理升级：如果运行时发出 escalate，向用户报告——不要尝试自行修复该链

Agent 通信

Agent 之间不会直接通信。所有协调都由编排器负责：

Agent 间依赖：

• 任务 A 生成 types.ts
• 任务 B 需要 types.ts
• 编排器：等待 A 收到 complete 指令，然后向 B 提供 types.ts 的位置作为参考并生成 B

共享状态：

• 所有 Agent 都会读取和写入 .goodvibes/memory/
• 编排器在生成 Agent 之前检查 memory 中的决策、模式和失败记录
• 编排器将编排决策记录到 .goodvibes/memory/decisions.json

特定模式的行为

Vibecoding 模式（默认）

初始分解前确认：

• 在生成任何 Agent 之前，向用户展示任务分解结果
• 允许用户修改分解结果
• 仅初始分解需要用户确认；Agent 开始运行后，流程由运行时驱动

遇到歧义时自动生成：

• 如果任务分解有多种可行方案，则采用 memory 中最常见的模式
• 如果不存在可用模式，则自行决策并将其记录到 decisions.json
• 仅在涉及架构决策时（如身份验证提供方、数据库选择等）才向用户升级

错误处理：

• Agent 重试由运行时引擎管理（最多 max_fix_attempts 次）
• 达到最大尝试次数时，运行时会发出 escalate 指令
• 收到 escalate 后，根据指令的 reason 字段向用户说明情况

Justvibes 模式（严格）

自动继续：

• 跳过分解前确认
• 分解完成后立即生成 Agent
• 运行时引擎会自动处理所有 WRFC 循环

错误处理：

• 与 Vibecoding 模式相同——运行时管理修复尝试次数，并在次数用尽时发出 escalate
• 收到升级指令后向用户说明情况

分解示例

示例 1：功能实现

用户请求：“添加带有编辑功能的用户资料页面”

**分类：**功能实现

分解：

tasks:
  - task_id: create-profile-types
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Create Profile and ProfileUpdate types
    scope:
      files: [src/types/profile.ts]
    blocking: [create-profile-api, create-profile-ui]
    blocked_by: []
    
  - task_id: create-profile-api
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, trpc, prisma]
    description: Implement tRPC routes for profile CRUD
    scope:
      files: [src/server/routers/profile.ts]
    blocking: [create-profile-ui]
    blocked_by: [create-profile-types]
    
  - task_id: create-profile-ui
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, react, tailwindcss, shadcn-ui]
    description: Build profile page with edit form
    scope:
      files: [src/app/profile/page.tsx, src/components/ProfileForm.tsx]
    blocking: []
    blocked_by: [create-profile-types]
    
  - task_id: test-profile-feature
    agent: tester
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Create tests for profile feature
    scope:
      files: [src/server/routers/profile.test.ts, src/components/ProfileForm.test.tsx]
    blocking: []
    blocked_by: [create-profile-api, create-profile-ui]

执行计划：

1. 生成 create-profile-types（无阻塞项）
2. 等待 create-profile-types 的 complete 指令
3. 并行生成 create-profile-api 和 create-profile-ui（两者均无阻塞项）
4. 等待两者的 complete 指令
5. 生成 test-profile-feature（受 API 和 UI 阻塞）
6. 等待 test-profile-feature 的 complete 指令
7. 汇总结果并返回给用户

**注意：**每个 Agent 的审核和修复循环都由运行时引擎通过指令自动处理。编排器不会安排这些循环。

**并行度：**3 个阶段（单独执行类型定义 -> 并行执行 API 和 UI -> 单独执行测试）

示例 2：修复缺陷

用户请求：“修复 /dashboard 上的登录重定向循环”

**分类：**修复缺陷

任务分解：

tasks:
  - task_id: diagnose-redirect-loop
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, nextauth]
    description: Identify root cause of redirect loop
    scope:
      files: [src/middleware.ts, src/app/dashboard/page.tsx, src/lib/auth.ts]
    blocking: [fix-redirect-loop]
    blocked_by: []
    
  - task_id: fix-redirect-loop
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, nextauth]
    description: Apply fix based on diagnosis
    scope:
      files: [determined by diagnosis]
    blocking: []
    blocked_by: [diagnose-redirect-loop]

执行计划：

1. 启动 diagnose-redirect-loop
2. 等待诊断的 complete 指令
3. 使用诊断上下文启动 fix-redirect-loop
4. 等待修复的 complete 指令
5. 返回用户

**并行性：**无（完全按顺序执行：诊断 -> 修复）

示例 3：重构

用户请求：“将共享的身份验证逻辑提取为可复用的 hooks”

**分类：**重构

任务分解：

tasks:
  - task_id: plan-refactoring-approach
    agent: architect
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Design the refactoring strategy and hook API
    scope:
      directories: [src/components, src/app]
    blocking: [analyze-auth-patterns]
    blocked_by: []
    
  - task_id: analyze-auth-patterns
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Discover all auth usage patterns in components
    scope:
      directories: [src/components, src/app]
    blocking: [create-auth-hooks]
    blocked_by: [plan-refactoring-approach]
    
  - task_id: create-auth-hooks
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Create hooks based on discovered patterns
    scope:
      files: [src/hooks/useAuth.ts, src/hooks/useRequireAuth.ts]
    blocking: [refactor-components-1, refactor-components-2]
    blocked_by: [analyze-auth-patterns]
    
  - task_id: refactor-components-1
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Refactor components in src/app to use hooks
    scope:
      directories: [src/app]
    blocking: []
    blocked_by: [create-auth-hooks]
    
  - task_id: refactor-components-2
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Refactor components in src/components to use hooks
    scope:
      directories: [src/components]
    blocking: []
    blocked_by: [create-auth-hooks]

执行计划：

1. 启动 plan-refactoring-approach（架构师）
2. 等待规划的 complete 指令
3. 启动 analyze-auth-patterns
4. 等待分析的 complete 指令
5. 启动 create-auth-hooks
6. 等待 hooks 的 complete 指令
7. 并行启动 refactor-components-1 和 refactor-components-2
8. 等待两者的 complete 指令
9. 返回用户

**并行性：**4 个阶段（规划 -> 分析 -> hooks -> 并行执行 2 项重构）

升级处理标准

出现以下情况时，立即升级并询问用户：

1. 架构存在歧义——存在多种有效方案，且各有显著权衡

   • 示例：“新 API 使用 REST 还是 GraphQL”
   • 升级处理：列出选项及其优缺点，请用户决定

2. 信息缺失——没有用户输入就无法完成任务

   • 示例：“应该使用哪个身份验证提供商？”
   • 升级处理：列出选项，说明所需信息

3. 范围扩大——任务规模超出最初描述

   • 示例：“添加个人资料页面需要新增数据库架构并执行迁移”
   • 升级处理：展示扩大的范围，请求批准

4. 运行时升级——运行时引擎发出 escalate 指令

   • 示例：工作 Agent 达到最大修复尝试次数
   • 升级处理：展示该指令中的 reason，请求指示或人工干预

5. 需求冲突——发现的约束彼此矛盾

   • 示例：“用户想用 Prisma，但代码库使用 Drizzle”
   • 升级处理：说明冲突，请求解决

总结

任务编排工作流：

1. 对请求分类（功能、缺陷、重构等）
2. 找出并行机会（领域、文件、研究）
3. 定义 Agent 任务（包含 blocking/blocked_by 的任务结构）
4. 分配 Agent 和技能（使用决策表）
5. 使用结构化提示词启动初始工作 Agent
6. 监控活跃链（最多并发 6 条）
7. 立即、机械地执行运行时发出的 <gv> 指令
8. 所有链都收到 complete 指令后，汇总结果

关键原则：

• 明确优于含糊（使用文件路径，而非模糊描述）
• 能并行时就并行，必要时才按顺序执行
• 编排器负责初始任务分解；运行时引擎负责所有 WRFC 循环
• 先执行指令，再采取任何其他操作——没有例外
• 在 vibecoding 模式下遇到歧义时升级处理，在 justvibes 模式下自动继续
• 利用记忆辅助决策，避免重复失败