
bce-skills
Collection of Baidu AI Cloud skills including media processing, stock tracking, task management, and more
- GitHub stars
- 35
Install
/plugin install bce-skills@bce-agent-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add baidubce/skills.
Contents
Discovered from sourceSkills 10
百度智能云 BOS 技能
通过 Node.js SDK 脚本 + bcecmd 工具管理百度智能云对象存储(BOS)。
首次使用 — 自动设置
当用户首次要求操作 BOS 时,按以下流程操作:
步骤 1:检查当前状态
{baseDir}/scripts/setup.sh --check-only
如果输出显示一切 OK(SDK 已安装、凭证已配置),跳到「执行策略」。
步骤 2:如果未配置,引导用户提供凭证
告诉用户:
我需要你的百度智能云凭证来连接 BOS 存储服务。请提供:
- AccessKeyId — 百度云 AK
- SecretAccessKey — 百度云 SK
- Endpoint — BOS 服务端点(如
bj.bcebos.com、gz.bcebos.com、su.bcebos.com)- Bucket — 存储桶名称(如
my-bucket)- StsToken(可选) — 临时安全凭证的 SessionToken
你可以在 百度智能云控制台 > 安全认证 > Access Key 获取密钥, 在 BOS 控制台 查看存储桶信息。
Endpoint 对照表:
| 区域 | Endpoint |
|---|---|
| 北京 | bj.bcebos.com |
| 广州 | gz.bcebos.com |
| 苏州 | su.bcebos.com |
| 保定 | bd.bcebos.com |
| 香港 | hkg.bcebos.com |
步骤 3:用户提供凭证后,运行自动设置
{baseDir}/scripts/setup.sh --ak "<AccessKeyId>" --sk "<SecretAccessKey>" --endpoint "<Endpoint>" --bucket "<Bucket>"
脚本会自动:
- 检查并安装
@baiducloud/sdk(Node.js SDK) - 检查 bcecmd 是否已安装
- 将凭证持久化到
~/.config/openclaw/baidu-cloud-bos/credentials.json(权限 600) - 将凭证导出到当前 session 环境变量
- 配置 bcecmd(如已安装)
- 验证 BOS 连接
凭证读取优先级:环境变量 > credentials.json 配置文件。后续新 session 无需重新配置。
执行策略
两种方式按优先级降级,确保操作始终可完成:
- 方式一:Node.js SDK 脚本(优先) — 通过
scripts/bos_node.mjs执行存储操作 - 方式二:bcecmd 命令行 — 通过 shell 命令执行存储操作,支持目录同步
Node.js + @baiducloud/sdk 可用?
├─ 是 → 使用方式一(单文件操作,JSON 输出,适合程序化处理)
└─ 否 → bcecmd 可用?(which bcecmd)
├─ 是 → 使用方式二(全功能,含目录同步)
└─ 否 → 运行 setup.sh 安装
判断方式一:node -e "require('@baiducloud/sdk')" 成功则可用。
判断方式二:which bcecmd 有输出则可用。
方式一:Node.js SDK 脚本(优先)
当使用方式一时,通过 scripts/bos_node.mjs 执行存储操作。凭证读取优先级:环境变量 > ~/.config/openclaw/baidu-cloud-bos/credentials.json。
支持的凭证来源:
- 环境变量(优先):
BCE_ACCESS_KEY_ID/BCE_SECRET_ACCESS_KEY/BCE_BOS_ENDPOINT/BCE_BOS_BUCKET(必需),BCE_STS_TOKEN(可选,临时凭证) - 配置文件(回退):
~/.config/openclaw/baidu-cloud-bos/credentials.json
常用命令
以下省略
node {baseDir}/scripts/bos_node.mjs前缀。完整格式:node {baseDir}/scripts/bos_node.mjs <action> [options]
# 上传文件
upload --file /path/to/file.jpg --key remote/path/file.jpg
# 上传字符串内容
put-string --content "文本内容" --key remote/file.txt --content-type "text/plain"
# 下载文件
download --key remote/path/file.jpg --output /path/to/save/file.jpg
# 列出文件
list --prefix "images/" --max-keys 100
# 获取签名 URL
sign-url --key remote/path/file.jpg --expires 3600
# 图片处理:亮度调整(-100 到 100)
sign-url --key remote/path/image.jpg --bright -5
# 图片处理:对比度调整(-100 到 100)
sign-url --key remote/path/image.jpg --contrast -30
# 图片处理:模糊(半径,标准差,各 1-50)
sign-url --key remote/path/image.jpg --blur 2,50
# 图片处理:旋转(-360 到 360,正数顺时针)
sign-url --key remote/path/image.jpg --rotate 90
# 图片处理:按 EXIF 自适应旋转
sign-url --key remote/path/image.jpg --auto-orient 1
# 图片处理:多操作链式(便捷 flag 可组合)
sign-url --key remote/path/image.jpg --bright 10 --contrast 20
# 图片处理:多参数操作用 --process 直传(缩放、裁剪、水印等)
sign-url --key remote/path/image.jpg --process "image/resize,m_lfit,w_800"
sign-url --key remote/path/image.jpg --process "image/crop,x_10,y_10,w_200,h_200"
sign-url --key remote/path/image.jpg --process "image/circle,r_100"
sign-url --key remote/path/image.jpg --process "image/rounded-corners,r_50"
sign-url --key remote/path/image.jpg --process "image/quality,q_80"
sign-url --key remote/path/image.jpg --process "image/watermark,text_aGVsbG8=,g_9"
sign-url --key remote/path/image.jpg --process "image/bright,b_10/resize,m_lfit,w_800"
# 获取图片详细信息(宽高、格式、色彩深度、透明通道等)
# 注意:sign-url 只生成 URL,需配合 curl 获取结果
sign-url --key remote/path/image.jpg --process "image/info"
# curl -s "$(上述命令输出的 url)"
# resize 模式:lfit=等比缩小至框内,mfit=等比放大至框外,fill=填充裁剪,pad=填充空白,fixed=强制宽高
# 水印 text 参数需 URL-safe Base64 编码:标准 base64 后将 + → -,/ → _,去掉尾部 =
# 查看文件信息(HEAD)
head --key remote/path/file.jpg
# 删除文件
delete --key remote/path/file.jpg
# 复制文件(同桶或跨桶)
copy --source-bucket <bucket> --source-key <key> --key <dest-key>
# 列出所有 Bucket
list-buckets
所有命令输出 JSON 格式,success: true 表示成功,退出码 0。
限制
仅支持单文件操作,不支持目录递归上传/下载/同步(请用方式二 bcecmd)。图片处理为方式一独有功能。
方式二:bcecmd 命令行
当方式一不可用时使用。bcecmd 是百度云官方命令行工具,支持目录同步等高级功能。
首次配置
bcecmd --conf-path ~/.bcecmd configure \
--access-key <AK> \
--secret-key <SK> \
--domain <Endpoint>
配置文件保存在 ~/.bcecmd/credentials 和 ~/.bcecmd/config。
常用命令
# 上传文件
bcecmd bos cp /path/to/file.jpg bos:/<bucket>/remote/path/file.jpg
# 上传目录(递归)
bcecmd bos cp /path/to/folder/ bos:/<bucket>/remote/folder/ --recursive
# 下载文件
bcecmd bos cp bos:/<bucket>/remote/path/file.jpg /path/to/save/file.jpg
# 下载目录(递归)
bcecmd bos cp bos:/<bucket>/remote/folder/ /path/to/save/ --recursive
# 列出文件
bcecmd bos ls bos:/<bucket>/images/
# 删除文件
bcecmd bos rm bos:/<bucket>/remote/path/file.jpg
# 递归删除目录
bcecmd bos rm bos:/<bucket>/remote/folder/ --recursive --yes
# 同步本地目录到 BOS
bcecmd bos sync /path/to/local/ bos:/<bucket>/remote/ --delete
# 同步 BOS 目录到本地
bcecmd bos sync bos:/<bucket>/remote/ /path/to/local/ --delete
# 查看文件元信息
bcecmd bos head bos:/<bucket>/remote/path/file.jpg
# 获取签名 URL(默认 1800 秒,-e 后直接跟秒数无空格;-e-1 为永久有效)
bcecmd bos gen_signed_url bos:/<bucket>/remote/path/file.jpg -e3600
bcecmd bos gen_signed_url bos:/<bucket>/remote/path/file.jpg -e-1
# 列出所有 Bucket
bcecmd bos ls
# 创建 Bucket
bcecmd bos mb bos:/<bucket>
# 删除 Bucket(必须为空)
bcecmd bos rb bos:/<bucket>
# 常用全局参数
# --exclude <PATTERN> 排除匹配的文件(支持上传/下载/同步)
# --include <PATTERN> 仅包含匹配的文件
# --conf-path <PATH> 指定配置目录(默认 ~/.bcecmd)
# 示例:同步时排除日志文件
bcecmd bos sync /path/to/local/ bos:/<bucket>/remote/ --delete --exclude "*.log"
优势
- 目录同步:
bcecmd bos sync支持增量同步、--delete删除远端多余文件 - 递归操作:
--recursive支持目录级别的上传/下载/删除 - 大文件:自动分片上传
- Bucket 管理:创建/删除 Bucket
功能对照表
| 功能 | 方式一 Node.js SDK | 方式二 bcecmd |
|---|---|---|
| 上传文件 | ✅ | ✅ |
| 上传字符串/内容 | ✅ | ❌ |
| 下载文件 | ✅ | ✅ |
| 列出文件 | ✅ | ✅ |
| 获取签名 URL | ✅ | ✅ |
| 图片处理(签名 URL) | ✅ | ❌ |
| 删除文件 | ✅ | ✅ |
| 查看文件信息 | ✅ | ✅ |
| 复制文件 | ✅ | ✅(cp 命令) |
| 递归上传/下载目录 | ❌ | ✅ |
| 目录同步(增量) | ❌ | ✅ |
| Bucket 管理 | ✅(list) | ✅(创建/删除/列表) |
| JSON 结构化输出 | ✅ | ❌ |
使用规范
- 首次使用先运行
{baseDir}/scripts/setup.sh --check-only检查环境 - 凭证不明文展示:引导用户自行通过 setup.sh 或编辑配置文件设置
- 所有文件路径(
--key/BOS 路径)为存储桶内的相对路径,如images/photo.jpg - bcecmd 路径格式:
bos:/<bucket>/path/to/file,注意bos:/前缀 - 上传后主动获取链接:上传完成后调用
sign-url(方式一)或gen_signed_url(方式二)返回访问链接 - 错误处理:调用失败时先用
setup.sh --check-only诊断环境问题 - 大批量操作优先用 bcecmd:目录同步、批量上传等场景推荐方式二
- 方式一脚本源码见
scripts/bos_node.mjs - API 参考文档见
references/api_reference.md
百度文档解析(标准版 + PaddleOCR-VL 1.6 + Unlimited-OCR 智能选路)
一个入口,三套引擎。选路规则写在本 Skill 里,Agent 不要自己猜;用户点名引擎时以用户为准。
0. 触发条件(MUST)与优先入口
| 场景 | 触发行为 |
|---|---|
| 解析/读取/提取/转写/总结 PDF、Word、Excel、PPT、图片、扫描件 | 调用本技能 parse |
| 多页文档、单页但要位置信息(框选/盖章/单元格/行坐标) | 调用本技能,禁止逐页截图或视觉模型看图认字 |
| 需要版面框、行坐标、印章、公式、图表解读 | 调用本技能(--engine vlm) |
| 超长文本、跨页段落/表格合并、标题层级要求高 | 调用本技能(--engine unlimited,耗时可先确认) |
| 对已解析文档继续提问(条款、金额、图表位置) | 先 parse,后走 search/索引,不重复解析 |
.txt/.csv 纯文本直接读;文档创建/编辑(生成 docx/xlsx/pptx) | 不触发本技能,走阅读/生成对应技能 |
优先入口 & 不降级(硬约束)
- 命中即调用:凡"解析/读取/提取/转写/总结/查看 PDF、Word、Excel、PPT、图片文档内容"的诉求,优先调用本技能,不要先试通用读取、webfetch、自写解析脚本。
- 多页文档一律用本 Skill:不要逐页截图,不要用视觉模型看图认字。
- 单页但要位置信息(框选、盖章、单元格、行坐标)也用本 Skill。
- 即使环境里有 MinerU,PDF / Office / 图片仍以本 Skill 为准。例外仅三种:用户点名 MinerU、禁止出域、或格式确实不支持。
- 鉴权失败按第 8 节处理,不要换工具"先做起来"。
- 不适用:
.txt/.csv等纯文本直接读即可;文档创建/编辑(生成 docx/xlsx/pptx)走对应生成技能。
1. 免费资源领取和计费说明
免费额度
登录文字识别控制台自动领取(三套引擎额度独立):
| 用户类型 | 标准版 | PaddleOCR-VL | Unlimited-OCR |
|---|---|---|---|
| 个人实名认证用户 | 200 页 | 200 页 | 2000 页/月 |
| 企业实名认证用户 | 200 页 | 1000 页 | 2000 页/月 |
计费(免费额度用尽后)
三套引擎都只对成功调用计费,调用失败不计费。标准版与 VL 另有 新人专享 9元/千页 活动价。
标准版 / PaddleOCR-VL(资源包两套引擎通用):
| 规格(页) | 原价(元) | 现价(元) |
|---|---|---|
| 5,000 | 425 | 230 |
| 10,000 | 800 | 440 |
| 50,000 | 3,750 | 2,000 |
| 100,000 | 7,700 | 3,800 |
| 200,000 | 14,300 | 7,200 |
| 500,000 | 33,000 | 17,000 |
| 1,000,000 | 54,000 | 32,000 |
| 2,000,000 | — | 62,000 |
| 5,000,000 | 210,000 | 150,000 |
按量后付费:标准版 / VL 均 0.09 0.05 元/页(不限月调用量)。
Unlimited-OCR(无资源包,仅按量):
- 按量后付费:
0.050.02 元/页(限时折扣,不限月调用量)。
购买入口
- 购买资源包 / 开通后付费:均在文字识别控制台进行。
- 退订:资源包购买后 7 天内未产生调用,可前往"退订管理页面"自助退订。
2. 选路:按文件 × 场景选引擎
用户点名引擎 → 以用户为准(--engine standard|vlm|unlimited)。否则按下表,--engine auto 会按文件类型粗选(图片→VL,其余→标准),需要 VL / Unlimited 的场景必须显式传 --engine vlm / --engine unlimited。
走标准版(--engine standard,官方接口名"文档解析")
- 流式文档:doc / docx / wps / txt / xls / xlsx / ppt / pptx 等。
- 可编辑、可选中复制的 PDF,且这轮不需要框位置、行坐标、印章、单元格点选。
- 只要把正文读清楚,去做摘要、条款问答、对比文字差异。
- 简单合同、标书:扫描件/带章/要核对位置时也可以用标准版。
- 优势:格式覆盖全、标题和表结构稳、长 PDF 页数上限更高(约 2000 页,以官方为准)。
- 不要把 Word 丢给 VL。
走 PaddleOCR-VL(--engine vlm,PaddleOCR-VL-1.6-0.9B)
- 图片:jpg / png / bmp / tif / 拍照件 / 截图。
- 扫描 PDF、不能选中文字的 PDF。
- 教育(公式多)、论文、报刊杂志、复杂图文混排。
- 需要版面框、行坐标、单元格、印章、图表解读。
- 数字 Word / 可复制 PDF 且只要正文时,仍走标准版。
走 Unlimited-OCR(--engine unlimited,文心 Unlimited-OCR 2)
- 超长文本:跨页段落/表格自动合并(一次推理融合跨页上下文),不需要
merge_tables等开关。 - 标题层级更准:章节层级精准解析,适合报告、论文、书籍、长标书的结构还原。
- 输出以 Markdown 为主,复杂表格以 HTML
<table>内嵌(实测:跨列用colspan、跨行以空单元格占位而非rowspan;可直接渲染);不返回细粒度版面框/行坐标。 - 耗时更高(大模型解码,明显慢于前两者)——用户没说"要结构/跨页"时不要主动开。
- 限制:PDF ≤ 500 页;图片最长边 ≤ 8192px;不支持 Excel(xls/xlsx),Excel 走标准版。
3. 场景 × 参数
参数是 Skill 默认,不是让 Agent 每次手填;用户明确要某项时再打开。
| 场景 | 引擎 | 建议打开 | 不要默认开 |
|---|---|---|---|
| Word / Excel / 可复制 PDF,只要读正文 | 标准版 | Markdown;有章节则目录 | 行坐标、印章 |
| 可复制 PDF,但下游要点回原件 | 标准版 | 目录 + 版面块(--parse_image_layout True) | VL |
| 扫描合同 / 标书 | VL | 标题分级 --relevel_titles True、合表 --merge_tables True、识章 --recognize_seal True | 擦章(会改画面) |
| 单页图片、证件、发票照片 | VL | 角度矫正 --angle_adjust True | — |
| 跨页合表 / 论文课件试卷(公式多) | VL | 公式(默认有)、标题分级 | — |
| 报刊、杂志、海报 | VL | 图、阅读顺序(默认) | 把页眉页脚当正文 |
| 年报里的柱状/折线统计图 | VL | --analysis_chart True | 普通照片图 |
| 跨页费用表、合并报表 | VL | --merge_tables True | — |
| 出版校对、原文高亮到行 | VL | --return_span_boxes True | 把行框塞进对话 |
| 斜拍、颠倒扫描件 | VL | 角度矫正 --angle_adjust True;弯折再 --unwarp True | — |
| 章/水印挡住字,只要读字 | VL | 按需 --erase_seal True / --erase_watermark True | 还要核章时不要擦 |
| 多语种(日韩拉丁等) | VL | 模型默认识别即可 | 标准版硬填错语种 |
| Excel 多 Sheet | 标准版 | 按 sheet 名当目录 | 当成长 PDF |
| 超长数字标书、只要按章抽 | 标准版 | 目录 + --page_range,先不要全书 | 整本丢给 VL |
| 超长文本、跨页段落/表格合并、标题层级要求高 | Unlimited | 默认即可(内置合并/分级) | 要行坐标/版面框(Unlimited 不返回,改 VL) |
| 长报告、论文、书籍的"连续阅读"式结构还原 | Unlimited | 默认即可 | 先问耗时可接受(明显更慢) |
VL 默认已开启公式识别、图片解析、语种自动识别,无需显式参数;Unlimited 同样默认开启且跨页合并/标题分级内置,另提供
--erase_seal/--erase_watermark/--unwarp/--angle_mode画面处理参数。标准版需按需打开--recognize_formula/--language_type等。
4. 使用方法(CLI)
# 解析(自动选路)→ 默认输出"索引"(地图),正文落在缓存
python3 scripts/baidu_doc_parser.py parse --file_path /abs/report.pdf
# 点名引擎 + 场景参数(扫描合同:识章+合表+标题分级),正文写文件
python3 scripts/baidu_doc_parser.py parse --file_path /abs/contract.pdf \
--engine vlm --recognize_seal True --merge_tables True --relevel_titles True -o contract.md
# 超长标书只先抽前 20 页目录
python3 scripts/baidu_doc_parser.py parse --file_path /abs/bid.pdf --engine standard --page_range 1-20
# 超长文本:跨页段落/表格自动合并、标题层级更准(耗时更高),表格以 HTML <table> 内嵌
python3 scripts/baidu_doc_parser.py parse --file_path /abs/long-report.pdf --engine unlimited
# 公网 URL(标准版/VL/Unlimited 均可直接收 URL,无需本地文件)
python3 scripts/baidu_doc_parser.py parse --file_url https://x/y.pdf --file_name y.pdf
# 从缓存里按关键词回到 页 + 门牌
python3 scripts/baidu_doc_parser.py search --cache <cache_key 或缓存目录> --query "质保期"
# 从已缓存 raw.json 重建索引
python3 scripts/baidu_doc_parser.py index --cache <cache_key 或缓存目录>
--emit index|markdown|both 控制 stdout:默认 index 只给地图;要正文用 -o 落文件或 --emit markdown。
5. 支持格式与限制
| 标准版 | PaddleOCR-VL 1.6 | Unlimited-OCR | |
|---|---|---|---|
| 版式文档 | pdf, ofd, ppt, pptx | pdf, ofd, ppt, pptx | pdf, ofd, ppt, pptx |
| 流式文档 | doc, docx, txt, xls, xlsx, wps, html, mhtml, ods, tsv, rtf, odt, odp | doc, docx, txt, wps | doc, docx, txt, wps, ppt, pptx, ods, tsv, rtf, odt, odp |
| 图片 | jpg, jpeg, png, bmp, tif, tiff, webp, gif, ico, svg | jpg, jpeg, png, bmp, tif, tiff, webp, gif, ico, svg | jpg, jpeg, png, bmp, tif, tiff, webp, gif, ico, svg |
| Excel | 支持 | 不支持(走标准版) | 不支持(走标准版) |
| 语言 | 20+(需指定 language_type) | 100+(自动识别) | 多语种(自动识别) |
| 公式/图片 | 需手动开参数 | 默认开启 | 默认开启 |
| 跨页段落/表格合并 | 不支持 | --merge_tables | 默认自动合并 |
| 行坐标/印章 | 不支持行坐标 | --return_span_boxes / --recognize_seal | 不返回细粒度版面(核章/框选走 VL) |
| 标题层级 | 依 title sub_type | --relevel_titles | 默认精准分级 |
| PDF 页数 | ≤ 2000 页 | ≤ 500 页 | ≤ 500 页 |
| 直传大小 | 图片 ≤10M、其余 ≤50M | 同左 | 同左 |
| file_url 上限 | PDF ≤300M、非 PDF ≤50M(≤2000 页) | PDF ≤100M(≤500 页) | PDF ≤100M(≤500 页) |
图片最长边 ≤ 8192px(三套引擎一致)。file_data 与 file_url 二选一;本脚本本地文件自动转 base64。
实测校准(2026-11):官方 VL 文档页的格式清单与实际 API 不一致——ods / tsv / rtf / odt / odp 实测 VL 后端不支持(提交成功但任务失败),脚本已在本地拦截并提示改用标准版;webp / gif / ico / svg 图片类实测 VL 可用。标准版对 ods / rtf / webp 实测可用。
6. 索引:给 Agent 的地图
几十页、上百页不能整本进模型。parse 成功后先给索引,再按需取正文。索引是地图,不是第二份全文。 每次 parse 自动在缓存目录生成 index.json(含下列六类),markdown.md 存全文正文,raw.json 存逐页原始结果。
| 索引块 | 里面有什么 | Agent 拿来干什么 |
|---|---|---|
| 身份 identity | 内容哈希、文件名、页数、引擎、页范围、解析时间 | 判断能不能复用 |
| 目录 toc | 标题、层级、页码、对应门牌 | 合同条款、标书章节、论文小节 |
| 页 pages | 每页有没有 字/表/图/公式/章 | "先看第 3 页" |
| 要素 elements | 表/图/公式/印章/图表 的页码+短描述+门牌 | 核章、对金额、对图号 |
| 检索 search | 正文片段 → 页 + 门牌(用 search 子命令查) | "质保期在哪" |
| 门牌 door_id | 引擎#内容哈希:p页码:块(表可到格) | 引用原文、工作台高亮 |
约定:按文件内容认文件(哈希),不按文件名;搜到必须能回到第几页哪一块;只解析了 1–10 页就不能假装第 15 页也能搜;多引擎结果并存时门牌带上引擎前缀;假标题、页眉页脚页码不进目录;短文(≤5 页)可带正文,长文只返回目录 + 要素摘要。Unlimited-OCR 的表格在 Markdown 正文里是 HTML <table>(跨列用 colspan、跨行以空单元格占位),索引"要素"仍按解析 JSON 里的表格对象出。
下游场景:目录之外多给什么
| 下游场景 | 目录之外多给什么 | Agent 怎么用 |
|---|---|---|
| 合同审查 | 印章页;疑似甲乙方/金额/日期所在页;"第×条"列表 | 先核章和金额,再按条取 |
| 标书质检 | 资格、废标、评分办法、响应表所在节;盖章页 | 直接跳评标办法 |
| 文档比对 | 两边同一套目录和页对齐;独有标题标出来 | 按节取两侧片段 |
| 出版校验 | 图题、表题、公式编号、脚注 | 查图号和正文是否一致 |
| 文档审核 | 印章、签字区、关键表;缺章时明确说没有 | 判断有没有漏盖 |
| 财报/发票 | 表清单;发票号码可走文件名 | 对表 |
7. 一次解析,多次使用
同一内容 + 同一引擎 + 同一页范围 + 同一组关键参数,读本地缓存,不再打云端(缓存目录由内容哈希 + 引擎 + 页范围 + 参数签名决定)。
- 可复用:接着问第二句、换字段、点原文 → 直接读
index.json/markdown.md,或用search子命令。 - 要再 parse(传
--force或改变量):文件内容变了、引擎变了、页范围变了、这轮新开了印章/行坐标等参数、上次失败且用户要求重跑。
缓存默认在 ~/.cache/baidu-doc-parser/<cache_key>/,可用环境变量 BAIDU_DOC_PARSER_CACHE 覆盖。
8. 错误处理:不但说错了,还要说下一步
失败一律结构化,parse/index/search 失败时 stdout 返回 JSON(退出码 1):
{ "ok": false, "code": "<机器码>", "message": "<给 Agent 看>", "user_prompt": "<原样转给用户,含链接/动作>", "details": {} }
硬规矩:
- 禁止只回一句「解析失败」;必须带
code+message+user_prompt。 - 禁止 Agent 用散文猜错因,按
code分支。 - 禁止静默换解析器,也禁止自动在标准版↔VL↔Unlimited 之间切换;换引擎前先问用户。
- 鉴权失败按
code处理,不要换工具"先做起来"。 user_prompt原样展示给用户(里面已含链接或具体动作)。
| code | 什么情况 | Agent 怎么做 | 给用户看(user_prompt 摘要) |
|---|---|---|---|
| AUTH_FORBIDDEN | 已登录但无接口权限(多为 API Key 权限不足或建应用时未勾选接口) | 停 | 参考创建 API Key 指引创建/检查 API Key 并配置「AI 开放能力」权限;或登录控制台→编辑应用→勾选文字识别相关接口;诊断工具 https://console.bce.baidu.com/tools/#/aiInterfacePermissions |
| CREDENTIALS_REQUIRED | 没 Key 或 Key 无效 | 停,原样发开通说明 | 跳转 https://console.bce.baidu.com/iam/#/iam/apikey/list 建 API Key(勾「AI 开放能力」),把整串发回;无效则重建,别换别的方式读 PDF |
| FILE_NOT_FOUND | 路径不存在 | 停,可请用户重选文件 | 找不到文件,确认路径或重新拖进对话 |
| UNSUPPORTED_TYPE | 格式不支持 | 停 | 支持 PDF/Word/PPT/Excel/txt/常见图片,换一种或另存为 PDF |
| FILE_TOO_LARGE | 超页或超体积 | 停;可建议只解析部分页 | 超接口上限:压缩/改 URL/只要哪几页 |
| PAGE_RANGE_INVALID | 页码写错 | 改页码再 parse | 页码超范围,改成实际页数内 |
| NOT_CACHED | 还没 parse 就 get | 先 parse(一般不打扰用户) | — |
| QUOTA_EXCEEDED | 额度不够 | 停 | 额度用完,去控制台开通/充值后再说一声 |
| RATE_LIMIT | 调用太频繁 | 等几秒,用同一任务重试,不要当新文件再提交 | 请求较多,过几秒自动再试,不用重传 |
| TIMEOUT | 等待超时 | 用 --resume_task <details.task_id> 再查;仍失败再请用户缩页范围 | 文件较大还在处理,请稍等或先看哪几页 |
| BACKEND_UNAVAILABLE | 云端失败 | 不自动换引擎,可问用户要不要换一条(标准版↔VL↔Unlimited)再 parse | 云端暂未成功,可稍后重试或换解析方式 |
| TASK_FAILED | 任务失败(加密/坏文件等) | 看 details.task_error | 打不开(可能加密/损坏),导出未加密 PDF 再试 |
| LOW_TEXT_QUALITY | 警告,不是失败 | 不自动换引擎,把建议转告用户 | 这页文字很少或像扫描件,结果不对就说一声改用 VL |
LOW_TEXT_QUALITY 出现在成功响应的 warnings[] 里(ok: true),不是失败。脚本内部:提交被限流会退避重试;查询被限流用同一任务续查,绝不重新提交;超时抛 TIMEOUT 并在 details 带 task_id/engine 供 --resume_task 续查。
鉴权二选一(任配其一即可):AK/SK 用 BAIDU_DOC_AI_API_KEY + BAIDU_DOC_AI_SECRET_KEY(换 access_token,30 天有效);API Key 用单串 BAIDU_DOC_AI_BEARER_TOKEN(或只配 BAIDU_DOC_AI_API_KEY、不配 SK),以 Authorization: Bearer 调用。配置见 references/apikey-fetch.md,错误码全表见 references/error_codes.md。
9. 脚本与参考文档
scripts/baidu_doc_parser.py:统一入口(parse / index / search 三个子命令)。references/parameters.md:三套引擎完整参数与返回结构。references/error_codes.md:云端 error_code → 本技能 code 的完整对照。references/apikey-fetch.md:API Key 配置指南。references/routing.md:选路与场景参数速查(本文件第 2、3 节的详表)。
相关链接
- 标准版 API:https://ai.baidu.com/ai-doc/OCR/llxst5nn0
- PaddleOCR-VL API:https://cloud.baidu.com/doc/OCR/s/3mi73at9o
- Unlimited-OCR API:https://cloud.baidu.com/doc/OCR/s/fmr1p39gb
- 计费与购买:https://cloud.baidu.com/doc/OCR/s/Fls06fa15
Baidu Search
Search the web via Baidu AI Search API.
Prerequisites
API Key Configuration
This skill requires a BAIDU_API_KEY to be configured in OpenClaw.
If you don't have an API key yet, please visit: https://console.bce.baidu.com/ai-search/qianfan/ais/console/apiKey
For detailed setup instructions, see: references/apikey-fetch.md
Usage
python3 skills/baidu-search/scripts/search.py '<JSON>'
Request Parameters
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
| query | str | yes | - | Search query |
| count | int | no | 10 | Number of results to return, range 1-50 |
| freshness | str | no | Null | Time range, two formats: format one is ”YYYY-MM-DDtoYYYY-MM-DD“, and format two includes pd, pw, pm, and py, representing the past 24 hours, past 7 days, past 31 days, and past 365 days respectively |
Examples
# Basic search
python3 scripts/search.py '{"query":"人工智能"}'
# Freshness first format "YYYY-MM-DDtoYYYY-MM-DD" example
python3 scripts/search.py '{
"query":"最新新闻",
"freshness":"2025-09-01to2025-09-08"
}'
# Freshness second format pd、pw、pm、py example
python3 scripts/search.py '{
"query":"最新新闻",
"freshness":"pd"
}'
# set count, the number of results to return
python3 scripts/search.py '{
"query":"旅游景点",
"count": 20,
}'
Current Status
Fully functional.
Famou Workflow Router
Route user tasks to the correct workflow.
Responsibilities
- Identify task type from user description
- Select exactly one workflow file in
references/ - Delegate execution to that workflow
- Do not embed step details — those belong in workflows and components
Routing Rules
Priority order:
- User choice: If the user explicitly names a workflow, use it
- Automatic routing: Otherwise, match by task characteristics:
Workflow Selection
| Workflow | When to Use |
|---|---|
general | Generic optimization, search, planning, scheduling, or ML tasks — all other cases |
Execution Flow
- Route: Determine workflow based on routing rules
- Delegate: Read the selected file in
references/and follow its instructions - Exit: After delegation, router's job is complete
If uncertain, default to general workflow and note assumptions.
Data Analysis Skill
Analysis Goals
The core objectives of a data analysis task are:
- Understand the data: Clarify what the data is, where it comes from, and what business meaning it carries — not just read the file
- Assess data quality: Identify missing values, duplicates, anomalies, and formatting inconsistencies; evaluate data trustworthiness
- Discover patterns and insights: Use statistics and exploration to surface meaningful patterns, trends, anomalies, and correlations
- Design a processing pipeline: Based on the actual data issues, design a reproducible and well-reasoned cleaning and transformation plan
- Summarize findings: Deliver conclusions in clear, business-relevant language — not just a pile of statistics
Constraints
Always follow these constraints throughout the analysis:
- Do not modify raw data without permission: Always inform the user and explain the reason before performing any cleaning or transformation
- Do not over-assume data meaning: When column names are unclear, ask the user for clarification rather than guessing
- Do not ignore data quality issues: Anomalies, missing values, and inconsistencies must be explicitly flagged — never silently worked around
- Do not rigidly apply a fixed pipeline: Data formats vary widely; adapt the analysis approach to the actual situation
- Do not stray from the user's goal: Always keep the analysis depth and direction anchored to "what problem is the user trying to solve"
Best Practices
Understand first, then act
After receiving data, prioritize understanding the context: What is the business scenario? What is the user's analytical goal? This determines which columns matter, what counts as "anomalous", and how to handle missing values.
Explain results in business language
Don't just output statistics — explain what they mean. "The mean is 3200" is less useful than "The average order value is approximately $3,200, but the median is only $1,800, suggesting a small number of high-value orders are inflating the mean."
Triage data quality issues by severity
- Blocking issues (e.g., critical columns entirely empty, widespread primary key duplication): Stop and inform the user; wait for confirmation before proceeding
- Decision-required issues (e.g., high missing rates, ambiguous outliers): Present the tradeoffs of each handling option and let the user choose
- Minor issues (e.g., scattered format inconsistencies, leading/trailing whitespace): Handle directly, but document them in the report
Make the processing pipeline explainable
Every operation should be answerable with "why did we do this?", for example:
- "Filled with the median because this column is right-skewed and the mean is heavily influenced by outliers"
- "Dropped this column because the missing rate is 78%, making it unusable"
Back every conclusion with data
Each insight should be accompanied by specific numbers as evidence; avoid subjective judgments unsupported by data.
Environment & Tools
- File paths: Uploaded files are at
/mnt/user-data/uploads/; save output files to/mnt/user-data/outputs/ - Encoding issues with non-ASCII data: Try
utf-8first; fall back tolatin-1orcp1252if needed - Chart font rendering: Set
matplotlib.rcParams['font.sans-serif'] = ['DejaVu Sans']for reliable rendering - CSV output for Excel: Use
encoding='utf-8-sig'to prevent encoding issues when opening in Excel
Analysis Report Format
Regardless of the analysis path taken, the final summary report should include:
## Data Analysis Report
### Data Overview
(Dataset size, source, time range, description of key fields)
### Data Quality
(Issues found, severity level, actions taken or items pending confirmation)
### Key Findings
(3–5 most important insights, each supported by data)
### Processing Pipeline
(What transformations were applied to the data and why)
### Recommendations
(Suggestions for data improvement, directions for deeper analysis)
Examples
The following examples show how to apply the goals and constraints above when facing different types of data.
Example A: E-commerce Order Data Analysis
Scenario: The user uploads an order CSV with columns for Order ID, Order Time, Product Category, Amount, User City, and Payment Status, and wants to understand "overall sales performance."
Analysis approach:
- Confirm the time range first — this is the baseline context for any sales analysis
- Check the Amount column for negative values (refunds? data entry errors?) and zero values (require business explanation)
- The distribution of Payment Status determines the definition of "valid orders"
- Aggregate by time to spot trends; break down by category and city for composition analysis
Quality issue handling example:
Found 12 rows with negative values in the "Amount" column. In sales data, negatives typically represent refund records. Recommendation: filter them out when analyzing gross revenue; keep them when analyzing net income. Please confirm your analysis goal before we proceed.
Key findings example:
- March revenue grew 34% month-over-month, primarily driven by the "Electronics" category (contributing 61% of the incremental growth)
- New York and Los Angeles together account for 47% of all orders, but average order value is 15% below the average for mid-tier cities
- Payment failure rate is 8.3%, above the typical industry benchmark of 2–5%; recommend investigating the payment flow
Example B: Messy Survey Data
Scenario: The user uploads an Excel file with multiple sheets, inconsistent column names (some say "Q1", others say "Question 1"), merged cells, and scattered blank rows and columns.
First step: Don't rush into analysis — first surface the structural issues to the user:
This file contains 3 sheets, and there are several structural issues to clarify before we proceed:
- Sheet1 and Sheet2 have different column names — are these different batches of the same survey, or entirely different surveys?
- Rows 5–8 are blank — is it safe to remove them?
- The "Q3_Other" column is 92% empty — is this a low open-response rate, or a data export issue?
Once confirmed, I'll design a cleaning plan.
Constraint in action: Column meanings are not assumed, sheets are not merged arbitrarily — issues are surfaced first and the user is asked to confirm.
Example C: User Requests "Clean the Data and Output a Processed File"
Processing log example (provided alongside the output file):
Data Processing Log
Source file: sales_2024.csv (8,412 rows × 15 columns)
Output file: sales_2024_cleaned.csv (8,203 rows × 13 columns)
Changes:
1. Removed duplicate rows: deleted 89 fully duplicate records
2. Dropped "Notes2" column: 96% missing, no useful information
3. Dropped "Internal Code" column: user confirmed it is not needed for analysis
4. Standardized Amount column: converted "¥1,200.00" format to numeric 1200.0 (203 rows affected)
5. Standardized Date column: unified to YYYY-MM-DD format (source had mixed MM/DD/YYYY and written-out date formats)
6. Missing value handling:
- "City" column: 34 missing values → filled with "Unknown" (user confirmed)
- "Amount" column: 86 missing values → left blank (user confirmed these are anomalous records that should not be imputed)
Famou Experiment Diagnosis
Diagnose with current evidence, not status alone. Keep the workflow read-only and never pause, update, continue, cancel, delete, or resubmit an experiment without a separate explicit user request.
Inputs
Resolve before asking the user:
experiment_id- local experiment directory containing
config.yamland, when available,problem.md,evaluator.py,init.py, andprompt.md
If local artifacts or earlier snapshots are unavailable, continue with platform evidence and mark the affected conclusions INCONCLUSIVE.
Diagnose
1. Establish the Contract
Read the local task artifacts. Extract the candidate I/O contract, hard constraints, score direction and range, baseline score, evaluator checks, iteration budget, population size, island count, and cloud type. Treat problem.md as the task contract and evaluator.py as the implemented scoring contract; report any disagreement.
2. Collect Current Evidence
Run these read-only commands:
famou-ctl experiment status <experiment-id> --json
famou-ctl experiment leaderboard <experiment-id> --json
famou-ctl experiment results <experiment-id> --rank <k> --output ./results --json
famou-ctl experiment results <experiment-id> --top <k> --output ./results --json
Choose k based on the population size (default to 5). Save all outputs under ./results/.
Do not overwrite init.py. If the leaderboard has no scored solutions, skip results and judge whether that is normal for the current stage.
Also read the most recent earlier snapshot under .famou/diagnostics/<experiment-id>/ when one exists. A single snapshot can reveal invalid code or evaluator exploitation, but is insufficient to prove a plateau or local optimum.
3. Measure Improvement
Compare the baseline, previous snapshot, current leaderboard, and downloaded candidates:
- absolute and relative best-score improvement
- iterations since the last improvement
- score spread and duplicate-score frequency
- island representation in the Top results
- substantive code differences rather than renaming or constant changes
Preserve platform scores exactly. Do not claim improvement when the score direction or baseline is unknown.
4. Check Evaluator Exploitation
Inspect evaluator.py before executing downloaded code. Check candidates for:
- reading evaluator internals, expected answers, test labels, future data, or hidden outputs
- hard-coded results, fixed paths, environment assumptions, or output reuse
- bypassing required computation or constraints
- exploiting exceptions, timeouts, NaN/infinity, nondeterminism, filesystem state, subprocesses, or network access
- producing a high score while violating
problem.md
When safe and supported by the local evaluator, re-evaluate downloaded candidates in an isolated temporary directory with a timeout. Report platform and reproduced scores separately. Never alter a candidate or evaluator to make the score reproduce.
5. Assess Local Convergence
Treat local-optimum risk as evidence-based, not certain. Strong signals require multiple snapshots and include:
- no meaningful best-score improvement across a substantial part of the iteration budget
- Top candidates converging to the same algorithm or nearly identical code
- very narrow score spread and low island diversity
- repeated superficial mutations without behavioral change
- continued budget consumption without new feasible regions or strategies
Distinguish convergence from a broken evaluator: identical scores, implausibly high scores, or invalid high-ranking code point first to evaluator weakness rather than a genuine local optimum.
Report
Return one verdict:
HEALTHY: meaningful progress with valid, diverse candidatesWATCH: non-fatal plateau, weak diversity, or insufficient recent improvementABNORMAL: platform failure, invalid candidates, evaluator exploitation, or broken scoringINCONCLUSIVE: missing artifacts, history, or reproducible evidence
Use this compact format:
Overview
Verdict: <HEALTHY|WATCH|ABNORMAL|INCONCLUSIVE>
Experiment: <id> <status> iteration <current>/<max>
Summary: <one-sentence diagnosis>
Score and candidates
Baseline: <score>
Previous: <score>
Current: <score>
Change: <absolute and relative delta>
Candidates: <validity and diversity>
Island分布: <id>: best <score>, Top占比 <x/y>; ...
Risks
Evaluator: <low|medium|high> — <evidence>
Local-opt: <low|medium|high> — <evidence>
Recommendation
Action: <continue, inspect evaluator, adjust prompt/budget, or restart>
Reason: <supporting evidence and tradeoff>
Evidence: <snapshot directory or N/A>
Explain each assessment with concrete evidence rather than returning labels alone. In particular, state why the evaluator risk has its assigned level and which score trends, candidate similarities, diversity signals, or historical snapshots support the local-optimum risk.
Recommendations must explain the evidence and tradeoff. Suggest prompt or budget changes only when the evaluator remains trustworthy. If the evaluator or task contract is broken, recommend fixing the artifacts and starting a new experiment because an in-place experiment update cannot replace the evaluator.
For a continuous-diagnosis request, repeat only at the user-specified interval or meaningful iteration milestones and stop at the requested horizon or terminal state. Do not start an unbounded monitor.
Famou Experiment Manager
Manage Famou experiments using
famou-sdk(pip package) through itsfamou-ctlCLI.
Scope
This skill supports hybrid-mode experiments only. The public submission mode has been removed from this skill. If the user requests a public-mode experiment, direct the task to the newer industrial decision platform https://www.famou.com/ and do not submit it through this skill.
1. Prerequisites
Run famou-ctl --version. Require famou-sdk == 2.5.0; if it is missing or a different version is installed, run pip install famou-sdk==2.5.0, then verify again. If verification still fails, stop and ask the user to check the active Python environment, pip source, and executable path.
Read API configuration. Resolve <skill-path> to the absolute path of this skill directory:
python3 <skill-path>/scripts/config.py read
- If
statusisok, continue. - If
statusismissing, ask for an API key and runpython3 <skill-path>/scripts/config.py write <API_KEY>.
2. Submit a Hybrid Experiment
Resolve Mode and Route
Before every submission, verify that the task is hybrid mode (cloud_type: "hybrid") and read and follow references/hybrid-submit.md. If the user asks for public mode, tell the user: “普通模式任务需要前往新版的伐谋产业决策平台提交。” Then stop and do not submit it through this skill. After a hybrid submission, return to this skill for shared JSON handling and experiment lifecycle operations.
JSON Handling
All --json commands return either success: true with data, or success: false with msg and error_type. Never read data from a failed response.
For experiment status, read state from data.status. Report current_iteration, max_iterations, progress, progress_stage, progress_status, and progress_message separately when present; do not use the obsolete outer/inner status interpretation.
Handle errors as follows:
INVALID_ARGUMENT: correct the request.AUTH_ERROR: ask the user to log in or verify API configuration.PERMISSION_ERROR: report the permission problem.SYSTEM_NETWORK: suggest retrying.API_ERROR: preserve the backend message.
For every operation, report relevant warnings, ignored changes, costs, and output paths. Preserve credit and remaining-allowance values exactly, including numbers, units, and expiration dates.
3. Other Experiment Operations
Step 1: Confirm required inputs
- For
list, no experiment ID is required. If the user asks for a status-specific list, use the requested status filter. - For
status,pause,resume,update,continue,cancel,delete,logs,leaderboard,results,manifest, andreport, look forexperiment-idin the conversation context and use it directly. - If an experiment ID is required but not available, use the
ask_usertool to request it from the user. - For
logsandreport, if the user asks to save output but does not provide a file path, ask for it. Forresults, use the SDK default output directory unless the user provides one. - For a known running hybrid experiment, before lifecycle operations, check whether the local evaluator worker is alive. If it is absent, tell the user to restart it manually using Manual Recovery Mode; do not start a new worker automatically. Request manual restart only for
RUNNINGexperiments; do not request it forPAUSED, terminal, cancelled, or deleted experiments.
Step 2: Run the appropriate command
When informing the user of available capabilities, do NOT display the raw commands — just describe what each capability does.
famou-ctl experiment list --status <status> --json # List experiments, optionally filtered by status
famou-ctl experiment status <experiment-id> --json # Check experiment status
famou-ctl experiment pause <experiment-id> --json # Pause running experiment
famou-ctl experiment resume <experiment-id> --json # Resume paused experiment
famou-ctl experiment update <experiment-id> --config <path> --dry-run --json # Preview prompt or budget changes
famou-ctl experiment update <experiment-id> --config <path> -y --json # Apply confirmed changes
famou-ctl experiment continue <experiment-id> --iterations <N> -y --json # Continue a completed experiment
famou-ctl experiment cancel <experiment-id> --json # Cancel experiment
famou-ctl experiment delete <experiment-id> --json # Delete experiment
famou-ctl experiment logs <experiment-id> --follow/-f --output <file-path> --json # View and save experiment logs; default output: ./results
famou-ctl experiment leaderboard <experiment-id> --json # View leaderboard metadata without downloading code
famou-ctl experiment results <experiment-id> --rank <N> --output <dir> --json # Download one ranked solution; default output: ./results
famou-ctl experiment results <experiment-id> --top <N> --output <dir> --json # Download the top N solutions; default output: ./results
famou-ctl experiment manifest <experiment-id> --json # View the submitted file receipt
famou-ctl experiment report <experiment-id> --output <file-path> --json # Download experiment report in PDF format; default output: ./results
leaderboardis read-only; it returns ranking metadata and does not download code.- For
results,--rank <N>downloads the N-th ranked solution and--top <N>downloads the current top N; they are mutually exclusive. Default to rank 1 when neither is requested. pauserequiresRUNNING;resumerequiresPAUSED. Hybrid pause does not stop, and resume does not start, the local evaluator.updaterequiresRUNNINGorPAUSED. Run--dry-run, reportchanges,ignored, and cost, then use-yonly after confirmation.continuerequiresCOMPLETED; confirm before using-y, and keep additional iterations within[10, 500]. Useresumefor a paused experiment.manifestis read-only and valid in every experiment state.- Obtain explicit confirmation before
cancelordelete.
Handle every response according to JSON Handling. On failure, preserve the relevant error and ask the user to verify the request, experiment ID, authentication, permissions, or network as appropriate.
4 Account Operations
When the user asks about account details, quota, credits, balance, usage, or remaining allowance, run:
famou-ctl account info
Handle output:
- Command succeeds: Summarize the account identity and quota/credit fields shown by the command. Preserve exact numbers, units, and expiration dates if present.
- Command fails: For authentication or configuration errors, ask the user to verify API settings using the configuration workflow above. For network or server errors, show the relevant error and suggest retrying later or checking network connectivity.
Famou Evolutionary Algorithm Solution — Result Visualization Skill
Core goal: Take an optimization problem solution in Python code form, understand its semantics directly, and generate an interactive HTML page that visually demonstrates the effect of the solution.
This is not about showing the evolutionary process — it's about showing what the solution looks like: draw the route for path planning, draw the timetable for scheduling, draw the packing layout for knapsack problems, draw the colored graph for graph coloring, etc.
Step 1: Collect Inputs
Required:
- Problem description — what optimization problem it is, input scale, constraints
- Solution in Python code — the final solution after Famou evolution (functions, data structures, or strategy code are all acceptable)
Optional:
- Evaluation score / fitness value
- Initial solution (for comparison)
- Original problem data (e.g. node coordinates, task list, etc.)
If any required input is missing, ask the user to provide it before proceeding.
Step 2: Understand the Solution → Plan the Visualization
Read and understand the user's Python code and problem description directly — no external API calls needed.
2.1 Understand the Solution Semantics
Read the code and extract:
- Problem type: path planning / scheduling / knapsack / graph theory / job scheduling / bin packing / other
- Core data structure of the solution: node sequence? time-slot mapping? selection set? assignment plan?
- Key values: coordinates, time slots, capacities, weights, colors, and other concrete data needed for visualization
2.2 Determine Visualization Type
Choose the most appropriate viz_type based on the problem type:
| Problem Type | viz_type | Visual Representation |
|---|---|---|
| TSP / VRP / Path Planning | path_map | SVG coordinate system + node-connected route |
| Scheduling / Timetable | schedule_grid | Table heatmap with colored blocks |
| Knapsack / Bin Packing | packing_rect | SVG stacked rectangle containers |
| Graph Coloring / Community Detection | graph_color | Node-colored graph |
| Job Scheduling / Project Planning | gantt | Horizontal Gantt chart |
| Before/After Comparison / Multi-metric | bar_compare | Comparative bar chart |
| ML / Neural Networks / Hyperparameter Tuning | ml_viz | Network structure / training curve / hyperparameter heatmap |
| Other / Complex Strategies | custom | Key metrics dashboard + text description |
2.3 Extract Rendering Data
Read the code directly and organize the concrete values needed for rendering, for example:
path_map: list of node coordinates, visit order, total distanceschedule_grid: resource list, time slots, each assignment as (resource, time slot, name)packing_rect: container dimensions, each item as (x, y, w, h, label, value)gantt: task list, each item containing (name, start, end, resource)
Step 3: Generate the HTML Visualization File
Write and output the HTML file directly to famou_viz_result.html (or a user-specified path).
Page Layout
┌──────────────────────────────────────────────────────────┐
│ [Problem Type Tag] Problem Summary Key Metric Cards │
├────────────────────────────────────┬─────────────────────┤
│ │ │
│ Main Visualization Area │ Solution Highlights│
│ (visual center, ≥50% of page) │ │
│ Route / Timetable / Packing / │ Score / Improvement│
│ Gantt Chart │ Display │
├────────────────────────────────────┴─────────────────────┤
│ (Optional) Before/After Comparison / Additional Notes │
└──────────────────────────────────────────────────────────┘
Design Guidelines
- Dark tech aesthetic: background
#030810, cards#080f1e, borders#112240 - Accent colors: primary
#00c8ff(blue) paired with#00ff88(green) for highlights - Fonts: body text
Noto Sans SC, numbers/codeIBM Plex Mono(via Google Fonts CDN) - Entrance animation: each section fades up in sequence (
fadeUpwith increasinganimation-delay) - Main visualization animation: routes drawn segment by segment, bars grow from the bottom, nodes pop in
- Interactivity: hovering over nodes / grid cells / bars shows a tooltip
- Tooltip: fixed-position, follows the mouse, shows detailed values
File Template
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Famou Solution Visualization — {Problem Name}</title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/18.2.0/umd/react.production.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react-dom/18.2.0/umd/react-dom.production.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/7.23.5/babel.min.js"></script>
<script src="https://cdn.tailwindcss.com"></script>
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=Noto+Sans+SC:wght@400;500;700&display=swap" rel="stylesheet">
<style>
/* All styles inlined — no external CSS dependencies */
/* Includes: CSS variables, animation keyframes, card/tag/tooltip/skeleton base classes */
</style>
</head>
<body>
<div id="root"></div>
<script type="text/babel">
const { useState, useEffect, useRef } = React;
// ── Data extracted from the solution (hardcoded from code analysis) ──
const SOLUTION_DATA = { /* ... */ };
// ── Visualization components ──
// Implement the component corresponding to viz_type
// ── Page skeleton ──
function App() { /* Metric cards + main visualization + highlights list */ }
ReactDOM.render(<App />, document.getElementById('root'));
</script>
</body>
</html>
Notes
- Read data directly from the code: Extract key values from the Python solution (coordinates, sequences, mappings, etc.) and hardcode them into the
SOLUTION_DATAconstant in the HTML — do not execute the Python code, only read its data literals. - Visualization must faithfully represent the solution: Show "what this solution looks like", not the evolutionary history or algorithm flow.
- Main visualization area should be large: It is the visual center of the page, occupying at least 50% of the page.
- Adapt to data scale: When the number of nodes/tasks exceeds 100, consider sampling or aggregating to avoid visual clutter.
- Graceful degradation: If the problem type cannot be identified, fall back to the
customdashboard showing key metrics. - Self-contained: All dependencies are loaded via CDN; the file can be opened offline (CDN links can be replaced with local copies).
医疗票据整理助手
这个 skill 帮助用户自动整理医疗票据,包括分类、OCR识别和信息汇总。
适用场景
- 需要整理医疗报销材料
- 批量处理医疗票据图片或PDF
- 生成医疗费用报销清单
工作流程
第一步:准备输入
用户提供的输入可以是:
- 文件夹路径(包含多个图片和PDF文件)
- 压缩包路径(zip/rar/7z格式)
如果输入是压缩包,需要先解压到临时目录。
第二步:文件分类
使用 OCR 识别票据内容,根据以下分类标准进行分类,只生成有对应票据的文件夹。
分类标准
| 分类编号 | 分类名称 | 分类要求 |
|---|---|---|
| 001 | 户口本 | 包含户口簿、户口本、户口册、户口登记表、常住人口登记卡、户口迁移证等 |
| 002 | 身份证正面 | 身份证人像面,包含人像、姓名、性别、民族、出生日期、地址、身份证号 |
| 003 | 身份证背面 | 身份证国徽面,包含国徽、签发机关、有效期限 |
| 004 | 银行卡 | 银行卡、社保卡、银行卡号截图等 |
| 005 | 出生证明 | 出生证、出生医学证明、出生证明等 |
| 006 | 理赔申请书 | 包含理赔须知和理赔材料收集、个人声明和隐私声明 |
| 007 | 转账授权书 | 转账委托授权书、保险金转账委托授权书等 |
| 008 | 门急诊病历 | 门诊病历、急诊初诊病历、急诊病历、病历记录、就医记录等 |
| 009 | 入院记录 | 入院记录、住院病历、住院证、住院记录、查房记录等,包含"住院号"或"床号",无"出院时间" |
| 010 | 出院小结 | 出院小结、出院记录、出院医嘱,包含"住院号"、"入院时间"、"出院时间"、"诊疗经过"、"出院诊断"等 |
| 011 | 检查报告 | CT、MRI、DR、X线、报告单、诊断报告、B超申请单、化验单等 |
| 012 | 处方笺 | 处方笺、门诊处方笺、处方、急诊处方、处方单、处方明细等 |
| 013 | 住院诊断证明 | 标题为诊断证明书、疾病诊断书、出院证明书,同时包含"住院号"或"床号" |
| 014 | 病理报告 | 标题包含病理报告、病理检查报告,内容含有"病理诊断/病理学诊断"字段 |
| 015 | 门诊诊断证明 | 标题为诊断证明书、病情诊断证明书、门(急)诊病情证明书等 |
| 016 | 门诊费用清单 | 标题为医疗收费明细、门诊费用清单、诊疗项目收费清单等(归类到门诊电票) |
| 017 | 住院费用清单 | 标题为住院费用清单、住院病人费用明细、住院费用结算单等 |
| 018 | 门诊电票 | 门诊收费票据、发票,标题包含"门诊/急诊"和"(电子)",有二维码;门诊费用清单也归类到此类型 |
| 019 | 门诊纸票 | 门诊收费票据、发票,标题包含"门诊/急诊",无"(电子)"和二维码 |
| 020 | 住院电票 | 住院收费票据、发票,标题包含"住院"和"(电子)",有二维码 |
| 021 | 住院纸票 | 住院收费票据、发票,标题包含"住院",无"(电子)"和二维码 |
| 022 | 药房增值税发票 | 电子发票、普通发票,存在"增值税/纳税人识别号/税率",项目名称包含医疗服务、化学药品 |
| 023 | 病案首页 | 标题必须为病案首页或住院病案首页 |
| 024 | 纸质发票复印件 | 门诊/住院收费票据复印件,黑白或带"复印"字样,无彩色防伪标识 |
| 025 | 伤残鉴定报告 | 鉴定意见书、鉴定结论书等 |
| 026 | 理赔分割单 | 理赔分割单、理赔通知书、理赔核定通知书、理赔决定通知书等 |
| 027 | 交通事故认定书 | 标题为道路交通事故认定书 |
| 028 | 其他 | 不属于上述分类的材料,医保结算单也归类到此类型 |
分类原则
- 根据 OCR 识别的内容,按照分类标准进行判断
- 仔细甄别各个类型之间的联系和区别
- 如果原始是PDF包含多页,只看第一页进行分类
- 只生成有对应票据的文件夹
第三步:OCR识别和信息抽取
使用 qianfanocr-document-intelligence skill 对每个文件进行 OCR 识别。
病历信息抽取
对于病历文件(包括门急诊病历、入院记录、出院小结、住院诊断证明、门诊诊断证明),抽取以下信息:
- 住院日期 - 入院和出院日期
- 医院名称 - 就医医院的完整名称
发票信息抽取
对于发票文件(包括门诊电票、门诊纸票、住院电票、住院纸票、药房增值税发票),抽取以下字段:
- 就诊日期
- 账单金额(金额合计)
- 统筹先期给付金额(医保统筹基金支付)
- 全额自费(个人自费)
- 部分自费(个人自付)
- 第三方支付(来自理赔分割单,发票中暂无此字段,填0)
注意事项:
- 金额字段需要识别数字格式,支持小数点
- 日期格式可能是多种形式,统一转换为 YYYY-MM-DD
- 如果某个字段在发票中不存在,留空或填0
第四步:生成输出
文件夹结构
根据实际分类结果,创建对应的文件夹:
输出目录/
├── [分类名称]/ # 只生成有对应票据的文件夹
├── [分类名称]/
├── ...
└── 发票汇总.csv # 发票信息汇总表(如果有发票)
发票汇总 CSV
创建 发票汇总.csv 文件,格式如下:
| 列名 | 说明 |
|---|---|
| 发票号 | 发票号码 |
| 就诊日期 | 就诊日期(YYYY-MM-DD格式) |
| 账单金额 | 金额合计 |
| 统筹先期给付金额 | 医保统筹基金支付金额 |
| 全额自费 | 个人自费金额 |
| 部分自费 | 个人自付金额 |
| 第三方支付 | 来自理赔分割单,发票中填0 |
最后一行为合计行,对各金额列进行单独合计(除发票号和就诊日期外)。
CSV 格式示例:
发票号,就诊日期,账单金额,统筹先期给付金额,全额自费,部分自费,第三方支付
12345678,2024-03-15,1500.00,1000.00,0.00,300.00,0.00
87654321,2024-03-16,2500.00,1800.00,50.00,400.00,250.00
合计,,2800.00,50.00,700.00,250.00
注意: CSV 文件需要按就诊日期进行排序。
处理压缩包
如果输入是压缩包:
- 创建临时解压目录
- 解压文件
- 处理所有文件
- 清理临时目录(询问用户是否保留)
支持的压缩格式:
- zip
- rar
- 7z
错误处理
- 如果某个文件 OCR 失败,记录到错误日志,继续处理其他文件
- 如果发票某个字段无法识别,在 CSV 中留空
- 如果无法确定文件类型,放入"其他"文件夹
输出总结
处理完成后,向用户报告:
- 处理文件总数
- 各分类文件数量
- OCR 成功/失败数量
- 输出目录位置
- 发票总金额等关键统计信息
Qianfan OCR Document Intelligence
This skill orchestrates visual understanding for images and PDFs. It does not implement a vision model itself. It selects the right analysis mode, prepares inputs, invokes the bundled CLI, and returns a structured result for the upstream agent.
Required Execution Order
Always follow this order:
- Check whether
QIANFAN_TOKENis already available. - If the token is missing, stop immediately and ask the user for the API Key.
- If the user provides the API Key, write it to
<skill-root>/.envasQIANFAN_TOKEN=.... - Only after the token is available, continue to mode selection, reference loading, and CLI calls.
This token preflight takes precedence over all later rules in this skill. Do not read
references/*.md, do not select a mode, and do not call any bundled script until the token check
has passed.
API Key Setup
Before first use, make sure QIANFAN_TOKEN is available either in the process environment or in
<skill-root>/.env.
If the token is missing, ask the user in Chinese:
QIANFAN_TOKEN 环境变量未设置。请提供百度千帆 API Key。
如果您暂时没有 API Key,请到 https://cloud.baidu.com/product-s/qianfan_home 注册获取。
If the user provides the key, persist it to <skill-root>/.env before continuing. Do not rely on
a temporary export QIANFAN_TOKEN=... as the only storage mechanism.
Do not assume a bundled default token exists.
Bundled Tools
scripts/qianfan_ocr_cli.py: send one or more images to the backend VLM.scripts/pdf_to_images.py: convert one or more PDFs into per-page images before calling the VLM.scripts/render_doc_markdown.py: replace document-parsing image placeholders with cropped image files.scripts/run_document_parsing.py: run document parsing end-to-end and always render image placeholders.scripts/run_pdf_document_parsing.py: run PDF document parsing end-to-end and export combined markdown, shared assets, and per-page markdown files.scripts/run_document_parsing_with_layout.py: run document parsing with layout and export markdown, layout JSON, and a layout overlay image.scripts/run_layout_analysis.py: run layout analysis and export_layout.jsonplus a layout overlay image.scripts/run_element_recognition.py: run element recognition and save the result as a sibling markdown file.
Always call scripts by absolute path. In Codex, use the installed absolute skill path instead of a bare relative path.
Examples:
python3 "<skill-root>/scripts/qianfan_ocr_cli.py" "<prompt>" --image <path_or_url>
python3 "<skill-root>/scripts/pdf_to_images.py" <pdf_or_url> --output-dir <dir>
python3 "<skill-root>/scripts/render_doc_markdown.py" parsed.md --image <page_image> --output-dir <assets_dir> --output-markdown <rendered_md>
python3 "<skill-root>/scripts/run_document_parsing.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_pdf_document_parsing.py" <pdf> --pages all
python3 "<skill-root>/scripts/run_document_parsing_with_layout.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_layout_analysis.py" <image_or_pdf>
python3 "<skill-root>/scripts/run_element_recognition.py" <cropped_image_or_pdf> --element-type <text|formula|table>
Trigger Rules
Trigger this skill only when all of the following are true:
- The task involves one or more image files or URLs, or one or more PDF files or URLs.
- The agent must recognize, understand, extract, answer questions about, or locate content inside those images or PDFs.
- The relevant information cannot be obtained from existing plain-text sources already available to the agent.
Do not trigger when:
- The file is plain text, structured data, or source code that can be read directly.
- The user is asking for image-processing or PDF-processing code rather than visual understanding.
- The image/PDF path or URL is mentioned incidentally and no visual understanding is requested.
- A previous invocation already answered the same question and repeating the call would be redundant.
Input Preparation
Image inputs
- Pass local image paths or image URLs directly to
qianfan_ocr_cli.py. - Use one call per unrelated image.
- Use repeated
--imageflags only when cross-image reasoning is required.
PDF inputs
- If the input is a PDF, convert it to page images first with
scripts/pdf_to_images.py. - For single-page questions, analyze only the relevant page when known.
- For multi-page PDFs, keep page order and label outputs with page numbers.
- If the PDF already has reliable selectable text and the task is pure text retrieval, do not use this skill; read the text directly.
Recommended PDF flow:
python3 "<skill-root>/scripts/pdf_to_images.py" report.pdf --output-dir /tmp/report-pages
python3 "<skill-root>/scripts/qianfan_ocr_cli.py" "<prompt>" --image /tmp/report-pages/report-p001.png
Analysis Modes
Select exactly one primary mode per call. If needed, make a second, more specific call after an initial pass.
| Mode | Use When | Goal |
|---|---|---|
document parsing | Need document structure, text, formulas, tables, and image placeholders from an image/PDF | Output Markdown parsing result |
layout analysis | Need all layout elements with positions and categories | Output layout elements with bbox and category |
element recognition | Need precise recognition on cropped elements such as text blocks, formulas, or tables | Output exact recognition for the cropped element |
document parsing with layout | Need both structural parsing and layout detection in one workflow | Output Markdown parsing plus layout analysis |
general ocr | Need all visible text without document structure | Extract all visible text lines |
key information extraction | Need key fields from cards, forms, receipts, invoices, contracts, or similar documents | Extract key information in structured form |
chart understanding | Need chart captions, structured chart content, or chart QA | Understand and structure chart content |
doc vqa | Need answers to specific questions about a document image/PDF | Answer questions grounded in the document |
Mode Selection Heuristics
- Use
document parsingfor full-page document understanding where output should be Markdown and preserve hierarchy. - Use
layout analysiswhen bounding boxes and categories are the main output. - Use
element recognitiononly after cropping the target region or when the user provides a single focused element image. - Prefer
scripts/run_element_recognition.pyforelement recognitionso the result is written next to the source file as a single markdown file without any assets directory. - Use
document parsing with layoutwhen both Markdown reconstruction and layout boxes are needed. - Use
general ocrfor screenshots, signs, posters, and simple document text extraction where layout is not important. - Use
key information extractionfor forms, certificates, IDs, invoices, receipts, contracts, and other field-centric documents. - For
key information extraction, if the user asks for all key-value information or all fields without naming a concrete field list, use the schema-free prompt path instead of inventing an explicit schema. - Use
chart understandingfor plots, dashboards, and chart-heavy report pages. - Use
doc vqafor targeted questions such as totals, dates, clauses, page content, or whether a document contains a specific item.
Reference Loading Rule
Only after token preflight has passed and after selecting the mode, always read the corresponding
file in references/ before composing the prompt or calling any script.
document parsing->references/document-parsing.mdlayout analysis->references/layout-analysis.mdelement recognition->references/element-recognition.mddocument parsing with layout->references/document-parsing-with-layout.mdgeneral ocr->references/general-ocr.mdkey information extraction->references/key-information-extraction.mdchart understanding->references/chart-understanding.mddoc vqa->references/doc-vqa.md
Do not skip this step when a matching reference exists.
Prompt Sourcing Rule
When the selected reference contains a prompt template, prompt rule, fixed prompt, output format, or parameter recommendation, use that reference as the primary source of truth.
- Prefer the prompt in the corresponding
references/*.mdfile over ad-hoc prompt writing. - Reuse the reference prompt verbatim when it is marked as a fixed prompt or standard prompt.
- Reuse the reference output format requirements instead of inventing a new format.
- Only add task-specific details, such as the user question, selected keys, page number, or input scope, on top of the reference prompt.
- If you intentionally deviate from the reference prompt, state why in the intermediate reasoning and keep the deviation minimal.
Parameter Mapping Rule
If the selected reference defines execution parameters, convert them into actual CLI flags or request fields. Do not leave them as documentation-only notes.
Examples:
min_dynamic_patch = 8-> pass--min-dynamic-patch 8max_dynamic_patch = 24-> pass--max-dynamic-patch 24- thinking mode -> pass
--thinking
Before running qianfan_ocr_cli.py, verify that the final command includes the parameter settings
required by the selected mode.
Prompt Rules
- Write the VLM prompt in Chinese when the user is communicating in Chinese; otherwise use English.
- State the mode and output format explicitly in the prompt.
- Tell the model to mark anything uncertain as unclear / unreadable instead of guessing.
- For PDFs, mention page numbers in the prompt whenever multiple pages are analyzed.
- For cropped inputs used in
element recognition, specify the element type: text, formula, table, figure caption, seal, signature block, and so on. - For
document parsingoutputs that containplaceholders, runscripts/render_doc_markdown.pybefore presenting the Markdown to users who need renderable local images. - Prefer
scripts/run_document_parsing.pyover manually chainingqianfan_ocr_cli.pyandrender_doc_markdown.pywhen the task is standard document parsing. - Prefer
scripts/run_pdf_document_parsing.pyfor PDF document parsing when the user wants one markdown for the whole PDF plus per-page markdown files and a shared assets directory. Use--request-mode jointwhen selected PDF pages are semantically related and should be sent as one multi-image request. Use--request-mode batch --concurrency <N>when pages can be parsed independently and should run concurrently. - Prefer
scripts/run_document_parsing_with_layout.pyfordocument parsing with layoutso the final output includes markdown,_layout.json, and a rendered layout overlay image.
CLI Strategy
- Default to one call per image or page.
- Use repeated
--imageflags only for cross-page or cross-image reasoning that truly depends on joint context. - If multiple images should be processed independently rather than jointly, use
scripts/qianfan_ocr_cli.py --batch --concurrency <N>or a dedicated runner instead of sending all images as one joint request. - Use
--thinkingonly for difficult document understanding tasks with ambiguous reading order or dense field relationships. - Retry at most once per image/page, and only with a more specific prompt.
Read only the relevant reference file when needed, but do read that file before prompt construction:
references/document-parsing.mdreferences/layout-analysis.mdreferences/element-recognition.mdreferences/document-parsing-with-layout.mdreferences/general-ocr.mdreferences/key-information-extraction.mdreferences/chart-understanding.mdreferences/doc-vqa.md
Output Contract
Return a structured result instead of raw model prose:
=== VISUAL ANALYSIS RESULT ===
mode: <mode>
confidence: <high|medium|low>
input_type: <image|pdf>
image_count: <N>
page_count: <N or n/a>
answer:
<direct answer or summary>
evidence:
- <directly observed fact>
warnings:
- <uncertainty or limitation>
markdown:
<for document parsing modes>
layout:
- page: <n>
category: <label>
bbox: [x1, y1, x2, y2]
structured_data:
<for key information extraction / chart understanding>
recognized_elements:
<for element recognition>
=== END VISUAL ANALYSIS ===
Conservatism Rules
- Separate observation from inference.
- Never invent text, values, fields, or boxes.
- Mark unreadable regions explicitly.
- For charts, distinguish exact values from estimated values.
- For PDFs, keep page attribution explicit:
page_1,page_2, and so on. - If page conversion or image quality is poor, mention that in
warnings.
Sponsors
Details
- Marketplace
- baidubce/skills
- Category
- Community