skills/skills/baimiao-table-ocr/SKILL.md

name, description

name	description
baimiao-table-ocr	将表格截图、扫描图或图片中的表格转换为结构化数据。用于用户提供图片并希望提取表格、转 CSV/JSON/Markdown/XLSX、或让 agent 读取图片里的行列内容时。通过 bundled Python CLI 调用白描匿名 Web API，支持文件路径、stdin、base64/data URI 输入，默认输出终端友好的 ASCII 表格。需要网络；不适合隐私敏感或不能上传到第三方服务的图片。

白描表格 OCR

本 skill 用于把图片中的表格识别成结构化数据。它通过 bundled CLI 调用白描 Web 的匿名 image-to-excel API，上传图片并下载 OCR 后的 .xlsx，再按需要渲染为 ASCII、Markdown、CSV、JSON 或保留 XLSX。

CLI 的完整参数说明在 CLI_USAGE.md。逆向 API 细节在 references/api_reference.md。

它不负责：

• 本地离线 OCR。
• 保证敏感图片不离开本机。
• 识别非表格型自然文本。
• 修复 OCR 模型本身的识别错误。

何时优先使用

以下情况优先选择本 skill：

• 用户提供的是表格截图、账单表、价格表、清单、报表、课程表等图片。
• 用户要求“图片转 Excel”“提取图片里的表格”“OCR 表格”“转 CSV/JSON/Markdown”。
• agent 需要把图片里的表格内容转成可复制、可分析的结构化文本。
• 用户希望保留原始 Excel 文件，用 -f xlsx -o <path> 输出。

何时不使用

以下情况不要使用本 skill：

• 图片内容隐私敏感，不能上传到第三方服务。
• 用户只需要普通 OCR 文本，而不是表格结构。
• 用户已经有可读的 XLSX/CSV/HTML 表格文件，直接读取原文件更可靠。
• 当前网络不可用，或 Baimiao 匿名接口被限流且没有可用 UUID/代理。

默认调用策略

agent 使用本 skill 时，默认按以下策略构造命令：

1. 优先调用 skill 内 bundled CLI，不要假设命令已在 PATH：

   uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "<image>" [options]
   

2. 如果没有 uv，回退系统 Python。回退前确保安装依赖：

   python -m pip install -r "<skill-dir>\scripts\requirements.txt"
   python "<skill-dir>\scripts\baimiao_table_ocr.py" --image "<image>" [options]
   

3. 默认使用 -f ascii，因为它适合终端直接阅读。

4. 如果结果要被后续程序处理，优先用 -f json 或 -f csv。

5. 如果结果要贴进 Markdown 文档，使用 -f md。

6. 如果用户要求 Excel 文件，使用 -f xlsx -o <output.xlsx>；xlsx 格式必须指定 --out。

7. 如果用户已经提供 UUID，或上下文中有之前可用的 UUID，带 --uuid <uuid>；否则让 CLI 自动生成 UUID。

8. 如果用户请求使用代理，先给 HTTP 代理示例；只有明确需要 SOCKS5 时再使用 socks5://，并提示需要 PySocks。

9. 默认允许本地缓存。除非用户明确要求重新 OCR 或怀疑缓存过期，才使用 --no-cache。

推荐命令模板

# 默认：终端 ASCII 表格
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png"

# Markdown 表格，适合直接回复或写入文档
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" -f md

# JSON，适合 agent 后续解析
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" -f json

# 保存 XLSX
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" -f xlsx -o "D:\path\result.xlsx"

# 多 sheet 时只输出一个 sheet
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" -f json --sheet Table2

# 使用已有 UUID，避免反复创建匿名账号触发限流
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" --uuid "<UUID>"

# HTTP 代理优先
uv run "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" --proxy http://127.0.0.1:8080

# SOCKS5 代理，需要额外安装 PySocks
uv run --with PySocks "<skill-dir>\scripts\baimiao_table_ocr.py" --image "D:\path\table.png" --proxy socks5://127.0.0.1:7890

输入说明

--image 支持三类输入：

• 文件路径，例如 D:\path\table.png。
• stdin，用 --image -，图片二进制从标准输入传入。
• base64 或 data URI，例如 data:image/png;base64,...。

输出说明

默认输出 ASCII 表格到 stdout。多 sheet 结果会按 sheet 分段输出。

可选格式：

• ascii：终端友好，默认格式。
• md：Markdown 表格。
• csv：CSV 文本；多 sheet 时用 # SheetName 分段。
• json：对象形式，键为 sheet 名，值为二维数组。
• xlsx：保存原始 OCR 结果文件，必须指定 --out。

UUID 与限流

白描匿名流程使用客户端 UUID 登录获取 guest token。CLI 不持久化 token 或 UUID，只按以下顺序取 UUID：

1. --uuid <uuid>。
2. 环境变量 BAIMIAO_UUID。
3. 自动生成新 UUID。

同一个 UUID 可以反复登录获得新的 guest token，但 OCR 免费额度可能耗尽。创建新 UUID 可能被服务端按 IP 限流，表现为登录返回 code: 4。如果出现限流，优先复用已有 UUID；如果 UUID 额度耗尽，则需要更换 UUID 或切换可用出口 IP。

缓存策略

CLI 会按图片 MD5 缓存 OCR 下载得到的 .xlsx，缓存目录位于脚本目录下的 .baimiao_cache。每次运行会自动清理修改时间超过 7 天的 .xlsx 缓存文件。缓存命中时会跳过网络 OCR，只重新渲染请求的输出格式。

使用 --no-cache 可强制重新识别。

排查与回退

常见错误处理策略：

• 代理连接失败：检查 --proxy 地址和端口。
• SSL 握手超时：代理可能无法访问目标服务器，换 HTTP 代理或出口。
• 连接超时 / 网络不通：检查网络或代理。
• UUID 配额已用尽：更换 UUID，或等待额度恢复。
• anonymous login failed: rate limited：当前出口 IP 创建匿名账号过多，复用旧 UUID 或切换出口 IP。

如果用户不允许上传图片到第三方服务，停止使用本 skill，并说明需要本地 OCR 方案。

前置条件

• Python 3.9+。
• 推荐安装 uv，脚本包含 PEP 723 内联依赖元数据，可用 uv run 自动准备 requests 和 openpyxl。
• 网络能访问 https://web.baimiaoapp.com 和 https://baimiaopdf.oss-cn-hangzhou.aliyuncs.com。
• SOCKS5 代理需要额外安装 PySocks，例如 uv run --with PySocks ... 或 python -m pip install PySocks。