前言¶
在 Agent 工作流裏，個人文件往往還在網盤裏：備份、分享鏈接、按目錄整理，都要先打開瀏覽器或客戶端。若希望對話裏直接「列目錄、上傳、生成外鏈」，需要一套穩定的網盤 API 與鑑權方式，還要把 Tool 名、參數約定寫進 Skill，避免模型誤觸騰訊文檔、本地路徑或其他雲盤。
下面介紹 SkillHub 上的 微雲 MCP（@tencent-adm/tencent-drive-mcp）：面向 weiyun.com 微雲網盤 的 MCP 文件操作技能，由騰訊微雲發佈，當前 SkillHub 版本 1.0.6，分類 dev-programming，標籤含 requires_api_key=true（需配置 MCP Token）。
這是什麼¶
微雲 MCP 是一份基於通用 SKILL.md 格式的 Agent 技能包：指導模型在正確場景下調用微雲 MCP Server 上的 weiyun.* 工具，並附帶授權腳本、上傳腳本與 API/工作流參考文檔。
- 出品：騰訊微雲（SkillHub 座標
@tencent-adm/tencent-drive-mcp） - 協議：MCP（HTTP 傳輸），服務端地址爲
https://www.weiyun.com/api/v3/mcpserver - 邊界：僅處理微雲網盤存儲的文件；與騰訊文檔（docs.qq.com）、純本地文件、微信/QQ 直髮、其他網盤無關（技能內對這類需求有明確負向排除說明）
SkillHub 頁面：https://www.skillhub.cn/skills/tencent-adm/tencent-drive-mcp
技能包 API：https://api.skillhub.cn/tencent-adm/tencent-drive-mcp
核心功能¶
技能說明中歸納的能力如下（經 SkillHub 簡介與技能包 SKILL.md 覈對）。
MCP Tool（共 14 個）¶
| 工具名 | 作用 |
|---|---|
weiyun.list |
目錄列表 |
weiyun.list_by_category |
按分類拉取 |
weiyun.recent_list |
最近訪問 |
weiyun.search |
搜索 |
weiyun.download |
批量獲取下載信息 |
weiyun.delete |
批量刪除 |
weiyun.upload |
兩階段上傳 |
weiyun.gen_share_link |
生成分享外鏈 |
weiyun.rename_file / weiyun.rename_dir |
重命名文件/目錄 |
weiyun.create_dir |
創建文件夾 |
weiyun.move_file / weiyun.move_dir |
移動文件/目錄 |
check_skill_update |
檢查技能版本更新 |
調用時需在 req_header 中攜帶 qua 與 version；HTTP 認證頭爲 WyHeader: mcp_token=<token>。
上傳與 FTN 協議¶
- 上傳可走 MCP 兩階段流程；技能推薦使用一鍵腳本
scripts/upload_to_weiyun.py。 - 大文件 FTN 上傳需要 SHA1 分塊（
block_sha_list）；技能提供scripts/gen_block_info_list.py等腳本，上傳協議細節見包內references/upload_protocol.md。
觸發與排除（Agent 路由）¶
正向觸發：用戶提到「微雲」「weiyun」「微雲網盤」，或調用 weiyun.list / weiyun.upload / weiyun.download / weiyun.gen_share_link / weiyun.recent_list / weiyun.search 等，或提及 block_sha_list、FTN 上傳。
不應觸發：騰訊文檔在線編輯、與微雲無關的本地文件操作、向微信/QQ 聯繫人或羣直接發文件、百度網盤/OneDrive 等；用戶明確不用微雲時應停用本技能。
安裝與啓用¶
1、安裝 SkillHub CLI（若尚未安裝）¶
按 SkillHub 安裝文檔 檢查 CLI：
command -v skillhub && skillhub --version
未安裝時可執行：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2、安裝微雲 MCP 到當前 Agent 的 skills 目錄¶
安裝時必須用 --dir 指向 Agent 識別的 skills 路徑，否則默認落在 ./skills/ 可能無法加載。
skillhub install tencent-drive-mcp --namespace tencent-adm --dir <你的 skills 目錄>
常見路徑（來自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下.agents/skills/
也可將下面提示交給 AI，讓其按官方流程安裝：
請根據 https://skillhub.cn/install/skillhub.md，安裝 `@tencent-adm/tencent-drive-mcp`。
3、配置 MCP 鑑權（mcporter + Token）¶
技能依賴 mcporter 連接微雲 MCP Server。在技能包目錄下，先做授權檢查：
bash ./setup.sh weiyun_check_and_start_auth
- 輸出
READY：可直接調用工具。 - 輸出
AUTH_REQUIRED:<url>：在瀏覽器用 QQ/微信完成授權，用戶確認後再執行：
bash ./setup.sh weiyun_fetch_token
成功時輸出 TOKEN_READY。若已有 Token，也可在 微雲 OpenClaw 活動頁 獲取後寫入：
bash ./setup.sh weiyun_set_token <你的Token>
或手動配置 mcporter（與 references/auth.md 一致）：
mcporter config add weiyun "https://www.weiyun.com/api/v3/mcpserver" \
--header "WyHeader=mcp_token=$Token" \
--transport http \
--scope home
Windows 下將 bash ./setup.sh 替換爲 powershell -ExecutionPolicy Bypass -File setup.ps1。
4、上傳相關環境¶
- 上傳需要 Python 3 與
requests（pip install requests）。 - 列表、下載、分享、刪除、重命名、移動、搜索等可不依賴 Python。
典型用法¶
用 mcporter 列目錄¶
在 mcporter 已配置 weiyun 的前提下：
mcporter call --server weiyun --tool weiyun.list limit=50 order_by=2 --output json
注意：須使用 --server weiyun --tool weiyun.xxx，避免把 server 與 tool 名拼錯。
列出根目錄（JSON 請求體示例）¶
技能文檔中的 weiyun.list 示例：
{"limit": 50, "get_type": 0, "req_header": {"qua": "MAC_15.4.1_CODEBUDDY_4.8.1", "version": "1.0.8"}}
qua 按實際客戶端平臺與版本填寫；version 與當前技能 frontmatter 版本一致。
上傳本地文件¶
推薦在技能包目錄執行：
python3 scripts/upload_to_weiyun.py /path/to/file --pdir_key <pdir_key>
--token 可顯式傳入，或設置環境變量 WEIYUN_MCP_TOKEN。pdir_key 應使用 weiyun.list 響應頂層的 pdir_key，不要用單個條目裏可能爲空的字段。
下載與分享¶
weiyun.list取得file_id與頂層pdir_key。weiyun.download拿到 HTTPS 地址後，用curl落盤，並覈對文件大小與file_size。weiyun.gen_share_link生成外鏈；file_list中的pdir_key必須非空。分享鏈接無法用本技能直接當下載接口，需在瀏覽器打開。
更完整的九類工作流見包內 references/workflows.md；參數表見 references/mcp_api.md。
適用場景與注意¶
適合誰
- 已在用微雲網盤存個人/團隊文件，希望在 Cursor、Claude Code、Codex 等 Agent 裏用自然語言或 Tool 調用完成網盤操作。
- 需要腳本化 FTN 分塊上傳、批量整理目錄、生成帶密碼的分享鏈。
限制與坑
| 事項 | 說明 |
|---|---|
| 產品邊界 | 微雲網盤 ≠ 騰訊文檔；IM 直髮文件不支持，可改用 weiyun.gen_share_link |
| 刪除目錄 | dir_name 必填，且技能要求刪除目錄前必須讓用戶再次確認 |
| 搜索後續操作 | 搜索結果不含 pdir_key，需再用 weiyun.list 定位 |
| 錯誤碼 | 如 117402 Token 無效、1192 目錄名無效、50000 服務繁忙等，見 references/faq.md |
| SkillHub 數據 | 頁面顯示評分 100000、下載約 2433 次（以 SkillHub 爲準） |
結尾¶
微雲 MCP 把 weiyun.com 網盤 的文件操作收斂到 MCP Tool 與一套授權/上傳腳本里，並寫清觸發邊界，減少 Agent 誤用其他產品或本地路徑。若你的文件在微雲且 Agent 已支持 SkillHub 安裝，可按上文裝好技能、完成 Token 配置後，從 weiyun.list 或上傳腳本開始驗證。
官方入口：https://api.skillhub.cn/tencent-adm/tencent-drive-mcp
