令牌节约上下文压缩技能Skill token-saver-context-compression

---

name: 令牌节约器上下文压缩 description: 用于代理工作室的搜索感知上下文压缩工作流。使用 pnpm 混合搜索 + 令牌节约器压缩，然后通过 MemoryRecord 持久化提炼出的学习内容。 argument-hint: [文件或文本和查询] verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

令牌节约器上下文压缩

使用此技能以减少令牌使用，同时保留基于证据的上下文。这集成了：

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

何时使用

• pnpm search:tokens 显示文件/目录超过 32K 令牌
• 上下文较大或成本高，需要压缩摘要
• 在合成前需要查询目标压缩
• 在持久化内存前需要硬证据充分性门控
• 您正在构建提示，仅 search:code 结果不足以提供上下文

铁律

不要直接从子进程将压缩内容持久化到内存文件。 发出 MemoryRecord 负载，并让框架钩子处理同步/索引。

工作流程

1. 检索候选上下文（pnpm search:code "<查询>"）。
2. 使用 token-saver 在 JSON 模式下压缩（run_skill_workflow.py --output-format json）。
3. 如果证据不足且失败门控开启，停止。
4. 将提炼出的洞察映射到 MemoryRecord 就绪的负载。
5. 通过 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 "<问题>" --mode evidence_aware --limit 20 --fail-on-insufficient-evidence

直接 Python 引擎（高级）：

python .claude/skills/token-saver-context-compression/scripts/run_skill_workflow.py --file <路径> --mode evidence_aware --query "<问题>" --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/skills/token-saver-context-compression/commands/token-saver-context-compression.md
• 引用格式不变：
  • 内存条目变为 [mem:xxxxxxxx]
  • RAG 条目保持 [rag:xxxxxxxx]

与 search:tokens 集成

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

# 检查是否需要压缩
pnpm search:tokens .claude/lib/memory
# 输出：60 文件，500KB，~128K 令牌 ⚠ 超过上下文

# 然后使用目标查询进行压缩
node .claude/skills/token-saver-context-compression/scripts/main.cjs \
  --query "内存持久化如何工作" --mode evidence_aware --limit 10

该工具从搜索结果中读取实际文件内容（不仅是文件路径），通过 Python 引擎压缩，并提取按类型分类的内存记录（模式、陷阱、问题、决策）。

自适应压缩

自适应压缩（根据语料库大小调整压缩比）是自动的，无需环境变量配置。当输入语料库较小时，压缩较轻；当较大时，压缩更激进。这是由 Python 引擎内部基于令牌计数控制的。

要求

• Node.js 18+
• Python 3.10+

内存协议（强制）

工作前：

cat .claude/context/memory/learnings.md

工作后：

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