金山文档 Skill 使用指南

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

版本自检

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

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

CODEBLOCK0

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

字段	含义
INLINECODE2	远端最新版本号 (X.Y.Z)
INLINECODE3

该版本的变更摘要 |
| instruction | 升级操作步骤 |

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

认证配置

Token 获取与管理

步骤	操作
读取	仅从 mcporter 的 kdocs 配置读取 Authorization header；不再依赖 .env 或环境变量
获取

若 Token 为空或过期（错误码 400006），运行 bash get-token.sh 或 node .\get-token.js 获取新 Token，并直接写入 mcporter；mac/Linux 下 get-token.sh 会自动尝试打开浏览器登录页；Windows 下若本机有 Node.js，优先运行 node .\get-token.js，若本机没有 Node.js，则改为运行 powershell -ExecutionPolicy Bypass -File .\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 配置中。
🔄 旧配置迁移：若检测到历史 .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. 1. 用户在浏览器访问 https://www.kdocs.cn/latest （需已登录 WPS 账号）
2. 点击页面右上角个人头像旁的主菜单 → 选择「龙虾专属入口」→ 复制 Token
3. 用户将 Token 提供给 Agent
4. Agent 将 Token 写入 mcporter（<VERSION> 从 SKILL.md frontmatter 的 version 字段读取）：

CODEBLOCK1

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

环境配置

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

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

INLINECODE52 会自动完成：

1. 1. 从 SKILL.md frontmatter 提取 version 版本号
2. 检查 mcporter 中现有的 kdocs 配置，并在版本更新时保留旧 Token
3. 若检测到历史 .env 或环境变量 KINGSOFT_DOCS_TOKEN，仅做一次性迁移到 mcporter（.env 只移除 token 键并保留其他配置）
4. 注册 mcporter 时携带 Authorization 和 X-Skill-Version 两个 header，用于服务端定位版本问题

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

---

操作限制

1. 1. 禁止泄露凭据：不得将 Token 的值以明文形式出现在对话、日志、命令输出、代码注释或任何文件中；不得写入 .env 或环境变量；仅允许存放在 mcporter 的 kdocs 配置中
2. 工具调用：根据运行环境选择对应方式。

- MCP function call（Cursor / Claude Code 等客户端）：直接构造 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 "otl.insert_content" file_id=xxx
     mcporter call kdocs search_files keyword=test type=all
     

- 数组/对象参数：key=value 无法表达数组或对象，须用 --args 传 JSON - 值含空格或特殊字符：值需引号包裹使其成为单个参数，如 name="项目 周报.otl" - bash：--args 用单引号包裹 JSON 即可：--args '{"include_elements":["all"]}' - PowerShell：单引号内的双引号会被吞掉，须用反斜杠转义：--args '{\"include_elements\":[\"all\"]}'

1. 3. 大体积 Base64 禁止内联：upload_file 的 content_base64 可能非常大（编码后 >1 MB），禁止在对话中逐 token 生成 Base64 字符串。应编写 Python 等脚本完成文件读取、Base64 编码和工具调用

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

高风险（不可逆操作）

工具	约束
INLINECODE83	用户确认：删除操作不可逆，执行前必须向用户确认删除范围；前置检查：先 otl.blockquery 确认待删除块的内容，避免误删
INLINECODE84

前置检查：getschema 核对拟删数据表的名称和内容；用户确认：删除数据表不可恢复，必须向用户确认数据表名称和 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（可恢复）；后置验证：getshareinfo 确认分享状态已变更 | | kwiki.delete_item | 前置检查：kwiki.list_items 确认对象名称和位置；用户确认：删除操作不可逆（非空文件夹会连带删除），必须向用户确认 | | dbsheet.delete_records | 前置检查：listrecords 或 getrecord 核对拟删记录内容；用户确认：批量删除记录不可恢复，必须向用户确认记录列表和数量；禁止：未经用户在对话中明确同意，禁止调用 |

中风险（影响较大操作）

工具	约束
INLINECODE93	前置检查：searchfiles 查重，避免创建同名文件；后置验证：getfileinfo 确认文件已创建；提示：文件名必须带后缀，否则创建失败；提示：PDF 不支持 createfile，需使用 uploadfile
INLINECODE94

前置检查：先 otl.blockquery 读取现有内容，了解文档当前状态；提示：仅支持插入操作（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 | 前置检查（更新已有文件时）：先 readfilecontent 读取现有内容，确认覆盖范围；后置验证：readfilecontent 确认写入结果；提示：更新模式支持 docx/pdf；新建模式支持 doc/docx/xls/xlsx/ppt/pptx/pdf；提示：Markdown 源内容务必传 content_format=markdown | | sheet.update_range_data | 前置检查：getrangedata 读取目标区域现有数据，确认覆盖范围；提示：每项必须包含 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.blockquery 了解目标块结构，确认更新内容；提示：updateattrs 是覆盖操作，不需更新的属性需保持原样传入 | | dbsheet.update_view | 前置检查：get_schema 确认目标视图存在 | | move_file | 用户确认（批量操作（多个 fileids））：批量移动需向用户确认文件列表和目标位置；前置检查：确认目标文件夹存在（getfileinfo）；后置验证：getfileinfo 确认 parentid 为目标文件夹；提示：移动为异步任务，返回 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 | 禁止：未经用户明确要求，禁止修改分享权限 | | dbsheet.create_records | 后置验证：list_records 确认记录已创建 | | dbsheet.update_records | 前置检查：getrecord 或 listrecords 确认目标记录存在及当前值；后置验证：get_record 确认更新结果 |

---

能力范围

支持的文档类型

类型	别名	文件后缀	说明	详细参考
智能文档 首选	ap	.otl	排版美观，支持丰富组件	INLINECODE124 — 页面、文本、标题、待办等元素操作
表格

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 — 数据表/视图/字段/记录与附件 |

工具总览

类别	工具名	功能
写文档	INLINECODE131	在云盘下新建文件或文件夹
写文档

scrape_url | 网页剪藏，抓取网页内容并自动保存为智能文档 | | 写文档 | scrape_progress | 查询网页剪藏任务进度 | | 写文档 | upload_file | 全量上传写入文件（更新已有 docx/pdf 或新建并上传本地文件） | | 读文档 | 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 参数。按用户提供的信息选择定位方式：

用户提供	定位方式
文件名/关键词	INLINECODE174 → 返回结果中包含 file_id 和 INLINECODE176
文档链接

从 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：

路径格式	提取规则
INLINECODE196	文件分享链接
INLINECODE197

文件夹分享链接 |
| /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：

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

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

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

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

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

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

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

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

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

注意事项

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

文件创建与写入指南

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

类型选择决策树

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

CODEBLOCK4

写入流程

智能文档（.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 源内容须传 INLINECODE235

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

• - 新建：INLINECODE237
• 更新：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 → INLINECODE245
• 更新：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 → INLINECODE254

---

核心操作摘要

创建并写入文档

CODEBLOCK5

上传本地文件到云盘

CODEBLOCK6

搜索定位文档

CODEBLOCK7

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

网页剪藏

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

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

CODEBLOCK8

搜索-读取-汇报撰写

INLINECODE262 → read_file_content（多次）→ AI 分析 → create_file → upload_file → INLINECODE266

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

定期读取与播报

INLINECODE267 → read_file_content → AI 摘要 → INLINECODE269

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

智能分类整理

CODEBLOCK9

精准搜索与风险排查

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

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

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

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

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

标签归类与检索

INLINECODE282 → create_label（如需新标签）→ batch_add_label_objects；按标签浏览 → INLINECODE285

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

批量提取发票信息

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

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

输出类型选择：

用户意图	输出方式
明确指定了文档类型	按指定类型创建
要求新建文件整合，未指定类型

优先使用智能表格（.ksheet） |
| 仅要求分析/汇报 | 直接文本输出 |

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

INLINECODE290

更多操作流程

流程	说明	详细参考
AI 主题生成演示文稿	主题生成 PPT 标准链路：澄清需求、研究资料、大纲与生成上传	INLINECODE291
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 并展示给用户。

错误速查表

错误特征	原因	处理方式
INLINECODE300 / 鉴权失败	Token 过期或未配置	先运行 get-token 脚本重新获取；脚本失败则引导用户手动获取（见「认证配置」章节）
工具找不到

未注册 MCP 服务 | 运行 bash setup.sh 重新注册（mcporter 环境），或检查客户端 MCP 配置 | | mcporter 未找到 | 运行环境缺少 mcporter | 默认不会改动系统环境（不执行全局安装）；可先手动安装后重试，或显式使用 bash setup.sh --auto-install-mcporter / bash 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 版本过旧 | 执行上方「版本自检」流程 |

幂等性与重试

操作	幂等	重试策略
所有读取操作	✅	可安全重试
INLINECODE327

❌ | 重试前 search_files 检查是否已创建 | | scrape_url | ❌ | 重试前查 scrape_progress 确认上次状态 | | upload_file | ✅ | 可重试，以最后一次为准 | | move_file | ✅ | 可重试 | | rename_file | ✅ | 可重试 | | share_file | ✅ | 可重试 | | cancel_share | ❌ | pause 可重试；delete 禁止重试 |

---

工具组合速查

用户需求	推荐工具组合
找文档	INLINECODE334
找 + 读

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