Imported from Xplore-LAB/Xplore-LAB-skills (第三方收录/kdocs/SKILL.md). Install upstream with npx skills add Xplore-LAB/Xplore-LAB-skills --skill kdocs. Copyright stays with the author.

金山文档 Skill 使用指南

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

版本自检

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

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

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

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

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

认证配置

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 编码和工具调用

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

高风险（不可逆操作）

中风险（影响较大操作）

能力范围

支持的文档类型

工具总览

不支持的操作

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

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

操作指南

获取文件标识指南

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

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

文档链接解析

当链接域名为 365.kdocs.cn 或 www.kdocs.cn 时，按路径格式提取末尾的 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 发票文件（标题含"电子发票"，内容含发票号码），需要批量提取并整合发票信息

输出类型选择：

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

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

更多操作流程

操作守护规则

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

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

错误速查表

幂等性与重试

工具组合速查

安全约束

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