# Wps Docs

> 灵犀封装了金山云文档能力。若用户指定 *.kdocs.cn/l/xxxx 这类金山云文档链接，相关操作均通过本技能处理。包含以下四大模块： - 云文档基础能力：支持文件信息查询、文件上传与下载。 - 在线表格与智能表格：支持云端创建与编辑在线表格与智能表格，两者共用同一套底层 API。在线表格后缀为 .xlsx，智能表格后缀为 .ksheet。在线表格与智能表格又称ET（即 Electronic Table）。 - 多维表格：面向多维表，提供 Schema 查询、记录读写、字段与各种视图管理能力。多维表格后缀为 .dbt。多维表格又称DbSheet（即 Database Sheet）。 - 智能文档：提供智能文档的创建和修改能力。智能文档后缀为 .otl。智能文档又称AP（即 ActivePage），在使用中也称 otl 文档。

- Skill: `zxbdzh/wps-docs` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add zxbdzh/wps-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zxbdzh/wps-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: zxbdzh (https://skillmd.com/u/zxbdzh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zxbdzh/wps-docs

---


# 金山云文档 SKILL

## 强制规则
1. **禁止使用浏览器操作云文档**：对 `*.kdocs.cn` 链接，禁止使用浏览器（browser skill）进行任何操作（下载、打开、截图等）。所有云文档操作必须且只能通过本技能提供的 API 完成。
2. **权限错误必须立即终止**：当任何 kdocs API 返回包含"无权限""权限""申请访问权限"的错误时，**立即终止所有后续操作**，不得尝试任何变通方案。直接告知用户：文件无访问权限，请联系文件所有者授权后重试。
3. **默认存储位置**：本技能创建或上传的云文档默认存入「我的云文档」下的 `应用/灵犀专业版`。落盘参数约定如下（各子模块 `folder_id` / `parent_id` / `location` 语义同此表）：

| 写法 | 含义 |
|------|------|
| 省略 `folder_id`/`parent_id` 和 `location` | 默认 `应用/灵犀专业版` |
| `folder_id="0"` / `parent_id="0"` | 根目录 |
| `folder_id="xxx"` | 指定文件夹 ID |
| `location="某/路径"` | 按路径解析目标文件夹 |

### 常见链接格式

https://365.kdocs.cn/l/{file_id}?lingxi_file_name={file_name}

## CLI 调用约定（drive / DbSheet / AP / ET）

统一入口：

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" <domain> <子命令> [参数]
```

`<domain>` 为 `drive` / `dbsheet` / `ap`；ET 增强类子命令使用 `et`。单元格读写/格式等仍用 `python_cell_exec`（详见 et_guide.md）。

**写操作入参约定**

- 长文本 / 批量结构化数据写入工作区 Markdown 文件后用对应 flag 传入（如 `--content-file`、`--records-file`、`--fields-file`、`--ops-file`、`--objects-file`、`--body-file`）；文件格式见各命令调用示例。

**失败判定**

- stdout JSON 中 `"success": false` → 视为失败，读取 `error`（及可能的 `error_type`）
- 进程 exit code 非 0 → 同样视为失败，**禁止忽略后继续后续写操作**
- 错误文案含「无权限 / 申请访问权限」→ 立即终止（见上方强制规则）

## 场景路由

收到云文档链接或 file_id 后，先获取文件信息，根据文件类型分发：

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-file-info --file-id {file_id}
```

| 文件类型 | 文件后缀        | 使用模块 | 调用方式 |
| -------- | --------------- | -------- | -------- |
| 智能文档 | .otl | AP（导出 Markdown / 块操作） | python（`ap`） |
| 表格     | .xlsx           | ET                               | python_cell / python（`et`） |
| 智能表格 | .ksheet         | ET（同 .xlsx）                   | python_cell / python（`et`） |
| 多维表   | .dbt            | DbSheet                          | python（`dbsheet`） |
| 其他     | .docx / .pdf 等 | 云文档基础能力（下载到本地处理） | python（`drive`） |

**规则**：除非用户明确要求下载到本地，对云文档的操作都在云端进行。禁止将云文档下载到本地后用 openpyxl / pandas 等python库处理再上传——这会丢失云端格式、公式、图表和协作状态。必须使用对应模块（ET / DbSheet）的云端 API 直接操作。

---

## 一、云文档基础能力


```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive <子命令> [参数]
```

### drive get-file-info

获取云文档文件信息。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件ID |

**返回值**

```json
{
  "success": true,
  "data": {
    "file_id": "文件ID",
    "drive_id": "云盘ID",
    "name": "文件名（含后缀）",
    "link_url": "云文档访问链接",
    "size": "1.23 MB",
    "ctime": "创建时间(ISO 8601)",
    "created_by": {"id": "创建者ID", "name": "创建者名称"}
  },
  "message": "成功获取文件信息: xxx.ksheet"
}
```

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-file-info --file-id xxx
```

### drive download-file

下载云文档文件到本地。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件ID |
| `--save-dir` | 本地保存目录 |

**返回值**

```json
{
  "success": true,
  "data": {
    "file_id": "文件ID",
    "name": "云端文件名",
    "link_url": "云文档访问链接",
    "size": "1.23 MB",
    "ctime": "创建时间(ISO 8601)",
    "created_by": {"id": "创建者ID", "name": "创建者名称"}
  },
  "message": "下载成功，保存路径为: /path/to/file.xlsx"
}
```

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive download-file --file-id xxx --save-dir workspace/output
```

### drive upload-file

上传本地文件到云文档。

**注意**： 直接上传，无需提前检查是否存在同名文件。

| 参数 | 说明 |
|------|------|
| `--file-path` | 本地文件路径 |
| `--folder-id` | 目标文件夹的 `file_id`；不传则默认「应用/灵犀专业版」；传 `0` 为根目录 |
| `--location` | 目标文件夹路径（如 `工作/项目A`）；`--folder-id` 优先 |

**返回值**

```json
{
  "success": true,
  "data": {
    "file_id": "文件ID",
    "name": "文件名",
    "link_url": "云文档访问链接",
    "size": "1.23 MB",
    "ctime": "创建时间(ISO 8601)",
    "created_by": {"id": "创建者ID", "name": "创建者名称"}
  },
  "message": "上传成功，云文档文件名为: xxx.docx，链接为: https://..."
}
```

**调用示例**

```bash
# 默认上传到「应用/灵犀专业版」
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive upload-file --file-path /tmp/report.docx

# 上传到根目录
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive upload-file --file-path /tmp/report.docx --folder-id 0

# 按路径上传
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive upload-file --file-path /tmp/report.docx --location "工作/项目A"
```

### drive move-file

移动文件到目标文件夹。

| 参数 | 说明 |
|------|------|
| `--file-id` | 源文件 ID |
| `--dst-parent-id` | 目标文件夹 ID；`0` 表示根目录 |
| `--dst-drive-id` | 目标云盘 ID；不传时按 `--dst-parent-id` 自动解析 |

**返回值**

```json
{
  "success": true,
  "data": {
    "file_id": "文件ID",
    "name": "文件名",
    "link_url": "云文档访问链接",
    "size": "1.23 MB",
    "ctime": "创建时间(ISO 8601)",
    "created_by": {"id": "创建者ID", "name": "创建者名称"}
  },
  "message": "文件已移动到文件夹 <dst_parent_id>"
}
```

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive move-file --file-id xxx --dst-parent-id {folder_id}
```

### drive list-latest-items

获取最近访问/编辑的文件列表

| 参数 | 说明 |
|------|------|
| `--page-size` | 每页条数，最大 500，默认 20 |
| `--page-token` | 翻页 token，首次不传 |

**返回值**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "file_id": "文件ID",
        "name": "文件名",
        "type": "file",
        "drive_id": "云盘ID",
        "link_url": "云文档链接",
        "mtime": "修改时间(ISO 8601)"
      }
    ],
    "next_page_token": "翻页token（无更多数据时为空）"
  },
  "message": "获取到 N 条最近记录"
}
```

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-latest-items --page-size 20
```

### drive list-my-files

列出「我的云文档」根目录的直接子项。

| 参数 | 说明 |
|------|------|
| `--page-size` | 每页条数，最大 500，默认 50 |
| `--page-token` | 翻页 token，首次不传 |
| `--filter-type` | 只返回指定类型：`file` / `folder` / `shortcut` |

**返回值**

```json
{
  "success": true,
  "data": {
    "drive_id": "云盘ID",
    "parent_id": "0",
    "drive_source": "special",
    "items": [
      {
        "file_id": "文件ID",
        "name": "文件名",
        "type": "file/folder/shortcut",
        "drive_id": "云盘ID",
        "parent_id": "0",
        "link_url": "云文档访问链接",
        "ctime": "创建时间(ISO 8601)",
        "mtime": "修改时间(ISO 8601)"
      }
    ],
    "next_page_token": "翻页token（无更多数据时为空）"
  },
  "message": "获取到 N 个文件"
}
```

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-my-files
```

### drive list-folder-files

获取文件夹下的子文件列表。
**注意**：文件夹本质上也是特殊的 file，拥有 `file_id`，可通过本接口列举其中所有文件。

| 参数 | 说明 |
|------|------|
| `--folder-id` | 文件夹的 `file_id`（**必填**）；根目录为 `0` |
| `--page-token` | 翻页 token，首次不传，后续传上一次返回的 `next_page_token`  |
| `--filter-type` | 只返回指定类型：`file` / `folder` / `shortcut` |

**返回值**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "file_id": "文件ID",
        "name": "文件名",
        "type": "file/folder/shortcut",
        "drive_id": "云盘ID",
        "parent_id": "父目录ID",
        "link_url": "云文档访问链接",
        "ctime": "创建时间(ISO 8601)",
        "mtime": "修改时间(ISO 8601)"
      }
    ],
    "next_page_token": "翻页token（无更多数据时为空）"
  },
  "message": "获取到 N 个文件"
}
```

**注意**：返回的 `file_id` 若对应 `type=folder` 的子文件夹，可再次传入本命令实现递归遍历

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-folder-files --folder-id xxx
```

### drive search-files

按文件名或内容搜索云文档。

| 参数 | 说明 |
|------|------|
| `--type` | 搜索类型：`file_name` / `content` / `all`（必填） |
| `--page-size` | 每页条数，默认 20 |
| `--keyword` | 搜索关键字 |
| `--page-token` | 翻页 token，首次不传 |
| `--file-type` | 可选：`file` / `folder` |
| `--file-exts` | 后缀过滤，逗号分隔 |
| `--parent-ids` | 限定目录，逗号分隔 |
| `--with-total` | 返回总数 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive search-files --type all --keyword "周报" --page-size 20
```

### drive rename-file

重命名文件（夹）。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--dst-name` | 新文件名，须含后缀 |
| `--drive-id` | 可选，云盘 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive rename-file --file-id xxx --dst-name "新名称.otl"
```

### drive copy-file

复制文件到指定目录。

| 参数 | 说明 |
|------|------|
| `--file-id` | 源文件 ID |
| `--dst-drive-id` | 目标云盘 ID |
| `--dst-parent-id` | 目标文件夹 ID；`0` 为根目录 |
| `--drive-id` | 可选，源云盘 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive copy-file --file-id xxx --dst-drive-id DID --dst-parent-id PID
```

### drive check-file-name

检查目标目录下是否已存在同名文件。

| 参数 | 说明 |
|------|------|
| `--drive-id` | 云盘 ID |
| `--parent-id` | 父目录 ID |
| `--name` | 文件名 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive check-file-name --drive-id DID --parent-id 0 --name "报告.docx"
```

### drive save-as-file

将文件另存为到指定目录。

| 参数 | 说明 |
|------|------|
| `--file-id` | 源文件 ID |
| `--dst-drive-id` | 目标云盘 ID |
| `--dst-parent-id` | 目标文件夹 ID |
| `--name` | 可选，目标文件名 |
| `--on-name-conflict` | 可选：`fail` / `rename` |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive save-as-file --file-id xxx --dst-drive-id DID --dst-parent-id PID
```

### drive share-file

开启文件分享。

**注意**：须经用户明确确认后再调用。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--scope` | `anyone` / `company` / `users` |
| `--drive-id` | 可选 |
| `--opts-file` | 可选，分享选项 Markdown 文件 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive share-file --file-id xxx --scope anyone
```

### drive set-share-permission

修改已有分享链接的权限或选项。

| 参数 | 说明 |
|------|------|
| `--link-id` | 分享链接 ID（由 share-file 返回） |
| `--scope` | 可选 |
| `--opts-file` | 可选，选项 Markdown 文件 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive set-share-permission --link-id LID --scope company
```

### drive cancel-share

取消文件分享。

**注意**：须经用户明确确认后再调用；优先使用 `pause`。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--mode` | 可选，默认 `pause`：`pause`（暂停分享，可恢复）/ `delete`（删除分享链接，不可恢复，须确认） |
| `--drive-id` | 可选 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive cancel-share --file-id xxx --mode pause
```

### drive get-share-info

查询分享链接信息。

| 参数 | 说明 |
|------|------|
| `--link-id` | 分享链接 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-share-info --link-id LID
```

### drive get-file-link

获取文件的云文档在线访问链接。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-file-link --file-id xxx
```

### drive list-star-items

获取收藏（星标）列表。

| 参数 | 说明 |
|------|------|
| `--page-size` | 每页条数，默认 20 |
| `--page-token` | 翻页 token |
| `--include-exts / --exclude-exts` | 可选，后缀过滤 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-star-items --page-size 20
```

### drive batch-create-star-items

批量添加收藏。

| 参数 | 说明 |
|------|------|
| `--objects-file` | Markdown 表，列须含 `id`、`type`（如 `file` / `folder`） |

**调用示例**

```bash
# objects.md:
# | id | type |
# | --- | --- |
# | file_xxx | file |
# | folder_yyy | folder |
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive batch-create-star-items --objects-file objects.md
```

### drive batch-delete-star-items

批量移除收藏。

| 参数 | 说明 |
|------|------|
| `--objects-file` | Markdown 表，结构同 batch-create-star-items |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive batch-delete-star-items --objects-file objects.md
```

### drive list-deleted-files

获取回收站文件列表。

| 参数 | 说明 |
|------|------|
| `--page-size` | 每页条数，默认 20 |
| `--page-token` | 翻页 token |
| `--drive-id` | 可选，限定云盘 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-deleted-files --page-size 20
```

### drive restore-deleted-file

将回收站文件还原到原位置。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive restore-deleted-file --file-id xxx
```

### drive list-doclibs

获取团队文档库列表。

| 参数 | 说明 |
|------|------|
| `--page-size` | 可选 |
| `--page-token` | 可选 |
| `--user-role` | 可选，逗号分隔：owner/admin/normal |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-doclibs
```

### drive get-doclib-meta

获取单个团队文档库详情。

| 参数 | 说明 |
|------|------|
| `--drive-id` | 文档库云盘 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-doclib-meta --drive-id DID
```

### drive list-labels

分页获取标签列表。

| 参数 | 说明 |
|------|------|
| `--page-size` | 默认 100 |
| `--page-token` | 可选 |
| `--allotee-type` | 可选：user/company |
| `--label-type` | 可选 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-labels --page-size 100
```

### drive create-label

创建自定义标签。

| 参数 | 说明 |
|------|------|
| `--name` | 标签名 |
| `--allotee-type` | 默认 user |
| `--attr` | 可选属性 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive create-label --name "重点项目"
```

### drive get-label-meta

获取单个标签详情。

| 参数 | 说明 |
|------|------|
| `--label-id` | 标签 ID（系统标签：1 星标 / 2 待办 等） |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-label-meta --label-id 1
```

### drive get-label-objects

获取某标签下的对象列表。

| 参数 | 说明 |
|------|------|
| `--label-id` | 标签 ID |
| `--object-type` | file / drive / history / app / url |
| `--page-size` | 默认 100 |
| `--page-token` | 可选 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-label-objects --label-id 1 --object-type file
```

### drive batch-add-label-objects

批量为对象打标签。

| 参数 | 说明 |
|------|------|
| `--label-id` | 标签 ID |
| `--objects-file` | Markdown 表（列 `id` / `type`） |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive batch-add-label-objects --label-id LID --objects-file objects.md
```

### drive batch-remove-label-objects

批量取消标签。

| 参数 | 说明 |
|------|------|
| `--label-id` | 标签 ID |
| `--objects-file` | Markdown 表，结构同上 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive batch-remove-label-objects --label-id LID --objects-file objects.md
```

### drive batch-update-label-objects

批量更新标签下对象属性/排序。

| 参数 | 说明 |
|------|------|
| `--label-id` | 标签 ID |
| `--objects-file` | Markdown 表 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive batch-update-label-objects --label-id LID --objects-file objects.md
```

### drive batch-update-labels

批量修改自定义标签名称或属性。

| 参数 | 说明 |
|------|------|
| `--labels-file` | Markdown 表，列 `id`，可选 `name` / `attr` |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive batch-update-labels --labels-file labels.md
```

### drive list-file-versions

获取文件历史版本列表。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--page-size` | 可选 |
| `--page-token` | 可选 |
| `--with-comment` | 可选，返回版本备注 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-file-versions --file-id xxx
```

### drive get-file-version-download

获取指定历史版本的下载信息。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--version-num` | 版本号（整数） |
| `--drive-id` | 可选 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-file-version-download --file-id xxx --version-num 1
```

### drive list-document-comments

获取文档全文评论列表。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--origin-id` | 根评论传 `0`；查看回复时传父评论 ID |
| `--page-size` | 可选 |
| `--page-token` | 可选 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive list-document-comments --file-id xxx --origin-id 0
```

### drive create-document-comment

发表全文评论或回复。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--content` | 评论内容 |
| `--origin-id / --reply-id` | 回复时成对传入 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive create-document-comment --file-id xxx --content "已阅"
```

### drive get-file-inline-comments

获取正文划选批注列表。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--drive-id` | 可选 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive get-file-inline-comments --file-id xxx
```

### drive read-file

读取云文档正文为 Markdown/结构化内容。若返回 pending，使用 `--task-id` 轮询直至完成。

| 参数 | 说明 |
|------|------|
| `--file-id / --url / --link-id` | 三选一指定文档 |
| `--task-id` | 异步任务 ID（轮询时） |
| `--format` | 可选：markdown / plain / kdc |
| `--enable-upload-medias` | 可选，导出图片链接 |
| `--sheet-name / --sheet-id / --sheet-range-file` | 表格类可选限定区域 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive read-file --file-id xxx --format markdown
```

### drive scrape-url

网页剪藏：抓取网页并保存为智能文档，返回异步任务 `job_id`。

| 参数 | 说明 |
|------|------|
| `--url` | 目标网页 URL |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive scrape-url --url "https://example.com/article"
```

### drive scrape-progress

查询网页剪藏任务进度。

| 参数 | 说明 |
|------|------|
| `--job-id` | scrape-url 返回的任务 ID |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive scrape-progress --job-id JOB
```

### drive upload-attachment

向已有文档上传通用附件。

| 参数 | 说明 |
|------|------|
| `--file-id` | 目标文件 ID |
| `--filename` | 附件文件名 |
| `--url` | 附件 URL（与 content-base64-file 二选一） |
| `--content-base64-file` | Base64 内容文件路径 |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive upload-attachment --file-id xxx --filename a.png --url https://example.com/a.png
```

### drive download-attachment

获取文档附件的下载信息。

| 参数 | 说明 |
|------|------|
| `--file-id` | 文件 ID |
| `--attachment-id` | 附件 ID（上传返回的 object_id） |

**调用示例**

```bash
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive download-attachment --file-id xxx --attachment-id AID
```

### drive create-folder

在云端创建文件夹。仅支持「我的云文档」。

| 参数 | 说明 |
|------|------|
| `--name` | 文件夹名称 |
| `--parent-id` | 父文件夹 `file_id`，默认 `0`（根目录） |

**返回值**

```json
{
  "success": true,
  "data": "folder_id",
  "message": "文件夹「xxx」创建成功，file_id: xxx"
}
```

**调用示例**

```bash
# 在已有文件夹下创建子文件夹
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive create-folder --name "子目录" --parent-id {folder_id}
```

### drive find-folder-by-path

按名称或路径查找文件夹。
**注意**：需要在指定文件夹下创建/上传文件时，先调用本接口获取 `file_id`，再传给对应接口的 `folder_id` / `parent_id` 参数。若返回 `"success": false` 且 error 含「未找到」，告知用户确认路径或是否需创建文件夹。

| 参数 | 说明 |
|------|------|
| `--path` | 文件夹名称或多层路径（`/` 分隔，如 `"工作/项目A"`） |

**返回值**

```json
{
  "success": true,
  "data": "folder_id",
  "message": "找到文件夹: 工作/项目A"
}
```

**调用示例**

```bash
# 单层文件夹名
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive find-folder-by-path --path "多维表样张"
# 多层路径
python "$SKILL_PATH_BASH/wps-docs/scripts/wps_docs_cli.py" drive find-folder-by-path --path "工作/项目A"
```

### 错误处理

| 错误 | 原因 | 解决方案 |
| ---- | ---- | -------- |
| CLI 失败（`"success": false` 或 exit code 非 0） | 参数错误、网络/服务端失败等 | 读取 stdout JSON 的 `error`（及可能的 `error_type`），禁止忽略后继续写操作 |
| 获取下载地址失败 | 文件无权下载或不存在 | 检查 `--file-id` 是否合法 |
| 无权限 / 申请访问权限 | 当前用户无权访问该文件 | **立即终止所有操作**，告知用户无权限并建议联系文件所有者授权。禁止尝试浏览器、wget 等变通方案 |

---

## 二、ET（在线表格 / 智能表格）

使用前必须先读取完整文档：

```
{skill_path}/wps-docs/et/et_guide.md
```

涵盖能力：创建和编辑在线表格（.xlsx）或智能表格（.ksheet），两种文件类型共用同一套 API。包括数据读写、公式、格式美化、图表、条件格式、数据透视表、图片插入，以及筛选、数据校验、区域权限、浮动图片等（详见 et_guide.md）。

---

## 三、DbSheet（多维表）

DbSheet 功能作为本技能的子模块，使用前必须先读取完整文档，完整文档请读取：

```
{skill_path}/wps-docs/dbsheet/dbsheet_guide.md
```

涵盖能力：查询 Schema、列举/检索/创建/更新/删除记录、管理字段与各种视图，以及分享协作、高级权限、Webhook、父子记录、仪表盘等（详见 dbsheet_guide.md）。

---

## 四、AP（智能文档）

AP 功能作为本技能的子模块，使用前必须先读取完整文档：

```
{skill_path}/wps-docs/ap/ap_guide.md
```

涵盖能力：导出智能文档为 Markdown、创建智能文档、查询文档块结构、插入/删除/更新块内容，以及整篇内容写入与格式转换（详见 ap_guide.md）。

---

## 云文档交付规范


凡是通过本技能创建或上传云文档后，向用户交付结果时，**必须**使用以下格式：

```
[`文件名`](link_url)
```

- `link_url` 取 API 返回值中的 `link_url` 字段，该字段已包含 `lingxi_file_name` 参数，**直接使用，禁止截断或替换为裸链接**
- 文件名原样写在反引号内

**示例：**

```
[`明月.otl`](https://www.kdocs.cn/l/ckR5jy8fj2Hw?lingxi_file_name=明月.otl)
[`5月开支详情.dbt`](https://www.kdocs.cn/l/cpc5ijZVRqX0?lingxi_file_name=5月开支详情.dbt)
[`你好.pptx`](https://www.kdocs.cn/l/ciyDvJZIdLfB?lingxi_file_name=你好.pptx)
```