WeChat Work WeDrive（企业微信微盘空间 + 文件管理）

经 relay 透传凭据，对微盘做完整管理：建空间 → 建文件夹 → 上传 → 取文件分享链接（file-share）发给同事 是主链路；另有列目录 / 取信息 / 重命名 / 移动 / 删除 / 空间安全设置 / 空间邀请链接等辅助接口。

⚠️ 分享标准用法 = file-share（文件级），不是 space-share（空间级）。应用建的空间默认「邀请链接功能关闭」且 API 打不开（只能管理后台手动开），space-share 在未开启时报 640028。file-share 只要微盘权限就能用，发给同事直接看文件、无需加入空间。默认走 file-share，别白白去试 space-share。详见下文「典型流程」与「特殊用途接口」。

关键约束：往哪传文件

企业微信微盘的权限规则：应用只能往「自己创建的文件夹」或「空间根目录」里传文件，不能往他人/其他应用建的文件夹传。本应用 space-create 建空间后自动成为该空间超级管理员，所以根目录可传；但生产建议先 mkdir 建子文件夹再往里传，便于整理。整个文件夹/文件生命周期由本技能自行管理（relay 不替你记 spaceid/fileid）。

凭据与存储位置

• 企业微信凭据 WXWORK_CORP_ID + WXWORK_CORP_SECRET 存放在 daemon.env（实例级，朋友圈 + 微盘共用）。
• relay 身份 OFB_KEY + RELAY_BASE_URL 同样来自 daemon.env（entrypoint 注入）。
• 空间/文件夹 ID 缓存 spaces.json 存放在本技能目录下（已 gitignore，实例级，非密）：

  skills/wxwork-drive/spaces.json

  结构见 spaces.example.json：{default_space, spaces:[{alias, spaceid, default_folderid?}]}。<space> 参数统一接受 alias 或裸 spaceid。

凭据缺失时 Agent 行为

1. 若 WXWORK_CORP_ID / WXWORK_CORP_SECRET 未配置：先读同目录 REFERENCE.md，按其中步骤指导用户获取企业 ID + 应用 Secret（含 relay 可信 IP 123.60.18.144 的配置、微盘权限开通）。
2. 收到值后，交给 IT engineer 写入 daemon.env 并重启实例（或按 REFERENCE.md 用户自助 + 重启）。
3. 若 OFB_KEY 未配置：同样让 IT engineer 在 daemon.env 配置后重启。

命令

通过 PATH 调用 wrapper，无需拼接脚本路径。

wxwork-drive <subcommand> [args...]

空间管理（写 spaces.json）

space-setting flags

只把显式传入的字段带上游，未传的字段保持原状。

文件管理（<space> 接受 alias 或裸 spaceid）

脚本自动：

• 从 daemon.env 读 corp 凭据 + relay 身份
• upload 按类型/大小自动选 upload-image（≤10M 图片）或 upload-video（视频或 >10M，relay 侧分块）
• 每条命令输出一行 JSON 结果（供 Agent 解析链式调用）+ 人类可读摘要

典型流程：从零上传到自建空间，再发文件分享链接

主链路 = 建空间 → 建文件夹 → 上传 → 取文件分享链接发给同事。同事拿到链接直接看文件，不需加入空间。

# 1. 建空间（首次）并设为默认
wxwork-drive space-create main wiseflow素材 --default

# 2. 在空间根建文件夹，并记为默认上传文件夹
wxwork-drive mkdir main 2026-07 --default-folder

# 3. 上传（自动用 default_folderid）
wxwork-drive upload ./cover.jpg main

# 4. 取文件分享链接，发给同事即可直接看文件（不依赖空间邀请链接功能）
wxwork-drive file-share <上一步 upload 返回的 fileid>
# → share_url，发给同事

为什么主链路用 file-share 而不是 space-share：应用建的空间默认「邀请链接功能关闭」，且这个开关 API（97876）打不开，只能去企业微信管理后台手动开。space-share 在未开启时报 640028。file-share 是文件级分享，只要微盘权限就能用，绕过这个限制。所以默认走 file-share；只有要让同事加入整个空间协作时才用 space-share（且需先在管理后台开邀请链接功能）。

特殊用途接口（主链路用不到，按需调）

返回值

每条命令最后一行 JSON 即 relay 返回的业务包络（{ ok, ...字段, detail }）。常用字段：

• space-create：spaceid
• mkdir / upload / rename：fileid
• upload：fast_forward: true 表示命中秒传
• file-share：share_url（文件级分享链接，发给同事直接看文件）
• space-share：space_share_url（空间邀请链接，需管理后台开邀请链接功能）
• ls：detail.file_list.item[]，每项含 fileid / file_name / file_type(1文件夹/2文件/3文档/4表格/5收集表) / file_size / mtime
• info：detail.file_info
• move / delete：detail（上游回包）

fileid / spaceid 永久有效（未删除前），可长期引用。

Agent 行为约束

1. 上传目标要合法：fatherid 必须是空间根（spaceid）或本应用 mkdir 拿到的 fileid（或该空间已设 default_folderid）。往他人/其他应用建的文件夹传会 no permission 失败。
2. 链式调用时从上一条命令的 JSON 行提取 fileid，不要凭空捏造。
3. 优先用 spaces.json 的 alias / default，避免每次让用户重复传 spaceid。
4. 视频上传可能耗时较长（100MB 约 1–3 分钟），等待脚本完整返回后再进行下一步，期间告知用户"正在上传..."。
5. 禁止手动拼接 curl 命令替代脚本。

Error Handling

Notes

• relay 在转发给企业微信前会剥离 corp_id / corp_secret，不下发
• relay 按 (corp_id, corp_secret) 缓存 access_token，client 无需自己管 token
• spaces.json 只存 ID（非密），gitignore 是因为实例级、避免跨部署污染
• 接口契约详见 docs/WXWORK-DRIVE-API.md，上游 API 详见企业微信微盘文档
• 空间成员/部门增删、权限、空间重命名/解散属 admin 级，本技能不覆盖；用到再让 relay 加透传路由