# 第 17 章 高级技能

## 本章目标

- **O1** 能够解释“单任务代理”“并行编排”“恢复与交接”之间的依赖层次（产物：高级技能升级路径）
  - 证据: 高级技能升级路径按依赖关系排列“单任务代理”“并行编排”和“恢复与交接”
- **O2** 能够自下而上构造高级技能升级路径并为每层写出完成证据（产物：高级技能升级路径）
  - 证据: 高级技能升级路径为每一层写出输入、完成标准和可复核证据
- **O3** 能够判断单任务代理何时升级到并行编排或恢复交接（产物：高级技能升级路径）
  - 证据: 产物用一个复杂任务记录升级条件、并行边界和恢复点

## 学习路径

- **初学者**: 本章迁移任务是：能够判断单任务代理何时升级到并行编排或恢复交接。先按图中的“前置依赖”关系完成高级技能升级路径的第一项证据，再逐项核对责任人与判断标准。
- **有经验者**: 先用当前项目完成这一任务：能够判断单任务代理何时升级到并行编排或恢复交接。提交高级技能升级路径后，再对照正文复核关系类型、缺失证据和授权边界。

## 教学图解

- **必交产物**: 高级技能升级路径
- **图解类型**: advanced-skills
- **关系语义**: 三层自下而上形成前置依赖；上层不能补偿下层缺口，诊断必须回到最早失效层。
- **核心概念**: 单任务代理 · 并行编排 · 恢复与交接

![第 17 章高级技能升级路径教学图](/learning/diagrams/zh/chapter-17.svg)

从底层前置条件读到上层结果，用高级技能升级路径定位不能被高层表现掩盖的缺口。

图将高级技能升级路径画成三级阶梯，底层“单任务代理”支撑中层“并行编排”，中层再支撑上层“恢复与交接”。层级表达前置依赖而非重要性排名；任一底层证据缺失时，上层结果不能视为已成立。

> **公开课程改编版。**正文依据内部教材整理，保留概念、流程与示范。案例规模、用时、提升比例及目标阈值均用于教学，不是本站交付成果或通用标准。工具、平台与技能描述需在实际环境核验。提示词不能授予权限；重试次数不自动触发恢复；恢复须先保护工作并确认目标、共享状态和外部数据影响。

## 课程讲解

### 17.1 项目编排（Orchestrator）：依赖树管理、上下文隔离与集成验收

为什么需要编排：一个功能做对了，十个功能加在一起可能全是错的——顺序决定一切。当你手上有 4 个功能需要在一个月内完成，你决定"并行推进"——让 AI 同时写 4 个功能的代码。一周后你发现：功能 A 的数据库模型和功能 B 的冲突了，功能 C 依赖的 API 还没建好，功能 D 的 API 接口定义改了三次……项目陷入"所有功能互相等待、互相依赖"的死锁状态。

单功能的开发流程是清晰的：拆解 → 编码 → 验收 → 固化。但当有多个功能时，问题不再是"怎么做一个功能"，而是"怎么安排这些功能的顺序"。功能之间不是"独立的墙"，而是"共享地基的建筑"——共享数据库表、共享 API、共享组件库。需要一个"交通指挥"来管理这些共享资源。

核心原则：

- 功能即任务：对 Orchestrator 来说，最小的执行单元是一个完整的功能。它只问三个问题：这个功能依赖哪些前置功能？（依赖排序）；这个功能验收通过了吗？（质量门禁）；这个功能完成后，整体项目集成测试通过吗？（集成验证）。
- 进度即状态：Orchestrator 管理跨会话的项目状态。进度状态机：待办（TODO）→ 进行中（IN_PROGRESS）→ 已完成（DONE）/ 阻塞（BLOCKED）。关键规则：只有验收通过的功能才能标记为 DONE。
- 集成即红线：每个功能单独验收通过后，必须做跨功能集成检查——功能 A 的 API 输出能否被功能 B 正确消费？功能 A 新增的数据模型是否与功能 B 兼容？整体测试是否通过？单个功能没问题 ≠ 整个系统没问题。

依赖树管理：Orchestrator 最核心的能力是管理功能之间的依赖关系：

| 依赖类型 | 说明 | 示例 |
|---------|------|------|
| 硬依赖 | 功能 B 必须等功能 A 完成才能开始 | 先做登录接口（A），再做个人中心（B） |
| 软依赖 | 功能 B 可以和功能 A 并行，但需要知道 A 的接口定义 | 用 mock 数据代替 A 的真实输出 |
| 无依赖 | 功能 B 完全不依赖功能 A | 用户管理和系统配置通常是独立的 |

最优顺序的推导：A 是根节点无依赖最先做；C 独立可以和 A 并行；B 依赖 A 在 A 之后做；D 依赖 A + B 最后做。最优顺序：A 和 C 并行 → B → D。如果不按这个顺序——比如先做 B 再做 A——B 的代码会在 A 完成后需要大量重写，因为 B 在 A 不存在时，AI 会"猜"一个认证接口的定义，而这个猜测大概率会和实际的 A 不一致。

上下文隔离与重置：多功能开发中最大的陷阱是"在一个对话里做所有功能"。Orchestrator 的解决方案是：每个功能使用独立的对话上下文——功能 A 的对话不包含功能 B 的任何信息，反之亦然。但功能 B 需要知道功能 A 的 API 定义才能正确调用它，答案在蓝图（CONTEXT.md）中：Orchestrator 在每个新功能开始前都会更新蓝图，把前一个功能的 API 契约、数据模型固化到蓝图中。对话隔离了，但信息通过蓝图流通。

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

<!-- code-example:chapter-17-E1 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```text
.agents/
├── job.state.json     # 机器可读的完整项目状态
└── job.progress.md    # 人类可读的追加式进度账本
```

`job.state.json` 示例：

<!-- code-example:chapter-17-E2 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```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"
}
```

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

异常处理：某个功能阻塞（失败 N 次后标记 BLOCKED 并通知用户，由获授权的人决定人工介入或调整依赖；不得通过降低标准把失败标成 PASS）；跨功能集成发现问题（生成集成问题报告，等待用户决策，不自动修复）；项目中途变更需求（将受影响的功能重新标记为 TODO，更新蓝图，重新执行受影响的功能及其下游依赖）。

### 17.2 全自动构建（Job）：八阶段流程与降级策略、使用边界

定位：Job 站在技能体系的最顶层。它的存在意义是：把"从零到部署"这条八个环节的链条，封装成一个自动化流程。

<!-- code-example:chapter-17-E3 mode:pseudocode -->
> **示例类型：伪代码。** 伪代码，不可直接执行。它只表达判断顺序，实施时必须补齐真实接口、权限与错误处理。
```text
脚手架搭建 → 需求分析 → 架构设计 → 前端设计 → POC（可选）→ 功能开发 → 集成验收 → 部署配置生成
```

八阶段流程中的分工边界——每个阶段"AI 做什么、人做什么、边界在哪里"，这是 Job 设计中最重要的部分：

| 阶段 | AI 做什么 | 人的职责 |
|------|----------|---------|
| 1. 脚手架搭建 | 根据技术栈模板生成目录结构、配置文件、README | 确认模板选择 |
| 2. 需求分析 | 调用 Requirements 技能，引导用户说出需求，产出 REQUIREMENTS.md | 回答关键问题，确认需求文档 |
| 3. 架构设计 | 调用 Architect 技能，基于需求文档产出 CONTEXT.md | 确认技术选型、数据模型、API 设计 |
| 4. 前端设计 | 调用 Frontend Architect 技能，产出前端设计文档 | 确认 UI 风格、组件划分 |
| 5. 高保真原型（可选） | 先出纯前端原型，确认效果后再开发 | 确认原型效果 |
| 6. 功能开发 | 调用 Orchestrator，按依赖顺序逐个实现功能 | 在关键节点确认 |
| 7. 集成验收 | 检查跨功能集成的正确性 | 做最终判断 |
| 8. 部署配置生成 | 根据项目结构生成 Dockerfile、CI/CD 配置 | 确认部署目标环境 |

模式选择：normal 模式（每个阶段展示计划后等待确认，适合新项目/技术栈不熟悉/需求不明确）；auto 模式（里程碑计划确认后直接执行，适合技术栈成熟、需求清晰）；silent 模式（在第 19.3 节同等护栏下自动执行，适合已验证的管道或 CI/CD；不含业务取舍和生产发布授权）。

状态驱动架构：Job 的核心设计是"状态驱动"——所有进度信息写入文件系统，每个阶段的状态决定下一步做什么。对话中断后恢复：读取 job.state.json，找到当前阶段，从该阶段继续执行。

降级策略：以第 19.3 节为统一权限边界：仅当蓝图成熟、技术路径已验证、风险低且测试电网与关键验收完备时，才授予全自动执行权。门禁失败、结果未知或出现新风险，降级的是执行模式——转入调研 → 谋局 → 落地；无法界定风险则停止并请人判断。只有已经获批、且不触及关键要求的备用路径可继续，失败项保留失败状态。验收标准、客户承诺和交付范围的改变必须由获授权的人决策并留痕，不能因自动化受阻就降低标准，把失败改成 PASS。

使用边界：什么时候不该用 Job？

1. 需求极度模糊——连你自己都不知道要做什么，就别说"全自动"了，先做需求分析；
2. 技术栈不成熟——需要尝试新技术、做 POC 验证，不适合一键全自动；
3. 需要深度定制——项目有特殊的安全、性能、合规要求，需要人工介入的环节多；
4. 已有大量代码的项目——Job 是为"从零"设计的，已有项目应该用 Orchestrator 或 Next 技能。

在这些场景中，建议使用 Orchestrator + Workflow 的灵活组合，而不是全自动的 Job。

### 17.3 特殊场景技能：代码克隆（Cloner）、高保真原型（POC）、老系统还原（Legacy Recon）、项目接续（Next）

代码克隆（Cloner）——当你需要参考现有代码实现新功能时。你有一个功能，和项目中另一个功能的实现模式完全一样，只是业务逻辑不同。用 Cloner 可以"按这个模式实现那个功能"，而不是从零写。核心方法：分析现有代码的模式，按照同样的风格和结构实现新功能。进阶用法：一次分析多个现有功能，提取通用的模式模板，然后批量应用。

高保真原型（POC）——当你不确定一个方案是否可行时。POC 生成纯前端的高保真页面，使用模拟数据，不需要后端介入。进阶用法：POC 可以作为"需求确认工具"——让业务方看到真实界面后再确认需求，减少需求变更。

老系统还原（Legacy Recon）——当你需要从老系统迁移到新系统时。接手一个没有文档、没有测试、没有蓝图的遗留项目，Legacy Recon 先扫描代码、还原架构、提炼蓝图，然后再开始改造。进阶用法：先做"字段级对照"——逐字段对比老系统和新系统的实现，确保没有遗漏。对于"老系统迁移"，当已有信息比"重新分析"更可靠时，优先使用已有信息——老系统已经上线运行，它的功能描述是对真实需求的精确映射，比任何"分析"都准确。

项目接续（Next）——当你接手一个半成品项目时。别人做了一半的项目交给你，Next 先分析当前状态、识别未完成的工作、建立上下文。进阶用法：先评估项目的"代码体量"——源文件数、代码行数、测试覆盖率——然后决定是继续开发还是重建。

触发逻辑总结：有现有代码可以复用 → Cloner（不要从零写）；有老系统需要迁移 → Legacy Recon（不要从头设计）；别人做了一半的项目 → Next（不要重新理解）；不确定方案是否可行 → POC（先验证再开发）；项目需要全面测试 → QA（不要只靠手动测试）。

### 17.4 质量保障（QA）：测试策略与质量门禁

QA 不是什么：QA 不是"写测试"，而是"设计测试策略 + 生成测试用例 + 执行测试 + 报告结果"。

为什么需要独立的 QA 技能：项目完成后，需要系统性的测试覆盖。QA 解决的问题是——测试策略应该覆盖哪些层级（单元/集成/端到端）？测试覆盖率目标是多少？如何建立不可逾越的质量红线？

与 Inspector 的区别：Inspector 是"验收 AI 生成的代码是否符合蓝图"（针对单个里程碑）；QA 是"全面的测试策略与质量门禁"（针对整个项目）。Inspector 把住每一扇门，QA 设计整条防线。

测试驱动开发（TDD）在 AI 时代的演进：传统 TDD 是先写测试用例，再自己写代码去通过测试；在 AI 时代，则是先设定"验收标准"，再让 AI 出码（验收驱动开发）。在让 AI 输出任何一行实质性代码之前，架构师必须先将该节点的验收规则当作 Prompt 喂给 AI。（详见第 9 章。）

---

## 独立练习

使用虚构或已获授权的脱敏材料，先独立作答，再查看参考。将产物保存为 `chapter-17.md`，写上版本、决定、证据和缺项。

把分类、API、界面拆成三个任务。说明哪些可并行、共享契约如何冻结、谁整合，以及任一任务失败时怎么降级。

<!-- chapter-artifact-requirement -->
### 本章必交产物：高级技能升级路径

以下证据必须出现在本次独立练习的提交物中；正文原有问题用于提供内容，不能替代这些验收项。

- O1: 高级技能升级路径按依赖关系排列“单任务代理”“并行编排”和“恢复与交接”
- O2: 高级技能升级路径为每一层写出输入、完成标准和可复核证据
- O3: 产物用一个复杂任务记录升级条件、并行边界和恢复点

<details>
<summary>查看参考反馈（先独立作答）</summary>

## 参考反馈

共享契约确认后，API适配与界面可按契约推进，但整合要核验实际实现。每个任务有独立修改范围、检查记录与负责人；失败转串行定位，不降低验收标准。技能名称或自动编排不能授予外部写入、合并和部署权限。

### 自评与下一步

对照本章目标检查：决定是否明确，依据是否能复现，未知项是否如实记录。参考给出一种判断方式，不是唯一答案；若不同结论能提供同等证据，可请同伴复核。缺少证据的部分记未完成，再回到对应步骤补充。

</details>

## 来源与边界

登记来源只支持本章涉及的外部事实；高级技能升级路径、示例数字和练习情境属于课程内部教学设计，必须在实际项目中重新验证。

- [Git 官方参考](https://git-scm.com/docs) — Git project, 2026-09-17. 版本、分支、提交与恢复操作须按实际仓库状态验证。