Progress Updater

进度更新器 (Progress Updater)

版本: 2.0.0 | 十步循环: D.1 架构: 双层任务架构支持 (tasks.md + detailed-tasks.yaml)

快速开始

我应该使用这个 Skill 吗？

使用场景:

• D.1: 任务完成后更新项目进度
• 需要更新 UPM 文档的 KPI 指标
• 需要标记任务为已完成
• 需要写入周期进度报告

不使用场景:

• 只需要查询进度 → 使用 state-scanner (A.0)
• 需要规划任务 → 使用 task-planner (A.2)
• 需要归档 Spec → 使用 openspec:archive (D.2)

核心功能

输入参数

执行流程

D.1.1 - 读取当前状态:
  - 调用 state-scanner 获取当前状态
  - 记录当前 stateToken (用于冲突检测)

D.1.2 - 准备更新数据:
  - 生成新的 lastUpdateAt (ISO 8601)
  - 构建 lastUpdateRef
  - 合并 kpi_updates 到 kpiSnapshot
  - 更新 risks 和 nextCycle.candidates

D.1.3 - 计算新 stateToken:
  → 详见 [STATETOKEN_SPEC.md](./STATETOKEN_SPEC.md)

D.1.4 - 写入周期文档 (可选):
  - 路径: docs/project-lifecycle/week{N}/
  - 创建 progress-report.md / quality-review.md

D.1.5 - 回写 UPM 文档:
  - 校验 stateToken 未被修改
  - 更新 UPMv2-STATE YAML 区块

D.1.6 - 双层架构后向同步 (可选):
  → 详见 [SYNC_RULES.md](./SYNC_RULES.md)
  - 如果提供了 spec_path
  - 执行三类冲突检测
  - 更新 tasks.md checkbox 状态

UPM 路径规则

stateToken 计算

完整算法: STATETOKEN_SPEC.md

快速参考

输入字段: module|stage|cycleNumber|lastUpdateAt|kpiSnapshot
算法: SHA256 → 取前 12 位
格式: "sha256:{12位哈希}"

示例:
  输入: mobile|Phase 4 - Development|9|2025-12-16T15:30:00+08:00|{...}
  输出: "sha256:a1b2c3d4e5f6"

并发冲突处理

完整规范: STATETOKEN_SPEC.md

快速参考

检测时机: 写入 UPM 前校验 stateToken

处理策略:
  策略 A - 重读-合并-重试 (推荐): 最多 3 次
  策略 B - 报告冲突: 重试失败后请求人工干预

双层架构后向同步

完整规范: SYNC_RULES.md

快速参考

同步方向: detailed-tasks.yaml → tasks.md

触发条件: 提供 spec_path 参数时

执行流程:
  1. 读取 completed 状态的任务
  2. 获取 parent 字段 (如 "1.1")
  3. 更新 tasks.md 对应 checkbox: [ ] → [x]

三类冲突检测

输出格式

成功响应

═══════════════════════════════════════════════════════════════
  PROGRESS UPDATE SUCCESSFUL
═══════════════════════════════════════════════════════════════

Module: mobile
Updated At: 2025-12-16T15:30:00+08:00

┌─────────────────────────────────────────────────────────────┐
│ State Changes                                               │
├─────────────────────────────────────────────────────────────┤
│ stateToken: sha256:abc123 → sha256:def456                   │
│ coverage: 87.2% → 89.5%                                     │
└─────────────────────────────────────────────────────────────┘

✅ Tasks Completed: 2
📋 Next Cycle Candidates Updated
📄 Cycle Documents: progress-report.md (created)

使用示例

基本进度更新

用户请求: "更新 mobile 模块进度"

输入:
  module: mobile
  commit_ref: "git:abc1234-完成图表组件"

输出:
  新 stateToken: sha256:def456

带 KPI 更新

用户请求: "更新进度，测试覆盖率提升到 89.5%"

输入:
  module: mobile
  kpi_updates:
    coverage: "89.5%"
    build: "green"

标记任务完成并同步 checkbox

用户请求: "标记任务完成并同步 tasks.md"

输入:
  module: mobile
  completed_tasks: ["TASK-001", "TASK-002"]
  spec_path: "changes/user-auth"

流程:
  1. 更新 UPM 文档
  2. 执行三类冲突检测
  3. 更新 tasks.md checkbox

错误处理

与其他 Skills 的协作

A.0: state-scanner ──▶ 读取当前状态
        │
A.1-C.2: 开发流程
        │
D.1: progress-updater (本 Skill)
        │
        ├─▶ 更新 UPM 文档
        ├─▶ 后向同步 tasks.md (可选)
        │
D.2: openspec:archive

检查清单

使用前

• 确认目标模块已初始化 UPM 文档
• 准备好 commit_ref (推荐)

使用后

• 确认 stateToken 已更新
• 确认 KPI 数据正确 (如有更新)
• 确认 tasks.md checkbox 已同步 (如使用后向同步)

子文件

• STATETOKEN_SPEC.md - stateToken 计算规范
• SYNC_RULES.md - 双层同步规则

相关文档

• 十步循环概览
• Phase D: Closure
• UPM 规范
• task-planner Skill
• state-scanner Skill

最后更新: 2025-12-23 Skill版本: 2.0.0 架构: 双层任务架构 (v2.0.0)