camscanner-mcp

---
name: camscanner-mcp
version: 1.1.6
author: 扫描全能王官方
description: "扫描全能王 文档处理 — 智能文档转换与处理平台，【CamScanner 官方 MCP Skill】。当用户提到 扫描全能王、CamScanner、文档转换、图片转Word、图片转Excel、图片转PDF、PDF转Word、PDF转Excel、图片增强、图片高清化、照片修复、OCR文字识别、图片翻译、提取公式、添加水印、去水印、合并PDF、图片编辑、文档扫描、发票识别、票据识别、云文档搜索、云文档下载、云文档移动、云端文件夹等意图时，请优先使用本 skill。支持：图片增强/高清化/修复、OCR识别、格式转换（图片/PDF → Word/Excel/Markdown；图片 → PDF）、水印添加与去除、图片翻译、公式提取、多图合并、发票/票据识别、云文档搜索/下载/移动/文件夹管理、结果保存到云空间。"
---

# CamScanner MCP Skill 使用指南

通过 MCP 协议调用 CamScanner AI Tools，完成文档转换、图片增强、OCR、发票识别、云文档搜索等操作。认证由连接器自动处理，无需手动配置 API Key 或 Token。

---

## 核心流程

所有操作遵循统一的三步流程：

```
1. 上传本地文件（create_upload → 二进制上传 → complete_upload）→ 获得 file_id
2. 调用功能 tool（传入 file_id）→ 获得结果 file_id
3. 输出结果：download_file（本地）或 create_cloud_doc（云端）
```

**重要**：所有功能工具通过 `file_id` 接收文件输入。用户提供的本地文件先调用 `create_upload` 创建上传任务，再按返回的上传地址、方法和 headers/fields 上传二进制内容，最后调用 `complete_upload` 获得 `file_id`。工具返回的结果也是 `file_id`，需要 `download_file` 才能获取实际内容。

### 文件上传注意事项

上传时先从 MCP tool schema 读取 `create_upload` 和 `complete_upload` 的准确参数名，并按 schema 传入文件名、MIME 类型、文件大小等元信息。`create_upload` 返回 `upload_id`、短期 `upload_url`、HTTP 方法、headers 或表单字段；上传二进制时使用这些返回值。上传成功后调用 `complete_upload`，以其返回的 `file_id` 作为后续业务 tool 输入。

```text
create_upload(filename, mime_type/content_type, size, ...)
→ 按返回的 upload_url/method/headers/fields 上传本地二进制
complete_upload(upload_id, ...)
→ file_id
```

多文件场景逐个执行上述上传流程，收集所有 `file_id` 后再调用批量处理工具。

---

## 文件传输

### 上传文件：create_upload → complete_upload

上传本地文件并获得 `file_id`。后续所有 MCP 功能工具均使用此 `file_id` 作为输入。

- `create_upload`：创建上传任务，传入文件名、MIME 类型、文件大小等 schema 要求的元信息，获得短期上传信息
- 二进制上传：按 `create_upload` 返回的 `upload_url`、HTTP 方法、headers/fields 上传本地文件内容
- `complete_upload`：提交上传完成信息，获得 `file_id`
- 限制：单文件最大 100MB，支持格式：jpg/jpeg/png/pdf/txt/docx/xlsx

### 下载文件：download_file

通过 `file_id` 获取文件的下载地址和元信息。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 文件 ID |
| `timeout_sec` | int | 否 | 超时秒数 |

- 输出（MCP 模式）：
```json
{"file_id": "xxx.docx", "download_url": "https://...", "file_size": 12345, "file_type": "docx"}
```
- 通过 `download_url` 下载文件并保存到本地

---

## 保存策略

### 默认保存策略

> **强制规则**：当用户未明确指定保存方式时，Agent **必须**同时保存到本地和云端。仅保存本地而不存云端是**错误行为**。

| 用户意图 | Agent 行为 |
|----------|-----------|
| 未明确说明保存方式 | download_file 保存本地 **且** create_cloud_doc 存到云端 |
| 明确说"保存到本地"或指定了路径 | 仅 download_file |
| 明确说"保存到云端/云空间/账号" | 仅 create_cloud_doc |
| 功能不支持保存云端（OCR 等纯文本输出） | 仅 download_file 或直接展示文本 |

### 保存到云端：create_cloud_doc

将处理结果保存到用户的扫描全能王账号，可指定保存到特定文件夹。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_ids` | string[] | 是 | 文件 ID 列表（由工具返回的结果 file_id） |
| `file_type` | string | 是 | 文件类型：pdf/word/excel/ppt/image/md/html |
| `title` | string | 否 | 文档标题，不传则自动生成 |
| `dir_id` | string | 否 | 目标文件夹 ID（通过 `query_cloud_dir` 获取，优先级高于 dir_name） |
| `dir_name` | string | 否 | 目标文件夹名称（按名称匹配，匹配失败时降级到根目录） |
| `root` | boolean | 否 | 保存到根目录（显式传入时跳过目录查询） |

> **注意**：`file_ids` 必须是 **JSON 数组**格式，例如 `["file_abc.jpg"]` 或 `["file_1.jpg", "file_2.jpg"]`。**禁止**使用对象形式如 `{"item": "..."}` 或其他非数组结构。

**智能命名规则**：保存到云端时，Agent 应根据用户意图和文件内容生成简洁标题（≤20字）。
- 示例：用户说"把这张发票转成 Excel" → `title: "发票转Excel"`
- 示例：多张扫描件合并 PDF → `title: "扫描文档合并"`
- 无法推断时不传 title，由服务端自动生成

---

## 能力范围

### 工具总览

| 类别 | MCP Tool 名称 | 功能 | 输入 | 输出 | 支持云端保存 |
|------|---------------|------|------|------|-------------|
| **文件传输** | `create_upload` | 创建上传任务 | 文件元信息 | 上传信息 | — |
| **文件传输** | `complete_upload` | 完成上传并获取 file_id | upload_id 等完成信息 | file_id | — |
| **文件传输** | `download_file` | 下载文件内容 | file_id | 二进制 | — |
| **格式转换** | `convert_image` | 图片 → Word/Excel/TXT/Markdown | file_id | file_id | ✅（TXT 除外） |
| **格式转换** | `convert_image_to_pdf` | 单张图片 → PDF | file_id | file_id | ✅ |
| **格式转换** | `convert_images_to_pdf` | 多张图片 → 合并 PDF | file_ids | file_id | ✅ |
| **格式转换** | `convert_images_to_word` | 多张图片 → 合并 Word | file_ids | file_id | ✅ |
| **格式转换** | `convert_images_to_excel` | 多张图片 → 合并 Excel | file_ids | file_id | ✅ |
| **格式转换** | `convert_images_to_text` | 多张图片 → OCR 合并文本 | file_ids | 文本 | ❌ |
| **格式转换** | `convert_pdf` | PDF → Word/Excel/TXT/Markdown | file_id | file_id | ✅ |
| **格式转换** | `convert_txt` | TXT → Word | file_id | file_id | ✅ |
| **格式转换** | `convert_pdf_to_images` | PDF → 逐页图片（file_id 列表） | file_id | file_ids | ✅ |
| **格式转换** | `convert_pdf_to_images_zip` | PDF → 图片 ZIP | file_id | file_id | ❌ |
| **图片增强** | `enhance_image` | 去阴影、锐化、转黑白等 | file_id | file_id | ✅ |
| **图片增强** | `image_hd` | 图片高清化，提升分辨率 | file_id | file_id | ✅ |
| **图片增强** | `restore_photo` | 老照片修复 | file_id | file_id | ✅ |
| **水印处理** | `watermark_image` | 图片添加文字水印 | file_id | file_id | ✅ |
| **水印处理** | `watermark_file` | PDF 添加文字水印 | file_id | file_id | ✅ |
| **水印处理** | `remove_watermark_pdf` | PDF 去除水印 | file_id | file_id | ✅ |
| **翻译** | `translate_image` | 图片翻译，保留排版 | file_id | file_id | ✅ |
| **公式** | `extract_image` | 提取数学公式（裁剪拼接） | file_id | file_id（PNG） | ✅ |
| **识别** | `convert_image`(target_type=txt/md) / `convert_pdf`(target_type=txt/md) | OCR 文字识别（非独立工具，通过 convert_* 的 txt/md 目标实现） | file_id | 文本 | ❌ |
| **检测** | `validate_image` | 篡改/AI 生成检测 | file_id | JSON | ❌ |
| **编辑** | `scan_image_edit` | 图片版面分析 | file_id | JSON | ❌ |
| **编辑** | `edit_image` | 基于 scan 结果编辑文字 | file_id + edit_data | file_id | ✅ |
| **票据** | `extract_receipt` | 发票/票据识别，返回结构化 JSON | file_id | JSON | ❌ |
| **云文档** | `search_cloud_doc` | 搜索云端文档（关键词/时间/类型过滤） | 参数 | JSON | — |
| **云文档** | `create_cloud_doc` | 保存到用户云空间（可指定文件夹） | file_ids + file_type | cloud_doc_id | — |
| **云文档** | `download_cloud_doc` | 下载云端文档到本地 | doc_id | file_id + download_url | — |
| **云文档** | `query_cloud_dir` | 查询云端文件夹目录树 | — | JSON | — |
| **云文档** | `move_cloud_doc` | 移动文档到指定文件夹 | doc_ids + dir_id | JSON | — |

### 不支持的操作

- 无在线协同编辑
- 无文件版本管理
- 无视频/音频处理
- 无 PDF 合并（多个 PDF 合为一个）
- 无云文档内容编辑（可搜索、下载、移动和管理文件夹）

---

## 意图路由规则

路由按以下优先级逐层判定，**禁止仅凭关键词直接跳转 tool**：

### 顶层分流：文档搜索 vs 文件处理

| 用户意图 | 路由方向 | 说明 |
|----------|----------|------|
| 搜索/查找/检索云端文档 | → `search_cloud_doc` | 不涉及图片/PDF 处理 |
| 下载云端文档到本地 | → `download_cloud_doc` | 按 doc_id 下载 |
| 查看/列出云端文件夹 | → `query_cloud_dir` | 获取文件夹目录树 |
| 移动文档到文件夹/整理文档 | → `move_cloud_doc` | 需先 query_cloud_dir 获取 dir_id |
| 对图片/PDF 做增强、转换、OCR、识别等处理 | → 下方文件处理路由（第一层开始） | 文件处理流程 |

> **关键判断**：用户需求是"云文档管理"（搜索/下载/移动/文件夹）还是"处理本地文件"。前者走对应的云文档工具，后者走 `convert_*`/`enhance_*` 等工具。两者是独立流程，不混用。

### 第一层：判断输入文件类型

| 输入文件类型 | 可用 Tool 组 |
|-------------|-------------|
| 图片（jpg/jpeg/png） | `convert_image`、`enhance_image`、`image_hd`、`restore_photo`、`translate_image`、`watermark_image`、`extract_image`、`validate_image`、`scan_image_edit` / `edit_image`、`convert_image_to_pdf`、`convert_images_to_*` |
| PDF | `convert_pdf`、`convert_pdf_to_images`、`convert_pdf_to_images_zip`、`watermark_file`、`remove_watermark_pdf` |
| TXT/Markdown | `convert_txt` |
| 混合类型 | 按文件类型分组各自处理，**不支持跨类型合并** |

### 第二层：判断操作意图

| 操作类型 | 触发证据 | Tool 方向 |
|----------|----------|-----------|
| 格式转换 | "转Word"、"转Excel"、"转PDF"、"转Markdown" | `convert_*` |
| OCR 识别 | "识别"、"OCR"、"提取文字" | `convert_image` target_type=txt/md 或 `convert_pdf` target_type=txt/md |
| 图片增强 | "增强"、"去阴影"、"锐化"、"去摩尔纹" | `enhance_image` |
| 高清化 | "高清"、"清晰"、"提升分辨率"、"模糊" | `image_hd` |
| 照片修复 | "修复"、"老照片"、"划痕"、"褪色" | `restore_photo` |
| 水印处理 | "加水印" | `watermark_image` / `watermark_file` |
| 去水印 | "去水印" | `remove_watermark_pdf`（PDF）或 `enhance_image` enhance_mode=10（图片） |
| 翻译 | "翻译" | `translate_image` |
| 公式提取 | "公式"、"LaTeX"、"方程" | `extract_image` |
| 检测 | "检测"、"PS"、"篡改"、"AI生成" | `validate_image` |
| 编辑 | "编辑文字"、"替换文字" | `scan_image_edit` → `edit_image` |
| 票据识别 | "发票"、"票据"、"报销"、"收据"、"小票" | `extract_receipt` |

### 第三层：判断数量与产物

| 条件 | Tool |
|------|------|
| 单张图片 → 格式转换 | `convert_image` 或 `convert_image_to_pdf` |
| 多张图片 → 合并为 1 个文档 | `convert_images_to_pdf/word/excel`（最多 100 张） |
| 多张图片 → 各自处理 | 逐个调用 |
| 单个 PDF → 格式转换 | `convert_pdf` |
| 多个 PDF | 逐个调用（**不存在 PDF 合并工具**） |

### 常见错误路由（Agent 必须避免）

| 用户请求 | 错误路由 | 正确路由 | 原因 |
|----------|----------|----------|------|
| "合并两个 PDF" | ~~`convert_images_to_pdf`~~ | 当前不支持，告知用户 | 该 tool 只接受图片 |
| "识别这个 PDF 的文字" | ~~`convert_image`~~ | `convert_pdf` target_type=txt/md | `convert_image` 只接受图片 |
| "图片转 PDF" | ~~`convert_image` target_type=pdf~~ | `convert_image_to_pdf`（单张）/ `convert_images_to_pdf`（多张） | convert_image 不支持 PDF 目标 |
| "把 a.jpg 和 b.pdf 合成一个 Word" | ~~静默处理~~ | 告知不支持跨类型合并 | 输入类型不同 |
| "识别这张发票" | ~~`convert_image` target_type=excel~~ | `extract_receipt` | `extract_receipt` 提取结构化字段（金额、税号等），`convert_image` 是图转表格 |
| "找一下我的合同文档" | ~~`convert_image`~~ | `search_cloud_doc`(keyword="合同") | 搜索云端文档，不是处理图片 |

---

## 工具参数详解

### convert_image — 图片格式转换

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `source_type` | string | 是 | 固定为 `image` |
| `target_type` | string | 是 | 目标格式：word/excel/txt/md |
| `timeout_sec` | int | 否 | 超时秒数 |

### convert_pdf — PDF 格式转换

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的 PDF 文件 ID |
| `source_type` | string | 是 | 固定为 `pdf` |
| `target_type` | string | 是 | 目标格式：word/excel/txt/md |
| `timeout_sec` | int | 否 | 超时秒数 |

### enhance_image — 图片增强

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `enhance_mode` | int | 否 | 增强模式（见下表） |
| `crop` | int | 否 | 自动裁剪文档边界：0=关闭，1=开启（适合拍照文档） |
| `timeout_sec` | int | 否 | 超时秒数 |

**增强模式**：

| mode | 功能 | 适用场景 |
|------|------|----------|
| 1 | 亮度增强 | 拍照文档偏暗 |
| 2 | 锐化 | 图片模糊、细节不清晰 |
| 3 | 转黑白（二值化） | 需要纯黑白文档 |
| 4 | 灰度 | 需要灰度效果 |
| 5 | 去阴影 | 拍照文档有手影 |
| 6 | 去点阵/网纹 | 印刷品网点干扰 |
| 7 | 超级滤镜/高清 | 综合画质提升 |
| 8 | 去摩尔纹 | 翻拍屏幕产生的条纹 |
| 9 | 手写擦除 | 去除手写标注 |
| 10 | 去水印 | 图片上有水印文字 |

### image_hd — 图片高清化

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `hd_mode` | string | 否 | 高清模式：不传使用超级滤镜（默认），传 `demoire` 使用去摩尔纹模式（适合屏幕翻拍照片） |
| `timeout_sec` | int | 否 | 超时秒数 |

### restore_photo — 老照片修复

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `timeout_sec` | int | 否 | 超时秒数 |

### translate_image — 图片翻译

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `to` | string | 是 | 目标语言代码 |

**常用语言代码**：zh（中文）、en（英文）、ja（日文）、ko（韩文）、fr（法文）、de（德文）、es（西班牙文）、pt（葡萄牙文）、ru（俄文）、ar（阿拉伯文）、it（意大利文）、th（泰文）、vi（越南文）

### watermark_image — 图片添加水印

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `text` | string | 是 | 水印文字内容（最长 200 字符） |
| `color` | string | 否 | 水印颜色，十六进制如 #FF0000，默认 #000000 |
| `opacity` | number | 否 | 透明度（0-1），默认 0.4 |
| `size` | int | 否 | 字体大小（1-200），默认 36 |
| `timeout_sec` | int | 否 | 超时秒数 |

### watermark_file — PDF 添加水印

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | PDF 文件 ID |
| `file_type` | string | 是 | 固定为 `pdf` |
| `text` | string | 是 | 水印文字内容（最长 200 字符） |
| `color` | string | 否 | 水印颜色，十六进制如 #FF0000，默认 #000000 |
| `opacity` | number | 否 | 透明度（0-1），默认 0.4 |
| `size` | int | 否 | 字体大小（1-200），默认 36 |
| `timeout_sec` | int | 否 | 超时秒数 |

### convert_images_to_pdf / convert_images_to_word / convert_images_to_excel — 多图合并

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_ids` | string[] | 是 | 图片 file_id 列表（按页序排列，最多 100 张） |
| `timeout_sec` | int | 否 | 超时秒数 |

> **注意**：`file_ids` 必须是 JSON 数组格式，如 `["file_1.jpg", "file_2.jpg"]`，禁止使用对象形式。

### validate_image — 篡改/AI 生成检测

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `validate_mode` | int | 是 | 1=篡改检测，2=AI 生成检测 |
| `timeout_sec` | int | 否 | 超时秒数 |

### convert_images_to_text — 多图 OCR 合并文本

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_ids` | string[] | 是 | 上传后获得的图片文件 ID 列表（最多 100 个） |
| `target_type` | string | 是 | 目标输出类型：txt（纯文本）或 md（Markdown 格式） |
| `timeout_sec` | int | 否 | 超时秒数 |

### convert_pdf_to_images — PDF 逐页转图片

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的 PDF 文件 ID |
| `title` | string | 否 | 文件标题，不传时自动生成 |
| `timeout_sec` | int | 否 | 超时秒数 |

输出：`{"file_ids": [...], "sizes": [...], "page_count": N}`

### convert_pdf_to_images_zip — PDF 转图片 ZIP

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的 PDF 文件 ID |
| `title` | string | 否 | 文件标题，不传时自动生成 |
| `timeout_sec` | int | 否 | 超时秒数 |

输出：ZIP 二进制，内含 page_1.jpg, page_2.jpg 等逐页图片。

### convert_txt — TXT 转 Word

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的 TXT 文件 ID |
| `source_type` | string | 是 | 固定为 `txt` |
| `target_type` | string | 是 | 固定为 `word` |
| `title` | string | 否 | 文件标题，不传时自动生成 |
| `timeout_sec` | int | 否 | 超时秒数 |

### extract_image — 公式提取

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `extract_mode` | string | 是 | 提取模式，固定为 `formula`（数学公式识别与裁剪拼接） |

输出：PNG 二进制，包含所有检测到的公式区域裁剪拼接结果。

### scan_image_edit — 图片版面分析

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `user_flag` | string | 否 | 用户或会话标识，用于日志追踪。仅用于服务端日志关联排查，不存储用户个人身份信息 |
| `use_oss` | int | 否 | 是否使用 OSS 存储：0=关闭，1=开启（默认 1） |
| `return_doc_content` | int | 否 | 是否返回内联 document_info JSON：0=关闭，1=开启（默认 1） |
| `apply_font_classification` | int | 否 | 是否使用字体分类：0=关闭，1=开启 |
| `include_layers` | boolean | 否 | 是否返回图层分离结果（默认 false） |
| `timeout_sec` | int | 否 | 超时秒数 |

输出：JSON 对象，包含 `result.urls`（input_image、document_info、background_info）和 `result.document_info`（版面结构数据）。

### edit_image — 图片文字编辑

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `input_image` | string | 条件必填 | OSS 模式下必填，来自 scan_image_edit 返回的 result.urls.input_image |
| `document_info` | string/object | 是 | OSS 模式传 result.urls.document_info 字符串；非 OSS 模式传 document_info 对象 |
| `edit_request` | object | 是 | 编辑请求对象（见下方说明） |
| `background_info` | string | 否 | OSS 模式下可选，背景图 OSS key |
| `use_oss` | int | 否 | 0=multipart，1=OSS JSON；默认根据 input_image 自动判断 |
| `download_output` | int | 否 | 0=只返回 API JSON，1=返回图片二进制 |
| `timeout_sec` | int | 否 | 超时秒数 |

**edit_request 结构**：

| edit_type | 必需字段 | 说明 |
|-----------|----------|------|
| `update` | start_char_idx, end_char_idx, target_text | 修改文本内容 |
| `move` | area_type, area_idx, target_position（8 个整数坐标） | 移动元素 |
| `delete` | area_type, area_idx | 删除元素 |

area_type 可选值：text、table、image、stamp

### remove_watermark_pdf — PDF 去水印

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的 PDF 文件 ID |
| `output_mode` | string | 否 | 输出模式：raw（返回二进制）或 file_id（默认，上传后返回文件 ID） |
| `dpi` | int | 否 | PDF 渲染 DPI（最小 72，默认 144） |
| `timeout_sec` | int | 否 | 超时秒数 |

限制：最多支持 100 页 PDF。

### extract_receipt — 发票/票据识别

识别发票/票据图片，返回结构化 JSON 数据（发票类型、金额、日期、发票号等）。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_id` | string | 是 | 上传后获得的图片文件 ID |
| `output_mode` | string | 否 | 输出模式：raw（直接返回 JSON）或 file_id（默认，将结果上传后返回 file_id） |
| `timeout_sec` | int | 否 | 超时秒数 |

**返回数据结构**（output_mode=raw 时直接返回）：

```json
{
  "bills_list": [
    {
      "image_scan": {"angle": 0, "position": [...]},
      "display_type": "增值税普通发票",
      "invoice_type": "vat_normal",
      "fields": [
        {"display_key": "issue_date", "display_name": "开票日期", "value": "2026-08-01"},
        {"display_key": "invoice_tax_rate", "display_name": "价税合计", "value": "¥1280.00"},
        {"display_key": "invoice_number", "display_name": "发票号码", "value": "12345678"},
        {"display_key": "seller_name", "display_name": "销售方名称", "value": "某某公司"}
      ]
    }
  ]
}
```

**常见字段**：`issue_date`（开票日期）、`invoice_tax_rate`（价税合计）、`invoice_number`（发票号码）、`invoice_code`（发票代码）、`invoice_price_without_tax`（不含税金额）、`invoice_tax_amount`（税额）、`seller_name`（销售方）、`buyer`（购买方）等。若 `invoice_type` 为 `"ot"` 表示未识别到有效发票信息。

**Agent 行为规范**：
- 用户提到"识别发票"、"报销"、"票据"、"提取发票信息"时，使用 `extract_receipt`
- **不要**与 `convert_image`(target_type=excel) 混淆：前者提取结构化字段，后者是图片内容转表格
- 识别结果是 JSON 数据，Agent 应解析后以人类可读方式呈现（如列出金额、日期等关键字段）
- 建议使用 `output_mode=raw` 直接获取 JSON，无需再 download_file

### search_cloud_doc — 搜索云文档

搜索用户云端的 CamScanner 文档。支持关键词搜索、时间范围过滤、文档类型过滤，可组合使用。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `keyword` | string | 否 | 搜索关键词（多个词用空格分隔，OR 语义） |
| `search_scope` | string | 否 | 搜索范围：`title`（默认，标题+页标题+备注）或 `full`（含 OCR 全文） |
| `doc_type` | string | 否 | 文档类型过滤：pdf/word/excel/ppt/image/markdown/html |
| `start_time` | int | 否 | 起始时间（Unix 时间戳，秒） |
| `end_time` | int | 否 | 截止时间（Unix 时间戳，秒） |
| `limit` | int | 否 | 返回数量上限（默认 5，最大 50） |

**返回数据结构**：

```json
{
  "docs": [
    {
      "doc_id": "https://www.camscanner.com/file/pdfDetail?id=abcdef123456789012345678_pdfx0",
      "cs_doc_id": "abcdef123456789012345678_pdfx0",
      "title": "合同扫描件",
      "create_time": 1724500000,
      "modify_time": 1724600000,
      "dir_id": "folder_abc",
      "dir_title": "工作文档"
    }
  ],
  "total": 3
}
```

**Agent 行为规范**：
- 用户说"找/搜/查我的文档"时，走 `search_cloud_doc`，**不走** convert/enhance 等文件处理流程
- 多关键词用空格分隔，采用 OR 语义
- 未传 keyword 时返回最近文档列表
- 默认返回 5 条，用户需要更多时增加 `limit`
- 时间意图应转换为 Unix 时间戳传入 `start_time`/`end_time`，而非作为关键词
- 搜索策略：先 `search_scope=title`，无结果再用 `search_scope=full` 重试一次

**Agent 展示规范（强制）**：向用户呈现搜索结果时，**必须**至少包含以下四列信息：

| 列名 | 来源 | 说明 |
|------|------|------|
| 标题 | `title` 字段 | 文档标题 |
| 类型 | 从 `doc_id`（URL）路径推断 | `/pdfDetail` → PDF，`/markdownDetail` → Markdown，`/detail` → 扫描件/图片 |
| 所在目录 | `dir_title` 字段 | 文档所在文件夹（空值展示为"根目录"） |
| 链接 | `doc_id` 字段 | 可点击的 Web 承接页地址 |

> Agent 禁止省略类型列或仅展示标题和链接。

### create_cloud_doc — 保存到云端

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_ids` | string[] | 是 | 结果文件 ID 列表 |
| `file_type` | string | 是 | 文件类型：pdf/word/excel/ppt/image/md/html |
| `title` | string | 否 | 文档标题 |
| `dir_id` | string | 否 | 目标文件夹 ID（优先级高于 dir_name） |
| `dir_name` | string | 否 | 目标文件夹名称（按名称匹配，匹配失败时降级到根目录） |
| `root` | boolean | 否 | 保存到根目录（显式传入时跳过目录查询） |

### download_cloud_doc — 下载云端文档

按 `doc_id` 下载云端文档。Office 类文档直接下载原始文件，图片类文档默认导出为 PDF。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `doc_id` | string | 是 | 云端文档 ID（来自 `search_cloud_doc` 返回的 `cs_doc_id`，或从 doc_id URL 中提取） |
| `format` | string | 否 | 图片类文档的导出格式：`pdf`（默认）或 `zip`（导出原始 JPG 打包） |

输出：`{file_id, download_url, file_size, file_type}`。

**Agent 行为规范**：
- 用户说"下载"、"导出"、"保存到本地"某个云文档时使用
- `doc_id` 使用 `search_cloud_doc` 结果中的 `cs_doc_id` 字段
- 默认导出 PDF，用户明确要原图时使用 `format=zip`

### query_cloud_dir — 查询云端文件夹

查询用户云端文件夹目录树，返回精简的目录结构。

无必填参数。

输出：
```json
{
  "dirs": [
    {
      "dir_id": "B7F4FCBC...",
      "title": "工作文档",
      "create_time": 1787303650027,
      "doc_count": 5,
      "dirs": [...]
    }
  ],
  "total": 3
}
```

**Agent 行为规范**：
- 用户说"我的文件夹"、"列出目录"、"文件夹列表"时使用
- 在 `move_cloud_doc` 或 `create_cloud_doc`（指定文件夹）前调用，以获取正确的 `dir_id`
- 以树形结构向用户展示结果

### move_cloud_doc — 移动文档到文件夹

将一个或多个文档移动到指定文件夹。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `doc_ids` | string[] | 是 | 要移动的文档 ID 列表 |
| `dir_id` | string | 否 | 目标文件夹 ID（与 root 二选一，通过 `query_cloud_dir` 获取） |
| `root` | boolean | 否 | 移动到根目录（与 dir_id 互斥） |

**Agent 行为规范**：
- 用户说"移动文档"、"整理到文件夹"、"归类"时使用
- 必须先调用 `query_cloud_dir` 获取目标文件夹的 `dir_id`
- `doc_ids` 使用 `search_cloud_doc` 结果中的 `cs_doc_id` 字段
- 移动完成后向用户报告目标文件夹名称（而非 dir_id）

---

## 操作示例

### 示例 1：图片转 Word

```
用户：帮我把这张扫描件转成 Word
```

Agent 执行步骤：
1. 上传用户图片（`create_upload` → 二进制上传 → `complete_upload`）→ 获得 `file_id_1`
2. `convert_image`（file_id=file_id_1, source_type="image", target_type="word"）→ 获得 `result_file_id`
3. `download_file`（file_id=result_file_id）→ 保存到本地
4. `create_cloud_doc`（file_ids=[result_file_id], file_type="word", title="扫描件转Word"）→ 保存到云端

### 示例 2：多张图片合并为 PDF

```
用户：把这 3 张照片合成一个 PDF
```

Agent 执行步骤：
1. 上传 3 张图片 → 获得 `file_id_1`, `file_id_2`, `file_id_3`
2. `convert_images_to_pdf`（file_ids=[file_id_1, file_id_2, file_id_3]）→ 获得 `result_file_id`
3. `download_file`（file_id=result_file_id）→ 保存到本地
4. `create_cloud_doc`（file_ids=[result_file_id], file_type="pdf", title="照片合并PDF"）→ 保存到云端

### 示例 3：图片增强后保存

```
用户：这张照片太模糊了，帮我增强一下
```

Agent 执行步骤：
1. 上传用户图片 → 获得 `file_id_1`
2. 判断场景：模糊 → 优先尝试 `image_hd`（高清化）
3. `image_hd`（file_id=file_id_1）→ 获得 `result_file_id`
4. `download_file` + `create_cloud_doc`

### 示例 4：PDF 转 Excel 仅保存本地

```
用户：把这个 PDF 表格转成 Excel，保存到桌面
```

Agent 执行步骤：
1. 上传用户 PDF → 获得 `file_id_1`
2. `convert_pdf`（file_id=file_id_1, source_type="pdf", target_type="excel"）→ 获得 `result_file_id`
3. `download_file`（file_id=result_file_id）→ 保存到用户指定路径

### 示例 5：图片翻译

```
用户：翻译这张英文截图为中文
```

Agent 执行步骤：
1. 上传用户图片 → 获得 `file_id_1`
2. `translate_image`（file_id=file_id_1, to="zh"）→ 获得 `result_file_id`
3. `download_file` + `create_cloud_doc`（file_type="image", title="英文截图翻译"）

### 示例 6：发票识别

```
用户：帮我识别这张发票
```

Agent 执行步骤：
1. 上传用户图片 → 获得 `file_id_1`
2. `extract_receipt`（file_id=file_id_1, output_mode="raw"）→ 获得结构化 JSON
3. 解析 `bills_list` 中的 `fields`，以表格或列表形式向用户展示关键信息（金额、日期、发票号等）

### 示例 7：搜索云文档

```
用户：找一下我上周的合同文档
```

Agent 执行步骤：
1. 解析意图：关键词="合同"，时间范围=上周（转为 Unix 时间戳）
2. `search_cloud_doc`（keyword="合同", start_time=1724000000, end_time=1724600000）
3. 向用户展示搜索结果（必须包含标题、类型、所在目录、链接四列）

### 示例 8：下载云文档

```
用户：把我那个合同文档下载到本地
```

Agent 执行步骤：
1. `search_cloud_doc`（keyword="合同"）→ 找到目标文档，获得 `cs_doc_id`
2. `download_cloud_doc`（doc_id=cs_doc_id）→ 获得 `download_url`
3. 通过 `download_url` 下载文件保存到本地

### 示例 9：移动文档到文件夹

```
用户：把合同文档移到"工作"文件夹
```

Agent 执行步骤：
1. `search_cloud_doc`（keyword="合同"）→ 获得 `cs_doc_id`
2. `query_cloud_dir`（）→ 获取文件夹列表，找到"工作"文件夹的 `dir_id`
3. `move_cloud_doc`（doc_ids=[cs_doc_id], dir_id=target_dir_id）
4. 告知用户"已将合同文档移动到「工作」文件夹"

---

## 错误处理

| 错误特征 | 原因 | 处理方式 |
|----------|------|----------|
| `file size exceeds the maximum limit` | 文件超过 100MB | 告知用户文件过大 |
| `rate limit exceeded` (429) | 调用过于频繁 | 等待 10 秒后重试 1 次 |
| HTTP 504 / timeout | 后端处理超时 | 增加 timeout_sec 后重试 1 次 |
| HTTP 500 | 服务端内部错误 | 等待 5 秒后重试 1 次 |
| `unauthorized` (401) | Token 过期 | 提示用户重新连接 CamScanner 连接器 |
| `file_id not found` | file_id 已过期或无效 | 重新上传文件 |

### 重试策略

- 所有转换/增强操作均为幂等操作，可安全重试
- 重试间隔：429 → 等 10 秒、500 → 等 5 秒、504 → 增加 timeout_sec
- 重试最多 1 次
- `create_cloud_doc` 重试可能产生重复文档（可接受）
- 认证失败不重试，直接提示用户

---

## 操作限制

1. **文件大小**：上传文件不超过 100MB
2. **支持的图片格式**：JPG、JPEG、PNG
3. **支持的文档格式**：PDF、TXT、Markdown
4. **多图合并上限**：最多 100 张
5. **认证**：由连接器自动管理，用户无需手动操作

---

## 意图消歧规则

当用户表述同时命中多个操作时：

| 冲突场景 | 消歧规则 |
|----------|----------|
| "锐化清晰一点"：enhance vs hd | 若原图模糊/低分辨率 → `image_hd`；若需锐化细节 → `enhance_image` enhance_mode=2；不确定时追问 |
| "识别文字"：TXT vs Markdown vs Word | 追问用户需要什么格式；默认推荐 `convert_image` target_type=md（保留格式） |
| "修复"：restore vs enhance | 提到"老照片/划痕/褪色" → `restore_photo`；否则按具体问题选 enhance 模式 |
| "检测"：篡改 vs AI 生成 | 提到"PS/篡改" → validate_mode=1；提到"AI/生成/假的" → validate_mode=2；不确定时追问 |
| "去水印"：PDF vs 图片 | 按输入文件类型选择（PDF → `remove_watermark_pdf`，图片 → `enhance_image` enhance_mode=10） |

**原则：存在会改变 tool 选择的歧义时，追问用户而非猜测。**

---

## 安全约束

- 认证由连接器管理，Skill 不存储、不记录任何凭据
- 输入文件上传到服务端处理，结果通过 file_id 获取
- 使用 create_cloud_doc 时，结果持久保存到用户账号
- 不使用 create_cloud_doc 时，服务端临时文件按保留策略自动清理
- 禁止将 file_id 作为永久引用——它有时效性，过期后需重新上传