简体中文 · English

带上她的眼睛 · her-eyes

给纯文本 LLM 装上视觉 —— 一个单一可执行文件的 MCP 工具，让 Claude Code / Codex / Cursor 里的纯文本模型 通过一次工具调用，把图片交给视觉模型，拿回结构化的关键信息。

纯文本模型 ── tool_use{read_image, image_path, fields, context} ──> her-eyes.exe
    ▲                                                               │
    │            读取图片 → 缩放 → base64 → 调用视觉模型              │
    └──── 结构化 JSON（summary / fields[] / raw_text）<───────────────┘

---

快速开始

1. 构建

需要 Go 1.22+：

go build -o her-eyes.exe .

产物是单一静态二进制，无运行时依赖；交叉编译到 Linux/macOS 见"构建"章节。

2. 生成配置文件

用命令生成带注释的模板：

her-eyes init            # 在当前目录生成 her-eyes.yaml
her-eyes init --home     # 或写入用户主目录 ~/her-eyes.yaml

3. 填写 API Key

编辑 her-eyes.yaml，选择一种后端并填入 key：

# OpenAI 或任何 OpenAI 兼容接口（Qwen / GLM / 豆包 / Ollama）
provider: openai
openai:
  api_key: "sk-xxx"

# 或者用 Claude
# provider: anthropic
# anthropic:
#   api_key: "sk-ant-xxx"

4. 接入 agent

将 "D:\her-eyes.exe" 替换为编译后二进制可执行文件实际所在路径

Claude Code

# --scope user：让 MCP 在任意目录的项目里都可用
# （默认 local 作用域只在注册时所在目录生效，其它目录不会加载）
claude mcp add her-eyes --scope user -- "D:\her-eyes.exe" mcp

配置文件不在默认位置时，可在 args 里带 --config：

claude mcp add her-eyes --scope user -- "D:\her-eyes.exe" mcp --config D:\path\to\her-eyes.yaml

作用域说明：local（默认，仅注册时所在目录）→ user（所有项目）→ project（写入仓库 .mcp.json，随版本控制共享，同项目成员可用）。 验证：claude mcp list 查看连接状态；claude mcp get her-eyes 查看作用域。

Codex (OpenAI) — 编辑 ~/.codex/config.toml：

[mcp_servers.her-eyes]
command = "D:\\Projects\\giveLLMeyes\\her-eyes.exe"
args = ["mcp"]

Cursor — 设置 → MCP → 添加 stdio server：command 填 D:\her-eyes.exe，args 填 mcp。

Claude Desktop — 编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "her-eyes": {
      "command": "D:\\her-eyes.exe",
      "args": ["mcp"]
    }
  }
}

5. 使用

模型会自动调用 read_image 工具。字段没找全时，结果会标注缺失项，模型会针对缺失项细化提问后再次调用。

---

演示

仓库 docs/ 下附带两组演示素材，可直接用 her-eyes describe 复现。

发票识别

原图	识图演示

小猫识别

原图	识图演示

---

用法详解

命令行 CLI

her-eyes init [--home]          生成配置模板 her-eyes.yaml
her-eyes mcp [--config 路径]    以 MCP stdio server 方式运行（供 agent 连接）
her-eyes describe <图片> [选项]  命令行直接提取图片关键信息
her-eyes version / providers / help

describe 选项：

选项	说明
--config 路径	指定配置文件
--fields "金额,日期"	需要提取的具体字段，逗号分隔
--context "发票"	图片类型/任务背景
--ask "问题"	可选的开放问题（解释/总结类需求）
--provider / --model / --base-url / --api-key	临时覆盖配置
--json	只输出原始 JSON

图片支持三种来源：本地路径、http(s):// URL、base64:... 前缀。

read_image 工具

参数	必填	说明
image_path	✅	本地绝对路径 / http(s) URL / base64: 数据
fields	✅	需要提取的具体字段清单，如 ["金额","日期","收款方"]
context		图片类型与任务背景，如"这是报错截图""这是UI设计稿"
question		可选的开放问题
max_tokens		视觉模型回复上限，默认 1024

返回结构（structuredContent + 文本）：

{
  "summary": "对图片及需求的中文总结",
  "fields": [
    { "name": "金额", "value": "1,234.56", "found": true, "evidence": "票据金额栏" },
    { "name": "收款方", "value": "", "found": false, "evidence": "" }
  ],
  "raw_text": "图片中出现的主要文字",
  "provider": "openai",
  "model": "gpt-5.6-luna",
  "parsed": true
}

字段未找全时，返回文本会额外附加覆盖率反馈，例如：

（字段覆盖 1/2，缺失: 收款方。如仍需要这些信息，请针对缺失项再次调用 read_image 并细化 question/context。）

配置

配置放在 YAML 文件里，默认搜索顺序：

1. --config 指定的路径
2. 当前目录的 her-eyes.yaml（或 her-eyes.yml）
3. 可执行文件所在目录的 her-eyes.yaml（MCP server 从任意目录拉起也能找到，配置与 exe 放一起即可）
4. 用户主目录的 her-eyes.yaml

完整模板（her-eyes init 生成，即格式唯一权威说明）：

# 带上她的眼睛 (her-eyes) 配置文件
provider: openai          # openai | anthropic

openai:
  api_key: ""             # OpenAI 兼容接口的 API Key（本地 Ollama 可留空）
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o-mini"

anthropic:
  api_key: ""             # Anthropic API Key
  base_url: "https://api.anthropic.com"
  model: "claude-sonnet-5"

vision:
  max_image_dim: 1568     # 图片最长边缩放上限(px)；0 用默认 1568，设极大值关闭缩放
  max_tokens: 1024        # 视觉模型回复 token 上限
  timeout_seconds: 120    # 请求超时(秒)

工作原理

MCP 协议

手写实现了最小而完整的 MCP stdio server（JSON-RPC 2.0 逐行传输）：

• initialize → 协议版本、capabilities.tools、serverInfo（名称"带上她的眼睛"）
• tools/list → read_image 工具定义（含 JSON Schema、必填项与注解）
• tools/call → 执行提取，返回 content.text + structuredContent（类型化 JSON）
• ping → {}；未知方法 → -32601

所有日志走 stderr，协议流只有 stdout，互不污染。

结构化输出的双通道保证

• OpenAI 兼容：response_format=json_object 约束 JSON 输出；个别后端不认该字段时自动回退重试。
• Anthropic：用强制工具调用（tool_choice）固定返回 {summary, fields, raw_text}，比提示词约束可靠得多。

设计取舍

• 单一二进制：Go 编译，无运行时依赖，可交叉编译到任意平台。
• 零环境变量：全部配置走 YAML 文件。
• 字段化提取：用必填 fields 强制模型具体化提问，配合覆盖率反馈形成"提取 → 发现缺失 → 细化重试"的闭环。
• 一体两面：CLI（describe）与 MCP 复用同一内核，MCP 环境下可用 CLI 先行调试。

---

构建

需要 Go 1.22+：

go build -o her-eyes.exe .

交叉编译：

GOOS=linux  GOARCH=amd64 go build -o her-eyes-linux .
GOOS=darwin GOARCH=amd64 go build -o her-eyes-mac .

局限

• 安全提示：read_image 按模型传入的路径读取本地文件，请在可信的 agent 环境中使用。

许可证

MIT