dev-resume

从检查点恢复

步骤 0：发现项目根目录

运行发现脚本：

bash "$DISCOVER" root

其中，$DISCOVER 是此技能目录中 scripts/discover.sh 的绝对路径。

路径安全 — 工具调用之间不会保留 shell 状态，因此每次调用都必须提供完整的脚本路径：

• 使用 $HOME，而不是直接写出主目录路径（例如，使用 bash "$HOME/code/…/discover.sh"，而非 bash "/Users/name/…/discover.sh"）。这样可以避免臆测用户名。
• 从工具输出中复制值。 重用前一条命令返回的值（例如 $PROJECT_ROOT）时，请从该命令的输出中原样复制。切勿凭记忆重新输入路径。
• 首次调用时验证：如果脚本调用因“找不到文件”而失败，说明路径有误——停止并根据技能加载上下文重新推导路径。
• 切勿忽略非零退出状态。 如果此技能中的任何脚本失败，请停止并在继续之前报告错误。

将输出保存为 $PROJECT_ROOT。如果命令失败，请告知用户并停止。

步骤 1：确定要恢复的功能

运行发现脚本以查找检查点：

bash "$DISCOVER" checkpoints "$PROJECT_ROOT" "$ARGUMENTS"

仅当用户提供了 $ARGUMENTS 时，才将其作为第三个参数传入；否则省略。

• 如果脚本以非零状态退出（没有 .dev/ 目录）：告知用户并停止。
• 如果输出为空：未找到检查点，询问要处理什么。
• 如果只有一行：将其用作 $FEATURE_DIR（包含检查点的目录）。
• 如果有多行：询问要恢复哪个功能。

切勿根据原始 $ARGUMENTS 构造路径。只能使用脚本输出中的路径。

选择后，使用验证脚本进行验证：

bash "$VALIDATE" checkpoint-path "$CHECKPOINT_PATH" "$PROJECT_ROOT"

其中，$VALIDATE 是此技能目录中 scripts/validate.sh 的绝对路径。遵循步骤 0 中的路径安全规则（使用 $HOME，从输出中复制）。成功时输出 $FEATURE_NAME；失败时，立即停止——不得继续使用未经验证的路径。

将 $FEATURE_DIR 设置为 $PROJECT_ROOT/.dev/$FEATURE_NAME。

步骤 2：通过 resume-context 加载上下文

调用一次 resume-context 即可——它取代之前的步骤 2–5（git-state、checkpoint-read、feature-show、有效性比较）：

node "$CLI" resume-context --json --dir "$FEATURE_DIR"

其中 $CLI 是此技能目录中 scripts/dev-workflow.cjs 的绝对路径。应用步骤 0 中的路径安全规则（$HOME，从输出中复制）。

解析 JSON 输出。它包含先前通过多次工具调用收集的所有数据：

• feature：{ name, status, progress {done, total, percent}, currentPhase {number, total, title} }
• checkpoint：{ context, nextAction, decisions[], blockers[], notes[] }
• validity："fresh" | "stale" | "drifted" — 预先计算的分支匹配和新鲜度检查结果
• validityDetails：{ checkpointBranch, currentBranch, checkpointUncommitted, currentUncommitted }
• currentPhasePrd：仅提取当前阶段的 Markdown 章节（不是完整的主计划）
• referenceFiles：主计划「Reference Files」章节中的文件路径
• sessionDigest：较早会话尾部的提炼摘要 — { sessionCount, consolidatedThrough, generated, aggregate, decisions[] } — 当某项功能达到整合阈值（≥10 个会话）后，由 /dev-checkpoint 写入。低于阈值或尚未生成摘要时为 null。
• recentSessionHistory：近期原始会话窗口（最近 N 个，默认 5 个；使用 --sessions=all 获取全部）。如果存在 sessionDigest，窗口之外的较早会话会被概括在其中。（取代原先的 sessionHistory 字段。）
• accumulatedDecisions：范围受限的决策集 — 存在 sessionDigest 时，为摘要中沿用的决策 ∪ 近期窗口中的决策（去重）；不存在摘要时，为所有会话中的完整去重并集（旧版行为）。

LLM 不再调用：git-state.sh、checkpoint-read --json、feature-show --json。它不再手动比较分支，也不再读取完整主计划（currentPhasePrd 仅包含相关章节）。

检查退出代码。 非零退出代码表示命令失败（例如，未找到功能目录或没有检查点）。绝不能忽略非零退出代码——如果 resume-context 失败，请停止并报告错误。不要尝试通过单独的工具调用重新收集数据。

步骤 3：检查上下文有效性

从 resume-context 输出中读取 validity 字段：

• fresh：分支匹配，检查点较新（距今 < 3 天）。正常继续。
• stale：分支匹配，但检查点较旧。显示信息性警告，然后继续。
• drifted：分支不匹配。发出警告并询问：「检查点位于 X，你当前位于 Y。切换还是继续？」继续前等待用户回复。

如果是 "drifted"，validityDetails 字段会提供提示中所需的两个分支名称。

步骤 4：提供恢复摘要

根据 resume-context 输出整理恢复摘要。这是不可替代的 LLM 步骤——CLI 负责执行操作，LLM 负责判断。

**Status**: [feature.currentPhase.title] — [feature.progress.done]/[feature.progress.total] ([feature.progress.percent]%)
**Last session**: [Derive from checkpoint.context field]
**Decisions**: [checkpoint.decisions, or "None recorded"]
**Session history**: [If sessionDigest present: "sessions 1–{sessionDigest.consolidatedThrough} consolidated into a digest + {recentSessionHistory.length} recent raw"; otherwise "{recentSessionHistory.length} sessions tracked"] — {accumulatedDecisions.length} decisions carried forward
**Feature arc**: [Only when sessionDigest present — summarize sessionDigest.aggregate so the distilled older-session history isn't lost. Omit this line entirely when sessionDigest is null.]
**Watch out for**: [checkpoint.blockers, or "Nothing flagged"]

**Current phase PRD**: [currentPhasePrd — summarize or reference; don't re-read the full master plan]

**Start with**: [First concrete action from checkpoint.nextAction field]

在相关时纳入 accumulatedDecisions——较早会话中的决策可能有助于理解当前步骤。存在 sessionDigest 时，应参考其中的 aggregate 来了解较早的历史，而不是依赖只涵盖最近几个会话的原始 recentSessionHistory 窗口。

等待用户确认——在用户确认之前不要继续。

步骤 5：处理差异

情况	操作
文件与检查点不一致	继续，并注明存在差异
关键文件缺失或已重命名	停止——询问如何继续
检查点中没有的新文件	继续，并提及这些文件
PRD 文件缺失	停止——没有 PRD 无法恢复

第 6 步：阅读关键文件和参考模式

开始工作前：

1. resume-context 中的 currentPhasePrd 字段包含相关阶段的内容 — 阅读该内容，无需阅读完整主计划
2. 使用 resume-context 输出中的 referenceFiles 确定要阅读哪些文件 — 这些是 PRD 推荐的参考实现
3. 阅读其中 2-3 个参考文件，并在新代码中遵循它们的约定（命名、结构、API、错误处理）
4. 可选：查看 $HOME/.dev-wiki/index.md，了解跨项目上下文（相关功能、先前实践）。如果文件不存在，请静默跳过。

如果代码库中已有类似代码，切勿从头编写新代码。

第 7 步：开始工作

确认后，执行 Agent 摘要中的第一个操作。遵循 PRD 的阶段和关卡。

重要：严格执行阶段关卡

完成某个阶段的工作后，运行 CLI，以机械方式验证关卡状态：

node "$CLI" gate-check --json --dir "$FEATURE_DIR"

其中 $CLI 是此技能目录下 scripts/dev-workflow.cjs 的绝对路径。

命令成功时始终返回退出码 0（出错时返回退出码 1）。检查 JSON 输出中的 atGate 和 allComplete 字段，以确定关卡状态。请使用这些字段确认阶段已完成，不要仅凭目测 Markdown 标记来判断。

每到一个关卡（无论是由 gate-check 检测到，还是由 PRD 中的 ⏸️ **GATE**: 标记指示）— 都必须立即停止：

1. 停止 — 不要进入下一阶段
2. 报告已完成的工作
3. 询问：“第 [N] 阶段已完成。继续进入第 [N+1] 阶段，还是使用 /dev-checkpoint？”
4. 等待用户明确回复后再继续
   • 如果 gate-check 返回 allComplete: true — 或者下一阶段是最终验证/测试阶段 — 在关卡问题后补充：“这是最后一个实现阶段。建议在最终测试前运行 /dev-review，生成 PRD 与实现的对齐报告。”

步骤级停止

完成某个阶段中的每个实现步骤后：

1. 报告已完成的工作
2. 询问：“步骤已完成。继续下一步吗？”
3. 等待确认后再继续

这样可以避免在当前任务尚未测试时就跳到下一项任务。

隐私规则

如果检查点/PRD 文件中包含以下内容，请提醒用户：带有用户名的绝对路径、机密/凭据或个人信息。