{"id":"7c6b7023-2ebe-4454-aea1-2992c27b4679","entityType":"agent","slug":"clawhub-yescan-ai-alibaba-quark-scanking-all","name":"夸克扫描王-OCR 文字识别/文件扫描/转 Office Alibaba-Quark-Scanking-All","canonicalUrl":"https://www.xpersona.co/agent/clawhub-yescan-ai-alibaba-quark-scanking-all","canonicalPath":"/agent/clawhub-yescan-ai-alibaba-quark-scanking-all","generatedAt":"2026-10-11T14:17:53.921Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T11:20:07.913Z","emptyReason":null},"description":"夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描/线稿）、图片转 Word/Excel/PDF、AI 证件照生成。 Skill: 夸克扫描王-OCR 文字识别/文件扫描/转 Office Alibaba-Quark-Scanking-All Owner: yescan-ai Summary: 夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描/线稿）、图片转 Word/Excel/PDF、AI 证件照生成。 Tags: latest:1.1.3 Version history: v1.1.3 | 2026-07-09T11:07:39.287Z | auto - Skill renamed from yescan-universal to alibaba-quark-scank","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17cpsmkvb7rwpbns3vsexnv0n882f2y:alibaba-quark-scanking-all","sourceUrl":"https://clawhub.ai/yescan-ai/alibaba-quark-scanking-all","homepage":"https://clawhub.ai/yescan-ai/skills/alibaba-quark-scanking-all","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/yescan-ai/alibaba-quark-scanking-all","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/yescan-ai/skills/alibaba-quark-scanking-all","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:20:07.913Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:20:07.913Z","emptyReason":null},"stars":null,"forks":null,"downloads":1078,"packageName":null,"latestVersion":"1.1.3","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:20:07.856Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T11:20:07.913Z","lastCrawledAt":"2026-10-11T11:20:07.856Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T11:20:07.856Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.3","createdAt":"2026-07-09T11:07:39.287Z","changelog":"- Skill renamed from yescan-universal to alibaba-quark-scanking-all, with updated author metadata. - Removed _meta.json file. - Documentation files (README.md, README.en.md, SKILL.md) updated to reflect new name and author, with no material logic or functionality changes. - All original workflow, verification, and usage details are retained.","fileCount":9,"zipByteSize":13438},{"version":"1.1.1","createdAt":"2026-07-09T10:39:22.283Z","changelog":"- 新增或大幅重写技能文档，明确操作流程及约束规则。 - 统一技能名称为 yescan-universal，提供标准化图片OCR、图像增强、格式转换等功能描述。 - 强调严格执行 Plan → Execute → Verify 流程，每步包含硬性前置 Gate，明确升级、密钥配置和参数确认等要求，流程不可跳步。 - 明确支持和禁止用例范围（如仅支持图片类处理、不支持视频或纯文本）。 - 完善执行细节，要求所有场景、参数、执行和结果均以实际CLI输出为准，禁止手动假造或补全。 - 附带多份参考文档和错误处理指引，提升技能操作的规范性与安全性。","fileCount":9,"zipByteSize":13321},{"version":"1.0.1","createdAt":"2026-07-09T10:32:31.118Z","changelog":"No user-facing changes detected in this release. - No file or documentation changes observed between 1.0.0 and 1.0.1.","fileCount":9,"zipByteSize":13427}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17cpsmkvb7rwpbns3vsexnv0n882f2y:alibaba-quark-scanking-all","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T14:17:53.920Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-yescan-ai-alibaba-quark-scanking-all/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T11:20:07.913Z","emptyReason":null},"readme":"Skill: 夸克扫描王-OCR 文字识别/文件扫描/转 Office Alibaba-Quark-Scanking-All\n\nOwner: yescan-ai\n\nSummary: 夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描/线稿）、图片转 Word/Excel/PDF、AI 证件照生成。\n\nTags: latest:1.1.3\n\nVersion history:\n\nv1.1.3 | 2026-07-09T11:07:39.287Z | auto\n\n- Skill renamed from yescan-universal to alibaba-quark-scanking-all, with updated author metadata.\n- Removed _meta.json file.\n- Documentation files (README.md, README.en.md, SKILL.md) updated to reflect new name and author, with no material logic or functionality changes.\n- All original workflow, verification, and usage details are retained.\n\nv1.1.1 | 2026-07-09T10:39:22.283Z | auto\n\n- 新增或大幅重写技能文档，明确操作流程及约束规则。\n- 统一技能名称为 yescan-universal，提供标准化图片OCR、图像增强、格式转换等功能描述。\n- 强调严格执行 Plan → Execute → Verify 流程，每步包含硬性前置 Gate，明确升级、密钥配置和参数确认等要求，流程不可跳步。\n- 明确支持和禁止用例范围（如仅支持图片类处理、不支持视频或纯文本）。\n- 完善执行细节，要求所有场景、参数、执行和结果均以实际CLI输出为准，禁止手动假造或补全。\n- 附带多份参考文档和错误处理指引，提升技能操作的规范性与安全性。\n\nv1.0.1 | 2026-07-09T10:32:31.118Z | auto\n\nNo user-facing changes detected in this release.\n\n- No file or documentation changes observed between 1.0.0 and 1.0.1.\n\nArchive index:\n\nArchive v1.1.3: 9 files, 13438 bytes\n\nFiles: README.en.md (2239b), README.md (2106b), references/implementation.md (2805b), references/privacy.md (2671b), references/troubleshooting.md (2153b), SECURITY.md (2315b), skill-card.md (3033b), SKILL.md (5558b), _meta.json (145b)\n\nFile v1.1.3:SKILL.md\n\n---\nname: alibaba-quark-scanking-all\ndescription: 夸克扫描王一站式图片/文档处理中心。当用户需要对图片进行文字识别（OCR）、图片翻译、画质增强（去除水印/阴影/手写/底色/屏纹等瑕疵，矫正，高清增强，素描/线稿转换等）、格式转换（转 Word/Excel/PDF）或 AI 生成（证件照）时使用此技能。即使用户没有明确提到具体功能名称，只要涉及图片处理、文字提取、文档转换、图像优化或证件照生成，都应触发此技能。不适用于视频处理、纯文本编辑或非图片输入的任务。夸克扫描王图片处理能力中心。\nlicense: MIT\ncompatibility: Requires pip3 install yescan and SCAN_WEBSERVICE_KEY configuration. Performs network calls to scan-business.quark.cn.\nmetadata:\n  author: alibaba-quark-scanking\n  version: \"1.0.5\"\n  homepage: https://scan.quark.cn/business\n---\n\n## 执行流程\n\n每次执行严格按 **Plan → Execute → Verify** 顺序进行，不得跳过或乱序。\n\n### Plan — 理解意图，发现能力\n\n1. 确认环境就绪（每次执行，不得跳过）：\n   - **安装 & 升级**：\n     1. `yescan --version` — 未安装则执行 `pip3 install yescan`；若版本 < 1.0.5，执行 `pip3 install yescan --upgrade`，升级完成后才继续\n     2. `pip3 index versions yescan` — 若 INSTALLED < LATEST，告知用户有新版本可用并提供升级命令：`pip3 install yescan --upgrade`，由用户决定是否升级\n   - **密钥检查**：`yescan config get SCAN_WEBSERVICE_KEY`，未配置则引导用户配置\n     - 设置命令：`yescan config set SCAN_WEBSERVICE_KEY <your_api_key>`\n     > Key 获取方式：https://scan.quark.cn/business → 开发者后台 → API Key\n\n   > **Checkpoint**：版本 < 1.0.5 → 必须升级后才能继续。版本 ≥ 1.0.5 但不是最新 → 提示用户后可继续。密钥未配置则引导配置后再继续。\n\n2. 发现能力：\n   ```bash\n   yescan --list-scenes              # 获取全部场景及意图描述\n   yescan --list-scenes <scene>      # 获取该场景的 --set 参数\n   ```\n   从输出中匹配用户意图到具体场景\n3. 多步处理时，向用户展示完整步骤计划\n\n**Gate**：\n- 「确认环境就绪」每一步均为硬性前置，不得跳过任何一步，未全部通过 → 禁止进入 Execute：\n  1. 未执行 `yescan --version` 确认安装状态 → 禁止继续\n  2. 版本 < 1.0.5 且未完成升级 → 禁止继续\n  3. 未执行 `pip3 index versions yescan` 确认最新版本状态 → 禁止继续\n  4. 未执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认密钥已配置 → 禁止继续\n- 只执行用户明确需要的场景，不主动添加额外步骤。为提升当前任务效果的辅助操作不受此限\n- 文档转换（Word/Excel/PDF）直接处理图片，不依赖 OCR 结果。两者输入都是图片，是独立操作\n- 场景名和 `--set` 参数必须来自本次会话的 CLI 输出\n- 未执行过 `--list-scenes` 则不得进入 Execute\n- 场景有 `--set` 参数且用户未明确指定时，须向用户展示可选参数并确认后再执行\n\n### Execute — 执行场景\n\n```bash\nyescan --scene <SCENE> --path <FILE> --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\nyescan --scene <SCENE> --url  <URL>  --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\n```\n> `--path` 传本地文件路径，`--url` 传 http/https 链接。\n\n> 把 `${AGENT_NAME}` 替换为当前 Agent 平台名称（如 openclaw、hermes、qoderWork、wukong、coze、claudecode 等），无法确定时填 `community`，禁止猜测或自造。\n\n- 单步：直接执行\n- 多步处理为逐步 Execute → Verify 循环：step N+1 的命令在 step N Verify 通过后才构造，`--path` 取自 step N 响应中的 `data.path`\n\n**Gate**：\n- 多步处理时向用户说明步骤计划\n- 每步命令不得预先构造\n- `--set` 参数不跨场景沿用\n\n### Verify — 验证并交付\n\n每步执行后检查响应中的 `code` 字段：\n\n- **成功**（`code` 为 `\"00000\"` 或 `0`）→ 进入交付\n- **失败** → 不继续下一步，根据错误信息处理（详见 Gate）\n\n交付标准 — 以下条件满足才算完成：\n\n- **OCR 识别**：识别内容已以可读文本呈现给用户\n- **图片翻译 / 图像增强 / AIGC**：输出文件路径已告知用户\n- **文档转换**：输出文档路径和格式已告知用户\n\n**Gate**：\n- code 非成功 → 不得继续下一步，不得报告成功\n- 根据错误信息自行修复（如场景名无效 → 重新 `--list-scenes`）或将错误原因告知用户\n- 用户未看到结果 → 未完成\n\n---\n\n## 约束\n\n- **输入方式**：`--path` 或 `--url`，二选一。不支持 base64（如需则先写入临时文件）\n- **URL 引号**：`--url` 参数须用单引号包裹，避免 shell 对 `!` `$` 等特殊字符的解析\n- **文件大小**：≤ 5MB\n- **图片来源**：仅限用户当次请求中明确指定的文件或 URL\n- **禁止伪造**：不得编造或模拟 yescan CLI 的请求参数或响应输出；所有场景名、参数值和执行结果必须来自实际运行的 CLI 命令\n\n---\n\n## 参考文档\n\n- [references/privacy.md](./references/privacy.md) — 隐私、数据流向与密钥安全\n- [references/troubleshooting.md](./references/troubleshooting.md) — 错误码与排错\n- [references/implementation.md](./references/implementation.md) — 实现细节：CLI 行为与响应字段\n- [SECURITY.md](./SECURITY.md) — 安全策略与数据流声明\n\nFile v1.1.3:README.md\n\n# yescan\n\n夸克扫描王一站式图片处理技能。支持 36 个场景，覆盖 OCR 识别、图像增强、文档转换、AIGC 生成四大能力。\n\n## 能力概览\n\n| 类别 | 场景数 | 典型用途 |\n|---|---|---|\n| OCR 识别 | 19 | 身份证、发票、表格、手写体、公式等文字提取 |\n| 图像增强 | 13 | 去水印、去阴影、去手写、矫正裁剪、画质增强等 |\n| 文档转换 | 3 | 图片转 Word / Excel / PDF |\n| AIGC 生成 | 1 | 证件照生成 |\n\n## 快速开始\n\n### 1. 安装\n\n```bash\npip3 install yescan\n```\n\n### 2. 配置 API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> 获取 API Key：https://scan.quark.cn/business → 开发者后台\n\n### 3. 使用\n\n```bash\n# 查看所有场景\nyescan --list-scenes\n\n# OCR 识别\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# 图像增强\nyescan --scene remove-watermark --path ./img.jpg\n\n# 文档转换\nyescan --scene image-to-excel --path ./table.jpg\n\n# 查看单个场景的参数\nyescan --list-scenes id-photo\n```\n\n## 设计理念\n\n- **CLI-first**：CLI 自解释，`--list-scenes` 输出包含意图描述和参数详情\n- **Agent-native**：SKILL.md 定义 PEV 协议（Plan → Execute → Verify）与约束，Agent 自主决策场景匹配\n- **动态发现**：所有场景和参数通过 CLI 动态查询，不硬编码\n\n## 文件结构\n\n```\nalibaba-quark-scanking-all/\n├── SKILL.md                        ← Agent 技能契约（PEV 协议 + 约束）\n├── references/\n│   ├── privacy.md                  ← 隐私、数据流向与密钥安全\n│   ├── troubleshooting.md          ← 错误码与排错\n│   └── implementation.md           ← 实现细节：CLI 行为与响应字段\n├── SECURITY.md                     ← 安全策略\n├── README.md                       ← 本文档\n└── README.en.md                    ← English README\n```\n\n## 相关链接\n\n- [夸克扫描王开放平台](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent 技能契约\n- [SECURITY.md](SECURITY.md) — 安全策略\n\nFile v1.1.3:_meta.json\n\n{\n  \"ownerId\": \"kn70q165k6hd6cpjtfp8enaa8s82vyem\",\n  \"slug\": \"alibaba-quark-scanking-all\",\n  \"version\": \"1.1.3\",\n  \"publishedAt\": 1783595259287\n}\n\nFile v1.1.3:references/implementation.md\n\n# 实现细节：CLI 行为与响应字段\n\n本文档描述 `yescan` CLI 的内部行为，供需要理解工作原理的开发者参考。\n\n---\n\n## 1. 执行流程\n\n```\n用户/Agent 调用\n  → yescan --scene <scene> --path/--url <input> [--output <dir>] [--set key=value]\n  → 加载凭证（SCAN_WEBSERVICE_KEY）\n  → 根据 scene_configs 构建请求参数\n  → POST https://scan-business.quark.cn/vision\n  → 解析响应 JSON\n  → 根据场景类型处理输出（stdout JSON / 落盘图片 / 落盘文档）\n```\n\n## 2. 响应结构\n\n### 成功响应（OCR 类场景）\n\n> **注意**：OCR 类场景的 `code` 为字符串 `\"00000\"`，而图像/文档类场景的 `code` 为数字 `0`，判断时需注意类型差异。\n\n```json\n{\n  \"code\": \"00000\",\n  \"message\": null,\n  \"data\": {\n    // 各场景返回不同字段，如：\n    // general-ocr: \"content\" (纯文本)\n    // table-ocr: \"tables\" (表格结构)\n    // idcard-ocr: \"name\", \"idNumber\", \"address\" 等\n  }\n}\n```\n\n### 图像/文档类输出（落盘后）\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"path\": \"/tmp/imgs/<Unix时间戳>_<16位随机十六进制串>.<扩展名>\"\n  }\n}\n```\n\n### 错误响应\n\n```json\n{\n  \"code\": \"A0100\",\n  \"message\": \"SCAN_WEBSERVICE_KEY 未配置...\",\n  \"data\": null\n}\n```\n\n## 3. 场景类型与输出行为\n\n| 场景类型 | 输出方式 | 输出位置 |\n|---|---|---|\n| OCR 识别 | JSON 打印到 stdout | 不落盘（除 pic-translate）；指定 `--output` 时保存 JSON 到指定目录 |\n| 图像增强 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n| 文档转换 | 文档落盘 | 系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 目录 |\n| AIGC 生成 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n\n## 4. 关键约定\n\n- OCR 场景直接返回 API 原始响应的 `data` 字段，不做二次加工。\n- **pic-translate 场景例外**：API 返回 `data.ImageInfo[0].ResImageBase64`，CLI 将其解码落盘并注入 `data.translated_image_path`，同时剔除 `ImageInfo` 字段避免 base64 噪音。\n- 图像/文档类输出的文件名格式：`<Unix时间戳>_<16位随机十六进制串>.<扩展名>`。\n- 多步 Pipeline 时，前一步的 `data.path` 作为下一步的 `--path` 输入。\n\n## 5. 错误码速查\n\n| 错误码 | 含义 | 常见原因 |\n|---|---|---|\n| A0100 | 凭证错误 | SCAN_WEBSERVICE_KEY 未配置或无效 |\n| A0201 | 缺少图片输入 | 未提供 --url 或 --path |\n| A0211 | 配额不足 | API 额度用尽，需充值 |\n| INVALID_SCENE | 场景名无效 | --scene 值不在可用场景列表中 |\n| FILE_ERROR | 文件校验失败 | 文件不存在、超过 5MB 或格式不支持 |\n\nFile v1.1.3:references/privacy.md\n\n# 隐私、数据流向与密钥安全\n\n本文档说明 `yescan` 技能在执行过程中涉及的全部数据流向、第三方服务交互范围，以及 API 密钥的配置、存储与轮换流程。\n\n---\n\n## 1. 数据流向（What leaves your machine）\n\n| 数据 | 是否外发 | 接收方 | 用途 |\n|---|---|---|---|\n| 用户提供的图片（URL / 本地文件） | 外发 | `https://scan-business.quark.cn`（夸克扫描王服务） | OCR / 增强 / 转换 / AIGC |\n| `SCAN_WEBSERVICE_KEY` | 随请求头发送 | 同上 | API 鉴权 |\n| 处理结果（JSON / 文件） | 不外发 | 仅返回给调用方 | CLI 输出到 stdout 或本地文件 |\n| 用户提示词、对话上下文 | 不外发 | — | 仅在本地 Agent 处理 |\n\n> **服务端处理说明**：夸克扫描王服务将获取并处理该图片内容，服务端不会永久保存。\n\n## 2. 本地文件行为\n\n- **OCR 场景**：不写入输出文件（结果以 JSON 打印到 stdout），`pic-translate` 场景例外（保存译图到临时目录）\n- **图像增强场景**：输出增强后图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- **文档转换场景**：输出文档文件到系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 指定目录\n- **AIGC 场景**：输出生成图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- 唯一的文件读取操作是用户指定的本地图片路径（`--path` 参数）\n\n## 3. API 密钥配置\n\n### 3.1 推荐方式：通过 CLI 配置（永久生效）\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key_here>\n```\n\n配置保存在 `~/.yescan/config.json`。\n\n### 3.2 备选方式：环境变量（仅当前会话）\n\n```bash\nexport SCAN_WEBSERVICE_KEY=<your_api_key_here>\n```\n\n> 优先级：CLI config（`~/.yescan/config.json`）> 环境变量\n\n## 4. 获取与轮换密钥\n\n1. 访问 `https://scan.quark.cn/business`（**仅此一个有效官方入口**）\n2. 进入开发者后台 → 登录/注册账号 → 创建应用 → 查看 API Key\n3. 如怀疑密钥泄露：在同一后台立即 *轮换* 或 *撤销* 旧密钥，并更新配置\n\n## 5. 安全实践清单\n\n- [x] 不要在公网截图/录屏中暴露 key 或配置文件内容\n- [x] 仅对用户主动指定的图片进行处理，不要遍历整个目录\n- [x] 处理涉密 / PII 图片前，用户应自行评估数据外发的合规性\n\n## 6. 适用范围\n\n本技能图片来源 **仅限用户在当次请求中明确指定** 的图片文件或 URL。技能不会主动扫描磁盘、访问剪贴板或读取额外文件。\n\nFile v1.1.3:references/troubleshooting.md\n\n# 错误码与排错\n\nyescan CLI 输出 JSON 响应，以下是常见错误码及对应排查步骤。\n\n---\n\n## 错误码一览\n\n| 错误码 | 含义 | 排查步骤 |\n|---|---|---|\n| A0100 | 凭证无效 | 1. 执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认已配置<br>2. 确认 key 无前后空格或引号问题<br>3. 访问 scan.quark.cn/business 确认 key 未过期 |\n| A0211 | 配额不足 | 访问 scan.quark.cn/business 开发者后台充值 |\n| INVALID_SCENE | 场景名无效 | 执行 `yescan --list-scenes` 查看所有可用场景名 |\n| INVALID_INPUT | 输入参数冲突 | `--url` 和 `--path` 只能提供一个 |\n| FILE_ERROR | 文件验证失败 | 确认文件存在、大小 ≤5MB、扩展名在支持列表中 |\n| URL_VALIDATION_ERROR | URL 格式无效 | 确认 URL 以 http:// 或 https:// 开头 |\n| HTTP_ERROR | 网络请求失败 | 检查网络连接，确认能访问 scan-business.quark.cn |\n\n## 常见问题\n\n### Q: yescan 命令不存在\n\n1. 确认已安装：`pip3 install yescan --upgrade`\n2. 若已安装仍找不到，说明 pip3 scripts 目录不在 PATH 中，执行 `python3 -m site --user-base` 查看安装路径，将其下的 `bin/`（macOS/Linux）或 `Scripts/`（Windows）加入 PATH\n3. 验证：`yescan --version`\n\n### Q: 提示凭证无效\n\n1. 执行 `yescan config get SCAN_WEBSERVICE_KEY` 查看当前配置\n2. 如果为空，执行 `yescan config set SCAN_WEBSERVICE_KEY <your_key>` 配置\n3. 访问 https://scan.quark.cn/business 确认 key 有效\n\n### Q: 执行后无任何输出\n\n确认 yescan 版本 ≥ 1.0.5：`yescan --version`。\n\n### Q: 识别结果为空或不准确\n\n- 确认图片清晰度足够\n- 确认选择了正确的 scene（如表格用 `table-ocr`，手写用 `handwritten-ocr`）\n- 图片分辨率过低时，可先使用 `image-hd-enhance` 增强再识别\n\n### Q: CLI 不支持 --base64 参数\n\nyescan CLI **不支持 `--base64` 输入**。如果图片是 base64 格式，请先写入临时文件再用 `--path` 传入。\n\n### Q: Pipeline 执行中某步失败\n\nPipeline 采用\"失败即停\"策略。排查失败步骤的错误码，修复后可从失败步骤重新执行。\n\nFile v1.1.3:README.en.md\n\n# yescan\n\nAll-in-one image processing skill powered by Quark Scan. Supports 36 scenes across OCR, image enhancement, document conversion, and AIGC generation.\n\n## Capabilities\n\n| Category | Scenes | Typical Use Cases |\n|---|---|---|\n| OCR | 19 | ID card, invoice, table, handwriting, formula, etc. |\n| Image Enhancement | 13 | Remove watermark / shadow / handwriting, crop & rectify, HD enhance, etc. |\n| Document Conversion | 3 | Image to Word / Excel / PDF |\n| AIGC Generation | 1 | ID photo generation |\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip3 install yescan\n```\n\n### 2. Configure API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> Apply for an API Key at the [Quark Scan Developer Console](https://scan.quark.cn/business).\n\n### 3. Usage\n\n```bash\n# List all scenes\nyescan --list-scenes\n\n# OCR\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# Image enhancement\nyescan --scene remove-watermark --path ./img.jpg\n\n# Document conversion\nyescan --scene image-to-excel --path ./table.jpg\n\n# View scene parameters\nyescan --list-scenes id-photo\n```\n\n## Design Philosophy\n\n- **CLI-first**: CLI is self-describing — `--list-scenes` output includes intent descriptions and parameter details\n- **Agent-native**: SKILL.md defines the PEV protocol (Plan → Execute → Verify) and constraints; Agent autonomously matches scenes\n- **Dynamic discovery**: All scenes and parameters are queried via CLI at runtime, never hardcoded\n\n## File Structure\n\n```\nalibaba-quark-scanking-all/\n├── SKILL.md                        ← Agent skill contract (PEV protocol + constraints)\n├── references/\n│   ├── privacy.md                  ← Privacy, data flow & key security\n│   ├── troubleshooting.md          ← Error codes & troubleshooting\n│   └── implementation.md           ← Implementation details: CLI behavior & response fields\n├── SECURITY.md                     ← Security policy\n├── README.md                       ← This document\n└── README.en.md                    ← English README\n```\n\n## Links\n\n- [Quark Scan Open Platform](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent skill contract\n- [SECURITY.md](SECURITY.md) — Security policy\n\nFile v1.1.3:SECURITY.md\n\n# Security Policy\n\nThis skill performs network calls via the `yescan` CLI. We disclose the full data flow upfront so that auditors and users can make informed decisions.\n\n## 1. Data flow at a glance\n\n| Item | Direction | Destination | Sensitive? |\n|---|---|---|---|\n| User-supplied image | **outbound** | `https://scan-business.quark.cn` | depends on content |\n| `SCAN_WEBSERVICE_KEY` | outbound (HTTP header) | same as above | yes — credential |\n| Processing result (JSON / files) | local only | stdout or temp dir | depends on content |\n| Conversation context, other local files | not transmitted | — | n/a |\n\nFull details: [references/privacy.md](references/privacy.md).\n\n## 2. Known risks (already disclosed)\n\n| Risk | Status | Mitigation |\n|---|---|---|\n| User images sent to third-party API | **disclosed**, required by skill purpose | User must opt in; data flow documented in SKILL.md & privacy.md |\n| API key stored via `yescan config` (`~/.yescan/config.json`) | **disclosed**, standard practice | Documented rotation procedure |\n| Output files written to system temp dir's `imgs/` and `documents/` subdirs (e.g. `/tmp/imgs/`, `/tmp/documents/`) and not auto-cleaned | **disclosed** | Users should manually clean temp directories when needed |\n| Network calls to `scan-business.quark.cn` | **disclosed** | Single, documented domain; no other external hosts |\n\nWe have **not** introduced any dangerous built-in functions on user input, hidden network endpoints, credential exfiltration, prompt injection, or obfuscated code.\n\n## 3. Reporting a vulnerability\n\nIf you find a security issue **in this skill** (not in the upstream Quark API):\n\n1. Do **not** open a public GitHub issue\n2. Email the maintainer at the address listed in `https://scan.quark.cn/business`\n3. Provide a minimal reproduction and the affected version\n\nWe aim to acknowledge within 5 business days.\n\n## 4. What this skill will never do\n\n- Read files outside the user-specified path\n- Access clipboard, browser cookies, or environment variables other than `SCAN_WEBSERVICE_KEY`\n- Send data to any host other than `scan-business.quark.cn`\n- Auto-retry failed requests (avoids quota leakage)\n- Modify files in place — output is always written to a fresh temp file\n- Reference previous conversation context for new intent recognition\n\nFile v1.1.3:skill-card.md\n\n## Description:\n\nQuark Scan image and document processing skill that helps agents use `yescan` for OCR, image translation and enhancement, conversion to Word/Excel/PDF, and ID photo generation from user-provided images or URLs.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[yescan-ai](https://clawhub.ai/user/yescan-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to process user-selected image or document inputs through Quark Scan for OCR extraction, image cleanup, document conversion, and generated ID photos. It is intended for cases where the user has explicitly provided a local image path or HTTP(S) URL.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Selected images or documents are sent to Quark Scan for processing and may contain sensitive or personal information.\n\nMitigation: Use the skill only when the user explicitly provides the image path or URL and accepts that the content will be processed by Quark Scan.\n\nRisk: The skill requires a `SCAN_WEBSERVICE_KEY` credential for Quark Scan API access.\n\nMitigation: Store the key only in a trusted account or environment, avoid exposing configuration files in screenshots or logs, and rotate the key if compromise is suspected.\n\nRisk: The workflow can install or upgrade the `yescan` CLI without a pinned package version.\n\nMitigation: Prefer an isolated virtual environment and pin or review the `yescan` version before use in sensitive environments.\n\nRisk: Generated image and document files may remain in temp directories after processing.\n\nMitigation: Clean local temp output directories such as `/tmp/imgs/` and `/tmp/documents/` after handling sensitive content.\n\n## Reference(s):\n\n- [Quark Scan Open Platform](https://scan.quark.cn/business)\n- [ClawHub Skill Page](https://clawhub.ai/yescan-ai/skills/alibaba-quark-scanking-all)\n- [Security Policy](artifact/SECURITY.md)\n- [Privacy, Data Flow, and Key Security](artifact/references/privacy.md)\n- [Implementation Details](artifact/references/implementation.md)\n- [Troubleshooting](artifact/references/troubleshooting.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance, Files]\n\n**Output Format:** [Markdown guidance with inline shell commands, JSON CLI responses, OCR text, and local output file paths]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires the `yescan` CLI, a configured `SCAN_WEBSERVICE_KEY`, runtime scene discovery, and user-provided image path or URL input; generated image and document outputs may be written to local temp directories or a caller-specified output directory.]\n\n## Skill Version(s):\n\n1.1.3 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.1: 9 files, 13321 bytes\n\nFiles: _meta.json (145b), README.en.md (2229b), README.md (2096b), references/implementation.md (2805b), references/privacy.md (2671b), references/troubleshooting.md (2153b), SECURITY.md (2315b), skill-card.md (2969b), SKILL.md (5483b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: yescan-universal\ndescription: 当用户需要对图片进行文字识别（OCR）、图片翻译、画质增强（去除水印/阴影/手写/底色/屏纹等瑕疵，矫正，高清增强，素描/线稿转换等）、格式转换（转 Word/Excel/PDF）或 AI 生成（证件照）时使用此技能。即使用户没有明确提到具体功能名称，只要涉及图片处理、文字提取、文档转换、图像优化或证件照生成，都应触发此技能。不适用于视频处理、纯文本编辑或非图片输入的任务。夸克扫描王图片处理能力中心。\nlicense: MIT\ncompatibility: Requires pip3 install yescan and SCAN_WEBSERVICE_KEY configuration. Performs network calls to scan-business.quark.cn.\nmetadata:\n  author: yescan-ai\n  version: \"1.0.5\"\n  homepage: https://scan.quark.cn/business\n---\n\n## 执行流程\n\n每次执行严格按 **Plan → Execute → Verify** 顺序进行，不得跳过或乱序。\n\n### Plan — 理解意图，发现能力\n\n1. 确认环境就绪（每次执行，不得跳过）：\n   - **安装 & 升级**：\n     1. `yescan --version` — 未安装则执行 `pip3 install yescan`；若版本 < 1.0.5，执行 `pip3 install yescan --upgrade`，升级完成后才继续\n     2. `pip3 index versions yescan` — 若 INSTALLED < LATEST，告知用户有新版本可用并提供升级命令：`pip3 install yescan --upgrade`，由用户决定是否升级\n   - **密钥检查**：`yescan config get SCAN_WEBSERVICE_KEY`，未配置则引导用户配置\n     - 设置命令：`yescan config set SCAN_WEBSERVICE_KEY <your_api_key>`\n     > Key 获取方式：https://scan.quark.cn/business → 开发者后台 → API Key\n\n   > **Checkpoint**：版本 < 1.0.5 → 必须升级后才能继续。版本 ≥ 1.0.5 但不是最新 → 提示用户后可继续。密钥未配置则引导配置后再继续。\n\n2. 发现能力：\n   ```bash\n   yescan --list-scenes              # 获取全部场景及意图描述\n   yescan --list-scenes <scene>      # 获取该场景的 --set 参数\n   ```\n   从输出中匹配用户意图到具体场景\n3. 多步处理时，向用户展示完整步骤计划\n\n**Gate**：\n- 「确认环境就绪」每一步均为硬性前置，不得跳过任何一步，未全部通过 → 禁止进入 Execute：\n  1. 未执行 `yescan --version` 确认安装状态 → 禁止继续\n  2. 版本 < 1.0.5 且未完成升级 → 禁止继续\n  3. 未执行 `pip3 index versions yescan` 确认最新版本状态 → 禁止继续\n  4. 未执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认密钥已配置 → 禁止继续\n- 只执行用户明确需要的场景，不主动添加额外步骤。为提升当前任务效果的辅助操作不受此限\n- 文档转换（Word/Excel/PDF）直接处理图片，不依赖 OCR 结果。两者输入都是图片，是独立操作\n- 场景名和 `--set` 参数必须来自本次会话的 CLI 输出\n- 未执行过 `--list-scenes` 则不得进入 Execute\n- 场景有 `--set` 参数且用户未明确指定时，须向用户展示可选参数并确认后再执行\n\n### Execute — 执行场景\n\n```bash\nyescan --scene <SCENE> --path <FILE> --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\nyescan --scene <SCENE> --url  <URL>  --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\n```\n> `--path` 传本地文件路径，`--url` 传 http/https 链接。\n\n> 把 `${AGENT_NAME}` 替换为当前 Agent 平台名称（如 openclaw、hermes、qoderWork、wukong、coze、claudecode 等），无法确定时填 `community`，禁止猜测或自造。\n\n- 单步：直接执行\n- 多步处理为逐步 Execute → Verify 循环：step N+1 的命令在 step N Verify 通过后才构造，`--path` 取自 step N 响应中的 `data.path`\n\n**Gate**：\n- 多步处理时向用户说明步骤计划\n- 每步命令不得预先构造\n- `--set` 参数不跨场景沿用\n\n### Verify — 验证并交付\n\n每步执行后检查响应中的 `code` 字段：\n\n- **成功**（`code` 为 `\"00000\"` 或 `0`）→ 进入交付\n- **失败** → 不继续下一步，根据错误信息处理（详见 Gate）\n\n交付标准 — 以下条件满足才算完成：\n\n- **OCR 识别**：识别内容已以可读文本呈现给用户\n- **图片翻译 / 图像增强 / AIGC**：输出文件路径已告知用户\n- **文档转换**：输出文档路径和格式已告知用户\n\n**Gate**：\n- code 非成功 → 不得继续下一步，不得报告成功\n- 根据错误信息自行修复（如场景名无效 → 重新 `--list-scenes`）或将错误原因告知用户\n- 用户未看到结果 → 未完成\n\n---\n\n## 约束\n\n- **输入方式**：`--path` 或 `--url`，二选一。不支持 base64（如需则先写入临时文件）\n- **URL 引号**：`--url` 参数须用单引号包裹，避免 shell 对 `!` `$` 等特殊字符的解析\n- **文件大小**：≤ 5MB\n- **图片来源**：仅限用户当次请求中明确指定的文件或 URL\n- **禁止伪造**：不得编造或模拟 yescan CLI 的请求参数或响应输出；所有场景名、参数值和执行结果必须来自实际运行的 CLI 命令\n\n---\n\n## 参考文档\n\n- [references/privacy.md](./references/privacy.md) — 隐私、数据流向与密钥安全\n- [references/troubleshooting.md](./references/troubleshooting.md) — 错误码与排错\n- [references/implementation.md](./references/implementation.md) — 实现细节：CLI 行为与响应字段\n- [SECURITY.md](./SECURITY.md) — 安全策略与数据流声明\n\nFile v1.1.1:README.md\n\n# yescan\n\n夸克扫描王一站式图片处理技能。支持 36 个场景，覆盖 OCR 识别、图像增强、文档转换、AIGC 生成四大能力。\n\n## 能力概览\n\n| 类别 | 场景数 | 典型用途 |\n|---|---|---|\n| OCR 识别 | 19 | 身份证、发票、表格、手写体、公式等文字提取 |\n| 图像增强 | 13 | 去水印、去阴影、去手写、矫正裁剪、画质增强等 |\n| 文档转换 | 3 | 图片转 Word / Excel / PDF |\n| AIGC 生成 | 1 | 证件照生成 |\n\n## 快速开始\n\n### 1. 安装\n\n```bash\npip3 install yescan\n```\n\n### 2. 配置 API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> 获取 API Key：https://scan.quark.cn/business → 开发者后台\n\n### 3. 使用\n\n```bash\n# 查看所有场景\nyescan --list-scenes\n\n# OCR 识别\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# 图像增强\nyescan --scene remove-watermark --path ./img.jpg\n\n# 文档转换\nyescan --scene image-to-excel --path ./table.jpg\n\n# 查看单个场景的参数\nyescan --list-scenes id-photo\n```\n\n## 设计理念\n\n- **CLI-first**：CLI 自解释，`--list-scenes` 输出包含意图描述和参数详情\n- **Agent-native**：SKILL.md 定义 PEV 协议（Plan → Execute → Verify）与约束，Agent 自主决策场景匹配\n- **动态发现**：所有场景和参数通过 CLI 动态查询，不硬编码\n\n## 文件结构\n\n```\nyescan-universal/\n├── SKILL.md                        ← Agent 技能契约（PEV 协议 + 约束）\n├── references/\n│   ├── privacy.md                  ← 隐私、数据流向与密钥安全\n│   ├── troubleshooting.md          ← 错误码与排错\n│   └── implementation.md           ← 实现细节：CLI 行为与响应字段\n├── SECURITY.md                     ← 安全策略\n├── README.md                       ← 本文档\n└── README.en.md                    ← English README\n```\n\n## 相关链接\n\n- [夸克扫描王开放平台](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent 技能契约\n- [SECURITY.md](SECURITY.md) — 安全策略\n\nFile v1.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn70q165k6hd6cpjtfp8enaa8s82vyem\",\n  \"slug\": \"alibaba-quark-scanking-all\",\n  \"version\": \"1.1.1\",\n  \"publishedAt\": 1783593562283\n}\n\nFile v1.1.1:references/implementation.md\n\n# 实现细节：CLI 行为与响应字段\n\n本文档描述 `yescan` CLI 的内部行为，供需要理解工作原理的开发者参考。\n\n---\n\n## 1. 执行流程\n\n```\n用户/Agent 调用\n  → yescan --scene <scene> --path/--url <input> [--output <dir>] [--set key=value]\n  → 加载凭证（SCAN_WEBSERVICE_KEY）\n  → 根据 scene_configs 构建请求参数\n  → POST https://scan-business.quark.cn/vision\n  → 解析响应 JSON\n  → 根据场景类型处理输出（stdout JSON / 落盘图片 / 落盘文档）\n```\n\n## 2. 响应结构\n\n### 成功响应（OCR 类场景）\n\n> **注意**：OCR 类场景的 `code` 为字符串 `\"00000\"`，而图像/文档类场景的 `code` 为数字 `0`，判断时需注意类型差异。\n\n```json\n{\n  \"code\": \"00000\",\n  \"message\": null,\n  \"data\": {\n    // 各场景返回不同字段，如：\n    // general-ocr: \"content\" (纯文本)\n    // table-ocr: \"tables\" (表格结构)\n    // idcard-ocr: \"name\", \"idNumber\", \"address\" 等\n  }\n}\n```\n\n### 图像/文档类输出（落盘后）\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"path\": \"/tmp/imgs/<Unix时间戳>_<16位随机十六进制串>.<扩展名>\"\n  }\n}\n```\n\n### 错误响应\n\n```json\n{\n  \"code\": \"A0100\",\n  \"message\": \"SCAN_WEBSERVICE_KEY 未配置...\",\n  \"data\": null\n}\n```\n\n## 3. 场景类型与输出行为\n\n| 场景类型 | 输出方式 | 输出位置 |\n|---|---|---|\n| OCR 识别 | JSON 打印到 stdout | 不落盘（除 pic-translate）；指定 `--output` 时保存 JSON 到指定目录 |\n| 图像增强 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n| 文档转换 | 文档落盘 | 系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 目录 |\n| AIGC 生成 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n\n## 4. 关键约定\n\n- OCR 场景直接返回 API 原始响应的 `data` 字段，不做二次加工。\n- **pic-translate 场景例外**：API 返回 `data.ImageInfo[0].ResImageBase64`，CLI 将其解码落盘并注入 `data.translated_image_path`，同时剔除 `ImageInfo` 字段避免 base64 噪音。\n- 图像/文档类输出的文件名格式：`<Unix时间戳>_<16位随机十六进制串>.<扩展名>`。\n- 多步 Pipeline 时，前一步的 `data.path` 作为下一步的 `--path` 输入。\n\n## 5. 错误码速查\n\n| 错误码 | 含义 | 常见原因 |\n|---|---|---|\n| A0100 | 凭证错误 | SCAN_WEBSERVICE_KEY 未配置或无效 |\n| A0201 | 缺少图片输入 | 未提供 --url 或 --path |\n| A0211 | 配额不足 | API 额度用尽，需充值 |\n| INVALID_SCENE | 场景名无效 | --scene 值不在可用场景列表中 |\n| FILE_ERROR | 文件校验失败 | 文件不存在、超过 5MB 或格式不支持 |\n\nFile v1.1.1:references/privacy.md\n\n# 隐私、数据流向与密钥安全\n\n本文档说明 `yescan` 技能在执行过程中涉及的全部数据流向、第三方服务交互范围，以及 API 密钥的配置、存储与轮换流程。\n\n---\n\n## 1. 数据流向（What leaves your machine）\n\n| 数据 | 是否外发 | 接收方 | 用途 |\n|---|---|---|---|\n| 用户提供的图片（URL / 本地文件） | 外发 | `https://scan-business.quark.cn`（夸克扫描王服务） | OCR / 增强 / 转换 / AIGC |\n| `SCAN_WEBSERVICE_KEY` | 随请求头发送 | 同上 | API 鉴权 |\n| 处理结果（JSON / 文件） | 不外发 | 仅返回给调用方 | CLI 输出到 stdout 或本地文件 |\n| 用户提示词、对话上下文 | 不外发 | — | 仅在本地 Agent 处理 |\n\n> **服务端处理说明**：夸克扫描王服务将获取并处理该图片内容，服务端不会永久保存。\n\n## 2. 本地文件行为\n\n- **OCR 场景**：不写入输出文件（结果以 JSON 打印到 stdout），`pic-translate` 场景例外（保存译图到临时目录）\n- **图像增强场景**：输出增强后图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- **文档转换场景**：输出文档文件到系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 指定目录\n- **AIGC 场景**：输出生成图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- 唯一的文件读取操作是用户指定的本地图片路径（`--path` 参数）\n\n## 3. API 密钥配置\n\n### 3.1 推荐方式：通过 CLI 配置（永久生效）\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key_here>\n```\n\n配置保存在 `~/.yescan/config.json`。\n\n### 3.2 备选方式：环境变量（仅当前会话）\n\n```bash\nexport SCAN_WEBSERVICE_KEY=<your_api_key_here>\n```\n\n> 优先级：CLI config（`~/.yescan/config.json`）> 环境变量\n\n## 4. 获取与轮换密钥\n\n1. 访问 `https://scan.quark.cn/business`（**仅此一个有效官方入口**）\n2. 进入开发者后台 → 登录/注册账号 → 创建应用 → 查看 API Key\n3. 如怀疑密钥泄露：在同一后台立即 *轮换* 或 *撤销* 旧密钥，并更新配置\n\n## 5. 安全实践清单\n\n- [x] 不要在公网截图/录屏中暴露 key 或配置文件内容\n- [x] 仅对用户主动指定的图片进行处理，不要遍历整个目录\n- [x] 处理涉密 / PII 图片前，用户应自行评估数据外发的合规性\n\n## 6. 适用范围\n\n本技能图片来源 **仅限用户在当次请求中明确指定** 的图片文件或 URL。技能不会主动扫描磁盘、访问剪贴板或读取额外文件。\n\nFile v1.1.1:references/troubleshooting.md\n\n# 错误码与排错\n\nyescan CLI 输出 JSON 响应，以下是常见错误码及对应排查步骤。\n\n---\n\n## 错误码一览\n\n| 错误码 | 含义 | 排查步骤 |\n|---|---|---|\n| A0100 | 凭证无效 | 1. 执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认已配置<br>2. 确认 key 无前后空格或引号问题<br>3. 访问 scan.quark.cn/business 确认 key 未过期 |\n| A0211 | 配额不足 | 访问 scan.quark.cn/business 开发者后台充值 |\n| INVALID_SCENE | 场景名无效 | 执行 `yescan --list-scenes` 查看所有可用场景名 |\n| INVALID_INPUT | 输入参数冲突 | `--url` 和 `--path` 只能提供一个 |\n| FILE_ERROR | 文件验证失败 | 确认文件存在、大小 ≤5MB、扩展名在支持列表中 |\n| URL_VALIDATION_ERROR | URL 格式无效 | 确认 URL 以 http:// 或 https:// 开头 |\n| HTTP_ERROR | 网络请求失败 | 检查网络连接，确认能访问 scan-business.quark.cn |\n\n## 常见问题\n\n### Q: yescan 命令不存在\n\n1. 确认已安装：`pip3 install yescan --upgrade`\n2. 若已安装仍找不到，说明 pip3 scripts 目录不在 PATH 中，执行 `python3 -m site --user-base` 查看安装路径，将其下的 `bin/`（macOS/Linux）或 `Scripts/`（Windows）加入 PATH\n3. 验证：`yescan --version`\n\n### Q: 提示凭证无效\n\n1. 执行 `yescan config get SCAN_WEBSERVICE_KEY` 查看当前配置\n2. 如果为空，执行 `yescan config set SCAN_WEBSERVICE_KEY <your_key>` 配置\n3. 访问 https://scan.quark.cn/business 确认 key 有效\n\n### Q: 执行后无任何输出\n\n确认 yescan 版本 ≥ 1.0.5：`yescan --version`。\n\n### Q: 识别结果为空或不准确\n\n- 确认图片清晰度足够\n- 确认选择了正确的 scene（如表格用 `table-ocr`，手写用 `handwritten-ocr`）\n- 图片分辨率过低时，可先使用 `image-hd-enhance` 增强再识别\n\n### Q: CLI 不支持 --base64 参数\n\nyescan CLI **不支持 `--base64` 输入**。如果图片是 base64 格式，请先写入临时文件再用 `--path` 传入。\n\n### Q: Pipeline 执行中某步失败\n\nPipeline 采用\"失败即停\"策略。排查失败步骤的错误码，修复后可从失败步骤重新执行。\n\nFile v1.1.1:README.en.md\n\n# yescan\n\nAll-in-one image processing skill powered by Quark Scan. Supports 36 scenes across OCR, image enhancement, document conversion, and AIGC generation.\n\n## Capabilities\n\n| Category | Scenes | Typical Use Cases |\n|---|---|---|\n| OCR | 19 | ID card, invoice, table, handwriting, formula, etc. |\n| Image Enhancement | 13 | Remove watermark / shadow / handwriting, crop & rectify, HD enhance, etc. |\n| Document Conversion | 3 | Image to Word / Excel / PDF |\n| AIGC Generation | 1 | ID photo generation |\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip3 install yescan\n```\n\n### 2. Configure API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> Apply for an API Key at the [Quark Scan Developer Console](https://scan.quark.cn/business).\n\n### 3. Usage\n\n```bash\n# List all scenes\nyescan --list-scenes\n\n# OCR\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# Image enhancement\nyescan --scene remove-watermark --path ./img.jpg\n\n# Document conversion\nyescan --scene image-to-excel --path ./table.jpg\n\n# View scene parameters\nyescan --list-scenes id-photo\n```\n\n## Design Philosophy\n\n- **CLI-first**: CLI is self-describing — `--list-scenes` output includes intent descriptions and parameter details\n- **Agent-native**: SKILL.md defines the PEV protocol (Plan → Execute → Verify) and constraints; Agent autonomously matches scenes\n- **Dynamic discovery**: All scenes and parameters are queried via CLI at runtime, never hardcoded\n\n## File Structure\n\n```\nyescan-universal/\n├── SKILL.md                        ← Agent skill contract (PEV protocol + constraints)\n├── references/\n│   ├── privacy.md                  ← Privacy, data flow & key security\n│   ├── troubleshooting.md          ← Error codes & troubleshooting\n│   └── implementation.md           ← Implementation details: CLI behavior & response fields\n├── SECURITY.md                     ← Security policy\n├── README.md                       ← This document\n└── README.en.md                    ← English README\n```\n\n## Links\n\n- [Quark Scan Open Platform](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent skill contract\n- [SECURITY.md](SECURITY.md) — Security policy\n\nFile v1.1.1:SECURITY.md\n\n# Security Policy\n\nThis skill performs network calls via the `yescan` CLI. We disclose the full data flow upfront so that auditors and users can make informed decisions.\n\n## 1. Data flow at a glance\n\n| Item | Direction | Destination | Sensitive? |\n|---|---|---|---|\n| User-supplied image | **outbound** | `https://scan-business.quark.cn` | depends on content |\n| `SCAN_WEBSERVICE_KEY` | outbound (HTTP header) | same as above | yes — credential |\n| Processing result (JSON / files) | local only | stdout or temp dir | depends on content |\n| Conversation context, other local files | not transmitted | — | n/a |\n\nFull details: [references/privacy.md](references/privacy.md).\n\n## 2. Known risks (already disclosed)\n\n| Risk | Status | Mitigation |\n|---|---|---|\n| User images sent to third-party API | **disclosed**, required by skill purpose | User must opt in; data flow documented in SKILL.md & privacy.md |\n| API key stored via `yescan config` (`~/.yescan/config.json`) | **disclosed**, standard practice | Documented rotation procedure |\n| Output files written to system temp dir's `imgs/` and `documents/` subdirs (e.g. `/tmp/imgs/`, `/tmp/documents/`) and not auto-cleaned | **disclosed** | Users should manually clean temp directories when needed |\n| Network calls to `scan-business.quark.cn` | **disclosed** | Single, documented domain; no other external hosts |\n\nWe have **not** introduced any dangerous built-in functions on user input, hidden network endpoints, credential exfiltration, prompt injection, or obfuscated code.\n\n## 3. Reporting a vulnerability\n\nIf you find a security issue **in this skill** (not in the upstream Quark API):\n\n1. Do **not** open a public GitHub issue\n2. Email the maintainer at the address listed in `https://scan.quark.cn/business`\n3. Provide a minimal reproduction and the affected version\n\nWe aim to acknowledge within 5 business days.\n\n## 4. What this skill will never do\n\n- Read files outside the user-specified path\n- Access clipboard, browser cookies, or environment variables other than `SCAN_WEBSERVICE_KEY`\n- Send data to any host other than `scan-business.quark.cn`\n- Auto-retry failed requests (avoids quota leakage)\n- Modify files in place — output is always written to a fresh temp file\n- Reference previous conversation context for new intent recognition\n\nFile v1.1.1:skill-card.md\n\n## Description: <br>\nQuark Scan image and document processing skill for OCR, image translation, image enhancement, image-to-Word/Excel/PDF conversion, and ID photo generation from user-selected images or URLs. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[yescan-ai](https://clawhub.ai/user/yescan-ai) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to route image-based OCR, cleanup, translation, document conversion, and ID-photo tasks through the yescan CLI and Quark Scan service. It is intended for user-selected images or image URLs, not video, pure text editing, or unsolicited local file scanning. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: User-selected images or document photos are sent to Quark Scan's external service for processing. <br>\nMitigation: Use the skill only with images the user explicitly provides, and avoid regulated or confidential documents unless the user's policy permits this data flow. <br>\nRisk: The SCAN_WEBSERVICE_KEY credential is required for service access. <br>\nMitigation: Configure the key through the documented yescan mechanism, avoid exposing it in logs or screenshots, and rotate or revoke it if compromise is suspected. <br>\nRisk: Generated images, converted documents, or OCR outputs may contain sensitive content and can remain in local temp or output directories. <br>\nMitigation: Tell users where output files were written and clean up temp or output directories when sensitive results are no longer needed. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/yescan-ai/skills/alibaba-quark-scanking-all) <br>\n- [Publisher Profile](https://clawhub.ai/user/yescan-ai) <br>\n- [Quark Scan Open Platform](https://scan.quark.cn/business) <br>\n- [Security Policy](SECURITY.md) <br>\n- [Privacy and Data Flow](references/privacy.md) <br>\n- [Implementation Details](references/implementation.md) <br>\n- [Troubleshooting](references/troubleshooting.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files] <br>\n**Output Format:** [Markdown guidance with inline shell commands; OCR results may be presented as readable text or JSON, and enhancement, conversion, translation, or AIGC scenes produce local output file paths.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires yescan CLI setup, SCAN_WEBSERVICE_KEY configuration, runtime scene discovery, and a user-selected image path or URL.] <br>\n\n## Skill Version(s): <br>\n1.1.1 (source: evidence.release.version) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.0.1: 9 files, 13427 bytes\n\nFiles: _meta.json (145b), README.en.md (2229b), README.md (2096b), references/implementation.md (2805b), references/privacy.md (2671b), references/troubleshooting.md (2153b), SECURITY.md (2315b), skill-card.md (3174b), SKILL.md (5483b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: yescan-universal\ndescription: 当用户需要对图片进行文字识别（OCR）、图片翻译、画质增强（去除水印/阴影/手写/底色/屏纹等瑕疵，矫正，高清增强，素描/线稿转换等）、格式转换（转 Word/Excel/PDF）或 AI 生成（证件照）时使用此技能。即使用户没有明确提到具体功能名称，只要涉及图片处理、文字提取、文档转换、图像优化或证件照生成，都应触发此技能。不适用于视频处理、纯文本编辑或非图片输入的任务。夸克扫描王图片处理能力中心。\nlicense: MIT\ncompatibility: Requires pip3 install yescan and SCAN_WEBSERVICE_KEY configuration. Performs network calls to scan-business.quark.cn.\nmetadata:\n  author: yescan-ai\n  version: \"1.0.5\"\n  homepage: https://scan.quark.cn/business\n---\n\n## 执行流程\n\n每次执行严格按 **Plan → Execute → Verify** 顺序进行，不得跳过或乱序。\n\n### Plan — 理解意图，发现能力\n\n1. 确认环境就绪（每次执行，不得跳过）：\n   - **安装 & 升级**：\n     1. `yescan --version` — 未安装则执行 `pip3 install yescan`；若版本 < 1.0.5，执行 `pip3 install yescan --upgrade`，升级完成后才继续\n     2. `pip3 index versions yescan` — 若 INSTALLED < LATEST，告知用户有新版本可用并提供升级命令：`pip3 install yescan --upgrade`，由用户决定是否升级\n   - **密钥检查**：`yescan config get SCAN_WEBSERVICE_KEY`，未配置则引导用户配置\n     - 设置命令：`yescan config set SCAN_WEBSERVICE_KEY <your_api_key>`\n     > Key 获取方式：https://scan.quark.cn/business → 开发者后台 → API Key\n\n   > **Checkpoint**：版本 < 1.0.5 → 必须升级后才能继续。版本 ≥ 1.0.5 但不是最新 → 提示用户后可继续。密钥未配置则引导配置后再继续。\n\n2. 发现能力：\n   ```bash\n   yescan --list-scenes              # 获取全部场景及意图描述\n   yescan --list-scenes <scene>      # 获取该场景的 --set 参数\n   ```\n   从输出中匹配用户意图到具体场景\n3. 多步处理时，向用户展示完整步骤计划\n\n**Gate**：\n- 「确认环境就绪」每一步均为硬性前置，不得跳过任何一步，未全部通过 → 禁止进入 Execute：\n  1. 未执行 `yescan --version` 确认安装状态 → 禁止继续\n  2. 版本 < 1.0.5 且未完成升级 → 禁止继续\n  3. 未执行 `pip3 index versions yescan` 确认最新版本状态 → 禁止继续\n  4. 未执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认密钥已配置 → 禁止继续\n- 只执行用户明确需要的场景，不主动添加额外步骤。为提升当前任务效果的辅助操作不受此限\n- 文档转换（Word/Excel/PDF）直接处理图片，不依赖 OCR 结果。两者输入都是图片，是独立操作\n- 场景名和 `--set` 参数必须来自本次会话的 CLI 输出\n- 未执行过 `--list-scenes` 则不得进入 Execute\n- 场景有 `--set` 参数且用户未明确指定时，须向用户展示可选参数并确认后再执行\n\n### Execute — 执行场景\n\n```bash\nyescan --scene <SCENE> --path <FILE> --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\nyescan --scene <SCENE> --url  <URL>  --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\n```\n> `--path` 传本地文件路径，`--url` 传 http/https 链接。\n\n> 把 `${AGENT_NAME}` 替换为当前 Agent 平台名称（如 openclaw、hermes、qoderWork、wukong、coze、claudecode 等），无法确定时填 `community`，禁止猜测或自造。\n\n- 单步：直接执行\n- 多步处理为逐步 Execute → Verify 循环：step N+1 的命令在 step N Verify 通过后才构造，`--path` 取自 step N 响应中的 `data.path`\n\n**Gate**：\n- 多步处理时向用户说明步骤计划\n- 每步命令不得预先构造\n- `--set` 参数不跨场景沿用\n\n### Verify — 验证并交付\n\n每步执行后检查响应中的 `code` 字段：\n\n- **成功**（`code` 为 `\"00000\"` 或 `0`）→ 进入交付\n- **失败** → 不继续下一步，根据错误信息处理（详见 Gate）\n\n交付标准 — 以下条件满足才算完成：\n\n- **OCR 识别**：识别内容已以可读文本呈现给用户\n- **图片翻译 / 图像增强 / AIGC**：输出文件路径已告知用户\n- **文档转换**：输出文档路径和格式已告知用户\n\n**Gate**：\n- code 非成功 → 不得继续下一步，不得报告成功\n- 根据错误信息自行修复（如场景名无效 → 重新 `--list-scenes`）或将错误原因告知用户\n- 用户未看到结果 → 未完成\n\n---\n\n## 约束\n\n- **输入方式**：`--path` 或 `--url`，二选一。不支持 base64（如需则先写入临时文件）\n- **URL 引号**：`--url` 参数须用单引号包裹，避免 shell 对 `!` `$` 等特殊字符的解析\n- **文件大小**：≤ 5MB\n- **图片来源**：仅限用户当次请求中明确指定的文件或 URL\n- **禁止伪造**：不得编造或模拟 yescan CLI 的请求参数或响应输出；所有场景名、参数值和执行结果必须来自实际运行的 CLI 命令\n\n---\n\n## 参考文档\n\n- [references/privacy.md](./references/privacy.md) — 隐私、数据流向与密钥安全\n- [references/troubleshooting.md](./references/troubleshooting.md) — 错误码与排错\n- [references/implementation.md](./references/implementation.md) — 实现细节：CLI 行为与响应字段\n- [SECURITY.md](./SECURITY.md) — 安全策略与数据流声明\n\nFile v1.0.1:README.md\n\n# yescan\n\n夸克扫描王一站式图片处理技能。支持 36 个场景，覆盖 OCR 识别、图像增强、文档转换、AIGC 生成四大能力。\n\n## 能力概览\n\n| 类别 | 场景数 | 典型用途 |\n|---|---|---|\n| OCR 识别 | 19 | 身份证、发票、表格、手写体、公式等文字提取 |\n| 图像增强 | 13 | 去水印、去阴影、去手写、矫正裁剪、画质增强等 |\n| 文档转换 | 3 | 图片转 Word / Excel / PDF |\n| AIGC 生成 | 1 | 证件照生成 |\n\n## 快速开始\n\n### 1. 安装\n\n```bash\npip3 install yescan\n```\n\n### 2. 配置 API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> 获取 API Key：https://scan.quark.cn/business → 开发者后台\n\n### 3. 使用\n\n```bash\n# 查看所有场景\nyescan --list-scenes\n\n# OCR 识别\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# 图像增强\nyescan --scene remove-watermark --path ./img.jpg\n\n# 文档转换\nyescan --scene image-to-excel --path ./table.jpg\n\n# 查看单个场景的参数\nyescan --list-scenes id-photo\n```\n\n## 设计理念\n\n- **CLI-first**：CLI 自解释，`--list-scenes` 输出包含意图描述和参数详情\n- **Agent-native**：SKILL.md 定义 PEV 协议（Plan → Execute → Verify）与约束，Agent 自主决策场景匹配\n- **动态发现**：所有场景和参数通过 CLI 动态查询，不硬编码\n\n## 文件结构\n\n```\nyescan-universal/\n├── SKILL.md                        ← Agent 技能契约（PEV 协议 + 约束）\n├── references/\n│   ├── privacy.md                  ← 隐私、数据流向与密钥安全\n│   ├── troubleshooting.md          ← 错误码与排错\n│   └── implementation.md           ← 实现细节：CLI 行为与响应字段\n├── SECURITY.md                     ← 安全策略\n├── README.md                       ← 本文档\n└── README.en.md                    ← English README\n```\n\n## 相关链接\n\n- [夸克扫描王开放平台](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent 技能契约\n- [SECURITY.md](SECURITY.md) — 安全策略\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn70q165k6hd6cpjtfp8enaa8s82vyem\",\n  \"slug\": \"alibaba-quark-scanking-all\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1783593151118\n}\n\nFile v1.0.1:references/implementation.md\n\n# 实现细节：CLI 行为与响应字段\n\n本文档描述 `yescan` CLI 的内部行为，供需要理解工作原理的开发者参考。\n\n---\n\n## 1. 执行流程\n\n```\n用户/Agent 调用\n  → yescan --scene <scene> --path/--url <input> [--output <dir>] [--set key=value]\n  → 加载凭证（SCAN_WEBSERVICE_KEY）\n  → 根据 scene_configs 构建请求参数\n  → POST https://scan-business.quark.cn/vision\n  → 解析响应 JSON\n  → 根据场景类型处理输出（stdout JSON / 落盘图片 / 落盘文档）\n```\n\n## 2. 响应结构\n\n### 成功响应（OCR 类场景）\n\n> **注意**：OCR 类场景的 `code` 为字符串 `\"00000\"`，而图像/文档类场景的 `code` 为数字 `0`，判断时需注意类型差异。\n\n```json\n{\n  \"code\": \"00000\",\n  \"message\": null,\n  \"data\": {\n    // 各场景返回不同字段，如：\n    // general-ocr: \"content\" (纯文本)\n    // table-ocr: \"tables\" (表格结构)\n    // idcard-ocr: \"name\", \"idNumber\", \"address\" 等\n  }\n}\n```\n\n### 图像/文档类输出（落盘后）\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"path\": \"/tmp/imgs/<Unix时间戳>_<16位随机十六进制串>.<扩展名>\"\n  }\n}\n```\n\n### 错误响应\n\n```json\n{\n  \"code\": \"A0100\",\n  \"message\": \"SCAN_WEBSERVICE_KEY 未配置...\",\n  \"data\": null\n}\n```\n\n## 3. 场景类型与输出行为\n\n| 场景类型 | 输出方式 | 输出位置 |\n|---|---|---|\n| OCR 识别 | JSON 打印到 stdout | 不落盘（除 pic-translate）；指定 `--output` 时保存 JSON 到指定目录 |\n| 图像增强 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n| 文档转换 | 文档落盘 | 系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 目录 |\n| AIGC 生成 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n\n## 4. 关键约定\n\n- OCR 场景直接返回 API 原始响应的 `data` 字段，不做二次加工。\n- **pic-translate 场景例外**：API 返回 `data.ImageInfo[0].ResImageBase64`，CLI 将其解码落盘并注入 `data.translated_image_path`，同时剔除 `ImageInfo` 字段避免 base64 噪音。\n- 图像/文档类输出的文件名格式：`<Unix时间戳>_<16位随机十六进制串>.<扩展名>`。\n- 多步 Pipeline 时，前一步的 `data.path` 作为下一步的 `--path` 输入。\n\n## 5. 错误码速查\n\n| 错误码 | 含义 | 常见原因 |\n|---|---|---|\n| A0100 | 凭证错误 | SCAN_WEBSERVICE_KEY 未配置或无效 |\n| A0201 | 缺少图片输入 | 未提供 --url 或 --path |\n| A0211 | 配额不足 | API 额度用尽，需充值 |\n| INVALID_SCENE | 场景名无效 | --scene 值不在可用场景列表中 |\n| FILE_ERROR | 文件校验失败 | 文件不存在、超过 5MB 或格式不支持 |\n\nFile v1.0.1:references/privacy.md\n\n# 隐私、数据流向与密钥安全\n\n本文档说明 `yescan` 技能在执行过程中涉及的全部数据流向、第三方服务交互范围，以及 API 密钥的配置、存储与轮换流程。\n\n---\n\n## 1. 数据流向（What leaves your machine）\n\n| 数据 | 是否外发 | 接收方 | 用途 |\n|---|---|---|---|\n| 用户提供的图片（URL / 本地文件） | 外发 | `https://scan-business.quark.cn`（夸克扫描王服务） | OCR / 增强 / 转换 / AIGC |\n| `SCAN_WEBSERVICE_KEY` | 随请求头发送 | 同上 | API 鉴权 |\n| 处理结果（JSON / 文件） | 不外发 | 仅返回给调用方 | CLI 输出到 stdout 或本地文件 |\n| 用户提示词、对话上下文 | 不外发 | — | 仅在本地 Agent 处理 |\n\n> **服务端处理说明**：夸克扫描王服务将获取并处理该图片内容，服务端不会永久保存。\n\n## 2. 本地文件行为\n\n- **OCR 场景**：不写入输出文件（结果以 JSON 打印到 stdout），`pic-translate` 场景例外（保存译图到临时目录）\n- **图像增强场景**：输出增强后图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- **文档转换场景**：输出文档文件到系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 指定目录\n- **AIGC 场景**：输出生成图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- 唯一的文件读取操作是用户指定的本地图片路径（`--path` 参数）\n\n## 3. API 密钥配置\n\n### 3.1 推荐方式：通过 CLI 配置（永久生效）\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key_here>\n```\n\n配置保存在 `~/.yescan/config.json`。\n\n### 3.2 备选方式：环境变量（仅当前会话）\n\n```bash\nexport SCAN_WEBSERVICE_KEY=<your_api_key_here>\n```\n\n> 优先级：CLI config（`~/.yescan/config.json`）> 环境变量\n\n## 4. 获取与轮换密钥\n\n1. 访问 `https://scan.quark.cn/business`（**仅此一个有效官方入口**）\n2. 进入开发者后台 → 登录/注册账号 → 创建应用 → 查看 API Key\n3. 如怀疑密钥泄露：在同一后台立即 *轮换* 或 *撤销* 旧密钥，并更新配置\n\n## 5. 安全实践清单\n\n- [x] 不要在公网截图/录屏中暴露 key 或配置文件内容\n- [x] 仅对用户主动指定的图片进行处理，不要遍历整个目录\n- [x] 处理涉密 / PII 图片前，用户应自行评估数据外发的合规性\n\n## 6. 适用范围\n\n本技能图片来源 **仅限用户在当次请求中明确指定** 的图片文件或 URL。技能不会主动扫描磁盘、访问剪贴板或读取额外文件。\n\nFile v1.0.1:references/troubleshooting.md\n\n# 错误码与排错\n\nyescan CLI 输出 JSON 响应，以下是常见错误码及对应排查步骤。\n\n---\n\n## 错误码一览\n\n| 错误码 | 含义 | 排查步骤 |\n|---|---|---|\n| A0100 | 凭证无效 | 1. 执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认已配置<br>2. 确认 key 无前后空格或引号问题<br>3. 访问 scan.quark.cn/business 确认 key 未过期 |\n| A0211 | 配额不足 | 访问 scan.quark.cn/business 开发者后台充值 |\n| INVALID_SCENE | 场景名无效 | 执行 `yescan --list-scenes` 查看所有可用场景名 |\n| INVALID_INPUT | 输入参数冲突 | `--url` 和 `--path` 只能提供一个 |\n| FILE_ERROR | 文件验证失败 | 确认文件存在、大小 ≤5MB、扩展名在支持列表中 |\n| URL_VALIDATION_ERROR | URL 格式无效 | 确认 URL 以 http:// 或 https:// 开头 |\n| HTTP_ERROR | 网络请求失败 | 检查网络连接，确认能访问 scan-business.quark.cn |\n\n## 常见问题\n\n### Q: yescan 命令不存在\n\n1. 确认已安装：`pip3 install yescan --upgrade`\n2. 若已安装仍找不到，说明 pip3 scripts 目录不在 PATH 中，执行 `python3 -m site --user-base` 查看安装路径，将其下的 `bin/`（macOS/Linux）或 `Scripts/`（Windows）加入 PATH\n3. 验证：`yescan --version`\n\n### Q: 提示凭证无效\n\n1. 执行 `yescan config get SCAN_WEBSERVICE_KEY` 查看当前配置\n2. 如果为空，执行 `yescan config set SCAN_WEBSERVICE_KEY <your_key>` 配置\n3. 访问 https://scan.quark.cn/business 确认 key 有效\n\n### Q: 执行后无任何输出\n\n确认 yescan 版本 ≥ 1.0.5：`yescan --version`。\n\n### Q: 识别结果为空或不准确\n\n- 确认图片清晰度足够\n- 确认选择了正确的 scene（如表格用 `table-ocr`，手写用 `handwritten-ocr`）\n- 图片分辨率过低时，可先使用 `image-hd-enhance` 增强再识别\n\n### Q: CLI 不支持 --base64 参数\n\nyescan CLI **不支持 `--base64` 输入**。如果图片是 base64 格式，请先写入临时文件再用 `--path` 传入。\n\n### Q: Pipeline 执行中某步失败\n\nPipeline 采用\"失败即停\"策略。排查失败步骤的错误码，修复后可从失败步骤重新执行。\n\nFile v1.0.1:README.en.md\n\n# yescan\n\nAll-in-one image processing skill powered by Quark Scan. Supports 36 scenes across OCR, image enhancement, document conversion, and AIGC generation.\n\n## Capabilities\n\n| Category | Scenes | Typical Use Cases |\n|---|---|---|\n| OCR | 19 | ID card, invoice, table, handwriting, formula, etc. |\n| Image Enhancement | 13 | Remove watermark / shadow / handwriting, crop & rectify, HD enhance, etc. |\n| Document Conversion | 3 | Image to Word / Excel / PDF |\n| AIGC Generation | 1 | ID photo generation |\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip3 install yescan\n```\n\n### 2. Configure API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> Apply for an API Key at the [Quark Scan Developer Console](https://scan.quark.cn/business).\n\n### 3. Usage\n\n```bash\n# List all scenes\nyescan --list-scenes\n\n# OCR\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# Image enhancement\nyescan --scene remove-watermark --path ./img.jpg\n\n# Document conversion\nyescan --scene image-to-excel --path ./table.jpg\n\n# View scene parameters\nyescan --list-scenes id-photo\n```\n\n## Design Philosophy\n\n- **CLI-first**: CLI is self-describing — `--list-scenes` output includes intent descriptions and parameter details\n- **Agent-native**: SKILL.md defines the PEV protocol (Plan → Execute → Verify) and constraints; Agent autonomously matches scenes\n- **Dynamic discovery**: All scenes and parameters are queried via CLI at runtime, never hardcoded\n\n## File Structure\n\n```\nyescan-universal/\n├── SKILL.md                        ← Agent skill contract (PEV protocol + constraints)\n├── references/\n│   ├── privacy.md                  ← Privacy, data flow & key security\n│   ├── troubleshooting.md          ← Error codes & troubleshooting\n│   └── implementation.md           ← Implementation details: CLI behavior & response fields\n├── SECURITY.md                     ← Security policy\n├── README.md                       ← This document\n└── README.en.md                    ← English README\n```\n\n## Links\n\n- [Quark Scan Open Platform](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent skill contract\n- [SECURITY.md](SECURITY.md) — Security policy\n\nFile v1.0.1:SECURITY.md\n\n# Security Policy\n\nThis skill performs network calls via the `yescan` CLI. We disclose the full data flow upfront so that auditors and users can make informed decisions.\n\n## 1. Data flow at a glance\n\n| Item | Direction | Destination | Sensitive? |\n|---|---|---|---|\n| User-supplied image | **outbound** | `https://scan-business.quark.cn` | depends on content |\n| `SCAN_WEBSERVICE_KEY` | outbound (HTTP header) | same as above | yes — credential |\n| Processing result (JSON / files) | local only | stdout or temp dir | depends on content |\n| Conversation context, other local files | not transmitted | — | n/a |\n\nFull details: [references/privacy.md](references/privacy.md).\n\n## 2. Known risks (already disclosed)\n\n| Risk | Status | Mitigation |\n|---|---|---|\n| User images sent to third-party API | **disclosed**, required by skill purpose | User must opt in; data flow documented in SKILL.md & privacy.md |\n| API key stored via `yescan config` (`~/.yescan/config.json`) | **disclosed**, standard practice | Documented rotation procedure |\n| Output files written to system temp dir's `imgs/` and `documents/` subdirs (e.g. `/tmp/imgs/`, `/tmp/documents/`) and not auto-cleaned | **disclosed** | Users should manually clean temp directories when needed |\n| Network calls to `scan-business.quark.cn` | **disclosed** | Single, documented domain; no other external hosts |\n\nWe have **not** introduced any dangerous built-in functions on user input, hidden network endpoints, credential exfiltration, prompt injection, or obfuscated code.\n\n## 3. Reporting a vulnerability\n\nIf you find a security issue **in this skill** (not in the upstream Quark API):\n\n1. Do **not** open a public GitHub issue\n2. Email the maintainer at the address listed in `https://scan.quark.cn/business`\n3. Provide a minimal reproduction and the affected version\n\nWe aim to acknowledge within 5 business days.\n\n## 4. What this skill will never do\n\n- Read files outside the user-specified path\n- Access clipboard, browser cookies, or environment variables other than `SCAN_WEBSERVICE_KEY`\n- Send data to any host other than `scan-business.quark.cn`\n- Auto-retry failed requests (avoids quota leakage)\n- Modify files in place — output is always written to a fresh temp file\n- Reference previous conversation context for new intent recognition\n\nFile v1.0.1:skill-card.md\n\n## Description: <br>\nThis skill helps agents use Quark Scan through the yescan CLI for OCR, image translation, image enhancement, document conversion to Word, Excel, or PDF, and ID photo generation from user-specified images. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[yescan-ai](https://clawhub.ai/user/yescan-ai) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users, developers, and agent operators use this skill when they need to extract text from images, clean or enhance scanned images, translate image content, convert image-based documents, or generate ID photos through Quark Scan. It is intended for user-selected local image files or image URLs, not video or pure text editing tasks. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Selected images or document scans may contain IDs, invoices, or other sensitive content and are sent to Quark Scan for processing. <br>\nMitigation: Use the skill only for user-selected inputs after confirming the user is comfortable with external processing and any applicable data handling requirements. <br>\nRisk: The SCAN_WEBSERVICE_KEY is a credential used by the Quark Scan service. <br>\nMitigation: Configure it through the documented yescan configuration flow, avoid exposing it in screenshots or logs, and rotate or revoke it if disclosure is suspected. <br>\nRisk: Generated images and converted documents may be written to local temporary output directories and are not automatically cleaned up. <br>\nMitigation: Review output paths after execution and remove temporary files when processing sensitive documents. <br>\nRisk: Network access to scan-business.quark.cn and valid Quark Scan quota are required for successful execution. <br>\nMitigation: Check connectivity, API key status, and quota before relying on the skill for time-sensitive workflows. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/yescan-ai/skills/alibaba-quark-scanking-all) <br>\n- [Quark Scan Open Platform](https://scan.quark.cn/business) <br>\n- [Security Policy](SECURITY.md) <br>\n- [Privacy and Data Flow](references/privacy.md) <br>\n- [Implementation Details](references/implementation.md) <br>\n- [Troubleshooting](references/troubleshooting.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance, files] <br>\n**Output Format:** [Markdown guidance with shell commands, JSON responses, OCR text, and local output file paths] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Outputs depend on the selected yescan scene; OCR normally returns JSON or readable text, while enhancement, conversion, translation, and AIGC scenes return generated local file paths.] <br>\n\n## Skill Version(s): <br>\n1.0.1 (source: ClawHub release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>","readmeExcerpt":"Skill: 夸克扫描王-OCR 文字识别/文件扫描/转 Office Alibaba-Quark-Scanking-All Owner: yescan-ai Summary: 夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描/线稿）、图片转 Word/Excel/PDF、AI 证件照生成。 Tags: latest:1.1.3 Version history: v1.1.3 | 2026-07-09T11:07:39.287Z | auto - Skill renamed from yescan-universal to alibaba-quark-scank","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"yescan --list-scenes              # 获取全部场景及意图描述\n   yescan --list-scenes <scene>      # 获取该场景的 --set 参数"},{"language":"bash","snippet":"yescan --scene <SCENE> --path <FILE> --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\nyescan --scene <SCENE> --url  <URL>  --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]"},{"language":"bash","snippet":"pip3 install yescan"},{"language":"bash","snippet":"yescan config set SCAN_WEBSERVICE_KEY <your_api_key>"},{"language":"bash","snippet":"# 查看所有场景\nyescan --list-scenes\n\n# OCR 识别\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# 图像增强\nyescan --scene remove-watermark --path ./img.jpg\n\n# 文档转换\nyescan --scene image-to-excel --path ./table.jpg\n\n# 查看单个场景的参数\nyescan --list-scenes id-photo"},{"language":"text","snippet":"alibaba-quark-scanking-all/\n├── SKILL.md                        ← Agent 技能契约（PEV 协议 + 约束）\n├── references/\n│   ├── privacy.md                  ← 隐私、数据流向与密钥安全\n│   ├── troubleshooting.md          ← 错误码与排错\n│   └── implementation.md           ← 实现细节：CLI 行为与响应字段\n├── SECURITY.md                     ← 安全策略\n├── README.md                       ← 本文档\n└── README.en.md                    ← English README"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: alibaba-quark-scanking-all\ndescription: 夸克扫描王一站式图片/文档处理中心。当用户需要对图片进行文字识别（OCR）、图片翻译、画质增强（去除水印/阴影/手写/底色/屏纹等瑕疵，矫正，高清增强，素描/线稿转换等）、格式转换（转 Word/Excel/PDF）或 AI 生成（证件照）时使用此技能。即使用户没有明确提到具体功能名称，只要涉及图片处理、文字提取、文档转换、图像优化或证件照生成，都应触发此技能。不适用于视频处理、纯文本编辑或非图片输入的任务。夸克扫描王图片处理能力中心。\nlicense: MIT\ncompatibility: Requires pip3 install yescan and SCAN_WEBSERVICE_KEY configuration. Performs network calls to scan-business.quark.cn.\nmetadata:\n  author: alibaba-quark-scanking\n  version: \"1.0.5\"\n  homepage: https://scan.quark.cn/business\n---\n\n## 执行流程\n\n每次执行严格按 **Plan → Execute → Verify** 顺序进行，不得跳过或乱序。\n\n### Plan — 理解意图，发现能力\n\n1. 确认环境就绪（每次执行，不得跳过）：\n   - **安装 & 升级**：\n     1. `yescan --version` — 未安装则执行 `pip3 install yescan`；若版本 < 1.0.5，执行 `pip3 install yescan --upgrade`，升级完成后才继续\n     2. `pip3 index versions yescan` — 若 INSTALLED < LATEST，告知用户有新版本可用并提供升级命令：`pip3 install yescan --upgrade`，由用户决定是否升级\n   - **密钥检查**：`yescan config get SCAN_WEBSERVICE_KEY`，未配置则引导用户配置\n     - 设置命令：`yescan config set SCAN_WEBSERVICE_KEY <your_api_key>`\n     > Key 获取方式：https://scan.quark.cn/business → 开发者后台 → API Key\n\n   > **Checkpoint**：版本 < 1.0.5 → 必须升级后才能继续。版本 ≥ 1.0.5 但不是最新 → 提示用户后可继续。密钥未配置则引导配置后再继续。\n\n2. 发现能力：\n   ```bash\n   yescan --list-scenes              # 获取全部场景及意图描述\n   yescan --list-scenes <scene>      # 获取该场景的 --set 参数\n   ```\n   从输出中匹配用户意图到具体场景\n3. 多步处理时，向用户展示完整步骤计划\n\n**Gate**：\n- 「确认环境就绪」每一步均为硬性前置，不得跳过任何一步，未全部通过 → 禁止进入 Execute：\n  1. 未执行 `yescan --version` 确认安装状态 → 禁止继续\n  2. 版本 < 1.0.5 且未完成升级 → 禁止继续\n  3. 未执行 `pip3 index versions yescan` 确认最新版本状态 → 禁止继续\n  4. 未执行 `yescan config get SCAN_WEBSERVICE_KEY` 确认密钥已配置 → 禁止继续\n- 只执行用户明确需要的场景，不主动添加额外步骤。为提升当前任务效果的辅助操作不受此限\n- 文档转换（Word/Excel/PDF）直接处理图片，不依赖 OCR 结果。两者输入都是图片，是独立操作\n- 场景名和 `--set` 参数必须来自本次会话的 CLI 输出\n- 未执行过 `--list-scenes` 则不得进入 Execute\n- 场景有 `--set` 参数且用户未明确指定时，须向用户展示可选参数并确认后再执行\n\n### Execute — 执行场景\n\n```bash\nyescan --scene <SCENE> --path <FILE> --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\nyescan --scene <SCENE> --url  <URL>  --platform \"${AGENT_NAME}\" [--output <DIR>] [--set key=value]\n```\n> `--path` 传本地文件路径，`--url` 传 http/https 链接。\n\n> 把 `${AGENT_NAME}` 替换为当前 Agent 平台名称（如 openclaw、hermes、qoderWork、wukong、coze、claudecode 等），无法确定时填 `community`，禁止猜测或自造。\n\n- 单步：直接执行\n- 多步处理为逐步 Execute → Verify 循环：step N+1 的命令在 step N Verify 通过后才构造，`--path` 取自 step N 响应中的 `data.path`\n\n**Gate**：\n- 多步处理时向用户说明步骤计划\n- 每步命令不得预先构造\n- `--set` 参数不跨场景沿用\n\n### Verify — 验证并交付\n\n每步执行后检查响应中的 `code` 字段：\n\n- **成功**（`code` 为 `\"00000\"` 或 `0`）→ 进入交付\n- **失败** → 不继续下一步，根据错误信息处理（详见 Gate）\n\n交付标准 — 以下条件满足才算完成：\n\n- **OCR 识别**：识别内容已以可读文本呈现给用户\n- **图片翻译 / 图像增强 / AIGC**：输出文件路径已告知用户\n- **文档转换**：输出文档路径和格式已告知用户\n\n**Gate**：\n- code 非成功 → 不得继续下一步，不得报告成功\n- 根据错误信息自行修复（如场景名无效 → 重新 `--list-scenes`）或将错误原因告知用户\n- 用户未看到结果 → 未完成\n\n---\n\n## 约束\n\n- **输入方式**：`--path` 或 `--url`，二选一。不支持 base64（如需则先写入临时文件）\n- **URL 引号**：`--url` 参数须用单引号包裹，避免 shell 对 `!` `$` 等特殊字符的解析\n- **文件大小**：≤ 5MB\n- **图片来源**：仅限用户当次请求中明确指定的文件或 URL\n- **禁止伪造**：不得编造或模拟 yescan CLI 的请求参数或响应输出；所有场景名、参数值和执行结果必须来自实际运行的 CLI 命令\n\n---\n\n## 参考文档\n\n- [references/pri"},{"path":"README.md","content":"# yescan\n\n夸克扫描王一站式图片处理技能。支持 36 个场景，覆盖 OCR 识别、图像增强、文档转换、AIGC 生成四大能力。\n\n## 能力概览\n\n| 类别 | 场景数 | 典型用途 |\n|---|---|---|\n| OCR 识别 | 19 | 身份证、发票、表格、手写体、公式等文字提取 |\n| 图像增强 | 13 | 去水印、去阴影、去手写、矫正裁剪、画质增强等 |\n| 文档转换 | 3 | 图片转 Word / Excel / PDF |\n| AIGC 生成 | 1 | 证件照生成 |\n\n## 快速开始\n\n### 1. 安装\n\n```bash\npip3 install yescan\n```\n\n### 2. 配置 API Key\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key>\n```\n\n> 获取 API Key：https://scan.quark.cn/business → 开发者后台\n\n### 3. 使用\n\n```bash\n# 查看所有场景\nyescan --list-scenes\n\n# OCR 识别\nyescan --scene idcard-ocr --path ./idcard.jpg\n\n# 图像增强\nyescan --scene remove-watermark --path ./img.jpg\n\n# 文档转换\nyescan --scene image-to-excel --path ./table.jpg\n\n# 查看单个场景的参数\nyescan --list-scenes id-photo\n```\n\n## 设计理念\n\n- **CLI-first**：CLI 自解释，`--list-scenes` 输出包含意图描述和参数详情\n- **Agent-native**：SKILL.md 定义 PEV 协议（Plan → Execute → Verify）与约束，Agent 自主决策场景匹配\n- **动态发现**：所有场景和参数通过 CLI 动态查询，不硬编码\n\n## 文件结构\n\n```\nalibaba-quark-scanking-all/\n├── SKILL.md                        ← Agent 技能契约（PEV 协议 + 约束）\n├── references/\n│   ├── privacy.md                  ← 隐私、数据流向与密钥安全\n│   ├── troubleshooting.md          ← 错误码与排错\n│   └── implementation.md           ← 实现细节：CLI 行为与响应字段\n├── SECURITY.md                     ← 安全策略\n├── README.md                       ← 本文档\n└── README.en.md                    ← English README\n```\n\n## 相关链接\n\n- [夸克扫描王开放平台](https://scan.quark.cn/business)\n- [SKILL.md](SKILL.md) — Agent 技能契约\n- [SECURITY.md](SECURITY.md) — 安全策略"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn70q165k6hd6cpjtfp8enaa8s82vyem\",\n  \"slug\": \"alibaba-quark-scanking-all\",\n  \"version\": \"1.1.3\",\n  \"publishedAt\": 1783595259287\n}"},{"path":"references/implementation.md","content":"# 实现细节：CLI 行为与响应字段\n\n本文档描述 `yescan` CLI 的内部行为，供需要理解工作原理的开发者参考。\n\n---\n\n## 1. 执行流程\n\n```\n用户/Agent 调用\n  → yescan --scene <scene> --path/--url <input> [--output <dir>] [--set key=value]\n  → 加载凭证（SCAN_WEBSERVICE_KEY）\n  → 根据 scene_configs 构建请求参数\n  → POST https://scan-business.quark.cn/vision\n  → 解析响应 JSON\n  → 根据场景类型处理输出（stdout JSON / 落盘图片 / 落盘文档）\n```\n\n## 2. 响应结构\n\n### 成功响应（OCR 类场景）\n\n> **注意**：OCR 类场景的 `code` 为字符串 `\"00000\"`，而图像/文档类场景的 `code` 为数字 `0`，判断时需注意类型差异。\n\n```json\n{\n  \"code\": \"00000\",\n  \"message\": null,\n  \"data\": {\n    // 各场景返回不同字段，如：\n    // general-ocr: \"content\" (纯文本)\n    // table-ocr: \"tables\" (表格结构)\n    // idcard-ocr: \"name\", \"idNumber\", \"address\" 等\n  }\n}\n```\n\n### 图像/文档类输出（落盘后）\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"path\": \"/tmp/imgs/<Unix时间戳>_<16位随机十六进制串>.<扩展名>\"\n  }\n}\n```\n\n### 错误响应\n\n```json\n{\n  \"code\": \"A0100\",\n  \"message\": \"SCAN_WEBSERVICE_KEY 未配置...\",\n  \"data\": null\n}\n```\n\n## 3. 场景类型与输出行为\n\n| 场景类型 | 输出方式 | 输出位置 |\n|---|---|---|\n| OCR 识别 | JSON 打印到 stdout | 不落盘（除 pic-translate）；指定 `--output` 时保存 JSON 到指定目录 |\n| 图像增强 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n| 文档转换 | 文档落盘 | 系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 目录 |\n| AIGC 生成 | 图片落盘 | 系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 目录 |\n\n## 4. 关键约定\n\n- OCR 场景直接返回 API 原始响应的 `data` 字段，不做二次加工。\n- **pic-translate 场景例外**：API 返回 `data.ImageInfo[0].ResImageBase64`，CLI 将其解码落盘并注入 `data.translated_image_path`，同时剔除 `ImageInfo` 字段避免 base64 噪音。\n- 图像/文档类输出的文件名格式：`<Unix时间戳>_<16位随机十六进制串>.<扩展名>`。\n- 多步 Pipeline 时，前一步的 `data.path` 作为下一步的 `--path` 输入。\n\n## 5. 错误码速查\n\n| 错误码 | 含义 | 常见原因 |\n|---|---|---|\n| A0100 | 凭证错误 | SCAN_WEBSERVICE_KEY 未配置或无效 |\n| A0201 | 缺少图片输入 | 未提供 --url 或 --path |\n| A0211 | 配额不足 | API 额度用尽，需充值 |\n| INVALID_SCENE | 场景名无效 | --scene 值不在可用场景列表中 |\n| FILE_ERROR | 文件校验失败 | 文件不存在、超过 5MB 或格式不支持 |"},{"path":"references/privacy.md","content":"# 隐私、数据流向与密钥安全\n\n本文档说明 `yescan` 技能在执行过程中涉及的全部数据流向、第三方服务交互范围，以及 API 密钥的配置、存储与轮换流程。\n\n---\n\n## 1. 数据流向（What leaves your machine）\n\n| 数据 | 是否外发 | 接收方 | 用途 |\n|---|---|---|---|\n| 用户提供的图片（URL / 本地文件） | 外发 | `https://scan-business.quark.cn`（夸克扫描王服务） | OCR / 增强 / 转换 / AIGC |\n| `SCAN_WEBSERVICE_KEY` | 随请求头发送 | 同上 | API 鉴权 |\n| 处理结果（JSON / 文件） | 不外发 | 仅返回给调用方 | CLI 输出到 stdout 或本地文件 |\n| 用户提示词、对话上下文 | 不外发 | — | 仅在本地 Agent 处理 |\n\n> **服务端处理说明**：夸克扫描王服务将获取并处理该图片内容，服务端不会永久保存。\n\n## 2. 本地文件行为\n\n- **OCR 场景**：不写入输出文件（结果以 JSON 打印到 stdout），`pic-translate` 场景例外（保存译图到临时目录）\n- **图像增强场景**：输出增强后图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- **文档转换场景**：输出文档文件到系统临时目录下的 `documents/` 子目录（如 `/tmp/documents/`）或 `--output` 指定目录\n- **AIGC 场景**：输出生成图片到系统临时目录下的 `imgs/` 子目录（如 `/tmp/imgs/`）或 `--output` 指定目录\n- 唯一的文件读取操作是用户指定的本地图片路径（`--path` 参数）\n\n## 3. API 密钥配置\n\n### 3.1 推荐方式：通过 CLI 配置（永久生效）\n\n```bash\nyescan config set SCAN_WEBSERVICE_KEY <your_api_key_here>\n```\n\n配置保存在 `~/.yescan/config.json`。\n\n### 3.2 备选方式：环境变量（仅当前会话）\n\n```bash\nexport SCAN_WEBSERVICE_KEY=<your_api_key_here>\n```\n\n> 优先级：CLI config（`~/.yescan/config.json`）> 环境变量\n\n## 4. 获取与轮换密钥\n\n1. 访问 `https://scan.quark.cn/business`（**仅此一个有效官方入口**）\n2. 进入开发者后台 → 登录/注册账号 → 创建应用 → 查看 API Key\n3. 如怀疑密钥泄露：在同一后台立即 *轮换* 或 *撤销* 旧密钥，并更新配置\n\n## 5. 安全实践清单\n\n- [x] 不要在公网截图/录屏中暴露 key 或配置文件内容\n- [x] 仅对用户主动指定的图片进行处理，不要遍历整个目录\n- [x] 处理涉密 / PII 图片前，用户应自行评估数据外发的合规性\n\n## 6. 适用范围\n\n本技能图片来源 **仅限用户在当次请求中明确指定** 的图片文件或 URL。技能不会主动扫描磁盘、访问剪贴板或读取额外文件。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描/线稿）、图片转 Word/Excel/PDF、AI 证件照生成。 Skill: 夸克扫描王-OCR 文字识别/文件扫描/转 Office Alibaba-Quark-Scanking-All Owner: yescan-ai Summary: 夸克扫描王官方图片处理中心：OCR 文字识别（身份证/社保卡/驾驶证/行驶证/港澳台通行证/学位证/营业执照、增值税发票/火车票/英文发票、医疗检验报告/药检报告、表格/公式/手写体/试卷习题/商品图/通用文字）、拍照翻译、画质增强（去水印/去阴影/去手写/去底色/去摩尔纹、裁剪矫正、高清修复、试卷增强、合同增强、素描/线稿）、图片转 Word/Excel/PDF、AI 证件照生成。 Tags: latest:1.1.3 Version history: v1.1.3 | 2026-07-09T11:07:39.287Z | auto - Skill renamed from yescan-universal to alibaba-quark-scank","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":804,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:20:07.913Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:20:07.913Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:17:53.921Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}