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-create <alias> <space_name> [--default]	经 relay 创建空间并登记；--default 设为默认
space-add <alias> <spaceid> [--default]	登记一个已有空间
space-ls	列已登记空间
space-default <alias>	设默认空间
space-setting <space> [flags]	空间安全设置（开链接免审批等，见下）
space-share <space>	取空间邀请链接（应用建的空间默认对普通用户不可见，把链接发给同事即可加入）。注意：邀请链接功能本身需先在「企业微信管理后台 → 微盘 → 空间安全设置」开启，API（97876）只控制「链接加入是否免审批」，不控制「链接功能是否开启」；未开启时 space-share 报 640028 space setting disable share url
file-share <fileid>	取文件级分享链接（发给同事直接看文件，不需加入空间）。不依赖空间邀请链接功能，绕过 640028。优先用这个
folder-default <space_alias> <folderid>	设某空间的默认上传文件夹

space-setting flags

flag	上游字段	说明
--share-url-no-approve	share_url_no_approve=true	链接加入空间免审批（邀请同事前通常要先开这个，否则链接发出去对方加入会被审批卡住）
--share-url-default-auth N	share_url_no_approve_default_auth	邀请链接默认权限：1仅下载 / 2可编辑 / 4仅预览 / 5可上传下载 / 200自定义
--enable-watermark	enable_watermark=true	水印（仅专业版）
--enable-confidential	enable_confidential_mode=true	保密模式
--default-file-scope N	default_file_scope	文件默认可查看范围：1仅成员 / 2企业内
--ban-share-external	ban_share_external=true	禁止分享到企业外

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

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

子命令	用途	关键参数
mkdir <space> <file_name> [--fatherid F] [--default-folder]	新建文件夹	--fatherid 缺省=空间根；--default-folder 把新文件夹记为默认上传文件夹
upload <file> <space> [--fatherid F] [--name NAME]	上传图片/视频	--fatherid 缺省=该空间 default_folderid
ls <space> [--fatherid F] [sort_type] [limit] [start]	列目录	--fatherid 缺省=空间根；sort_type 1名升2名降3大小升4大小降5mtime升6mtime降
info <fileid>	取文件/文件夹信息
rename <fileid> <new_name>	重命名
move <fatherid> <fileid> [fileid...] [--replace]	移动到目标目录	--replace 重名覆盖
delete <fileid> [fileid...]	批量删除

脚本自动：

• 从 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（且需先在管理后台开邀请链接功能）。

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

子命令	何时用
space-setting	要开链接免审批 / 水印 / 保密模式 / 禁止外分享等空间级安全设置时。注意：它打不开「邀请链接功能」本身（那个只能管理后台开），只控制「链接加入是否免审批」等子项
space-share	要让同事加入整个空间协作（不只是看一个文件）时。前提：已在管理后台开邀请链接功能，否则报 640028
ls / info / rename / move / delete	后续整理：列目录确认、改名、移动、删除

---

返回值

每条命令最后一行 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

错误	原因	处理
WXWORK_CORP_ID / WXWORK_CORP_SECRET 未配置	daemon.env 缺凭据	按 REFERENCE.md 引导用户获取，交 IT engineer 写 daemon.env + 重启
OFB_KEY 未配置	daemon.env 缺 OFB_KEY	让 IT engineer 配置后重启
MISSING_CORP_CREDENTIALS（relay 400）	请求体缺 corp_id/corp_secret	检查 daemon.env 是否生效（需重启）
MISSING_FIELD（relay 400）	缺必填字段（如 file_name）	补全参数
GETTOKEN_FAILED（relay 502）	corp_secret 错或 corp_id 不存在	核对凭据；按 REFERENCE.md 重新获取
上游 errcode != 0（relay 400）	企业微信拒绝，detail 里是原始 errcode/errmsg	看 errmsg：no privilege→按 REFERENCE.md 开通微盘权限；no permission→fatherid 是他人建的文件夹，改用空间根或自己 mkdir 出来的 fileid

---

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 加透传路由