# 任务拆解与执行

## 输入要求

1. **需求或spec**（必填）：需要实现的功能描述或已有spec
2. **现有代码**（可选）：相关代码片段或文件列表
3. **约束条件**（可选）：时间、性能、依赖限制

## 执行流程

### 第一步：需求分析

- 理解核心目标和边界
- 不得委派理解：在拆分或调用子 Agent 前，主 Agent 必须先自行确认目标、边界、验收口径和风险点；子 Agent 只能接收明确任务，不能替主 Agent 判断用户真实意图
- 如需求属于做网站/建站/企业官网/CMS网站/营销页/网站上线，先调用 `website-project` 确认站点规划、SEO、部署、验收和运维阶段，再进入任务拆解
- 如需求属于 API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目，先调用 `software-project` 确认边界、架构、数据/API、发布、回滚和交付阶段，再进入任务拆解
- 识别隐含依赖（如"用户系统"依赖"数据库表已存在"）
- 识别风险点（复杂算法、第三方集成、性能瓶颈）
- 识别安全触发面：外部输入、权限、数据库、文件上传、API、后台操作、长任务、第三方回调

### 第二步：原子任务拆解

将复杂需求拆分为2-7个原子任务（每Wave 2-5个）。每个任务必须满足：

- **单一职责**：只解决一个明确问题
- **可独立完成**：一个context window内可完成
- **可验证**：有明确的完成标准
- **可回滚**：失败时不影响其他任务
- **安全可验收**：涉及输入/权限/数据/文件/API/后台操作的任务必须包含安全检查项
- **可委派**：任务目标、输入、输出和验收标准已明确；若仍需判断用户意图或业务边界，须回第一步继续分析

**任务结构（XML格式）**：

```xml
<task type="auto|human-verify|decision">
  <name>[任务名称]</name>
  <files>[涉及文件列表]</files>
  <action>
    [具体执行步骤]
  </action>
  <verify>
    [验证方法：测试命令/检查清单/人工确认]
  </verify>
  <security>
    [安全验证：SQL注入/XSS/CSRF/权限绕过/文件上传/反序列化/敏感信息泄露；不涉及则写"不涉及，原因：..."；**禁止留空**]
  </security>
  <done>
    [完成标准：什么状态算完成]
  </done>
</task>
```

**长任务需求专项拆解**：若需求含"批量导入/导出/生成静态页/重建索引/采集同步/清理缓存/>3 秒或 >100 条处理"，不得按单端点单任务拆解，必须按 `Init → Step → Poll` 拆成依赖有序的 Wave：

- **Wave 1（Init）**：校验权限/CSRF/参数，创建任务记录，计算总量 → 返回 `task_id`、`total`、`status=queued`
- **Wave 2（Step）**：每批 20-100 条，更新进度、持久化状态、检测取消标记、幂等（用 `last_id`/游标保证每批唯一）
- **Wave 3（Poll）**：查状态/进度/错误，检测僵尸任务（`running` 超阈值标记 `failed` 或允许 `resume`）
- **Wave 4（Cancel）**：标记取消，正在执行的 Step 在下一批次检测取消标记后优雅退出
- **Wave 5（前端轮询交互）**：`Init/Step/Poll/Done/Failed/Cancelled` 状态、轮询间隔 800-2000ms、重试/取消入口、进度感知
- **Wave 6（长任务测试）**：Init/Step/Poll/失败重试/取消/超时/幂等全覆盖

各 Wave 间存在依赖（Step 依赖 Init 的任务记录，Poll 依赖 Step 的进度），必须串行；权限/CSRF/文件/SQL 等安全触发面须在每 Wave 的 `<security>` 写明验证方法。

### 第三步：Wave分组

按依赖关系将任务分组：

```
Wave 1（并行，无依赖）
├── Task 1.1: [任务A]
└── Task 1.2: [任务B]

Wave 2（依赖Wave 1）
├── Task 2.1: [任务C，依赖1.1]
└── Task 2.2: [任务D，依赖1.2]

Wave 3（依赖Wave 2）
└── Task 3.1: [任务E，依赖2.1和2.2]
```

**分组原则**：

- 无依赖的任务 → 同一Wave，可并行
- 有依赖的任务 → 后续Wave，必须串行
- 可能文件冲突的任务 → 同一Wave内串行或合并为一个任务
- 涉及安全触发面的Wave → 必须安排安全验证任务或在每个相关任务的 `<security>` 中给出验证方法

### 第四步：上下文隔离

执行单个任务时，只加载必要上下文：

```
任务上下文 = {
  spec: [相关requirement和scenario],
  design: [相关技术决策],
  files: [该任务需要读写的文件],
  decisions: [影响该任务的历史决策],
  previous_summary: [前置Wave的任务summary]
}
```

如平台允许子 Agent 或并行代理执行，必须使用简报式上下文，而不是传递完整对话历史：

```text
委派简报 = {
  task: [单一任务目标],
  background: [只保留与任务直接相关的背景],
  files: [允许读取或修改的文件范围],
  constraints: [技术/安全/编码/输出限制],
  verify: [必须返回的验证证据],
  forbidden: [不得触碰的模块、不得扩展的范围]
}
```

**禁止加载**：

- 无关模块的代码
- 已完成的无关任务细节
- 未决但无关的讨论
- 完整聊天记录或未经筛选的日志

> 上下文隔离同时受主 SKILL.md「二、子Agent 边界与委派协议 → 2.3」与「长任务执行可靠性（L0）」约束：长任务只加载当前 Wave / 当前原子任务所需上下文，已完成 Wave 细节仅以 `previous_summary` 传递，不回灌完整对话历史，避免上下文污染导致后续 Wave 误判。

### 第五步：执行与验证闭环

每个任务执行后：

1. **执行**：按action完成代码修改
2. **自测**：运行verify中的验证方法
3. **复核结果**：对照目标完成度、格式合规性、事实准确性、上下文一致性、边界条件和安全约束逐项检查；子 Agent 输出不得未经复核直接转交给用户
4. **记录summary**：

   ```
   ## Task Summary: [任务名]

   **完成状态**: [完成/部分完成/失败]
   **修改文件**: [文件列表]
   **验证证据**: [命令/API响应/测试结果/人工确认]
   **置信度**: [高/中/低，低置信度必须说明原因]
   **关键决策**: [执行中做出的决策]
   **偏差说明**: [与plan的差异及原因]
   **遗留问题**: [未解决的问题]
   ```

5. **验证通过**：标记done，进入下一任务
6. **验证失败**：修复或回滚，重新执行

### 第六步：记录到项目记忆

所有Wave执行完毕后，将任务执行结果和关键决策沉淀到项目记忆（参见 `project-memory-management.md`）：

- 汇总各任务的 summary，生成整体执行报告（Session Summary 模式）
- 记录执行中的关键决策和偏差（Decision Record 模式）：如任务拆分调整、依赖关系变更
- 记录新发现的项目约束和规范（Convention Capture 模式）：如文件组织约定、模块边界规则

## 输出格式

````
## 任务拆解报告

### 需求概述
[一句话总结]

### 任务列表

#### Wave 1（并行）
```xml
<task type="auto">
  <name>...</name>
  <files>...</files>
  <action>...</action>
  <verify>...</verify>
  <security>...</security>
  <done>...</done>
</task>
```

#### Wave 2（依赖Wave 1）

...

### 执行建议

- 优先执行Wave 1，并行推进
- Wave 2等Wave 1全部完成后再开始
- 每个任务完成后立即验证

### 风险点

- [风险1及缓解措施]

````

## 质量标准

- 每个任务必须可在单个context window完成（建议不超过200行代码变更）
- 每个任务必须有明确的verify方法，不能是"看起来对就行"
- Wave分组必须明确标注依赖关系
- 涉及外部输入、权限、数据库、文件上传、API、后台操作、长任务、第三方回调的任务，必须写明安全验证方法
- 安全验证不得只写"已检查"，必须指向具体风险：SQL注入、XSS、CSRF、权限绕过、文件上传、反序列化、敏感信息泄露
- `<security>` 节点禁止为空：涉及安全触发面必须写明验证方法，不涉及必须写明原因
- 任务summary必须记录偏差，不能假装一切按计划进行
- 失败任务必须说明原因，不能默默跳过
- 子 Agent 或并行任务输出必须经过主 Agent 复核后才能计入完成度，不能把“已返回结果”等同于“已验证完成”
- 优先"垂直切片"（端到端功能）而非"水平分层"（全部模型→全部API）

## 失败回退机制

| 步骤                   | 失败条件                                        | 回退目标                                | 最大重试 | 不可恢复时升级路径                          |
| ---------------------- | ----------------------------------------------- | --------------------------------------- | -------- | ------------------------------------------- |
| 第一步：需求分析       | 需求边界不清，隐含依赖未识别                    | 基于已知信息拆解，标注"依赖待确认"      | 1        | 输出需求澄清清单，等待用户补充              |
| 第二步：原子任务拆解   | 任务数量超出单次context window容量              | 按模块/资源域拆分为多个Wave集合         | 1        | 建议拆分为多个独立Spec驱动开发会话          |
| 第三步：Wave分组       | 任务间存在循环依赖                              | 识别循环并合并为单任务，或引入中间状态  | 2        | 输出依赖图，建议架构层面解耦                |
| 第四步：上下文隔离     | 任务上下文跨Wave污染                            | 强制重置context，仅加载previous_summary | 1        | 标注"上下文隔离失败"，建议人工接管          |
| 委派执行               | 子 Agent 接收到完整对话、模糊目标或缺少验收口径 | 收回任务，重写委派简报后再执行          | 1        | 标注"委派边界失败"，由主 Agent 重新分析任务 |
| 第五步：执行与验证闭环 | 验证连续失败3次                                 | 暂停执行，输出差异分析                  | 0        | 标记任务为"阻塞"，输出阻塞清单移交人工      |
| 第六步：记录到项目记忆 | 项目记忆系统不可用                              | 输出执行报告和决策到本地文件            | 1        | 标注"执行结果未沉淀"，提示用户手动保存      |

## 关联 reference

- **website-project**（网站项目总控）— 建站类需求拆解前先定义完整生命周期阶段和上线交付清单
- **software-project**（软件项目总控）— 非网站类完整项目拆解前先定义边界、架构、验证、发布和交付清单
- **spec-driven-development**（Spec驱动开发）— 拆解前用 `spec-driven-development` 确保需求已对齐
- **api-design**（API设计）— API/服务类任务拆解前先定义接口契约、认证、错误码和分页
- **frontend-design**（前端设计）— 页面/后台交互任务拆解前先定义组件、状态、响应式和浏览器验证
- **cms-development**（CMS二次开发）— CMS/PHP二开任务拆解前先确认CMS访问层、插件入口和兼容性
- **mysql-database**（MySQL数据库）— 数据库/SQL任务拆解前先定义表结构、索引、事务、迁移和回滚
- **code-generation**（代码生成）— 每个task可用 `code-generation` 实现具体代码
- **code-review**（代码审查）— 每个task完成后用 `code-review` 检查质量
- **test-generation**（测试用例生成）— 每个Wave完成后补充正常、异常、边界、回归、安全、性能和长任务测试
- **doc-generation**（文档生成）— 交付前生成README、API文档、部署说明和使用说明
- **project-memory-management**（项目记忆管理）— 将task summary和决策记录到项目记忆