金山文档 CLI Skill 使用指南

金山文档 CLI Skill 提供了一套完整的在线文档操作工具，通过 kdocs-cli 命令行工具与金山文档 API 交互。支持创建、查询、读取、编辑、分享、移动多种类型的在线文档。

严格规则

禁止（NEVER）

• 禁止将 Token 明文出现在对话、日志、命令输出、代码注释或任何文件中；Token 仅允许通过 kdocs-cli auth set-token 或 kdocs-cli auth login 保存到系统密钥链
• 上传写入等接口需传入的 content_base64 可能非常大（编码后 >1 MB），禁止在对话中逐 token 生成 Base64 字符串，用脚本完成文件读取、编码和传参

必须（MUST）

• 不可逆操作（delete/close 类）执行前必须向用户确认
• 写操作完成后必须用独立读取请求验证实际结果（不信任 code: 0）
• 创建文档并验证通过后，必须调用 get_file_link 获取链接并展示给用户
• 通过 --file 或脚本创建的临时 JSON 文件（如 payload.json、temp.json），在整个操作流程结束后必须删除，避免残留在用户工作目录

保持最新版本

何时触发：首次使用 Skill / 距上次自检 >24h / 收到 unknown action 或 unknown service 错误。

1. CLI 版本：kdocs-cli version — 若命令不存在则按下方「工具安装与认证」安装；若低于本文件 frontmatter version，运行 kdocs-cli upgrade -y（自动备份旧版本，失败可 kdocs-cli upgrade --rollback）
2. Skill 版本：若本文件 version 低于 kdocs-cli version，运行 kdocs-cli call check_skill_update version=<本文件version>，若返回 update_available: true，从 instruction 中提取 zip 下载链接（格式 https://...kdocs.zip），下载解压替换当前 Skill 目录

若 upgrade 和 rollback 均失败，在本 Skill 目录下重新运行安装脚本（bash setup.sh / powershell setup.ps1 / node setup.cjs，脚本位于 scripts/）可从 CDN 重新安装。若仍无法更新，以 kdocs-cli --help 实际支持的工具集为准。

工具安装与认证

login 失败时的手动获取流程、auth status 诊断、auth logout 退出等详见 references/auth.md。

调用格式

kdocs-cli <service> <action> [参数]

参数传递

• --file / stdin 输入必须是该工具的完整 JSON 参数对象
• 中文/多行参数禁止 key=value（Windows/PowerShell 破坏 UTF-8 编码）
• 生成 JSON 文件用 Node.js/Python；禁止 ConvertTo-Json（输出带 BOM）
• PowerShell 传 JSON 字符串须反斜杠转义：'{\"key\":[\"val\"]}'

--file 示例：写入大段内容时，用脚本生成 JSON 文件再 --file 传入，操作完成后删除临时文件：

const fs = require('fs');
fs.writeFileSync('payload.json', JSON.stringify({
  file_id: "<file_id>",
  content: fs.readFileSync('article.md', 'utf8'),
  format: "markdown",
  mode: "append"
}), 'utf8');

kdocs-cli otl insert-content --file payload.json --silent

// 操作完成后清理临时文件
fs.unlinkSync('payload.json');

全局选项：

帮助：kdocs-cli --help、kdocs-cli <service> --help、kdocs-cli <service> <action> --help

以下工具不可逆，调用前必须向用户确认（详细约束见各工具参考文档的「操作约束」区）：

otl.block_delete、dbsheet.delete_sheet、kwiki.close_knowledge_view、sheet.delete_sheets、sheet.delete_range、dbsheet.delete_view、dbsheet.delete_fields、cancel_share、kwiki.delete_item、sheet.delete_protection_ranges、dbsheet.delete_records、sheet.delete_data_validations、sheet.delete_conditional_format_rules、sheet.delete_float_images、sheet.delete_filters、dbsheet.sheet_batch_delete、dbsheet.permission_delete_roles_async

能力范围

支持的文档类型

通用工具总览

文档创建与上传

文档读取与下载

文件组织

分享与访问

搜索

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

不支持的操作

• 无批量删除文件工具（仅支持移动）
• 云盘 drive 侧暂无逐文件 ACL 成员矩阵（以分享链接为主）；多维表格（.dbt）见 dbsheet.permission_* 与 dbsheet.share_*（详阅 references/dbsheet.md）
• 在线 Excel / 智能表格工作表区域保护见 sheet.*_protection_ranges 相关工具（详阅 references/sheet.md）
• 无文件版本回滚
• 无实时协同编辑控制

操作指南

执行指南

执行以下操作前，必须先阅读对应指南文件：

⚠️ 不阅读指南直接操作可能导致：参数错误、内容丢失、格式异常。

高频流程指引

创建并写入文档

执行顺序：

1. 先按 references/file-locating-guide.md 获取目标目录 drive_id(可选)、parent_id(可选)。
2. 再按 references/file-writing-guide.md 选择文档类型与写入路径。 字段传递：步骤 1 获取 drive_id(可选)、parent_id(可选)，作为步骤 2 的输入，执行“新建写入”流程。

上传本地文件到云盘

执行顺序：

1. 先按 references/file-locating-guide.md 获取目标目录 drive_id(可选)、parent_id(可选)、file_id(可选)。
2. 再按 references/file-writing-guide.md 的“本地文件上传（upload_file）”路径调用上传能力（新建上传或覆盖更新）。 字段传递：新建上传使用步骤 1 的 drive_id(可选)、parent_id(可选) + name；覆盖更新使用步骤 1 的 file_id 。

搜索定位文档

工具说明：search_files(keyword="关键词", type="all", page_size=20)，获取 file_id、drive_id 供后续链路使用。 详细参数与返回结构见 references/drive/search.md。

更多操作流程

错误速查

安全约束

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

WPS 云文档 Skill（wps skill）问题反馈

当满足以下任一条件时，生成反馈链接并提供给用户：

1. 错误速查表中的处理方式（重试、保持最新版本等）均已尝试但问题仍未解决
2. 用户主动要求反馈或投诉

运行 kdocs-cli feedback 获取反馈链接，将完整链接展示给用户并告知"点击即可打开反馈页面"，由用户决定是否打开。