wecomcli-disk

# 企业微信微盘

> 执行任何 `wecom-cli` 命令前，必须先读取并完成 `wecomcli-shared` 技能的公共前置检查。

资源型 skill，负责微盘文件的列出、搜索、读取信息、上传、下载、重命名与新建文件夹。

## 适用范围

### 适用

- 列出微盘最近查看的文件
- 按关键词/类型/创建者/共享空间搜索微盘文件或文件夹
- 读取微盘文件基础信息
- 上传本地文件到微盘指定文件夹
- 下载微盘文件到本地
- 重命名微盘文件
- 在微盘中新建文件夹

### 不适用

- 移动微盘文件或文件夹 → 告知用户暂未支持，建议前往企业微信客户端手动操作
- 删除微盘文件 / 复制微盘文件 → 告知用户暂未支持，建议前往企业微信客户端手动操作
- 删除 / 重命名微盘文件夹（`folder`）、调整目录树结构 → 告知用户暂未支持，建议前往企业微信客户端手动操作
- 创建 / 删除共享空间（`space`）、修改空间成员与空间设置 → 告知用户暂未支持，建议前往企业微信客户端手动操作
- 给机器人授予某空间的权限 / 把机器人加入共享空间成员 → 微盘**没有**该功能，任何渠道都做不到（客户端也不行）。**禁止**向用户提出这类建议，也不要引导用户"联系空间管理员给机器人授权"
- 修改文件分享权限、生成分享链接、撤销分享、设置访问密码 / 有效期 → 告知用户暂未支持，建议前往企业微信客户端手动操作
- 微盘文件版本管理（查看历史版本、恢复旧版本、比对版本） → 告知用户暂未支持
- 撤销 / 修改已上传的文件（覆盖上传 / 秒传 / 断点续传） → 告知用户暂未支持；如需替换，请重新走「上传文件」上传一份新文件
- 解析微盘文件的**内容**（正文提取、OCR、看图问答、PDF/Word/Excel 解析等） → 本 skill 负责把文件下载到本地拿 `file_path`
- 视频 / 音频文件的转写或字幕生成 → 告知用户暂未支持
- 持续监视微盘变更 / 实时通知新文件到达 → 无法主动监视，不要承诺「有新文件时告知你」，请让用户稍后主动再次发起查询

### 路由决策（判断本 skill / 其他 skill）

| 用户输入信号 | 路由到 |
|---|---|
| 明确提"微盘 / 网盘 / disk / Wecom 网盘" | 本 skill |
| 提供 `https://drive.weixin.qq.com/s?k=...` 链接（微盘分享 URL） | 本 skill（作为 `get` / `download` 的 `url` 入参） |
| 提供 `https://doc.weixin.qq.com/<doc\|sheet\|smartsheet\|smartpage>/...` 链接 | 对应 `wecomcli-doc` / `wecomcli-sheet` / `wecomcli-smartsheet` / `wecomcli-smartpage` |
| 在线文档 `doc` / `sheet` / `smartsheet` / `smartpage` 的读写内容 | 同上对应文档 skill |
| 改文档权限 / 加成员 / 改文档名（针对 doc/sheet/smartsheet/smartpage） | `wecomcli-doc-manage` |

> 注意：`doc.weixin.qq.com` / `page.weixin.qq.com` 是在线文档域名，`drive.weixin.qq.com` 才是微盘域名，切勿混用。

### 文件类型枚举

`doc`（在线文档）、`sheet`（在线表格）、`ppt`（在线幻灯片）、`collect`（收集表）、`mind`（思维导图）、`flow`（流程图）、`smartsheet`（智能表格）、`smartpage`（智能主页）、`journal`（汇报）、`pdf`（PDF）、`offline_word`（离线 Word）、`offline_excel`（离线 Excel）、`offline_ppt`（离线 PPT）、`offline_pdf`（离线 PDF）、`image`（图片）、`videoaudio`（视频音频）、`design`（设计稿）。在线文档保持原名，离线文件用 `offline_` 前缀区分。腾讯文档不在本 skill 范围，按【路由决策】表改走对应文档 skill。

> **在线/离线模糊时同时搜**：用户说「Excel」「Word」「PPT」「PDF」等未明确在线还是离线时，`file_types` 同时传入在线版和离线版（如 `["sheet", "offline_excel"]`），避免遗漏。其余类型按上方枚举名按字面对应传入即可。

## 接口详述

### 列出文件

获取用户微盘最近查看的文件列表，支持分页。

**命令**

```bash
wecom-cli disk files list --json '{"limit": 10}'
```

**入参**

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|:----:|---|---|
| `cursor` | string | 否 | `""` | 分页游标；不传或传空串则获取首页数据 |
| `limit` | number | 否 | 10 | 每页返回的最大条数；不传则使用服务默认值，最大 100 |

**返回**

| 字段 | 类型 | 说明 |
|---|---|---|
| `has_more` | boolean | 是否还有更多数据；`true` 时用 `next_cursor` 续取 |
| `next_cursor` | string | 下一页游标 |
| `files[].id` | string | 文件 ID 或文件夹 ID |
| `files[].file_name` | string | 文件名称 |
| `files[].docid` | string | 文档 ID，仅 `type=smartsheet` / `smartpage` / `sheet` / `word` / `ppt` / `collect` / `journal` 时有意义 |
| `files[].type` | string | 文件类型：`file` / `folder` / `space` / `smartsheet` / `smartpage` / `sheet` / `word` / `ppt` / `collect` / `journal` / `flow` / `mind` |
| `files[].file_size` | number | 文件大小（字节）；仅 `type=file` 时有意义 |
| `files[].creator_userid` | string | 创建者 userid |
| `files[].space_id` | string | 所属共享空间 ID |
| `files[].space_name` | string | 所在共享空间名称 |
| `files[].folder_id` | string | 所在文件夹 ID |
| `files[].folder_name` | string | 所在文件夹名称 |
| `files[].create_time` | string | 创建时间，`YYYY-MM-DD HH:mm:ss` |
| `files[].update_time` | string | 最后更新时间，`YYYY-MM-DD HH:mm:ss` |
| `files[].path` | string | 文件完整路径 |
| `files[].doc_url` | string | 文档打开链接，仅在线文档类型（`smartsheet` / `smartpage` / `sheet` / `word` / `ppt` / `collect` / `journal`）时填充 |

### 搜索文件

按关键词、文件类型、创建者、共享空间、排序等条件搜索微盘文件、文件夹或共享空间。

**命令**

```bash
wecom-cli disk files search --json '{"keywords": ["季度汇报"], "search_type": "file", "sort_by": "modify_time", "sort_order": "desc", "limit": 10}'
```

**入参**

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|:----:|---|---|
| `keywords` | string[] | 选填 | — | 字面关键词数组，长度 0~20（or 关系）；与 `creator_userids` / `search_type` / `file_types` **四选一，至少传一个**   |
| `creator_userids` | string[] | 选填 | — | 限定创建者 `userid` 列表，长度 0~50，不传则不过滤；与 `keywords` / `search_type` / `file_types` **四选一，至少传一个**；用户给的是姓名时通过 `wecomcli-contact` 解析为 `userid` |
| `search_type` | string | 选填 | `all` | 查询范围枚举：`all` / `file`（文件）/ `folder`（文件夹）/ `space`（共享空间）；与 `keywords` / `creator_userids` / `file_types` **四选一，至少传一个**； |
| `file_types` | string[] | 选填 | — | 限定文件类型，长度 0~10；可选 `doc` / `sheet` / `ppt` / `collect` / `mind` / `flow` / `smartsheet` / `smartpage` / `journal` / `pdf` / `offline_word` / `offline_excel` / `offline_ppt` / `offline_pdf` / `image` / `videoaudio` / `design`（在线文档保持原名，离线文档用 `offline_` 前缀区分）；不得传枚举外的值；与 `keywords` / `creator_userids`/ `search_type` **四选一，至少传一个**|
| `space_keywords` | string[] | 否 | — | 限定所在空间名称的关键词，长度 0~10，or 关系；命中的 space 会被作为搜索范围；不传则不限空间；**附加过滤条件，不能单独触发搜索** |
| `sort_by` | string | 否 | `best_match` | 排序方式：`best_match` / `modify_time` / `file_size`；不得传枚举外的值 |
| `sort_order` | string | 否 | `desc` | 排序方向：`asc` / `desc`；仅在 `sort_by=modify_time` 或 `file_size` 时需传 |
| `cursor` | string | 否 | — | 分批拉取增量 key，上一次请求返回的 `next_cursor`；不传则从头开始 |
| `limit` | number | 否 | 10 | 每页最大返回条数，最大 100 |

**返回**

| 字段 | 类型 | 说明 |
|---|---|---|
| `has_more` | boolean | 是否还有更多数据；`true` 时用 `next_cursor` 续取 |
| `next_cursor` | string | 下一页游标 |
| `files[].id` | string | 微盘文件 ID / 文件夹 ID / 空间 ID |
| `files[].type` | string | 命中项类型：`file` / `folder` / `space` / `smartsheet` / `smartpage` / `sheet` / `word` / `ppt` / `flow` / `mind` / `journal` / `collect`|
| `files[].file_name` | string | 名称（文件名 / 文件夹名 / 空间名） |
| `files[].file_size` | number | 文件大小（字节），仅 `type=file` 时有意义 |
| `files[].creator_userid` | string | 创建者 userid |
| `files[].space_id` | string | 所在共享空间 ID |
| `files[].space_name` | string | 所在共享空间名称 |
| `files[].folder_id` | string | 所在父文件夹 ID；位于空间根目录时等于 `space_id` |
| `files[].folder_name` | string | 所在文件夹名称 |
| `files[].path` | string | 文件完整路径；`space_name` 与 `folder_name` 同名时不一定是父子关系，可能平级，以 `path` 为准判断层级 |
| `files[].create_time` | string | 创建时间，`YYYY-MM-DD HH:mm:ss` |
| `files[].update_time` | string | 最近更新时间，`YYYY-MM-DD HH:mm:ss` |
| `files[].docid` | string | 文档 ID，仅 `type=smartsheet` / `smartpage` / `sheet