前言¶

拨测任务一旦报错或指标抖动，常见做法是登录控制台翻图表、再对照抓包与多地域数据。人工串联「错误分布 → 性能趋势 → 是否链路问题 → 是否服务端问题」往往耗时，且 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 定义与清单说明，可按场景选用：

1. 错误分析：识别异常类型与错误分布规律。
2. 整体分析：呈现被拨测服务整体网络质量与可用性相关视图。
3. 性能分析：从整体分析中独立出的性能指标维度（v1.1.0 起）。
4. 抓包分析：解析报文数据做根因诊断；支持首次「进行抓包分析」与带 session-id 的抓包跟进（structured_json 指定探针时刻与错误码等）。
5. 多任务对比（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 文件。

未设置 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 不应包含时间描述或任务 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