前言¶

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

Tencent Cloud CAT：云拨测网络质量分析 Skill

前言¶

这是什么¶

核心功能¶

安装与启用¶

环境与依赖¶

凭证与端点（两级配置）¶

tcproxycli 代理模式（可选）¶

在 IDE 中使用 Skill¶

典型用法¶

CLI 公共参数¶

示例 1：错误分析¶

示例 2：整体分析与性能分析¶

示例 3：抓包分析¶

示例 4：多任务对比¶

输出约定¶

适用场景与注意¶

结尾¶

精选优惠券

Tencent Cloud CAT：云拨测网络质量分析 Skill

前言¶

这是什么¶

核心功能¶

安装与启用¶

环境与依赖¶

凭证与端点（两级配置）¶

tcproxycli 代理模式（可选）¶

在 IDE 中使用 Skill¶

典型用法¶

CLI 公共参数¶

示例 1：错误分析¶

示例 2：整体分析与性能分析¶

示例 3：抓包分析¶

示例 4：多任务对比¶

输出约定¶

适用场景与注意¶

结尾¶

精选优惠券

相关文章