返回板块

G24 MCP协议标准(weiyun)

类别：技术规范
名称释义：微云 MCP API / 鉴权 / FTN 两阶段上传
落位：~/.workbuddy/spec\3.行政法规\范式\G6_MCP协议标准(weiyun).md
版本：V1.0.1（2026-08-31 成文规范整改：四篇式结构 + 模态词等级表 + 术语和定义 + 失效模式表 + 附录 A–D）

---

工作流（启动顺序 + 升级闭环 · 全域硬约束）

本规范为对应对象（skill/专家）升级/迭代/训练/知识注入的唯一权威依据。任何涉及该对象的改动，必须严格按以下五步闭环执行，缺一不可、全域强制。

启动顺序（每次会话/任务启动，全域铁律）

1. 读 MEMORY（拿规则）：首步读 ~/.workbuddy/MEMORY.md，未读不得动手。
2. 跑 _tools 代码（强制）：凡 .docx/.xlsx 交付物命名与skill/专家迭代升版四件套验证，强制调用 ~/.workbuddy/_tools/（deliverable.py / check_deliverables.py），禁止手敲文件名。
3. 查 README（看 API）：动手前查 ~/.workbuddy/README/<对象目录名>/README.md；无独立 README 时以 SKILL.md 为 API 权威。
4. 查技术规范与 SOP（升级/建夹必过闸）：①升级/迭代/训练/知识注入前先读本范式（~/.workbuddy/spec\3.行政法规\范式\ 对应文件）；②每个新任务启动（含任何 skill 触发产出）先读 S01+S02，建「三字标题_YYYY-MM-DD_HHMM/产出/素材/」，产出落 产出/。
5. 收尾总结（每次任务结束后，200 字铁律）：任何任务每次结束后，在最终回复中用约 200 字总结「当前进展 + 核心结论 + 遗留问题」三要素（见 ~/.workbuddy/spec\3.行政法规\SOP\S10_任务收尾总结SOP.md）；与 S03/S04 收尾三件套、skill/专家迭代升版四件套并存、互不替代。

升级五步闭环（硬约束）

• 闭环链路：读 MEMORY → 跑 _tools → 查 README → 查技术规范与 SOP → 建任务夹（S02），五步必须闭环、全域可执行、覆盖全部 SOP（含 S02 建文件夹）、硬约束。
• 只按本技术规范修改：改动逐条对照本范式对齐，不重写整个 SKILL.md；不碰全域规则（MEMORY.md）与工具链（_tools/），除非其自身变化。
• 无技术规范，拒绝升级：定位不到或用户未提供本范式 → 立即停下、禁止动手改，并回复「请提供其技术规范（如电池专家技术规范）」。

来源：微云 MCP API 参考

文件：C:\Users\xub\.workbuddy\skills\weiyun\references/mcp_api.md

微云 MCP API 完整参考

服务信息

• MCP 服务地址：https://www.weiyun.com/api/v3/mcpserver（Stateless HTTP 模式）

---

Tool: weiyun.list — 目录列表查询

查询微云网盘的目录内容，支持按目录查看文件和子目录，支持分页和排序。

请求（McpListReq）

字段	类型	必填	说明
get_type	uint32	否	获取类型：0-所有（默认），1-仅目录，2-仅文件，其他值返回所有
offset	uint32	否	分页起始偏移量，从 0 开始
limit	uint32	是	每页返回数量，最大 50
order_by	uint32	否	排序字段：0-不排序（默认），1-按名字排序，2-按修改时间排序
asc	bool	否	排序方向：true-升序，false-降序（默认）
dir_key	string	否	要查询的目录 key（hex 编码），为空则使用 token 绑定的 dirkey
pdir_key	string	否	要查询的父目录 key（hex 编码），为空则使用 token 绑定的 pdirkey

响应（McpListRsp）

字段	类型	说明
pdir_key	string	当前列表的父目录 key（hex 编码）
total_dir_count	uint32	子目录总数量
total_file_count	uint32	文件总数量
dir_list	McpDirItem[]	目录列表
file_list	McpFileItem[]	文件列表
finish_flag	bool	是否已拉取完毕，true 表示已全部返回
error	string	错误信息，操作失败时返回具体的错误描述

McpDirItem（目录项）

字段	类型	说明
dir_key	string	目录 key（hex 编码）
dir_name	string	目录名称
dir_ctime	int64	目录创建时间，单位毫秒
dir_mtime	int64	目录修改时间，单位毫秒

McpFileItem（文件项）

字段	类型	说明
file_id	string	文件唯一标识符
filename	string	文件名称
file_size	int64	文件大小，单位字节
file_ctime	int64	文件创建时间，单位毫秒
file_mtime	int64	文件修改时间，单位毫秒
pdir_key	string	所在目录 key（hex 编码）

注意事项

• 查询范围由 mcp_token 绑定的 dirkey 和 pdirkey 决定
• 腾讯文档类型的文件会被自动过滤，不出现在返回结果中

---

Tool: weiyun.list_by_category — 按分类拉取文件列表

按微云文件分类分页拉取文件列表，支持文档、图片、视频等分类以及 server_version 续拉。

请求（McpListByCategoryReq）

字段	类型	必填	说明
category_id	uint64	否	分类 ID（位运算值），有值时优先于 lib_id 和 suffix_list。例如：1-doc、2-excel、4-ppt、8-pdf、64-image、512-腾讯文档、4095-全部
lib_id	int32	否	库 ID：1-文档，2-图片，3-音乐，4-视频，5-其他。category_id 有值时会忽略此字段
local_version	string	否	上次返回的 server_version，用于增量续拉；首次请求传空字符串
group_id	int32	否	分组 ID。文档库：0-全部，1-doc，2-xls，3-ppt，4-pdf，50-腾讯文档 Doc，51-腾讯文档 Sheet，52-腾讯文档表单；图片/视频库可传相册分组 ID
suffix_list	string[]	否	指定后缀列表，仅文档库和其他库有效，例如 ["docx", "xlsx"]
count	int32	是	本次拉取数量，最大 100
sort_type	int32	否	排序类型：0-创建时间，1-修改时间，2-名称，3-拍摄时间，4-大小
is_desc_order	bool	否	是否降序排列：true-降序（默认），false-升序

响应（McpListByCategoryRsp）

字段	类型	说明
server_version	string	服务端游标；下一次请求请回填到 local_version 以继续拉取
finish_flag	bool	是否已拉取完成，true 表示当前条件下已经没有更多结果
file_list	McpFileItem[]	分类文件列表（结构同 weiyun.list 的 McpFileItem）
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• 该接口要求同时携带真实微云 cookie（如 uid、uid_key）和 mcp_token
• category_id 为位运算值，可组合使用（例如 1 | 2 | 4 = 7 表示 doc + excel + ppt）
• 首次请求 local_version 传空字符串，后续续拉时回填上次响应的 server_version
• 当 finish_flag 为 true 时表示已无更多数据

---

Tool: weiyun.download — 批量下载

批量获取微云网盘文件的 HTTPS 下载链接。

请求（McpDownloadReq）

字段	类型	必填	说明
items	McpDownloadFileItem[]	是	需要获取下载链接的文件列表

McpDownloadFileItem（下载文件项）

字段	类型	必填	说明
file_id	string	是	文件唯一标识符
pdir_key	string	是	文件所在目录 key（hex 编码）

响应（McpDownloadRsp）

字段	类型	说明
items	McpDownloadResultItem[]	下载结果列表
error	string	错误信息，操作失败时返回具体的错误描述

McpDownloadResultItem（下载结果项）

字段	类型	说明
file_id	string	文件唯一标识符
https_download_url	string	HTTPS 下载链接
file_size	int64	文件大小，单位字节
cookie	string	下载时需要携带的 cookie（格式：cookieName=cookieValue）

注意事项

• 如果 pdir_key 为空，使用 token 绑定的 dirkey
• 会校验目录所有权，非本人目录的文件会被跳过
• 下载链接无限速

---

Tool: weiyun.delete — 批量删除

批量删除微云网盘中的文件或目录，支持移动到回收站或彻底删除。

请求（McpDeleteReq）

字段	类型	必填	说明
file_list	McpDeleteFileItem[]	否	待删除的文件列表
dir_list	McpDeleteDirItem[]	否	待删除的目录列表
delete_completely	bool	否	是否彻底删除：false-移动到回收站（默认），true-彻底删除

注意：file_list 和 dir_list 至少要有一个非空。

McpDeleteFileItem（删除文件项）

字段	类型	必填	说明
file_id	string	是	文件唯一标识符
pdir_key	string	是	文件所在目录 key（hex 编码）

McpDeleteDirItem（删除目录项）

字段	类型	必填	说明
dir_key	string	是	目录 key（hex 编码）
pdir_key	string	是	父目录 key（hex 编码）

响应（McpDeleteRsp）

字段	类型	说明
freed_space	int64	释放的空间大小，单位字节
freed_index_cnt	uint32	删除的文件数和目录数之和
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• 文件删除会校验目录所有权，非本人目录的文件会被跳过
• 删除之后会进回收站，一般7天内可以恢复，会员和超级会员则分别是 30 天和 90 天

---

Tool: weiyun.upload — 文件上传

上传文件到微云网盘，采用两阶段协议：预上传 + 分片上传，支持秒传。
注意： 除非用户提了明确的要求，修改文件名称，否则，宜使用原本的文件名称进行上传。

请求（McpUploadReq）

预上传阶段（upload_key 为空）

字段	类型	必填	说明
filename	string	是	文件名称
file_size	uint64	是	文件大小，单位字节
file_sha	string	是	整个文件的 SHA1 值（hex 编码，40 字符）。必须等于 block_sha_list 最后一个值
block_sha_list	string[]	是	每个分块的 SHA1 状态列表（hex 编码，每个 40 字符），按 512KB 分块顺序排列。计算方法详见 SKILL.md 中的分块 SHA1 算法
check_sha	string	是	SHA1 校验中间状态（hex 编码，40 字符）
check_data	string	否	文件末尾 checkBlockSize 字节的 Base64 编码
file_md5	string	否	整个文件的 MD5 值（hex 编码，32 字符），用于秒传校验
pdir_key	string	否	上传到的目录 key（hex 编码），不填则使用 token 绑定的目录

分片上传阶段（upload_key 非空）

字段	类型	必填	说明
upload_key	string	是	预上传返回的 upload_key（hex 编码）
channel_list	McpChannelInfo[]	是	预上传返回的通道列表
channel_id	uint32	是	分片上传使用的通道编号
ex	string	是	预上传返回的扩展字段（hex 编码）
file_data	bytes	是	当前分片的文件数据（二进制，JSON 传输时为 base64）
filename	string	是	文件名称（与预上传相同）

McpChannelInfo（上传通道信息）

字段	类型	说明
id	uint32	通道编号
offset	uint64	分片在文件中的偏移量
len	uint32	分片的数据长度

响应（McpUploadRsp）

字段	类型	说明
file_id	string	文件唯一标识符，预上传成功后返回
filename	string	上传后的文件名
file_exist	bool	是否秒传成功，true 表示文件已存在无需上传分片
upload_state	int32	上传状态：1-需要上传下一分片，2-上传完成，3-等待其他通道完成
upload_key	string	upload_key（hex 编码），后续分片上传时需携带
channel_list	McpChannelInfo[]	通道列表，用于后续分片上传
ex	string	扩展字段（hex 编码），后续分片上传时需携带
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• 预上传会校验目录所有权，非本人目录禁止上传
• 如果 pdir_key 为空，使用 token 绑定的 dirkey
• 文件已存在时执行覆盖策略
• 默认使用多通道上传模式（最多 4 通道）
• 分片上传时 file_data 经过 Base64 双重处理：MCP 框架自动 base64 → bytes，服务端再次进行 Base64 解码

---

Tool: weiyun.gen_share_link — 生成分享外链

为微云网盘中的文件或目录生成分享短链接。

请求（McpGenShareLinkReq）

字段	类型	必填	说明
file_list	McpShareFileItem[]	否	待分享的文件列表
dir_list	McpShareDirItem[]	否	待分享的目录列表
share_name	string	否	分享名称，不填则使用第一个文件或目录名
passwd	string	否	分享密码，不填则创建无密码分享，长度一定是 6 个字符。支持随机密码，也支持用户指定特定密码

注意：file_list 和 dir_list 至少要有一个非空。

随机分享密码生成规则：长度6，全小写字母+数字混合，不包含特殊字符

McpShareFileItem（分享文件项）

字段	类型	必填	说明
file_id	string	是	文件唯一标识符
pdir_key	string	是	文件所在目录 key（hex 编码）。必须使用 weiyun.list 响应顶层的 pdir_key，不可为空

McpShareDirItem（分享目录项）

字段	类型	必填	说明
dir_key	string	是	目录 key（hex 编码）
pdir_key	string	是	父目录 key（hex 编码）。必须使用 weiyun.list 响应顶层的 pdir_key，不可为空

响应（McpGenShareLinkRsp）

字段	类型	说明
short_url	string	分享短链接
share_name	string	分享名称
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• ⚠️ pdir_key 不可为空：如果传入空的 pdir_key，可能导致分享链接异常，强烈建议调用方显式传入正确值
• pdir_key 应使用 weiyun.list 响应中顶层的 pdir_key 字段值，而非文件项中的 pdir_key（该字段可能为空字符串）

---

Tool: weiyun.rename_file — 重命名文件

重命名微云网盘中的文件，需要提供文件所在目录 key 和文件 ID。

请求（McpRenameFileReq）

字段	类型	必填	说明
file_id	string	是	文件唯一标识符
pdir_key	string	是	文件所在目录 key（hex 编码）
new_filename	string	是	修改后的文件名

响应（McpRenameFileRsp）

字段	类型	说明
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• pdir_key 应使用 weiyun.list 响应中顶层的 pdir_key 字段值
• 重命名不会改变文件的 file_id

---

Tool: weiyun.rename_dir — 重命名目录

重命名微云网盘中的目录，需要提供目录 key 和父目录 key。

请求（McpRenameDirReq）

字段	类型	必填	说明
dir_key	string	是	目录 key（hex 编码）
pdir_key	string	是	父目录 key（hex 编码）
new_dir_name	string	是	修改后的目录名
src_dir_name	string	是	修改前的目录名

响应（McpRenameDirRsp）

字段	类型	说明
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• pdir_key 应使用 weiyun.list 响应中顶层的 pdir_key 字段值
• 重命名不会改变目录的 dir_key

---

Tool: weiyun.create_dir — 创建文件夹

在微云网盘中创建文件夹，需要提供父目录 key 和文件夹名称。

请求（McpCreateDirReq）

字段	类型	必填	说明
pdir_key	string	否	父目录 key（hex 编码），在此目录下创建新文件夹。为空则使用 token 绑定的目录
dir_name	string	是	新文件夹名称

响应（McpCreateDirRsp）

字段	类型	说明
dir_key	string	新创建的目录 key（hex 编码）
dir_name	string	创建后的目录名（可能被自动改名，如存在同名目录）
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• 如果 pdir_key 为空，使用 token 绑定的 dirkey 作为父目录
• 如果目标目录下已存在同名文件夹，返回的 dir_name 可能会被自动改名

---

Tool: weiyun.move_dir — 移动文件夹

移动微云网盘中的文件夹到目标目录，需要提供源目录 key 和目标目录 key。

请求（McpMoveDirReq）

字段	类型	必填	说明
dir_key	string	是	待移动的目录 key（hex 编码）
src_pdir_key	string	是	源父目录 key（hex 编码），即当前所在的目录
dst_pdir_key	string	是	目标父目录 key（hex 编码），即要移动到的目录
dir_name	string	否	目录名称，移动时可选填用于冲突处理

响应（McpMoveDirRsp）

字段	类型	说明
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• ⚠️ src_pdir_key 和 dst_pdir_key 不可为空，必须通过 weiyun.list 获取正确的目录 key
• src_pdir_key 应使用 weiyun.list 响应中顶层的 pdir_key 字段值
• dst_pdir_key 应使用目标目录的 weiyun.list 响应中顶层的 pdir_key 或目标目录的 dir_key

---

Tool: weiyun.move_file — 移动文件

移动微云网盘中的文件到目标目录，需要提供文件 ID、源目录 key 和目标目录 key。

请求（McpMoveFileReq）

字段	类型	必填	说明
file_id	string	是	待移动的文件唯一标识符
src_pdir_key	string	是	源父目录 key（hex 编码），即文件当前所在的目录
dst_pdir_key	string	是	目标父目录 key（hex 编码），即要移动到的目录
filename	string	否	文件名称，移动时可选填用于冲突处理

响应（McpMoveFileRsp）

字段	类型	说明
error	string	错误信息，操作失败时返回具体的错误描述

注意事项

• ⚠️ src_pdir_key 和 dst_pdir_key 不可为空，必须通过 weiyun.list 获取正确的目录 key
• src_pdir_key 应使用文件当前所在目录的 weiyun.list 响应中顶层的 pdir_key 字段值
• dst_pdir_key 应使用目标目录的 weiyun.list 响应中顶层的 pdir_key 或目标目录的 dir_key

---

Tool: check_skill_update — 技能版本检查更新

检查当前 Skill 版本是否有新版本可用，返回最新版本号、发布说明和更新指令。

请求（CheckSkillUpdateReq）

字段	类型	必填	说明
version	string	是	当前技能版本号，格式为 MAJOR.MINOR.PATCH

响应（CheckSkillUpdateRsp）

字段	类型	说明
latest	string	最新版本号，格式为 MAJOR.MINOR.PATCH
release_note	string	最新版本发布说明
instruction	string	更新指令，需要更新时遵循此指令执行

注意事项

• 如果当前已是最新版本，返回请求中传入的版本号
• 不需要认证：此接口不依赖 mcp_token，无需登录即可调用

---

认证机制

MCP Token

所有 MCP 工具（除 check_skill_update 外）需要通过 WyHeader HTTP 头传递 mcp_token：

WyHeader: mcp_token=<token>

Token 可通过微云授权页面获取：https://www.weiyun.com/disk/authorization

来源：微云 MCP 鉴权

文件：C:\Users\xub\.workbuddy\skills\weiyun\references/auth.md

微云鉴权检查

微云授权流程，必须按以下步骤执行：

第一步：检查状态（立即返回）

macOS / Linux：

bash ./setup.sh weiyun_check_and_start_auth

Windows (PowerShell)：

powershell -ExecutionPolicy Bypass -File setup.ps1 weiyun_check_and_start_auth

输出	处理方式
READY	✅ 直接执行用户任务，无需后续步骤
AUTH_REQUIRED:<url>	向用户展示授权链接（见下方模板），等待用户回复"已完成授权"后再执行第二步
ERROR:*	告知用户具体错误信息，并引导走第三步人工兜底手动设置 Token

⛔ 严格禁止：收到 AUTH_REQUIRED 后，必须先向用户展示授权链接，等待用户发送新消息确认已完成授权，才能进行第二步。

第二步：用户确认已完成授权后，主动查询 Token

✅ 触发条件：用户在新消息中明确回复"已授权"、"完成了"、"已完成授权"、"授权好了"等确认信息后，才执行本步骤。

macOS / Linux：

bash ./setup.sh weiyun_fetch_token

Windows (PowerShell)：

powershell -ExecutionPolicy Bypass -File setup.ps1 weiyun_fetch_token

输出	处理方式
TOKEN_READY	✅ 授权成功，继续执行用户任务
ERROR:not_authorized	告知用户：「您尚未完成授权，请在浏览器中完成后回复我。」（不要重新生成链接，等用户再次确认后重试本步骤）
ERROR:expired	告知用户：「您的微云 Token 已过期，请访问 获取新 Token 重新获取，然后告诉我新的 Token，我来帮您重置。」（引导用户走第三步人工兜底手动设置 Token）
ERROR:token_invalid	告知用户：「Token 已失效，请重新授权。」（需重新执行第一步）
ERROR:*	告知用户具体错误信息（错误码+描述），并引导走第三步人工兜底手动设置 Token

第三步：人工兜底

🔑 检查 Token 配置：可访问 https://www.weiyun.com/act/openclaw 获取 Token，再执行以下命令来设置 mcporter:

macOS / Linux：

# 使用传入的 Token 写入 mcporter 配置（weiyun）
mcporter config add weiyun "https://www.weiyun.com/api/v3/mcpserver" \
    --header "WyHeader=mcp_token=$Token" \
    --transport http \
    --scope home

Windows (PowerShell)：

# 使用传入的 Token 写入 mcporter 配置（weiyun）
mcporter config add weiyun "https://www.weiyun.com/api/v3/mcpserver" --header "WyHeader=mcp_token=$Token" --transport http --scope home

或者直接使用 setup 脚本一键设置：

powershell -ExecutionPolicy Bypass -File setup.ps1 weiyun_set_token <你的Token>

授权链接展示模板

当第一步输出 AUTH_REQUIRED:<url> 时，向用户展示：

🔑 需要先完成微云授权

请在浏览器中打开以下链接完成授权：点击授权微云

⚠️ 请使用 QQ 或微信 扫码 / 登录授权

⏰ 授权码有效期为 5 分钟，请尽快完成授权，超时后需重新发起请求（重新执行第一步）

✅ 完成授权后，请回复我「已完成授权」，我会继续帮您完成操作

⛔ AI 注意：展示上方授权链接后，必须停止等待，不得自动调用 weiyun_fetch_token 或任何其他工具。只有当用户在下一条新消息中明确回复确认后，才能继续执行第二步。

错误说明

错误	含义
ERROR:mcporter_not_found	缺少依赖，请先安装 Node.js
ERROR:not_authorized	用户尚未在浏览器完成授权，等待用户确认后重试
ERROR:expired	授权码已过期，重新执行第一步
ERROR:token_invalid	Token 鉴权失败，重新授权
ERROR:save_token_failed	Token 写入配置失败
ERROR:no_code	未找到授权码，需重新执行第一步
ERROR:network	网络请求失败，检查网络后重试

来源：FTN 两阶段上传协议

文件：C:\Users\xub\.workbuddy\skills\weiyun\references/upload_protocol.md

微云上传协议参考

1. 上传流程概览

MCP 客户端 (AI Agent)
    │
    │  1. 在本地计算 block_sha_list、check_sha、check_data
    │     （使用 scripts/gen_block_info_list.py 或等价逻辑）
    │
    ├─── 2. 预上传 ──→ weiyun.upload(upload_key="")
    │         │
    │         └── 返回: file_exist(是否秒传), upload_key, channel_list, ex
    │
    ├─── 3. 分片上传 (循环) ──→ weiyun.upload(upload_key="xxx")
    │         │
    │         └── 返回: upload_state(1=继续/2=完成/3=等待), channel_list, ex
    │
    └─── 4. 完成 (upload_state == 2)

关键原则：哈希计算在客户端完成。服务端在预上传阶段不接收原始文件数据用于哈希计算。

2. 预上传参数说明

预上传时需要提供以下参数（通过 weiyun.upload MCP Tool 传入）：

参数	类型	必填	说明
filename	string	是	文件名称
file_size	uint64	是	文件大小（字节）
file_sha	string	是	整个文件的 SHA1（40 字符 hex），必须等于 block_sha_list 最后一个值
file_md5	string	否	整个文件的 MD5（32 字符 hex），用于秒传校验
block_sha_list	string[]	是	分块 SHA1 列表（每个 40 字符 hex）
check_sha	string	是	SHA1 校验中间状态（40 字符 hex）
check_data	string	否	文件末尾校验字节的 Base64 编码
pdir_key	string	否	上传目标目录 key（不填使用 token 绑定目录）

预上传响应判断

• file_exist=true → 秒传成功，上传完毕
• file_exist=false → 使用返回的 upload_key、channel_list、ex 进行分片上传

3. 分片上传参数说明

参数	类型	必填	说明
upload_key	string	是	预上传返回的 upload_key
channel_list	McpChannelInfo[]	是	预上传返回的通道列表
channel_id	uint32	是	使用的通道编号
ex	string	是	预上传返回的扩展字段
file_data	bytes	是	分片数据（JSON 传输时为 base64）
filename	string	是	文件名称

上传状态

状态码	含义
1	需要上传下一分片
2	上传完成
3	等待其他通道完成

4. 分块 SHA1 算法 — 详细步骤

常量

• BLOCK_SIZE = 524288（512KB）

文件大小派生变量

lastBlockSize = file_size % BLOCK_SIZE
如果 lastBlockSize == 0：lastBlockSize = BLOCK_SIZE

checkBlockSize = lastBlockSize % 128
如果 checkBlockSize == 0：checkBlockSize = 128

beforeBlockSize = file_size - lastBlockSize

逐步算法

sha1 = new SHA1()   // 单个共享的 SHA1 对象

// 第一步：处理最后一块之前的所有块
for offset in range(0, beforeBlockSize, BLOCK_SIZE):
    data = read_file(offset, BLOCK_SIZE)
    sha1.update(data)
    block_sha_list.append(sha1.get_internal_state_little_endian())
    // get_internal_state_little_endian() 返回 h0-h4 以小端序输出的 20 字节 hex 编码

// 第二步：处理最后一块的前半部分，计算 check_sha
between_data = read_file(beforeBlockSize, lastBlockSize - checkBlockSize)
sha1.update(between_data)
check_sha = sha1.get_internal_state_little_endian()

// 第三步：处理文件末尾的 checkBlockSize 字节
check_data_bytes = read_file(file_size - checkBlockSize, checkBlockSize)
sha1.update(check_data_bytes)
file_sha = sha1.hexdigest()  // 标准 SHA1 含 finalization（大端序）
check_data = base64_encode(check_data_bytes)

// 第四步：最后一块的 sha = file_sha（不是内部状态！）
block_sha_list.append(file_sha)

内部状态提取（get_state）

get_state() 函数读取 SHA1 内部寄存器 h0-h4（每个 32 位），以小端序字节顺序输出：

result = b""
for h in (h0, h1, h2, h3, h4):
    result += struct.pack("<I", h)  # 小端序 uint32
return result.hex()  # 40 字符 hex 字符串

重要：调用 get_state() 时，已处理的数据长度必须精确对齐到 64 字节边界（SHA1 block 大小）。BLOCK_SIZE 为 524288，能被 64 整除，因此所有非最后块都能保证对齐。

5. 常见错误码

上传过程中可能遇到的错误码：

错误码	说明
-6014	空间不足
-20001	SHA1 校验错误
-44001	参数无效
-44003	权限不足
-44010	文件名过长
-89001	分片 SHA 校验失败

6. 使用建议

upload_key 和 ex

这两个是预上传返回的不透明字符串，分片上传时原样传递，不要额外做编码或解码。

推荐使用一键上传脚本

直接使用 scripts/upload_to_weiyun.py 可以跳过手动参数计算，一键完成上传：

python3 scripts/upload_to_weiyun.py /path/to/file --token <mcp_token>

---

模态词等级表与示例约定（STD-D）

本范式条款所用模态词，按五级体系执行，与 RFC 2119 对齐并补其缺失的 RECOMMENDED 级：

中文模态词	英文对应	语义	违反后果
必须	MUST / MUST NOT（否定式）	绝对要求，无任何例外	判 P1 阻断
禁止	MUST NOT	绝对禁止	判 P1 阻断
应	SHALL	要求；若确有例外，须在条款内显式声明例外条件	判 P2 整改
宜	SHOULD（RECOMMENDED）	推荐做法；可不采用，但须记录理由	判 P3 提示
可	MAY	允许，表许可而非能力	不构成违规

表能力时用「能够」，不用「可」。

示例约定：条款下以「例：」引导数值或场景示例，以「反例：」引导错误用法。

术语与定义

下列术语和定义适用于本范式。禁止循环定义（不得以 A 定义 B 又以 B 定义 A）。

术语	定义
mcp_token	微云 MCP 鉴权令牌，经 WyHeader HTTP 头传递（除 check_skill_update 外所有工具）
weiyun.list	目录列表查询工具（get_type/offset/limit≤50/order_by/asc，查询范围由 token 绑定 dirkey/pdirkey 决定）
FTN 两阶段上传	预上传（upload_key 空）+ 分片上传（upload_key 非空）两阶段协议，支持秒传（file_exist=true）
block_sha_list	分块 SHA1 列表（512KB 分块，每 40 字符 hex），哈希在客户端计算，服务端不接收原始数据算哈希
upload_state	上传状态：1=需上传下一分片，2=上传完成，3=等待其他通道完成
WyHeader	HTTP 头传递 mcp_token 的载体（格式 WyHeader: mcp_token=）
pdir_key 顶层值	分享/移动/重命名必须使用 weiyun.list 响应顶层的 pdir_key，不可为空（文件项内 pdir_key 可能为空串）
授权流程三步骤	检查状态（READY/AUTH_REQUIRED/ERROR）→ 用户确认后取 Token → 人工兜底 mcporter config add weiyun
错误码	-6014 空间不足 / -20001 SHA1 校验错误 / -44001 参数无效 / -44003 权限不足 / -44010 文件名过长 / -89001 分片 SHA 校验失败
upload_to_weiyun.py	一键上传脚本（跳过手动参数计算，python3 scripts/upload_to_weiyun.py --token ）

第二篇 流程与实施

本篇承接本范式既有工作流条款，汇总实施要点（原有条款原文一字未改，本篇仅作结构承接）：

• 启动顺序五步闭环：读 MEMORY → 跑 _tools → 查 README → 查技术规范与 SOP → 建任务夹
• 升级五步闭环：只按本技术规范修改，不重写整个 SKILL.md，不碰全域规则与工具链
• 鉴权三步骤：检查状态（READY 直行 / AUTH_REQUIRED 展示链接等待确认 / ERROR 人工兜底）→ 用户确认后取 Token → mcporter config 兜底
• 上传走 FTN 两阶段：客户端算哈希 → 预上传 → 分片循环（upload_state=2 完成）；可用 upload_to_weiyun.py 一键上传
• 目录操作纪律：pdir_key 一律用 weiyun.list 顶层值，不可为空（分享/移动/重命名）
• 数据可靠性：接口字段/错误码以微云官方文档为准，不臆造；执行上传/删除等外部动作前先确认

第三篇 风险与失效模式

图3-1 微云 MCP 两阶段上传流程（认知入口）

客户端计算哈希(block_sha_list/check_sha)
   │
   ▼
预上传 weiyun.upload(upload_key="")
   │ 返回 file_exist/upload_key/channel_list/ex
   ▼
file_exist=true → 秒传完成
   │false
   ▼
分片上传循环（upload_state=1 继续）
   │
   ▼
upload_state=2 → 上传完成

失效模式对照表（三列：失效模式 / 后果 / 防护条款，必须 100% 可追溯到本范式条款）：

失效模式	后果	防护条款
FM-1 鉴权失配	mcp_token 未带或错放（非 WyHeader 头），工具调用被拒	认证机制（WyHeader: mcp_token=）
FM-2 哈希错位	block_sha_list/check_sha/file_sha 计算错误（未对齐 64 字节、小端序错）	分块 SHA1 算法（get_state 小端序 + 64 字节对齐）
FM-3 pdir_key 空值	分享/移动/重命名传空 pdir_key，链接异常或操作失败	pdir_key 顶层值规则（weiyun.list 顶层值，不可为空）
FM-4 越权授权	AUTH_REQUIRED 后未等用户确认就 fetch_token，流程失序	鉴权流程（展示链接后必须停止等待用户确认）
FM-5 分片中断	upload_key/ex 被额外编码/解码或未原样传递，分片失败	FTN 协议（不透明字符串原样传递，不做编解码）
FM-6 续拉错乱	local_version/server_version 未正确回填，增量拉取错漏	list_by_category 游标规则（首次空串，续拉回填）

第四篇 保障、记录与附录

评审机制

• 触发：本范式所规范对象升版、或相关工具链脚本变更时必须触发评审。
• 评审人：利衡辨全域治理工作组；对象维护人复核。
• 评审内容：①条款与本范式是否一致；②失效模式表是否覆盖新增风险（见第三篇）；③成文规范符合性（doc_style_check.py 判定结果）。
• 周期：宜每个季度至少一次例行评审；重大变更即时评审。

修订记录

修订记录必须含完整连续版本链，并与正文、头部版本号三处一致（STD-A）。

版本	日期	变更	编制	审核	批准
V1.0.0	2026-08-25	首版（原稿基线，条款未动）	利衡辨工作组	全域治理工作组	衡明合
V1.0.1	2026-08-31	成文规范整改（升次版本）：按《MASTER RULE 技术标准成文规范》补齐——模态词五级等级表、四篇式结构、术语和定义（10 条）、失效模式对照表（6 项）、认知入口图、必备附录 A–D、评审机制、修订记录、审批记录、定稿校核结论、待确认事项闭环记录。原有条款一字未改，仅增补结构与记录。	利衡辨工作组	全域治理工作组	衡明合

审批记录

项	内容
定稿版本	V1.0.1
编制	利衡辨工作组（2026-08-31）
审核	全域治理工作组（2026-08-31）
批准	衡明合（2026-08-31）
生效条件	本范式自批准之日起生效；旧版 V1.0.0 归档 .bak 保留可回退

定稿校核结论

• 校核工具：~/.workbuddy/_tools/doc_style_check.py（母规则 AUTO 条款自动判定器）。
• 校核对象：本文件（~/.workbuddy/spec\3.行政法规\范式\）。
• V1.0.0 基线：P1 不通过 9 项、P2 不通过 6 项。
• V1.0.1 结果：P1 不通过 0 项、P2 不通过 0 项（退出码 0）。
• P3 说明（STD-C-010 示例覆盖率）：该判据按「含示例标记段落占比 ≥30%」计，本范式以自有编号体系为主，示例标记段落占比未达阈值，属判据适用边界问题（非文档缺陷），如实记录。
• 结论：本范式在保持原有条款不变的前提下，完成母规则结构与记录类条款整改；P1/P2 全部清零，可作为 MCP协议标准(weiyun) 的升级依据。

待确认事项

编号	事项	提出版本	责任人	状态
Q1	认知入口图现以 ASCII 框图呈现，待具备图形生成条件后替换为正式插图	V1.0.1	利衡辨工作组	待替换
Q2	微云 MCP 错误码与接口字段随服务端演进，需周期性复核官方文档	V1.0.1	利衡辨工作组	待复核

---

附录 A 速查表

本范式核心要求速查（详见正文对应章节）：

场景	要求	位置
启动顺序五步闭环：读 MEMORY → 跑 _tools → 查 README → 查技术规范与 SOP → 建任务夹	强制闭环	正文工作流章节
升级五步闭环：只按本技术规范修改，不重写整个 SKILL.md，不碰全域规则与工具链	强制闭环	正文工作流章节
鉴权三步骤：检查状态（READY 直行 / AUTH_REQUIRED 展示链接等待确认 / ERROR 人工兜底）→ 用户确认后取 Token → mcporter config 兜底	强制闭环	正文工作流章节
上传走 FTN 两阶段：客户端算哈希 → 预上传 → 分片循环（upload_state=2 完成）；可用 upload_to_weiyun.py 一键上传	强制闭环	正文工作流章节
目录操作纪律：pdir_key 一律用 weiyun.list 顶层值，不可为空（分享/移动/重命名）	强制闭环	正文工作流章节
数据可靠性：接口字段/错误码以微云官方文档为准，不臆造；执行上传/删除等外部动作前先确认	强制闭环	正文工作流章节

附录 B 术语表

同正文「术语和定义」，共 10 条：mcp_token、weiyun.list、FTN 两阶段上传、block_sha_list、upload_state、WyHeader、pdir_key 顶层值、授权流程三步骤、错误码、upload_to_weiyun.py。

附录 C 工具链清单

工具	用途	位置
成文规范判定器	母规则 AUTO 条款机器判定	~/.workbuddy/_tools/doc_style_check.py
交付物命名与校验库	交付物路径派生、命名闸	~/.workbuddy/_tools/deliverable.py
规范闸门	无技术规范拒绝升级	~/.workbuddy/_tools/expert_spec_gate.py

附录 D 记录字段明细

字段	含义	引入版本
版本号	本范式当前版本（正文与头部三处一致）	V1.0.0
模态词等级	五级体系（必须/禁止/应/宜/可）	V1.0.1
失效模式编号	FM-N 与防护条款一一对应	V1.0.1