前言¶
在 Cursor、Claude Code 等環境裏做騰訊雲運維或排障時，常見做法是反覆查文檔、拼 tccli 命令、覈對接口參數。上下文裏一旦缺了服務名、Action 或數據結構，Agent 很容易給出過時或不可執行的調用。
tsa 是 SkillHub 上由 Tencent CloudQ Team 發佈的 enterprise 類 Skill（座標 @tencent-adm/tsa，當前版本 1.1.1，分類 it-ops-security）。它把 TSA（Tencent Cloud Smart Advisor） 與 CloudQ 相關能力寫進標準 SKILL.md，並附帶 TCCLI 安裝、憑證配置與騰訊雲 API 信息庫檢索步驟，便於 Agent 在用戶詢問 CloudQ 或需要智能顧問相關操作時按同一套流程執行。
這是什麼¶
一句話：tsa 是面向 Agent 的騰訊雲智能顧問（TSA）技能包，歸屬 CloudQ 產品線（Skill 描述中稱 CloudQ 爲 ITOM「領域蝦」）。
維護方：Tencent CloudQ Team（SkillHub 頁面標註爲 enterprise 來源）。
解決的問題：統一觸發條件（例如「cloudq 是誰」「cloudq 是什麼」、騰訊雲智能顧問相關操作）、運行依賴（Python 3、騰訊雲憑證環境變量）、網絡與本地配置目錄權限，以及通過 TCCLI 與公開信息庫檢索接口文檔的最佳實踐。
SkillHub 標籤標明 requires_api_key=true：使用前需要可訪問騰訊雲 API 的憑證（環境變量或 TCCLI 登錄態）。
核心功能¶
以下能力均來自 Skill 包內 SKILL.md 與 references/ 文檔，安裝後 Agent 讀取這些文件即可遵循。
運行與環境約束¶
Skill 元數據要求：
- 本機具備
python3 - 環境變量
TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY（或通過 TCCLI 瀏覽器授權寫入本地憑證，見下文） - 網絡訪問
https://*.tencentcloudapi.com、https://cloud.tencent.com - 可讀寫本地目錄
~/.tencent-cloudq/
涉及 CAM/STS 的操作在元數據中有明確列舉（如 cam:GetRole、cam:CreateRole、sts:AssumeRole 等）。說明中強調：角色創建/刪除爲獨立步驟，需用戶明確同意後執行（create_role.py 創建角色，cleanup.py --cloud 刪除角色；check_env.py 僅只讀檢測）。臨時憑證僅在內存中使用；配置文件只保存角色 ARN，不保存密鑰。
TCCLI 安裝與憑證（references）¶
Skill 將 TCCLI 作爲調用騰訊雲 API 的推薦 CLI。安裝與驗證示例：
pip install tccli
tccli --version
憑證方面推薦瀏覽器授權，避免手填 SecretId/SecretKey：
tccli auth login
命令會阻塞直到用戶在瀏覽器完成 OAuth 授權；成功後可用 tccli cvm DescribeRegions 驗證。多賬戶可使用 tccli auth login --profile user1；登出使用 tccli auth logout（或帶 --profile）。
信息庫檢索（references/refs.md）¶
當需要確定服務名、最佳實踐、具體 Action 或數據結構時，Skill 給出基於 curl 與 grep 的檢索流程，數據源爲騰訊雲公開 refs：
發現業務（示例：查「雲服務器」對應服務名）：
curl -s https://cloudcache.tencentcs.com/capi/refs/services.md | grep 雲服務器
檢索某業務最佳實踐：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/practices.md | grep 重裝
檢索接口列表：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/actions.md | grep "擴容\|磁盤"
閱讀單個接口或數據結構文檔：
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/action/ResizeInstanceDisks.md
curl -s https://cloudcache.tencentcs.com/capi/refs/service/cvm/model/SystemDisk.md
配置與清理（SKILL.md）¶
Skill 文檔提供本地/雲端清理腳本用法（路徑中的 {baseDir} 爲 Skill 安裝目錄）：
python3 {baseDir}/scripts/cleanup.py
python3 {baseDir}/scripts/cleanup.py --all
python3 {baseDir}/scripts/cleanup.py --all --cloud
清理範圍包括：
~/.tencent-cloudq/（含config.json）- 系統臨時目錄下的
.tcloud_advisor_uin_cache - 已設置的
TENCENTCLOUD_*環境變量（腳本可生成對應 shell/PowerShell 清理命令） - 加
--cloud時刪除雲端 CAM 角色advisor（需已配置 AK/SK）
安裝與啓用¶
1、安裝 SkillHub CLI（若尚未安裝）¶
command -v skillhub && skillhub --version
未安裝時可按 SkillHub 官方說明執行完整安裝腳本（見 SkillHub 安裝文檔）。
2、安裝 @tencent-adm/tsa¶
官方頁面給出的方式是讓 Agent 依照 SkillHub 安裝文檔，安裝座標 @tencent-adm/tsa。命令形態如下（必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認裝到 ./skills/ 可能不會被識別）：
skillhub install @tencent-adm/tsa --dir <skills 目錄>
常見路徑（來自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
安裝完成後按你所用客戶端要求刷新或重啓，使 Skill 被加載。
3、準備 TCCLI 與憑證¶
按 Skill 內 references/install.md、references/auth.md 安裝 TCCLI 並完成 tccli auth login，或按 Skill 元數據配置 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY。
典型用法¶
場景 A：用戶問 CloudQ 或 TSA 是什麼
Agent 應加載 tsa Skill，依據 SKILL.md 前言中的描述回答，並在涉及實際操作時走 TCCLI 或信息庫檢索流程，而不是憑空編造產品能力。
場景 B：要爲某臺 CVM 擴容磁盤查接口
- 用
services.md確認服務名爲cvm（見上文 curl 示例）。 - 在
actions.md中 grep 目標操作，打開對應action/*.md閱讀參數。 - 需要時查看
model/*.md中的數據結構。 - 使用已配置的 TCCLI 或 SDK 發起調用（示例驗證命令：
tccli cvm DescribeRegions）。
場景 C：結束使用後清理本地與可選雲端角色
在用戶確認後執行 cleanup.py 相應參數，避免殘留 ~/.tencent-cloudq/ 或環境變量中的密鑰信息。
適用場景與注意¶
適合誰
- 已在用 Cursor、Claude Code、Codex 等支持 Skills 的客戶端，且工作流裏經常涉及騰訊雲運維、顧問類能力或 CloudQ 相關問答的團隊。
- 願意通過 TCCLI 或 AK/SK 授權 Agent 訪問
tencentcloudapi.com的環境。
限制與注意
- 標籤
requires_api_key=true：無有效騰訊雲憑證時，Skill 無法完成真實 API 調用。 - IAM 相關寫操作（創建/刪除
advisor角色）需用戶明確同意後再執行，不要默認一鍵開通。 tccli auth login在 Agent 自動執行時會長時間阻塞，需提示用戶打開終端中的授權鏈接完成瀏覽器登錄。- SkillHub 頁面統計（截至資料抓取）：評分 100000，下載 1170，安裝 31；與個別第三方摘要中的數字可能不一致，以 SkillHub 爲準。
結尾¶
tsa 把騰訊雲智能顧問（TSA）/ CloudQ 的觸發語義、憑證與權限邊界、TCCLI 路徑以及公開 API 信息庫檢索步驟收斂到一個 Skill 裏，適合作爲 IT 運維與安全類 Agent 的固定能力模塊。安裝與詳情見 SkillHub：
- 頁面：https://www.skillhub.cn/skills/tencent-adm/tsa
- API 座標頁：https://api.skillhub.cn/tencent-adm/tsa
