teamwiseflow 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.jsonspaces.example.json：{default_space, spaces:[{alias, spaceid, default_folderid?}]}。<space>参数统一接受 alias 或裸 spaceid。
凭据缺失时 Agent 行为
- 若
WXWORK_CORP_ID/WXWORK_CORP_SECRET未配置：先读同目录REFERENCE.md，按其中步骤指导用户获取企业 ID + 应用 Secret（含 relay 可信 IP123.60.18.144的配置、微盘权限开通）。 - 收到值后，交给 IT engineer 写入
daemon.env并重启实例（或按REFERENCE.md用户自助 + 重启）。 - 若
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：spaceidmkdir/upload/rename：fileidupload：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 / mtimeinfo：detail.file_infomove/delete：detail（上游回包）
fileid / spaceid 永久有效（未删除前），可长期引用。
Agent 行为约束
- 上传目标要合法：
fatherid必须是空间根（spaceid）或本应用mkdir拿到的 fileid（或该空间已设default_folderid）。往他人/其他应用建的文件夹传会no permission失败。 - 链式调用时从上一条命令的 JSON 行提取 fileid，不要凭空捏造。
- 优先用 spaces.json 的 alias / default，避免每次让用户重复传 spaceid。
- 视频上传可能耗时较长（100MB 约 1–3 分钟），等待脚本完整返回后再进行下一步，期间告知用户"正在上传..."。
- 禁止手动拼接 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 加透传路由