金山文档 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 字符串，用脚本完成文件读取、编码和传参
• 工具返回或 stderr 明确表示当前文件/链接整份不可访问（如整文件无权限、需向所有者申请访问、无权打开该文档等）时：停止对该文件的后续读写，不得换参数对该文件变通重试；告知用户联系文件所有者授权。若用户提供了其他可访问文件或明确换目标，可继续处理其它文件。单次字段/单表/局部操作权限不足且未声明整文件不可用时：说明原因，跳过该步或询问用户是否继续，不得仅因子串「权限」就终止本会话内所有云文档操作

必须（MUST）

• 不可逆操作（delete/close 类）执行前必须向用户确认
• 创建云文档文件并验证通过后，必须向用户展示可访问链接。若响应包含 data.link_url 则直接展示；若响应无链接时，调用 get_file_link 获取并展示。
• 除 SKILL.md 已给出最小可用示例的主路径工具外，其他工具调用前须先执行 kdocs-cli help <tool> 获取详细参考文档；参数细节（类型、可选值、约束）以工具参考文档为准
• 满足「问题反馈」章节触发条件时，必须运行 feedback 命令并展示完整反馈链接，并遵守该章节的防重复规则；禁止仅口头告知联系客服或仅以「暂不支持」结束对话
• 参考文档按本技能总览或索引中的文件路径读取，不猜文件名、不把目录当文件、不套用其他技能的路径。路径报错时先核对索引。

保持最新版本

何时触发：首次使用 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 --args '{"version":"2.9.0","skill_name":"kdocs"}'，若返回 update_available: true，从 instruction 中提取 zip 下载链接，下载解压替换当前 Skill 目录

若 upgrade 和 rollback 均失败，在本 Skill 目录下重新运行安装脚本（bash setup.sh / powershell setup.ps1 / node setup.cjs，脚本位于 scripts/）可从 CDN 重新安装。 若仍无法更新，以各能力域 service 参考页内工具选型指引与 kdocs-cli version 所对应能力为准，并运行 kdocs-cli feedback。

工具安装与认证

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

调用格式

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

参数传递

• --file 必须是该工具的完整 JSON 参数对象；使用 --file 时只读 JSON 文件，命令行里 <service> <action> 之后不要再写 --file-id 等工具选项（多余选项会被忽略，容易误以为生效）
• --file = 本地 JSON 参数文件；--file-id = 云文档 ID（reference 里 JSON 字段 file_id 写成 --file-id）。勿把云文档 ID 或 .otl 路径传给 --file
• PowerShell 传 JSON 字符串须反斜杠转义：'{\"key\":[\"val\"]}'

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

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

全局选项（Agent 子集；可与 <service> <action> 同条命令；勿用 --compact / --silent / --endpoint 等替代）：

成功时 stdout 为单行 JSON（工具返回的 data）；失败时 stderr 为结构化错误。

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

找不到命令？ 浏览 kdocs-cli help / kdocs-cli help <service> 时若发现预期的 service 或 action 不存在，先运行 kdocs-cli upgrade -y 升级到最新版本再重试。CLI 能力随版本持续扩展，未升级是命令缺失的首要原因。详见上方「保持最新版本」章节。

能力范围

操作域路由

Agent 首先判定用户请求的操作域，将后续步骤转交到对应子 Skill，在子 Skill 内按索引选用工具。子 Skill 遇到域外需求时返回主 Skill；主 Skill 保留已完成操作、实际资源和任务 ID，再安排后续转交。

云文档管理

支持的文档类型

错误速查

问题反馈

满足以下任一条件时 MUST 提供反馈链接。可界定异常无需先穷尽错误速查表。

可界定异常（必出链接）： 功能缺少、工具不存在、格式/类型不支持、接口/参数不支持、结果不达标（回读验证失败且无法修正）、权限/账户限制（告知原因后）、搜索/查询无结果（已调整检索条件至少 1 次且任务仍无法继续）。

错误与兜底： 当前错误处理步骤（含有限重试）已完成仍失败。

用户主动： 要求反馈、投诉、报告问题或提交功能需求。

引导语： Bug/异常用「欢迎反馈具体问题」；功能需求用「欢迎通过反馈链接告诉我们你希望实现什么」。功能缺少或不支持时禁止仅以「暂不支持」结束，必须附带反馈链接。

运行 kdocs-cli feedback（可选 --reason <trigger_reason> 用于统计），将 stdout 完整 URL 展示给用户，告知「点击即可打开反馈页面」。

复杂任务部分成功且用户可能有改进建议时，可在回复末尾附带反馈链接；日常简单成功不必每次展示。

防重复（MUST 遵守）：

• 每条回复最多展示 1 个反馈链接；已展示则同条回复内不再重复获取链接。
• 同一会话内，同一根因（同一类阻断，如相同的不支持格式、相同的缺失能力）只须出链接 1 次；后续同类情况用文字说明，可提示用户沿用已给出的链接。
• 用户已表示不需要反馈或已知悉后，本会话不再主动贴链接；除非用户再次要求或出现不同根因的新阻断。
• 「搜索/查询无结果」须在已调整检索条件至少 1 次且仍无法继续时，才计入 MUST。

安全约束

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