wps

金山 Doc CLI Skill 使用ガイド

金山 Doc CLI Skill は、オンラインドキュメント操作ツールの完全なセットを提供し、kdocs-cli コマンドラインツールを通じて金山 Doc API とやり取りします。さまざまな種類のオンラインドキュメントの作成、照会、読み取り、編集、共有、移動をサポートします。

厳格なルール

禁止（NEVER）

• Token を平文で会話、ログ、コマンド出力、コードコメント、その他いかなるファイルにも出現させることを禁止します。Token は kdocs-cli auth set-token または kdocs-cli auth login を通じてシステムキーチェーンに保存することのみ許可されます
• アップロードや書き込みなどのインターフェースで渡す必要がある content_base64 は非常に大きくなる可能性があり（エンコード後 >1 MB）、会話の中でトークンごとに 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 が実際にサポートするツールセットを基準としてください。

---

ツールのインストールと認証

操作	コマンド
インストール	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

以下のツールは不可逆であるため、呼び出し前に必ずユーザーへ確認してください（詳細な制約は各ツールのリファレンスドキュメントの「操作制約」セクションを参照）：

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

---

機能範囲

支持的文档类型

类型	别名	文件后缀	说明	详细参考
智能文档 首选	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

通用工具总览

文档创建与上传

工具	用途
create_file	在云盘下新建文件
scrape_url	网页剪藏，抓取网页内容并自动保存为智能文档
scrape_progress	查询网页剪藏任务进度
upload_file	全量上传写入文件（更新已有 docx/pdf 或新建并上传本地文件）

文档读取与下载

工具	用途
list_files	获取指定文件夹下的子文件列表
download_file	获取文件下载信息
read_file_content	文档内容抽取为 Markdown/纯文本

文件组织

工具	用途
move_file	批量移动文件(夹)
rename_file	重命名文件（夹）

分享与访问

工具	用途
share_file	开启文件分享
set_share_permission	修改分享链接属性
cancel_share	取消文件分享
get_share_info	获取分享链接信息
get_file_link	获取文件的云文档在线访问链接

搜索

工具	用途
search_files	文件（夹）搜索

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

不支持的操作

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

---

操作指南

执行指南

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

操作类型	指南文件	何时阅读
获取文件标识指南	references/file-locating-guide.md	需要搜索或浏览文件时
文件读取指南	references/file-reading-guide.md	需要获取文档内容时
文件创建与写入指南	references/file-writing-guide.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。

更多操作流程

流程	说明	详细参考
AI 生成演示文稿（全文）	aippt.execute 单接口全文生成链路：两次调用完成需求澄清与生成，支持主题/文档两种来源，固定使用 html 模式	references/workflows/aippt-whole.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
信息收集表单生成	根据用户需求自动设计并创建信息收集表格	references/workflows/form-generator.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> 重新设置
Expecting value: line 1 column 1 (char 0) 或类似 JSON 解析失败	上游返回了空响应或非 JSON（HTML 错误页 / 重定向 / 网关错误），不是 CLI 本身崩溃。常见触发：文件 ID 错误、文件已被删除、无访问权限、Token 过期但未触发 400006、临时网络中断	按顺序排查：① kdocs-cli auth status 确认 Token 有效；② 用 kdocs-cli drive search 或 kdocs-cli wps file_info 重新核对 file_id；③ 确认当前账号对该文件有读权限（在金山文档网页端打开链接验证）；④ 等待 3-5 秒后重试一次；仍失败则报告用户
429001 / 限频	请求过于频繁，响应含限频恢复时间	立即停止命令调用，直到达到恢复时间；禁止立即重试、换参、换子命令连续请求
429002 / 熔断	多因短时间内连续触发 429001 ，响应含熔断持续时间	熔断时长内零请求，期满再试；重新规划任务避免请求过频
unknown action / unknown service	CLI 版本过旧或名称拼写错误	先运行 kdocs-cli upgrade 升级到最新版本；仍报错再运行 kdocs-cli <service> --help 确认可用命令
搜索无结果	关键词过精确 / 索引延迟	缩短关键词 / 等待 3-5 秒重试
读取内容为空	文件无内容或格式不支持	确认文件非空且后缀正确
创建文件失败	文件名后缀不正确	检查后缀：.otl / .docx / .xlsx / .ksheet / .dbt / .pdf / .pptx
移动文件失败	目标文件夹不存在	先搜索确认或创建文件夹
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

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

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

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

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