内容
# 微缩胶片
将代理的上下文存储为图像。以高达 2.8 倍的 token 减少读取。
一张 1092x1092 的 PNG 页面可容纳约 13,500 个字符的文章，字体大小为 10px，单间距，并需 1521 个图像 token 供模型读取。相同的字符需约 4,300 个文本 token。微缩胶片将文本渲染为密集的页面，每页通过本地 OCR 认证，确保没有任何有损数据进入您的上下文，并为代理提供搜索和召回功能。Claude Opus 4.8 读取这些页面时的字符准确率为 99.55%，与真实 API 对比。
命名源自原始的光学上下文压缩技术：图书馆将一个世纪的报纸存储为微小图像，并使用镜头读取。
## 为什么
长上下文代理大部分时间和预算都用于重新阅读参考资料：文档、日志、转录、研究转储。图像 token 是每个前沿 API 公开的唯一折扣输入通道。最近的研究（DeepSeek-OCR、Glyph、Text or Pixels、AgentOCR）表明，对于渲染的文章，压缩比 2 倍到 4 倍是可行的；完整的文献综述，包括失败模式，在 [docs/LITERATURE.md](docs/LITERATURE.md) 中。
微缩胶片是该成果的可部署版本，具有研究论文所需的安全防护措施：认证门。每页渲染后由 Tesseract 读取并与真实值比较。通过认证的页面（文章、日志）以约 2.8 倍的压缩率作为图像召回。未通过认证的页面（代码、哈希、密集表格）自动保留为精确文本。您不会在不知道的情况下用 token 换取正确性。
## 实测结果
真实的 Claude API、文章语料库、字符级准确率 vs 测量的 token 比率（完整网格：[bench-results/ROUNDTRIP.md](bench-results/ROUNDTRIP.md)）：
| 读取器 | 字体 | 准确率 | token 比率 |
| --- | --- | --- | --- |
| Opus 4.8 | 10px | 99.55% | 2.83x |
| Opus 4.8 | 9px | 99.74% | 2.84x |
| Sonnet 5 | 12px | 99.18% | 1.89x |
本地流水线：7.4M 字符分段，耗时 0.9s；页面渲染速度为 2.9/s；BM25 搜索在 2,184 个分段上达到 33ms p50。
## 安装
```bash
pip install microfiche # 或：pip install "microfiche[mcp]"
sudo apt-get install tesseract-ocr # 或：brew install tesseract
```
## 从命令行使用
```bash
microfiche init --reader opus # 10px 页面，2% OCR 门限
microfiche ingest --root .microfiche docs/*.md notes.txt
microfiche flush --root .microfiche # 渲染 + 认证页面
microfiche search --root .microfiche "你记得的事情"
microfiche stats --root .microfiche # 压缩记分板
```
召回是任何可以读取图像的工具：将代理指向 `.microfiche/pages/<page_id>.png`，它将支付 1521 个 token，而不是约 4,300 个。
## 从 Claude 代码中使用
复制技能，让代理管理自己的存储：
```bash
mkdir -p ~/.claude/skills && cp -r skills/microfiche ~/.claude/skills/
```
该技能教授打包、搜索和读取 PNG 工作流程，包括规则（从不通过图像召回未经认证的页面，引用精确的字符串来自文本）。
## 从任何 MCP 客户端（Claude Code、Codex、...）使用
```bash
pip install "microfiche[mcp]"
claude mcp add microfiche -- microfiche-mcp --root .microfiche
```
四个工具：`pack`（文件输入，认证页面输出）、`search`、`recall`（返回页面 PNG 作为图像内容，或认证失败时的精确文本）、`stats`。Codex 和其他 MCP 客户端：通过 `MICROFICHE_ROOT` 设置的标准输入/输出运行 `microfiche-mcp`。
## 工作原理
```
文本文件
-> 分段器 分割为规范分段（真实来源，永不删除）
-> 渲染器 将分段打包为 1092x1092 超采样单色页面
-> 认证器 Tesseract 读取每个页面；CER <= 门限或页面被拒绝，其分段保留为文本
-> 索引 分段标题、关键词、摘要的 BM25
-> 召回 认证页面 PNG（1521 token）或精确分段文本
```
读取器配置文件根据真实 API 进行校准：`--reader opus` 以 10px 渲染，2% 门限（Tesseract 是一个保守的代理：Opus 读取 Tesseract 读取的内容，加上余量）。`--reader sonnet` 为 12px，1% 门限。页面成本由补丁公式固定：ceil(w/28) x ceil(h/28)；1092x1092 是每个 Claude 模型层都无需降级的最大正方形。
## 研究施加的规则
文献和我们自己的测量结果得出的三个发现，已被应用：
1. 文章压缩；熵不压缩。随机字符串、哈希和代码在每个测试模型上都失败图像召回。OCR 门限自动捕获此类，因为它们也失败本地 OCR。
2. 读取后推理。模型从渲染页面中很好地检索信息，但跨压缩图像墙推理很差（VTCBench）。将页面召回到对话中，从转录开始工作。
3. 密度是悬崖，不是斜坡。准确率与字体大小是急剧的相变，因此保持在测量的稳定带中，并认证每个页面。
## 开发
```bash
python3 -m venv .venv && .venv/bin/pip install -e ".[mcp]"
.venv/bin/python -m unittest discover -s microfiche/tests -t . # 95 个测试
./run_e2e.sh # 研究流水线端到端
./run_bench.sh # 完整的本地基准测试套件
```
原始研究框架（扫描、保真度网格、成本模拟、真实 API 往返测试）位于存储库根目录和 `bench-results/` 中；研究轨迹在 `RESEARCH.md`、`REPORT.md` 和 `SCALE.md` 中。
## 许可证
MIT
