mcpField
C
context-compressor

context-compressor

github.com/oimiragieoAgent 工作流44268 次安装17 周前更新
代码仓库

关于 context-compressor

用于本地分析和压缩文本或适配后的 JSON 的技能，适合上下文过长的场景。它提供查询引导和证据感知流程，并检查压缩内容是否保留足够依据以支持可靠回答。

主要功能

  1. 01分析压缩前后的令牌用量
  2. 02压缩文本和适配后的 JSON
  3. 03提供查询引导与证据感知模式
  4. 04检查保留证据是否充分
  5. 05支持缓存友好的提示词组装
  6. 06提供 Python 脚本和 Node.js 封装

适用场景

  1. 01发送给模型前缩减上下文
  2. 02压缩对话历史并保留近期轮次
  3. 03准备面向查询的 RAG 或提示词内容
  4. 04检查压缩上下文能否支撑可靠回答

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oimiragieo/agent-studio --skill context-compressor

安装后在 Claude Code 中输入/context-compressor确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

commands/
context-compressor.md
evals/
evals.json
hooks/
post-execute.cjs
pre-execute.cjs
references/
evaluation.md
prompt-caching.md
research-requirements.md
references/skill-creator-reference/
LICENSE.txt
references/skill-creator-reference/agents/
analyzer.md
comparator.md
grader.md
references/skill-creator-reference/assets/
eval_review.html
references/skill-creator-reference/commands/
skill-creator-reference.md
references/skill-creator-reference/eval-viewer/
generate_review.py
viewer.html
references/skill-creator-reference/hooks/
post-execute.cjs
pre-execute.cjs
references/skill-creator-reference/references/
research-requirements.md
schemas.md
references/skill-creator-reference/rules/
skill-creator-reference.md
references/skill-creator-reference/schemas/
input.schema.json
output.schema.json
references/skill-creator-reference/scripts/
__init__.py
aggregate_benchmark.py
generate_report.py
improve_description.py
main.cjs
package_skill.py
quick_validate.py
run_eval.py

详细介绍

上下文压缩器

当问题主要是“上下文过多”而非“能力不足”时，使用此技能。

此技能是一个自包含的本地包，无需 MCP 服务。当你需要快速分析 token 用量、本地压缩、检查证据或在代码库中执行可复现的压缩工作流时，优先使用此技能。

此技能的功能

使用打包的 Python 脚本来：

  1. 衡量原始与压缩后的 token 用量
  2. 压缩大型文本或经过适配的 JSON 载荷
  3. 保留与查询相关的证据，而不是进行简单摘要
  4. 检查压缩后的输出是否仍包含足够证据，以便安全地作答
  5. 通过将稳定上下文放在前面、易变的查询文本放在后面，支持缓存友好的提示词组装

触发时机

当用户提出以下任一需求时，使用此技能：

  • 压缩此文件、对话记录、文档或代码转储
  • 在向模型发送上下文前降低 token 成本
  • 让提示词或 RAG 载荷更适合缓存
  • 精简多轮对话历史，同时保留最近的轮次
  • 比较语义压缩与更轻量的抽取式基线
  • 验证压缩后的上下文是否仍有足够证据

以下情况也会自动触发：

  • 上下文接近 80K token（spawn-token-guard.cjs 会写入 compression-reminder.txt）
  • 上下文达到 120K token（新增生成进程前必须先压缩）
  • 上下文达到 150K token（红线——压缩完成前不得生成新的 Agent）

快速工作流

默认按以下顺序执行：

  1. 先分析
  2. 有具体问题时，运行 query_guided
  3. 注重正确性并需要充分性检查时，运行 evidence_aware
  4. 如果证据薄弱，则降低压缩强度或扩大检索范围
  5. 报告节省情况、风险和下一步最安全的操作

如果用户只需要一条命令，请使用 run_skill_workflow.py。

命令

从 agent-studio 代码库根目录运行。始终使用以下确切命令——不得改用通用指导。

1. 分析 token 用量
python .claude/skills/context-compressor/scripts/profile_tokens.py --file <path> --output-format auto
2. 压缩上下文
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode baseline --output-format auto
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode query_guided --query "<question>" --output-format auto
python .claude/skills/context-compressor/scripts/compress_context.py --file <path> --mode evidence_aware --query "<question>" --min-similarity 0.4 --output-format auto
3. 适配框架 JSON 并进行压缩
python .claude/skills/context-compressor/scripts/compress_context.py --json-file <payload.json> --input-adapter auto --mode query_guided --query "<question>" --output-format auto
4. 运行完整工作流
python .claude/skills/context-compressor/scripts/run_skill_workflow.py --file <path> --mode evidence_aware --query "<question>" --output-format auto --fail-on-insufficient-evidence
5. 仅验证证据
python .claude/skills/context-compressor/scripts/validate_evidence.py --file <path> --query "<question>" --min-similarity 0.4 --output-format json
6. 运行 TOON 与 JSON 防护检查
python .claude/skills/context-compressor/scripts/benchmark_toon_vs_json.py
7. Node.js 包装器（用于 Agent 集成）
node .claude/skills/context-compressor/scripts/main.cjs --query "<question>" --mode evidence_aware --limit 20 --fail-on-insufficient-evidence

如何选择模式

  • baseline：尚无具体问题时，进行快速通用压缩
  • query_guided：问答、审查或定向提取任务的最佳默认模式
  • evidence_aware：用于高风险回答、审计，或需要明确信号来判断证据是否充分时

输出要求

使用此技能时，用通俗易懂的语言概述结果：

  1. 原始大小与压缩后大小
  2. 估算的 token 节省量或压缩率
  3. 输出是针对查询优化还是通用输出
  4. 证据是否充分
  5. 回答可能遗漏重要细节的风险

如果脚本返回的证据不足，不要虚张声势。应说明压缩后的上下文尚不够安全，并建议扩大处理范围。

随附参考资料

仅在相关时阅读：

  • references/workflow-guide.md：命令选择、模式选择和示例流程
  • references/prompt-caching.md：稳定前缀排序、缓存遥测和缓存安全的提示词结构
  • references/evaluation.md：如何对技能进行基准测试并解读结果

评估脚手架

入门提示词位于 evals/evals.json。迭代改进技能或需要一组小型、可重复的基准测试时，可使用这些提示词。

与 agent-studio 集成

压缩触发流水线
  1. compression-trigger.cjs 检测到上下文压力 → 写入 compression-reminder.txt
  2. Router 读取提醒 → 使用此技能生成 context-compressor Agent
  3. Agent 使用查询上下文运行 run_skill_workflow.py
  4. 实际压缩统计数据记录在 compression-stats.jsonl 中
记忆持久化

压缩后，通过 MemoryRecord 持久化提炼出的经验：

  • 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：所有其余提炼证据的默认回退文件
ccusage 成本跟踪

在决定压缩力度前，读取 .claude/context/runtime/ccusage-status.txt 获取实时令牌用量。每次调用工具时，ccusage-statusline.cjs 都会自动更新此文件。格式：

[tokens] 135,345 today (in: 14,850 / out: 120,495) | Cost: $127.4826
[cache] $627.2992 saved | 139,399,832 reads, 8,751,364 writes

Router MUST 在每个流水线里程碑都显示此内容（P0 用户反馈）。回退方案：ccusage --no-color 2>&1 | tail -5。

铁律

  1. 始终使用上述确切的脚本命令——绝不回退到通用的 CLAUDE.md 指南
  2. 始终先进行分析，再压缩，以了解输入大小
  3. 绝不在正确性至关重要时不带查询进行压缩——使用 evidence_aware 模式
  4. 始终在压缩后通过 MemoryRecord 持久化提炼出的经验
  5. 绝不在证据不足时虚张声势——建议进行更全面的处理
  6. 始终用通俗语言报告节省量、风险和下一步最稳妥的操作

评论

支持 Markdown