eutopiazen/clouddrive2

CloudDrive2 雲端硬碟管理

透過本機 CloudDrive2 gRPC 服務執行雲端硬碟（115/百度網盤/迅雷/本地目錄）的檔案操作與系統管理。服務位址 127.0.0.1:19798，已登入，認證自動完成。

前置

• 服務常駐執行，無需啟動
• 認證自動：優先處理 CD2_TOKEN/CLOUDDRIVEAPI 環境變數 → 本機 /opt/clouddrive2/config/api_tokens.json 內的 API token → GET token.txt。通常可直接使用。
• 工具目錄：/root/.openclaw/workspace/skills/clouddrive2/
  • cd2.py — 通用呼叫器，支援全部 227 個 RPC
  • cd2cmd.py — 常用命令便捷封裝
  • gen/proto/ — 產生的 Python gRPC 客戶端（請勿更動）
  • clouddrive.proto — 最新 proto 定義（1.0.17）
  • docs/ — 官方 gRPC 文件快照（錯誤時的說明書）

官方文件說明書

• 本地快照：docs/CloudDrive2_gRPC_API_Guide_zh-CN.md（隨官方更新自動同步）
• 報錯或查詢欄位時優先查閱此處：方法名稱、請求/回應欄位、列舉值、常見錯誤說明皆在此文件中
• 線上版：https://www.clouddrive2.com/api/CloudDrive2_gRPC_API_Guide.html
• 自動更新：每週一自動偵測官方文件/proto 變更，有更新時自動重新產生客戶端並同步三處（本工作副本、~/.agents/skills/clouddrive2、GitHub eutopiazen/clouddrive2-skill），變更摘要寫入 scripts/cd2doc-watch/changes/

用法

A. 快捷命令（cd2cmd.py，高頻操作首選）

cd /root/.openclaw/workspace/skills/clouddrive2
python3 cd2cmd.py ls /115open            # 列出目錄：名稱<TAB>大小<TAB>類型
python3 cd2cmd.py ls / --refresh         # 強制重新整理快取
python3 cd2cmd.py find /115open 電影     # 模糊搜尋
python3 cd2cmd.py info /115open/xx.mkv   # 檔案詳細資訊
python3 cd2cmd.py mkdir /115open 新資料夾
python3 cd2cmd.py mv /115open/a.mkv /115open/電影        # 移動（預設 rename 衝突）
python3 cd2cmd.py cp /115open/a.mkv /115open/備份 --policy overwrite
python3 cd2cmd.py rm /115open/垃圾.mkv                    # 刪除（資源回收桶）
python3 cd2cmd.py rmperm /115open/垃圾.mkv                # 永久刪除
python3 cd2cmd.py rn /115open/a.mkv b.mkv                # 重新命名
python3 cd2cmd.py dl /115open/a.mkv                      # 下載URL + curl/wget
python3 cd2cmd.py mounts | clouds | copy-tasks           # 掛載點/雲端硬碟/複製任務
python3 cd2cmd.py dl-tasks | ul-tasks                    # 下載/上傳佇列
python3 cd2cmd.py backups                                # 備份狀態
python3 cd2cmd.py settings | acct | tokens               # 設定/帳戶/令牌
python3 cd2cmd.py token-create 名稱 --perm allow_read allow_list
python3 cd2cmd.py unlock /path 密碼 [--permanent]
python3 cd2cmd.py stat                                   # 系統資訊

B. 任意 RPC（cd2.py）—— 文件全部功能

python3 cd2.py <RpcName> [field=value ...] [--json|--raw|--no-auth|--list]

• 欄位名稱使用 camelCase（與文件一致），巢狀結構使用 .：subField=value
• 數值會依據 JSON 解析（數字/bool/陣列自動轉換），串流方法會自動聚合
• --list 列出全部 227 個方法名稱
• 常用範例：

python3 cd2.py GetSubFiles path=/115open forceRefresh=true
python3 cd2.py FindFileByPath parentPath=/115open path=/115open/電影/xxx.mkv
python3 cd2.py GetSearchResults searchFor=電影 path=/ fuzzyMatch=true
python3 cd2.py CreateFolder parentPath=/115open folderName=新目錄
python3 cd2.py RenameFile theFilePath=/115open/a.mkv newName=b.mkv
python3 cd2.py MoveFile theFilePaths=/115open/a.mkv destPath=/115open/電影 conflictPolicy=Rename
python3 cd2.py CopyFile theFilePaths=/115open/a.mkv destPath=/115open/備份 conflictPolicy=Skip
python3 cd2.py DeleteFiles path=/115open/垃圾1.mkv path=/115open/垃圾2.mkv
python3 cd2.py GetMountPoints
python3 cd2.py GetAllCloudApis
python3 cd2.py GetDownloadUrlPath path=/115open/a.mkv preview=false
python3 cd2.py GetCopyTasks
python3 cd2.py BackupGetAll
python3 cd2.py GetAccountStatus
python3 cd2.py ListTokens
python3 cd2.py GetSystemSettings

關鍵概念

• 路徑前綴（雲端硬碟根目錄）：/115open、/百度網盤、/迅雷雲盤、/mnt（本機磁碟）、/CD2（本機 /ssd/CD2）
• 衝突策略 conflictPolicy：Overwrite=0 / Rename=1 / Skip=2
• 雲端硬碟列表：python3 cd2.py GetAllCloudApis
• 掛載點：預設僅掛載 /mnt/115open，使用 GetMountPoints 檢視
• 刪除 預設進入資源回收桶；DeleteFilesPermanently/rmperm 才是永久刪除
• 下載：GetDownloadUrlPath 回傳拼接好的 URL（directUrl 優先，否則 downloadUrlPath 包含 {SCHEME}/{HOST}/{PREVIEW} 佔位符號需置換）；位址使用 127.0.0.1:19798
• 大型檔案操作（跨雲端硬碟移動/複製）會產生背景任務，使用 GetCopyTasks 追蹤

認證故障排除

• No valid auth token → 憑證檔案/環境遺失，檢查 api_tokens.json 是否存在
• 2FA 提示 → 需要 CD2_TOTP 或改用 API token
• 公用方法（GetSystemInfo/GetToken/Login 等）不需要認證，加上 --no-auth

驗證

每次執行操作後，應透過結果欄位確認成功：

• 建立/移動/複製/刪除 → 回傳 FileOperationResult 包含 success/errorMessage
• 列出/搜尋 → 檢查回傳的項目數量與目標
• 若操作失敗，先查看 errorMessage，再決定重試或查詢任務狀態