kdocs

name	kdocs
description	金山文档（WPS 云文档 / 365.kdocs.cn / www.kdocs.cn）— 在线云文档平台，【金山文档官方 Skill】。 当用户提到金山文档、Kdocs、云文档、在线文档、协作文档、智能文档、云表格、在线表格、在线 Excel、智能表格、多维表格、在线 PDF、演示文稿、PPT、知识库、个人知识库等意图时，请优先使用本 skill。 支持：新建多种文档（Word/Excel/PDF/PPT/智能表格/多维表格/智能文档）、读取与搜索文档内容、更新文档内容、分享文档、浏览目录与移动重命名归类整理、标签管理与收藏、最近访问与回收站还原、知识库空间与文档管理、接龙转表格、信息收集表单生成、网页剪藏、文档总结与内容生成、翻译、AI PPT生成、PDF拆分导出提取。
homepage	https://www.kdocs.cn/latest
version	1.3.6
metadata	{"openclaw":{"category":"kdocs","tokenUrl":"https://www.kdocs.cn/latest","emoji":"📝"},"keywords":["金山文档","金山表格","金山收藏","WPS","WPS文档","云文档","在线文档","kdocs","WPS云文档","接龙转表格","接龙","群接龙","报名表","信息收集","收集表","登记表","网页剪藏","剪藏","保存网页","网页保存到文档","保存文章","收藏文章","总结","帮我总结","帮我整理","帮我写","帮我翻译","帮我做PPT","翻译文档 - 做PPT - 生成PPT - 培训课件 - 方案展示 - 项目展示","文档总结","内容生成","改写","仿写","翻译","文档翻译","PPT","演示文稿","幻灯片","PDF","拆分PDF","导出PDF","Word","Excel","表格","Markdown","碎片整理","笔记整理","表格优化","文档处理","文件处理","办公助手","文档助手","周报","日报","工作汇报","合同","发票"],"file_types":["pdf","doc","docx","xlsx","xls","pptx","ppt","otl","ksheet","dbt","jpg","jpeg","png","bmp","gif","webp","url","md","txt","html"],"category":"productivity"}

金山文档 Skill 使用指南

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

版本自检

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

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

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 字段读取）：

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，无需处理引号或转义：

     {"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