🎯 学 gstack 的跨会话恢复机制：在新会话开始时（或手动触发时）恢复之前保存的工作状态——自动检出正确的分支、加载关键决策和下一步计划——让"今天继续昨天的工作"从记忆依赖变成自动化。 ⏱️ 预计时间：10 分钟
[!tip] 初学提示：本课内容虽短，但解决的"跨天断点续做"问题是 AI 辅助开发中最实用的功能之一，建议和上一课（会话记忆保存）一起学习。
[!quote]- 📖 原Skill精要 技能名称：context-restore 核心功能：恢复之前由 [[L6-46-会话记忆保存|context-save]] 保存的工作上下文。加载最新保存的状态（默认跨所有分支），让你从上次离开的地方继续——甚至跨 Conductor workspace 交接。每次 Skill 调用的 preamble 会自动检测并加载上下文。 所属体系：gstack 虚拟工程团队 协作关系：与 [[L6-46-会话记忆保存|context-save]] 配对，解决 AI 会话"空白上下文"的固有限制
§1 课程概览
[!info] 白话小课堂 一句话：你早上打开终端，Agent 自动读取昨天的检查点，告诉你"你上次做到了支付模块 handleRefund，微信审批还在等"——不需要你说一个字，Agent 已经知道从哪继续了。
为什么重要：context-save 保存了检查点，但如果恢复机制不顺畅，保存的价值就打了折扣。context-restore 的价值在于"自动化"——不是"你可以手动恢复了"，而是"Agent 在新会话开始时就自动恢复了"——把人的记忆负担转移给机器。
核心心法：恢复不是"读取文件"那么简单——恢复时必须做冲突检测（当前分支 vs 检查点分支是否一致？有没有未提交的变更？stash 了没？环境版本对不对？）。恢复的不是一段文字，是一个可安全接续的"工作环境"。
[!note] 类比：IDE 的"恢复上次会话" VS Code 关闭再打开时，会自动恢复你上次打开的文件、光标位置、甚至未保存的编辑。context-restore 做的事类似——但恢复的不是"文件标签页"，而是"整个开发上下文"：分支、决策、进度、阻塞项。
§2 结构拆解
核心特征
- 管理对象：检查点文件 → 可操作的工作上下文（分支切换 + 环境验证 + 进度加载）
- 核心原则：安全恢复优先 —— 永远不丢失用户的未提交工作
- 关键设计：
- 三级触发：自动（preamble 检测）、手动最新（/context-restore）、手动指定（/context-restore
）
- 冲突检测：分支不一致 + stash 检查 + 未提交变更 + 环境版本验证
- 进度时效验证：checkpoint 保存后文件是否被他人修改（git log 交叉验证）
- 跨工作区交接：Conductor workspace 间上下文传递
通用结构
输入层： → 触发方式（自动 preamble / 手动命令 / 手动指定文件） → 检查点目录：~/.gstack/projects/$SLUG/checkpoints/ ├── 自动恢复流程（preamble） │ ├── 扫描 checkpoints 目录，按日期排序找最新 │ ├── 解析结构化字段（Branch / Status / Done / Next / Decisions / Blocked by / Files） │ ├── 显示欢迎摘要（Welcome back! 进度 + 下一步） │ └── 等待用户确认后加载完整上下文 ├── 手动恢复流程 │ ├── /context-restore → 最新 checkpoint │ ├── /context-restore --list → 列出所有 checkpoint（带日期和任务描述） │ └── /context-restore
→ 指定 checkpoint ├── 冲突检测与处理 │ ├── 检测当前分支 vs checkpoint 分支（git branch --show-current） │ ├── 检测 git stash（git stash list） │ ├── 检测未提交变更（git status --short） │ ├── 检测环境版本（Node / Bun / Python 版本匹配） │ └── 冲突解决选项：A) stash → switch → pop / B) 忽略 / C) 查看 diff └── 进度时效验证 └── git log --since 检查 checkpoint 记录的文件是否被他人修改 输出层： → 恢复的 git 分支（自动检出或提示切换） → 加载的进度摘要（2-3 句） → 加载的下一步行动（1-3 条） → 环境不一致警告（如有）
§3 自动恢复机制深度解析
3.1 Preamble 检测：你什么都不用做
context-restore 最重要的设计决策是自动触发而非手动触发：
每次 gstack Skill 调用
→ preamble 执行
→ 自动扫描 ~/.gstack/projects/$SLUG/checkpoints/
→ 找到最新（按文件名日期排序）的 checkpoint 文件
→ 解析结构化字段
→ 如果找到 checkpoint → 显示 "Welcome back!" 摘要
→ 如果没有 checkpoint → 静默跳过
这个设计意味着：恢复不是"一个操作"，而是"一个环境"。就像你打开 IDE 时自动恢复上次的文件一样自然。
3.2 三种恢复模式
模式一：自动恢复（Preamble）
- 场景：每天早上打开终端继续昨天的工作——不想手动运行恢复命令
- Agent 自动告诉你"昨天你做到了这里"
模式二：手动最新恢复 (/context-restore)
- 场景：想切换工作上下文（从任务 A 切换到任务 B）
模式三：手动指定恢复 (`/context-restore
`)
- 场景：最新的 checkpoint 是"Google Pay 集成"但你想回到两天前保存的"支付宝集成"
/context-restore --list
# 列出所有 checkpoint:
# 2026-05-05-payment-alipay-integration.md — "支付宝集成（40%）"
# 2026-05-04-payment-wechat-refund.md — "微信退款模块（70%）"
# 2026-05-03-payment-wechat-integration.md — "微信支付基础（30%）"
/context-restore 2026-05-03-payment-wechat-integration.md
§4 恢复逻辑的安全检查与冲突解决
4.1 四层安全检查
context-restore 恢复时:
→ 读取 checkpoint 中的 Branch 字段 → "feat/wechat-pay"
→ 运行 git branch --show-current → "main"
→ 不匹配！→ 显示冲突警告
→ 运行 git stash list → 发现 2 个 stash
→ 显示: "You have 2 stashed changes."
→ 运行 git status --short → 发现 3 个 modified 文件
→ 显示: "You have uncommitted changes on main."
→ 检查 checkpoint 中是否有环境要求（如 "Node >= 20"）
→ 运行 node --version → "18.0.0"
→ 显示: "This checkpoint requires Node >= 20 but your workspace has Node 18."
4.2 安全优先原则与冲突解决流程
context-restore 的最高原则是：永远不丢失用户的未提交工作。
标准冲突解决流程：
context-restore 检测到冲突:
→ 显示: "You are on main with uncommitted changes.
The checkpoint is for feat/wechat-pay.
What should I do?"
→ 选项 A: 暂存 main 的变更 → 切换到 feat/wechat-pay → 继续 checkpoint 任务（推荐）
git stash push -m "context-restore: saved from main before switching to feat/wechat-pay"
git checkout feat/wechat-pay
# 展示 checkpoint 进度...
# 完成后：
git checkout main
git stash pop
→ 选项 B: 忽略 checkpoint，保持在 main 继续当前工作
→ 选项 C: 查看 main 上的未提交变更详情（git diff）
核心原则：git stash 是安全的暂存机制——变更被保存而非删除。
§5 电商 Skill 案例：跨会话电商项目上下文恢复——支付模块Day 2
🛒 实战案例：接L6-46的支付模块开发场景。第二天开发者打开新会话，context-restore自动检测到checkpoint并恢复完整的开发上下文。微信商户号审批已通过，沙箱环境也配置好了——从30%继续推进到70%。
- 自动恢复流程（preamble触发）：新会话启动→preamble自动扫描
~/.gstack/projects/mega-shop/checkpoints/→检测到最新checkpoint2026-05-03-payment-wechat-integration.md→显示："Welcome back! You were working on the WeChat Pay integration. Progress: 30% — createOrder and verifyPayment done. Next: handleRefund (blocked by WeChat merchant approval). Branch: feat/wechat-pay (you're already on this branch). Would you like to see the full checkpoint?"→用户确认。- 上下文注入与决策继承：Agent读取checkpoint全量内容→注入到当前会话上下文。关键信息继承——Decision"金额以分为单位"→Agent继续使用INTEGER存储金额（9900=99.00元），不会重新询问"金额单位是分还是元"；Dead End"数据库事务做幂等不可行"→Agent在实现handleRefund的退款回调幂等时直接使用去重表方案，不会重新尝试事务方案；Blocked by→Agent第一步不是开始写代码，而是检查"商户号审批是否已通过"→用户回复"已通过，沙箱环境也配置好了"→Agent开始handleRefund实现。
- git状态安全检查：Agent在恢复前检查git状态——当前branch
feat/wechat-pay与checkpoint branch一致→安全恢复；如果有未提交变更→提示用户决定(stash/commit/abort)；如果当前在别的branch→checkout到feat/wechat-pay并检查远程跟踪状态。这个检查防止"上下文不一致"——在错误的分支上盲目加载支付模块的上下文会导致后续操作混乱。- Day 2进展与再次保存：Agent基于checkpoint上下文顺利实现handleRefund()——退款创建(
POST /api/payment/refund→创建refund_task→入队Bull队列→Worker调用微信退款API→处理退款回调→更新订单状态REFUNDED→通知用户)→运行17个已有测试+新增8个退款测试→全部通过。运行/context-save→进度更新为70%——Done增加handleRefund() with refund idempotency、Next: 对账模块(reconciliation)与微信账单下载集成。
🔑 启示：context-restore的价值在"决策继承"而非"信息传递"。如果恢复只是告诉Agent"进度30%，下一步handleRefund"，Agent会重新询问"金额单位是什么？幂等用什么方案？"——这等于重新开始了。但checkpoint中的Decisions/Dead Ends让Agent获取的不是信息而是决策结论——它不需要重新决策，它继承了之前的决策并直接执行。信息的价值是线性的，决策的价值是指数的。
[!info] 参考来源 上下文恢复的会话连续性理念参考了 Obsidian daily notes 的断点续写模式和 tmux resurrect 的工作区恢复机制。
§6 掌握检验
Q1：context-restore 的自动恢复机制在什么时机触发？
- A) 只在用户手动运行 /context-restore 时
- B) 每次 Skill 调用的 preamble 自动检测并加载最新的 checkpoint——显示 "Welcome back! You were working on..."
- C) 每天凌晨自动触发
- D) 只在 git commit 时触发
Q2：context-restore 恢复时需要检查 git 状态（当前 branch vs checkpoint branch，是否有 git stash）——为什么这个检查很重要？
- A) 只是形式检查，没有实际作用
- B) 防止"上下文不一致"——如果当前 branch 与 checkpoint branch 不同（用户在别的分支上做了别的工作），盲目加载 checkpoint 的上下文会误导 Agent 以为它在错误的上下文中操作；如果有 stash，说明有未保存的工作可能丢失
- C) GitHub 强制执行这个检查
- D) 为了生成更长的恢复报告
Q3：context-restore 支持三种恢复方式：自动（preamble）、手动最新（/context-restore）、手动指定（`/context-restore
`）。请各给出一个场景，说明为什么这三种方式都需要——不能只用一种方式。
Q4：如果 checkpoint 记录了 "Branch: feat/wechat-pay"，但用户当前在 main 分支上且 main 有未提交的变更。context-restore 检测到这个冲突时，应该如何处理？请设计一个安全的冲突解决流程——不能丢失用户当前在 main 上的未提交变更。
Q5：context-restore 恢复后显示"Progress: 30% — createOrder and verifyPayment done. Next: handleRefund"。但这个进度信息是两天前保存的——在这两天中，可能有其他 Agent 或开发者已经推进了进度。Agent 如何验证"checkpoint 中的进度信息仍然准确"——如果一个文件在 checkpoint 后已经被别人修改了，Agent 应该信任 checkpoint 还是信任 git log？
Q6：在 Conductor workspace 交接场景中，Agent A 在工作区 A 中保存了 checkpoint，Agent B 在工作区 B 中恢复了 checkpoint。但工作区 A 和工作区 B 可能有不同的环境配置（如不同的 Node 版本、不同的环境变量）。context-restore 除了恢复"代码上下文"外，是否也应该恢复"环境上下文"？如果 checkpoint 中包含"Node >= 20 required"，但工作区 B 安装的是 Node 18——Agent B 恢复 checkpoint 后运行的第一步应该是什么？
§7 答案
点击查看答案
Q1：B —— 每次 Skill 调用的 preamble 自动运行 context-restore 检测。
Q2：B —— 上下文一致性的基础是"你在正确的文件上操作"。
Q3：自动（preamble）——场景：你每天早上打开终端继续昨天的工作——你不想手动运行恢复命令，Agent 应该自动告诉你"昨天你做到了这里"。手动最新——场景：你想切换工作上下文（从任务 A 切换到任务 B）——你手动运行 /context-restore 加载最新的 checkpoint（可能是任务 B 的）。手动指定——场景：最新的 checkpoint 是 Agent A 保存的"Google Pay 集成"但你想回到 Agent B 两天前保存的"支付宝集成"（因为你今天要接着做支付宝）→ 你从列表中选中那个特定的 checkpoint 恢复。
Q4：冲突解决流程：context-restore 检测冲突 → 显示："You are on main with uncommitted changes. The checkpoint is for feat/wechat-pay. What should I do?" → 提供选项：A) 暂存 main 的变更（git stash）→ 切换到 feat/wechat-pay → 继续 checkpoint 任务（推荐）；B) 忽略 checkpoint，保持在 main 继续当前工作；C) 查看 main 上的未提交变更详情。如果用户选择 A → git stash push -m "context-restore: saved from main before switching to feat/wechat-pay" → git checkout feat/wechat-pay → 显示 checkpoint 进度 → 完成任务后 → git checkout main → git stash pop。核心原则：永远不丢失用户的未提交工作——git stash 是安全的暂存机制。
Q5：Agent 应该信任 git log 而非 checkpoint——checkpoint 是人/Agent 在某个时间点的快照，git log 是代码的真实历史。验证流程：Agent 读取 checkpoint 中的 Files 列表（如 src/payment/wechat.ts）→ Agent 运行 `git log --oneline --since="2 days ago" --
` 检查这些文件在 checkpoint 保存后是否有新的 commit → 如果有 → Agent 显示："Note: src/payment/wechat.ts has been modified since the checkpoint was saved (2 commits by user X). The checkpoint progress may be out of date." → 读取最新的文件内容（而非 checkpoint 中的描述）→ 基于最新代码 + checkpoint 中"未完成的任务"来判断当前真正的进度。
Q6：context-restore 应该检测但不自动修复环境上下文。检测：checkpoint 中包含 ## Environment: Node >= 20, bun >= 1.0 → Agent B 恢复时运行 node --version 和 bun --version → 发现 Node 18 < 20 → 显示警告："This checkpoint requires Node >= 20 but your workspace has Node 18. Some features may not work. Install Node >= 20 first?" Agent B 的第一步：不是读取代码，而是验证环境是否满足 checkpoint 的最低要求——如果环境不满足 → 先解决环境问题 → 再恢复工作。这就像你接手同事的代码时首先跑 npm install 确保依赖正确——环境一致性检查是跨工作区交接的前提条件。
（5/6 通过）
延伸阅读
- [[L6-46-会话记忆保存|上一课：会话记忆保存]]
- [[L6-48-项目知识积累|下一课：项目知识积累]]
- [[L6-49-经验Skill化|进阶：经验Skill化]] —— context-restore 恢复的进度可以成为 skillify 提取操作模式的来源
评论区
共 0 条评论