金山文档 CLI 工具

解决的具体问题

在开发自动化脚本、数据管道或集成工具时，如果需要与金山文档（如 WPS 云文档、表格、演示文稿等）进行交互，传统的 Web UI 操作效率低下且难以批量化。开发者需要一种可靠、可编程的方式来管理云端文档资产，实现如批量创建、内容提取、格式化更新和分享权限控制等操作，同时确保操作安全（如凭据不泄露）和流程可验证。

技能如何工作

金山文档 CLI Skill 提供了一套完整的命令行工具集（kdocs-cli），它作为本地代理与金山文档的 RESTful API 进行交互。其工作核心围绕以下几个能力展开：

• 全面的文档类型支持：不仅处理传统的 .docx、.xlsx、.pptx，更深度支持金山自家的智能文档（.otl）、智能表格（.ksheet）和多维表格（.dbt）。对于每种类型，都有专门的参考文档（如 references/otl.md）定义了其独特的操作方法。
• 标准化的命令行调用：所有操作通过 kdocs-cli <service> <action> [参数] 的统一格式发起。参数传递灵活，支持简单的 key=value 形式、直接的 JSON 字符串，或通过 --file 参数从文件读取复杂/大体积的 JSON payload，避免了命令行长度限制和编码问题。
• 严格的操作安全与验证：技能强制执行一系列规则。例如，禁止在任何对话或日志中明文暴露 Token，必须通过 kdocs-cli auth set-token 存入系统密钥链。对于 delete、close 等不可逆操作，在执行前必须向用户二次确认。任何写操作（如更新单元格、插入段落）完成后，必须发起一个独立的读取请求来验证结果，而不依赖 API 返回的成功状态码。
• 智能的文件定位与工作流：当需要处理已有文档时，它提供了完整的查找链路。可以通过关键词 search_files 搜索，或使用 references/file-locating-guide.md 中描述的层级浏览方式。对于常见任务（如“搜索-读取-汇报”），有预定义的工作流（如 references/workflows/search-read-report.md）可以遵循。

适用边界与注意点

• 环境与版本依赖：它是一个需要本地安装的 CLI 工具（通过 scripts/setup.sh 等脚本安装）。首次使用或距上次使用超过 24 小时，必须检查并确保 kdocs-cli 和 Skill 本身版本是最新的，以避免遇到 unknown action/service 等错误。升级失败时，有回滚和重新安装机制。
• 参数传递的严谨性：当参数包含中文、多行文本或超过 200 字符时，必须使用 --file 或 stdin 方式传入 JSON 文件，禁止使用 key=value 或某些语言（如 PowerShell）的原生 JSON 序列化，以防编码损坏。生成 JSON 文件推荐使用 Node.js 或 Python。
• 错误处理与限流：会遇到鉴权失败（400006）、请求限频（429001）或服务熔断（429002）等错误。遇到限频时，必须等待响应中指定的恢复时间，禁止立即重试。对于幂等性不同的工具，重试策略也不同，需要查阅对应工具的参考文档。
• 能力边界：它主要用于对金山文档进行操作，而非渲染或呈现文档内容。其输出是 JSON 格式的数据或状态。如果 CLI 的 --help 中找不到预期的功能，首要步骤是升级版本，因为新功能随版本持续增加。