Token Savior

---

谁为这个代码仓库点了星？

2026 年 6 月 30 日，GitHub 将点星者和关注者列表限制为代码仓库管理员及协作者可见，这让所有“谁为我的代码仓库点了星”工具同时失效。我重新构建了一个仍可用的工具，正是因为它只读取你拥有或有权推送的代码仓库：starscope 会按影响力为你的代码仓库点星或派生的人排序，并在他们的 GitHub 个人资料中公开社交账号时将其显示出来。

用它计算出的本代码仓库数据：1,147 人，其中 27% 有公开社交账号，关注者最多的人有 18,922 名关注者。具名列表仅代码仓库所有者可见，其他人均不可见——公开页面仅显示汇总数据。

---

新功能

发布说明存放在与代码同步更新的位置：

• CHANGELOG.md 查看完整历史记录
• Releases 查看已标记的构建版本
• PyPI 查看 pip 实际会安装的内容

---

快速开始

pip install "token-savior-recall[mcp]"

添加到 MCP 配置中（例如 Claude Code）：

{
  "mcpServers": {
    "token-savior-recall": {
      "command": "/path/to/venv/bin/token-savior",
      "alwaysLoad": true,
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code",
        "TOKEN_SAVIOR_PROFILE": "optimized"
      }
    }
  }
}

在 Claude Code（2.1.28x 及更高版本）中，"alwaysLoad": true 很重要：没有它，服务的每个工具都会隐藏在 ToolSearch 后面，而模型会改用已经加载的 Read 和 Grep。该选项推出之前，在本项目基准测试中测得：143 个会话中只有 1 个调用了 Token Savior 工具。启用后，每个会话的清单只需消耗几千个缓存 token。

就这样。TOKEN_SAVIOR_PROFILE=optimized 附带在 tsbench 中表现最佳的帕累托最优配置。它包含：

• tiny_plus（包含 15 个常用工具的清单）
• 精简的 inputSchema（清单缩减 44%）
• 禁用捕获沙箱
• 启用内存钩子保护，确保跨项目安全

无需其他调优。

---

启用（Bash 压缩 + 重写）

Bash 压缩和 PreToolUse 重写器均为可选功能。只需设置两个环境变量并调用一次 CLI：

export TS_BASH_COMPACT=1       # PostToolUse output compactors (34 of them)
export TS_BASH_REWRITE=1       # PreToolUse command rewriter (10 rules)

ts init --agent claude --yes   # auto-merge hooks into ~/.claude/settings.json

ts init 可重复运行，不会产生重复配置。它会检测已有的钩子条目，按 (matcher, command) 去重，打印统一差异，并在写入前将 settings.json 备份为 .bak-YYYYMMDD-HHMMSS（UTC）。支持的 Agent： claude、cursor、gemini、codex、openclaw。传入 --dry-run 可预览，或传入 --global 写入用户级配置。

可选：记录每次重写的审计日志：

export TS_BASH_REWRITE_LOG=$HOME/.local/state/token-savior/rewrites.jsonl

---

压缩器目录（34）

系列	压缩器
git	status、diff、log、push/pull、commit、add、fetch、checkout、branch、worktree list、stash list
gh	run list、run view、pr diff、pr view、issue view、repo view
测试/ lint	pytest、jest、vitest、eslint、biome、cargo test、cargo build/clippy、tsc
云	kubectl get、kubectl logs、aws sts、aws ec2、aws lambda、aws logs、aws iam、aws dynamodb、aws s3
docker	docker ps、docker logs
打包	npm/yarn/pnpm list、pip list/show
shell 通用项	grep、find、cat、curl

每个压缩器都是纯函数（无 I/O、无全局变量），返回节省 token 的呈现结果。没有匹配器触发时，分发器会返回 None，现有沙箱流程不受影响。复合命令（cd ... && cmd）会回退到最后一个有意义的片段。

这些功能在 PostToolUse 中运行，因此不会缩减当前轮次的内容。 钩子在工具返回后触发；它只能添加上下文，不能移除上下文。精简后的呈现结果会附加在原始输出下方，原始输出仍会保留。它带来的好处是持久化：完整输出会写入捕获沙箱，并在上下文压缩后继续保留。若要实际减少传给模型的内容，请使用 PreToolUse 重写器（TS_BASH_REWRITE=1）——它会在命令运行前修改命令。

---

ts_discover -- 查找遗漏的 TS 使用机会

新增 MCP 工具，可扫描你的 Claude Code 对话记录，找出本可使用 TS 工具以更低成本完成、但 Agent 实际采用了其他方式的模式。

ts_discover()                       # active project, last 30 days
ts_discover(project=None)           # ALL transcript projects
ts_discover(format="adoption")      # TS vs native ratio per session
ts_discover(format="adoption_json") # same, JSON

发现的问题包括：Read->Grep->Read 调用链、连续调用 find_symbol、未使用 get_edit_context 就进行编辑、未使用 memory_index 就调用 memory_search、对代码文件使用原生 shell。参数会精简为承载关键信息的字段（保护 PII）。以 JSONL 流式输出，并根据修改时间快速跳过未变更内容。

---

ts init CLI

ts init --agent claude [--global] [--dry-run] [--yes]
ts init --agent cursor
ts init --agent gemini
ts init --agent codex
ts init --agent openclaw

检测目标 Agent 的设置位置，深度合并 Token Savior 钩子配置（PostToolUse + PreToolUse），保留现有钩子、去重并打印统一差异。备份为 settings.json.bak-YYYYMMDD-HHMMSS（UTC）。重复运行不会产生任何变更。

---

功能说明

Claude Code 会读取整个文件来回答有关三行代码的问题，并且会在会话结束时忘记所有内容。Token Savior 同时解决这两个问题，还覆盖第三个方面：通过在命令运行前重写命令，限制会占用轮次预算、干扰代码读取的冗长 Bash 输出。

它会按符号为代码库建立索引——函数、类、导入项、调用图——让模型通过指针导航，而不是使用 cat。实测结果：在 170 多个真实会话中，注入的字符减少了 97%。

此外，它还配备了持久化记忆引擎。所有决策、错误修复、约定、护栏和会话摘要都会存储在 SQLite WAL + FTS5 + 向量嵌入中，并根据贝叶斯有效性和 ROI 排序，然后在下一个会话开始时以精简的增量内容重新注入。

而在此之上，自 v4.1 起还加入了 Bash 精简器和 PreToolUse 重写器。性能数据见上文。

这两者中，哪个真正缩短了轮次，哪个不会。 测量日期为 2026-08-09。值得明确说明这一点，因为两者的区别并不显而易见：

• PreToolUse 重写器会在命令运行之前修改命令，因此产生的输出更少，传给模型的输出也更少。这确实能缩短当前轮次。
• PostToolUse 精简器会在工具返回之后运行。PostToolUse 钩子只能添加上下文；它触发时，原始输出早已发送。精简后的内容会被附加上去，而不是替换原有内容。精简器真正带来的价值有所不同，但依然重要：完整输出会保存在捕获沙盒中，并在上下文压缩后保留，因此之后可以查询，而不必重新运行命令。

如果你希望缩短轮次，请启用 TS_BASH_REWRITE=1。如果你希望避免命令输出在上下文压缩后丢失，请启用 TS_BASH_COMPACT=1。

---

配置对比

配置	暴露的工具	清单令牌数	适用场景
optimized	15	约 1.5 KT	推荐默认配置——在 tsbench 上实现帕累托优势
auto	自适应	约 1-2 KT	基于各客户端遥测数据（实验性）
tiny	6	约 0.6 KT	最小热循环
lean	51	约 4 KT	旧配置——覆盖面更广
compact-only	1	约 0.3 KT	仅 Bash 层（重写器 + 捕获）——你已在其他地方使用符号导航
full	68	约 6 KT	暴露所有工具

你很可能需要 optimized。

---

与相邻工具的组合方式

Token Savior 涉及多个层，而大多数相邻工具只覆盖其中一层。每层的重叠都可选择禁用，因此禁用已有工具覆盖的部分后，通常可以同时运行。感谢 @chirag127 在 #45 中梳理了这些情况。

工具	层	重叠情况	处理方式
RTK（当前无法访问其代码库）	PostToolUse Bash 输出压缩	同一层、相同的 PostToolUse 限制：两者都无法缩减当前轮次	二选一。设置 TS_BASH_COMPACT=0，交由 RTK 处理
serena	符号图导航	与 find_symbol / get_dependents 直接重叠	如果使用 serena 导航，则将 TS 设为 compact-only
codebase-memory	持久化代码图	与记忆引擎重叠	设置 TS_MEMORY_DISABLE=1
Ponytail、Caveman	输出侧压缩（代码和文字）	部分重叠：Token Savior 提供可选启用的 Ponytail 风格规范（TS_DISCIPLINE=1），并已接入其工具	互为补充，无需调整

Token Savior 独有而这些工具不具备的层包括：PreToolUse Bash 重写器（它会在命令运行前缩短命令，而非在运行后缩短输出）、可使索引保持同步的结构化编辑，以及审计工具（detect_breaking_changes、find_dead_code、analyze_config）。

如果你只需要 Bash 层，TOKEN_SAVIOR_PROFILE=compact-only 会仅提供一个工具，同时保留压缩器和重写器运行。这两者中，重写器可以减少当前轮次的开销。

---

Token 节省情况

操作	普通 Claude	Token Savior	减少量
find_symbol("send_message")	41M 字符（完整读取）	67 字符	-99.9%
get_function_source("compile")	grep + cat 链式调用	4.5K 字符	直接获取
get_change_impact("LLMClient")	无法实现	16K 字符	新功能
96 任务 tsbench（Opus，普通模式与 ts 对比）	每个任务 17 221 活跃 Token	每个任务 3 395 活跃 Token	-80%
7 天 Bash 输出基准测试（v4.3）	约 30 K Token/周	约 9.6 K Token/周	约 20.4 K/周

---

安装

pip（MCP 服务）

pip install "token-savior-recall[mcp]"
# Optional hybrid vector search:
pip install "token-savior-recall[mcp,memory-vector]"

uvx（无需 venv，无需克隆）

uvx token-savior-recall

Claude Code 单行命令

claude mcp add token-savior -- /path/to/venv/bin/token-savior

开发

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv .venv
.venv/bin/pip install -e ".[mcp,dev]"
pytest tests/ -q

主分支上的测试套件规模：1898 项通过，2 项跳过。CI 在 Python 3.11 / 3.12 / 3.13 上均通过。

---

自行运行基准测试

上文的压缩器数据来自通过调度器重放真实 Claude Code 对话记录。scripts/ 下有两个脚本：

python3 scripts/bench_compactors_real.py       # match rate + mean savings
python3 scripts/bench_compactors_unmatched.py  # top unmatched commands

第一个脚本会遍历 ~/.claude/projects/*/*.jsonl，通过注册表重放每条 Bash 输出，并报告各类别的节省量和总体匹配率。第二个脚本会对未匹配的命令进行分组，以便从直方图中一目了然地找出下一个压缩器目标。

复现 tsbench 分数

**诚实状态，已于 2026-08-09 核实：**这些说明指向的基准测试仓库返回 404，上方的 BENCHMARK-SUMMARY 链接也一样。为了不留下无法运行的步骤，下面说明测试框架的工作方式，便于根据其方法评判分数：

• 使用确定性种子的生成式玩具仓库，其中埋有四个陷阱：一个符号被定义两次、一条三级调用链、一个 a -> b -> c -> a 导入循环，以及一个名称包含某个有效名称的死函数。
• 八项只读任务，根据 expected 列表和 forbidden 列表进行机械评分。forbidden 列表才是关键所在：答案可能既包含正确目标，也包含错误目标；如果评分器只检查是否包含正确目标，就会将其判为正确。
• 一个运行普通 Read/Grep/Glob 的 sans_ts 对照组；如果没有这个对照组，基准测试就只能比较不同的 Token Savior 配置，永远无法得出“无用”的结论——因此也无法得出“有用”的结论。

如果你要重新构建测试，这里有一个值得注意的陷阱：测试框架会启动 claude -p，该命令会继承 ~/.claude/settings.json。如果机器上启用了任何 Token Savior PreToolUse hook，它也会应用于对照组，从而操纵比较结果。请在两个组中都停用这些 hook（TS_GUARD_OFF=1 TS_READ_GUARD=0 TS_BASH_REWRITE=0）。

---

额外内容：供非 MCP Agent 使用的 ts CLI

对于没有 MCP 的 Agent（Cursor、Aider、Continue、脚本、CI），ts 命令可通过 shell 提供部分工具：

ts use /path/to/project
ts get my_function          # JSON output
ts search 'pattern'
ts daemon start             # ~145ms per call vs 1.5s cold fork
ts init --agent cursor      # wire up Bash hooks for non-Claude agents

在 Claude Code 上，建议优先使用 MCP 服务——实测比 CLI 更省 Opus 4.7 的用量。CLI 是为可移植性场景提供的。

---

环境变量

全部为可选项。标为 =1 的值不接受其他值——请设为 1；标为 bool 的值接受 1/true/yes（以及注明的 on）。

服务与工具清单

变量	默认值	用途
WORKSPACE_ROOTS	当前目录	要建立索引的项目根目录，以逗号分隔。Codex 注意事项：Codex 会对白名单过滤 MCP 服务环境变量，因此导出的 shell 变量不会传入——请在 config.toml 的 [mcp_servers.token-savior] env（或 env_vars）下设置
PROJECT_ROOT	—	WORKSPACE_ROOTS 的单根目录替代方案
CLAUDE_PROJECT_ROOT	—	有意指定的活动项目覆盖项（Token Savior 自身的约定——没有宿主会设置它）。如果有效，则注册，并优先于其他所有启动信号
TS_STICKY_ACTIVE	关闭（布尔值，也接受 on）	固定活动项目：显式的 project= 提示和绝对路径参数仍会为每次调用指定路由，但不会有调用重新指向共享默认项目。适用于并行 Agent 在同级工作树中的情况
TOKEN_SAVIOR_PROFILE	full	工具配置。optimized——快速入门配置和 ts init 推荐使用的值——采用帕累托清单，启用精简 schema，并从清单中省略捕获工具
TS_THIN_SCHEMAS=1	关闭（在 optimized 中开启）	从清单中移除冗长的工具 schema
TS_DISCIPLINE	关闭（布尔值）	采用 Ponytail 风格的会话指令：通过 get_edit_context 确定范围，完成尽可能小且完整的更改；通过 search_codebase 复用发现的内容；最后用一行说明跳过了什么。默认关闭：在 tsbench 中，每个会话会多耗费 3-4 %，但未测得任何收益
TS_PROMPTS	开启（布尔值）	review / audit / lean MCP 提示词（Claude Code 中的斜杠命令）。调用前不产生开销。设为 0 可移除
TS_AUTO_HOT_K	8	遥测驱动的 auto 配置所公开的热门工具数量（总计 13 个工具）
TS_LEVEL_BANDIT	关闭	未提供 level 时，让 Thompson 抽样老虎机选择 get_function_source / get_class_source 的详细程度。默认关闭：它曾逐渐改为提供摘要而非源码
TS_EXECUTE_MAX_CHARS	60000	ts_execute 结果的上限；超过上限时会截断返回值并报告截断情况
TS_GUARD_READ_FREE_LINES	200	规范守卫：对已建立索引代码进行整文件 Read，行数不超过此值时允许通过
TOKEN_SAVIOR_CHAIN_NUDGE	开启	设为 0/false/off 可禁用链式工具提示
TS_MEMORY_DISABLE=1	关闭	禁用记忆引擎（适用于干净上下文工作负载）
TS_CAPTURE_DISABLED=1	关闭	跳过读取侧捕获沙箱，并从清单中移除捕获工具（没有任何配置会切换此项；optimized 只会隐藏捕获工具）
TS_CODE_MODE_DISABLE=1	关闭	禁用代码模式工具
TS_CODE_MODE_NODE	node	代码模式沙箱使用的 Node 二进制文件
TS_RESOURCES_DISABLED	关闭（布尔值）	不将观察结果作为 ts://obs/{id} MCP 资源公开
TS_WARM_START	关闭（布尔值）	启动时预先构建项目槽位
TOKEN_SAVIOR_NO_WARMUP	关闭（布尔值）	跳过 ts_search 嵌入预热
TS_SEARCH_COLD_DELEGATE	关闭（布尔值，也接受 on）	将冷启动的 ts_search 调用委托给正在运行的 ts 守护进程
TS_SOCK	/tmp/ts.sock	ts 守护进程的 Unix 套接字（CLI + 冷启动委托）
TOKEN_SAVIOR_CLIENT	自动检测	用于遥测/客户端检测的客户端标签（claude-code，……）
TOKEN_SAVIOR_SESSION_LABEL	—	附加到会话遥测的自由格式标签

索引

变量	默认值	用途
INCLUDE_PATTERNS	内置列表	以冒号分隔的 glob；替换默认包含列表
EXCLUDE_PATTERNS	内置列表	以冒号分隔的 glob；替换默认排除列表
EXCLUDE_EXTRA	—	以冒号分隔的 glob，追加到默认排除项
TOKEN_SAVIOR_EXCLUDE_PATTERNS	—	在索引器级别追加的、以冒号分隔的 glob
TOKEN_SAVIOR_MAX_FILE_SIZE	500000	要索引的最大文件大小（字节）
TOKEN_SAVIOR_MAX_FILES	10000	每个项目的最大文件数
TOKEN_SAVIOR_WATCHER	auto	文件监视器：auto / on / off
TS_WATCHER_FORCE_POLLING	off	强制使用轮询监视器后端

Claude Code 钩子

变量	默认值	用途
TS_CAPTURE_THRESHOLD_BYTES	4096	要进行沙盒处理的工具输出最小大小
TS_CAPTURE_REPLACE=1	off	强制替换：告知 Agent 忽略内联输出，并通过 capture_get 获取 URI
TS_CAPTURE_TTL_DAYS	30	超过此期限的捕获内容会在下一次 capture_put 时清除；0 表示禁用 GC
TS_BASH_COMPACT=1	off	PostToolUse 压缩器。在压缩后保留输出；不会缩短当前轮次（见上文说明）
TS_COMPACT_INLINE_THRESHOLD	4096	混合模式：压缩结果大小超过此值时，也会将完整原始内容放入沙盒
TS_COMPACT_TINY_THRESHOLD	256	混合模式：压缩结果大小低于此值时，始终跳过沙盒处理
TS_BASH_REWRITE=1	off	启用 PreToolUse Bash 命令重写器
TS_BASH_REWRITE_LOG	—	记录每次重写的 JSONL 审计日志
TS_HOOK_MINIMAL=1	off	SessionStart 记忆钩子仅输出 Memory Index 块

记忆扩展功能

变量	默认值	用途
TS_VIEWER_PORT	off	观察记录 Web 查看器的端口（未设置 = 禁用）
TS_AUTO_EXTRACT=1 + TS_API_KEY	off	使用大模型自动提取记忆观察记录（需要 Anthropic API 密钥）
TS_MODEL	claude-sonnet-4-6	自动提取模型覆盖项
TOKEN_SAVIOR_MEMORY_AUTO_SAVE=1	off	自动保存记忆观察记录
TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID	—	重要观察记录推送

存储、仪表板与调试

变量	默认值	用途
TOKEN_SAVIOR_STATS_DIR	~/.local/share/token-savior	遥测数据和统计信息目录
TOKEN_SAVIOR_DASHBOARD_HOST	127.0.0.1	仪表板绑定主机
TOKEN_SAVIOR_DASHBOARD_PORT	8921	仪表板端口
TOKEN_SAVIOR_INCLUDE_TMP_PROJECTS	off (bool)	仪表板也列出临时目录下的项目
TOKEN_SAVIOR_DEBUG=1	off	调试日志
TOKEN_SAVIOR_TRACE	off (bool)	MCP 请求生命周期跟踪

不可配置项：CLAUDECODE、CLAUDE_CODE_ENTRYPOINT、CLAUDE_PROJECT_DIR、 CLAUDE_CONTEXT_REMAINING_PCT、CODEX_* 和 HERMES_* 用于检测宿主端/客户端 并提供启动时的项目提示——这些变量由环境设置，而非由你设置。 （CLAUDE_PROJECT_DIR 是 Claude Code 实际导出的变量；它始终指向主检出目录，而不是会话 所在的工作树，因此当启动目录是关联工作树时，启动目录优先级更高。CLAUDE_PROJECT_ROOT 已移入上方的配置项表：只有你会设置它。）

命名陷阱：基准测试代码片段中的 TS_PROFILE 是 tsbench 的变量； 服务读取的是 TOKEN_SAVIOR_PROFILE。

---

许可证

MIT