开源 Agent 套件 ECC 怎么管 token：上下文预算这条线上的可调旋钮
本文基于 ECC 仓库 commit 591ab5c（2026-07-29）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/affaan-m/ECC 最新代码与文档为准。
装一套增强件会不会把上下文吃光，取决于哪些东西常驻、哪些按需加载，而不取决于仓库里有多少文件。 ECC 这套挂在编码 Agent 之上的增强件，agents 目录 67 个 agent、skills 目录 281 个技能、commands 目录 94 个命令，光看数量确实吓人。但真正每轮对话都压在你窗口里的，只是其中很小一部分，剩下的要么按需加载，要么根本不进上下文。搞清楚这个分界线，才谈得上”调”。
站内已经有几篇讲通用方法论的文章：token 成本优化讲怎么系统性省钱，Agent 框架的 token 效率对比不同框架的开销结构，上下文窗口是什么补基础概念。这篇不重复那些，它只干一件事：拿 ECC 这个具体项目当样本，看一套真实存在的开源增强件是怎么把这些道理落成文件、钩子和环境变量的。方法论你可以去上面几篇看，落地长什么样看这篇。
一、先分清哪些东西常驻，哪些不是
ECC 仓库里有一份 docs/capability-surface-selection.md，是它给自己定的路由规则：一个能力该做成 rule、skill、MCP server 还是普通脚本。这份文档把判断标准写得很直白——rules 是”总是生效”的确定性约束，路径或事件一匹配就注入；skills 是按需加载的工作手册，只在任务真的需要时才进来；MCP 适合需要长期存在的结构化工具面；能用本地脚本解决的就别起服务。
这个排序本身就是 token 排序。文档里明说了，选择面向的目标之一就是把 token 成本控制住，不制造多余的运行时负担。所以 281 个技能这个数字对你的上下文来说基本没有意义，有意义的是你装了几条 rule、开了几个 MCP server、CLAUDE.md 写了多长。
skills/context-budget/SKILL.md 里的几条判断更具体，也更反直觉：
- agent 的
description字段是永远在场的。哪怕这个 agent 你一次都没调用过，它的描述文字也会出现在每次 Task 工具的上下文里。技能里把超过三十来个词的描述直接标成”膨胀”。 - MCP 是最大的那根杠杆。技能给的估算口径是每个工具 schema 按固定量级折算，一个工具数量偏多的 server，开销可以超过你所有技能加起来。
- agent 文件本身太长也会拖累——文件行数过多会在每次派发时抬高上下文。
README 里那条红线也是同一个意思：每个项目开启的 MCP server 数量要克制。docs/token-optimization.md 转述了这条，并且补了一句更实际的建议——能用命令行工具就别套 MCP，比如有 gh 就别再挂一个 GitHub MCP。
二、context-budget：把开销当账本盘一遍
skills/context-budget/SKILL.md 是这条线上最”工程化”的一块。它不给你玄学建议，而是走四个阶段。
盘点阶段扫描各个组件目录，分别估算 agents/*.md、skills/*/SKILL.md、rules/**/*.md、MCP 配置和 CLAUDE.md 链条的 token 量。估算口径写死在技能里：散文按词数乘系数，代码密集的文件按字符数折算。它还专门提了一个细节——技能可能在另一个目录下存在完全相同的副本，遇到一模一样的要跳过，否则会重复计数。
分类阶段把每个组件塞进三个桶：总是需要的（被 CLAUDE.md 引用、支撑某个活跃命令、或者匹配当前项目类型）、有时需要的（领域相关但没被引用，考虑改成按需激活）、很少需要的（没有命令引用、内容重叠、跟项目对不上，删掉或者延迟加载）。
检测阶段找的是几类固定病症：描述膨胀的 agent、行数过多的重型 agent、跟 agent 逻辑重复的技能、跟 CLAUDE.md 重复的 rule、MCP 订阅过量、CLAUDE.md 里塞了本该是 rule 的指令。
报告阶段输出一张组件明细表加一份按可省 token 排序的优化清单。技能里还留了 verbose 模式，能出到每个文件的逐项开销和每个 MCP 工具的 schema 估算——文档自己说这个模式是用来定位问题文件的，不适合当日常体检。
有意思的是最后一条最佳实践：改完就跑一次。加了任何 agent、技能或者 MCP server 之后立刻盘一遍，把蔓延掐在早期。这跟站内那篇上下文预算怎么定讲的思路是一致的，区别只是 ECC 把它写成了一个可以直接触发的流程。
三、这条线上都有哪些东西，各在哪
| 组成部分 | 它负责什么 | 仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 上下文开销盘点 | 清点 agent、技能、rule、MCP、CLAUDE.md 各吃掉多少，排出可回收项 | skills/context-budget/SKILL.md | 刚装完一批组件、或者会话开始变迟钝时 |
| 压缩时机建议 | 在 Edit/Write 之前判断该不该提示你手动压缩 | skills/strategic-compact/SKILL.md、scripts/hooks/suggest-compact.js | 长会话里跨阶段切换时自动冒出来 |
| 运行期告警注入 | 上下文耗尽、成本、改动范围蔓延、工具循环四类告警 | scripts/hooks/ecc-context-monitor.js | 每次工具调用之后 |
| 本机花费流水 | 会话结束时落一行该会话的累计快照 | scripts/hooks/cost-tracker.js、skills/cost-tracking/SKILL.md、commands/cost-report.md | 想回头看这几天到底花在哪 |
| 回答深度协商 | 在回答之前先让你选详略档位 | skills/token-budget-advisor/SKILL.md | 你明确说了”给我短版本”之类的话 |
| 应用侧成本模式 | 模型路由、预算上限、重试口径、提示缓存 | skills/cost-aware-llm-pipeline/SKILL.md | 你自己写程序去调 LLM 接口时 |
| 设置与习惯清单 | 模型选择、思考预算、MCP 管理、压缩习惯 | docs/token-optimization.md、rules/common/performance.md | 第一次配置环境时 |
| 仓库体检打分 | Context Efficiency 与 Cost Efficiency 各占一项 | commands/harness-audit.md、scripts/harness-audit.js | 想要一个可复现的分数而不是感觉时 |
四、压缩这件事，它做得比”到点提醒”细
skills/strategic-compact/SKILL.md 的出发点是：自动压缩触发的时机是任意的，经常卡在任务中间，把要紧的东西压没了。所以它宁可提示你手动压。
支撑它的脚本是 scripts/hooks/suggest-compact.js，挂在 PreToolUse 的 Edit 和 Write 上。它同时看两个信号，而且明确说了哪个主哪个辅。主信号是上下文实际大小——从钩子载荷里的 transcript_path 读会话记录，取最新一条 usage，把 input_tokens、cache_read_input_tokens、cache_creation_input_tokens 三项加起来，这才是这一轮真实的上下文体积。辅信号是工具调用次数。
技能里对这两个信号的关系有一句挺关键的说明：工具调用次数是个很弱的代理指标——几次大文件读取或者几个 MCP 返回就能把窗口填满，而一堆小调用攒到阈值时窗口可能还空着。所以次数只是兜底，真正该响的时候靠的是体积信号。
阈值全都是环境变量，能改：COMPACT_THRESHOLD 管工具次数那条线，COMPACT_CONTEXT_THRESHOLD 管上下文体积那条线（设成零就是关掉体积信号），COMPACT_CONTEXT_INTERVAL 管提示重复的间隔，COMPACT_STATE_TTL_DAYS 管临时目录里那些每会话状态文件多久清一次。
窗口大小是自动探测的，从模型标识里的 [1m] 标记判断，或者在观察到的 token 量已经超出常规窗口时反推。文档写得很实在：如果你用的大窗口模型两个信号都不带，得手动设 ECC_CONTEXT_WINDOW_TOKENS，否则阈值会按小窗口算，把占用率报得虚高；没设这个的话它会退而认 CLAUDE_CODE_AUTO_COMPACT_WINDOW。
技能里还有两张我觉得比阈值更有用的表。一张是阶段转换该不该压：调研转规划压、规划转实现压、调试转下一个功能压、试错失败之后压；实现中途别压、多文件重构中途别压。另一张是压缩之后什么活着什么没了——CLAUDE.md 指令、待办列表、记忆文件、git 状态、磁盘上的文件会留下；中间推理、你之前读过的文件内容、多步对话脉络、口头说过的偏好会没。这张表的实际用法是：压之前先把重要的东西写进文件。
五、花掉的东西怎么被看见
stop:cost-tracker 这个钩子在会话结束时往 ~/.claude/metrics/costs.jsonl 追加一行 JSON。skills/cost-tracking/SKILL.md 和 commands/cost-report.md 都把行结构写清楚了：时间戳、会话 id、记录路径、模型、输入输出 token、缓存写入与读取 token、以及一个预先算好的累计估算金额。
这里有个容易算错的地方，两份文档都特意强调了：每一行是那个会话到当时为止的累计快照，不是增量。要算总量得先按会话 id 取最新一行再相加，一行行全加会重复计数。另外它们统一用 node 而不是 sqlite3 或 jq 来处理，理由是跨平台行为一致——这是个很小但很体面的决定，Windows 用户会感谢它。
scripts/hooks/ecc-context-monitor.js 是另一条线。它挂在 PostToolUse 上，读上游桥接文件，在跨过阈值时往上下文里注入面向模型的告警，分四类：上下文耗尽、成本、改动范围蔓延、工具循环。如果你是订阅制用户，看到按 API 计价折算出来的估算会觉得莫名其妙——文档给了一个精确到只关一类的开关：
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off
关掉的只是面向模型的成本估算提示，上下文耗尽、范围、循环这三类告警照常，/cost 和成本遥测文件也不受影响。这种”只关一类”的粒度，比一刀切关掉整个监控要好用。
会话内的日常习惯那部分，docs/token-optimization.md 归纳得比较朴素：/clear 用在两个不相干的任务之间，因为陈旧上下文会在之后每一条消息上重复收费；/compact 用在逻辑断点；/cost 看当前会话。模型层面它建议把日常挡在中档模型上，复杂推理再用 /model opus 切上去，简单查询用轻量模型。这套跟站内的Claude Code 上下文管理讲的操作是同一层的，差别在于 ECC 把”什么时候该切”写进了 rules/common/performance.md，让它成为一条常驻约束而不是靠你记。
六、同一套思路，怎么搬进你自己的程序
skills/cost-aware-llm-pipeline/SKILL.md 是这条线上唯一一个不管你的编码会话、而是管你写的应用的技能。它把四件事拼成一条流水线。
模型路由：按输入长度和条目数量判断复杂度，简单的走轻量模型，超过门槛才升级，同时留一个强制指定的口子。成本追踪：用不可变数据结构记账，每次调用返回一个新的追踪器而不是改旧的，理由写在反模式清单里——可变状态让调试和审计都变难。重试口径：只对瞬时错误重试，认证错误和请求格式错误立刻抛出。
_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
提示缓存：把长系统提示标出来，让它不必每次重发。
{
"type": "text",
"text": system_prompt,
"cache_control": {"type": "ephemeral"},
}
技能末尾那份反模式清单值得单独看一眼：所有请求都用最贵的模型、对所有错误都重试、可变的成本状态、模型名硬编码在代码各处、重复系统提示不做缓存。这五条里前两条最常见，第四条最难改。
七、边界与代价：它明确不管的那些事
估算不是计量。 context-budget 的 token 数是按词数和字符数折算出来的，cost-tracking 里的金额字段名字本身就带”估算”二字，skills/token-budget-advisor/SKILL.md 更是直接写明自己没有真实分词器、纯启发式、还要求把误差声明展示给用户。你可以拿这些数做趋势判断和优先级排序，但别拿它去跟账单对账。
订阅制下的成本提示可能就是对不上。 这一点文档没有回避，docs/token-optimization.md 直接建议订阅用户把那类告警关掉。各家服务商的计费与额度规则不同且会调整，以官方最新说明为准——ECC 这边给的只是本机遥测折算出来的估计值。
它要往你机器里写东西。 钩子是在 PreToolUse、PostToolUse、Stop 这些时机跑 Node 脚本，压缩提示会在系统临时目录写每会话状态文件，花费流水会往用户目录下写 JSONL。安装流程会往用户级配置里落文件。这些都是实打实的副作用，装之前该知道。好在钩子的开关粒度做得不错，hooks/README.md 里给了运行期控制方式：ECC_HOOK_PROFILE 选三档配置（minimal 只留必要的生命周期与安全钩子，standard 是默认，strict 更严），ECC_DISABLED_HOOKS 按 id 逐个关，ECC_SESSION_START_MAX_CHARS 限制会话启动时注入的附加上下文长度，ECC_SESSION_START_CONTEXT 干脆整个关掉。
它不管服务商侧的账单，也不管你的提示词写得好不好。 这条线上所有东西的作用域都是”你本机这台机器上的会话”。跨人、跨团队的口径要另外做。
并发那条路它标了警告。 关于多个独立上下文并行工作的实验特性，文档写得很明确：每个参与者单独消耗，只在并行确实有价值的场合用，简单的顺序任务用 Task 工具那层更省。
有一个配置项它建议你别碰。 关于自动压缩阈值的那个覆盖变量，文档转述了社区反馈：某些版本里它可能只能把阈值往低了调，结果是压得更早而不是更晚。遇到这种情况的建议是把覆盖去掉，回到手动压缩加 strategic-compact 的提示。这种”我们也不确定，先别用”的写法，在开源文档里不算多见。
八、上手与避坑清单
插件装和手动装的钩子配置不一样，抄错会双跑。 为什么会踩：skills/strategic-compact/SKILL.md 里贴了一段往用户 settings.json 里加钩子的 JSON，很容易顺手就复制。但技能里紧接着写了——如果你是以插件方式安装的，钩子已经在插件自己的 hooks/hooks.json 里注册好了（id 是 pre:edit-write:suggest-compact），插件安装根本不存在那个脚本目录，抄进去只会让钩子跑两遍。怎么避：先确认自己是哪种安装方式，插件装的直接跳过那段 JSON。
想关 MCP 别去改设置文件。 为什么会踩：直觉上禁用一个已加载的组件应该改配置文件。但 docs/token-optimization.md 说得很清楚，项目级和本地级的设置文件都不能用来关掉已经加载的 MCP server，得用 /mcp 做运行期变更，而运行期禁用会被持久化到用户目录下的配置里。怎么避：运行期用 /mcp，同时记住 ECC_DISABLED_MCPS 只影响安装与同步流程里生成的 MCP 配置输出，它不是一个实时开关。
大窗口模型不设窗口变量，占用率会被算高。 为什么会踩：窗口大小靠自动探测，模型标识里没有对应标记的话就按常规窗口算。你用着一个大窗口模型，却一直被提示该压缩了。怎么避：显式设 ECC_CONTEXT_WINDOW_TOKENS。
默认配置里有个没人用的 MCP server。 为什么会踩：默认配置带上了，你自然以为它在被用。但 docs/token-optimization.md 写着：那个 memory server 是默认配置的，却没有任何技能、agent 或钩子在用它——纯占位。怎么避：盘点的时候第一个考虑关掉它。这个例子挺说明问题的，占用上下文的东西未必是你主动装的。站内那篇MCP 工具数量怎么控讲的就是这类账。
别指望技能文档里提到的命令名一定有对应文件。 为什么会踩：context-budget 的触发条件里写了一个斜杠命令名，看着像是可以直接敲。但 commands/ 目录下并没有同名文件——这是个正在高频迭代的仓库，文档和目录不同步很正常。怎么避：真要用的时候，先去 commands/ 目录确认一遍；确认不到就直接按技能名称唤起。
装的时候就该做减法，而不是装完再回头减。 为什么会踩：全量装最省事，结果是先把上下文撑起来再花时间往回收。但仓库里 manifests/install-profiles.json 已经把选择性安装做出来了，里面的 minimal 档案描述里明写着是低上下文配置，带 rules、agent、命令和平台配置，不带钩子运行时。docs/SELECTIVE-INSTALL-ARCHITECTURE.md 里还列了配套的计划、状态与体检脚本，装之前可以先看计划再决定落不落。怎么避：先按档案装最小集，缺什么再按模块加。
压缩别在多文件改动中间做。 为什么会踩：提示是按体积和次数触发的，它不知道你正改到一半。怎么避：把决策表记住——提示告诉你”什么时候”，是否真压由你判断，这句话是技能里的原话。
最后，给自己一份自检
装完这套东西，值得当场问自己四个问题：我开了几个 MCP server，其中有几个是本地命令行工具就能替代的；我的 CLAUDE.md 链条有多长，里面有多少内容其实该是 rule；我装的那些 agent，描述字段是不是都在合理长度内；我知不知道自己上一周花在哪个模型上。前三个问题 context-budget 能替你答，第四个问题得看那份本机流水。
接着读哪个文件，按你的处境挑：想调设置，读 docs/token-optimization.md 和 rules/common/performance.md；想搞清压缩机制，读 skills/strategic-compact/SKILL.md 再对着 scripts/hooks/suggest-compact.js 看一遍；想控钩子的副作用，读 hooks/README.md 里运行期控制那一节；想把成本控制搬进自己的程序，读 skills/cost-aware-llm-pipeline/SKILL.md。这个项目采用 MIT 许可证，所有判断你都能自己回仓库核一遍——考虑到它迭代得这么快，也建议你核一遍。
本文属于 ECC 开源 Agent 套件专题（共 40 篇，从选择性安装一直拆到内部机制）。同一批还写了另一种取向的项目——不给你资产、只给你纪律的 superpowers 方法论专题。