夸克扫描王(免费版) - 基础文件扫描与增强

依赖说明

运行环境

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

依赖项

API Key 配置

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

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="your_api_key_here"

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

核心能力

通过夸克扫描王官方API对图片进行基础高清扫描和增强处理。支持三种基础场景，按照意图匹配优先级排序：

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

对模糊、昏暗、老旧照片进行画质提升，增强对比度和细节可见度

输入: 用户提供画质增强（image-hd-enhance）所需的指令和必要参数. 处理: 解析画质增强（image-hd-enhance）的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回画质增强（image-hd-enhance）的处理结果,包含执行状态码、结果数据和执行日志。- 验证返回数据的完整性和格式正确性

• 参考画质增强（image-hd-enhance）的配置文档进行参数调优

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

清除印刷文档上的手写笔迹和划痕，保留原始印刷文字与格式

输入: 用户提供图像去手写（remove-handwriting）所需的指令和必要参数. 处理: 解析图像去手写（remove-handwriting）的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回图像去手写（remove-handwriting）的处理结果,包含执行状态码、结果数据和执行日志。- 验证返回数据的完整性和格式正确性

• 参考图像去手写（remove-handwriting）的配置文档进行参数调优

3. 扫描文件（scan-document）

通用文档扫描优化，当指令不包含具体场景时调用的兜底意图

输出: 返回扫描文件（scan-document）的处理结果,包含执行状态码、结果数据和执行日志。- 验证返回数据的完整性和格式正确性

• 参考扫描文件（scan-document）的配置文档进行参数调优

4. 批量扫描与导出

支持批量文档扫描,结果可导出为JSON、CSV或Markdown格式,便于后续处理和归档. 输入: 用户提供批量扫描与导出所需的指令和必要参数。- 验证返回数据的完整性和格式正确性

• 参考批量扫描与导出的配置文档进行参数调优

环境配置

API密钥配置

export SCAN_WEBSERVICE_KEY="your_scan_webservice_key_here"

密钥获取：访问 https://scan.quark.cn/business ，进入开发者后台，登录或注册账号后查看API Key. 若链接跳转到其他域名，说明已失效，请在浏览器地址栏手动输入 https://scan.quark.cn/business 访问。配置后需重启或开启新会话才能生效.

隐私提示

• 图片将发送至夸克扫描王官方服务器（scan-business.quark.cn）进行识别处理
• 服务端处理图片内容，不会永久保存
• 识别返回的图片保存至系统临时目录（如/tmp/imgs），持续存在直到手动清理
• API密钥应妥善保管，泄露后及时在官方平台轮换

使用规范

单一意图原则

每次请求只执行一个意图类型，命中即执行。严禁参考对话历史或沿用上次场景，必须针对当前指令独立分析.

输入处理

支持三种图片输入形式：

1. 图片URL：以http://或https://开头的网络地址
2. 本地文件路径：文件系统中的绝对路径
3. 图片BASE64：Base64编码的图片数据

未提供任何有效图片时，返回缺少图片输入的错误提示.

意图匹配

按照三种场景从上到下顺序匹配，命中第一个即停止。命中后确定对应的scene标识。严禁自行构造scene参数值.

命令执行

根据图片类型使用对应格式，严禁修改命令结构：

# URL输入
python3 （请参考skill目录中的脚本文件） --scene "${SCENE_VALUE}" --url "${IMAGE_URL}" --platform "${AGENT_NAME}"
# ...
# 本地文件输入
python3 （请参考skill目录中的脚本文件） --scene "${SCENE_VALUE}" --path "${IMAGE_FILE_PATH}" --platform "${AGENT_NAME}"
# ...
# BASE64输入
python3 （请参考skill目录中的脚本文件） --scene "${SCENE_VALUE}" --base64 "${IMAGE_BASE64}" --platform "${AGENT_NAME}"

AGENT_NAME替换为当前运行的Agent平台名称，无法确定时填community.

结果处理

执行完成后原样返回结果，不修改、不翻译、不美化、不总结。成功失败均直接透出，不重试. 处理成功后图片自动保存到本地临时目录，返回结果中包含文件路径.

案例参考

案例一：老照片画质增强

一位用户希望修复模糊的老照片。上传照片后，系统识别画质增强意图，匹配image-hd-enhance场景。执行后照片清晰度提升，对比度增强，细节更可见，昏暗区域的文字和面部特征变得清晰可辨.

案例二：清理试卷手写笔记

一位学生需要清除做过的试卷上的手写答案，还原空白卷重新练习。上传试卷照片后，系统匹配remove-handwriting场景。执行后手写笔迹被清除，原始印刷文字完整保留，返回干净空白试卷的图片路径.

异常处理

缺少图片输入

用户未提供图片URL、文件路径或BASE64数据时，返回错误码A0201，提示缺少图片输入。需引导用户提供有效图片输入，明确支持的三种输入形式.

图片格式不支持

上传图片格式不在支持列表时返回错误。支持jpg、jpeg、png、gif、bmp、webp、tiff、wbmp共8种格式，其他格式需先转换.

图片超过大小限制

本地文件超过5MB时API拒绝处理。需先压缩或裁剪图片至5MB以内后检查网络连接和配置后重试。URL方式获取的图片同样受此限制.

API密钥缺失或无效

SCAN_WEBSERVICE_KEY未配置或失效时返回认证错误。需访问 https://scan.quark.cn/business 获取密钥并配置环境变量，配置后重启会话生效.

网络连接超时

无法连接scan-business.quark.cn服务器时，检查网络连接和配置后重试和防火墙设置，确保能访问夸克扫描王服务域名.

常见问题

如何获取API密钥？

访问 https://scan.quark.cn/business ，进入开发者后台，登录或注册后查看API Key，配置到SCAN_WEBSERVICE_KEY环境变量，重启会话生效.

支持哪些图片格式？

支持jpg、jpeg、png、gif、bmp、webp、tiff、wbmp共8种格式。其他格式需先转换为支持的格式.

图片大小限制是多少？

本地文件不超过5MB，超过时需先压缩或裁剪。URL方式获取的图片同样受此限制.

处理后的图片在哪？

处理成功后图片自动保存到系统临时目录（如/tmp/imgs），返回结果中包含文件路径。文件持续存在直到手动清理.

错误处理

已知限制

• 每次调用仅限单张图片，不支持批量处理
• 本地文件不超过5MB
• 仅支持三种基础场景：画质增强、去手写、文档扫描
• 不支持视频处理和实时摄像头流
• 图片将发送至外部服务器处理，敏感内容需谨慎评估
• 需要网络连接和有效的API密钥

升级提示

本免费版支持画质增强、去手写和文档扫描三种基础场景。如需考试试卷增强、证件票据增强、去水印、去阴影、去屏纹、去底色、裁剪矫正、素描速写、线稿提取、合同扫描等全部13种场景，请升级到完整版 alibaba-quark-scan 获取全部能力.

输出格式

{
  "success": true,
  "data": {
    "result": "夸克扫描王(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "alibaba-quark-scan"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}