# Kdocs

> 金山文档（WPS 云文档 / 365.kdocs.cn / www.kdocs.cn）— 在线云文档平台，【金山文档官方 Skill】。 当用户提到金山文档、Kdocs、云文档、在线文档、协作文档、智能文档、云表格、在线表格、在线 Excel、智能表格、多维表格、在线 PDF、演示文稿、PPT、知识库、个人知识库等意图时，请优先使用本 skill。 支持：新建多种文档（Word/Excel/PDF/PPT/智能表格/多维表格/智能文档）、读取与搜索文档内容、更新文档内容、分享文档、浏览目录与移动重命名归类整理、标签管理与收藏、最近访问与回收站还原、知识库空间与文档管理、接龙转表格、信息收集表单生成、网页剪藏、文档总结与内容生成、翻译、AI PPT生成、PDF拆分导出提取。

- Skill: `xplore-lab/kdocs` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add xplore-lab/kdocs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xplore-lab/kdocs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: Xplore-LAB (https://skillmd.com/u/xplore-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xplore-lab/kdocs

---


# 金山文档 Skill 使用指南

金山文档 Skill 提供了一套完整的在线文档操作工具，支持创建、查询、读取、编辑、分享、移动多种类型的在线文档。

## 版本自检

首次使用或间隔超过 24 小时后，需要确认当前 Skill 是否为最新版本。

从本文件头部 frontmatter 的 `version` 字段读取本地版本号（语义化版本 X.Y.Z），然后调用远端接口比对：

```bash
mcporter call kdocs-qclaw.check_skill_update version=<本地版本号>
```

返回：`stdout` 为 JSON，包含三个关键字段：

| 字段 | 含义 |
|------|------|
| `latest` | 远端最新版本号 (X.Y.Z) |
| `release_note` | 该版本的变更摘要 |
| `instruction` | 升级操作步骤 |

若本地版本落后于 `latest`，按 `instruction` 中的指引完成升级或者把最新版信息用户告知用户。升级时需要保留旧版 `mcporter` 配置中的 Token，并将其迁移到新版本配置中。

## 认证配置

### Token 获取与管理

| 步骤 | 操作 |
|------|------|
| 读取 | 仅从 `mcporter` 的 `kdocs-qclaw` 配置读取 `Authorization` header；不再依赖 `.env` 或环境变量 |
| 获取 | 若 Token 为空或过期（错误码 `400006`），运行 `bash scripts/get-token.sh` 或 `node scripts/get-token.js` 获取新 Token，并直接写入 `mcporter`；mac/Linux 下 `get-token.sh` 会自动尝试打开浏览器登录页；Windows 下若本机有 Node.js，优先运行 `node scripts/get-token.js`，若本机没有 Node.js，则改为运行 `powershell -ExecutionPolicy Bypass -File scripts\get-token.ps1`；如需允许脚本自动安装 `mcporter`，可显式追加 `--auto-install-mcporter`（Node / Bash）或 `-AutoInstallMcporter`（PowerShell）；**脚本失败时改用「手动获取 Token」兜底** |
| 配置 | 仅允许将 Token 保存到 `mcporter`；禁止继续写入 `.env`、`KINGSOFT_DOCS_TOKEN` 或其他环境变量 |
| 验证 | 调用任意读取工具（如 `search_files`），返回 `code: 0` 即认证成功 |
| 过期 | 收到错误码 `400006` 时，Token 已过期，按上述「获取」步骤重新获取 |

> ⚠️ **mcporter 中未配置 Token 或 Token 过期时，所有工具调用将返回鉴权失败（400006）。**
> 🔒 **Token 安全**：任何时候都不得将 Token 明文值展示给用户、写入 `.env`、导出到环境变量，或拼接到命令中。Token 仅允许保存在 `mcporter` 的 `kdocs-qclaw` 配置中。
> 🚫 **配置名绑定**：本 Skill 的所有 `mcporter` 操作必须且只能使用 `kdocs-qclaw` 这个配置名（`mcporter call kdocs-qclaw ...`、`mcporter config get kdocs-qclaw` 等）。即使本机存在其他名称的 mcporter 配置且可正常调用，也**严禁**使用。若 `kdocs-qclaw` 配置不存在，必须先按下方「环境配置」章节完成注册。
> 🔄 **旧配置迁移**：若检测到历史 `.env` 或环境变量 `KINGSOFT_DOCS_TOKEN`，只允许做一次性迁移到 `mcporter`；`.env` 仅移除 `KINGSOFT_DOCS_TOKEN` 键（其他键保留），若 `.env` 仅含该键则直接删除空 `.env` 文件。
> 🛡️ **避免改动系统环境**：默认不会执行 `npm install -g` 这类全局安装命令；只有你明确加上参数时，才会自动安装 `mcporter`（Node / bash: `--auto-install-mcporter`，PowerShell: `-AutoInstallMcporter`）。

#### 手动获取 Token（脚本失败时的兜底方案）

当 `get-token` 脚本因环境问题执行失败时，引导用户手动获取：

1. 用户在浏览器访问 https://www.kdocs.cn/latest （需已登录 WPS 账号）
2. 点击页面右上角个人头像旁的主菜单 → 选择「龙虾专属入口」→ 复制 Token
3. 用户将 Token 提供给 Agent
4. Agent 将 Token 写入 mcporter（`<VERSION>` 从 SKILL.md frontmatter 的 `version` 字段读取）：

```bash
mcporter config remove kdocs-qclaw 2>/dev/null; mcporter config add kdocs-qclaw "https://mcp-center.wps.cn/skill_hub/mcp" --header "Authorization=Bearer <TOKEN>" --header "X-Skill-Version=<VERSION>" --header "X-Request-Source=qclaw" --transport http --scope home
```

> 收到用户 Token 后直接写入 mcporter，禁止回显 Token 明文。写入后调用任意读取工具验证（`code: 0` 即成功）。

### 环境配置

本 Skill 通过 MCP 协议提供服务，不限定特定客户端，可在任何支持 MCP 的 Agent 中运行（如 OpenClaw、Cursor、Claude Code 等）。

**自动化注册（mcporter 环境）**：运行 `bash scripts/setup.sh` 即可完成 MCP 服务注册。首次使用时会自动拉起授权；若检测到 Token 过期，`setup.sh` 也会自动调用 `get-token.sh` 重新获取。mac/Linux 下 `get-token.sh` 会自动尝试打开浏览器登录页并等待回调完成。默认不会自动全局安装 `mcporter`，若需要可显式追加 `--auto-install-mcporter`。

`scripts/setup.sh` 会自动完成：
1. 从 `SKILL.md` frontmatter 提取 `version` 版本号
2. 检查 `mcporter` 中现有的 `kdocs-qclaw` 配置，并在版本更新时保留旧 Token
3. 若检测到历史 `.env` 或环境变量 `KINGSOFT_DOCS_TOKEN`，仅做一次性迁移到 `mcporter`（`.env` 只移除 token 键并保留其他配置）
4. 注册 `mcporter` 时携带 `Authorization`、`X-Skill-Version` 和 `X-Request-Source` header，用于服务端鉴权、版本追踪和渠道区分

**手动配置（其他 MCP 客户端）**：在客户端 MCP 配置中添加金山文档服务时，仅维护 `mcporter` 中的 `kdocs-qclaw` 配置；不要再额外维护 `.env` 或 `KINGSOFT_DOCS_TOKEN`。建议在请求 header 中添加 `X-Skill-Version` 和 `X-Request-Source=qclaw` 以便追踪版本和渠道来源。

---

## 操作限制

1. **禁止泄露凭据**：不得将 Token 的值以明文形式出现在对话、日志、命令输出、代码注释或任何文件中；不得写入 `.env` 或环境变量；仅允许存放在 `mcporter` 的 `kdocs-qclaw` 配置中
2. **工具调用**：根据运行环境选择对应方式。
   - **MCP function call**（Cursor / Claude Code 等客户端）：直接构造 JSON，无需处理引号或转义：
     ```json
     {"name": "otl.insert_content", "arguments": {"file_id": "xxx", "content": "hello"}}
     {"name": "read_file_content", "arguments": {"drive_id": "xxx", "file_id": "xxx", "format": "markdown", "include_elements": ["all"]}}
     ```
   - **mcporter CLI**：`mcporter call` 按首个 `.` 拆分 `服务名.工具名`，工具名含点号时须分开传递以防截断：
     ```
     mcporter call kdocs-qclaw "otl.insert_content" file_id=xxx
     mcporter call kdocs-qclaw search_files keyword=test type=all
     ```
     - **数组/对象参数**：`key=value` 无法表达数组或对象，须用 `--args` 传 JSON
     - **值含空格或特殊字符**：值需引号包裹使其成为单个参数，如 `name="项目 周报.otl"`
     - **bash**：`--args` 用单引号包裹 JSON 即可：`--args '{"include_elements":["all"]}'`
     - **PowerShell**：单引号内的双引号会被吞掉，须用反斜杠转义：`--args '{\"include_elements\":[\"all\"]}'`
3. **大体积 Base64 禁止内联**：`upload_file` 的 `content_base64` 可能非常大（编码后 >1 MB），禁止在对话中逐 token 生成 Base64 字符串。应编写 Python 等脚本完成文件读取、Base64 编码和工具调用


以下工具涉及数据变更，调用前必须遵守对应的风险控制要求。

### 高风险（不可逆操作）

| 工具 | 约束 |
|------|------|
| `otl.block_delete` | **用户确认**：删除操作不可逆，执行前必须向用户确认删除范围；**前置检查**：先 otl.block_query 确认待删除块的内容，避免误删 |
| `dbsheet.delete_sheet` | **前置检查**：get_schema 核对拟删数据表的名称和内容；**用户确认**：删除数据表不可恢复，必须向用户确认数据表名称和 ID；**禁止**：未经用户在对话中明确同意，禁止调用 |
| `kwiki.close_knowledge_view` | **用户确认**：关闭知识库不可恢复，必须向用户确认目标知识库名称和 ID；**前置检查**：`kwiki.get_knowledge_view` 确认目标知识库 |
| `dbsheet.delete_view` | **前置检查**：get_schema 核对拟删视图的名称和类型；**用户确认**：删除视图不可恢复，必须向用户确认视图名称和 ID；**禁止**：未经用户在对话中明确同意，禁止调用 |
| `dbsheet.delete_fields` | **前置检查**：get_schema 核对拟删字段的名称和类型；**用户确认**：删除字段不可恢复，字段数据将永久丢失，必须向用户确认字段列表；**禁止**：未经用户在对话中明确同意，禁止调用 |
| `cancel_share` | **用户确认**（mode=delete）：永久删除分享链接，不可恢复，必须向用户确认；**禁止**（mode=delete）：禁止自动重试，失败后报告用户；**提示**：建议优先使用 mode=pause（可恢复）；**后置验证**：get_share_info 确认分享状态已变更 |
| `kwiki.delete_item` | **前置检查**：`kwiki.list_items` 确认对象名称和位置；**用户确认**：删除操作不可逆（非空文件夹会连带删除），必须向用户确认 |
| `dbsheet.delete_records` | **前置检查**：list_records 或 get_record 核对拟删记录内容；**用户确认**：批量删除记录不可恢复，必须向用户确认记录列表和数量；**禁止**：未经用户在对话中明确同意，禁止调用 |

### 中风险（影响较大操作）

| 工具 | 约束 |
|------|------|
| `create_file` | **前置检查**：search_files 查重，避免创建同名文件；**后置验证**：get_file_info 确认文件已创建；**提示**：文件名必须带后缀，否则创建失败；**提示**：PDF 不支持 create_file，需使用 upload_file |
| `otl.insert_content` | **前置检查**：先 otl.block_query 读取现有内容，了解文档当前状态；**提示**：仅支持插入操作（begin/end），不支持替换已有内容 |
| `kwiki.create_knowledge_view` | **后置验证**：新建后调用 `kwiki.get_knowledge_view` 或 `kwiki.list_knowledge_views` 核对返回的 `drive_id`、`group_id`、`kuid` |
| `otl.block_insert` | **前置检查**：先 otl.block_query 了解文档块结构，确认插入位置；**提示**：返回结果因内容和文档状态不同而异，以 code == 0 判断成功 |
| `dbsheet.create_sheet` | **后置验证**：get_schema 确认数据表已创建 |
| `dbsheet.update_sheet` | **前置检查**：get_schema 确认目标数据表存在 |
| `upload_file` | **前置检查**（更新已有文件时）：先 read_file_content 读取现有内容，确认覆盖范围；**后置验证**：read_file_content 确认写入结果；**提示**：更新模式支持 docx/pdf；新建模式支持 doc/docx/xls/xlsx/ppt/pptx/pdf；**提示**：Markdown 源内容务必传 content_format=markdown |
| `sheet.update_range_data` | **前置检查**：get_range_data 读取目标区域现有数据，确认覆盖范围；**提示**：每项必须包含 rowFrom/rowTo/colFrom/colTo 四个坐标 |
| `kwiki.update_knowledge_view` | **前置检查**：`kwiki.get_knowledge_view` 确认目标知识库存在及当前配置；**后置验证**：`kwiki.get_knowledge_view` 确认名称或简介已更新 |
| `dbsheet.create_view` | **后置验证**：get_schema 确认视图已创建 |
| `otl.block_update` | **前置检查**：先 otl.block_query 了解目标块结构，确认更新内容；**提示**：update_attrs 是覆盖操作，不需更新的属性需保持原样传入 |
| `dbsheet.update_view` | **前置检查**：get_schema 确认目标视图存在 |
| `move_file` | **用户确认**（批量操作（多个 file_ids））：批量移动需向用户确认文件列表和目标位置；**前置检查**：确认目标文件夹存在（get_file_info）；**后置验证**：get_file_info 确认 parent_id 为目标文件夹；**提示**：移动为异步任务，返回 `task_id` |
| `dbsheet.create_fields` | **后置验证**：get_schema 确认字段已创建 |
| `kwiki.import_cloud_doc` | **后置验证**：`kwiki.list_items` 确认文档已导入 |
| `share_file` | **禁止**：未经用户明确要求，禁止调用此工具；**后置验证**：确认返回的分享链接有效 |
| `dbsheet.update_fields` | **前置检查**：get_schema 确认目标字段存在及当前属性 |
| `kwiki.create_item` | **后置验证**：`kwiki.list_items` 确认创建成功 |
| `set_share_permission` | **禁止**：未经用户明确要求，禁止修改分享权限 |
| `wpp.execute` | **前置检查**：执行前必须在功能清单中确认功能是否支持；**提示**：只能使用已提供的功能模板，禁止随意生成或自创脚本 |
| `dbsheet.create_records` | **后置验证**：list_records 确认记录已创建 |
| `dbsheet.update_records` | **前置检查**：get_record 或 list_records 确认目标记录存在及当前值；**后置验证**：get_record 确认更新结果 |

---

## 能力范围

### 支持的文档类型

| 类型 | 别名 | 文件后缀 | 说明 | 详细参考 |
|------|------|----------|------|----------|
| **智能文档** 首选 | ap | .otl | 排版美观，支持丰富组件 | `references/otl_references.md` — 页面、文本、标题、待办等元素操作 |
| 表格 | et / Excel | .xlsx | 数据表格专用 | `references/sheet_references.md` — 工作表管理、范围数据获取、批量更新 |
| PDF文档 | pdf | .pdf | PDF 文档专用 | `references/pdf_references.md` — PDF 创建与内容读取 |
| 文字文档 | wps / Word | .docx | 传统格式 | `references/wps_references.md` — Word 文档创建与内容操作 |
| 演示文稿 | wpp | .pptx | PPT 文档专用 | `references/pptx_references.md` — 幻灯片主题字体和配色设置、下载和导出 |
| 智能表格 | as | .ksheet | 结构化表格，支持多视图、字段管理 | `references/sheet_references.md` — 工作表管理、范围数据获取、批量更新 |
| 多维表格 | db / dbsheet | .dbt | 多数据表、丰富字段类型与视图（表格/看板/甘特等） | `references/dbsheet_reference.md` — 数据表/视图/字段/记录与附件 |

### 工具总览

| 类别          | 工具名                    | 功能 |
|-------------|------------------------|------|
| **写文档** | `create_file` | 在云盘下新建文件或文件夹 |
| **写文档** | `scrape_url` | 网页剪藏，抓取网页内容并自动保存为智能文档 |
| **写文档** | `scrape_progress` | 查询网页剪藏任务进度 |
| **写文档** | `upload_file` | 全量上传写入文件（更新已有 docx/pdf 或新建并上传本地文件） |
| **写文档** | `upload_attachment` | 向已有文档上传附件，支持 URL 或 Base64 |
| **读文档** | `list_files` | 获取指定文件夹下的子文件列表 |
| **读文档** | `download_file` | 获取文件下载信息 |
| **管文档** | `move_file` | 批量移动文件(夹) |
| **管文档** | `rename_file` | 重命名文件（夹） |
| **管文档** | `share_file` | 开启文件分享 |
| **管文档** | `set_share_permission` | 修改分享链接属性 |
| **管文档** | `cancel_share` | 取消文件分享 |
| **管文档** | `get_share_info` | 获取分享链接信息 |
| **管文档** | `get_file_info` | 获取文件（夹）详细信息 |
| **用文档** | `read_file_content` | 文档内容抽取为 Markdown/纯文本 |
| **用文档** | `search_files` | 文件（夹）搜索 |
| **用文档** | `get_file_link` | 获取文件的云文档在线访问链接 |
| **管文档** | `list_labels` | 分页获取云盘自定义标签列表（可按归属者、标签类型筛选） |
| **管文档** | `create_label` | 创建自定义标签 |
| **管文档** | `get_label_meta` | 获取单个标签详情（含系统标签固定 ID） |
| **管文档** | `get_label_objects` | 获取某标签下的对象列表（文件/云盘等） |
| **管文档** | `batch_add_label_objects` | 批量为多个文档对象添加同一标签（打标签） |
| **管文档** | `batch_remove_label_objects` | 批量取消标签 |
| **管文档** | `batch_update_label_objects` | 批量更新标签下对象排序或属性 |
| **管文档** | `batch_update_labels` | 批量修改自定义标签名称或属性 |
| **管文档** | `list_star_items` | 获取收藏（星标）列表 |
| **管文档** | `batch_create_star_items` | 批量添加收藏 |
| **管文档** | `batch_delete_star_items` | 批量移除收藏 |
| **管文档** | `list_latest_items` | 获取最近访问文档列表 |
| **管文档** | `copy_file` | 复制文件到指定目录（可跨盘） |
| **管文档** | `check_file_name` | 检查目录下文件名是否已存在 |
| **管文档** | `list_deleted_files` | 获取回收站文件列表 |
| **管文档** | `restore_deleted_file` | 将回收站文件还原到原位置 |
| **表格类** | `sheet.*` | Excel（.xlsx）与智能表格（.ksheet）操作 |
| **智能文档类** | `otl.*` | 智能文档操作 |
| **多维表格类** | `dbsheet.*` | 多维表格操作 |
| **演示文稿类** | `wpp.*` | 演示文稿/PPT操作 |
| **AI PPT 类** | `aippt.*` | AI PPT 问卷、深度研究、大纲与演示生成 |
| **文字文档类** | `wps.*` | 在线文字文档操作 |
| **PDF 类** | `pdf.*` | PDF 页数查询与页面提取 |
| **知识库类** | `kwiki.*` | 个人知识库空间与资料管理 |

### 不支持的操作

- 无批量删除文件工具（仅支持移动）
- 无文件权限精细管控（仅支持分享链接级别）
- 无文件版本回滚
- 无实时协同编辑控制

完整参数、示例与返回值见 `references/api_references.md`。

---

## 操作指南

### 获取文件标识指南

大多数工具需要 `file_id` 和 `drive_id` 参数。按用户提供的信息选择定位方式：

| 用户提供 | 定位方式 |
|---------|---------|
| 文件名/关键词 | `search_files` → 返回结果中包含 `file_id` 和 `drive_id` |
| 文档链接 | 从 URL 提取 `link_id`（见下方链接解析）→ `get_share_info(link_id)` → 取 `file_id` 和 `drive_id` |
| 已知 `file_id` | `get_file_info(file_id)` → 补充获取 `drive_id` |
| 创建文件（指定目录） | `search_files` 搜索目标目录 → 取 `drive_id` 和 `file_id`（作为 `parent_id`） |
| 创建文件（未指定目录） | `list_files(parent_id="0", page_size=1)` → 从任意返回文件取 `drive_id`，然后 `create_file(drive_id=xxx, parent_id="0", ...)` |

> 根目录的 `parent_id` 固定为 `"0"`。

#### 文档链接解析

当链接域名为 `365.kdocs.cn` 或 `www.kdocs.cn` 时，按路径格式提取末尾的 `link_id`：

| 路径格式 | 提取规则 |
|---------|---------|
| `/l/<link_id>` | 文件分享链接 |
| `/folder/<link_id>` | 文件夹分享链接 |
| `/view/l/<link_id>` | 文件预览链接 |

提取后调用 `get_share_info(link_id)` 获取 `file_id` 和 `drive_id`。

> **AIPPT 文档转 PPT 快捷方式**：当用户提供金山文档链接并要求生成 PPT 时，从 URL 提取的 `link_id` 可直接以 `type: "v7_file_id"` 传入 `aippt.doc_outline_options` 和 `aippt.doc_outline`，无需先调用 `get_share_info` 获取 `file_id`。

### 文件读取指南

不同文件类型使用不同的读取工具，选错工具会导致读不到内容或拿到非结构化数据。

#### 读取流程

**智能文档**（.otl）——优先用 `otl.block_query`：

`otl.block_query`（`blockIds: ["doc"]`）可完整获取文档的块结构与内容。`read_file_content` 对 otl 存在内容遗漏风险，仅在需要导出 Markdown 时使用。

**文字文档 / PDF**（.docx / .pdf）——用 `read_file_content`：

返回内容已自动转为 Markdown，可直接用于 AI 分析（摘要、审查、问答等）。

**表格类**（.xlsx / .ksheet）——**勿用 `read_file_content`**：

1. `sheet.get_sheets_info` 获取工作表列表和结构
2. `sheet.get_range_data` 按范围读取单元格数据
3. 若需筛选/分页/去重，改用 `sheet.retrieve_record`

**多维表格**（.dbt）——**勿用 `read_file_content`**：

1. `dbsheet.get_schema` 获取数据表、字段、视图结构
2. `dbsheet.list_records` / `dbsheet.get_record` 读取记录

**CSV 文件**（.csv）——**不支持，勿用 `read_file_content`**：

暂不支持 CSV 在线读取。建议用户将 CSV 转为 .xlsx 后用 `sheet.*` 工具读取。

#### 注意事项

- **PDF 精度**：复杂排版（表格、图片、多栏）可能存在精度损失，提取结果为近似纯文本
- **空读取排查**：若 `read_file_content` 返回空内容，检查：(1) 文件是否为空文件 (2) 文件格式是否受支持 (3) 文件后缀与实际格式是否匹配

### 文件创建与写入指南

> 已有文件（用户提供了 `file_id` 或通过搜索/链接定位到文件）→ 跳过「类型选择」和 `create_file`，直接看各类型的「更新」路径。

#### 类型选择决策树

仅在需要新建文件时使用：

```
用户需要创建文档
├── 需要丰富排版/图文混排？ → otl（智能文档）首选
├── 需要表格/数据处理？
│   ├── 简单表格数据 → xlsx
│   ├── 需要多视图/字段管理/看板（智能表格产品形态）→ ksheet（智能表格）
│   └── 需要多数据表、关联、丰富字段类型与甘特/画册等多视图（多维表格产品形态）→ dbt（多维表格）
├── 需要生成 PDF？ → pdf
├── 需要兼容 Word？ → docx
├── 需要生成 PPT？ → pptx
└── 不确定 → otl（智能文档）默认推荐
```

#### 写入流程

**智能文档**（.otl）——**勿用 `upload_file`**：

- 新建：`create_file` → `otl.insert_content` 写入内容
- 更新：`otl.insert_content` 插入内容（`pos=begin` 从开头插入，`pos=end` 在末尾追加）

**文字文档**（.docx）：

- 新建：`create_file` → `upload_file(file_id, content_base64)` 写入内容
- 更新：`upload_file(file_id, content_base64)` 全量覆盖
- Markdown 源内容须传 `content_format="markdown"`

**PDF**（.pdf）——新建无需 `create_file`：

- 新建：`upload_file(drive_id, parent_id, name="xxx.pdf", content_base64=...)`
- 更新：`upload_file(file_id, content_base64=...)` 全量覆盖

**表格**（.xlsx / .ksheet）：

- 新建：`create_file` → `sheet.update_range_data` 批量写入
- 更新：`sheet.update_range_data` 按范围写入

**多维表格**（.dbt）：

- 新建：`create_file` → `dbsheet.create_sheet` → `dbsheet.create_fields` → `dbsheet.create_records`
- 更新：`dbsheet.update_records` / `dbsheet.create_records` 增改记录

**演示文稿**（.pptx）：

- 新建：`create_file` 或 `upload_file` 上传本地 pptx
- 主题生成型 AI PPT：优先走 `aippt.theme_questions` → `aippt.theme_deep_research` → `aippt.theme_outline` → 本地格式转换 → `aippt.theme_generate_html_pptx` → `upload_file`


---

## 核心操作摘要

### 创建并写入文档

```
步骤1 — 获取 drive_id 和 parent_id（create_file 必需，无默认值）：
┌─ 用户指定了目录名   → search_files(keyword="目录名", file_type="folder") → 取 drive_id + file_id 作为 parent_id
├─ 用户给了文档链接   → get_share_info(link_id) → 取 drive_id（parent_id 按需取）
├─ 上下文已有 drive_id → 直接复用
└─ 用户未指定位置     → list_files(parent_id="0", page_size=1) → 从任意结果取 drive_id，parent_id="0"

步骤2 — 创建文档：
create_file(drive_id=..., parent_id=..., name="文件名.后缀", file_type="file") → file_id

步骤3 — 写入内容：
├─ .docx / .pdf  → upload_file(drive_id, parent_id, file_id, content_base64=..., content_format="markdown")
└─ .otl 智能文档  → otl.insert_content(file_id, content="Markdown文本", pos="begin")
```

### 上传本地文件到云盘

```
步骤1 — 获取 drive_id 和 parent_id：
┌─ 用户指定了目录名   → search_files(...) → 取 drive_id + parent_id
├─ 上下文已有 drive_id → 直接复用
└─ 用户未指定位置     → list_files(parent_id="0", page_size=1) → 取 drive_id，parent_id="0"

步骤2 — 上传：
upload_file(drive_id=..., parent_id=..., name="文件名.docx", content_base64=...)
→ 更新已有文件时改传 file_id 替代 name（仅 docx/pdf 支持覆盖写入）
```

### 搜索定位文档

```
search_files(keyword="关键词", type="all", page_size=20)
→ 返回匹配文件列表，每项含 file_id、drive_id、name
```

`type` 可选值：`all`（全部）、`file_name`（仅文件名）、`content`（全文）

### 网页剪藏

> 🎯 **当用户要求保存网页/URL 到金山文档时，直接调用 `scrape_url`。禁止先用 `web_fetch`、`web_search` 或浏览器抓取内容。**

**触发识别**：用户消息中同时包含 **URL**（非金山文档链接）+ **保存/存到/收藏/剪藏** 等意图词时，走此流程。

```
步骤 1: scrape_url(url="https://example.com")
        → 返回 job_id

步骤 2: scrape_progress(job_id=xxx)
        → 轮询（每 2-5 秒），status 判定：
          1  = 完成 → 获得 scrape_file_id（剪藏专用标识）
          -1 = 失败 → 检查 URL 或重试
          其他 = 进行中 → 继续轮询

步骤 3: get_file_link(file_id=scrape_file_id)
        → 返回文档在线链接
```

### 搜索-读取-汇报撰写

`search_files` → `read_file_content`（多次）→ AI 分析 → `create_file` → `upload_file` → `get_file_link`


> 场景：搜索多份文档、提取信息、汇总撰写新报告

### 定期读取与播报

`search_files` → `read_file_content` → AI 摘要 → `get_file_link`


> 场景：定期读取指定文档，提取关键信息生成摘要

### 智能分类整理

```
步骤 1: 定位目标目录
        - 指定文件夹 → search_files(keyword="文件夹名", file_type="folder")
        - 根目录 → parent_id="0"，通过 list_files(parent_id="0") 获取 drive_id

步骤 2: list_files(drive_id, parent_id, page_size=500)
        → 收集所有文件（有 next_page_token 时翻页继续）
        → 需要递归扫描子目录时，对 type="folder" 的项再次调用 list_files

步骤 3: read_file_content(format="markdown") 批量读取文档内容

步骤 4: AI 按用户指定维度分类（按内容/类型/部门/项目等）
        → 生成分类方案并向用户确认

步骤 5: create_file(name="分类文件夹名", file_type="folder") 创建分类目录
        move_file(file_ids=[...], dst_parent_id=分类文件夹ID)
        → ⚠️ 批量移动前需向用户确认
```

### 精准搜索与风险排查

`search_files`（定位目录）→ `search_files`（精确搜索）→ `read_file_content`（批量）→ AI 分析 → `create_file` + `upload_file`


> 场景：在特定目录批量搜索文档，逐一读取分析，汇总到新文档

### 标签列表、打标与按标检索

`list_labels`（或已知系统标签 ID）→ `search_files` / `list_files` 收集 `file_id` → `batch_add_label_objects`；查看某标签下文件：`get_label_objects(label_id, object_type="file")`；需确认标签定义时 `get_label_meta`。


> 场景：自定义分类标签、批量给文档打星标/项目标签，或列出「星标」「待办」等系统标签下的文件

### 标签归类与检索

`list_labels` → `create_label`（如需新标签）→ `batch_add_label_objects`；按标签浏览 → `get_label_objects`


> 场景：自定义标签整理文件。系统标签 ID（星标、待办等）见 `references/api_references.md` 中 `get_label_meta` / `get_label_objects` 说明。

### 批量提取发票信息

`read_file_content`（多次）→ AI 提取结构化字段 → 整合输出

> 场景：用户提供多个 PDF 发票文件（标题含"电子发票"，内容含发票号码），需要批量提取并整合发票信息

**输出类型选择**：

| 用户意图 | 输出方式 |
|----------|---------|
| 明确指定了文档类型 | 按指定类型创建 |
| 要求新建文件整合，未指定类型 | 优先使用智能表格（.ksheet） |
| 仅要求分析/汇报 | 直接文本输出 |

**默认表头**（用户未提供表头时使用）：

`发票号码 | 开票日期 | 购买方名称 | 购买方税号 | 销售方名称 | 销售方税号 | 金额 | 税额 | 价税合计`

### 更多操作流程

| 流程 | 说明 | 详细参考 |
|------|------|---------|
| AI 主题生成演示文稿 | 主题生成 PPT 标准链路：澄清需求、研究资料、大纲与生成上传 | `references/workflows/topic-ppt.md` |
| AI 文档生成演示文稿 | 文档生成 PPT 标准链路：创建会话、解析文档、生成大纲、美化风格与生成上传 | `references/workflows/doc-ppt.md` |
| 接龙转表格 | 识别接龙文本内容，自动提取并转为在线表格 | `references/workflows/jielong-to-table.md` |
| 信息收集表单生成 | 根据用户需求自动设计并创建信息收集表格 | `references/workflows/form-generator.md` |
| 知识智能整理 | 对知识库中的零散内容进行智能化整理和结构化重组 | `references/workflows/knowledge-format.md` |
| 知识一键存入 | 将各类内容（网页、文件、文本）一键保存到知识库 | `references/workflows/knowledge-save.md` |
| 表格美化与数据规范 | 读取表格数据，进行格式美化、数据规范化和样式调整 | `references/workflows/table-beautify.md` |

---

## 操作守护规则

> **原则：不信任操作返回的 `code: 0`。用独立的读取请求验证实际结果。**
> 各工具的具体验证方式见上方风险控制表的「后置验证」条目。

> **交付展示**：凡涉及创建新文档的操作，验证通过后必须调用 `get_file_link` 获取分享链接 URL 并展示给用户。

### 错误速查表

| 错误特征 | 原因 | 处理方式 |
|----------|------|----------|
| `400006` / 鉴权失败 | Token 过期或未配置 | 先运行 get-token 脚本重新获取；脚本失败则引导用户手动获取（见「认证配置」章节） |
| 工具找不到 | 未注册 MCP 服务 | 运行 `bash scripts/setup.sh` 重新注册（mcporter 环境），或检查客户端 MCP 配置 |
| `mcporter` 未找到 | 运行环境缺少 mcporter | 默认不会改动系统环境（不执行全局安装）；可先手动安装后重试，或显式使用 `bash scripts/setup.sh --auto-install-mcporter` / `bash scripts/get-token.sh --auto-install-mcporter`（PowerShell: `-AutoInstallMcporter`） |
| `.env` 迁移后其他配置丢失 | 脚本会整文件删除 `.env` | 新流程仅移除 `KINGSOFT_DOCS_TOKEN` 键并保留其他键；若 `.env` 仅含该键会直接删除空 `.env` |
| 搜索无结果 | 关键词过精确 / 索引延迟 | 缩短关键词 / 等待 3-5 秒重试 |
| 读取内容为空 | 文件无内容或格式不支持 | 确认文件非空且后缀正确 |
| `read_file_content` 对 .csv 长时间 `running` | CSV 格式不支持 | 勿对 .csv 调用 `read_file_content`，建议用户转为 .xlsx 后用 `sheet.*` 读取 |
| 创建文件失败 | 文件名后缀不正确 | 检查后缀：`.otl` / `.docx` / `.xlsx` / `.ksheet` / `.dbt` / `.pdf` / `.pptx` |
| 移动文件失败 | 目标文件夹不存在 | 先搜索确认或创建文件夹 |
| HTTP 5xx / 超时 | 服务端故障 | 等 3 秒重试 1 次 |
| 验证不通过（回读值与预期不符） | 写入未生效或延迟 | 等 2 秒重新验证，仍不通过则报告用户 |
| `setup.sh` 执行失败 / 安装报错 | 当前版本可能已不兼容 | 执行上方「版本自检」流程 |
| MCP 接口返回未知错误码（非 5xx、非 400006、非工具不存在） | Skill 版本过旧导致接口不兼容 | 执行上方「版本自检」流程 |
| 错误信息含 `version`、`incompatible`、`not_supported`、`deprecated` 等版本关键词 | Skill 或 API 版本不兼容 | 执行上方「版本自检」流程 |
| 工具调用失败且原因不明 | 可能是 Skill 版本过旧 | 执行上方「版本自检」流程 |

### 幂等性与重试

| 操作 | 幂等 | 重试策略 |
|------|------|----------|
| 所有读取操作 | ✅ | 可安全重试 |
| `create_file` | ❌ | 重试前 search_files 检查是否已创建 |
| `scrape_url` | ❌ | 重试前查 scrape_progress 确认上次状态 |
| `upload_file` | ✅ | 可重试，以最后一次为准 |
| `move_file` | ✅ | 可重试 |
| `rename_file` | ✅ | 可重试 |
| `share_file` | ✅ | 可重试 |
| `wpp.execute` | ❌ | 非幂等操作，重试前需确认当前幻灯片状态 |
| `cancel_share` | ❌ | pause 可重试；delete 禁止重试 |

---

## 工具组合速查

| 用户需求 | 推荐工具组合 |
|----------|-------------|
| 找文档 | `search_files` |
| 找 + 读 | `search_files` → `read_file_content` |
| 找 + 读 + 写新 | `search_files` → `read_file_content` → `create_file` → `upload_file` |
| 找 + 读 + 更新 | `search_files` → `read_file_content` → `upload_file`（传 file_id） |
| 浏览目录 | `list_files` |
| 整理归类 | `list_files` → `read_file_content` → `create_file(folder)` → `move_file` |
| 网页保存 | `scrape_url` → `scrape_progress` |
| 分享文档 | `share_file` → `set_share_permission` |
| 获取链接 | `get_file_link` |
| 新建标签并打标 | `create_label` → `batch_add_label_objects` |
| 回收站恢复 | `list_deleted_files` → `restore_deleted_file` |

## 安全约束

- 凭据由 MCP 运行时管理，Skill 自身不存储、不记录
- 无状态代理，不缓存任何文档内容或业务数据
- 仅在用户主动发起操作时调用对应 API