skimread

skimread — 阅读前先略读

为 AI 编码 Agent 提供无损上下文保护。 零依赖，完全在本机运行，采用 MIT 许可。开箱即用支持 Claude Code，也可通过 CLI 和 MCP 服务与其他任意 Agent（Codex、Cursor、Aider、Copilot，以及你自己的 Agent）配合使用。

它是什么？

使用 AI 编码 Agent 时，它读取的每个 token 都要付费。其中大部分费用都花在 Agent 实际上并不需要的两件事上：

1. 完整读取大文件。 Agent 只想找一个函数，却读取了文件的全部 2,000 行。下次会话时，它又会重来一遍。
2. 读取嘈杂的命令输出。 pytest -v 会打印 1,500 行 PASSED，只为告诉你有 2 个测试失败。npm install 会打印 40 条弃用警告。cargo build 会列出它编译的每个 crate。

skimread 介入 Agent 与这两类信息源之间，先向 Agent 提供一份略读结果：

• 针对文件：提供大纲，而非整个文件。 当 Agent 即将读取一个大文件时，skimread 会给它一份文件索引（函数、类、标题、键及其行范围），并提示“只读取你需要的片段”。这样 Agent 只需读取 60 行，而不是 2,000 行。
• 针对命令：提供摘要，而非完整输出。 嘈杂的命令会通过 skimread 运行。Agent 能看到错误、失败的测试、你代码中的堆栈帧，以及摘要行。1,500 行 PASSED 会折叠成一行说明。

关键在于无损。没有任何内容会被丢弃。每条命令的完整输出都会保存在你的磁盘上，每份摘要末尾都会附上一个引用方式（skimread show 42、skimread show 42 120-180、skimread show 42 --grep TypeError）。每份大纲都会明确告诉 Agent 接下来要读取的行范围。Agent 不会陷入困境，也不必重新运行构建来查看遗漏的内容。

为什么不用现有的输出压缩工具？

已有一些压缩 Shell 输出的工具（RTK、token-saver、condense）。它们有两个共同的局限：无法处理 Agent 自带的文件读取工具，而那才是更大的 token 消耗来源；而且它们是有损的：当压缩器删掉 Agent 需要的那一行时，Agent 会重新运行命令；一项独立基准测试发现，这样做的代价可能高于完全不压缩。skimread 也能保护文件读取，并确保所有内容都可检索。

它不是什么

• 不是云服务。不会发起网络请求，没有账户，也没有遥测。全部状态都保存在 ~/.skimread 中。
• 不是大模型。一切都通过确定性解析和折叠完成，因此只需几毫秒，而且无需付费。
• 不是会猜测的摘要器。它绝不会改写任何一行；只会隐藏它能够准确标识并计数的行，并告诉你如何找回它们。

数字

基于实际工具输出测量（测试样例位于 tests/fixtures，运行 python bench/bench.py 即可复现）。Token 数量为估算值（字符数 / 3.6）。

命令输出	行数	输入 token 数	输出 token 数	节省
pytest -v（1,504 个测试，2 个失败）	1546	33,876	473	99%
vitest --reporter=verbose（579 个测试，3 个失败）	653	7,751	698	91%
pytest（65 个测试，3 个失败，60 条警告）	294	3,451	496	86%
npm install（649 个包，23 条弃用警告）	41	1,048	204	81%
cargo build（37 个 crate，3 条警告）	61	559	254	55%
go test -v（1 个失败，1 次 panic）	35	301	137	54%
tsc（8 个文件中有 48 个错误）	48	1,087	628	42%
cargo test（1 个失败，包含回溯）	68	713	487	32%
cargo build（2 个错误）	39	408	411	-1%
vitest（13 个文件，3 个失败）	76	613	628	-2%

最后两行正是重点：当输出本身已经全是有效信息（短小的构建输出中有两个错误）时，skimread 会原样保留。节省来自噪声，而绝不会通过隐藏失败来实现。

文件读取	行数	完整读取（token 数）	大纲（token 数）	Agent 随后读取 60 行片段时的节省
skimread/outline.py	598	7,648	477	84%
skimread/formats.py	463	4,961	569	76%
skimread/cli.py	368	4,086	357	75%

一个 4,063 行的 Go 文件（net/http/server.go，约 36k token）会变成一份约 600 token 的结构体与方法映射，并标出行范围。skimread stats 会显示目前已为你节省的 token 数和金额。

使用方法

1. 安装（30 秒）

需要 Python 3.9 或更高版本，无需其他依赖。

pipx install skimread          # recommended: isolated, on your PATH
# or: uv tool install skimread
# or, inside any Python environment: pip install skimread
skimread --version

直接从 GitHub 安装最新开发版本：pipx install git+https://github.com/avikchakraborty060-create/The-top-innovation。

skimread 存储的所有内容都位于 ~/.skimread 下，权限仅所有者可访问，并会在 7 天或 300 次运行后清理。

2. Claude Code：一条命令

skimread setup claude            # global: ~/.claude/settings.json
skimread setup claude --project  # or per project: .claude/settings.json

重启 Claude Code。就这样。此后：

• 当 Claude 尝试在没有指定行范围的情况下 Read 一个超过 400 行（或 16 KB）的文件时，它会收到大纲以及改为读取指定范围的指示。指定范围的读取始终允许。如果 Claude 在同一会话中第二次请求读取同一个完整文件，它就会收到完整文件，因此不会陷入僵局。
• 当 Claude 运行已知会产生大量输出的命令（npm、pytest、cargo、go、tsc、docker、git diff、find 等约 100 个命令）时，该命令会被改写为通过 skimread run 运行。Claude 会看到摘要和句柄。系统还会添加权限规则 Bash(<path-to-skimread>:*)，因此不会因此多出权限提示。

这是 Claude 看到的内容，而不是一个 2,014 行的文件：

skimread: src/server.py is 2,014 lines (~20k tokens). Read only the part you need: call Read again
with offset and limit chosen from this outline. Any Read that sets offset or limit is allowed; ...
Outline: 2,014 lines, ~20k tokens (python)
      1-38  imports 12 import statements
    41-118  class Config
    44-58     def __init__(self, path: str) -> None
    61-90     def load(self) -> dict
   121-410  class Server(Base)
   123-140    def __init__(self, cfg: Config)
   142-229    def handle_request(self, req: Request) -> Response
   ...

这是 Claude 在包含 1,504 个测试的测试套件运行 pytest -v 后看到的内容：

$ pytest -v test_many.py  ·  exit 1 in 1.2s
============================= test session starts ==============================
  (1502 passing/skipped tests hidden)
test_many.py::test_some_fail[1] FAILED                                   [ 99%]
test_many.py::test_some_fail[3] FAILED                                   [100%]
=================================== FAILURES ===================================
______________________________ test_some_fail[1] _______________________________
...
E       AssertionError: role mismatch for user 1
E       assert 'dev' == 'ops'
test_many.py:10: AssertionError
=========================== short test summary info ============================
FAILED test_many.py::test_some_fail[1] - AssertionError: role mismatch for user 1
FAILED test_many.py::test_some_fail[3] - AssertionError: role mismatch for user 3
======================== 2 failed, 1502 passed in 0.98s ========================
[skimread #42: 1546 lines, ~34k tok → 473. Full/slice/search: skimread show 42 [A-B | --grep RE]]

调整：

skimread setup claude --wrap all     # route every safe Bash command through skimread
skimread setup claude --wrap off     # Read guard only, leave Bash alone
skimread setup claude --uninstall    # remove the hook and the permission rule
skimread config read_threshold_lines 600   # guard only files longer than this (default 400)
skimread config budget 4000                # digest size in characters (default 6000)
skimread setup print                       # just print the settings.json snippet to paste yourself

安全性：Bash 包装器绝不会处理会改变 shell 状态的命令（末尾带 cd、export、source）、重定向到文件的命令、在后台运行的命令、看起来需要交互的命令，以及具有破坏性或特权的命令（rm、sudo、git push、git commit、curl | sh 等）。这些命令会完全按照 Claude 编写的内容运行，并遵循常规权限规则。开头的 cd dir && … 会保留在包装器之外，以便仍能切换工作目录。

3. Codex、Cursor、Aider、Copilot 或你自己的 Agent

任何能运行 shell 命令的 Agent 都可以通过 CLI 使用 skimread。将以下内容放入 Agent 的规则文件（AGENTS.md、.cursorrules、系统提示词）；skimread setup agents 会输出一段可直接使用的代码片段：

skimread outline src/server.py           # map of the file with line ranges
skimread read src/server.py 142-229      # numbered slice
skimread run -c "npm test"               # digest + handle   (shorthand: skimread npm test)
skimread show 42                         # full stored output
skimread show 42 300-360                 # slice
skimread show 42 --grep "Error" -C 3     # search with context
skimread list                            # recent runs

支持 MCP 的 Agent 也可以将它作为服务使用。skimread mcp 是一个通过 stdio 通信的 MCP 服务，提供 run、show、outline、read、list 工具；skimread setup mcp 会输出 mcpServers 的配置块。标准输入中的任何内容也都可以处理：cmd 2>&1 | skimread pipe --cmd "cmd"。

4. 查看已节省的内容

skimread stats                 # tokens and dollars saved, all time, by format
skimread stats --price 15      # use your model's input price per million tokens
skimread stats --json

工作原理

1. 标准化。 去除 ANSI 颜色和光标控制码，将 \r 进度条解析为最终状态，并处理退格符。
2. 按格式精简。 针对 pytest、jest/vitest/mocha、cargo、go、npm/yarn/pnpm/bun、pip/uv/poetry、docker、tsc、git diff 以及文件/目录列表命令的精简器，只删除不影响决策的信息：PASSED 行、Compiling 行、弃用警告（计数后移除）、标准库堆栈帧。其他内容全部保留。对于未知工具，使用通用路径：移除进度噪声，统计完全重复的内容（line (x5)），折叠连续的近似重复行（… 847 similar lines (159-1005) …）。
3. 评分与预算。 为行评分（错误和堆栈帧分数高，摘要分数中等）。如果精简后的输出仍超出预算，则保留开头、结尾以及最高分行周围的内容；每处被删减的内容都会替换为 … [768 lines omitted (45-812) — skimread show 42 45-812] …。
4. 暂存。 在生成摘要前，将完整的标准化输出写入 ~/.skimread/out/<id>.txt，因此页脚中的句柄始终可用。
5. 提纲。 Python 使用 ast 模块（精确的签名和范围）；JS/TS、Go、Rust、Java/Kotlin/C#/Swift、C/C++、PHP、CSS 使用声明正则表达式和大括号匹配；Ruby/Elixir/Lua 使用缩进；Markdown 标题；JSON/YAML/TOML 键；CSV 结构；日志文件（时间跨度、错误行号）；Makefile、Shell 函数、SQL 语句。对于超大文件，会将成员折叠到其父级中，并附注截断，而不会假装内容完整。

已知限制

• Token 数量为估算值（字符数 / 3.6），不是分词器输出。重要的是比例，而且比例不会因此受到影响。
• 大括号语言的提纲基于正则表达式。它们用于导航，而非保证正确性；特殊的格式风格可能会导致某个符号遗漏。Grep 仍然可用。
• 对于刚刚超过阈值的文件，Read 防护会额外产生一次工具往返。默认值（400 行）的设置是为了让提纲加上一段内容仍然比整个文件便宜得多；如果你的 Agent 大多需要完整文件，可以调高阈值。
• Bash 包装器会在子进程中通过 bash -c 运行命令。Claude Code 持久化 Shell 中定义的 Shell 函数和别名对它不可见（环境变量和工作目录可见）。
• 只有 Claude Code 有钩子可以拦截 Agent 原生的 Read。其他 Agent 可通过 CLI/MCP 工具以及规则文件中的说明获得相同能力。

开发

git clone https://github.com/avikchakraborty060-create/The-top-innovation && cd The-top-innovation
pip install -e ".[dev]"
python -m pytest -q          # 68 tests, < 1 s
python bench/bench.py        # the tables above

添加一种格式：在 skimread/formats.py 中编写 reduce_<tool>()，用于删除或折叠噪声行并设置分数；在 detect() 中注册它；将真实输出样例放入 tests/fixtures；并在 tests/test_formats.py 中添加一行，说明哪些内容必须保留。添加一种语言：在 skimread/outline.py 中加入模式列表。

你能提供的最有价值的内容，是来自真实场景的样例：精简器的效果取决于它们见过哪些输出。

许可证

MIT。