前言¶
線上接口變慢、偶發超時，往往要同時在 APM 控制台裏翻業務系統、查 Trace、看 Span 耗時，再切到火焰圖定位熱點。對話式 Agent 能寫代碼、能跑命令，卻通常碰不到你已接入的騰訊雲 APM 數據。下面介紹 SkillHub 上的 Tencent Cloud APM（@tencent-adm/apm-performance-analysis）：讓 Agent 通過騰訊雲官方 SDK 的 ApmClient.SendMCPMessage 連接遠程 APM MCP Server，在對話裏完成工具發現、參數確認與性能診斷相關調用。
這是什麼¶
Tencent Cloud APM 是面向 APM 性能分析的 Agent Skill，由 騰訊雲 APM 團隊 發佈，來源爲 enterprise，當前版本 v1.0.3，SkillHub 分類爲 it-ops-security，標籤含 requires_api_key=true（需配置騰訊雲 API 密鑰）。
Skill 不替代 APM 控制台，而是把「連通 MCP → 列出工具 → 按規範調用 → 解讀結果」固化進 SKILL.md 與配套腳本：Agent 在技能目錄下執行 scripts/apm_mcp_client.py，經雲 API 標準簽名（TC3-HMAC-SHA256）訪問 MCP Server，從而支持業務系統查詢、調用鏈追蹤、火焰圖、Span 耗時分析等能力（以 MCP 實際暴露的工具爲準）。
觸發場景在 Skill 描述中寫明：當用戶提到 APM、性能分析、調用鏈、火焰圖、Span 或耗時分析時可啓用。
核心功能¶
以下能力均來自官方 Skill 說明與客戶端腳本，具體工具名以 list-tools 返回爲準。
- 遠程 MCP 接入：通過
ApmClient.SendMCPMessage與 APM MCP Server 交互，支持連通檢測（ping）、工具列表（tools/list）、工具調用（tools/call）。 - 業務與鏈路分析：Skill 簡介明確包含業務系統查詢、調用鏈追蹤、火焰圖、Span 耗時分析等運維向能力。
- 內嵌官方 SDK：技能包內 vendored 騰訊雲 Python SDK（文檔記載爲 v3.1.93），無需單獨
pip install或維護虛擬環境即可運行客戶端腳本。 - 憑證與安全約束：SecretId/SecretKey 僅通過 shell 環境變量（或命令行參數）讀取，禁止硬編碼與
.env；對話中需用佔位符，錯誤寫入./logs/apm_error.log（權限 600，不記錄密鑰）。 - 交互規範：調用前須確認功能與參數；支持從對話上下文複用 InstanceId、Region 等，詳見技能內
references/interaction_guide.md。
Skill 聲明的 allowed-tools 爲 Bash、Read，適合在 Cursor 等支持 Skills 的 Agent 中通過終端調用腳本。
安裝與啓用¶
通過 SkillHub 安裝¶
SkillHub 頁面給出的安裝提示爲：參照 SkillHub 安裝說明 安裝座標 @tencent-adm/apm-performance-analysis。
若本機已有 skillhub CLI，安裝時需用 --dir 指向當前 Agent 的 skills 目錄（裝到默認 ./skills/ 可能不會被 Agent 識別）。示例：
command -v skillhub && skillhub --version
skillhub install @tencent-adm/apm-performance-analysis --dir ~/.cursor/skills/
常用路徑（摘自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
未安裝 CLI 時，可按 SkillHub 文檔使用官方安裝腳本（需聯網環境）。
配置騰訊雲憑證¶
調用前檢查環境變量是否就緒：
echo $TENCENTCLOUD_SECRET_ID
必填項：
| 變量名 | 說明 |
|---|---|
TENCENTCLOUD_SECRET_ID |
騰訊雲 API SecretId |
TENCENTCLOUD_SECRET_KEY |
騰訊雲 API SecretKey |
可選項包括 APM_API_ENDPOINT（默認公網 apm.tencentcloudapi.com）、APM_ERROR_LOG_DIR（默認 ./logs/）。密鑰請在 騰訊雲 API 密鑰管理 創建，建議最小權限子賬號；勿在聊天中發送明文密鑰。
Agent 側 MCP 說明¶
本 Skill 通過 雲 API + SendMCPMessage 訪問 APM MCP Server，並非在 IDE 裏單獨配置本地 MCP Server 條目。Agent 讀取技能後，應在技能目錄下執行 python scripts/apm_mcp_client.py 完成 ping、列工具與 call-tool。
典型用法¶
安裝並配置憑證後，建議按 Skill 內「執行流程」順序操作。以下命令均在技能包根目錄（含 scripts/ 的路徑）下執行。
1. 驗證連通性
python scripts/apm_mcp_client.py ping
2. 發現 MCP 工具
python scripts/apm_mcp_client.py list-tools --output json
將 JSON 中的 name、description、inputSchema 按 interaction_guide.md 的表格模板展示給用戶，並確認要調用的工具與參數。
3. 調用指定工具
--args 傳入 JSON 對象，客戶端會轉換爲 APM 所需的 KV 結構。官方腳本註釋中的示例：
python scripts/apm_mcp_client.py call-tool \
--name DescribeApmOverview \
--args '{"start_time":"1744786829","end_time":"1744787429","region":"ap-beijing"}'
通用形式：
python scripts/apm_mcp_client.py call-tool --name <tool_name> --args '{"param1": "value1"}'
4. 對話中的自然語言入口
用戶可直接問「APM 能做什麼」「查看 MCP 支持哪些操作」或描述性能問題；Agent 應先說明需 SecretId/SecretKey、再走 ping → list-tools → 參數確認 → call-tool。Skill 要求：未確認功能和參數前不得直接調用工具。
適用場景與注意¶
適合誰
- 已在騰訊雲使用 APM，希望在 Cursor / Claude Code / Codex 等 Agent 裏用自然語言查鏈路、Span、火焰圖等數據的運維與後端同學。
- 希望把「列工具、填 Region/InstanceId/時間範圍」交給 Agent，但仍保留人工確認參數的團隊。
限制與注意
- 必須具備有效騰訊雲 API 密鑰；SkillHub 標記
requires_api_key=true。若出現服務角色授權失敗等錯誤，需按技能內references/error_log_guide.md在控制台完成授權。 - 工具集合由遠端 MCP Server 決定，文章無法枚舉全部接口名；以
list-tools實時結果爲準。 - 移動端遠程使用時，Skill 強制禁止創建臨時文件、禁止
rm、須在對話內用 Markdown 展示數據（見mobile_compat_guide.md）。 - SkillHub 頁面統計（截至資料抓取）：評分 100000，下載 1615，安裝 13；安裝後若 Agent 未加載新技能，需按所用客戶端說明刷新或重啓。
結尾¶
Tencent Cloud APM 把騰訊雲 APM 的 MCP 能力封裝成可安裝的 Agent Skill：內嵌 SDK、標準簽名鑑權、腳本化的 ping / list-tools / call-tool，再配合交互與安全規範，讓性能分析從「切控制台」變成「在對話裏按步驟查」。需要安裝或查看更新時，可訪問 SkillHub 官方頁：Tencent Cloud APM；API 入口：https://api.skillhub.cn/tencent-adm/apm-performance-analysis。
