用途
pod-checkpoint 用于在重置上下文窗口(运行 $clear)之前保存一份结构化恢复快照,写入 .cocoplus/lifecycle/checkpoint.md,从而保证之后执行 $pod resume 时能恢复到精确的工作位置。它不会创建 git 提交,快照会随下一个 CocoBrew 阶段提交一并纳入版本管理。
前置条件
- 必须先初始化 CocoPlus:.cocoplus/ 目录已存在(先运行 $pod init)。
- 该技能不接受任何参数。
主要能力(采集的状态)
- 校验初始化:检查 .cocoplus/ 是否存在,不存在则提示“CocoPlus not initialized. Run $pod init first.”并退出。
- 当前生命周期阶段:从 .cocoplus/lifecycle/meta.json 读取当前阶段、阶段 ID 与完成时间戳。
- 进行中的流程阶段:从 .cocoplus/flow.json 找到状态为 running 的阶段,或下一个 pending 阶段,记录阶段 ID、名称与检查点校验状态。
- 最近 5 条决策:从 .cocoplus/memory/decisions.md 提取最新 5 条(含 ID、简述、日期)。
- 待处理的必须修复项:从 .cocoplus/lifecycle/review.md(若存在)提取未解决的 must-fix 条目。
- 等待审批的 HITL 阶段:从 flow.json 中找出 hitl 为 true 且状态为 pending 的阶段。
- 已触发的 seeds:扫描 .cocoplus/seeds/*.yaml 中 status 为 triggered 的条目。
- CocoHarvest 状态:检查 .cocoplus/harvest/ 下带进行中阶段的 *-tasks.json,记录 harvest ID 与 agent 概要。
- 上下文占用评估:若 .cocoplus/meter/current-session.json 存在,按 token 累积估算占用率;数据不可用时该字段优雅省略(标记为 unavailable)。
- 写入快照:把上述状态写入 .cocoplus/lifecycle/checkpoint.md(若已存在则覆盖),包含 YAML 头(checkpoint_date、lifecycle_phase、phase_id、context_utilization)及分节正文:生命周期状态、进行中的流程阶段、最近 5 条决策、待处理必须修复项、HITL 待审批阶段、活跃 CocoHarvest 运行、已触发待提升的 seeds。
使用方式
- 运行 $pod checkpoint,按上述步骤采集并写入快照。
- 完成后向开发者输出确认信息,包括阶段、进行中阶段、捕获的决策数、必须修复项数、待审批 HITL 数、就绪 seeds 数,并提示下一步:先运行 $clear 重置上下文,再运行 $pod resume 从该检查点继续。
上下文接近 70% 时的恢复建议
当上下文占用 ≥70%,或由 CocoHealth 告警触发时,技能会用 git status --porcelain 与 git log --oneline -5 评估,并按矩阵追加建议:
- 无未提交改动、有近期阶段提交、任意检查点状态:从上次提交恢复。
- 有未提交改动(少于 20 行)、任意提交状态、有检查点:提交部分工作后恢复。
- 有未提交改动(≥20 行)、任意提交状态、有检查点:先 $clear 再 $pod resume。
- 有未提交改动、无近期提交、无检查点:紧急提交(使用 chore(recovery): emergency state preservation 信息)。
- 无未提交改动、无近期提交、无检查点:干净重启,以 .cocoplus/ 状态文件为恢复来源。
错误处理
- .cocoplus/ 未初始化:输出提示并退出,不创建检查点。
- meta.json 缺失:在检查点中注明“lifecycle phase unavailable”,继续执行。
- flow.json 缺失:注明“no pipeline active”,继续执行。
- 无法写入检查点文件:输出文件系统错误,不产生残缺文件。
限制与注意
- 该技能不会为检查点单独创建 git 提交。
- 部分状态不可用时仍应写入可用内容并标注缺失项,不应跳过整个文件。
- 写入检查点后不应阻止开发者继续工作。
适用场景
适用于使用 CocoPlus 生命周期管理、需要在长任务或上下文将满时安全中断并恢复的开发流程,尤其是涉及多阶段流程、HITL 审批、CocoHarvest 多 agent 运行的项目。