前言¶
撥測任務一旦報錯或指標抖動，常見做法是登錄控制台翻圖表、再對照抓包與多地域數據。人工串聯「錯誤分佈 → 性能趨勢 → 是否鏈路問題 → 是否服務端問題」往往耗時，且 Agent 側缺少統一、可腳本化的出口。下面介紹騰訊云云撥測團隊發佈的 cat-network-quality-analysis（Skill 展示名 Tencent Cloud CAT），它通過 ProcessAIEventsStream API 拉取分析流，把錯誤分析、整體分析、性能分析、抓包分析與多任務對比收斂爲一條 CLI / Skill 調用鏈，結果以 Markdown 歸檔，stdout 返回一行 JSON 供編排層解析。
這是什麼¶
cat-network-quality-analysis 是面向騰訊云云撥測（CAT，Cloud Automated Testing）任務的網絡質量分析 Agent Skill，版本 1.3.0，作者與維護方爲雲撥測團隊。Skill 座標爲 @tencent-adm/cat-network-quality-analysis-v1-0-1，在 SkillHub 分類爲 it-ops-security，需配置 API 密鑰（requires_api_key=true）。
它解決的核心問題：在指定任務 ID 與時間窗口內，用自然語言或結構化 query-text 觸發 CAT AI Console 側分析，自動生成分場景報告，並支持抓包跟進與多任務橫向對比。
騰訊雲內部用戶需使用內網 API 端點 cat.ai.internal.tencentcloudapi.com；公網默認端點爲 cat.ai.tencentcloudapi.com。
核心功能¶
以下能力均來自 Skill 定義與清單說明，可按場景選用：
- 錯誤分析：識別異常類型與錯誤分佈規律。
- 整體分析：呈現被撥測服務整體網絡質量與可用性相關視圖。
- 性能分析：從整體分析中獨立出的性能指標維度（v1.1.0 起）。
- 抓包分析：解析報文數據做根因診斷；支持首次「進行抓包分析」與帶
session-id的抓包跟進（structured_json指定探針時刻與錯誤碼等）。 - 多任務對比（v1.3.0）：
AnalyzeAction=MultiTaskCompare，對比 1 個主任務與最多 5 個對比任務的關鍵指標；主任務與對比任務撥測類型必須一致。
腳本使用 Python 3.10+，以標準庫實現 TC3-HMAC-SHA256 簽名，無第三方依賴（v1.2.0 起已移除 tencentcloud-sdk-python）。執行過程靜默，流式寫入 Markdown 文件，結束時 stdout 僅輸出一行 JSON（含 report、md_path、session_id、pcap_candidates、incomplete 等字段）。
安裝與啓用¶
環境與依賴¶
無需 pip install 第三方包；確保本機有 Python 3.10 及以上，在 Skill 包內直接運行 scripts/cat_network_quality_analysis.py 即可。
憑證與端點（兩級配置）¶
加載優先級：環境變量 > scripts/.env 文件。
| 配置項 | 環境變量 | 必填 | 默認值 | 說明 |
|---|---|---|---|---|
| SecretId | CAT_SECRET_ID |
是 | — | 騰訊雲 API 訪問密鑰 ID |
| SecretKey | CAT_SECRET_KEY |
是 | — | 騰訊雲 API 訪問密鑰 KEY |
| Token | CAT_TOKEN |
否 | — | 臨時憑證（可選） |
| Endpoint | CAT_ENDPOINT |
否 | cat.ai.tencentcloudapi.com |
內網用戶改爲 cat.ai.internal.tencentcloudapi.com |
未設置 CAT_* 時，腳本會降級讀取 TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY、TENCENTCLOUD_TOKEN、TENCENTCLOUD_ENDPOINT；建議優先使用 CAT_*。
尚未開通密鑰時，可通過控制台申請 CAT API 訪問權限：
https://console.cloud.tencent.com/cloudapp/run/yunti/apply-auth
在 scripts/ 下配置 .env 示例：
# scripts/.env
CAT_SECRET_ID=your-secret-id
CAT_SECRET_KEY=your-secret-key
CAT_TOKEN=your-token
CAT_ENDPOINT=cat.ai.internal.tencentcloudapi.com
.env 已列入 .gitignore，勿將密鑰寫入代碼倉庫。
等價的環境變量方式：
export CAT_SECRET_ID='your-secret-id'
export CAT_SECRET_KEY='your-secret-key'
export CAT_ENDPOINT='cat.ai.internal.tencentcloudapi.com'
tcproxycli 代理模式（可選）¶
若已安裝 tcproxycli 並設置 TCPROXYCLI_PROXY_ENDPOINT 與 TCPROXYCLI_SESSION_KEY，腳本可走代理模式，無需本地 SecretId/SecretKey。未設置時默認走 TC3 簽名模式。
export TCPROXYCLI_PROXY_ENDPOINT="https://your-proxy-endpoint"
export TCPROXYCLI_SESSION_KEY="your-session-key"
在 IDE 中使用 Skill¶
官方示例提到在 CodeBuddy IDE 中用自然語言描述需求，例如「分析最近 3 小時 task-xxxxxxxx 的撥測錯誤情況」，由 Agent 加載 SKILL.md 並調用腳本。Cursor 等其它支持通用 SKILL.md 的運行時，可按同樣參數約束封裝調用；具體安裝入口以 SkillHub 爲準。
SkillHub 頁面：
https://www.skillhub.cn/skills/tencent-adm/cat-network-quality-analysis-v1-0-1
API 元數據地址：
https://api.skillhub.cn/tencent-adm/cat-network-quality-analysis-v1-0-1
典型用法¶
CLI 公共參數¶
| 參數 | 必填 | 說明 |
|---|---|---|
--query-text |
是 | 發給 CAT AI Console 的查詢；常規模板見 references/query_text_templates.md；多任務對比爲 <structured_json> |
--task-id |
除多任務對比外必填 | 形如 task-xxxxxxxx |
--start-time / --end-time |
是 | 毫秒級 13 位時間戳 |
--analyze-action |
否 | Console / PcapAnalysis / MultiTaskCompare，缺省按 query-text 推斷 |
--session-id |
抓包跟進時 | 首輪分析返回的會話 ID |
--output / -o |
否 | Markdown 路徑；默認按 task 與 report 類型生成 |
--suppress-pcap-candidates |
否 | 抓包場景建議顯式帶上，抑制候選列表追加 |
query-text 不應包含時間描述或任務 ID（由 CLI 三件套傳遞）。
示例 1：錯誤分析¶
python3 scripts/cat_network_quality_analysis.py \
--query-text "進行錯誤分析" \
--task-id "task-xxxxxxxx" \
--start-time 1773734439444 \
--end-time 1773745239444 \
--output task-xxxxxxxx/task-xxxxxxxx_error_report_20260319_143025.md
示例 2：整體分析與性能分析¶
整體分析將 query-text 改爲「進行整體分析」；性能分析改爲「進行性能分析」，其餘三件套相同。
python3 scripts/cat_network_quality_analysis.py \
--query-text "進行性能分析" \
--task-id "task-xxxxxxxx" \
--start-time 1773658839444 \
--end-time 1773745239444 \
--output task-xxxxxxxx/performance_report.md
示例 3：抓包分析¶
首次直達抓包：
python3 scripts/cat_network_quality_analysis.py \
--query-text "進行抓包分析" \
--task-id "task-xxxxxxxx" \
--start-time 1773658839444 \
--end-time 1773745239444 \
--suppress-pcap-candidates \
--output task-xxxxxxxx/pcap_report.md
抓包跟進需傳入首輪 JSON 中的 session_id，且 query-text 爲結構化 JSON：
python3 scripts/cat_network_quality_analysis.py \
--query-text '<structured_json>{"task_id":"task-xxxxxxxx","probe_time":1773905195000,"code":"12929"}</structured_json>' \
--task-id "task-xxxxxxxx" \
--start-time 1773905195000 \
--end-time 1773905195000 \
--session-id "17f57xxxxxxxxxxxxxxxx5b224055354" \
--suppress-pcap-candidates \
--output task-xxxxxxxx/task-xxxxxxxx_pcap_report_20260319_120000.md
示例 4：多任務對比¶
不傳 --task-id；query-text 指明主任務與對比列表：
python3 scripts/cat_network_quality_analysis.py \
--query-text '<structured_json>{"main_task_id":"task-aaaabbbb","compare_task_ids":["task-aaaa1111","task-bbbb2222"]}</structured_json>' \
--start-time 1773658839444 \
--end-time 1773745239444 \
--output task-aaaabbbb/task-aaaabbbb_multitask_compare_report_20260319_143025.md
用戶未指定時間範圍時，多任務對比默認分析最近 3 小時（end 爲當前毫秒時間戳，start = end - 10800000）。
輸出約定¶
成功時 stdout 示例結構：
{"code": 0, "report": "# 報告正文...", "md_path": "/abs/path/report.md", "session_id": "xxx", "json_file": "...", "pcap_candidates": [], "incomplete": false}
失敗時 code 爲 1 並帶 error 字段。若 incomplete 爲 true，表示 SSE 未正常收到 agent.done，應縮小時間窗後重試。
適用場景與注意¶
適合誰：已使用騰訊云云撥測、需要在運維排障或 Agent 工作流中自動出報告的團隊；SkillHub 標籤指向 IT 運維與安全觀測類場景。
使用注意：
- 除多任務對比外，必須先有明確的
task-id；缺失時應向用戶確認，勿臆造。 - 多任務對比上限爲 1 主任務 + 5 對比任務，且任務類型必須一致。
- 內網與公網端點不可混用錯誤，否則無法訪問服務。
- 抓包分支的完整約束見包內
references/branch_pcap.md、references/error_handling.md。 - SkillHub 簡介提到控制台可生成 PDF 分析報告；本 Skill 腳本側明確導出爲 Markdown 並流式寫文件，PDF 能力以騰訊雲 CAT 產品文檔爲準：https://cloud.tencent.com/document/product/280
結尾¶
Tencent Cloud CAT（cat-network-quality-analysis）把雲撥測的五類分析場景和 ProcessAIEventsStream 流式結果封裝成可腳本化、可接入 Agent 的 Skill：配置 CAT_* 或 tcproxycli 後，用三件套時間窗與 query-text 即可落盤 Markdown 並拿到 JSON 摘要。獲取 Skill 與版本信息見：
https://www.skillhub.cn/skills/tencent-adm/cat-network-quality-analysis-v1-0-1
