SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场save-session

save-session

办公与效率

查看项目

更新于 10-16 07:06

技能介绍

save-session 是一个战术检查点技能，用于在会话边界保存临时上下文，写入项目根目录旁的 .session/CURRENT.md。

用途

该技能存在的目的是保留持久文档通常省略的临时上下文：操作者当时正在做什么、下次应先做什么、哪些内容已经验证过，以及交接时哪些少量本地文件或提交是重要的。它防止一种常见的会话边界失败模式：下一个智能体能看到文件和 git diff，却看不到确切的战术意图或最佳下一步。紧凑的仓库本地检查点比从头重建上下文更便宜、更可靠。

主要能力

  • 将检查点写入 .session/CURRENT.md，与项目根目录下的程序计划、跟踪和编排状态并列。
  • 通过全局 shell 命令 save-session 执行确定性写入；成功证据是命令打印检查点路径，文件存在且时间戳新鲜，并包含明确的 codex_goal 段落。
  • 支持通过环境变量传入精心整理的交接内容，优先于推断的文件系统最近性。
  • 支持显式 Codex 目标保存与恢复策略：ensure-active 或 reference-only。
  • 支持自动恢复资格窗口 SAVE_SESSION_RESUME_WINDOW_HOURS，范围 1–168 小时，默认 24 小时。
  • 当会话暴露可预防的摩擦时，先运行 session-introspection，并将最高价值的预防控制保存到检查点。

使用方式

基本调用：

save-session

更丰富的调用示例（通过环境变量传入上下文）：

SAVE_SESSION_HANDOFF_FOCUS="Resume from the last validated result, not from broad repo discovery." \
SAVE_SESSION_GOAL_OBJECTIVE="Complete the exact accepted objective without shrinking its exit gate." \
SAVE_SESSION_GOAL_RESUME_POLICY="ensure-active" \
SAVE_SESSION_WORKING_ON="Tightening save/resume checkpoint quality so next-session context stays small and actionable." \
SAVE_SESSION_NEXT_ACTION="Run the save-session validation script, regenerate CURRENT.md once, inspect it for noise, then commit the skill change in ~/.codex." \
SAVE_SESSION_BLOCKERS="None." \
SAVE_SESSION_LEARNINGS="Recent-file inference polluted checkpoints with cache/db artifacts; require curated relevant files instead." \
SAVE_SESSION_VERIFICATION_STATE="Wrapper patched; validation still pending." \
SAVE_SESSION_INTROSPECTION="session-introspection: prevent future noisy checkpoints by preferring curated handoff fields over filesystem recency." \
SAVE_SESSION_RELEVANT_FILES="$(printf '%s\n' "$HOME/.codex/skills/save-session/SKILL.md" "$HOME/.local/bin/save-session")" \
SAVE_SESSION_AVOID="Do not include cache files, generated DB files, broad untracked status, or historical discussion not needed for the next action." \
save-session

主流程包括：预检（在仓库内用 git rev-parse --show-toplevel 解析目标根，否则用当前工作目录；通过 session-orchestrate/scripts/session_workspace.py 确保共享 .session/ 工作区；若存在可预防摩擦先运行 session-introspection；优先使用已安装的 save-session shell 命令，不可用时仅用 Bash 复现其行为）；调用 get_goal 并传入精确目标；通过环境变量传入精心整理的上下文；执行写入。

支持的环境变量包括：SAVE_SESSION_ROOT、SAVE_SESSION_GOAL_OBJECTIVE、SAVE_SESSION_GOAL_RESUME_POLICY、SAVE_SESSION_RESUME_WINDOW_HOURS、SAVE_SESSION_HANDOFF_FOCUS、SAVE_SESSION_WORKING_ON、SAVE_SESSION_NEXT_ACTION、SAVE_SESSION_BLOCKERS、SAVE_SESSION_LEARNINGS、SAVE_SESSION_VERIFICATION_STATE、SAVE_SESSION_INTROSPECTION、SAVE_SESSION_RELEVANT_FILES、SAVE_SESSION_RELEVANT_COMMITS、SAVE_SESSION_AVOID、SAVE_SESSION_USEFUL_COMMANDS、SAVE_SESSION_ROUTE_ID、SAVE_SESSION_ROUTE_OWNER、SAVE_SESSION_FIRST_COMMAND、SAVE_SESSION_STOP_CONDITION、SAVE_SESSION_ALLOWED_BEFORE_FIRST_COMMAND、SAVE_SESSION_AVOID_BEFORE_FIRST_COMMAND。默认有意省略原始 git status；仅当原始状态本身对下一个智能体有用时设置 SAVE_SESSION_INCLUDE_GIT_STATUS=1。

适用场景

  • 会话结束或任务交接时，需要让下一个智能体快速接续。
  • 当前任务有未完成、应在新任务中继续的 Codex 目标。
  • 已知下一条工作路线，需要保存路由负责人、首条命令和停止条件，避免通过宽泛发现重新开始。
  • 会话暴露了可预防的摩擦，需要将预防控制写入检查点。
  • 多文档、路由面、AGENTS 文件、工作流、技能或持久决策被触及，需要扫描陈旧或重复路由。

限制与规则

  • 战术写入，而非永久文档；检查点仅用于交接上下文，不是长期项目记忆。
  • 优先仓库根目录；存在 git 根时存储于该处，便于未来会话可预测地找到。
  • 保持简洁，检查点应指导下一步，而非重建整个会话。
  • 实际写入使用 Bash；确定性命令是文件创建的真相来源。
  • 优先精心整理的上下文而非推断上下文；自动检测文件和原始状态是回退诊断，不是交接内容。
  • 已知路线需要首条命令；若设置了 SAVE_SESSION_FIRST_COMMAND 且未提供显式 SAVE_SESSION_NEXT_ACTION，包装器必须从该首条命令派生 next_action。
  • 目标必须显式且精确：只保存 get_goal 返回或操作者显式提供的目标，绝不派生、总结或扩展。
  • 完成状态很重要：未完成且有意可继续的工作用 ensure-active，已完成、放弃或取代的工作用 reference-only。
  • 可恢复性会过期：ensure-active 仅在 SAVE_SESSION_RESUME_WINDOW_HOURS 内是候选，绝不使战术状态永久权威。
  • 不委托检查点判断；子智能体只能扫描陈旧或重复上下文，主智能体负责记录持久决策、编辑所有者面、验证并写入检查点。
  • 编辑本技能文件后必须自验证：在技能目录运行 ./scripts/validate.sh。

相关文件包括 scripts/validate.sh、scripts/save-session、scripts/test_save_session.sh、~/.local/bin/save-session，以及同级技能 resume-session。