前言¶
在 Oceanus 上改 SQL 作業、查運行日誌、上傳依賴 JAR，常見路徑是控制台點選或自己拼 OpenAPI。把同樣的事交給通用 Agent，容易出現三類問題：命令和參數靠猜、密鑰寫進對話或腳本、創建/停止等寫操作缺少確認。下面介紹 SkillHub 上的 tencentcloud-oceanus-ops，它把 Oceanus 工作空間運維收斂到一套 Python CLI，並在 Skill 協議里約定觸發範圍、操作分級和草稿發佈門控。
這是什麼¶
tencentcloud-oceanus-ops 是面向騰訊雲流計算 Oceanus 的智能運維技能包（通用 SKILL.md 格式）。公開元數據顯示維護方爲 oceanus-team，許可證爲 Apache-2.0。
定位可以概括爲：用戶用自然語言描述意圖，Agent 按 Skill 指引執行 scripts/oceanus_ops.py 下的命令，底層通過 TC3-HMAC-SHA256 調用 Oceanus OpenAPI；憑證只從環境變量讀取，不寫入命令參數。該能力在騰訊雲產品文檔中有專門章節說明（見文末來源）。
核心功能¶
以下能力均來自官方 Skill 說明與騰訊雲文檔，按模塊歸納。
作業開發與發佈¶
- 創建、配置 SQL / JAR 作業；編輯草稿、SQL 語法檢查、發佈作業配置版本。
作業運行時¶
- 啓動、停止作業；觸發 Savepoint；查看作業詳情。
工作空間與資源¶
- 文件夾：創建、移動、重命名、刪除，整理作業樹。
- 依賴資源：上傳與版本化 JAR、配置文件，查詢依賴樹。
- 元數據：瀏覽 catalog、數據庫、表；查詢地域、工作空間、集羣、工作空間變量。
可觀測性¶
- 查詢作業事件、運行日誌（CLS / ES）、COS 日誌文件及下載鏈接。
明確不在範圍內¶
Skill 邊界說明中列出的不處理項包括：集羣生命週期（創建/擴縮/刪除）、容器或 Pod 排障、EMR/DLC 等其他引擎、以及 CVM/VPC/賬單等通用雲資源。未帶 Oceanus 語境的泛雲任務也不應觸發本 Skill。
安裝與啓用¶
環境要求¶
- Python 3.8+，僅使用標準庫（Skill 資產中
requirements.txt當前無第三方依賴）。 - 騰訊雲 CAM 密鑰通過環境變量注入（勿在對話中粘貼密鑰）。
export TENCENTCLOUD_SECRET_ID="Your SecretId"
export TENCENTCLOUD_SECRET_KEY="Your SecretKey"
# 僅臨時憑證需要
export TENCENTCLOUD_SECURITY_TOKEN="Temp Token"
macOS / zsh 持久化示例見騰訊雲文檔：可向 ~/.zshenv 追加上述變量後 source ~/.zshenv。
從 SkillHub 安裝¶
社區頁面：https://skillhub.cn/skills/tencentcloud-oceanus-ops。SkillHub API 入口（用戶提供的官方地址）：https://api.skillhub.cn/u_f4712daa/tencentcloud-oceanus-ops。
secure-skills-cli（SkillHub / 360 技能中心均給出同一話術）：
npx secure-skills-cli add tencentcloud-oceanus-ops
WorkBuddy：打開「專家·技能·連接器 > 技能 > SkillHub」，搜索 tencentcloud-oceanus-ops，點擊安裝。
CodeBuddy：在 SkillHub 搜索並下載 Skill 壓縮包解壓後，在「設置 > 技能 > 導入 Skill」中導入。
騰訊雲文檔寫明：任何支持 Skill 加載的 Agent 均可使用，當前推薦通過 SkillHub 安裝到 CodeBuddy 或 WorkBuddy。Cursor、Codex CLI、Claude Code 的安裝差異在已覈對資料中未單獨列出，可按各產品通用的 Skill 目錄規範放置本技能包；啓用前仍需配置上述環境變量。
典型用法¶
CLI 入口¶
Skill 要求 Agent 必須通過下列入口執行真實命令，而不是用 tccli、kubectl 或自編腳本替代：
python scripts/oceanus_ops.py <command> [args]
每條命令須帶 --region；用戶未指定時，Skill 約定默認 ap-guangzhou（也接受「廣州」等地域中文名）。常用參數包括 --workspace_id、--cluster_id、--job_type（1=SQL，2=JAR）、-o json|table|text，變更類操作需 --confirm。
示例（查詢類，具體子命令以 references/command-catalog.md 爲準）：
python scripts/oceanus_ops.py describe_workspaces --region ap-guangzhou -o json
自然語言開發作業（官方 walkthrough）¶
騰訊雲文檔給出的流程如下：
- 在對話中引用 Skill，用一句話描述需求，例如：「在廣州 Default 空間下，創建一個 MySQL 訂單表同步到 Doris 的作業，連接信息使用工作空間下的 ORDER 前綴變量替換。」
- Agent 按 Skill 內 playbooks（如
references/playbooks/create-sql-job.md）生成 SQL 草稿。 - 人工確認草稿無誤後，再讓 Agent 繼續，進入發佈流程。
生產環境不要在對話或 SQL 文件中明文暴露連接串與密碼；Sink/Source 建議在控制台用隱藏變量或 Catalog 管理。
操作分級（Agent 協議）¶
| 類型 | 示例 | 規則 |
|---|---|---|
| 讀 | describe_* |
可直接執行 |
| 寫（草稿） | modify_draft、check_sql |
可直接執行，無需 --confirm |
| 變更 | create_job、run_jobs、upload_resource 等 |
需要 --confirm 或用戶明確指令 |
| 破壞性 | stop_jobs、delete_folders |
需明確意圖 + --confirm，執行前說明影響 |
草稿發佈獨立於 --confirm：create_job_config 產出草稿摘要後，須用戶明確同意（如「確認發佈」）才能繼續；除非用戶明確說「跳過審覈」等，Agent 不得使用 --skip_draft_confirm。
適用場景與注意¶
適合誰
- 已在使用 Oceanus、希望用 Agent 完成作業 CRUD、依賴上傳、日誌與事件排查的開發和運維人員。
- 需要比「直接讓 Agent 調 OpenAPI」更可控的審批與憑證隔離的團隊（騰訊雲文檔對比說明了四級審批、草稿門控、環境變量隔離）。
使用注意
- 憑證：僅環境變量；Skill 禁止
echo/printenv等方式泄露TENCENTCLOUD_*。 - 權限：CAM 策略需覆蓋文檔所列 Oceanus 操作；生產環境建議使用 STS 臨時憑證。
- 誤操作防護：變更與破壞性操作有
--confirm與草稿確認；仍應在正確的工作空間與地域下操作。 - 觸發詞：作業、工作空間、依賴、日誌，或
space-*、cluster-*、cql-*等資源 ID 模式會觸發 Skill；純 CVM/COS/TKE 等任務不應走本 Skill。
SkillHub 社區側將該技能歸類爲 it-ops-security；具體評分與下載量以 SkillHub 頁面展示爲準（編寫時用戶提供的 API 頁面未能直接抓取正文）。
結尾¶
tencentcloud-oceanus-ops 把 Oceanus 工作空間運維固化爲可審計的 CLI + Agent 協議：邊界清晰、讀寫分級、發佈前人工看草稿。若你正在 Oceanus 上迭代 SQL/JAR 作業並打算把重複操作交給 Agent，可從 SkillHub 安裝並先配好 CAM 環境變量。
- SkillHub 技能頁：https://skillhub.cn/skills/tencentcloud-oceanus-ops
- SkillHub API（官方線索）：https://api.skillhub.cn/u_f4712daa/tencentcloud-oceanus-ops
- 騰訊雲產品文檔：使用 Oceanus Skill 管理作業
