shyamsridhar123/TokenMasterX

# TokenMaster

**代码理解代理的新成本模型。** TokenMaster 重新设计了 *绑定层的令牌经济学* —— 决定模型在每一轮中重新读取什么的层 —— 为 [Claude Code](https://docs.claude.com/en/docs/claude-code) 和 GitHub Copilot CLI。 一句话的论点：**模型应该一次性支付以理解代码库的结构，然后不再支付。** 今天的绑定器在每一轮都违反了这一点 —— 它将不断增长的记录交给模型，让它通过 grep 的方式理解，然后在每一轮都为整个累积的上下文重新支付。 ### 基线与 TokenMaster 的比较，测量结果 相同的 CLI。相同的模型。相同的任务。唯一不同的是 TokenMaster 的路由代理是否开启。 ``` /token-master ``` 这个命令为当前存储库构建索引并开启路由。 ## 为什么是令牌经济学，而不是令牌 *计数* 从以下一个事实开始：**模型在轮次之间没有记忆。** 为了继续任务，绑定器在每一轮都重新发送 *整个* 记录——每个读取的文件、每个工具的结果、每个消息——然后模型重新阅读并重新推理所有这些内容，然后再做任何新的操作。 因此，令牌不是一次性支付的。它是为 **它保持在上下文窗口中的每一轮而支付的。** 重要的成本不是 *发送的令牌*，而是 **处理的总令牌，汇总到任务完成的每一轮**。 ### 相同的答案，两种账单 任务：*"谁调用了 `load_config`?"* 上下文在每一轮都会增长，因此每一轮都会为之前的轮次重新支付。 ``` GREP its way there GRAPH lookup turn 1 grep 2,000 turn 1 query graph 2,500 turn 2 read auth.py 6,000 turn 2 answer 3,000 turn 3 read server 11,000 ────────────────────────── turn 4 read handlers 17,000 TOTAL PROCESSED 5,500 turn 5 grep narrower 19,000 turn 6 read config 24,000 turn 7 answer 26,000 ────────────────────────── TOTAL PROCESSED 105,000 ``` 相同的答案。**105,000 与 5,500 个处理的令牌。** grep 的总数不是 26,000——它是 *所有七轮的总和*，因为第七轮重新阅读了第一轮看到的，六次。 ### 它是曲线下的面积 绘制每一轮的上下文大小并测量面积。单独看起来很便宜的一轮是一个陷阱；真正花费你的是整个阴影区域。 ``` context │ ___________ grep: climbs AND runs long │ __/ -> big area, expensive │ __/ │ __/ │ __/ │ /__________ graph: stays low AND ends fast -> tiny area └──────────────────────────► turns ``` ### 提供图表还不够——你必须强制执行 单独放置，模型会默认使用 grep，因为它已经成为习惯：在 TokenMaster 的自己运行中，它只有在被积极路由到那里时才会 **0/15 次地** 伸手到图中。因此，TokenMaster 不仅仅是 *提供* 便宜的道路——它使预构建的图成为结构问题的 **默认** （“谁调用了 X”，“如果我更改 Y 会发生什么？”）。提供节省不了什么；强制执行是缩小曲线下面积的方法——而且这种缩小正是上面提到的 `-73%` 的标题。 ## 通过数字 首先在 **Django**（992 个 `.py` 文件，硬多跳任务）上得到证明，然后在独立的 SWE-bench Lite 存储库上复制，以排除单个存储库的运气。整个测量过程：完成结构任务的累积输入令牌，**基线代理与带有 TokenMaster 的相同设置**。 ### 池化标题 *36 次活 GitHub Copilot 运行。2 个存储库 x 3 个任务 x 2 个重复 x 3 个臂.* | | 基线 | **TokenMaster** | Delta | | --- | :---: | :---: | :---: | | 累积输入令牌 | 基线 | **-73.1%** | **3.71x 更少** | | 从图中回答的任务 | n/a | **12 / 12** | 永远没有回退 | | 与 AST 神谕的正确性 | 通过 | **通过** | 没有回归 | ### 胜利在哪里 遍历越困难，缩小就越大。调用查找节省 3-5 倍；爆炸半径分析（“如果我更改这个会发生什么？”）是基线代理爆炸的地方，它手动在存储库的整个范围内重新读取文件以跟踪影响，而一个有界图查询在这里赢得最大： ``` Cumulative input tokens to finish the task (lower is better) "Who calls X?" - reverse dependency lookup scikit-learn Baseline █████████ 69,609 scikit-learn TokenMaster ███ 21,215 3.3x fewer sympy Baseline ██████████████ 107,954 sympy TokenMaster ███ 21,189 5.1x fewer "What breaks if I change this?" - blast radius scikit-learn Baseline ███████████████████████████ 203,481 scikit-learn TokenMaster ████ 26,908 7.6x fewer sympy Baseline ████████████████████████████ 210,214 sympy TokenMaster ████ 26,830 7.8x fewer ``` 在爆炸半径上，基线通过手动跟踪影响超过了 **200,000 个令牌**；TokenMaster 从图中以 **\~27,000** 的数量回答——一个数量级的节省，在两个无关的代码库中重复。 ### 诚实的负面信息——这是方法的证明 一个在每个地方都获胜的绑定器是在衡量一个工件。TokenMaster 不是： - **sympy 上的继承查找运行 -44%** - 图查询成本比基线在该任务上更高。已报告，未隐藏。 - **负控制**（基线在 \~3 轮内就能解决的问题）正确地出现了 **平衡** - 不需要遍历，没有声称获胜。 ## 它是如何工作的 TokenMaster 安装了一个 **路由代理**，它优先选择图查询而不是 grep，由两个可互换的图供应商和主机 CLI 的会话内存支持： | 层 | 供应商 | 角色 | | --- | --- | --- | | **语义-空间**（默认） | [`graphify`](https://github.com/safishamsi/graphify) | 快速，无 LLM 结构索引。从推断边中回答调用者 / 被调用者 / 影响 / 继承者。便宜默认。 | | **精确-空间**（最后一英里） | [`@colbymchenry/codegraph`](https://www.npmjs.com/package/@colbymchenry/codegraph) | AST 解析的调用边。精确升级：当推断边不可靠时——精确影响分析，或稀疏调用图（在 JS/TS 中很常见）中，名称推断连接不足。需要更多令牌来购买精确边。 | | **时间** | 主机 CLI 会话内存 | 原生的跨会话回忆——没有额外的服务器。 | 路由层是产品；索引是可互换的供应商。路由是承载原始的原始操作——在早期测试中，模型在没有明确推动的情况下查询图 **0/15 次**，在有推动的情况下 **8/8 次**。一个模型永远不会查询的图节省不了任何东西，所以 TokenMaster 的任务不是 *提供* 效率的工具，而是使其成为阻力最小的路径。 ## 安装 TokenMaster 支持 **Claude Code** 和 **GitHub Copilot CLI** 两种主机 CLI。安装您使用的路由代理（以下先决条件是共享的）。`/token-master` 为每个存储库构建图并将适当的路由代理安装到您的用户范围 CLI 主目录中。 ### Claude Code TokenMaster 通过插件市场作为 Claude Code 插件分发： ``` /plugin marketplace add shyamsridhar123/TokenMasterX /plugin install token-master@token-master ``` 然后，在您想要索引的任何存储库中： ``` /token-master ``` 安装程序将路由代理写入 `~/.claude/agents/token-master.md` 并在 `~/.claude.json` 中注册图 MCP 服务器。在第一次安装后，**重新启动 Claude Code**（或使用 `claude --agent token-master` 启动它）以使路由生效。 ### GitHub Copilot CLI Copilot CLI 读取与 Claude Code 相同的插件市场，因此安装方式相同。在交互式 `copilot` 会话中： ``` /plugin marketplace add shyamsridhar123/TokenMasterX /plugin install token-master@token-master ``` （等效地，从您的 shell：`copilot plugin marketplace add shyamsridhar123/TokenMasterX` 然后 `copilot plugin install token-master@token-master`。） 然后，在您想要索引的任何存储库中： ``` /token-master ``` 这将为每个存储库构建图并将路由代理（及其 MCP 服务器声明内联）写入 `~/.copilot/agents/token-master.agent.md`。在第一次安装后，**重新启动 Copilot**（或使用 `copilot --agent token-master` 启动它）以使路由生效。 ### 先决条件 - [**`graphify`**](https://github.com/safishamsi/graphify) — 默认图后端。使用 `uv` 安装： ``` uv tool install graphifyy ``` - **`uv`** — 路由代理通过它启动图服务器。 - **`node` + `npm`** *(可选)* — 仅在需要精确 `codegraph` 升级后端时需要。如果没有它们，TokenMaster 运行 graphify-only 并仍然有效。 如果缺少先决条件，`/token-master` 会告诉您确切需要安装的内容，然后重新运行它。 ## 使用方法 设置完成后，只需正常提出结构问题： - *"谁调用了 `force_str`?"* - *"如果我更改此方法的签名会发生什么？"* - *"从 `BaseValidator` 继承的是什么？"* 代理会从图中回答这些问题。要确认路由已激活，请提出一个已知结构问题并检查答案是否来自图工具调用而不是 grep 扫描。 每当代码更改足够多以至于图已过时时，重新运行 `/token-master`。 ## 写入的内容 `/token-master` 对您的工作树很保守： - 代码图存储在存储库中的 `.token-master/graph.json`。 - `.token-master/` 和 `.codegraph/` 被添加到存储库的 `.gitignore`。 - 路由代理和图服务器安装到您的用户范围 CLI 主目录中，而不是存储库。 ## 诚实的限制 - **不是通用的加速。** TokenMaster 在困难的多跳遍历中获胜。对于 grep 在 \~3 轮内就能回答的简短结构问题，它是正确地 *中立* 的。一个在每个地方都获胜的绑定器是在衡量一个工件。 - **graphify 边是推断的；codegraph 是最后一英里。** 默认后端通过名称推断调用边（\~0.8 置信度）——快速且便宜，在命名良好的 Python 上，它大多数时候都能正确回答。`codegraph` 存在是为了购买 *最后一英里* 的精确度：AST 解析的边对于推断不可靠的情况。这种精确度不是免费的。在 SWE-bench Lite 飞行员的测试中，codegraph 的成本比 graphify **\~3-4 倍** 更高，在更简单的调用者/继承者任务中经常运行在基线以下；其解析的边集 **在比较的每个单元格中都与 graphify 的推断集不同**——不同，且精确，但不是免费的升级。数据支持的可取之处：**graphify 是默认的；codegraph 是当精确边值得支付时有意升级的最后一英里**，而不是始终开启的替代品。 - **稀疏调用图。** 在某些语言（特别是 JavaScript/TypeScript）中，graphify 的调用图是稀疏的；设置会检测到这一点并打印一条警告，指向 `codegraph` 后端。 - **累积令牌，而不是美元。** TokenMaster 优化任务上下文大小的积分。计费代理（高级请求，总令牌计数）明确地 *不是* 衡量标准。 ## 存储库布局 ``` token-master-plugin/ The plugin (this is the deliverable) ├── .claude-plugin/ │ └── plugin.json Plugin manifest └── skills/token-master/ ├── SKILL.md The /token-master command ├── setup.py Installer: builds the graph, installs the host agent ├── graphify_mcp.py Graph-query MCP server ├── agent.template.claude.md Routing agent template (Claude Code format) └── agent.template.copilot.md Routing agent template (Copilot CLI format) .claude-plugin/ └── marketplace.json Plugin marketplace manifest (the packager) assets/ ├── generate_art.py Deterministic, dependency-free SVG generator └── tokenmaster-hero.svg The hero image above (reproducible from a seed) ``` 英雄图像是生成的：它 *就是* 论点。微弱的混乱是 brute-force 搜索蔓延——上下文在每一轮后重新读取——而唯一的明亮路径是一个有界图路由查询。使用以下方法重新生成或混音它： ``` python assets/generate_art.py --seed 42 ``` ## 许可证 [MIT](LICENSE)

标签：AI 优化, AI 编码代理, AI 计算效率, AI 记忆, Claude Code, GitHub Copilot, Token 经济学, 代码分析, 代码图, 代码库, 代码搜索, 代码搜索优化, 代码理解, 代码理解工具, 代码理解技术, 代码理解效率, 代码理解模型, 代码理解经济模型, 代码索引, 代码结构, 代码路由, 凭证管理, 模型优化