Tapd Iteration Plan

TAPD 迭代规划

概述

本技能针对当前需求池中"approved"状态的需求进行全局优先级与规模评估，将规模合适 的需求按依赖关系编排进入指定迭代。规划过程遵循以下核心原则：

• 依赖优先：被依赖的需求优先入迭代，避免规划完成后无法启动开发
• 规模控制：单个迭代总 size 不超过上限（默认 1000）
• 重入安全：已有迭代重入时仅追加未规划需求，不影响已入迭代的需求
• 价值导向：在规模允许的前提下，优先编排高 size、高价值的需求

前置条件

• TAPD MCP 服务可用（需要 iterations_get、iterations_create、stories_get、stories_update 工具）
• 用户提供迭代名称
• 待规划需求需已完成评估（v_status="approved"）
• workspace_id 与 owner 可由用户提供，或从项目根目录 project.json 读取

输入

迭代命名规范

迭代名称必须遵循以下规范：

• 固定 iteration- 开头
• 版本号采用社区语义化规范 vMAJOR.MINOR.PATCH
• 默认 PATCH 位固定为 x（如 iteration-v0.1.x、iteration-v1.2.x）

示例：iteration-v0.1.x、iteration-v0.9.x、iteration-v1.0.x

执行流程

1. 参数收集与环境准备

1.1 校验迭代名称

用户输入消息中必须包含迭代名称 name。如果未提供，直接报错并终止：

错误：缺少迭代名称。请提供迭代名称（如 iteration-v0.1.x）后重试。

校验名称是否符合命名规范（iteration-vX.Y.Z 格式）。不符合时给出提示但继续 执行（仅作为警告）。

1.2 确定 workspace_id 与 owner

按以下优先级确定：

1. 用户消息中显式指定 → 直接使用
2. project.json 中的对应字段 → 使用 read_file 读取并解析
3. 以上均无 → 询问用户

2. 迭代查询或创建

2.1 精确查询迭代

使用 TAPD MCP iterations_get 精确查询：

调用参数:
  workspace_id: <workspace_id>
  name: <name>

2.2 分支判断

根据查询结果走不同流程：

分支 A：未找到迭代（新迭代流程）

使用 TAPD MCP iterations_create 创建新迭代：

调用参数:
  workspace_id: <workspace_id>
  name: <name>
  creator: <owner>
  startdate: <今日日期，YYYY-MM-DD 格式>
  enddate: <两周后的日期，YYYY-MM-DD 格式>

记录返回的 iteration_id。新迭代默认总规模上限为 total_size = size_limit。

分支 B：找到迭代（迭代流程重入）

记录迭代 iteration_id。使用 TAPD MCP stories_get 查询迭代下所有需求：

调用参数:
  workspace_id: <workspace_id>
  iteration_id: <iteration_id>
  limit: 200

统计已入迭代需求的 size 字段总和 workload_size，计算剩余可规划规模：

total_size = size_limit - workload_size

如果 total_size <= 0，告知用户该迭代规模已满，询问是否仍要继续规划（继续则 按用户提供的上限或忽略规模限制）。

3. 候选需求列表构建

3.1 自动筛选模式

如果用户未指定需求 ID，或者用户明确要求规划更多需求：

使用 TAPD MCP stories_get 拉取需求池中的"approved"需求：

调用参数:
  workspace_id: <workspace_id>
  v_status: "approved"
  with_v_status: "1"
  limit: 100

从查询结果中仅保留满足以下两个条件的需求：

• children_id == "|"（该需求没有子需求，避免规划"父需求壳子"）
• iteration_id == "" 或字段不存在（该需求尚未规划入任何迭代）

构建候选需求 ID 列表 candidate_ids。

3.2 用户指定模式

如果用户指定了需求 ID 列表：

逐一使用 TAPD MCP stories_get 查询需求详情，过滤掉以下需求：

• 已存在 iteration_id（已入其他迭代）
• children_id != "|"（有子需求的父需求壳子）

被过滤的需求需告知用户，列出 ID 与过滤原因，最终保留的列表作为 candidate_ids。

3.3 混合模式

如果用户既指定了需求 ID，又要求"再规划更多"，则两种模式合并：先处理用户指定 的需求，再追加自动筛选的需求。

4. 迭代规划

4.1 截取评估列表

从 candidate_ids 中取前 20 个 ID作为本轮评估列表 eval_list。20 是单轮处理 的合理上限，避免一次性 DAG 计算规模过大。

4.2 拉取详情与依赖扩展

对 eval_list 中每个 ID，逐一使用 TAPD MCP stories_get 获取详情：

调用参数:
  workspace_id: <workspace_id>
  id: <长ID>
  with_v_status: "1"

解析每个需求 description 字段中的"依赖关系"章节（参考 references/dependency-analysis.md 中的依赖识别规则），提取依赖的需求 ID。

对每个识别出的依赖需求：

• 使用 stories_get 获取详情
• 满足 children_id == "|" 且 iteration_id == "" 且 v_status == "approved" 的，追加进 eval_list
• 不满足条件的，记录为"外部依赖"，告知用户但不加入规划

4.3 构建依赖 DAG 与排序

针对 eval_list 中所有需求，构建有向无环图（DAG）：

• 节点：需求 ID
• 边：A 依赖 B 时，B → A（B 必须先于 A 完成）

排序规则（参考 references/dependency-analysis.md）：

1. 拓扑序优先：依赖链中位于上游的需求（被依赖方）排在前面
2. 同层 size 降序：同一拓扑层级内，size 大的排在前面
3. 优先级兜底：size 相同时，优先级高的排在前面

输出有序的入迭代列表 ordered_list。

4.4 逐个加入迭代

按 ordered_list 顺序逐个加入迭代。对每个需求：

调用 stories_update：
  workspace_id: <workspace_id>
  id: <需求长ID>
  iteration_id: <iteration_id>
  v_status: "todo"

每加入成功一个：

• total_size -= 该需求的 size
• 该需求从 candidate_ids 中移除
• 记录到 planned_list（用于最终汇总）

终止条件（满足任一即结束）：

• total_size <= 0（迭代已满）
• candidate_ids 已清空（无更多候选需求）
• 当前需求的 size > 剩余 total_size 时，跳过该需求继续尝试下一个； 若扫描完整个 ordered_list 中所有剩余需求均无法放入，加入结束。

5. 汇总输出

输出完整汇总：

## 迭代规划完成

**迭代信息**：
- 名称：<name>
- ID：<iteration_id>
- 模式：<新建 | 重入>
- 起止日期：<startdate> ~ <enddate>
- 规模上限：<size_limit>
- 已用规模：<size_limit - total_size>
- 剩余规模：<total_size>

**本次规划入迭代需求**（共 N 个）：

| 序号 | 需求 ID | 名称 | size | 优先级 | 依赖 |
|------|---------|------|------|--------|------|
| 1 | xxx | xxx | 80 | High | - |
| 2 | yyy | yyy | 120 | High | xxx |

**迭代核心目标**
<基于划入迭代的需求列出本次迭代的产品、特性的核心价值目标>

**未规划需求说明**：
- 因迭代规模已满，剩余 K 个候选需求未入迭代：[ID 列表]
- 因外部依赖未满足跳过：[ID 列表]

错误处理

参考文件

产出

• 已创建或复用的 TAPD 迭代单据
• 一批 v_status="todo" 且填入 iteration_id 的需求
• 控制台输出的规划汇总报告（含迭代信息、入迭代列表、未入迭代说明）

使用示例

示例 1：新建迭代并自动规划

用户输入：规划迭代 iteration-v0.2.x

系统处理：
1. 校验迭代名称符合规范
2. 从 project.json 读取 workspace_id 和 owner
3. iterations_get 查询未找到 → iterations_create 创建新迭代（今日 ~ 两周后）
4. 自动筛选 v_status="approved" 且 children_id="|" 且 iteration_id="" 的需求
5. 取前 20 个构建 DAG，按拓扑序+size 降序排序
6. 逐个调用 stories_update 入迭代，直到 total_size 用完
7. 输出规划汇总

示例 2：用户指定需求规划入已有迭代

用户输入：把需求 12345, 67890 规划进 iteration-v0.1.x

系统处理：
1. 校验迭代名称
2. iterations_get 找到已有迭代 → 统计已入迭代 size，计算剩余 total_size
3. 查询用户指定的两个需求详情，过滤掉已入迭代或有子需求的
4. 构建 DAG（含依赖扩展），排序
5. 逐个入迭代，输出汇总