shield_lock
JinDaGe
← Back to skills
extension
Category: OtherAPI key required

腾讯云可观测平台（tcop-api）

腾讯云可观测平台tcop-api 是腾讯云可观测平台首个全场景集成的Skill，覆盖 APM、RUM、CAT、PTS、TMP、Grafana、云产品监控、告警、Dashboard、EventBridge在内的11个子产品模块、其中基础监控相关数据查询覆盖100+ 云产品。 示例：你只需用自然语言说一句"查广州 CVM ins-xxx 最近 1 小时的 CPU"，AI 自动完成：产品路由 → 指标匹配 → 维度组装 → API 调用 → 结果摘要，全程无需翻文档、无需手拼参数。

personAuthor: u_ed500073hubenterprise
downloadDownload package

腾讯云可观测平台 — 原始 API 调用 Skill

本 skill 的核心职责是路由 + 调用：识别用户意图所属模块、加载对应模块指引、组装并执行腾讯云 API。

调用通道按"API 是否在 tccli CLI 白名单内"分两类：

| 通道 | 何时用 | 谁在用 | |------|-------|-------| | tccli CLI | 公开 SDK 已收录的标准 Action（GetMonitorData / DescribeAlarmPolicies / ...） | monitor_query.execute_query、用户直接 tccli xxx yyy 全部场景 | | Python SDK CommonClient | 控制台内部 API（如 mongodb:DescribeDBInstanceSummaries），不在 CLI 白名单 | instance_resolver.py 全部子命令，绕过 CLI 校验直通后端网关 |

参考：tccli 文档、tencentcloud-sdk-python。

决策路径总览

flowchart TD
    classDef step fill:#1f4e79,stroke:#7fb4e8,color:#fff
    classDef branch fill:#7a3f0a,stroke:#e8b87a,color:#fff
    classDef ref fill:#1a5c3e,stroke:#7fd0a0,color:#fff

    U[用户提问]:::step --> E[环境检查<br/>tccli 可用 + 已登录]:::step
    E --> R[Step 1<br/>路由识别]:::step
    R -->|给了 Action 名| D1[直接定位模块]:::branch
    R -->|有强关键词| D2[关键词匹配模块]:::branch
    R -->|含糊不清| D3[向用户确认模块]:::branch
    D1 --> L[Step 2<br/>加载模块 reference<br/>+ 用 tccli help 补全]:::step
    D2 --> L
    D3 --> L
    L --> P[Step 3<br/>组装调用 + 关键参数确认]:::step
    P --> X[执行 tccli + 摘要返回]:::step

    L -.读取.-> RF[references/&lt;module&gt;.md]:::ref
    L -.读取.-> TU[references/tccli-usage.md]:::ref
    R -.读取.-> RD[references/routing-decision.md]:::ref

环境检查（每次首次调用前静默执行，仅失败时告知用户）

Step 1 — 检查 tccli

which tccli && tccli --version

不存在则告知用户缺失依赖,推荐执行 pip install tccli(如需要管理员权限,由用户自行加 sudo);LLM 不自动执行 sudo。授权后再代为安装。安装失败则告知用户手动执行,不再继续。

Step 2 — 检查 Python SDK（monitor-query / instance-resolver 模块需要；纯告警查询可跳过此步）

python3 -c "from tencentcloud.common.common_client import CommonClient" 2>&1

不存在则告知用户缺失依赖,推荐执行 pip3 install tencentcloud-sdk-python,授权后再代为安装。instance_resolver.py 的 SDK 路径依赖此包。alarm_lookup.py 仅用标准库,不需要此 SDK。

Step 3 — 检查凭证

凭证有两套来源，按优先级判断：

# 1) 优先：OAuth 凭证文件（tccli auth login 产物，SDK CommonClient 也复用这个）
test -s ~/.tccli/default.credential && echo "OAuth OK"

# 2) 次选：旧式 SecretId/Key profile
tccli configure list 2>/dev/null

只要 ① 文件存在且非空，就视为已登录——无需关心 tccli configure list 是否有 profile（OAuth 凭证不在 configure 列表里）。两个都没有时才提示登录：

| 环境 | 判断依据 | 命令 | |------|---------|------| | 有头（macOS / 有 $DISPLAY 或 $WAYLAND_DISPLAY） | macOS 默认；Linux 看环境变量 | tccli auth login | | 无头（服务器 / 容器） | 上述变量都没有；或 tccli auth login 报"无法打开浏览器" | tccli auth login --browser no |

SDK 与 tccli 共享 ~/.tccli/default.credential，只需登录一次。tccli auth login 需要 tccli ≥ 3.0.x；老版本退化为 tccli configure 配 SecretId/Key 或环境变量 TENCENTCLOUD_SECRET_ID/KEY。

Step 4 — 就绪

通过则静默继续，不向用户输出"环境就绪"等噪声信息。失败时才告知具体故障。

🔒 安全红线：禁止询问、接收、回显 SecretId / SecretKey 明文。tccli auth login 是 OAuth 流，本 skill 可主动执行。如果用户提供了密钥明文，要明确拒绝并引导走 OAuth。

路由表（精简版，详细版见 routing-decision.md）

同名异义警告：告警 API、Prometheus 实例管理、云产品监控查询都共用 tccli monitor 服务名。区分靠"业务模块"，不是"tccli 服务名"。

| 用户意图关键信号 | 对应模块 | tccli 服务 | 加载 reference | 状态 | |-----------------|---------|-----------|---------------|------| | 拉云产品指标数据（CVM/CDB/CLB/COS… 的 CPU/内存/QPS/带宽） | 基础监控-查询 | monitor | monitor-query/overview.md | ✅ | | 告警策略/告警历史(触发记录)/告警通知模板/可配置指标&事件元数据（任何子业务的告警都走这里） | 基础监控-告警 | monitor | monitor-alarm.md | ✅(只读;Create* / Modify* / Delete* / Pause* 等写操作引导控制台,见 monitor-alarm § 2 速查表备注 + § 7 常见踩坑)| | APM、调用链、Trace、火焰图、应用性能、Span、业务系统(apm-) | APM | apm | apm.md | ✅ | | 移动端崩溃、ANR、Android/iOS/鸿蒙/Flutter 客户端性能 | 终端性能监控 Pro | rum | rum-app-pro.md | ✅ | | Web 性能、小程序性能、JS 错误、Ajax 错误、首屏测速 | 前端性能监控 | rum | rum.md | ✅ | | 拨测、可用性探测、网络质量、CDN 质量、域名 whois | 云拨测 | cat | cat.md | ✅ | | 压测、并发测试、JMeter、性能测试场景 | 云压测 | pts | pts.md | ✅ | | Prometheus 实例、PromQL、Exporter、ServiceMonitor、TMP | Prometheus 监控 | monitor（Prometheus 子集） | tmp.md | ✅ | | Grafana、托管 Grafana、可视化大盘 | Grafana 服务 | grafana | grafana.md | ✅ | | Dashboard、智能仪表盘、监控面板（云产品监控 Dashboard） | Dashboard | monitor 子集（走公共 API,脚本由外部 skill tcop-monitor-dashboard 提供,tccli choice 未暴露） | dashboard.md | ✅ | | 事件总线、EventBus、事件转投 | 事件总线 | eb | eb.md | ✅ |

* monitor 服务名同时承载查询/告警/Prometheus/Dashboard 4 个子集，按 Action 名识别，不看服务名。 * Dashboard 模块的查询 API（DescribeUnifyDashboards / DescribeUnifyDashboard / DescribeDashboardMetricData）未在 tccli choice 中公开,需走腾讯云公共 API 网关 + 外部 skill tcop-monitor-dashboard 提供的 query_dashboard.py 脚本封装(本 skill 不内置该脚本);详见 dashboard.md。

路由原则

  1. API Action 优先：用户给了 GetMonitorData / DescribeAlarmPolicies 这类具体 Action，直接锁定模块，不再走关键词匹配
  2. 关键词次优：用上表关键词识别。无歧义直接路由，有歧义按"细分业务优先"——比如"我想看 APM 业务系统的告警"是告警模块，不是 APM 模块（因为告警 API 全在 monitor 下）
  3. 含糊兜底：用户只说"我要查腾讯云监控数据"，先用 AskUserQuestion 让用户在 2-4 个候选模块中选

通用调用规约

1. 加载顺序

确认模块后，按需读取（节省上下文）：

  1. 必读：references/<module>.md（业务概念 + 推荐 Action + 常见坑）
  2. 必读：references/tccli-usage.md（如果还没读过）
  3. 用 tccli 自身能力补全 API 出入参： 
    tccli <service> <action> help --detail
    --detail 会展开嵌套类型 + 中文说明，不需要也不应该预先把 API 文档全塞到 reference 里。

2. 参数组装

| 参数复杂度 | 推荐方式 | |-----------|---------| | 简单（标量参数 ≤ 5 个） | 命令行 --Foo value --Bar value | | 含数组 / 嵌套对象 | 强烈推荐 --cli-input-json file:///tmp/req.json 走临时文件，避免 shell 转义 | | 不熟悉的复杂结构 | 先 tccli <svc> <action> --generate-cli-skeleton > /tmp/req.json 拿模板，再编辑填值 |

3. 关键参数确认时机

下列参数按场景区分确认策略：

| 参数类型 | 策略 | |---------|------| | --region | 分场景:① 列表类查询(如 DescribeAlarmPolicies / DescribeApmInstances)默认 ap-guangzhou,在输出里显式声明"已默认查广州,如需其他地域请告知"——避免每次反问拖慢简单任务;② 实例特定查询(如 GetMonitorData ins-xxx / DescribeAlarmHistories --AlarmObject ins-xxx)必须反问 region,因为错 region 直接返回空数据,用户根本不知道是 region 错还是数据真没有;③ 用户已用中文/缩写指代地域(广州/sh) → 按 common/region_dict.md 映射,不再反问 | | Namespace（云产品监控） | QCE/CVM vs QCE/CDB 决定查的是什么资源类型。错命名空间 → 全空。坑：DescribeProductList 返回的是小写形式（qce/cvm），但 GetMonitorData 入参必须大写（QCE/CVM）；monitor_query.build_request 已经做了 auto-uppercase 兜底，但手工调 tccli 时仍要注意 | | Instances / 实例 ID | 写错查不到，且容易混 InstanceId / Uin / AppId | | 时间窗口 (StartTime/EndTime) | 模糊"最近一段时间"必须明确：默认按"最近 1 小时"或"最近 1 天"，并在输出里写明 | | 凭证 profile (--profile) | 多账号场景必须确认，默认走当前活跃 profile |

如果上下文工具中有 current_time / time_to_unix 这类时间工具，优先用工具计算时间参数，不要靠 LLM 自己推算。

4. 输出格式

| 场景 | 选项 | |------|------| | 默认结构化解析 | --output json（默认） | | 表格化展示给用户 | --output table | | 取部分字段 | --filter <JMESPath>，如 --filter "Histories[*].Content" |

5. 只读定位 — 写操作引导控制台

本 skill 仅支持 Describe* / Get* 等只读 API。识别到 Create* / Modify* / Delete* / Put* / Pause* / Update* / Run* / Sync* / Terminate* / Bind* / Unbind* / Resume* / Enable* / Disable* / Install* / Uninstall* / Upgrade* / Clean* / Destroy* / Abort* / StartJob / PutEvents 等写动作时:

  1. 不构造写 API 命令(即使用户明确要求"帮我创建/修改/删除")
  2. 不调用 tccli xxx Create* / tccli xxx Modify* 之类的 help 探索写接口出入参
  3. 直接告知用户:"本 skill 仅支持只读 API,写操作请前往腾讯云控制台:<对应控制台 URL>"
  4. 必要时可指出对应控制台路径(如告警策略 → https://console.cloud.tencent.com/monitor/alarm2/policy)

理由:写操作风险高(配置错误可能影响告警通知 / 启动压测击穿目标 / 删除资源等),需要 UI 上下文 + 多重校验,远超 CLI 命令展示+用户确认的能力。如果未来要支持写操作,需单独立项设计参数确认与回滚流程。

6. 错误处理

本表为高频错误速查。完整错误地图（含凭据过期/缺失、接口不存在、网络超时、限流退避策略等 9 类）见 common/error_handling.md。两份冲突时以 common/error_handling.md 为准。

| HTTP 状态 / 错误码 | 行为 | |-------------------|------| | 403 / Unauthorized / AuthFailure.UnauthorizedOperation | 检查 ~/.tccli/default.credential 存在（详见 §3 OAuth 优先逻辑）；存在则提示用户当前账号是否有该产品/接口访问权限 | | InvalidParameter | 把 tccli 返回的错误 message 摘要给用户，附上你认为可能错的字段 | | ResourceNotFound | 不要重试，提示用户检查 region / 资源 ID | | LimitExceeded / 限频 | 退避重试 1 次，仍失败则报告 | | RequestTimeout | 加 --timeout 60 重试 1 次 |

不要陷入死循环重试。失败 1-2 次后停下来跟用户对齐。

references 索引

按通用工具 → 通用模块 → 子产品模块三层组织，按需加载。

通用工具（跨模块共享）

| 文件 | 用途 | |------|------| | tccli-usage.md | tccli 通用用法（参数探索四法、调用模板、常用选项） | | routing-decision.md | 详细路由决策（关键词、反例、AskUserQuestion 模板） | | common/region_dict.md | 地域中文/英文缩写 → ap-xxx ID 映射（全 18 个地域，覆盖国内+海外） | | common/error_handling.md | 跨子产品共享的错误码 → 友好提示映射 + tccli stderr 识别约定 + 重试禁忌 |

通用模块（被多个子产品主流程依赖）

| 文件 | 用途 | |------|------| | ⭐ instance-resolver.md | 通用基础模块 — strategy_type 枢轴（产品识别 + 实例发现 + 维度生成），被 monitor-query 主流程依赖、未来给 monitor-alarm/tmp 复用 | | ⭐ references/data/*.jsonl | 通用离线数据集（跨 monitor-query / monitor-alarm 共用）<br>· alarm_strategy.jsonl（922 行,strategy_type 字典 == 旧 viewName,instance_resolver + alarm_lookup 共同消费）<br>· api_metric_union.jsonl（GetMonitorData 指标全集,monitor_query 消费）<br>· show_product_dash.jsonl（strategy_type → dashboard_config_id 映射） |

子产品模块（按路由表对应加载）

| 文件 | 用途 | |------|------| | ✅ monitor-query/overview.md | 基础监控-查询：模块入口 + Action 索引 | | ↳ monitor-query/getmonitordata.md | GetMonitorData 完整工作流（6 步流水线） | | ↳ ⭐ references/data/*.jsonl | monitor-query 重度依赖三份共享数据(详见上方"通用模块"段)。monitor-query 是 alarm_strategy / api_metric_union / show_product_dash 三份的主消费者 | | ✅ monitor-alarm.md | 基础监控-告警：所有子业务告警 API 入口（10 个只读 action：枚举/strategy_type/接口/陷阱/错误特化） | | ↳ scripts/alarm_lookup.py | 封装 data/alarm_strategy.jsonl 查询（子命令：search / get / list_all），LLM 在用户提到非热门产品或多 strategy_type 产品时调用；与 instance_resolver 共用同一份元数据 | | ✅ apm.md | 应用性能监控 | | ✅ rum.md | 前端性能监控（Web/小程序） | | ✅ rum-app-pro.md | 终端性能监控 Pro（Android/iOS/鸿蒙/Flutter） | | ✅ cat.md | 云拨测 | | ✅ pts.md | 云压测 | | ✅ tmp.md | Prometheus 监控服务 | | ✅ grafana.md | Grafana 服务 | | ✅ dashboard.md | Dashboard(云监控自带智能仪表盘);⚠️ 依赖外部 skill tcop-monitor-dashboard 的 query_dashboard.py 脚本,本 skill 仅提供 API 与边界说明 | | ✅ eb.md | 事件总线(EventBridge);只读查询全量覆盖,纯 tccli 调用 |

反例提醒（容易踩的坑）

  • ❌ 跳过环境检查直接 tccli foo bar —— 用户没登录会一脸懵
  • ❌ 看到"告警"就往 APM 模块里塞 —— 告警 API 都在 monitor 下，跟子产品无关
  • ❌ 复杂结构参数硬靠 shell 转义 —— '[{"Dimensions":[{"Name":"x"}]}]' 这种容易翻车，走 cli-input-json file://
  • ❌ 把所有 reference 一次全读 —— 浪费上下文，按路由结果按需加载（哪怕骨架模块也只在用到时读）
  • ❌ 写操作展示命令并询问用户确认 —— 本 skill 是只读的,看到 Create* / Modify* / Delete* 等直接告知"不在范围,引导控制台"(见 § 5),不要构造写命令
  • ❌ 凭空猜 Namespace —— QCE/CVM 还是 QCE/CDB 必须按用户的资源类型来；不确定用 tccli monitor DescribeProductList --Module monitor 探查（注意：返回小写 qce/xxx，但 GetMonitorData 入参必须大写 QCE/XXX）
  • ❌ 在 reference / 示例里建议用 jq —— 本 skill 环境检查不强制 jq，统一用 tccli 的 --filter（JMESPath）+ python3 -c "import json,sys;..." 完成二次解析；只有 Python ≥ 3.7 是硬依赖