文档扫描增强

文档高清扫描增强工具，通过扫描服务API对图片进行画质优化、瑕疵去除和视觉增强. 支持13种场景：考试增强、画质增强、证件票据增强、去手写、去水印、去阴影、去屏纹、 去底色、裁剪矫正、素描速写、提取线稿、扫描合同、扫描文件。适用于独立开发者、 企业团队和自动化工作流场景。不适用于视频处理和实时摄像头流.

核心功能: 本技能提供中文交互等能力。

核心功能: 本技能提供化工作流场景等能力。

文档扫描增强工具

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

参数说明

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

付费版进阶功能

能力	免费版	付费版
基础功能	支持	支持
文档扫描增强文档高清扫描	不支持	支持
深度漏洞扫描与CVE关联	不支持	支持
安全基线合规审计	不支持	支持
批量资产风险评分	不支持	支持
威胁情报实时订阅与告警	不支持	支持

隐私与数据流向

• 图片发送至扫描服务官方服务器进行识别处理
• 服务端不会永久保存图片内容
• 识别返回的图片保存至系统临时目录（如 /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
• 示例指令："优化一下这张文档图片，让它看起来更专业"

快速掌握

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

操作流程

领先步：输入处理

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

• 图片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种格式	先转换为支持的图片格式

异常恢复流程

错误场景	错误码/原因	处理方式
缺少图片输入	A0201	提供图片URL、文件路径或BASE64数据
图片超过5MB限制	API拒绝处理	先压缩或裁剪图片至5MB以下
不支持的图片格式	格式校验失败	转换为jpg/jpeg/png/gif/bmp/webp/tiff/wbmp之一
SCAN_WEBSERVICE_KEY未配置	认证失败	通过config命令配置API密钥后重启会话
API服务端返回非00000错误码	服务端处理异常	原样透出错误信息，
网络连接扫描服务超时	网络不可达
自行构造--scene参数值	场景标识无效	必须使用本文档指定的13种场景名

热门问题

Q1: 支持哪些图片格式？

A: 支持8种格式：jpg、jpeg、png、gif、bmp、webp、tiff、wbmp。其他格式需先转换.

Q2: 图片大小限制是多少？

A: 本地文件不超过5MB。超过限制时需先压缩或裁剪.

Q3: 如何配置API密钥？

A: 使用 skill-platform config set skills.entries.alibaba-quark-scan.env.SCAN_WEBSERVICE_KEY "your_key" 配置，配置后需重启会话生效.

Q4: 支持批量处理多张图片吗？

A: 不支持。每次调用仅限单张图片。如需批量处理，请循环调用或联系管理员.

Q5: 处理结果保存在哪里？

A: 成功处理后的图片由 file_saver.py 自动保存至系统临时目录（如 /tmp/imgs），返回JSON中包含 path 字段。文件持续存在直到手动清理.

Q6: 支持视频处理吗？

A: 不支持。仅支持单张静态图片处理。视频需先提取帧再逐帧处理.

Q7: 如何获取API密钥？

A: 访问扫描服务官方开发者后台，登录/注册账号后查看API Key。密钥应妥善保管，泄露后需及时轮换.

限制条件

• 禁止修改固定命令格式，只能替换场景标识和图片占位符
• 严禁自行构造 --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 Key配置错误	检查API Key配置，确保正确	重新配置API Key
服务器错误	服务器故障或网络问题	检查网络连接，联系技术支持	重新尝试或联系技术支持
耗时过长	处理任务过多，服务器负载高	检查服务器负载，优化任务分配	优化任务分配，减轻服务器压力

安全提示

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

安全风险防范

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

功能速览

• 自动化执行: 文档高清扫描增强工具，
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

用户问题解答

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

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

Q2: 需要配置API Key吗？

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

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

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

错误恢复指南

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

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

文档扫描增强通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块