文档扫描增强

通过扫描服务API对文档图片进行高清画质优化和瑕疵去除，支持13种应用场景如考试增强和去水印。

Install

openclaw skills install @thcjp/quark-scan

功能说明: 本技能涵盖化工作流场景等核心能力。

功能说明: 本技能涵盖中文交互等核心能力。

文档扫描增强工具

通过扫描服务API对图片进行高清扫描、画质优化和瑕疵去除。支持13种场景识别，每次请求只执行一个意图类型.

参数说明

参数名	类型	必填	说明
input	string	是	文档扫描增强处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

隐私与数据流向

图片发送至扫描服务官方服务器进行识别处理
服务端不会永久保存图片内容
识别返回的图片保存至系统临时目录（如 /tmp/imgs）
SCAN_WEBSERVICE_KEY 应妥善保管，泄露后需及时轮换

配置

通过环境变量配置API密钥：

bash

skill-platform config set skills.entries.alibaba-quark-scan.env.SCAN_WEBSERVICE_KEY "your_scan_webservice_key_here"

配置后需重启或开启新会话才能生效.

前置条件

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

分类: MD+EXEC（）

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

能力描述

1. 考试增强（exam-enhance）

将手写笔记、试卷、教材等学习资料照片转化为高清、去噪、背景纯净的电子文档.

scene标识：exam-enhance
示例指令："把这张拍糊了的试卷变清晰后发给我"

2. 画质增强（image-hd-enhance）

将模糊、昏暗、老旧或低质量照片进行画质增强，改善视觉效果和可读性.

scene标识：image-hd-enhance
示例指令："这张老照片太模糊了，帮我把画质变清晰一点"

3. 证件票据增强（certificate-enhance）

对模糊、光线不佳的证件及票据照片进行画质优化，使文字与关键信息清晰可辨.

scene标识：certificate-enhance
示例指令："帮我把这张购物小票上的金额和日期部分增强清楚"

4. 图像去手写（remove-handwriting）

将手写笔迹、划痕从印刷文档图像中自动清除，保留原始印刷文字与格式.

scene标识：remove-handwriting
示例指令："把这张做过的试卷上的手写答案去掉，还原成空白卷子"

5. 图像去水印（remove-watermark）

精准去除图片水印（文字、Logo、标记等），不损伤背景和整体构图.

scene标识：remove-watermark
示例指令："帮我把图片右下角的网站水印去掉"

6. 图像去阴影（remove-shadow）

去除文档或图像中因拍摄角度、光线产生的阴影，获得均匀亮度的高清扫描效果.

scene标识：remove-shadow
示例指令："这张纸拍出来有大片阴影，请帮我去除阴影变平整"

7. 图像去屏纹（remove-screen-pattern）

修复拍摄屏幕时产生的摩尔纹、反光、低对比度等问题，获得清晰文档图像.

scene标识：remove-screen-pattern
示例指令："这张对着电脑屏幕拍的照片有很多波纹，请帮我消除屏纹"

8. 文档去底色（remove-background-color）

将带有彩色背景、水印、阴影的文档截图一键转换为纯白背景加黑色文字.

scene标识：remove-background-color
示例指令："把这张红头文件的红色背景去掉，变成白底黑字"

9. 图像裁剪矫正（image-crop-rectify）

对图像进行自动矫正（透视校正、水平对齐）并智能裁剪多余边缘.

scene标识：image-crop-rectify
示例指令："这张照片拍歪了，帮我把文档扶正并裁掉多余的桌子背景"

10. 素描速写（sketch-drawing）

将普通照片转换为素描或速写风格图像，突出线条与明暗关系.

scene标识：sketch-drawing
示例指令："把这张人物照片转换成铅笔素描风格"

11. 提取线稿（extract-lineart）

从图片中提取线稿，将图像转换为简洁的线条形式图，用于艺术创作.

scene标识：extract-lineart
示例指令："从这张动漫图片中提取纯线稿，去掉颜色"

12. 扫描合同（scan-contract）

对合同或协议图片进行画质优化，让文字更清晰，画面更整洁，便于归档.

scene标识：scan-contract
示例指令："帮我把这份合同高清优化一下"

13. 扫描文件兜底（scan-document）

当用户指令不包含上述具体场景，仅表达优化意图时，调用扫描文件场景.

scene标识：scan-document
示例指令："优化一下这张文档图片，让它看起来更专业"

操作流程

领先步：输入处理

识别用户传入的图片类型，只能是以下三种之一：

图片URL：--url
本地文件路径：--path
图片BASE64：--base64

未提供任何有效图片时，返回错误码 A0201.

第二步：意图匹配

按照场景列表从上到下顺序匹配，命中领先个即停止，只确定当前意图对应的scene标识.

第三步：构建执行命令

根据图片类型，严格使用对应格式：

bash

python3 （请参考skill目录中的脚本文件） --scene "exam-enhance" --url "https://example.com/exam.jpg" --platform "skill-platform"
# ...
python3 （请参考skill目录中的脚本文件） --scene "remove-watermark" --path "/tmp/image.png" --platform "skill-platform"
# ...
python3 （请参考skill目录中的脚本文件） --scene "scan-contract" --base64 "iVBORw0KGgoAAAANSUhEUgAA..." --platform "skill-platform"

--platform 替换为当前运行的Agent平台名称，无法确定时填 community
--scene 必须使用本文档指定的场景名，严禁自行构造
直接执行命令，不增删任何参数

第四步：结果透出

执行完成后原样返回执行结果，不修改、不翻译、不美化。当 scan.py 调用成功（code == "00000"）且响应包含 ImageBase64 时，file_saver.py 会自动解码保存为本地图片文件，返回 data 替换为 {"path": "/tmp/未指定.png"}.

真实示例

示例1：考试试卷增强

bash

python3 （请参考skill目录中的脚本文件） --scene "exam-enhance" --path "/tmp/exam_photo.jpg" --platform "skill-platform"

输出：

json

{
  "code": "00000",
  "message": "success",
  "data": {"path": "/tmp/imgs/exam_enhanced_20260721.png"}
}

示例2：去水印

bash

python3 （请参考skill目录中的脚本文件） --scene "remove-watermark" --url "https://example.com/watermarked.png" --platform "community"

输出：

json

{
  "code": "00000",
  "message": "success",
  "data": {"path": "/tmp/imgs/nowm_20260721_143022.png"}
}

示例3：缺少图片输入

json

{
  "code": "A0201",
  "message": "缺少图片输入，请提供图片链接、文件路径或 BASE64 数据。",
  "data": null
}

不支持的场景

不支持的场景	原因	建议替代方案
视频处理	仅支持单张静态图片	先提取视频帧，再逐帧处理
批量处理	每次调用仅限单张图片	循环调用或联系管理员
实时摄像头流	非实时流处理架构	使用专用视频处理服务
超大图片（>5MB）	API限制	先压缩或裁剪后再处理
非图片格式	仅支持8种格式	先转换为支持的图片格式

限制条件

禁止修改固定命令格式，只能替换场景标识和图片占位符
严禁自行构造 --scene 参数值，必须使用本文档指定的13种场景名
图片大小限制：本地文件不超过5MB
支持格式：jpg/jpeg/png/gif/bmp/webp/tiff/wbmp
每次调用仅限单张图片，不支持批量处理

差异化分析

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
图片去水印	5分钟/张	30秒/张	4分钟/张	95%
图像去阴影	10分钟/张	2分钟/张	8分钟/张	98%
文档裁剪矫正	3分钟/张	1分钟/张	2分钟/张	100%
证件票据增强	15分钟/张	3分钟/张	12分钟/张	99%
素描速写转换	30分钟/张	5分钟/张	25分钟/张	95%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
操作便捷性	一键操作	逐个步骤手动处理	需编写脚本，操作复杂	需专业软件，学习成本高
处理效率	高效处理	逐张处理，耗时较长	效率一般，需优化脚本	高效处理，但需付费
处理效果	高质量输出	效果参差不齐	效果一般，需调整参数	高质量输出，但需付费
适用场景	通用办公	适用于简单场景	适用于有编程基础的场景	适用于专业领域
成本	低成本	无需额外成本	需学习编程，成本较高	需付费软件，成本较高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
手动操作效率低	人工处理耗时较长，影响工作效率	各行业文档处理	自动化处理，提高效率	时间节约达50%
文档质量不佳	手动处理可能导致文档模糊不清	各行业文档处理	高质量输出，提升文档质量	准确率提升达95%
专业软件成本高	需要购买专业软件，成本较高	各行业文档处理	提供免费服务，降低成本	成本节约达80%

安全提示

确保API Key安全，避免泄露。
上传的图片内容不得包含敏感信息，如个人隐私、商业机密等。
图片处理过程中，确保用户隐私不被泄露。
服务器端不保存用户上传的图片，确保数据安全。
定期更新API，修复潜在的安全漏洞。

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

用户问题解答

Q1: 文档扫描增强支持哪些输入格式？

A1: 文档高清扫描增强工具，。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

错误恢复指南

针对文档扫描增强使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置