cheap-eyes

cheap-eyes

为昂贵的 Agent 配备廉价的“眼睛”。

AI Agent 的上下文很宝贵。当它读取大型日志、长文档、网页或整个代码树时，会把上下文浪费在大部分并不需要的行上。cheap-eyes 是一个 MCP 服务，会把阅读任务交给廉价模型。随后，它会根据源内容检查模型答案中的每一行，让 Agent 获得简短且可信的答案。

效果展示

这是服务返回的真实标头（经过删减），并附有一个模拟的模型答案。Agent 请求列出应用日志中 08:10 之后的所有 ERROR 行，以及后续的回溯信息：

eyes_run result: 2026-09-26_152246-extract-889090
model: alias fast -> qwen/qwen3.6-35b-a3b (used: qwen/qwen3.6-35b-a3b)
tokens in 412 / out 96; cost $0.000080; 2 ms
check (extract): refs ok 4 / bad 1 — ok 4, ok~ 0, partial 0, not-in-input 0
  L9 [bad] text differs from the source line
--- untrusted model output ---
L3| 2026-09-20 08:14:09.031 ERROR [sync] upload failed: timeout after 30 s
L4| 2026-09-20 08:14:09.032 Traceback (most recent call last):
L6| TimeoutError: timed out
L8| 2026-09-20 08:15:31.550 ERROR [sync] upload failed: HTTP 503 from api.example.com
L9| 2026-09-20 08:16:00.000 ERROR [sync] retry 2/3 failed
--- end ---

模型引用了五行。在真实日志中，第 9 行写的是 INFO [sync] retry 2/3 ok，因此模型捏造了一条错误信息。检查程序将每条引用与源内容逐行比对，并将 L9 标记为 bad。Agent 在依赖该答案之前，就能看到这个问题。

为什么答案值得信赖

• 模型没有工具。 它无法打开文件、浏览网页或调用任何内容。它只能看到 cheap-eyes 选择发送的编号行。
• 任何内容离开你的设备前，机密信息都会被遮蔽。 文件和任务中的密码、令牌和密钥等会变成 [token]、[key] 等。
• 仅使用零数据保留政策的提供商。 这些提供商不会存储你的提示词。cheap-eyes 只与 OpenRouter 通信，并在每次调用时要求采用该政策。
• 每条引用和行号都会与已发送的行进行机械校验。 错误值和未引用的声明都会被标记。
• 校验无法证明的内容： 答案是否完整或相关。它能证明引用的内容确实存在，但无法证明没有遗漏。

要求

运行环境	Node.js ≥ 22.17，或 Docker，或 Home Assistant OS / Supervised
架构（Home Assistant 应用）	amd64、aarch64
网络	出站 HTTPS 连接至 openrouter.ai，以及任务中指定的网页；对于 claude.ai，还需要一个可从互联网访问的 TLS 反向代理
磁盘	安装后约 56 MB，其中 33 MB 为 pdfjs-dist 及其 CMaps 和字体；可选的 @napi-rs/canvas 会额外占用约 37 MB 的原生二进制文件，而文本提取不需要它（npm install --omit=optional 可跳过安装）
OpenRouter	一个设有独立每日限额的 API 密钥

安装

Claude Code / Claude Desktop（npx）

1. 在 ~/.config/cheap-eyes/config.json 中编写配置文件；Windows 上使用 %APPDATA%\cheap-eyes\config.json（参见配置）。

2. 检查配置（不联网，也不会打印机密信息）：npx -y cheap-eyes check-config

3. 将服务添加到 Claude Code：

   claude mcp add --env CHEAP_EYES_OPENROUTER_KEY=<OPENROUTER_KEY> --transport stdio cheap-eyes -- npx -y cheap-eyes
   

4. 试用：“使用 eyes_run 列出 /home/me/notes/**/*.md 中的所有 TODO，并注明所在行。”

Claude Desktop、.mcp.json 和全局安装： 安装说明。

Home Assistant 应用

Home Assistant 在 2026.2 版本中将 add-ons 更名为 apps；较早版本中的相同菜单仍称为 Add-ons 和 Add-on Store。

1. 添加此仓库：

   

   或手动添加：选择 Settings → Apps → App Store → ⋮ → Repositories → + Add，粘贴 https://github.com/st412m/cheap-eyes，然后选择 Add。

2. 在商店中找到 cheap-eyes，然后选择 Install。

3. 在 Configuration 中设置 openrouter_key、至少 32 个字符的 http_token（运行 openssl rand -hex 32 可生成一个），以及 read_roots。

4. 选择 Start。该应用会在端口 3400 上提供 MCP 服务。

选项和连接器 URL： 应用文档。

Docker / HTTP

cheap-eyes serve --http 会使用令牌，通过 Streamable HTTP 运行同一个服务；仓库中的 Dockerfile 和 compose.example.yaml 将其封装起来。请参阅 安装说明。

配置

一个 JSON 配置文件。首先需要设置以下字段：

字段	含义
read_roots	服务可以读取的文件夹（或单个文件）。必须是绝对路径。
models	别名：例如，fast 这样的别名是模型 ID 列表的短名称。
defaults	调用未指定别名时，各模式使用的别名。
daily_budget_usd	每个 UTC 日的本地支出上限，默认为 1.0。

{
  "read_roots": ["/home/me/notes"],
  "models": { "fast": { "ids": ["qwen/qwen3.6-35b-a3b"], "params": { "reasoning": { "effort": "none" } } } },
  "defaults": { "extract": "fast", "draft": "fast", "edits": "fast" }
}

密钥应放在环境变量 CHEAP_EYES_OPENROUTER_KEY 中，切勿放入文件。所有字段、环境变量和文件位置请参阅： 配置。

连接到 claude.ai

运行 HTTP 服务（或 Home Assistant 应用），并通过负责终止 TLS 的反向代理发布。端点为：

https://<your-host>/private_<your-token>/mcp

在 claude.ai → Settings → Connectors → Add custom connector 中添加。路径错误会直接返回 404；按设计，此处不提供 OAuth。请参阅 安全。

使用方法

像平常一样与 Agent 对话。遇到合适的任务时，它会调用 cheap-eyes。根据你想要的结果选择模式：

• extract：需要精确行内容时使用，例如日志中的错误、某个配置值或某内容的所有提及。虚构的行会被标记。
• draft：需要笔记或摘要时使用。每一行都必须标注其来源行。来源行中不存在的值以及没有引用的行都会被标记。
• edits：需要提出修复方案时使用。你会得到 JSON 编辑内容，其旧文本会与文件进行核对。cheap-eyes 绝不会应用这些编辑。
• schema：需要填充字段时使用：输入 JSON 架构，输出相同的 JSON，并为每个值提供行引用和逐字引文。冲突值会被报告，不会被裁定。
• grep：已知确切模式时使用：返回匹配窗口，不调用模型，费用为 $0。

文件可以是文本、HTML、PDF（带文本层）、Word（DOCX、DOC）、RTF、PowerPoint（PPTX、PPT）、OpenDocument 文本文档和演示文稿（ODT、ODP）、EPUB、FB2、邮件（EML、MSG，包含附件），也可以是由服务自行获取的 http(s) URL。 电子表格和扫描件会被拒绝，并说明原因。引用会标明行所在的页面、幻灯片、章节或附件，例如：L40 (slide 3)、L12 (attachment: offer.pdf, p.2) （格式）。

你可能会输入的提示词（文件必须位于 read_roots 范围内）：

• "使用 eyes_run 提取 /var/log/app/app.log 中从今天 08:00 起的所有 ERROR，并附上回溯信息。"
• "让 cheap-eyes 为 /home/me/notes/deploy.md 起草摘要：版本、端口、备份时间。"
• "使用 eyes_run 的 edits 模式，修复 /home/me/notes/*.md 中失效的链接。"
• "对 /home/me/docs/tender.pdf 使用 eyes_run 的 schema 模式，提取客户、最高价格、截止日期，以及包含数量的项目列表。"

各项检查能发现和无法发现的内容： 检查。

何时使用 cheap-eyes，何时使用 grep

cheap-eyes 适合按含义阅读大量文本：日志、档案、长文档、网页、“关于 X 的所有内容”、时间线。对于精确查找——某个键、哪些区块包含 X、按某个字段列出内容、表格中的某个值——以及小于约 30 KB 的文件，grep、范围读取或代码更便宜，也更可靠。这就是为什么它完全不读取电子表格。

在 2026-09-30 进行的一项基准测试中，使用了独立的真实结果：

• 一个 887 KB 的日志档案，任务为“关于电力的所有内容”：召回率 96 %、精确率 100 %、费用 $0.08；Agent 上下文约占 12k 个令牌，而通读全文约需 227k 个令牌。
• 一项关于 Home Assistant 自动化的结构化任务（“谁会发送到 Telegram”）：精确率 41 %，但检查结果显示为绿色勾号。检查会发现编造的行，但不会发现选错的行。

可放入 CLAUDE.md 或 Claude 设置中的代码片段：

Reading by meaning over large text (logs, archives, long documents, web pages, "everything about X") → cheap-eyes eyes_run (extract/draft; fields → schema). Exact values, structure, small files (< ~30 KB) → grep / ranged read (no model: eyes_run mode grep). Verify any value from cheap-eyes against the source (eyes_result source) before relying on it.

要在自己的文档上比较模型，请运行 cheap-eyes bench。

工具

• eyes_run — 执行任务并返回简短、经过检查的摘要。
• eyes_result — 读取已存储的结果：页面、grep、检查报告、提供给模型的源文本；取消正在运行的任务。
• eyes_stats — 查看今日及累计支出、密钥状态；也可按需查看模型表格。

输入和输出：工具。

模型和费用

代码中没有固定指定模型。你可以在配置中为模型指定别名（fast、long 等），切换模型时只需编辑配置并重启。每个别名都会按优先级列出模型 ID；如果某个模型无法使用，就会尝试下一个。示例中的 ID 在 2026-09-26 时有效，之后可能会过时。要选择新模型：

cheap-eyes models --candidates

这会列出价格低廉的零数据保留模型，并显示每个模型在你自己的任务中通过各别名检查的情况。如果你的 OpenRouter 账户的 Guardrails 不允许使用某个模型，cheap-eyes 会跳过它，并标记为 blocked by account。如果希望使用该模型，请前往 openrouter.ai → Guardrails 将其设为允许。

使用低价模型时，每个任务的费用不到一美分。真正的上限是你的 OpenRouter 密钥每日限额。此外，daily_budget_usd（默认每天 $1）会在调用即将超出限额前阻止调用。更多信息： 模型和支出。

限制

• 检查只能证明引用真实存在，不能证明答案完整。 模型漏掉的相关行不会被标记。
• 不支持 OCR。 遇到扫描版 PDF 时会拒绝处理并说明原因；提取过程中会丢失版式和图片。
• 不支持电子表格。 Excel 和 OpenDocument 电子表格会被拒绝：关于表格的问题属于精确查找，grep 或代码可以回答，而模型以文本形式读取表格时容易出错。
• 大小限制。 超过 2 MB 的文本文件（或从文档中提取的文本）会被拒绝，不会截断；超过 50 MB 的文档和超过 10 MB 的 URL 也会被拒绝；过滤后任务大小上限为 5 MB，文件数上限为 200。
• draft 不执行归纳步骤。 有多个区块时，每个区块的笔记都会显示在各自的标题下。
• 此钩子只涵盖 Claude Code 的 Read 工具。 不会拦截 Shell 命令。

故障排除

• OpenRouter 返回 403“Access denied by security policy”。 OpenRouter 会拒绝某些地区的请求；请通过代理路由调用。
• 模型被标记为 blocked by account。 前往 openrouter.ai → Guardrails 将其设为允许，或在别名中填写其他 ID。
• 服务无法启动，并提示某个别名。 defaults 中的值未在 models 中定义。
• 更新后客户端仍显示旧工具。 刷新连接器的工具列表并开始新的聊天。

更多信息：故障排除。

安全

• 模型不会获得任何工具；它返回的所有内容都会被视为不可信输出。
• 只会读取 read_roots 内的文件，并且会先解析符号链接；始终拒绝读取 .env*、密钥、secrets.yaml、数据库和 .git。
• 任何内容离开设备前，密钥都会被屏蔽；模型调用只会发送至 openrouter.ai，且必须启用零数据保留。
• 作业中的 URL 由服务端获取；会拒绝私有和本地地址，也会防范 DNS 重绑定。
• 除非你选择导出，否则服务不会在自身状态文件夹之外写入任何内容。
• 在 HTTP 模式下，令牌相当于密码。长度至少需要 32 个字符，且绝不会记录在日志中；请在前面配置 TLS。超过 1 MiB 的请求正文会被拒绝。

更多信息：安全。

链接

• 文档 — 安装、 配置、 工具、 检查、 模型与支出、 结果、 安全、 钩子、 格式、 基准测试、 故障排查、 内部机制
• Home Assistant 应用
• 更新日志

先前成果

两者均采用 MIT 许可证；cheap-eyes 是从头编写的（参见 NOTICE）。

• BardyLaw/claude-worker-delegation — 服务端按路径读取文件、提供简短预览、使用情况日志、每日预算和 PreToolUse 钩子。cheap-eyes 补上了它缺少的功能：realpath 路径保护、拒绝而非静默截断、屏蔽、行号和输出检查。
• aashahin/claude-opencode-delegate — 异步任务注册表、紧凑的状态标头。

许可证

MIT — 作者：st412m。