⚔ token-savior

别再把整个代码库喂给 AI 了。给它一把手术刀吧。

Python 3.11+ MCP

一个对你的代码库进行结构化索引并提供外科手术式查询工具的 MCP 服务器——让你的 AI 代理只需读取 200 个字符，而不是 200 个文件。

find_symbol("send_message")           →  67 chars    (was: 41M chars of source)
get_change_impact("LLMClient")        →  16K chars   (154 direct + 492 transitive deps)
get_function_source("compile")        →  4.5K chars  (exact source, no grep, no cat)
analyze_config()                      →  finds duplicates, secrets, orphan keys

在 782 次真实会话中测得：Token 减少了 99%。

为什么存在这个项目

每个 AI 编码会话的开始方式都一样：代理使用 cat 或 grep，读取十几个文件来查找一个函数，然后为了理解还会破坏什么而导致上下文膨胀。到最后，在第一次编辑之前，你一半的 Token 预算就已经用光了。

token-savior 完全取代了这种模式。它构建一次结构化索引，自动与 git 保持同步，并在亚毫秒级时间内回答“X 在哪里”、“什么调用了 X”以及“如果我修改 X 会破坏什么”——响应大小取决于答案本身，而不是代码库的大小。

数据

真实会话中的 Token 节省情况

项目	会话	查询	使用字符数	字符数 (原始)	节省
project-alpha	35	360	4,801,108	639,560,872	99%
project-beta	26	189	766,508	20,936,204	96%
project-gamma	30	232	410,816	3,679,868	89%
总计	92	782	5,981,476	664,229,092	99%

“字符数 (原始)” = 代理使用 cat/grep 读取的所有文件的总源代码大小。这些节省与模型无关——无论使用哪种提供商，索引都能减轻上下文窗口的压力。

查询响应时间 (110 万行代码下亚毫秒级)

查询	RMLPlus	FastAPI	Django	CPython
`find_symbol`	0.01ms	0.01ms	0.03ms	0.08ms
`get_dependencies`	0.00ms	0.00ms	0.00ms	0.01ms
`get_change_impact`	0.02ms	0.00ms	2.81ms	0.45ms
`get_function_source`	0.01ms	0.02ms	0.03ms	0.10ms

索引构建性能

项目	文件	行数	索引时间	内存
小型项目	36	7,762	0.9s	2.4 MB
FastAPI	2,556	332,160	5.7s	55 MB
Django	3,714	707,493	36.2s	126 MB
CPython	2,464	1,115,334	55.9s	197 MB

借助持久化缓存，后续重启将跳过完整构建。CPython 在缓存命中时从 56 秒缩短至 1 秒以内。

覆盖范围

语言 / 格式	文件	提取内容
Python	`.py`, `.pyw`	函数、类、方法、导入、依赖图
TypeScript / JS	`.ts`, `.tsx`, `.js`, `.jsx`	函数、箭头函数、类、接口、类型别名
Go	`.go`	函数、方法 (接收者)、结构体、接口、类型别名
Rust	`.rs`	函数、结构体、枚举、特征、impl 块、macro_rules
C#	`.cs`	类、接口、结构体、枚举、方法、XML 文档注释
Markdown / 文本	`.md`, `.txt`, `.rst`	通过标题检测的章节
JSON	`.json`	深度达 4 层的嵌套键结构，`$ref` 交叉引用
YAML	`.yaml`, `.yml`	嵌套键层级、数组标记，深度上限 4
TOML	`.toml`	表、键值对、嵌套结构
INI / 属性	`.ini`, `.cfg`, `.properties`	章节、键值对
环境	`.env`	变量名、值 (带密钥掩码)
XML / Plist / SVG	`.xml`, `.plist`, `.svg`, `.xhtml`	元素层级、属性
HCL / Terraform	`.hcl`, `.tf`	块、嵌套资源、键值对
Conf	`.conf`	键值对、块结构
Dockerfile	`Dockerfile`, `*.dockerfile`	指令、多阶段构建、FROM/RUN/COPY/ENV
其他所有	`*`	行数 (通用回退)

51 个工具

工具	功能
`find_symbol`	符号定义位置——文件、行号、类型、20 行预览
`get_function_source`	函数或方法的完整源代码
`get_class_source`	类的完整源代码
`get_functions`	文件或项目中的所有函数
`get_classes`	所有带有方法和基类的类
`get_imports`	所有带有模块、名称、行号的导入
`get_structure_summary`	文件或项目结构概览
`list_files`	已索引文件，支持可选的 glob 过滤
`get_project_summary`	文件计数、包、顶级类/函数
`search_codebase`	在所有已索引文件中进行正则搜索
`reindex`	强制完全重新索引 (很少需要)

上下文与发现

工具	功能
`get_edit_context`	一体化：单次调用获取符号源码 + 依赖项 + 调用者 (节省 3 次调用)
`get_feature_files`	查找与功能关键字相关的所有文件，然后传递性地追踪导入
`get_routes`	检测 API 路由和页面 (Next.js App Router, Express, pages/api)
`get_components`	检测 `.tsx`/`.jsx` 文件中的 React 组件 (返回 JSX 的函数)
`get_env_usage`	查找代码库中对环境变量的所有引用

影响分析

工具	功能
`get_dependencies`	符号调用/使用的内容
`get_dependents`	调用/使用符号的内容
`get_change_impact`	单次调用获取直接 + 传递性依赖项
`get_call_chain`	两个符号之间的最短依赖路径 (BFS)
`get_file_dependencies`	给定文件导入的文件
`get_file_dependents`	从给定文件导入的文件

Git 与差异

工具	功能
`get_git_status`	分支、领先/落后、暂存、未暂存、未追踪
`get_changed_symbols`	以符号级摘要而非差异形式显示已更改的文件
`get_changed_symbols_since_ref`	自任何 git 引用以来的符号级更改
`summarize_patch_by_symbol`	紧凑的审查视图——使用符号而非文本差异
`build_commit_summary`	从已更改文件中生成的紧凑提交摘要

安全编辑

工具	功能
`replace_symbol_source`	替换符号源码而不触及文件其余部分
`insert_near_symbol`	在符号前后插入内容
`create_checkpoint`	编辑前对一组文件进行快照
`restore_checkpoint`	从检查点恢复
`compare_checkpoint_by_symbol`	在符号级别比较检查点与当前状态的差异
`list_checkpoints`	列出可用检查点

测试与运行

工具	功能
`find_impacted_test_files`	从已更改的符号推断可能受影响的 pytest 文件
`run_impacted_tests`	仅运行受影响的测试——紧凑摘要，而非原始日志
`apply_symbol_change_and_validate`	单次调用完成编辑 + 运行受影响测试
`apply_symbol_change_validate_with_rollback`	编辑 + 验证 + 失败时自动回滚
`discover_project_actions`	从项目文件中检测测试/lint/构建/运行命令
`run_project_action`	执行带有边界输出的已发现操作

配置分析

工具	功能
`analyze_config`	扫描配置文件以查找重复项、密钥、拼写错误和孤立键

运行三项检查 (可通过 checks 参数单独切换)：

重复项 — 同一文件中定义了两次的相同键，以及基于 Levenshtein 的拼写错误检测 (例如 db_hsot vs db_host)
密钥 — 已知密钥格式 (API 密钥、令牌、私钥) 的正则表达式模式，以及针对高熵字符串的香农熵分析
孤立项 — 将配置键与实际代码使用情况进行交叉引用。检测代码从不读取的键以及代码期望但未设置的环境变量。理解 os.environ, process.env, os.Getenv, std::env::var 等。

支持的格式：.yaml, .yml, .toml, .ini, .cfg, .properties, .env, .xml, .plist, .hcl, .tf, .conf, .json

代码质量

工具	功能
`find_dead_code`	查找零调用者的函数/类 (排除入口点、测试、装饰路由)
`find_hotspots`	按复杂度评分 (行数、分支、嵌套、参数计数) 对函数进行排名
`detect_breaking_changes`	将当前函数签名与 git 引用进行比较——标记已删除/重命名的参数、更改的默认值

Docker

工具	功能
`analyze_docker`	审计 Dockerfile：基础镜像、暴露端口、ENV/ARG 交叉引用、`latest` 标签警告

多项目

工具	功能
`find_cross_project_deps`	跨项目交叉引用导入以查找共享依赖项

统计

工具	功能
`get_usage_stats`	每个项目在会话中的累计 Token 节省量

与 LSP 的对比

LSP 回答“这里定义了什么？”——token-savior 回答“如果我修改它，什么会坏掉？”

LSP 是点查询：一个符号，一个文件，一个位置。它可以找到 LLMClient 的定义位置以及谁直接引用了它。如果问“如果我重构 LLMClient，什么会发生传递性破坏？”，LSP 就无能为力了——AI 需要递归地链接数十次引用查找调用，并在每一步读取文件。

在 CPython 上执行 get_change_impact("TestCase") 可在 0.45ms 内找到 154 个直接依赖项和 492 个传递性依赖项，返回 16K 字符而不是读取 41M。而且与 LSP 不同，它不需要任何语言服务器——一个二进制文件即可开箱即用支持 Python + TS/JS + Go + Rust + C# + 配置文件 + Dockerfile。

安装

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv ~/.local/token-savior-venv
~/.local/token-savior-venv/bin/pip install -e ".[mcp]"

配置

Claude Code / Cursor / Windsurf / Cline

添加到项目根目录的 .mcp.json 中：

{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/.local/token-savior-venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code"
      }
    }
  }
}

Hermes Agent

添加到 ~/.hermes/config.yaml：

mcp_servers:
  token-savior:
    command: ~/.local/token-savior-venv/bin/token-savior
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: hermes
    timeout: 120
    connect_timeout: 30

TOKEN_SAVIOR_CLIENT 是可选的，但允许实时仪表板按客户端归因节省量。

让代理真正使用它

即使有更好的工具可用，AI 助手也会默认使用 grep 和 cat。软性指令会被合理化忽略。请将此添加到你的 CLAUDE.md 或等效文件中：

## Codebase Navigation — MANDATORY

You MUST use token-savior MCP tools FIRST.

- ALWAYS start with: find_symbol, get_function_source, get_class_source,
  search_codebase, get_dependencies, get_dependents, get_change_impact
- Only fall back to Read/Grep when token-savior tools genuinely don't cover it
- If you catch yourself reaching for grep to find code, STOP

多项目工作区

一个服务器实例覆盖机器上的每个项目：

WORKSPACE_ROOTS=/root/myapp,/root/mybot,/root/docs token-savior

每个根目录都有自己独立的索引，在首次使用时延迟加载。list_projects 显示所有已注册的根目录。switch_project 设置当前活动项目。

如何保持同步

服务器在每次查询前检查 git diff 和 git status (~1-2ms)。已更改的文件会被增量重新解析。编辑、切换分支或拉取后无需手动 reindex。

索引在每次构建后保存到 .codebase-index-cache.json——人类可读的 JSON，在出现问题时可检查，且在不同 Python 版本间安全。

编程使用

from token_savior.project_indexer import ProjectIndexer
from token_savior.query_api import create_project_query_functions

indexer = ProjectIndexer("/path/to/project")
index = indexer.index()
query = create_project_query_functions(index)

print(query["get_project_summary"]())
print(query["find_symbol"]("MyClass"))
print(query["get_change_impact"]("send_message"))

开发

pip install -e ".[dev,mcp]"
pytest tests/ -v
ruff check src/ tests/

已知限制

实时编辑窗口： 索引是 Git 感知的，在查询时更新，而不是在保存时更新。如果你编辑了一个文件并立即调用 get_function_source，你可能会得到编辑前的版本。下一次 Git 跟踪的更改会触发重新索引。
跨语言追踪： get_change_impact 在语言边界处停止。Python 调用 shell 脚本调用 JSON 配置——链条在 Python 之后中断。
JSON 值语义： JSON 注释器索引键结构，而不是值的含义。追踪配置值在文件间如何传播仍然是手动的。

适用于任何兼容 MCP 的 AI 编码工具。
Claude Code · Cursor · Windsurf · Cline · Continue · Hermes · 任何自定义 MCP 客户端

token-savior