ctx-handoff：让 Claude Code 长会话更省心

ctx-handoff 是 CabLate（cablate）开发的社区插件，面向 Claude Code 长会话，也就是持续数小时的对话。它把长对话里常见的杂事打包在一起：你离开时发出一个极小的请求，让提示缓存不过期；把你重复说过的指示整理成按项目保存的笔记，并带入新对话；当 Claude 重试失败的工具，或没跑检查就说“完成了”时，给它一个提醒。

另外两个较大的功能没有那么自动。可选的交接会在上下文达到阈值时写出工作摘要、清空对话并在新对话里继续，默认关闭。守门（guard）是插件根据你反复提到的规则起草的工具调用检查，只有在你批准后才生效。输入框上方的面板（/handoff panel）会列出守门、记忆、规则、最近一次笔记更新和所有设置。

作者的 README 面向 Claude 订阅用户和大上下文的长会话。使用 API 密钥、Bedrock 或 Vertex 时缓存只保留五分钟，作者建议运行 /handoff refresh off。

录屏中，我们在小型演示项目里启动加载了该插件的 Claude Code。页脚立刻显示 ctx-handoff: 30 more messages until notes update，这是距离下一次后台笔记更新的倒计时。随后录屏运行 /handoff guard，它输出 Guards: none，并说明在什么情况下会起草守门；再运行 /handoff refresh，输出 Currently on. Usage: /handoff refresh on|off。整个录屏没有发出任何模型请求，也没有打开面板，因为面板会显示笔记文件的完整路径。

使用安装区块中的任意一种方式；它们都直接从作者自己的插件市场安装。启动新会话并运行 /handoff。会话开始后，页脚会出现倒计时。

所有功能都在一个模块 hooks/register.ts 中注册。每一轮结束后，空闲计时器会重新开始。计时器触发且上下文超过 min_tokens 时，插件发出一个最小的 fork 请求来读取缓存的对话，然后安排下一次。下面是调度函数，来自 hooks/register.ts：

async function schedule($: EngineInterface, delay = cfg.idleMs) {
  rt.idle?.cancel()
  if (await awayPaused($)) { rt.idle = undefined; await update($, idleState, () => null); return }
  rt.idle = $.clock.after(delay, () => void onIdle($))
  const due = (await $.clock.now()) + delay
  await update($, idleState, () => ({ due, refreshes: rt.refreshes }))
}

默认空闲时间为 50 分钟，最多刷新 3 次，之后保存一份不清空对话的离席交接。每 30 条用户消息，或在交接之前，另一个不带历史的请求会把对话中新增的部分发给笔记模型（claude-sonnet-5-5，低推理强度）。它输出的 JSON 动作会由代码校验，用户原话必须能在你真实的消息中找到，看起来像密钥的行在写入前会被丢弃。笔记通过 prompt.context 注入新对话。

插件没有声明 userConfig。设置位于面板的设置分页（/handoff panel，然后按 5），插件也会读取 settings.json 中的 pluginConfigs["ctx-handoff@<marketplace>"].options，面板的值优先。设置包括 auto_handoff（默认关闭）、threshold（600000 个 token）、idle_minutes（50）、max_refresh（3）、min_tokens（30000）、distill_every（30）、notes_model、retry_nudge、done_check、reply_language 和 language。其余功能由斜杠命令控制：/handoff now、dry、distill on|off、refresh on|off、away pause|resume、guard、resume、continue 和 resend。

我们读过清单、hooks/hooks.json、完整的 hooks/register.ts，以及设置、笔记、交接、守门、循环、语言、提升和整理提示等模块。其余文件主要是 i18n 文案、面板视图和少量记录辅助函数，我们通过搜索检查了副作用，没有逐行阅读。仓库中没有 package.json、安装脚本、二进制文件或压缩代码。tools/ 里是作者自用的脚本，插件不会加载，我们也没有运行它们。没有隐藏的 Unicode 字符。

你需要知道的发现：

• 会发出模型请求，没有其他网络访问。 没有 fetch、进程调用或网络代码。插件调用 $.model.fork 和 $.model.complete，会使用你的 Claude 额度。对话内容会被发送用于笔记和交接摘要，与对话本身的发送方式相同。
• 会在自己的存储之外写文件。 $.fs.write 会创建并更新 <claude 配置目录>/projects/<工作区>/memory/ctx-handoff.md，并在从面板删除笔记前把备份写入 .ctx-handoff-backup/。后台笔记更新默认开启，但如果会话是在你的主目录启动的就会跳过。它不会改动 settings.json、shell 文件或 LaunchAgents，会读取 HOME、USERPROFILE 和 CLAUDE_CONFIG_DIR。
• 它会向模型注入文本。 prompt.context 会把你的笔记、可选的进度备忘和守门询问加入新对话，并带有 [ctx-handoff] 标记。工具结果可能附带提醒。当某条规则在 git 仓库中出现 3 次后，注入的文本会要求 Claude 不先询问就把它写进仓库（CLAUDE.md、.claude/skills、hook），但不要提交。笔记是模型对你对话的总结，所以请不时检查这个文件。
• 拦截类 hook。 tool.call 只会对你批准过的守门拒绝调用。classic.Stop 在改过文件却没有跑检查时，每轮可以拦下一次“完成”的回答（done_check，默认开启）。prompt.submit 会在交接进行时暂存你的消息。如果你打开自动交接，插件会自己运行 /clear 并提交摘要。
• 没有后台守护进程，没有遥测。 计时器只存在于 Claude Code 进程中，用量统计保存在插件自己的存储里。
• 受管环境。 claude plugin validate 提示，在由组织管理 Claude Code 的环境中，用户自行安装的插件不会运行 prompt.context 和 classic.Stop hook。
• 许可证。 MIT，附有 LICENSE 文件。

claude plugin validate 没有报告错误。唯一的警告是仓库根目录的 CLAUDE.md 不会作为插件上下文加载。作者的 15 个文件共 290 个测试在 Claude Code 2.1.303 上全部通过。

已在 macOS 上使用 Claude Code 2.1.303 检查（validate、测试和录屏）。作者的 README 要求 2.1.287 或更高版本。如果 /handoff 没有反应：

• claude --version 为 2.1.287 或更高版本，并且安装后启动了新会话。
• 可能已有另一个 /handoff 命令；此时插件会改为注册 /ctx-handoff。
• 笔记更新关闭，或你在主目录启动 Claude Code 时，页脚没有倒计时。
• 缓存刷新只在缓存能保留一小时的环境中有用，使用 API 密钥时请用 /handoff refresh off 关闭。
• 运行 /handoff 查看当前状态，包括最近一次失败和笔记文件的路径。