redcon

---

问题所在

AI 编码 Agent 会把令牌浪费在无关上下文上。你只能：

• 倾倒整个代码库，每次请求都要为 200k 个输入令牌付费；或
• 让 Agent 盲目地 grep，浪费工具调用来摸索该去哪里找

Redcon 两者兼顾。它会按任务相关性为文件排序，使用语言感知策略（完整内容、代码片段、符号提取、摘要）进行压缩，并在你的令牌预算内打包结果。确定性、本地优先、无需嵌入。一个 MCP 服务即可支持 Claude Code、Cursor、Windsurf、Cline 和 Zed；CI 则可使用普通 CLI。在此代码库上测得，在任务覆盖率相同的情况下，输入令牌减少了 83% 以上（方法）。

让你的订阅发挥更大价值

如果使用固定订阅方案——Claude Pro/Max、Cursor、GitHub Copilot——真正让人头疼的不是令牌费用，而是使用限额。Redcon 可减少每项任务所需的令牌，让同一订阅方案在触及每周限额前支持更多工作。订阅不变，续航更久。

它能充分利用你已经付费的预算，并准确报告节省了多少。

安装

选项 1：VS Code 扩展（最简单）

1. 从市场中安装 Redcon - Context Budget
2. 打开 Redcon 侧边栏，点击 Install & Set Up
3. 重新加载窗口。完成。

该扩展会通过 pip 安装 CLI，为 Claude Code、Cursor 和 Windsurf 注册 MCP 服务，并提供一个侧边栏，展示预算分析、文件排名和压缩仪表板。

选项 2：CLI + MCP 服务

pip install "redcon[mcp]"
redcon init                      # creates redcon.toml + registers MCP

init 命令会自动为 Claude Code、Cursor 和 Windsurf 配置 MCP；如果检测到 VS Code、Codex CLI、Gemini CLI、Junie CLI、Cline 和 Zed，也会为它们配置，让你的 AI Agent 能将 redcon_rank、redcon_search、redcon_compress 和 redcon_budget 作为原生工具调用。它还会写入一段简短的 AGENTS.md 内容，告知 Agent 在选择上下文时优先使用这些工具。

选项 3：仅 CLI

pip install redcon
redcon init --no-mcp

快速入门

# Rank files relevant to a task
redcon plan "add rate limiting to auth API" --repo .

# Pack context under a token budget
redcon pack "refactor payment flow" --repo . --max-tokens 30000

# Compare compression strategies
redcon benchmark "add caching" --repo .

# Audit a PR for context growth
redcon pr-audit --repo . --base origin/main --head HEAD

输出会写入 run.json（机器可读）和 run.md（人类可读）。你可以在 CI 中使用这些文件，也可以将压缩后的上下文直接提供给 Agent。

如需了解真实服务代码库端到端的完整演练（规划、打包、验证，且输出具有确定性），请参阅 examples/service-repo。

工作原理

task: "add rate limiting to auth"
       |
       v
  [1] scan    - incremental scan of repo files (cached)
       |
       v
  [2] rank    - score each file: keyword match, imports, file role, git history
       |
       v
  [3] compress - per-file strategy: full / snippet / symbol extraction / summary
       |
       v
  [4] pack    - fit top-N compressed files under token budget, drop the rest
       |
       v
  run.json + run.md + compressed_context ready for your agent

每一步都是确定性的。同样的输入，得到同样的输出。无需嵌入，也不会随机分块。

基准测试：context-eval

选择质量是通过测量得出的，而非口头宣称。 context-eval/ 是一个面向上下文选择工具的开放基准测试：任务来自真实的 git 提交，真实结果是每次提交实际修改的文件，并且每个工具使用相同的 token 预算。当前结果（33 个任务，24k 预算）：

工具	平均覆盖率	每个覆盖率百分点的 Token 数
redcon	43.8%	306.8
keyword-topk（基线）	29.8%	538.9
aider-repomap（真实 aider）	15.3%	533.3
pagerank（基线）	11.4%	720.0

在任意仓库上重新运行：python context-eval/run.py --repo /path/to/repo。 方法、局限性以及如何添加自己的工具： context-eval/README.md。

MCP 集成（拉取模式）

mcp-name: io.github.natiixnt/redcon

Redcon 不会向 Agent 推送 30k token 的内容块，而是提供 9 个 MCP 工具，供 Agent 按需调用：

工具	功能
redcon_rank	返回带评分和原因的 Top-K 文件——请先调用此工具
redcon_overview	按目录分组的轻量级仓库映射
redcon_repo_map	返回排名靠前的文件及其代码签名，并适配 token 预算
redcon_compress	用于快速检查的单文件压缩视图
redcon_search	在排名靠前的文件或整个仓库中执行正则表达式搜索
redcon_structural_search	ast-grep 结构化搜索——模式匹配 AST，而非文本
redcon_budget	规划如何在 token 预算内纳入文件
redcon_run	运行 shell 命令，并以压缩形式返回输出
redcon_quality_check	运行命令，并使用质量测试框架验证压缩后的输出

Agent 的典型工作流在探索阶段约使用 5k token，而不是将 30k token 用于内容块。Agent 自行决定要完整读取哪些内容。

配置会自动写入：

• .mcp.json（Claude Code）
• .cursor/mcp.json（Cursor）
• ~/.codeium/windsurf/mcp_config.json（Windsurf）

命令输出压缩

源文件只占冗余内容的一半，另一半来自命令输出：git diff、pytest、cargo test、grep、ls -R。Redcon 的 redcon_run MCP 工具（以及 redcon run CLI）会封装调用、解析输出，并返回适配预算的压缩视图，保留 Agent 实际需要的所有事实。

代表性输入的主要压缩效果：

压缩器	测试样例	原始 Token 数	紧凑	超紧凑
git diff	12 个文件，240 个代码块	8,078	97.0%	99.5%
pytest	30 个失败 + 200 个通过	2,555	73.8%	99.2%
grep/rg	50 个文件中有 600 条匹配	7,015	76.9%	99.9%
find	500 个路径	3,398	81.3%	99.8%
ls -R	30 个目录 × 每个 15 个文件	1,543	33.5%	99.0%
kubectl events	200 行的 CrashLoopBackOff 事件	~5,000	91.5%	99.5%
py-spy collapsed	200 个调用栈	2,385	90.0%	99.0%
json-line log	200 条 NDJSON 记录	6,038	91.1%	98.0%
coverage report	50 个文件的表格	738	73.2%	95.0%
psql EXPLAIN ANALYZE	11 个节点的 Postgres 执行计划	435	71.3%	93.3%

质量由独立机制保障。每个压缩器都声明 must_preserve_patterns（例如，diff 中的文件路径、pytest 中失败的测试名称、git status 中的分支名称、EXPLAIN 中最慢节点的运算符）；M8 质量测试框架会拒绝任何紧凑输出中遗漏了原始输入事实的压缩器。将其作为 CI 步骤运行：

redcon cmd-quality   # exits non-zero if any compressor regressed
redcon cmd-bench     # markdown table; --json for CI baselines
redcon run "git diff" --quality-floor compact --max-output-tokens 4000

目前提供 20 种压缩器：git_diff、git_status、git_log、pytest、cargo_test、npm_test（vitest+jest）、go_test、grep、ls、tree、find、lint（ruff+mypy）、docker、pkg_install（pip+npm+yarn）、kubectl_get/kubectl_events、profiler（py-spy+perf）、json_log、coverage、sql_explain（Postgres+MySQL TREE）、bundle_stats（webpack + esbuild metafiles）。完整的各格式基准测试： docs/benchmarks/cmd/。

跨调用维度

除了单次调用压缩外，四个层级会在一次 Agent 会话中组合发挥作用：

• 路径别名（V41）：像 redcon/cmd/pipeline.py 这样的重复路径在后续提及时会折叠为 f001。首次使用时才生成，绝不会得不偿失。
• 内容引用账本（V43）：超过 6 cl100k token 的段落形块在第二次及后续出现时，会获得会话内稳定的 {ref:001} 别名。实测会话输出中有 23% 存在块级重叠。
• 符号别名（V49）：CamelCase 类型 / 多词 snake_case 标识符（>=8 个字符）会像路径一样折叠为 c001 别名。实测每个会话中，72% 的不同符号会重复出现 >=2 次。
• 相较于上次调用的快照差异（V47）：同一 argv 运行两次时，只传输差异部分。针对 pytest（对失败名称进行集合差分）、git_diff（文件集合及每个文件的 +/- 计数）和 coverage（每个文件的百分点变动）的感知架构渲染器，效果显著优于通用行差分。始终选择 min(cost_delta, cost_abs)，因此从设计上保证不会倒退。
• 不变量证书（V93）：每个 COMPACT/VERBOSE 输出都会对从原始内容中提取的 (pattern, capture) 排序多重集生成 mp_sha=<16hex>。审计人员会根据压缩文本重新计算证书，以检测虚假添加或捕获内容缩减——将现有的必须保留布尔值升级为集合相等性检查。

在 5 个模拟 Agent 会话上的实测（benchmarks/measure_sessions.py）：跨调用层在单次调用压缩器的基础上，额外实现 +8.3% 的会话级节省；在高重叠会话（调试、搜索并编辑）中达到 +15%，而在内容各不相同的会话中则接近于零。V85 对抗式 GA 模糊测试器会将全部 20 个架构纳入强制 CI 门禁（REDCON_V85_ENFORCE=1）。

VS Code 扩展

安装后，你将获得：

• 侧边栏聊天：输入任务并发送，实时查看打包过程
• 仪表板：以环形图 / 饼图 / 条形图展示预算、策略及每个文件的 token 影响
• 状态栏：显示当前预算使用量和风险指示器
• CodeLens：在每个文件上方显示压缩策略和 token 数量
• 文件装饰：在资源管理器中的文件上显示相关性评分徽章
• 历史记录：浏览以往运行记录、比较差异并导出到剪贴板

品牌设计：red->navy 渐变搭配三重箭头标记，以及玻璃风格 UI。

工作区（多仓库）

一个任务可以跨越多个仓库。将工作区 TOML 文件放在包含所有仓库的文件夹中 （单体仓库根目录或共同的父目录）——仓库路径必须解析到该文件夹内，因此工作区文件无法访问 其自身所在目录之外的路径：

name = "backend-services"

[scan]
include_globs = ["**/*.py", "**/*.ts"]

[budget]
max_tokens = 28000
top_files = 24

[[repos]]
label = "auth-service"
path = "auth-service"

[[repos]]
label = "billing-service"
path = "billing-service"
ignore_globs = ["tests/fixtures/**"]

生成的产物包括 workspace、scanned_repos、selected_repos，以及 auth-service:src/auth.py 这样的带仓库限定路径。

参见 docs/workspace.md。

Python API

from redcon import RedconEngine

engine = RedconEngine()

# Rank files
plan = engine.plan(task="add user auth", repo=".", top_files=15)

# Pack context
result = engine.pack(
    task="add user auth",
    repo=".",
    max_tokens=30000,
    top_files=25,
)
print(f"Used {result['budget']['estimated_input_tokens']} of {result['max_tokens']} tokens")
print(f"Risk: {result['budget']['quality_risk_estimate']}")

for file in result["compressed_context"]:
    print(f"{file['path']}: {file['strategy']} ({file['compressed_tokens']} tokens)")

完整参考：docs/python-api.md。

功能

• 确定性评分：关键词匹配、导入关系图、文件角色（测试／文档／生产）、Git 历史
• 语言感知压缩：Python、TypeScript、JavaScript、Go、Rust、Java 等
• 命令输出压缩：20 种压缩器，覆盖 Git、测试运行器、grep/rg、目录列表、lint、Docker、pkg-install、kubectl、性能分析器、JSON 日志、覆盖率、SQL EXPLAIN 和包体积统计；紧凑级别可减少 70-99%
• 增量扫描：缓存文件元数据，并根据 Git 感知的变更检测进行更新
• 多仓库工作区：单个任务、多个仓库、共享配置
• 预算策略：在 CI 中强制执行最大 token 数、质量风险级别和文件数限制
• 质量测试框架：每个压缩器均支持必须保留的正则表达式断言，具有确定性，并能稳健处理截断或二进制输入
• 流式运行器：分块 Popen 读取器，内存占用受限；达到输出上限时提前发送 SIGTERM/SIGKILL
• 运行历史：由 SQLite 支持的文件包和命令运行产物存储，支持差异／热力图／漂移分析
• 成本分析：估算 GPT-4o、Claude 和其他模型的 token 成本
• PR 审计：检测拉取请求中的上下文增长
• 插件系统：自定义评分器、压缩器、token 估算器、摘要器
• 缓存后端：内存、本地文件、Redis
• Doctor 命令：诊断环境、Python 版本、磁盘空间和 Git 可用性

文档

• 快速入门 - 60 秒内创建第一个包
• CLI 参考 - 所有命令和标志
• MCP 和 Hooks - Agent 集成、工具列表、确定性上下文注入
• 配置 - redcon.toml 字段
• 工作区 - 多仓库设置
• Python API - 编程方式使用
• Agent 集成 - 中间件层
• 插件 - 自定义扩展
• 架构 - 各部分如何协同工作
• 迁移说明 - 跨版本升级

许可证

本仓库中的所有内容均根据 功能源代码许可证，FSL-1.1-MIT 授权：可自由用于任何用途，但不得用于构建具有竞争关系的商业产品或服务。每个版本发布两年后，将自动转为 MIT 许可证。

托管版 Redcon Cloud 控制平面（组织、配额、用量计量、账单、团队仪表板）是独立的商业软件，由私有仓库维护。

商业许可：[email protected]