# Xiaoyi Image Understanding Win

> 使用小艺图像理解API进行图像内容识别和描述，获取图像的详细文本描述。当用户需要分析图片内容、识别图像中的物体、场景理解、提取图像信息、图像问答、OCR文字识别、图表分析等任务时使用此技能。

- Skill: `ahang1598/xiaoyi-image-understanding-win` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add ahang1598/xiaoyi-image-understanding-win`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/xiaoyi-image-understanding-win/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ahang1598 (https://skillmd.com/u/ahang1598)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/ahang1598/xiaoyi-image-understanding-win

---


# 小艺图像理解

传入图片（本地路径或公网 URL），返回图像的详细文本描述。最多 10 张。

> **桌面形态（默认）**：云端接口调用（图像理解 / OSMS 图片上传）经主进程
> skill API 代理（`np://claw-skill` 命名管道）转发，业务鉴权由主进程自动注入，
> **本 skill 零配置、零凭证**。仅要求环境变量 `CLAW_SKILL_TOKEN`（主进程已自动注入）。

## 核心功能

- **图片描述**：详细描述图片中的场景、人物、活动
- **OCR 文字识别**：识别图中文字，保持原始排版，支持手写、印刷、表格
- **物体识别**：识别并列举图中物体，标注位置
- **图片问答**：针对图片内容提问，获取精准回答
- **图表分析**：提取图表数据点、趋势和关键信息

## 用法

```bash
# 本地单图
python scripts/image_understanding.py --image "photo.jpg" --prompt "详细描述图片中的场景"

# URL 图片
python scripts/image_understanding.py --image "https://example.com/image.jpg" --prompt "提取图中所有文字"

# 多图（最多 10 张）
python scripts/image_understanding.py --image img1.jpg img2.jpg img3.jpg --prompt "对比这些图片的差异"
```

执行命令时，将外层 shell/exec 超时设为至少 900 秒，确保脚本自己的超时和错误处理能够完成；不要使用外层默认短超时提前杀掉进程。

## 参数

| 参数            | 必填  | 说明                           |
| ------------- | --- | ---------------------------- |
| --image / -i  | ✅   | 本地路径或 http/https URL，最多 10 张 |
| --prompt / -p | ✅   | 提示词                          |

## 输出格式

```json
{"images": ["photo.jpg"], "caption": "图片描述文本..."}
```

多图时 `images` 为数组，`caption` 为整体描述。失败时脚本返回非零退出码，并在最后一行输出：

```json
{"images": ["photo.jpg"], "error": {"code": "request_timeout", "message": "...", "retryable": true}}
```

## 超时与重试

- 图片上传读超时为 180 秒。
- 图像理解等待响应头最多 120 秒，流连续 180 秒无数据视为空闲超时，单次云侧理解总时长最多 360 秒。
- 收到 SSE `[DONE]` 或明确完成事件后，脚本会立即结束，不继续等待服务端关闭连接。
- 只有最后一行 JSON 中 `error.retryable` 为 `true` 时才允许自动重试；等待 10 秒后，使用完全相同的图片和 prompt 最多重试一次。
- 第二次失败后立即停止并向用户说明错误。禁止继续循环调用。
- 如果命令被外层 shell/exec 超时直接终止，没有拿到结构化错误，不要自动重试，以免前一个云侧任务仍在执行而产生重复请求。

## Prompt 要点

- **说清楚要什么**：`提取图中所有文字` > `图中讲了什么`
- **限定范围**：`忽略背景，只识别表格中的数字`、`仅描述人物动作`
- **多图对比**：`对比图1和图2的差异`

## 故障排除

| 问题        | 解决方案                                                                                        |
| --------- | ------------------------------------------------------------------------------------------- |
| 鉴权失败（401） | 请确认已登录小艺Work——业务凭据由主进程统一管理，skill 侧无需也无法配置                                                   |
| 配置缺失      | 桌面管道形态零配置；旧沙箱形态才需检查 `~/.openclaw/.xiaoyienv` 是否包含 PERSONAL_API_KEY、PERSONAL_UID、SERVICE_URL |
| 文件不存在     | 确认图片路径正确                                                                                    |
| 上传失败      | 检查连接，确认图片未损坏（phase2 为预签名 URL 直传）                                                            |
| 识别不准确     | 使用更具体的 prompt                                                                               |
| 请求超时      | 图片理解最长等待 360 秒；仅在结构化错误标记可重试时自动重试一次                                                        |
| 图片过大      | 超过 2048×2048 自动等比例缩放                                                                        |

