/checkpoint

会话进度存档 + 知识沉淀。从对话中提取知识归档到正确位置，覆写 HANDOFF.md，然后 git commit。

Checkpoint — 知识路由 + 会话存档

对话是知识产生的地方，/checkpoint 是知识持久化的统一收口点。

前置检查

执行前快速确认：

定位项目根目录 — HANDOFF.md 写入项目根目录（含 CLAUDE.md 或 .git/ 的目录）。如果无法确定，问用户。
检查 git 状态 — 运行 git rev-parse --is-inside-work-tree 2>/dev/null。如果不是 git 仓库，跳过 Step 5（git commit），其他步骤正常执行。
检查对话内容 — 如果本次对话没有产生任何值得归档的知识（如只是闲聊或简单问答），告知用户"本次对话无需归档"并退出，不强行走完流程。

步骤

Step 1: 知识提取 + 进度更新（只读分析，不写入）

回顾本次对话，识别值得持久化的内容。按以下类型逐项检查：

对话中发生了什么	归档到哪	格式
技术选型/架构决策	`docs/adr/{NNN}-{slug}.md`	标题 + 状态 + 上下文 + 决策 + 后果
技术调研、方案对比	`docs/research/{slug}.md`	标题 + 调研日期 + 各方案对比 + 结论
排查并解决了 bug	`docs/troubleshooting/{date}-{slug}.md`	症状 + 根因 + 修复 + 预防
确认了实施方案	`docs/plans/{slug}.md`	Status/Progress/Tasks 结构
功能完成/状态变更	`docs/features.md`	更新对应行
项目规则/架构变更	项目根目录的 `CLAUDE.md`（不是全局 ~/.claude/CLAUDE.md）	更新对应章节

不是每次都有所有类型——没有就跳过。 如果目标目录不存在，在归档时创建。

如果某类知识已在对话中通过专门 Skill（如 /tech-research、/debug）归档过，不重复归档。

Vault 回写建议（Query 反哺机制）：本会话是否产出了跨项目通用的洞察、方法论对比、概念澄清？如果是，建议入库到 ~/Vault/知识库/（对应子目录）并通过 /入库 执行，不要让有价值的对话成果消失在聊天历史中。只建议，不强制，等用户确认。

同时检查 docs/plans/ 中 Status 为 active 的方案文件，标记本次完成的任务（待写入）。如果 docs/plans/ 不存在或无活跃 plan，跳过。

输出归档清单（含 plan 进度变更），等待用户确认后再执行任何写入。

Step 2: 执行归档

用户确认后，批量执行：

写入归档文件 — 按目标类型分两条路径：
路径 A：4 类 Cell 走 Content OS 内核（plan / adr / research / troubleshooting，仅限新建）
按 @content-os/cli/SKILL-CLI-PROTOCOL.md §2 调用 new.mjs：
bash
```
node content-os/cli/new.mjs <<'EOF'
---
name: <slug>
type: <plan|adr|research|troubleshooting>
status: draft
created: <YYYY-MM-DD>
---

<body>
EOF
```
1
2
3
4
5
6
7
8
9
10
成功后从 KernelResult.data.path 取实际落盘路径。失败处理（退出码与 error code 标准动作表）见协议 §4 + §5。绝不绕过 kernel——不允许 Write/Edit / shell 重定向直接落到 4 类 Cell 路径。
字段提示：所有 4 类 Cell 显式带 status: draft（避开 ADR-020 schema/lifecycle 矛盾点；详见 docs/adr/ADR-020-schema-lifecycle-divergence.md）。
路径 B：其他文件直接 Write/Edit（CLAUDE.md / features.md / 各目录 README 索引）
这些不在 TYPE_ROUTES，超出 M2 内核覆盖范围，仍用 Write/Edit。
更新 plan 进度 — 勾选已完成任务（- [ ] → - [x]），更新 Progress: n/m。如全部完成，将 Status 改为 done。用 Edit 工具直接改（M2 内核暂不支持"更新已有 Cell"路径，lifecycle 没有 active→active 转换；这是已知摩擦点，留待后续 syscall 扩展）
更新索引 — 累积型目录（plans/、adr/、research/、troubleshooting/）写入后，如对应 README.md 存在则更新索引表；不存在则跳过

Step 2.4: 知识使用追踪（确定性回写）

目的：把本会话真实使用过的 Vault 知识卡的生命周期数据回写（use_count / last_used / heat），让沉淀的知识真正可观测。

原则：只回写本会话确实用 Read 工具打开过的 ~/Vault/知识库/ 下的文件——确定性事实，不回忆不猜测。没有就跳过整个步骤。

执行流程：

扫描本会话 Read 记录 — 回顾你在本会话中调用 Read 工具的所有路径，筛选前缀为 /Users/apple/Vault/知识库/ 的 .md 文件，去重。如果没有命中，直接跳到 Step 3，不做任何事。

输出候选列表 — 格式示例：

本会话引用的知识卡：
- 营销方法论/战略叙事-Raskin.md
- 技术积累/slide-creator-HTML演示生成.md
请确认是否全部回写 use_count（默认全部，可删）

用户确认后批量回写 — 对每张卡：
- use_count: N → use_count: N+1
- 新增或更新 last_used: <今天 YYYY-MM-DD>
- 按新的 use_count 和 last_used 重算 heat：
  - use_count > 0 且 last_used < 30 天前 → active
  - 30-90 天 → cooling
  - > 90 天 → dormant
  - use_count == 0 → unused
description 缺失提醒（收敛闭环）— 在回写的卡中，如果有卡缺 description 字段，单独列出：
```
⚠️ 这些刚用过的卡还没有 description，建议顺手写一句（参照 ~/Vault/知识库/_知识库宪法.md §5.1）：
- <路径>
```
1
2
只提醒，不强制补。
追加知识操作日志 — 在 ~/Vault/知识库/_knowledge-log.md 末尾用 Edit 追加（不覆写）：
```
## [YYYY-MM-DD HH:mm] checkpoint | N 张卡 | <一句话本会话主题>
```
1

边界约定：

没有 Read 过任何 Vault 卡 → 整个 Step 2.6 跳过
用户确认时删除了某些卡 → 不回写它们，但仍然追加 log（写实际回写数量）
回写过程中单张卡失败（如 frontmatter 损坏）→ 报告后跳过该卡，继续其余

Step 2.5: Memory Prune（条件触发）

触发条件：当前 workspace 的 MEMORY.md 行数 > 150。不满足则跳过。

触发时执行：

扫描 topic 文件 mtime — 列出 memory 目录下所有 .md 文件(排除 MEMORY.md)，按 mtime 排序
标记候选 — mtime 超过 90 天的标记为"降级候选"
检查 description 质量 — 对所有 topic 文件的 frontmatter description 做快速审查，标记模糊的（如"项目相关信息"）
输出 Prune 建议（不自动执行）：
- 降级候选列表（建议删除或归档到 Vault）
- description 改善建议
- MEMORY.md 索引中可压缩的行（描述过长、已过时的条目）
用户确认后执行 — 删除/归档确认的 topic 文件，更新 MEMORY.md 索引

不做的事：不自动删除任何 memory 文件，只给建议。

Step 3: 会话状态覆写

完全覆写项目根目录的 HANDOFF.md（不存在则创建），仅保留当前状态：

markdown

# HANDOFF
<!-- /checkpoint at {YYYY-MM-DD} -->

## Active Plan
{方案名} — `docs/plans/{slug}.md`（n/m, xx%）

## Session Tasks
- [x] {已完成任务，含文件路径}
- [ ] {待完成任务} → `{具体文件路径}` 或 `{具体命令}`

## Key Files
- `{file}` — {一句话说明}

## Next Actions
- [ ] {可执行的下一步，必须含文件路径或命令}

## Decisions Needed
- {需要人判断的悬而未决项}

5 字段校验（写入前必检）：

写入 HANDOFF.md 前，逐项检查以下 5 个字段：

字段	必填	无内容时处理
Active Plan	否	无正式 plan 时省略整节
Session Tasks	是	必须有至少 1 条（已完成或待完成），否则说明本次对话无实质进展，触发"无需归档"退出
Key Files	是	必须有至少 1 个文件路径
Next Actions	是	必须有至少 1 条可执行的下一步
Decisions Needed	否	无待决策项时省略整节

如果必填字段无法填写，不要写空壳（如 ## Key Files\n- 无），而是回退提醒用户补充信息。

其他写作约束：

Session Tasks — 每条待完成任务必须附带文件路径或命令，禁止"继续完善 XX"类模糊表述
Next Actions — 与 Session Tasks 分开。Session Tasks 是"本次会话的未完成项"，Next Actions 是"下次会话建议的起手动作"
行数上限 50 行 — 超过时优先砍 Session Tasks 中的已完成项（[x]），只保留最近 3 条；其次压缩 Key Files 为最关键的 5 个
覆写制 — 每次完全替换，历史通过 git log -p HANDOFF.md 回溯
不要累积历史 — 只保留本次会话的状态，不保留前几轮的 Completed 记录

Step 4: Git Commit

前置：如果前置检查确认不是 git 仓库，跳过此步骤。

bash

# 逐个添加归档文件，不要用 git add -A
git add HANDOFF.md docs/plans/*.md docs/adr/*.md docs/research/*.md  # 按实际改动的文件添加
git commit -m "checkpoint: {本轮简要描述}"

如果有 pre-commit hook 失败，修复问题后重新提交。不要用 --no-verify 跳过。

Step 5: 输出摘要

向用户输出：

归档了哪些知识（一句话列表）
commit hash（如有）
跳过了哪些步骤及原因（如有）
下次恢复命令：/handoff

IMPORTANT

4 类 Cell 必须走 kernel — plan / adr / research / troubleshooting 的新建必须通过 node content-os/cli/new.mjs；调用形态与失败处理见 @content-os/cli/SKILL-CLI-PROTOCOL.md。绝不绕过——不允许 Write/Edit / shell 重定向直接落到 4 类 Cell 路径（M2 硬约束，pre-commit hook 强制）
确认前不写入 — Step 1 只分析不写入，Step 2 在用户确认后才执行写入（含 plan 进度更新）
覆写而非追加 — HANDOFF.md 每次完全覆写，只保留当前状态，≤ 50 行
下一步必须可执行 — 含具体文件路径或命令，禁止"继续完善 XX"这种模糊指令
不用 git add -A — 逐个添加本次归档涉及的文件，避免误提交 .env 等敏感文件
不重复归档 — 已通过 /tech-research、/debug 等 Skill 归档的内容不再重复
CLAUDE.md 写项目级 — 更新项目根目录的 CLAUDE.md，不要写全局 ~/.claude/CLAUDE.md
空会话直接退出 — 对话没有产生值得归档的内容时，告知用户并退出，不强行走流程

/checkpoint ​

Checkpoint — 知识路由 + 会话存档 ​

前置检查 ​

步骤 ​

Step 1: 知识提取 + 进度更新（只读分析，不写入） ​

Step 2: 执行归档 ​

Step 2.4: 知识使用追踪（确定性回写） ​

Step 2.5: Memory Prune（条件触发） ​

Step 3: 会话状态覆写 ​

Step 4: Git Commit ​

Step 5: 输出摘要 ​

IMPORTANT ​