kdocs

金山文档 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 类）执行前必须向用户确认
• 创建云文档文件并验证通过后，必须向用户展示可访问链接。若响应包含 data.link_url 则直接展示；若响应无链接时，调用 get_file_link 获取并展示。
• 除 SKILL.md 已给出最小可用示例的主路径工具外，其他工具调用前必须先阅读对应的 references/ 详细参考文档；参数细节（类型、可选值、约束）以工具参考文档为准
• 满足「问题反馈」章节触发条件时，必须运行 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 version=2.6.17 skill_name=kdocs，若返回 update_available: true，从 instruction 中提取 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

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

---

调用格式

kdocs-cli [参数]

参数传递

参数特征	推荐方式	示例
简单值（无中文）	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

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

---

读写主路径

读用 read_file，写用 create_file_with_content。其他工具⚠️ 禁止跳过 reference 直接调用（违反必导致参数错误），工具总览仅供路由选择，调用前必须读对应 references/ 文档。

读：read_file

read_file 是正文读取主入口，定位参数 url / link_id / file_id 三选一：

kdocs-cli drive read-file url="https://www.kdocs.cn/l/xxx"

按已有定位信息选择一个参数即可：用户给完整链接传 url；已解析分享链接传 link_id；已拿到文件 ID 传 file_id。不要同时传多个定位参数。

首次请求返回 status=pending 时，携带该响应中的 task_id 和原读取参数再次请求，将返回文档全量内容：

kdocs-cli drive read-file file_id=file_xxx task_id=task_xxx

task_id 必须来自本次响应，禁止猜测或跨请求复用。

必须检查返回里的 data.warnings：表格可能只读默认工作表或首屏区域，warnings 会提示实际读取范围。

智能文档（.otl）内嵌图片：默认 read_file 仅返回 ![image]() 空占位。完整步骤见 references/otl.md「常用工作流 → 读取智能文档内嵌图片」。

kdocs-cli drive read-file link_id=xxx enable_upload_medias=true

若 content 仍含空占位 ![image]()，不得停止；改读 references/otl.md「常用工作流 → 读取智能文档内嵌图片」。

読み込み：create_file_with_content

create_file_with_content は「新規作成して内容を書き込む」ための基本ルートです。保存先フォルダーが明確な場合は parent_id（フォルダー ID）のみを指定します。保存先フォルダーが未指定の場合は、ドライブとフォルダーの両方を省略できます（デフォルトは個人用クラウドドライブのルートです）。

kdocs-cli drive create-file-with-content --file payload.json

payload.json：

{
  "name": "周报",
  "file_extension": "otl",
  "content": "# 周报\n\n这里是正文"
}

拡張子	主なパラメーター
.otl .docx .md .pdf	name + file_extension + content
.xlsx .ksheet	name + file_extension + sheet_name + rangeData
.dbt	name + file_extension + sheet_name + fields + records

スプレッドシートの rangeData のルートノードは配列である必要があります。各項目はオブジェクトで、formula は二次元配列でなければなりません。sheet.update_range_data の {range, values} と混在させないでください。

payload.json：

{
  "name": "台账",
  "file_extension": "xlsx",
  "sheet_name": "Sheet1",
  "rangeData": [{
    "row_from": 0,
    "row_to": 0,
    "col_from": 0,
    "col_to": 1,
    "formula": [["姓名", "部门"]]
  }]
}

参考ドキュメント（必要に応じて参照）

パラメーターの説明を補足したり、呼び出しエラーを調査したりする場合は、次を参照してください。

• read_file：references/drive/read_and_download.md
• create_file_with_content：references/drive/create_and_upload.md

上記の完全なパスを指定して参考ドキュメントを読み込んでください。ファイル名を推測しないでください。

以下のツールは取り消しできません。呼び出す前に必ずユーザーに確認してください（詳細な制約については、各ツールの参考ドキュメントの「操作上の制約」セクションを参照してください）。

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、cancel_collaborator_permissions、sheet.delete_conditional_format_rules、sheet.delete_float_images、sheet.delete_filters、dbsheet.sheet_batch_delete、sheet.delete_pivot_table、dbsheet.permission_delete_roles_async、dbsheet.innerdoc_block_delete、dbsheet.innerdoc_block_batch_delete

---

対応範囲

操作領域のルーティング

エージェントは、まずユーザーのリクエストの操作領域を判定します。

「部分更新」「種類別機能」に該当し、拡張子や種類が不明な場合：まず references/file-locating-guide.md に従って種類を確認し、対応する種類別 reference を開きます。呼び出し方法を推測しないでください。読み取り／作成／ファイル管理では、事前に呼び出す必要はありません。

操作領域	該当するケース	ルーティング
作成／書き込み	新規作成して書き込む、ローカルファイルをアップロードする、空白のドキュメントを新規作成する	基本ルートは上記の「読み書きの基本ルート」を参照。ローカルファイルのアップロード、空白のドキュメントの新規作成は references/drive.md を参照
部分更新	ブロック／段落／セルの変更、既存の対象ドキュメントの編集	「対応しているドキュメントの種類」→ 対応する reference の書き込み／更新系ツール
種類別機能	条件付き書式、エクスポート変換、翻訳、PDF 分割、スライドのテーマ、データ検証	「対応しているドキュメントの種類」→ 対応する reference の専用機能セクション
読み取り	ドキュメントの内容を読み取る／抽出する／エクスポートする	本文：read_file（url／link_id／file_id。references/drive/read_and_download.md を参照）。.otl の埋め込み画像 → references/otl.md「よく使うワークフロー → スマートドキュメントの埋め込み画像を読み取る」。それ以外は「ファイルの検索」を参照
ファイルの検索	ファイル ID や属性を検索／リンクから特定する、ディレクトリを参照する	詳細は references/file-locating-guide.md を参照。「マイドライブを見る」→ references/drive/read_and_download.md（drive.list_my_files）
ファイル管理	移動／名前変更／共有／タグ／お気に入り／ごみ箱／コメント／ドキュメントライブラリ／履歴バージョン／名前を付けて保存	→ references/drive.md
AI 生成	AI で PPT を作成する／プレゼンテーションを生成する	→ references/aippt.md
ナレッジベース	ナレッジベースのスペース／インポート／整理	→ references/kwiki.md

対応しているドキュメントの種類

種類	別名	ファイル拡張子	説明	詳細な参考情報
スマートドキュメント 優先	ap	.otl	見やすいレイアウトで、豊富なコンポーネントに対応	references/otl.md — ページ、テキスト、見出し、ToDo などの要素操作
スプレッドシート	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 — データテーブル／ビュー／フィールド／レコードの完全な CRUD に対応。フォームビュー、親子レコード、共有コラボレーション、高度な権限、Webhook を含む
スマートフォーム	form	.form	軽量フォームの下書き作成、質問の設定、公開、照会	references/form.md — 下書きの作成／更新／公開、フォーム情報の照会

よく使う手順ガイド

作成／書き込み

ユーザーの意図	ツール	対応する拡張子／説明
空白のドキュメントのみが必要	create_empty_file	.doc .docx .otl .dbt（デフォルトの列） .xlsx .xls .ksheet .pptx .ppt
既存の本文または表データを書き込む	create_file_with_content	.otl .docx .pdf .xlsx .ksheet .dbt
多次元スプレッドシートを新規作成し、列のカスタマイズが必要	create_file_with_content	.dbt（業務データがなくても fields+records が必要）
ローカルの Markdown をオフィスドキュメントとして新規作成	create_file_with_content	.otl .docx .pdf。元の形式のまま .md にする場合のみ upload_new_file を使用
ローカルファイルをアップロードしてクラウドドキュメントを新規作成	upload_new_file	.doc .docx .xls .xlsx .ppt .pptx .pdf .md .txt .html .zip .png .jpg .jpeg .csv .json .dps .et .wps .gif
AI で PPT を生成	aippt.execute	.pptx

拡張子が不明な場合は、デフォルトで .otl を使用します。フォルダーを指定する場合は、まず references/file-locating-guide.md に従って drive_id と parent_id を取得してください。

ツールを選択したら、references/drive/create_and_upload.md の該当セクションを読み、パラメーターの制約を確認してください（aippt.execute については references/aippt.md を参照）。

搜索定位文档

工具说明：search_files(keyword="关键词", page_size=10) 即可搜索（type 可省略，默认 all）；获取 file_id、drive_id 供后续链路使用。 type 为搜索维度（file_name/content/all），筛选文件夹/文件请用 file_type。 详细参数与返回结构见 references/drive/search.md。

更多操作流程

流程	说明	详细参考
读取多维表云文档元信息	从多维表记录中提取云文档字段的 file_id，再调用 get_file_info 获取元信息（文件名、大小、类型、修改时间等）	references/workflows/read-cloud-doc-meta.md
AI 生成演示文稿（全文）	aippt.execute 单接口全文生成链路：支持 html（两次调用 + follow_up）和 basic（一次调用，经典简约模式）两种模式，覆盖主题/文档场景	references/workflows/aippt-full-text.md
AI 单页生成幻灯片	aippt.execute 单接口单页生成幻灯片：HTML 布局模式，一次调用完成，可通过 wpp.import_slides 插入到已有演示文稿	references/workflows/aippt-single-page.md
网页剪藏	抓取网页内容并自动保存为智能文档	references/workflows/web-scrape.md
搜索-读取-汇报撰写	搜索多份文档、提取信息、汇总撰写新报告	references/workflows/search-read-report.md
定期读取与播报	定期读取指定文档，提取关键信息生成摘要	references/workflows/periodic-read-summary.md
智能分类整理	列出目录，按内容或指定维度分类创建文件夹并归档	references/workflows/smart-classify.md
精准搜索与风险排查	在特定目录批量搜索文档，逐一读取分析，汇总到新文档	references/workflows/precise-search-analysis.md
云文档导入幻灯片	将外部 PPTX 文件中的指定幻灯片导入到已有演示文稿中	references/workflows/import-slides.md
接龙转表格	识别接龙文本内容，自动提取并转为在线表格	references/workflows/jielong-to-table.md
跨表字段回填（按主键匹配）	两张表格按主键列（如订单号、企业ID、SKU）匹配，将源表指定列写入目标表对应列；须先读表头按列名定位，写后按列名回读验证	references/workflows/sheet-cross-fill.md
表单收集	根据用户需求设计并创建智能表单，发布后生成填写链接	references/workflows/form-collection.md
知识智能整理	对知识库中的零散内容进行智能化整理和结构化重组	references/workflows/knowledge-format.md
知识一键存入	将各类内容（网页、文件、文本）一键保存到知识库	references/workflows/knowledge-save.md
表格美化与数据规范	读取表格数据，进行格式美化、数据规范化和样式调整，并通过条件格式、数据校验、区域权限固化规则	references/workflows/table-beautify.md

---

错误速查

错误特征	原因	处理方式
400006 / 鉴权失败	Token 过期或未配置	运行 kdocs-cli auth login 重新登录，或 kdocs-cli auth set-token <token> 重新设置
429001 / 限频	请求过于频繁，响应含限频恢复时间	立即停止命令调用，直到达到恢复时间；禁止立即重试、换参、换子命令连续请求
429002 / 熔断	多因短时间内连续触发 429001 ，响应含熔断持续时间	熔断时长内零请求，期满再试；重新规划任务避免请求过频
403 / 权限不足 / 无权访问 / forbidden	当前凭据对目标文档、目录或资源无操作权限	停止操作，禁止重试或尝试其他接口绕过；告知用户当前账号无权限，并建议联系文档所有者开通权限、确认分享链接权限，或切换到有权限的账号
unknown action / unknown service	CLI 版本过旧或名称拼写错误	先运行 kdocs-cli upgrade 升级到最新版本；仍报错再运行 kdocs-cli <service> --help 确认可用命令
搜索无结果	关键词过精确 / 索引延迟	缩短关键词 / 等待 3-5 秒重试
读取内容为空	文件无内容或格式不支持	确认文件非空且后缀正确
第三方服务错误：任务不存在	使用了无效、跨请求或已完成的 task_id	前一次已返回完整内容时直接使用已有结果；否则丢弃旧 task_id，按原文件定位参数重新读取
创建文件失败	文件名后缀不正确	检查后缀：.otl / .docx / .xlsx / .ksheet / .dbt / .pdf / .pptx
移动文件失败	目标文件夹不存在	先搜索确认或创建文件夹
Client.Timeout exceeded while awaiting headers	服务端处理或排队时间超过 CLI HTTP 超时，常见于上传、导出、AI 生成、格式转换、大文件读取等慢操作	确认工具幂等性后重试 1 次，并显式设置 --timeout 值（如 --timeout=120000）；写入/创建类工具重试前先查询结果，避免重复创建
conflict / lock / 并发写入冲突	多个写操作同时修改同一资源（知识库节点、多维表记录等）导致锁竞争	指数退避重试（2s → 4s → 8s，最多 3 次）；批量写入场景改为串行逐条执行；详见 kwiki / dbsheet 各 reference「错误速查表」
HTTP 5xx	服务端故障	等 3 秒重试 1 次
验证不通过（回读值与预期不符）	写入未生效或延迟	等 2 秒重新验证，仍不通过则报告用户
setup.sh 执行失败 / 安装报错	当前版本可能已不兼容	执行上方「保持最新版本」流程
CLI 接口返回未知错误码（非 5xx、非 400006、非 429001/429002、非工具不存在）	Skill 版本过旧导致接口不兼容	执行上方「保持最新版本」流程；仍失败到 kdocs-cli feedback
错误信息含 version、incompatible、not_supported、deprecated 等版本关键词	Skill 或 API 版本不兼容	执行上方「保持最新版本」流程；仍失败到 kdocs-cli feedback
工具调用失败且原因不明	可能是 Skill 版本过旧	执行上方「保持最新版本」流程；仍失败到 kdocs-cli feedback
上述处理方式均已尝试仍无法解决	未知问题	仍失败则 kdocs-cli feedback
工具调用失败需判断是否可重试	不同工具幂等性不同	查看该工具参考文档「操作约束」区的幂等性说明，幂等工具可安全重试，非幂等工具须先确认状态

---

问题反馈

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

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

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

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

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

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

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

防重复（MUST 遵守）：

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

---

安全约束

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