delivery-timeline

交付时间线

根据已完成的 milestones.yaml 生成交付时间线。询问交付参数（生产环境部署日期、QA 轮次、每轮 QA 的天数），为里程碑添加天数估算，并生成包含两个部分的 timeline.yaml：相对天数 timeline，以及以生产环境部署日期为锚点的实际日期 workback 计划。

前置条件

• 已完成 {base_directory}/implementation/milestones.yaml（/implementation-planner 的输出）

用法

/delivery-timeline [base-directory]

如果未提供目录，则通过查找当前目录中的 implementation/milestones.yaml 自动检测。

如果未找到，则提示用户：“你的规划产物位于何处？”

等待用户提供路径后再继续。将其存储为 base_directory。

流程

步骤 1：确定基础目录并加载里程碑

如果未提供目录参数，检查当前目录中是否存在 implementation/milestones.yaml。

• 如果找到，则将当前目录用作 base_directory
• 如果未找到，则提示：“你的规划产物位于何处？”并等待用户回复

确定 base_directory 后：

读取 {base_directory}/implementation/milestones.yaml，并提取每个里程碑的 id、name、dependencies 和 estimated_duration。

如果存在，也读取 meta.ordering_strategy。将其存储为 ordering_strategy。如果不存在，则默认为 foundation-first。

ordering_strategy 的值决定步骤 6 和步骤 7 中的结构差异：

• multi-pr：在开发时间线中，每个里程碑之后都插入 PR／审查／合并周期；步骤 7 中固定的 QA 前 PR 模块将被省略。
• 所有其他策略（single-feature-branch、value-first、risk-first、vertical-slice、foundation-first）：采用标准的单 PR 开发后流程（不改变当前行为）。

步骤 2：收集交付参数

向用户询问以下三个问题。可以在一条消息中一并询问：

1. 生产环境部署日期 — “你期望的生产环境部署日期是什么时候？（YYYY-MM-DD）”
2. QA 轮次 — “需要进行几轮 QA？”
3. 每轮 QA 天数 — “每轮 QA 应安排几天？”

如果用户提供的生产环境部署日期是星期六或星期日，请提醒用户：

“注意：[date] 是周末。你希望改为[previous Friday]还是[next Monday]？”

等待用户确认或更正后再继续。将确认的值存储为：

• production_deploy_date（ISO 8601 日期字符串）
• qa_rounds（整数 ≥ 1）
• qa_days_per_round（整数 ≥ 1）

步骤 3：将时长转换为天数

使用下表将每个里程碑的 estimated_duration 字符串转换为整数工作日：

estimated_duration	estimated_days
0.5 周	3
1 周	5
1.5 周	8
2 周	10
2.5 周	13
3 周	15
3.5 周	18
4 周	20
N 周	N × 5（向上取整到最近的整数天）

对于已用天数表示的时长（例如 5 days），直接使用该数值。

步骤 4：更新 milestones.yaml

为 {base_directory}/implementation/milestones.yaml 中的每个里程碑条目添加 estimated_days。不要修改其他字段。

示例 — 修改前：

- id: m0
  name: Foundation & Project Setup
  estimated_duration: 1 week

修改后：

- id: m0
  name: Foundation & Project Setup
  estimated_duration: 1 week
  estimated_days: 5

步骤 5：确定项目规模

将所有里程碑的 estimated_days 相加，计算 total_development_days。

大型项目：符合以下任一条件：

• total_development_days > 30
• 里程碑数量 > 5

大型项目默认进行两轮 QA 反馈，但此默认值会被步骤 2 中用户提供的 qa_rounds 值覆盖。is_large_project 仍会记录在摘要中，仅供参考。

步骤 6：构建开发时间线

从第 0 天开始，按依赖顺序为每个里程碑指定 completion_day。每个里程碑的 start_day 是其最后一个依赖项完成后的下一个工作日（如果没有依赖项，则为 0）。其 completion_day 为 start_day + estimated_days。

天数计算公式：

• 无依赖项：start_day = 0
• 有依赖项：start_day = max(dependency.completion_day) + 1（依赖项完成后的下一个工作日）
• completion_day = start_day + estimated_days

对于顺序里程碑链（每个里程碑都依赖前一个）：

m0: start_day=0, completion_day=0+estimated_days(m0)=5
m1: start_day=5+1=6, completion_day=6+estimated_days(m1)=16
m2: start_day=16+1=17, completion_day=17+estimated_days(m2)=27
...

对于并行里程碑（共享同一个依赖项），它们都在该依赖项完成后的下一天开始。它们共享同一个 start_day，但根据各自的 estimated_days 独立计算 completion_day。

标准策略（除 multi-pr 外的所有策略）

last_milestone_day = 所有里程碑中最高的 completion_day。

multi-pr 策略

每个里程碑之后、下一个里程碑开始之前，插入四个 PR 周期阶段。使用里程碑 ID 作为前缀（例如，对于 m0：m0-pr-creation、m0-pr-review、m0-review-feedback、m0-merge）。

id pattern	name pattern	estimated_days	notes
[milestone-id]-pr-creation	[Milestone Name] PR 创建	0	在里程碑的 completion_day 当天开启
[milestone-id]-pr-review	[Milestone Name] PR 审查	2
[milestone-id]-review-feedback	[Milestone Name] 审查反馈实施	2
[milestone-id]-merge	[Milestone Name] 合并	0	与审查反馈完成的当天相同

PR 周期会在每个里程碑之后增加 4 个工作日 的额外时间。下一个里程碑的 start_day = 其前一个里程碑的 merge 阶段的 completion_day + 1（在合并完成后的第二天开始）。

对于 multi-pr 策略下的顺序里程碑：

m0: start_day=0, completion_day=0+estimated_days(m0)=5
m0-pr-creation: start_day=5, completion_day=5          # 0 days, opens same day
m0-pr-review: start_day=5, completion_day=5+2=7
m0-review-feedback: start_day=7, completion_day=7+2=9
m0-merge: start_day=9, completion_day=9                # 0 days, merges same day

m1: start_day=9+1=10, completion_day=10+estimated_days(m1)=20
# ... repeat for each milestone

对于 multi-pr 策略下的并行里程碑，每个分支都有自己的 PR 周期。依赖多个并行前置里程碑的里程碑，在这些前置里程碑中最晚的 merge 阶段完成后的下一天开始（max(merge.completion_day) + 1）。

last_milestone_day = 所有里程碑中最后一个 [milestone-id]-merge 阶段的最高 completion_day。

步骤 7：追加开发后时间线

从 last_milestone_day 开始添加交付阶段项目。每个项目都有一个 start_day（工作开始的日期）和一个 completion_day（工作完成的日期）。estimated_days: 0 的项目会在开始当天完成。

使用步骤 2 中的 qa_rounds 和 qa_days_per_round 来安排 QA 部分。

QA 前固定阶段

**标准策略（multi-pr 以外的所有策略）：**包含下方完整的 PR／合并／部署阶段。这表示项目结束时的单次 PR。

id	name	estimated_days	notes
post-pr-creation	PR 创建	0	在最后一个里程碑当天开启
post-pr-review	PR 审查	2
post-review-feedback	审查反馈实施	2
post-merge	合并	0	与反馈实施同一天
post-deployment	部署	1

**multi-pr 策略：**省略 post-pr-creation、post-pr-review、post-review-feedback 和 post-merge——这些周期已在第 6 步按里程碑完成。直接从 post-deployment 开始。

id	name	estimated_days	notes
post-deployment	部署	1	所有里程碑合并后的最终部署

QA 阶段（每轮重复，轮次为 1..qa_rounds）

对于从 1 到 qa_rounds 的每一轮 R，使用 qa_days_per_round 作为 QA 截止期限的时长，生成以下阶段。使用对应轮次的 ID（例如 post-qa-r1-deadline、post-qa-r2-deadline）。当 qa_rounds == 1 时，ID 可以省略轮次后缀（例如 post-qa-deadline）。

id pattern	name pattern	estimated_days	notes
post-qa-rR-deadline	QA 截止期限（第 R 轮）	qa_days_per_round	分配给 QA 团队进行测试的时间
post-qa-rR-feedback-impl	QA 反馈实施（第 R 轮）	3 if (R == 1 and qa_rounds > 1) else 2
post-qa-rR-pr	QA PR（第 R 轮）	0
post-qa-rR-feedback	QA 反馈（第 R 轮）	2 if (R == 1 and qa_rounds > 1) else 1
post-qa-rR-merge	QA 合并（第 R 轮）	0

QA 后固定阶段（所有项目）

id	name	estimated_days
post-signoff	签核	1

第 8 步：制定倒推排期

从 production_deploy_date 开始倒推，将每个时间线项目（里程碑和交付阶段）映射到实际日历日期。

锚点：production_deploy_date = post-signoff 的 completion_day（时间线的最后一天，即 total_delivery_days）对应的实际日期。

**工作日计算：**倒推时跳过周六和周日。周一往前倒推一个工作日是上周五。

对于每个时间线项目：

• completion_date = production_deploy_date 往前倒推（total_delivery_days − item.completion_day）个工作日
• start_date = production_deploy_date 往前倒推（total_delivery_days − item.start_day）个工作日

project_start_date = production_deploy_date 往前倒推 total_delivery_days 个工作日（第 0 天）。

按相同顺序包含 timeline 中的所有项目。另追加一个 date: production_deploy_date 的最终条目 production-deploy。

第 9 步：生成 timeline.yaml

写入 {base_directory}/delivery/timeline.yaml。

如果目录不存在，则创建：

mkdir -p {base_directory}/delivery

输出格式

更新后的 milestones.yaml

每个里程碑条目都会新增 estimated_days 字段。所有其他内容保持完全不变。

timeline.yaml 架构

输出文档包含：version、project、generated、milestones_file、summary（总天数、项目规模、QA 轮次、交付模式）、timeline（里程碑和交付阶段，包含 start_day/completion_day/estimated_days），以及 workback（生产部署日期、项目开始日期、实际日历排期）。

完整的文档规范（包含所有字段、阶段类型和倒推计算规则）请参阅 references/output-spec.md。

完整示例请参阅 references/example.yaml。

输出示例

完整的时间线示例请参阅 references/example.yaml。

差距分析

生成 timeline.yaml 后，执行差距分析并在文内报告结果。

检查项

覆盖范围

• milestones.yaml 中的每个里程碑都出现在 timeline.yaml 中
• 所有里程碑依赖关系均得到遵守（没有里程碑在其依赖项完成前完成）
• 已在 milestones.yaml 的每个里程碑中添加 estimated_days

时长合理性

• 没有单个里程碑的 estimated_days: 0（标记以供审核）
• 没有里程碑超过 30 天却没有说明范围的备注
• 时长换算与步骤 2 中的表格一致

项目规模分类

• is_large_project 正确反映 total_development_days > 30 或 milestone_count > 5
• timeline.yaml 中的 QA 轮次与用户提供的 qa_rounds 一致
• 每个 QA Deadline 阶段均使用 qa_days_per_round 天

交付模式

• 已从 milestones.yaml 读取 ordering_strategy（或默认设为 foundation-first）
• timeline.yaml 摘要中的 delivery_model 与解析后的策略一致
• 对于 multi-pr：每个里程碑在时间线中都有对应的 [milestone-id]-pr-creation / pr-review / review-feedback / merge 区块；后续开发阶段中不包含 post-pr-creation 至 post-merge
• 对于所有其他策略：后续开发阶段中包含 post-pr-creation 至 post-merge；不存在按里程碑划分的 PR 区块

时间线完整性

• 按顺序推进的里程碑，其 completion_day 值严格递增
• 并行里程碑具有正确且相互独立的 completion_day 值
• 后续开发阶段紧接在 last_milestone_day 之后
• total_delivery_days = post-signoff 的 completion_day

倒排计划完整性

• project_start_date = production_deploy_date 减去 total_delivery_days 个工作日
• production-deploy 条目的日期与 production_deploy_date 一致
• 所有 completion_date 值均为工作日（周一至周五）
• workback.schedule 按相同顺序包含 timeline 中的所有条目
• post-signoff 的 completion_date = production_deploy_date

差距分析报告

生成文件后，输出简短的内联报告：

## Timeline Gap Analysis

**Project:** [name]
**Delivery Model:** [ordering_strategy]
**Total Development Days:** [n] ([n] weeks)
**Total Delivery Days:** [n] (including post-dev phases)
**Project Size:** [Small / Large] ([reason if large])
**QA Rounds:** [n] × [qa_days_per_round] days each
**Production Deploy:** [YYYY-MM-DD]
**Project Start:** [YYYY-MM-DD]

**Checks:**
✓ All [n] milestones included
✓ Dependency order respected
✓ Duration conversions applied
[✓ / ✗] estimated_days added to milestones.yaml
[✓ / ✗] QA rounds match user-specified value ([n] rounds)
[✓ / ✗] All workback dates land on weekdays
[✓ / ✗] post-signoff completion_date = production_deploy_date

**Issues:** [none / list issues]

**Recommendations:** [none / list recommendations]

如果发现问题，请询问：

“我发现以下时间线问题：

• [问题 1]
• [问题 2]

您希望：

1. 现在修复这些问题
2. 按当前时间线继续
3. 先手动调整估算，然后再生成”