Compact Adviser：知道 Claude Code 何时运行 /compact

Compact Adviser 帮你判断 Claude Code 何时运行 /compact，它只回答一个问题：我现在应该运行 /compact 吗？作者是 Kun Chen（kunchenguid），同一个仓库为 Claude Code、Pi、Codex CLI 和 Grok 分别提供版本。本页介绍的是 packages/claude-mod 中的 Claude Code 插件。

压缩得太早会丢掉你仍然需要的上下文；压缩得太晚，每一轮都要背着一长串历史。每一轮结束后，插件会检查几个低成本的本地条件，条件满足时，再就当前对话向 TypeSafe 的 Jev 模型提出两个简短的问题：助手最近的这段工作是否已经完成？助手是亲自完成了工作，还是主要在做协调？两个答案合并成一个分数。如果分数超过下限，就会出现一行状态提示："work appears completed or recorded. Run /compact to save tokens."

当上下文大部分还空着时，下限很严格（0.90），随着上下文接近 Claude Code 的自动压缩点，下限会逐步放宽到 0.50，因为在仍有空间时，一次错误的提示代价最大。如果你选择开启自动模式，插件会在这样的检查点上自行执行压缩，而不只是给出提示。

它需要一个 TypeSafe API 密钥，由你自己提供。

真正的提示需要超过 40,000 个 token 的上下文和一个 TypeSafe 密钥，这放不进一段简短的录屏。录屏中，我们启动加载了该插件的 Claude Code，运行 /compact-adviser status（显示模式、最小值、预算和密钥状态），然后打开 /compact-adviser 设置窗格，移动到 TypeSafe API 密钥那一行，它显示为 missing。

使用安装区块中的任意一种方式；两者都直接从作者的插件市场安装。除非 Claude Code 启动时带有 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1，否则这个插件完全不起作用，所以请带上这个变量启动，然后运行 /compact-adviser 添加你的 TypeSafe 密钥。

一切都从 hooks/register.ts 中的 turn.complete 钩子开始：

on("turn.complete", async ($, e, next) => {
  const result = await next(e);
  if (!(await isActivated($)) || !interactive) return result;
  if (e.agentId !== undefined || e.reason !== "answer" || e.isAborted || !e.answer.trim()) {
    return result;
  }
  try {
    await settle($);
  } catch {
    notice($, "Compact adviser could not inspect this checkpoint; context left unchanged.");
  }
  return result;
});

只有以真正的回答结束的主循环轮次才会被计入；子代理的轮次和被中止的轮次都会被跳过。settle 统计这次交互并运行几道低成本的关卡：模式不是 off、存在密钥、上下文达到或超过 minContextTokens，并且没有处于冷却或暂缓状态。如果都通过，它会用 $.clock.after(0, …) 安排 judgeCheckpoint，这样不会拖住当前这一轮。

judgeCheckpoint 从 $.session.messages() 构建一份有界快照（见 lib/snapshot.ts）；如果对话不足 20,000 个 token，或者同一个检查点已经判断过，就跳过请求；否则用 $.http.fetch 把快照发送到 https://api.typesafe.ai/v1/systemone。请求 2 秒后超时，出错、超时或格式错误的回复都绝不会被当作"是"：插件会退避并改为弹出通知。当分数达标时，提示模式会用提示内容调用 $.ui.status，自动模式则调用 $.session.compact，并附带指令，要求原样保留当前工作、待办任务和下一步。

任何一次压缩，无论是你发起的还是 Claude Code 发起的，都会通过 session.compact 钩子重置会话的冷却时间。

运行 /compact-adviser 打开设置窗格，或者使用它的子命令：auto、hint 和 off 切换模式；threshold 60000 设置最小上下文；budget 450000 设置一个上下文预算，下限改为以它而不是自动压缩点为基准；snooze 跳过接下来的三次交互；dismiss 清除当前提示；status 打印当前状态。模式、最小值、预算和请求日志也都是 /config 中的条目。判断配置（profile 设置中的 JSON）可以修改问题、分数权重或下限的变化曲线。

在运行任何东西之前，我们读过了 register.ts、lib/ 下的每一个文件、plugin.json、hooks.json、package.json 以及测试辅助代码。

• **网络：**每个达标的检查点，插件都会向第三方服务 https://api.typesafe.ai/v1/systemone 发送一次请求，并在 Authorization 请求头中带上你的密钥。请求体是最近对话的快照，上限为 32,000 字节，并已对密钥格式以及 .env、auth.json、id_rsa/id_ed25519、.pem 和 .key 文件进行尽力脱敏。TYPESAFE_BASE 可以把它指向另一个 https 地址，或本机回环的 http 地址。安装插件即视为同意在有密钥时发送这些内容，所以对于不能离开本机的工作，请把模式设为 off。
• **文件：**它会读取会话文件夹中的 .env 来查找 TYPESAFE_API_KEY。只有在你开启请求日志时才会写文件：~/.claude/compact-adviser-requests-<session-id>.jsonl，其中绝不包含密钥。
• **设置：**在窗格中保存时，会通过 $.config.set 写入插件自己的 userConfig 条目。保存的密钥在 /config 中是隐藏的。
• **压缩：**只在自动模式下进行，并且需要先在一次性的确认对话框中确认。

没有安装脚本，没有打包或压缩过的代码，除了发给 TypeSafe 的请求本身之外也没有任何遥测。

已使用 Claude Code 2.1.291 验证：claude plugin validate 通过且没有警告，claude plugin test 运行了 114 个测试，全部通过。作者列出的要求是 Claude Code 2.1.274 或更新版本。如果什么都没发生，请按顺序检查以下几项：

• 没有 /compact-adviser：CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 不恰好是 1，或者设置了 COMPACT_ADVISER_DISABLE。
• /compact-adviser status 显示 Key: missing：在窗格、环境变量或 ./.env 中添加密钥。
• 命令能用但没有出现提示：上下文低于最小值，或者上一轮没有以一个确定的回答结束。
• 通知中提到 "nonessential network traffic"：CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 阻止了发往 TypeSafe 的请求。
• claude -p 会话按设计始终处于未激活状态。