| name | sh-save |
| description | 保存当前工作的会话交接上下文（session handoff）。当用户说'保存上下文'、'先记一下'、'帮我做个 handoff'、'准备切会话'、'compact 前存一下'、'sh-save'时触发。适用于把当前进展整理成可恢复的短期 handoff。 |
sh-save — 保存会话交接
你在做什么
把“这次会话做到哪了，下一次应该怎么接上”整理成一份短期交接文件，写入本地 memory/session-handoffs/。
这不是项目知识沉淀，也不是完整对话归档。
sh-save 负责短期 handoffsh-load 负责恢复 handoffkb-distill 负责把长期有效经验沉淀到 knowledge/projects/ 或 knowledge/resources/
优先使用仓库脚本
先用仓库脚本落盘，再基于结果做必要说明：
python3 scripts/session_handoff_save.py --topic "gateway migration" --current-goal "..." --done "..." --decision "..." --risk "..." --next-step "..."
如果用户明确给了 scope，优先使用：
python3 scripts/session_handoff_save.py --scope opensource-gateway-phase2 --current-goal "..." --next-step "..."
只有在脚本无法覆盖当前场景时，才手动编辑 handoff 文件。
如果本次保存表示“切换到这个事项继续干”，显式带上 --set-current yes。
如果只是后台记录、验收、测试或不想抢占默认 sh-load 入口，带 --set-current no。
存储结构
按 scope 存储：
memory/session-handoffs/
└── <scope>/
├── latest.md
├── meta.json
└── history/
└── YYYY-MM-DD-HHMM-<slug>.md
同时维护全局活跃事项索引：
memory/session-handoffs/_active.json
memory/session-handoffs/ 是本地短期状态，默认不提交到 Git。
scope 规则
优先级从高到低：
- 用户显式指定的
--scope
- 用户显式指定的
--topic，自动生成 ad-hoc_<topic-slug>
- 兼容旧习惯的
--req-id
--scope 会归一化成英文 slug；--topic 可以包含中文，无法转成英文 slug 时会自动追加短 hash，避免不同中文主题写进同一个 scope。
推荐格式：
- 项目：
opensource-gateway-phase2
- 临时话题：
ad-hoc_session-handoff-skills
输出目标
生成一份“最新稳定态” handoff，而不是流水账。
latest.md 只保留：
- 当前目标
- 已完成
- 关键决策
- 卡点/风险
- 下一步
- 相关文件
- 失效条件
全文控制在 250-400 字；如果超过，主动压缩。
latest.md 模板
# Session Handoff
> scope: <scope>
> updated_at: <YYYY-MM-DD HH:MM local>
> status: active
> source: sh-save
> supersedes: <snapshot-id or none>
## Current Goal
<一句话说明当前正在推进什么>
## Done
- <已完成的关键进展>
## Decisions
- <当前仍影响后续判断的决策>
## Risks
- <当前主要卡点、风险、待确认项>
## Next
- <下次恢复时优先执行的 1-3 步>
## Related Files
- `<path>`
## Expire When
- <什么条件下这份 handoff 失效>
空节不要保留。
长期层升级规则
以下内容不应只停留在 handoff：
- 明确技术决策
- 新发现的约束 / 踩坑
- 阶段推进
- 完成 / 暂停状态
出现这些内容时，优先用 kb-distill 写入：
- 项目相关：
knowledge/projects/<project-name>/
- 通用参考：
knowledge/resources/<scope>/
不要在 sh-save 里定义第二套长期知识格式。
不该做什么
不要：
- 粘贴大段对话 transcript
- 复制完整命令输出
- 把“观察到的暂时数据”写成长期结论
- 在 scope 不明确时自动改长期知识文件
- 因为用户说“保存一下”就强行沉淀到
knowledge/
完成后输出
简要说明：
- 写入了哪个 scope
- 是否更新了
latest.md
- 是否新增了 history 快照
- 是否同步升级了长期层
示例：
已保存 handoff 到 `memory/session-handoffs/opensource-gateway-phase2/`。
- 更新了 `latest.md`
- 新增 history 快照：`2026-04-24-2215-design-updated.md`
- 未同步长期层
