一个功能做对了，十个功能加在一起可能全是错的。顺序决定一切。

你手上有 4 个功能需要在一个月内完成。你决定"并行推进"——让 AI 同时写 4 个功能的代码。

一周后，你发现：功能 A 的数据库模型和功能 B 的冲突了——都用了一个叫 status 的字段，但 A 用 0/1/2 表示状态，B 用 pending/approved/rejected。功能 C 依赖的 API 还没建好，因为功能 D 的 API 接口定义改了三次。你检查功能 A 的代码，发现它把功能 B 的某个组件 import 进来用了——但那个组件本身还在开发中。

项目陷入了一种"所有功能互相等待、互相依赖"的死锁状态。你花了比写代码多一倍的时间来协调这些冲突。

这不是 AI 的问题。这是"没有编排"的问题。当多个功能同时开发时，它们不是独立的——它们共享数据库、共享 API、共享组件库。如果没有一个"交通指挥"来管理这些共享资源，冲突是必然的。

6.1 为什么需要编排

单个功能的开发流程是清晰的：拆解 → 编码 → 验收 → 固化。你已经熟悉了。但当你有 3 个、5 个、10 个功能需要实现时，问题不再是"怎么做一个功能"，而是"怎么安排这些功能的顺序"。

你可能觉得：并行不就行了？让 AI 同时写 3 个功能的代码，不是效率更高吗？

这个直觉在物理世界是对的——三个工人可以同时砌三面墙。但在软件工程中，功能之间不是"独立的墙"，它们是"共享地基的建筑"。功能 A 和功能 B 可能共享同一个数据库表、调用同一个 API、引用同一个组件。当 A 和 B 同时开发时，AI 可能不知道对方的存在——在 A 中改了数据库表的结构，在 B 中也改了同一个表——两个修改冲突了。

更隐蔽的问题是：功能 B 可能依赖功能 A 的输出。如果 A 还没完成，B 的 AI 会"猜"一个 A 的接口定义。这个猜测几乎一定是错的。等到 A 完成时，B 的代码需要大量重写。

这就是编排的必要性。Orchestrator 的职责不是写代码，而是回答三个问题：先做什么、后做什么、什么可以并行。它像交通指挥一样，确保所有功能在正确的轨道上推进，不会撞车，不会互相等待。

项目编排（Orchestrator） 就是解决这些问题。它不直接写代码，而是管理 Workflow 的调度：

Orchestrator
  ├── 读取蓝图 → 确定功能列表和依赖关系
  ├── 按依赖顺序调度 Workflow
  │   ├── Workflow(功能 A) → 完成 → 验收
  │   ├── Workflow(功能 B) → 完成 → 验收
  │   └── Workflow(功能 C) → 完成 → 验收
  ├── 跨功能集成验收
  └── 产出集成报告

6.2 核心原则

原则一：功能即任务

对 Orchestrator 来说，最小的执行单元不是一个文件或一行代码，而是一个完整的功能。每个功能由 Workflow 以全自动的方式完成。

Orchestrator 只问三个问题：

1. 这个功能依赖哪些前置功能？（依赖排序）
2. 这个功能验收通过了吗？（质量门禁）
3. 这个功能完成后，整体项目集成测试通过吗？（集成验证）

原则二：进度即状态

Orchestrator 管理跨会话的项目状态。每次上下文重置后，能从持久化记录中恢复进度。

进度状态机：

待办(TODO) → 进行中(IN_PROGRESS) → 已完成(DONE)
                                   ↘ 阻塞(BLOCKED)

关键规则：只有验收通过的功能才能标记为 DONE。

原则三：集成即红线

每个功能单独验收通过后，Orchestrator 必须做跨功能集成检查：

• 功能 A 的 API 输出是否能被功能 B 正确消费？
• 功能 A 新增的数据模型是否和功能 B 的兼容？
• 整体测试是否通过？

单个功能没问题 ≠ 整个系统没问题。

6.3 依赖树管理

Orchestrator 最核心的能力是管理功能之间的依赖关系。不是所有功能都可以并行开发。功能之间有三种依赖关系：

硬依赖：功能 B 必须等功能 A 完成才能开始。比如功能 B 调用功能 A 的 API，如果 A 的 API 还没写出来，B 的 AI 会"猜"一个接口定义——这个猜测几乎一定和实际的 A 不一致。

软依赖：功能 B 可以和功能 A 并行，但需要知道 A 的接口定义。比如功能 B 使用功能 A 的组件，如果 A 的组件接口是稳定的，B 可以提前开发，用 mock 数据代替 A 的真实输出。

无依赖：功能 B 完全不依赖功能 A，可以独立开发。比如"用户管理"和"系统配置"通常是独立的。

来看一个真实场景的依赖树推导过程。假设一个电商系统有 4 个功能：

• 功能 A：用户认证（包含登录/注册/JWT）
• 功能 B：订单列表（依赖用户认证，需要登录后才能查看订单）
• 功能 C：商品管理（独立，但使用同一套 UI 组件库）
• 功能 D：支付对接（依赖订单列表 + 用户认证）

依赖树分析：

• A 是根节点，无依赖，最先做
• C 独立，可以和 A 并行
• B 依赖 A，在 A 之后做
• D 依赖 A + B，最后做

最优顺序：A 和 C 并行 → B → D

如果不按这个顺序——比如先做 B，再做 A——B 的代码会在 A 完成后需要大量重写。因为 B 在 A 不存在时，AI 会"猜"一个认证接口的定义，而这个猜测几乎一定和实际的 A 不一致。

依赖类型

自动排序算法

Orchestrator 会读取蓝图中的里程碑定义，自动分析依赖关系，生成执行顺序：

输入：里程碑列表
  1.1 项目初始化（无依赖）
  1.2 数据库搭建（依赖 1.1）
  1.3 用户认证（依赖 1.2）
  2.1 订单列表（依赖 1.3）
  2.2 创建订单（依赖 1.3）
  2.3 订单详情（依赖 2.1）

输出：执行顺序
  Phase 1: 1.1 → 1.2 → 1.3
  Phase 2: 2.1 → 2.2（2.1 和 2.2 可并行？不，需要人工确认）
           2.3（依赖 2.1）

6.4 上下文隔离与重置

多功能开发中最大的陷阱是"在一个对话里做所有功能"。这会引发严重的上下文污染——功能 A 的调试代码、错误的尝试、废弃的方案，都会成为功能 B 生成的"背景噪音"。

Orchestrator 的解决方案是：每个功能使用独立的对话上下文。功能 A 的对话不包含功能 B 的任何信息，反之亦然。

但这里有一个矛盾：功能 B 需要知道功能 A 的 API 定义才能正确调用它。如果对话隔离了，B 怎么知道 A 的接口是什么？

答案在蓝图（CONTEXT.md）中。Orchestrator 在每个新功能开始前，都会更新蓝图，把前一个功能的 API 契约、数据模型固化到蓝图中。新功能开始时，AI 读取蓝图，就能获得所有"已完成功能"的接口定义。对话隔离了，但信息通过蓝图流通。

完整流程：

1. Orchestrator 启动功能 A → Workflow 执行 → 完成 → 更新蓝图
2. Orchestrator 启动功能 B → 读取最新蓝图（包含 A 的 API 契约）→ Workflow 执行 → 完成 → 更新蓝图
3. 以此类推

这个机制确保了两个关键目标：每个功能在干净的上下文中执行（避免上下文污染），同时每个功能都能获取到所有已完成功能的接口定义（通过蓝图传递）。

6.5 跨功能集成验收

为什么需要集成验收

每个功能单独验收时，AI 只会检查这个功能本身的正确性。但多个功能组合后，可能出现以下问题：

• 数据格式不一致：功能 A 的 API 返回 {id: 1}，功能 B 期望 {id: "1"}（类型不匹配）
• 命名冲突：功能 A 定义了 getUser()，功能 B 也定义了 getUser()（重复定义）
• 状态冲突：功能 A 把订单状态改为"已支付"，功能 B 依赖"已支付"状态做后续处理，但两者的"已支付"定义不同
• 资源竞争：功能 A 和功能 B 同时修改了同一个配置文件

集成验收方法

集成验收步骤：

1. 编译/构建项目
   → 确保没有编译错误

2. 运行完整测试套件
   → 确保没有回归

3. 检查跨功能数据流
   → 功能 A 的输出是否能被功能 B 消费？

4. 检查配置文件
   → 是否有冲突的配置修改？

5. 检查全局状态
   → 路由、状态管理、全局样式是否有冲突？

6.6 进度持久化

Orchestrator 的一个重要能力是"即使对话中断，也能恢复进度"。

持久化机制

进度信息写入文件系统，而不是只存在于对话上下文中：

.agents/
├── job.state.json    # 机器可读的完整项目状态
└── job.progress.md   # 人类可读的追加式进度账本

job.state.json 示例：

{
  "projectName": "订单管理系统",
  "phases": [
    {
      "name": "Phase 1: 基础架构",
      "milestones": [
        { "id": "1.1", "name": "项目初始化", "status": "DONE" },
        { "id": "1.2", "name": "数据库搭建", "status": "DONE" },
        { "id": "1.3", "name": "用户认证", "status": "DONE" }
      ]
    },
    {
      "name": "Phase 2: 核心功能",
      "milestones": [
        { "id": "2.1", "name": "订单列表", "status": "DONE" },
        { "id": "2.2", "name": "创建订单", "status": "IN_PROGRESS" },
        { "id": "2.3", "name": "订单详情", "status": "TODO" }
      ]
    }
  ],
  "currentMilestone": "2.2",
  "updatedAt": "2026-07-25T10:30:00Z"
}

即使整个对话上下文丢失，从这些文件也能完全恢复项目进度。

6.7 异常处理

场景一：某个功能阻塞了

功能 B 依赖功能 A，但功能 A 验收一直不通过。

处理方式： Orchestrator 不会无限等待。它会在功能 A 失败 N 次后，将其标记为 BLOCKED，并通知用户。用户可以选择：

• 人工介入修复功能 A
• 调整依赖关系，先做不依赖 A 的功能
• 降低功能 A 的验收标准

场景二：跨功能集成发现问题

功能 A 和功能 B 各自验收通过，但集成测试发现不兼容。

处理方式： Orchestrator 不尝试自动修复集成问题（涉及两个功能的修改，风险太高）。它会生成集成问题报告，等待用户决策。

场景三：项目中途变更需求

用户在第 5 个功能完成时，要求修改第 2 个功能的实现。

处理方式： Orchestrator 不会直接修改已 DONE 的功能。它会：

1. 将受影响的功能重新标记为 TODO
2. 更新蓝图
3. 重新执行受影响的功能及其下游依赖

本章小结

项目编排解决的是"多功能的组织问题"。核心是依赖树管理——识别功能之间的硬依赖、软依赖和无依赖，确定正确的开发顺序。上下文隔离与重置确保每个功能在干净的对话中执行，同时通过蓝图传递接口定义。Orchestrator 不写代码，它管理 Workflow 的调度和集成验收。记住：单个功能没问题 ≠ 整个系统没问题。下一章，我们将学习全自动构建——从零到部署的完整自动化。