kdocs

Files (92)

• SKILL.md
• aippt.md · references/
• auth.md · references/
• dbsheet.md · references/
• dashboard.md · references/dbsheet/
• data_table.md · references/dbsheet/
• field.md · references/dbsheet/
• form.md · references/dbsheet/
• parent_child.md · references/dbsheet/
• permission.md · references/dbsheet/
• record.md · references/dbsheet/
• share.md · references/dbsheet/
• view.md · references/dbsheet/
• webhook.md · references/dbsheet/
• drive.md · references/
• comment.md · references/drive/
• create_and_upload.md · references/drive/
• doclib.md · references/drive/
• label.md · references/drive/
• organize.md · references/drive/
• read_and_download.md · references/drive/
• recent_and_recycle.md · references/drive/
• search.md · references/drive/
• share.md · references/drive/
• star.md · references/drive/
• versions.md · references/drive/
• file-locating-guide.md · references/
• form.md · references/
• create_draft.md · references/form/
• get_form_info.md · references/form/
• publish_draft.md · references/form/
• update_draft.md · references/form/
• kwiki.md · references/
• close_knowledge_view.md · references/kwiki/
• create_item.md · references/kwiki/
• create_knowledge_view.md · references/kwiki/
• delete_item.md · references/kwiki/
• get_knowledge_view.md · references/kwiki/
• import_cloud_doc.md · references/kwiki/
• list_items.md · references/kwiki/
• list_knowledge_views.md · references/kwiki/
• update_knowledge_view.md · references/kwiki/
• otl.md · references/
• block_delete.md · references/otl/
• block_insert.md · references/otl/
• block_query.md · references/otl/
• block_update.md · references/otl/
• convert.md · references/otl/
• insert_content.md · references/otl/
• node.md · references/otl/
• pdf.md · references/
• convert.md · references/pdf/
• inspect.md · references/pdf/
• split_and_merge.md · references/pdf/
• translate.md · references/pdf/
• sheet.md · references/
• conditional_format.md · references/sheet/
• data.md · references/sheet/
• data_validations.md · references/sheet/
• filters.md · references/sheet/
• …and 32 more

SKILL.md (first lines)

# 金山文档 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`）
- 创建云文档文件并验证通过后，必须向用户展示可访问链接。若响应包含 `data.link_url` 则直接展示；若响应无链接时，调用 `get_file_link` 获取并展示。
- 调用工具前必须先阅读对应的 `references/` 详细参考文档，禁止仅凭指南（guide）的概要说明直接拼装调用；参数细节（类型、可选值、约束）以工具参考文档为准

---

## 保持最新版本
何时触发：**首次使用** 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 <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` 传入，操作完成后删除临时文件：
>
> ```javascript
> 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
> ```
> ```javascript
> // 操作完成后清理临时文件
> 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 能力随版本持续扩展，未升级是命令缺失的首要原因。详见上方「保持最新版本」章节。


以下工具不可逆，调用前必须向用户确认（详细约束见各工具参考文档的「操作约束」区）：

`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 首先判定用户请求的操作域：

| 操作域 | 触发场景 | 路由 |
|--------|---------|------|
| 创建/写入 | 新建并写入、上传本地文件、新建空白文档 | **见下方「创建/写入」** |
| 局部更新 | 改块/改段/改单元格，已有目标文档上的修改 | 按「支持的文档类型」→ 对应 reference 中的写入/更新类工具 |
| 类型专属能力 | 条件格式、导出转换、翻译、PDF 拆分、幻灯片主题、数据校验 | 按「支持的文档类型」→ 对应 reference 中的专属功能章节 | 读取 | 读取/提取/导出文档内容 | `read_file`（传 url 或 file_id，详见 `references/drive/read_and_download.md`）；没有则先「定位文件」 |
| 读取 | 读取/提取/导出文档内容 | `read_file`（传 url 或 file_id，详见 `references/drive/read_and_download.md`）；没有则先「定位文件」 |
| 定位文件 | 搜索/按链接找文件/浏览目录 | **必读** `references/file-locating-guide.md` |
| 文件管理 | 移动/重命名/分享/标签/收藏/回收站/评论/文档库/历史版本/另存为 | → `references/drive.md` |
| AI 生成 | AI 做PPT/生成演示文稿 | → `references/aippt.md` |
| 知识库 | 知识库空间/导入/整理 | → `references/kwiki.md` |

### 支持的文档类型

From wang-zi-tao/dotfiles, MIT.

More from wang-zi-tao/dotfiles