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` / `word` / `ppt` / `collect` / `journal` 时有意义 | | `files[].doc_url` | string | 文档打开链接，仅在线文档类型时填充；**可直接作为在线文档分享链接发送给用户/群，无需额外处理** | | `files[].title_highlight` | string[] | 标题命中关键词的高亮摘要片段；`type=space` 时为空 | | `files[].text_highlight` | string[] | 正文命中关键词的高亮摘要片段；`type=space` 时为空 | > **在线文档命中项处理约束——极重要**：搜索返回的 `type` 若为 `smartsheet` / `smartpage` / `sheet` / `word` / `ppt` / `journal` / `collect` / `mind` / `flow`，这些是**在线协作文档**（正文存云端，非二进制文件），**禁止**走 `disk files download`（会失败或拿到空壳），也不适合走 `disk files get`。其中 `smartsheet` / `smartpage` / `sheet` / `word` 有对应的下游 skill 可读正文，路由见文末【跨技能依赖】表；**`ppt` / `journal` / `collect` / `mind` / `flow` 目前没有任何下游 skill 或 CLI 能读取正文**，命中这些类型且用户要看内容时，直接告知暂不支持读取，引导用户用 `doc_url` 在企业微信客户端内打开查看。仅当 `type=file` 时才可用 `id` 作为 `file_id` 调 `disk files download` 拿本地文件。 **使用规则** - **触发条件（唯一权威描述）**：`keywords` / `creator_userids` / `search_type` / `file_types` **四选一，至少传一个**；`space_keywords` 只是附加过滤条件，**不能单独触发搜索**。若四者全空则用自然语言追问后再发起搜索。若用户仅给出空间关键词（如「在 XX 空间里搜一下」），可用自然语言追问具体搜索内容。 - **多次搜不到就如实告知**：多次调整关键词/类型后仍无结果时，停止搜索，如实告知用户是「搜不到文件」还是「搜不到该空间」，不要反复换词硬搜。 - **可选参数传值策略——默认不传，仅在用户明确点名时才传**： | 参数 | 何时不传（后端默认） | 何时传（用户明确表达时） | |---|---|---| | `search_type` | 用户笼统说"搜一下 xxx / 找 xxx / 文件 / 资料"等未明确对象类型 → 后端按 `all` | 明确说"只搜文件夹 / 目录"→`folder`；"只搜共享空间 / 团队空间"→`space`；"只要文件，不要文件夹"→`file` | | `sort_by` | 用户无排序偏好 → 后端按 `best_match` | "最新 / 最近改 / 最早"→`modify_time`；"最大 / 最小"→`file_size` | | `sort_order` | `sort_by=best_match` 时无需传 | 传 `modify_time` / `file_size` 时按新→旧用 `desc`、旧→新用 `asc`；不传则默认 `desc` | | `file_types` | 用户笼统说"文档 / 文件 / 资料 / 材料"或业务概念（合同 / 报告 / 会议纪要）→ 不过滤，靠 `keywords` 兑现 | 用户明确点到具体形态（PPT / Excel / PDF / 图片 / 智能表格 等），把对应枚举一并塞入数组 | | `space_keywords` | 不限空间时 | 用户说"在 XX 空间 / XX 团队盘里搜" → 填空间名关键词（本接口不接受 `space_id`） | - **`keywords` 不要混入文件类型后缀**：用户说「搜一下 Excel 报告」「找 PPT 方案」时，文件类型后缀（Excel/PPT/Word/PDF）交给 `file_types` 过滤，`keywords` 只保留业务关键词（如「报告」「方案」）。例：「Excel 报告」→ `keywords:["报告"]` + `file_types:["sheet","offline_excel"]`。 - **`file_types` 口语→枚举映射**：见上方「可选参数传值策略」表的 `file_types` 行（用户口语 → `file_types` 取值的映射）。 - **分页续传**：`has_more=true` 时用 `next_cursor` 作为下一次调用的 `cursor`；首次调用 `cursor` 传空串。 - **不支持时间范围过滤**：本接口没有 `begin_time` / `end_time` 字段，禁止伪造；若用户给出"最近 3 天 / 上周 / 本月"等时间范围，先按 `sort_by=modify_time`, `sort_order=desc` 拉取，再由客户端根据 `update_time` 二次筛选。 - **结果总结顺序跟随排序方向**：`sort_order=desc`（默认，新→旧）时，向用户总结结果也应从最新到最旧展示，不要颠倒顺序。 ### 读取文件信息 根据 `file_id` 或微盘文件 URL 读取文件基础信息。 **命令** ```bash wecom-cli disk files get --json '{"file_id": "FILE_ID"}' ``` **入参** | 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|:----:|---|---| | `file_id` | string | 二选一 | — | 文件 ID；与 `url` 二选一；同时提供时优先使用 `file_id` | | `url` | string | 二选一 | — | 微盘文件分享 URL（形如 `https://drive.weixin.qq.com/s?k=AJEAIQdfAAoN4N17GM`）；与 `file_id` 二选一 | **返回** | 字段 | 类型 | 说明 | |---|---|---| | `file.id` | string | 文件 ID 或文件夹 ID | | `file.file_name` | string | 文件名称 | | `file.docid` | string | 文档 ID，仅 `type=smartsheet` / `smartpage` / `sheet` / `word` / `ppt` / `collect` / `journal` 时有意义 |