# read-image-skill

**Repository Path**: feng-chenhao/read-image

## Basic Information

- **Project Name**: read-image-skill
- **Description**: 一个读取图片的skill
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# read-image

一个基于 [Agnes AI](https://agnes-ai.com) 视觉模型（`agnes-2.0-flash`）的图片识别 Skill。当你在 Claude Code、Cursor、ZCode 等 AI 编码工具中配置了不具备原生识图能力的模型（如 DeepSeek、GLM-5.2、LongCat-2.0 等）时，本 Skill 可以代为识别图片内容，将文字描述回传给下游模型，让任何纯文本模型都能"看懂"图片。

## 核心能力

- 将图片自动识别为文字描述，支持 PNG、JPG、GIF、BMP、WebP、SVG、TIFF 等常见格式。
- 无需当前 LLM 原生支持图像输入，只需模型能接收文本即可。
- 图片内容经 Agnes AI 服务端处理，当前模型只收到简短文字描述，显著降低 token 消耗。
- 可在命令行独立调用，也可作为 Claude Code / Cursor / ZCode 等工具的 Skill 使用。

## 典型使用场景

> 在 AI 编码工具中使用不能识图的模型时，通过调用 Agnes AI 来识别图片，从而继续完成后续任务。

例如：
- 用户上传 UI 截图并要求生成对应代码；
- 用户发送报错截图并要求分析错误原因；
- 用户发送设计稿并要求实现页面布局；
- 需要将图片内容传递给任何只支持文本输入的模型。

## 项目结构

```
read-image/
├── SKILL.md              # Skill 说明（供 Claude Code / ZCode 等加载）
├── README.md             # 项目介绍（本文件）
├── LICENSE               # 开源协议
├── .gitignore            # 忽略本地敏感配置
├── config.json           # 本地 Agnes AI API Key（不上传，由你自行创建）
├── config.example.json   # 配置示例，供复制后修改
└── scripts/
    └── agnes_vision.js   # 图片识别脚本
```

## 快速开始

### 1. 获取 Agnes AI API Key

访问 [Agnes AI](https://apihub.agnes-ai.com) 注册并获取 API Key。

### 2. 配置 API Key

将 `config.example.json` 复制为 `config.json`：

```bash
cp config.example.json config.json
```

然后编辑 `config.json`，填入你的 Agnes AI API Key：

```json
{
  "agnes_api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "llm_provider": {
    "name": "Agnes AI",
    "model": "agnes-2.0-flash",
    "base_url": "https://apihub.agnes-ai.com/v1",
    "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

> ⚠️ **注意**：`config.json` 已加入 `.gitignore`，不会进入 Git 仓库，请勿手动提交。

### 3. 命令行调用

```bash
# 基本用法
node "scripts/agnes_vision.js" --image "/path/to/screenshot.png"

# 带自定义提问
node "scripts/agnes_vision.js" --image "/path/to/screenshot.png" --prompt "图中有什么文字？"

# Windows 路径示例
node "scripts/agnes_vision.js" --image "C:\Users\user\Desktop\screenshot.png"

# Git Bash / MSYS2 路径示例
node "scripts/agnes_vision.js" --image "/c/Users/user/Desktop/screenshot.png"
```

### 4. 安装 Skill

#### Claude Code

```bash
# 安装到用户级 skill 目录（推荐）
cp -r read-image ~/.agents/skills/read-image
```

Claude Code 会自动检测并加载。当用户消息中包含图片时，会自动触发 read-image skill。

#### Cursor

将 skill 目录放置到项目或用户的 `.cursor/skills/` 目录下：

```bash
# 项目级
mkdir -p .cursor/skills
cp -r read-image .cursor/skills/read-image

# 或用户级
cp -r read-image ~/.cursor/skills/read-image
```

#### ZCode

```bash
# 安装到用户级 skill 目录
cp -r read-image ~/.zcode/skills/read-image
```

> 安装后路径类似：`C:\Users\<用户名>\.zcode\skills\read-image`

## 各平台使用方式

### Claude Code ✅ 推荐

1. 安装 Skill（见上方）
2. 在对话中**直接粘贴或拖拽图片**
3. Skill 自动触发，将图片转为文字描述后交给 Claude 处理

**工作流程：**
```
用户发送图片附件（粘贴/拖拽）
    ↓
Claude Code 检测到图片
    ↓
自动触发 read-image skill
    ↓
执行 agnes_vision.js → 调用 Agnes AI
    ↓
Agnes AI 返回文字描述（200-1000 tokens）
    ↓
文字描述 + 用户提示词 → 交给 Claude 处理
```

### Cursor ✅ 推荐

1. 安装 Skill（见上方）
2. 在对话中**直接粘贴或拖拽图片**
3. Cursor 会加载 SKILL.md 中的流程，自动完成图片识别

### ZCode ⚠️ 需注意

ZCode 对不同模型的多模态支持处理不同，需要根据模型选择使用方式：

#### 方式一：图片附件（适用于支持多模态的模型）

如果你的模型支持图片输入（如 kimi-for-coding），可直接粘贴/拖拽图片：

```
[粘贴截图]
这张图里是什么？
```

**如需启用 modalitiy 配置**（某些模型需要），编辑 `~/.zcode/v2/config.json`：

```json
"你的模型ID": {
  "modalities": {
    "input": ["text", "image"],
    "output": ["text"]
  }
}
```

> 修改后**必须重启 ZCode** 才能生效。

#### 方式二：文件路径（适用于不支持多模态的模型）

如果你的模型不支持图片输入（如 LongCat-2.0、DeepSeek 等），ZCode 会在发送前自动剥离图片。**此时请直接提供图片路径：**

```
C:\Users\冯晨昊\Desktop\screenshot.png
这张图里是什么？
```

Skill 会根据路径读取本地文件，通过 Agnes AI 识别后返回文字描述。

**为什么需要文件路径？**
- LongCat-2.0 等模型不支持多模态输入
- ZCode 检测到模型不支持 `image`，会在请求前剥离图片数据
- 模型收到的只有 `.attachment` 占位符，skill 无法获取图片
- 文件路径方式绕过了 ZCode 的图片传输，由 skill 直接读取本地文件

**工作流程：**
```
用户在消息中提供图片路径
    ↓
read-image skill 被触发（检测到消息中包含图片路径）
    ↓
执行 agnes_vision.js --image "<路径>"
    ↓
脚本读取本地文件 → 调用 Agnes AI
    ↓
Agnes AI 返回文字描述
    ↓
文字描述 + 用户提示词 → 发送给下游模型
```

## 工作原理

### 通用流程（图片附件方式）

```
用户发送图片附件
    ↓
宿主工具（Claude Code / Cursor / ZCode）检测到图片
    ↓
自动触发 read-image skill
    ↓
执行 agnes_vision.js → 调用 Agnes AI（agnes-2.0-flash）
    ↓
Agnes AI 返回文字描述（200-1000 tokens）
    ↓
图片描述 + 用户原始提示词 → 发送给下游模型
```

### ZCode 文件路径流程

```
用户在消息中粘贴图片路径
    ↓
read-image skill 被触发
    ↓
执行 agnes_vision.js --image "<图片绝对路径>"
    ↓
脚本读取本地文件 → 转为 base64 → 调用 Agnes AI
    ↓
文字描述返回给模型
```

**关键点：** 图片永远不会以 base64 或 image_url 格式出现在下游模型的消息中，所有图片处理都在 `agnes_vision.js` 内部通过 HTTPS 直接发送给 Agnes AI 服务器完成。

## 安全提示

- `config.json` 包含你的 API Key，**不要**分享给他人，也**不要**提交到公开仓库。
- Agnes AI 服务端在 HTTPS 连接中直接接收图片的 base64 编码，脚本不会把图片明文保存到磁盘或暴露给当前模型。
- 当前模型只能看到 Agnes AI 返回的简短文字描述（约 200–1000 tokens），不会直接接收原始图片数据。

## 支持的图片格式

| 格式 | MIME 类型 | 说明 |
|------|-----------|------|
| PNG | `image/png` | 推荐，无损格式 |
| JPG/JPEG | `image/jpeg` | 常见照片格式 |
| GIF | `image/gif` | 动图（仅首帧） |
| BMP | `image/bmp` | 位图 |
| WebP | `image/webp` | 现代网络图片格式 |
| SVG | `image/svg+xml` | 矢量图 |
| TIFF | `image/tiff` | 专业图像格式 |

## 常见错误

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `找不到 config.json` | 未创建配置文件 | 复制 `config.example.json` 为 `config.json` 并填入 API Key |
| `401 Unauthorized` | API Key 无效 | 检查 `config.json` 中的 `agnes_api_key` 是否正确 |
| `图片文件不存在` | 图片路径错误 | 使用图片的绝对路径，检查文件是否存在 |
| `429 Rate Limit` | 请求频率过高 | 稍等片刻后重试 |
| `500/503 Server Error` | Agnes AI 服务异常 | 稍后重试 |

## 平台故障排查

### Claude Code

#### Skill 没有被自动触发

1. 确认 `read-image` 目录在 `~/.agents/skills/read-image`
2. 确认 `config.json` 已正确配置
3. 确认图片以附件形式发送（不是文件路径）

### ZCode

#### 问题：发送图片后模型说"请提供图片文件"或看不到图片

**原因：** 当前模型（如 LongCat-2.0）不支持多模态输入。ZCode 在发送前剥离了图片，模型只收到 `.attachment` 占位符。

**解决方案：** 使用**文件路径方式**：
```
C:\Users\冯晨昊\Desktop\screenshot.png
这张图里是什么？
```

#### 问题：发送图片后报错 `unknown variant image_url`

**原因：** 模型配置了 `"image"` 模态但模型本身不支持多模态。

**解决方案：**
- 使用文件路径方式
- 或切换到支持多模态的模型（如 kimi-for-coding）

#### 问题：图片路径正确但 skill 没有触发

1. 确认消息中包含图片的**绝对路径**（以盘符开头如 `C:\`）
2. 确认 `config.json` 中 `agnes_api_key` 不为空
3. 确认 `read-image` 目录在 `~/.zcode/skills/` 下
4. 在消息中加入中文提示词帮助识别意图

### 通用问题

#### `agnes_vision.js` 脚本报错

1. 确保已安装 Node.js（v14+）
2. 检查 `config.json` 是否在 skill 根目录下
3. 检查图片路径是否正确
4. Windows Git Bash 中使用正斜杠：`/c/Users/...`

## 使用示例

### 示例 1：识别 UI 截图并生成代码

**用户输入：**
```
[粘贴截图] 或 C:\Users\user\desktop\ui.png
根据这个设计稿，写出对应的 React 组件代码
```

### 示例 2：分析报错截图

**用户输入：**
```
[粘贴报错截图]
这个报错是什么原因？怎么解决？
```

### 示例 3：识别图片中的文字

**用户输入：**
```
C:\Users\user\desktop\document.png
把图中的文字提取出来
```

## 开源协议

本项目采用 [MIT License](LICENSE) 开源。

## 贡献与反馈

欢迎通过 Issue 或 Pull Request 提交建议。如果你在使用过程中遇到问题，请优先检查：
1. `config.json` 是否正确配置
2. API Key 是否有效
3. 图片路径是否为绝对路径且文件存在
4. Claude Code / Cursor 用户：直接发送图片附件即可
5. ZCode 用户：如模型不支持多模态，请使用文件路径方式