opsx-handover — 会话阶段收束与交接
定位
本 skill 维护 .agent/SESSION_HANDOVER.md，为下一次会话或下一位 AI 提供准确的恢复起点。
它不是单纯的“快速快照”工具，而是任务阶段收束入口：用户准备结束本次会话时，通常意味着当前任务告一段落，正适合判断是否需要先把稳定事实沉淀到长期文档。
三层分工：
| 层级 | 文件 / skill | 目的 |
|---|---|---|
| 现场 | .agent/WORKLOG.md / opsx-worklog |
当前任务进行中的短期现场 |
| 收束 | .agent/SESSION_HANDOVER.md / 本 skill |
结束当前会话，给下次会话提供入口 |
| 沉淀 | 项目级 CLAUDE.md / AGENTS.md + README / docs / opsx-tidyup |
长期项目知识 |
核心原则
- 自动判断是否需要
opsx-tidyup，不要默认把选择题抛给用户。 - 明确需要沉淀长期事实时，先执行 tidyup，再生成 handover。
- 明确不需要沉淀时，直接生成 handover。
- 只有判断不清、归属不明、需要创建新长期文档或可能越界时，才向用户确认。
.agent/SESSION_HANDOVER.md覆盖式写入，不追加历史。- 不记录 secrets、tokens、私钥或本地敏感配置。
判断纪律（判例）
- 判例「什么都沉淀」：本次只是解释、探索、查了个文件，模型却想把过程写进长期文档 → 错误。流水不是稳定事实，不进长期文档。
- 判例「什么都不沉淀」：本次定了一条项目规则、改了架构，模型图省事只写 handover 快照 → 错误。稳定事实必须先 tidyup，不能只留快照。
- 判断锚定读文件可验证：是否 tidyup，必须基于第一步已读到的 WORKLOG / 长期文档内容逐条列出候选事实，不凭会话印象拍脑袋。
执行流程
第一步：收集当前状态
读取或核验：
- 项目根
CLAUDE.md/AGENTS.md（按项目实际，哪个存在读哪个）。 .agent/WORKLOG.md（如存在）。- 当前会话中已完成事项、已改文件、未验证风险和下一步。
git status等能反映当前工作区真实状态的信息。
降级路径：.agent/ 目录不存在则创建；WORKLOG 不存在则跳过，以当前会话为准；非 git 仓库则跳过 git status，标注「无版本信息」。
第二步：判断是否需要先 tidyup
判断本次会话或 WORKLOG 是否产生了已稳定、长期有价值、未来读者需要知道的事实。
明确需要 tidyup 的信号：
- 新的项目级规则、原则、禁忌或经验教训。
- 架构、模块边界、数据流或技术选型出现稳定变化。
- README / docs 中的安装、运行、使用、接口、环境变量或运维信息已经过期。
- ROADMAP 中的事项完成、推迟、放弃或方向改变。
- 新术语、新约定、新对外接口需要未来读者知道。
.agent/WORKLOG.md中已有明确“未同步事实 / TBD”。
明确不需要 tidyup 的信号：
- 本次只是解释、探索、临时排查，没有形成稳定项目事实。
- 只做了局部小改动，未来读者不需要通过长期文档理解它。
- 稳定事实已经同步到对应长期文档。
需要询问用户的信号：
- 某条事实既可能是短期现场，也可能是长期规则。
- 写入目标不清，例如 PRINCIPLES 与 ARCHITECTURE 边界不明确。
- 需要创建新的长期文档，但创建门槛不确定。
- 继续 tidyup 可能超出用户本次收束范围。
询问时只问具体判断点，不给泛化菜单。例如：
> 我发现“<事实>”可能是长期项目规则，也可能只是本次任务现场。你希望我把它沉淀到 <目标文档>，还是只写入 handover 快照？
第二步·五：判断是否有跨项目可复用模式
判断本次会话是否产生了「跨项目可复用」的模式（抽象化后，别的 skill/插件/提示词研发也能用），区别于只对本项目有用的延续性事实：
- 有 → 按
references/pattern-candidate-template.md的四要素写一条候选，追加到你的模式库落点文件的「待验收」区（路径由使用者自定，见模板头部说明）；未配置模式库时跳过此步。 - 无 → 跳过，进第三步。
- 判断不清 → 并入第二步 tidyup 询问一起问，不单独打断。
第三步：执行 tidyup 或直接 handover
- 明确需要 tidyup：调用 / 执行
opsx-tidyup，完成后继续生成 handover。 - 明确不需要 tidyup：跳过 tidyup，直接生成 handover。
- 用户裁决后：按裁决继续，并在 handover 中记录结果。
第四步：生成交接文档
按 references/handover-template.md 覆盖写入 .agent/SESSION_HANDOVER.md。
写入时保持中文、简洁、可恢复。只保留下一次会话真正需要的信息，不积累流水账历史。
第五步：回复用户
简短说明：
- 是否执行了 tidyup，以及原因。
.agent/SESSION_HANDOVER.md已生成或更新。- 下一次会话最应该先做什么。
不做什么
- 不把普通总结当 handover。
- 不替代
opsx-worklog维护任务过程中的滚动现场。 - 不把长期项目知识只留在 handover；明确需要沉淀时应先 tidyup。
- 不主动修改
.clinerules、.cursorrules、AGENTS.md等平台规则文件。 - 不保留历史快照；历史交给 git 或项目文档。
已知限制（诚实条款）
- handover 模板的「来源平台」字段是占位符，生成时按实际运行平台填写：在 Claude Code 运行填
Claude Code，在 Codex 运行填Codex。不要照抄占位符，也不要一律写成 Claude Code。
