微云工具箱（免费版）

概述

微云网盘是腾讯提供的个人云存储服务。本工具箱通过 MCP工具协议与微云网盘交互，把日常的"列目录、下载、上传"三件事封装成可直接复制的工作流。免费版聚焦于"能用、够用"，专业版补齐分享、删除、重命名、移动、分类查询等进阶操作。

所有文件哈希计算与分片逻辑均在本地完成，服务端只接收预计算好的哈希值，既保护隐私又降低服务端压力。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 按照skill规范执行核心功能执行操作,遵循单一意图原则。 输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。 输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。 输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：微云网盘文件管理、免费版、目录浏览、文件下载与上传、内置一键脚本与基、础错误码指南、微云工具箱、面向个人用户与独、立开发者、封装微云网盘的日、常文件操作、文件下载、文件上传、MCP、工具协议与微云网、盘交互、所有文件哈希计算、在本地完成、避免敏感数据外泄、Use、when、需要数据分析、报表生成、统计洞察、数据可视化时使用、不适用于实时流数、据处理、适用于独立开发者、企业团队和自动化、工作流场景等。

使用场景

场景一：下载网盘中的文档到本地

用户说"把我微云里的会议纪要下载下来"。Agent 应先调用 weiyun.list 浏览目录定位文件，拿到 file_id 与顶层 pdir_key，再调用 weiyun.download 获取下载链接，最后用 curl -b 携带 cookie 下载。

场景二：上传本地文件到网盘备份

用户说"把这个项目压缩包传到微云"。Agent 应直接调用一键脚本 upload_to_weiyun.py，传入文件路径与目标目录 pdir_key，无需手动计算分片哈希。

场景三：浏览网盘结构

用户说"看看我微云根目录有哪些东西"。Agent 调用 weiyun.list，参数 limit=50, get_type=0，回显 dir_list 与 file_list。

快速开始

60 秒上手

1. 确认已通过微云授权获得 MCP工具 token（存于环境变量 WEIYUN_MCP_TOKEN）
2. 浏览目录：调用 weiyun.list
3. 下载文件：调用 weiyun.download 获取链接后用 curl 下载
4. 上传文件：直接运行一键脚本

一键上传脚本（推荐）

# Linux/macOS
python3 scripts/upload_to_weiyun.py /path/to/file --token  --pdir_key 

# Windows PowerShell（需先切换 UTF-8 编码）
chcp 65001 >nul && python scriptsupload_to_weiyun.py C:pathtofile --pdir_key 

脚本参数：

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。

示例

目录列表查询

调用 weiyun.list，参数：
  limit = 50
  get_type = 0    # 0-所有，1-仅目录，2-仅文件

响应包含 pdir_key（顶层目录 key，后续操作必填）、dir_list、file_list、finish_flag。

下载文件

调用 weiyun.download，参数：
  items = [{"file_id": "", "pdir_key": "<顶层 pdir_key>"}]

返回每个文件的 https_download_url 与 cookie，下载时必须携带：

curl -s -L -o <本地文件名> -b "" ""

上传文件（手动方式）

阶段一：预上传
  filename, file_size, file_sha, block_sha_list, check_sha
  → file_exist=true 秒传成功
  → file_exist=false 获取 upload_key + channel_list

阶段二：分片上传
  upload_key, channel_list, channel_id, ex, file_data, filename
  → status=1 继续下一片
  → status=2 上传完成

最佳实践

1. pdir_key 取值规则

所有需要 pdir_key 的操作都必须使用 weiyun.list 响应顶层的 pdir_key，不要使用文件条目自身的 pdir_key 字段（该字段常为空字符串）。这是最常见的错误来源。

2. 下载 cookie 携带

weiyun.download 返回的下载链接必须用 curl -b 携带 cookie，且加 -L 跟随重定向，否则会 403。

3. 上传优先用脚本

手动计算 block_sha_list 容易出错（微云使用流式 SHA1 内部状态，非标准独立分块 SHA1）。优先使用 upload_to_weiyun.py，它内置哈希计算与重试逻辑。

4. 服务繁忙重试

遇到 retcode=50000 时，等待 2-5 秒后重试，最多 3 次。一键脚本已内置此逻辑。

5. 安全披露

上传脚本会读取本地文件与 WEIYUN_MCP_TOKEN 环境变量，并向受信任的微云 MCP端点 发起 HTTPS 请求。调用前应向用户确认文件路径，禁止用通配符触发上传。

常见问题

Q1：下载时 pdir_key 应该填什么？

A：使用 weiyun.list 响应中顶层的 pdir_key，不是文件自身的 pdir_key 字段（该字段可能为空字符串）。

Q2：上传报 "Cannot upload to a directory that you do not own"？

A：必须指定 --pdir_key 参数。先调用 weiyun.list 获取响应顶层的 pdir_key。

Q3：分片上传通道 len=0？

A：每轮上传完一片后，通道列表可能全部 len=0，需要重新预上传获取下一批通道。一键脚本已自动处理。

Q4：SHA1 不匹配？

A：确保分块 SHA 值使用流式 SHA1 内部状态（小端序），而非独立分块 SHA1。直接用一键脚本可避免此问题。

Q5：file_sha 被覆盖？

A：服务端用最后一个 block 的 SHA 覆盖 file_sha，两者必须相等。一键脚本会自动保证这一点。

Q6：通道 ID 不匹配？

A：上传分片时 channel_id 必须与 channel_list 中某个条目匹配，否则报错。

Q7：Windows 下中文乱码？

A：执行 Python 脚本或命令前必须先 chcp 65001 >nul 切换控制台为 UTF-8，且 Windows 下用 python 而非 python3。

错误处理

已知限制

本免费体验版限制以下高级功能：

• 按分类查询文件（weiyun.list_by_category，文档/图片/视频分类）
• 生成分享外链（weiyun.gen_share_link，含密码设置）
• 批量删除（weiyun.delete，支持回收站与彻底删除）
• 重命名文件/目录（weiyun.rename_file/rename_dir）
• 创建文件夹与移动文件/目录（weiyun.create_dir/move_file/move_dir）
• 技能版本自动检查更新（check_skill_update）
• 高级错误恢复与重试策略

解锁全部功能请使用专业版：weiyun-toolkit-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• Python：3.8+（运行上传脚本）
• 网络：可访问 https://www.weiyun.com 域名

依赖详情

API Key 配置

• 微云 MCP工具 token：通过微云授权流程获取，存于环境变量 WEIYUN_MCP_TOKEN
• 环境标识：SIT 环境需额外设置 WEIYUN_ENV_ID
• 禁止：在 SKILL.md 或脚本中硬编码 token
• 端点白名单：脚本仅接受 https://*.weiyun.com / *.qq.com 的 MCP server 端点

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务
• 模型路由建议：免费版使用低成本模型（如 GPT-4o-mini / Claude Haiku）