前言¶
在 Agent 裏處理騰訊雲 COS，常見做法是臨時寫一段 SDK 示例，或把控制台步驟口述給用戶。上傳、列目錄、簽名鏈接、批量同步各自一套參數，刪改對象還要反覆確認路徑。下面介紹 SkillHub 上的社區技能「騰訊雲COS技能」（@user_9aa92135/tx-cos）：把 COS 高頻操作收斂成 OpenClaw 可調用的工作流，並附帶可複用的 Node 腳本。
這是什麼¶
「騰訊雲COS技能」是面向 OpenClaw 的騰訊雲 COS 原生操作技能，座標 @user_9aa92135/tx-cos，當前 SkillHub 頁面標註版本 1.0.0，來源爲 community，分類 it-ops-security。發佈者爲 user_9aa92135。Skill 元數據要求運行環境具備 node 與 npm；SkillHub 標籤爲 requires_api_key=false（指技能商店側不要求額外 API Key，訪問 COS 仍須配置騰訊雲憑證）。
技能目標是把對象存儲變成 Agent 可直接調度的一組腳本化流程：先校驗配置，再按場景調用 scripts/ 下腳本，結果以結構化 JSON 或簡潔中文返回。
核心功能¶
以下能力與 SkillHub 簡介及技能包內 SKILL.md 一致，均已覈實：
- 上傳：單文件上傳、目錄/多文件批量上傳、大文件分片上傳（可配置分片大小、併發等）。
- 訪問：生成對象臨時簽名 URL（文檔默認有效期示例爲 3600 秒）。
- 瀏覽：按前綴列出對象，用
Prefix+Delimiter: '/'模擬文件夾視圖。 - 對象管理：複製、移動、重命名、刪除對象；創建文件夾；遞歸刪除文件夾。
- 統計：統計某前綴下文件數量、總體積與類型分佈。
- 排障：檢查 COS 憑證、地域、Bucket、自定義域名等配置是否齊全。
技能包內腳本清單（Agent 優先複用，避免每次重寫邏輯）：
| 腳本 | 用途 |
|---|---|
scripts/check_config.js |
檢查關鍵環境變量 |
scripts/upload_file.js |
上傳單個文件 |
scripts/upload_batch.js |
批量上傳文件或目錄 |
scripts/upload_large_file.js |
大文件分片上傳 |
scripts/generate_signed_url.js |
生成臨時簽名鏈接 |
scripts/list_objects.js |
列出對象或文件夾視圖 |
scripts/manage_objects.js |
刪除、批量刪除、複製、移動、重命名、創建文件夾 |
scripts/delete_folder.js |
刪除文件夾（支持遞歸） |
scripts/get_folder_stats.js |
目錄體量與類型統計 |
安裝與啓用¶
通過 SkillHub CLI 安裝¶
安裝前確認本機已有 skillhub（安裝方式見 SkillHub 安裝文檔）。必須用 --dir 指向當前 Agent 的 skills 目錄，否則技能不會被識別。
command -v skillhub && skillhub --version
skillhub install tx-cos --namespace user_9aa92135 --dir <skills 目錄>
各客戶端常用 skills 目錄（摘自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
OpenClaw 及其變體（NanoBot、PicoClaw、memUBot 等）同樣使用各自的 skills 目錄，安裝後按對應 Agent 要求重啓或刷新技能列表。
通過自然語言讓 AI 安裝¶
SkillHub 頁面提供的提示詞爲：請根據 https://skillhub.cn/install/skillhub.md，安裝 @user_9aa92135/tx-cos。
環境變量（COS 訪問）¶
scripts/check_config.js 會檢查下列變量。必需項未設置時，技能要求先說明缺失項，不繼續執行上傳/刪除類操作。
必需：
COS_SECRET_ID=
COS_SECRET_KEY=
COS_REGION=
COS_BUCKET=
可選：
COS_DOMAIN=
典型用法¶
技能約定：需要真實讀寫 COS 時，優先執行 scripts/ 下腳本，入參爲 單行 JSON 字符串（與 SKILL.md 中的調用形式一致；路徑以技能包內 scripts/ 爲準）。
1. 先檢查配置¶
確認憑證與 Bucket 相關環境變量已導出後，讓 Agent 運行配置檢查腳本。輸出爲 JSON，標明各鍵是否已設置。
2. 上傳單個文件¶
upload_file.js 要求 JSON 至少包含 file_path；可選 object_key（默認取本地文件名 basename）、custom_domain。
示例入參結構：
{"file_path": "/path/to/local/file.zip", "object_key": "builds/file.zip"}
成功時腳本返回對象鍵、大小、ETag、訪問 URL 等字段。
3. 生成臨時簽名鏈接¶
適用「給一個可下載的臨時鏈接」。關鍵參數包括對象 Key 與 Expires；用戶未指定有效期時，技能文檔建議默認 3600 秒並明確告知爲臨時鏈接。
4. 列目錄與謹慎刪除¶
列目錄時優先返回文件夾與文件分組；結果過多時只展示前若干項並提示可繼續翻頁。刪除、批量刪除、遞歸刪文件夾前，技能要求確認對象鍵或前綴範圍；移動/重命名會提示其本質多爲複製後刪除。
大文件上傳場景下，文檔建議顯式設置分片大小（SliceSize）、併發（AsyncLimit）並說明網絡與覆蓋同名對象的風險。
適用場景與注意¶
適合誰
- 已在用 OpenClaw 系 Agent，需要把本地構建產物、備份、媒體文件同步到騰訊雲 COS。
- 希望用統一腳本完成上傳、簽名分享、目錄瀏覽與清理，而不是每次讓模型從零寫 SDK 代碼。
- 需要快速判斷「是憑證、地域還是 Bucket 名配錯」的運維/開發場景。
限制與注意
- 依賴 Node 運行時；需在技能目錄或依賴環境中能加載 COS SDK（腳本通過
scripts/lib.js創建客戶端）。 requires_api_key=false不等於免配置：仍須合法騰訊雲 SecretId/SecretKey 與 Bucket 信息，且不要在對話中泄露敏感值。- 刪除與公開分享屬於高風險操作；技能文檔要求對簽名 URL 時效、公開 Bucket 額外確認。
- SkillHub 頁面統計（截至查閱時）：下載 1016 次、安裝 11 次；技能爲社區發佈，使用前可在 SkillHub 查看版本與說明是否更新。
結尾¶
「騰訊雲COS技能」把 COS 上傳、同步、簽名、瀏覽、對象管理與配置排查寫成 OpenClaw 可執行的工作流，並配套 scripts/ 腳本與明確的安全邊界。若你要在 Agent 裏穩定操作騰訊雲對象存儲，可從 SkillHub 安裝 @user_9aa92135/tx-cos。
- SkillHub 頁面：https://www.skillhub.cn/skills/user_9aa92135/tx-cos
- API 座標頁：https://api.skillhub.cn/user_9aa92135/tx-cos
