# Session Archive Checker

> 在用户明确要求“这个会话能归档吗”“归档前检查”或手动调用本 Skill 时使用。检查当前会话的未完结事项、任务产生的临时文件及相关 Git 变更，只给出归档建议和待处理清单，不执行清理或归档。

- Skill: `subtlespark/session-archive-checker` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add subtlespark/session-archive-checker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/subtlespark/session-archive-checker/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SubtleSpark (https://skillmd.com/u/subtlespark)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/subtlespark/session-archive-checker

---


# 会话归档前检查

判断当前会话是否已经收尾，而不是审计整个项目。工作区“干净”指本会话相关变更已妥善处理，不要求整个仓库的 `git status` 为空。

## 只读边界

只读取可用会话历史、文件、Git 状态和已有验证结果。不要删除或修改文件、生成报告文件、修改忽略规则、暂存、提交、回滚、切分支、stash、fetch、push，也不要重命名或归档会话。不要为补齐验证而执行测试、构建、格式化或其他可能产生写入的命令；将缺失验证列为待处理。需要清理时仅给建议，执行属于另一个任务。

## 1. 确定范围与证据

- 按用户最新明确意图梳理本会话的全部任务、验收要求、已完成内容与遗留事项；不要只检查最后一个任务。
- 优先使用用户要求、会话中的工具操作及当前可验证状态。不要仅凭助手说“完成”、会话闲置时间或干净的 Git 状态判定完成。
- 确认任务所在目录及实际 Git worktree；对本会话实际操作过的路径识别其所属 Git 仓库。即使外层仓库状态干净，或该路径被外层仓库忽略，也不能据此认为内部仓库已收尾；如果该路径属于另一个 Git 仓库，应单独检查。不要为此递归扫描所有被忽略目录，只检查本会话实际触达的路径。
- 只使用确实可访问的历史；不要假装能读取全部旧消息，也不要遍历其他会话记录。历史被截断、工作区不可访问或检查失败，且缺失证据影响判断时，记录为“需要确认”。
- 用户只要求检查某个子任务或只检查 Git 时，明确标注“局部检查，不能据此判断整个会话可归档”。未发现明确阻塞项时，整会话结论仍为“需要确认”，不能输出“可归档”。

## 2. 检查未完结事项

查找尚未满足的用户要求、约定但未执行或失败的验证、当前范围内的 TODO、阻塞项，以及承诺执行但没有实际完成的动作。已有失败被后续有效验证解决时，不再算遗留项；通过结果必须对应相关版本，不能拿旧版本通过记录替代当前验证。

取消、明确放弃、接受限制或已明确移交到其他 issue / PR / 人员的工作不算本会话未完成，但要说明去向。仅存在一个 PR 不等于已经移交。暂停、等待条件恢复但仍需本会话继续的任务仍未完成。可选优化、未采纳的建议和项目原有 TODO 不自动成为阻塞项。

## 3. 检查文件与 Git 变更

先根据会话中的创建/修改操作列出相关路径，再做定向检查。检查交付物、一次性脚本、日志、测试数据及中间产物，包括历史中明确提到的已忽略文件或仓库外文件；不要递归扫描整个磁盘或全部构建缓存。

归属判断优先看会话操作记录、已知起始状态和具体 diff。仅凭文件名、时间戳或 Git 状态不能认定归属。明显无关的修改排除；可能涉及本任务且影响收尾、但归属不明的变更才需要确认。一个文件混有多任务修改时按变更片段判断，不把整个文件都算成本会话产物。

在已确认的仓库中按需使用以下只读命令。`repo` 是实际仓库路径，`path` 是要检查的仓库相对路径；不是 Git 仓库时跳过，不把“非 Git 项目”本身当作问题。

```bash
git --no-optional-locks -c core.fsmonitor=false -C "$repo" rev-parse --show-toplevel
git --no-optional-locks -c core.fsmonitor=false -C "$repo" status --short --untracked-files=all
git --no-pager --no-optional-locks --literal-pathspecs -c core.fsmonitor=false -C "$repo" diff --no-ext-diff --no-textconv -- "$path"
git --no-pager --no-optional-locks --literal-pathspecs -c core.fsmonitor=false -C "$repo" diff --cached --no-ext-diff --no-textconv -- "$path"
git --no-optional-locks -c core.fsmonitor=false -C "$repo" check-ignore -v -- "$path"
```

`check-ignore` 返回 1 表示没有匹配规则，不是检查故障。Git diff 不显示未跟踪文件内容，需要时只读取相关文件；避免运行外部 diff、textconv 或文件监视器。状态已被后续操作改变时，以当前证据为准。

逐项给出处置建议及依据：

| 建议 | 判断条件 |
| --- | --- |
| 保留 / 已妥善处理 | 正式交付物已按约定保存，或用户明确要求保留当前状态（包括未提交状态）。不能自行假设用户打算稍后处理。 |
| 建议提交 | 本会话的有效源码、测试或文档应受版本控制，但仍未提交且没有明确的保留理由。暂存不等于提交。 |
| 建议删除 | 有证据属于本会话、用途已结束的一次性产物；生成文件和未跟踪文件不必然是垃圾。 |
| 建议忽略 | 应持续保留在本地、按项目约定不应入库的生成物，且没有适用规则。已跟踪文件不能仅靠新增忽略规则解决。 |
| 需要确认 | 影响本次收尾，但用途、归属或最终处置无法可靠确定。 |

已忽略不等于无需清理：不再需要的一次性日志即使被忽略，也可能是遗留项。相反，有明确保留用途的正常忽略产物不必删除。提交、push 或 PR 合并不是统一要求，按本次约定判断。

## 4. 判定与报告

按以下优先级输出且只输出一个整会话结论：

1. **暂不建议归档**：存在明确未完结事项，或明确待处置的本会话文件 / Git 变更。
2. **需要确认**：没有明确阻塞项，但存在影响结论的证据缺口、归属/处置疑问，或仅完成局部检查。
3. **可归档**：本会话范围已检查，未发现上述阻塞项或重要不确定项。

明确阻塞项与不确定项并存时使用“暂不建议归档”，并分别列出两类事项。遇到混合修改、局部检查或忽略产物等容易误判的情况，按需读取 [边界案例](references/examples.md)，不要无条件加载或扩展成全仓库审计。

采用以下简短格式；只列影响判断的信息，路径、相关操作或验证结果应能支撑结论。不要输出凭证、令牌或无关文件内容。

```markdown
## 会话
<用途与当前进度，1–3 句话；注明检查范围及重要证据缺口>

## 结论
**可归档 / 暂不建议归档 / 需要确认**
依据：<用 1–2 句话说明支撑结论的关键事实，例如任务完成情况、相关文件 / Git 状态或证据缺口；不复述检查过程，不重复待处理清单。>

## 待处理
<没有则写“无”；有则逐项列出：事项或路径 — 观察到的状态 — 建议 / 待确认的问题>

## Git / 文件
<本会话相关变更及已确认的保留理由；未检查写“未检查”，不能写成“未发现”>
```

只有有助于解释结论时才补充“不纳入本次判断”，简述明显无关的修改。报告建议，不声称已经执行清理，也不为了填模板制造待办。