金山文档 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 获取链接并展示给用户
调用工具前必须先阅读对应的 references/ 详细参考文档，禁止仅凭指南（guide）的概要说明直接拼装调用；参数细节（类型、可选值、约束）以工具参考文档为准

保持最新版本

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

CLI 版本：kdocs-cli version — 若命令不存在则按下方「工具安装与认证」安装；若低于本文件 frontmatter version，运行 kdocs-cli upgrade -y（自动备份旧版本，失败可 kdocs-cli upgrade --rollback）
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 实际支持的工具集为准。

工具安装与认证

| 操作 | 命令 | |------|------| | 安装 | bash scripts/setup.sh / powershell scripts/setup.ps1 / node scripts/setup.cjs | | 认证 | 用户已提供 Token: kdocs-cli auth set-token "<token>" · 无 Token: kdocs-cli auth login |

调用格式

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

参数传递

| 参数特征 | 推荐方式 | 示例 | |----------|----------|------| | 简单值（无中文） | key=value | kdocs-cli drive search-files keyword=test type=all | | 数组/对象，短 JSON | JSON 字符串 | kdocs-cli sheet query-records '{"file_id":"xxx","filter":{}}' | | 数组/对象，或含中文/换行/>200 字符 | --file | kdocs-cli otl insert-content --file payload.json | | 脚本流水线集成 | stdin | node gen.js \| kdocs-cli otl insert-content - |

--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');

全局选项：

| 选项 | 说明 | |------|------| | --token <token> | 一次性 Token（优先级最高，不持久化） | | --endpoint <url> | 覆盖默认 endpoint | | --compact | 输出紧凑 JSON | | --silent | 仅输出 data 字段 | | --verbose | 输出请求详情到 stderr | | --timeout <ms> | HTTP 请求超时（毫秒，默认 30000） |

帮助：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_data、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

能力范围

操作域路由

Agent 首先判定用户请求的操作域：

| 操作域 | 触发场景 | 路由 | |--------|---------|------| | 创建/写入 | 新建文档/编辑内容/上传文件 | 必读 references/file-writing-guide.md | | 局部更新 | 修改部分内容/块级编辑/更新单元格 | 按文档类型查下方表 → 对应 reference 中的写入/更新类工具 | | 读取 | 读取/提取/导出文档内容 | read_file（传 url 或 file_id，详见 references/drive/read_and_download.md）；没有则先「定位文件」 | | 定位文件 | 搜索/按链接找文件/浏览目录 | 必读 references/file-locating-guide.md | | 文件管理 | 移动/重命名/分享/标签/收藏/回收站 | → references/drive.md | | 文档专项功能 | 格式/样式/导出/转换/数据校验等 | 按文档类型查下方表 → 对应 reference | | AI 生成 | AI 做PPT/生成演示文稿 | → references/aippt.md | | 知识库 | 知识库空间/导入/整理 | → references/kwiki.md |

支持的文档类型

| 类型 | 别名 | 文件后缀 | 说明 | 详细参考 | |------|------|----------|------|----------| | 智能文档 首选 | ap | .otl | 排版美观，支持丰富组件 | references/otl.md — 页面、文本、标题、待办等元素操作 | | 表格 | et / Excel | .xlsx | 数据表格专用 | references/sheet.md — 工作表管理、范围数据获取、批量更新 | | PDF文档 | pdf | .pdf | PDF 文档专用 | references/pdf.md — PDF 创建与内容读取 | | 文字文档 | wps / Word | .docx | 传统格式 | references/wps.md — Word 文档创建与内容操作 | | 演示文稿 | wpp | .pptx | PPT 文档专用 | references/wpp.md — 幻灯片主题字体和配色设置、下载和导出 | | 智能表格 | as | .ksheet | 结构化表格，支持多视图、字段管理 | references/sheet.md — 工作表管理、范围数据获取、批量更新 | | 多维表格 | db / dbsheet | .dbt | 多数据表、丰富字段类型与视图（表格/看板/甘特等） | references/dbsheet.md — 支持数据表/视图/字段/记录的完整增删改查，含表单视图、父子记录、分享协作、高级权限与 Webhook | | 智能表单 | form | .form | 轻量表单草稿创建、题目配置、发布与查询 | references/form.md — 草稿创建/更新/发布与表单信息查询 |

高频流程指引

创建并写入文档

执行顺序：

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

上传本地文件到云盘

执行顺序：

先按 references/file-locating-guide.md 获取目标目录 drive_id(可选)、parent_id(可选)、file_id(可选)。
再按 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。

错误速查

| 错误特征 | 原因 | 处理方式 | |----------|------|----------| | 400006 / 鉴权失败 | Token 过期或未配置 | 运行 kdocs-cli auth login 重新登录，或 kdocs-cli auth set-token <token> 重新设置 | | 429001 / 限频 | 请求过于频繁，响应含限频恢复时间 | 立即停止命令调用，直到达到恢复时间；禁止立即重试、换参、换子命令连续请求 | | 429002 / 熔断 | 多因短时间内连续触发 429001 ，响应含熔断持续时间 | 熔断时长内零请求，期满再试；重新规划任务避免请求过频 | | unknown action / unknown service | CLI 版本过旧或名称拼写错误 | 先运行 kdocs-cli upgrade 升级到最新版本；仍报错再运行 kdocs-cli <service> --help 确认可用命令 | | 搜索无结果 | 关键词过精确 / 索引延迟 | 缩短关键词 / 等待 3-5 秒重试 | | 读取内容为空 | 文件无内容或格式不支持 | 确认文件非空且后缀正确 | | 创建文件失败 | 文件名后缀不正确 | 检查后缀：.otl / .docx / .xlsx / .ksheet / .dbt / .pdf / .pptx | | 移动文件失败 | 目标文件夹不存在 | 先搜索确认或创建文件夹 | | Client.Timeout exceeded while awaiting headers | 服务端处理或排队时间超过 CLI HTTP 超时，常见于上传、导出、AI 生成、格式转换、大文件读取等慢操作 | 确认工具幂等性后重试 1 次，并显式设置 --timeout 值（如 --timeout=120000）；写入/创建类工具重试前先查询结果，避免重复创建 | | HTTP 5xx | 服务端故障 | 等 3 秒重试 1 次 | | 验证不通过（回读值与预期不符） | 写入未生效或延迟 | 等 2 秒重新验证，仍不通过则报告用户 | | setup.sh 执行失败 / 安装报错 | 当前版本可能已不兼容 | 执行上方「保持最新版本」流程 | | CLI 接口返回未知错误码（非 5xx、非 400006、非 429001/429002、非工具不存在） | Skill 版本过旧导致接口不兼容 | 执行上方「保持最新版本」流程 | | 错误信息含 version、incompatible、not_supported、deprecated 等版本关键词 | Skill 或 API 版本不兼容 | 执行上方「保持最新版本」流程 | | 工具调用失败且原因不明 | 可能是 Skill 版本过旧 | 执行上方「保持最新版本」流程 | | 上述处理方式均已尝试仍无法解决 | 未知问题 | 运行 kdocs-cli feedback 获取反馈链接，引导用户提交反馈 | | 工具调用失败需判断是否可重试 | 不同工具幂等性不同 | 查看该工具参考文档「操作约束」区的幂等性说明，幂等工具可安全重试，非幂等工具须先确认状态 |

安全约束

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

金山文档 Skill（kdocs skill）问题反馈

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

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

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