# Checkpoint

> 当用户显式调用 $checkpoint，需要把讨论状态保存到当前仓库，并跨会话、工具或智能体继续讨论时使用。

- Skill: `qianchengjie/checkpoint` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add qianchengjie/checkpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qianchengjie/checkpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: qianchengjie (https://skillmd.com/u/qianchengjie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qianchengjie/checkpoint

---


# Checkpoint

维护仓库内可跨会话恢复的单主题讨论活文档。

## 解析请求

- 使用用户提供的当前 Git 仓库相对 Markdown 路径；路径越出仓库时停止。
- 初次保存未提供路径时，根据主题在 `docs/checkpoints/` 下选择一个尚不存在的 Markdown 路径；其他请求缺少路径时询问用户。
- 从自然语言判断用户要保存还是恢复。两种语义都成立时先询问。

## 保存讨论

1. 目标文件存在时先完整读取；不存在时根据当前请求和讨论确定单一主题。
2. 只提取与该主题相关的当前目标、决策、分叉、非目标和载体。
3. 只有用户明确接受的完整决策命题才能进入“已确认决策”。用户确认方案只确认方案选择，不改变其中事实性前提的证据状态；完整表述同时包含决策和未验证的 agent 判断时，拆分记录，后者仍标为“AI 推断”。确认使用简写时，按当前适用指令解释简写并保存完整决策命题。
4. 把尚未确认的用户方案标为“候选”，把 agent 推导的内容标为“AI 推断”；把未裁决分叉保留在“待讨论问题”。
5. 按以上分类直接写入目标文件。新决定明确使旧决定失效时，直接修改或删除旧内容。
6. 写入后重新完整读取目标文件并做内部语义一致性检查：不得保留相反的当前结论；已裁决事项不得留在“待讨论问题”；被新决定替代的旧内容必须清理；同一当前有效决策不得存在多份完整正文。该检查不核验 checkpoint 外部事实或证据强度。检查完成后展示目标路径、检查结果、实际新增、修改、删除和结构整理的内容以及未决项；没有实际变化时明确说明。
7. 已进入 spec、plan、issue 等正式载体的决策仍保留完整内容，并附对应引用。
8. 不自动执行 `git add`、commit 或 push。

使用以下结构；空章节省略：

```md
# <讨论主题>

## 当前目标
## 已确认决策
## 候选与 AI 推断
## 已否决方案
## 待讨论问题
## 非目标
## 相关载体
```

在同一 checkpoint 内，“已确认决策”是当前有效决策完整正文的唯一落点；“当前目标”只保留摘要，其他章节只记录决策造成的边界或影响，不重复完整的条件、理由和结论。

候选和 AI 推断逐项标明类型。理由只保存讨论中已经出现的内容。原始措辞、否定范围或条件组合影响语义时保留用户原话。

讨论未收口时仍可保存。互相冲突且尚未裁决的说法同时进入“待讨论问题”。人工修改过的文件按语义理解。

## 恢复讨论

1. 目标文件不存在时报告路径并停止。
2. 完整读取目标文件，并只根据其内容按语义恢复。
3. 展示简短恢复摘要。按依赖关系提出最先阻塞后续判断的问题；问题互不依赖时提出文档中最前面的。
4. 没有待讨论问题时说明当前没有未解决项并停止。
5. 恢复本身只读；后续变化仍需用户再次显式保存。

恢复后若在普通讨论中实际发现 checkpoint 与其他载体冲突，展示双方内容并等待用户裁决；只暂停受影响的讨论分支。