token-saver-context-compression

Token Saver 上下文压缩

使用此技能，在保留可靠证据的同时减少 Token 用量。此技能整合了：

• pnpm search:code（混合检索）
• token-saver Python 压缩脚本
• 将 MemoryRecord 持久化到框架记忆中
• 注入生成提示词的证据（[mem:*] / [rag:*]）

激活

可以通过两种方式调用 token-saver 技能：

手动调用（始终可用）

Skill({ skill: 'token-saver-context-compression' });

当上下文压力较大、pnpm search:tokens 显示某个文件/目录超过 32K Token，或需要针对查询进行压缩时使用。

通过 compression-reminder.txt 自动强制执行（需要 AUTO_COMPRESSION_PHASE_3=1）

在 .env 中设置 AUTO_COMPRESSION_PHASE_3=1，以启用 compression-reminder.txt 触发器：

# In .env
AUTO_COMPRESSION_PHASE_3=1

启用后，每当触发压缩事件，compression-trigger.cjs 都会写入 .claude/context/runtime/compression-reminder.txt。路由器会读取此文件，并自动生成 context-compressor。

未设置此环境变量时：压缩事件会记录到 .claude/context/compression-stats.jsonl，但不会写入 compression-reminder.txt，因此路由器不会自动生成压缩任务。必须手动调用此技能。

路由器强制执行的 Token 阈值（来自 CLAUDE.md 第 8 节）：

• 80K Token — 主动生成 context-compressor
• 120K Token — 生成新的任务前必须压缩
• 150K Token — 压缩完成前不得生成新的 Agent

注意：这些阈值是 CLAUDE.md 第 8 节中规定的路由器行为准则。compression-trigger.cjs 的触发条件是独立的启发式规则（预算 >90%、读取量 >10KB、获取量 >5KB、每 10 次操作定期触发）。没有自动钩子来强制执行 80K/120K/150K 阈值——这些阈值依赖路由器读取 compression-reminder.txt。

使用时机

• pnpm search:tokens 显示某个文件/目录超过 32K Token
• 上下文很大或成本很高，需要压缩摘要
• 综合分析前需要针对查询进行压缩
• 持久化记忆前需要严格验证证据是否充分
• 你正在构建提示词，而 search:code 结果本身不足以提供所需上下文

铁律

不要从子进程直接将压缩内容持久化到记忆文件。 输出 MemoryRecord 载荷，并交由框架钩子处理同步/索引。

工作流

1. 检索候选上下文（pnpm search:code "<query>"）。

步骤 0.5：检查实际 Token 用量和成本（ccusage-adapter）

压缩前，通过 ccusage-adapter 查询今天实际的 API Token 用量和成本。 这样可以依据数据做出压缩决策，并准确报告节省的成本。

// Attempt to read actual token usage (graceful degradation — never blocks compression)
let usageData = null;
let costs = null;
try {
  const ccusage = require('.claude/lib/utils/ccusage-adapter.cjs');
  usageData = ccusage.getTodayTotals();
  if (usageData) {
    costs = ccusage.calculateCost(usageData, process.env.CCUSAGE_MODEL || 'opus');
  }
} catch (_err) {
  // ccusage not installed or unavailable — fall back to heuristic estimation
}

if (usageData && costs) {
  console.log('[token-saver] Usage today:', {
    total: usageData.inputTokens + usageData.outputTokens,
    cost: `$${costs.actualCost.toFixed(4)}`,
    cacheSaved: `$${costs.cacheSavings.toFixed(4)}`,
  });

  // Use actual counts to decide compression aggressiveness
  const totalTokens = usageData.inputTokens + usageData.outputTokens;
  if (totalTokens > 120_000) {
    console.log('[token-saver] HIGH pressure (>120K tokens) — aggressive compression mode');
  } else if (totalTokens > 80_000) {
    console.log('[token-saver] MODERATE pressure (>80K tokens) — standard compression mode');
  } else {
    console.log('[token-saver] LOW pressure (<80K tokens) — light compression');
  }
} else {
  // ccusage unavailable — fall through to heuristic estimation from compression-trigger.cjs
  console.log('[token-saver] ccusage unavailable — using heuristic token estimation');
}

回退行为：当 getTodayTotals() 返回 null（未安装 ccusage、超时或 CCUSAGE_DISABLED=1）时，工作流会继续使用 compression-trigger.cjs 中现有的启发式阈值。此步骤绝不会阻止压缩。

状态文件：ccusage-statusline 钩子会在每次提示词调用时，将实时状态写入 .claude/context/runtime/ccusage-status.txt。读取该文件即可快速查看易读摘要，无需直接调用适配器。

定价表

规范参考 — ccusage-adapter.cjs → calculateCost() 使用这些费率。 skill-updater 刷新此技能时，必须通过 Exa 搜索验证这些数值，并同时更新此表和 .claude/lib/utils/ccusage-adapter.cjs 中的 PRICING。

上次验证：2026 年 3 月（来源：Silicon Data、IntuitionLabs、DevTk.AI）

模型	输入	输出	缓存写入（输入的 1.25×）	缓存读取（输入的 0.10×）
opus → Claude Opus 4.6	$5.00/M	$25.00/M	$6.25/M	$0.50/M
sonnet → Claude Sonnet 4.6	$3.00/M	$15.00/M	$3.75/M	$0.30/M
haiku → Claude Haiku 4.5	$1.00/M	$5.00/M	$1.25/M	$0.10/M

缓存定价规则（Anthropic 标准）：

• 缓存写入 = 基础输入价格的 1.25×（存储前缀需额外支付 25%）
• 缓存读取 = 基础输入价格的 0.10×（重复上下文可享受 90% 折扣）

设置 CCUSAGE_MODEL=sonnet 或 CCUSAGE_MODEL=haiku，以匹配当前使用的模型。 默认值为 opus（较为保守——费率最高，显示的节省金额最大）。

成本追踪组件

成本追踪流程由三个文件组成：

文件	作用
.claude/lib/utils/ccusage-adapter.cjs	解析 JSONL 会话日志、汇总 token 数，并通过 PRICING 表计算成本
.claude/hooks/monitoring/ccusage-statusline.cjs	UserPromptSubmit 钩子——每次提交提示词时运行适配器，并将状态写入运行时文件
.claude/context/runtime/ccusage-status.txt	实时状态文件——路由器读取此文件以生成流程摘要

状态输出格式（三个节省层级）：

[tokens]      <N> today (in: <N> / out: <N>) | Cost: $<X>
[cache]       $<X> saved | <N> reads, <N> writes
[compression] <N> events | <X>KB freed (~<N> tokens) | ~$<X> saved

• [tokens] — 实际 API 支出
• [cache] — 服务端节省（Anthropic 提示词缓存，缓存读取可享受 90% 折扣）
• [compression] — 客户端节省（此技能避免发送的 token 数）

维护说明（供 skill-updater 使用）

skill-updater 刷新此技能时，请在标准研究流程之后执行此附加步骤：

定价验证步骤

1. 运行 Exa 搜索，确认当前 Claude API 定价：

   mcp__Exa__web_search_exa({
     query: 'Anthropic Claude API pricing per million tokens Opus Sonnet Haiku current',
     numResults: 4,
   });
   

2. 至少交叉核对两个来源（例如 Anthropic 文档、Silicon Data、IntuitionLabs、DevTk.AI）。

3. 将查到的费率与上面的定价表进行比较。

4. 如果任何费率已变更：

   • 更新此 SKILL.md 中的表格
   • 更新 .claude/lib/utils/ccusage-adapter.cjs 中的 PRICING 常量
   • 更新 Last verified 日期
   • 在 .claude/context/memory/decisions.md 中记录变更

5. 如果费率均未变更，则仅更新 Last verified 日期。

为何重要：过时的定价会夸大节省金额（旧版 Opus 4.0 费率会将 $86 显示为 $258）。准确的定价是此技能成本报告价值的核心。

1. 使用 token-saver 以 JSON 模式压缩（run_skill_workflow.py --output-format json）。
2. 如果证据不足且启用了失败门禁，则停止。
3. 将提炼出的见解映射为符合 MemoryRecord 格式的负载。
4. 通过 MemoryRecord 持久化，以便运行 .claude/hooks/memory/sync-memory-index.cjs。

映射规则（确定性）

• gotchas.json：
  • 文本包含 gotcha|pitfall|anti-pattern|risk|warning|failure
• issues.md：
  • 文本包含 issue|bug|error|incident|defect|gap
• decisions.md：
  • 文本包含 decision|tradeoff|choose|selected|rationale
• patterns.json：
  • 作为默认回退项，用于所有其余提炼出的证据

工具命令

首选包装器入口：

node .claude/skills/token-saver-context-compression/scripts/main.cjs --query "<question>" --mode evidence_aware --limit 20 --fail-on-insufficient-evidence

直接使用 Python 引擎（高级）：

python .claude/skills/token-saver-context-compression/scripts/run_skill_workflow.py --file <path> --mode evidence_aware --query "<question>" --output-format json --fail-on-insufficient-evidence

输出契约

• 包装器会输出 JSON，包含：
  • search 摘要
  • compression 摘要
  • 按目标分组的 memoryRecords（patterns、gotchas、issues、decisions）
  • evidence 充分性状态

工作流参考

• 技能工作流：.claude/workflows/token-saver-context-compression-skill-workflow.md
• 配套工具：.claude/tools/token-saver-context-compression/token-saver-context-compression.cjs
• 命令接口：.claude/commands/token-saver-context-compression.md
• 引用格式不变：
  • memory 条目变为 [mem:xxxxxxxx]
  • RAG 条目仍为 [rag:xxxxxxxx]

与 search:tokens 集成

使用 pnpm search:tokens 来决定何时调用此技能：

# Check if you need compression
pnpm search:tokens .claude/lib/memory
# Output: 60 files, 500KB, ~128K tokens ⚠ OVER CONTEXT

# Then compress with a targeted query
node .claude/skills/token-saver-context-compression/scripts/main.cjs \
  --query "how does memory persistence work" --mode evidence_aware --limit 10

该工具会读取搜索结果中的实际文件内容（而不只是文件路径），通过 Python 引擎进行压缩，并按类型（patterns、gotchas、issues、decisions）提取记忆记录。

自适应压缩

自适应压缩（根据语料库大小调整压缩比）会自动进行，无需配置环境变量。输入语料较小时，压缩力度较轻；语料较大时，压缩力度较强。Python 引擎会根据 token 数量在内部进行控制。

要求

• Node.js 18+
• Python 3.10+

铁律

1. 始终在压缩前运行混合搜索（pnpm search:code），以检索可为提炼输出提供依据的证据
2. 绝不压缩仍存在未解决疑问的上下文——压缩前先消除歧义
3. 始终在压缩后立即通过 MemoryRecord 持久化提炼出的经验
4. 绝不在压缩过程中丢弃与当前工作假设相矛盾的证据
5. 始终在压缩后的输出中加入 [mem:*] 和 [rag:*] 引用，为下游生成提示词提供依据

反模式

反模式	失败原因	正确做法
未先进行混合搜索就压缩	输出缺乏可靠证据，存在幻觉风险	先运行 pnpm search:code，并嵌入引用
丢弃相矛盾的证据	会使提炼后的输出产生虚假的确信	在摘要中保留所有相互矛盾的信号
压缩后未创建 MemoryRecord	下次重置上下文时经验会丢失	通过 MemoryRecord 立即持久化关键发现
压缩过晚（超过 80K tokens）	压缩前准确性会严重下降	在达到 80K tokens 时触发压缩，而不是等到上限
跳过 [mem:*] / [rag:*] 引用	下游 Agent 无法验证声明	始终在输出中标注证据来源

记忆协议（强制）

开始工作前：

cat .claude/context/memory/learnings.md

工作完成后：

• 将集成经验添加到 .claude/context/memory/learnings.md
• 将集成风险添加到 .claude/context/memory/issues.md