tsa-risk

腾讯云智能顾问 — 架构风险巡检分析报告

本 skill 用于分析用户在腾讯云智能顾问产品下的架构图风险巡检情况，自动拉取数据并生成可视化报告。

接口约束

重要：本 skill 仅允许调用以下 references/ 中定义的 4 个智能顾问接口，不得调用任何 references 之外的接口：

所有接口统一通过 {baseDir}/scripts/tcloud_api.py 调用，服务名 advisor，API 版本 2020-07-21。

路径约定：下文使用 {pluginDir} 表示 {baseDir}/references/plugins/tas-risk，插件专用脚本（数据拉取、报告生成、截图转换）位于 {pluginDir}/scripts/，公用脚本（环境检查、API调用、免密登录等）位于 {baseDir}/scripts/。

辅助脚本说明：{baseDir}/scripts/login_url.py 和 {baseDir}/scripts/setup_role.py 为可选辅助脚本，使用 STS/CAM 通用服务接口（非智能顾问业务接口），仅用于免密登录链接生成和角色配置，不在核心数据流程中。

前置条件

• 系统需安装 python3（3.6 及以上版本）
• 需配置腾讯云 API 密钥环境变量：TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY

工作流程

第一步：获取用户输入

• ArchId（必填）：架构图 ID，如 arch-xxxxx

注意：ResultId 无需用户提供，系统会自动通过 DescribeArchScanReportLastInfo 接口获取最新的报告 ID。

第二步：环境检查

python3 {baseDir}/check_env.py

第三步：拉取数据

python3 {pluginDir}/scripts/risk_fetch_data.py <ArchId>

该脚本自动完成以下工作：

1. 自动获取 ResultId：首先调用 DescribeArchScanReportLastInfo 接口，通过 ArchId 获取最新的报告 ID
   • 如果接口调用失败（报错），中断整个流程，脚本会输出错误信息，需向用户提示异常原因
   • 如果 ResultId 为空，说明该架构图尚未进行过巡检，中断整个流程，需提示用户前往 腾讯云智能顾问控制台 发起巡检
2. 依次调用三个数据接口并将数据合并为 JSON 文件，输出到 ./output/data_<ArchId>.json（当前工作目录下）

数据拉取特性：

• DescribeScanPluginRiskTrendListInfo 接口使用 Limit=200（最大分页） 并自动分页遍历，确保获取全部风险明细数据
• 所有分页数据合并后统一写入 JSON，TotalCount 为实际获取的总条数
• 其他接口单次调用即可

使用接口前，必须先加载对应的接口文档：{baseDir}/references/api/<Action>.md

第四步：生成 HTML 报告

数据来源：./output/data_<ArchId>.json

4a. 默认方案（无特殊样式要求）

脚本优先级机制：系统优先加载 generate_report_custom.py，不存在时回退到 generate_report_default.py。

规则：

• generate_report_custom.py 不预置，仓库中只有 generate_report_default.py 作为基线版本
• 当用户自定义报告需求通过 --template 模板配置无法满足、需要修改生成逻辑（如布局、模块增删、图表样式、数据处理等）时，先将 generate_report_default.py 复制为 generate_report_custom.py，再在副本上修改
• 一旦 generate_report_custom.py 存在，后续所有生成都自动使用它；generate_report_default.py 始终保持不变作为基线

# 如需修改生成逻辑，先创建自定义副本（仅首次）
if [ ! -f "{pluginDir}/scripts/generate_report_custom.py" ]; then
  cp {pluginDir}/scripts/generate_report_default.py {pluginDir}/scripts/generate_report_custom.py
fi

# 自动选择脚本（优先 _custom 版本）
GEN_SCRIPT="{pluginDir}/scripts/generate_report_custom.py"
if [ ! -f "$GEN_SCRIPT" ]; then
  GEN_SCRIPT="{pluginDir}/scripts/generate_report_default.py"
fi
python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --theme random

可指定主题：--theme ocean|sunset|forest|lavender|coral|slate

4b. 使用自定义模板

如果用户之前保存过自定义模板，可通过 --template 指定模板目录：

# 同样优先使用 _custom 版本
python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --template <自定义模板名>

4c. 保存自定义模板

当用户对主题有自定义修改需求时：

1. 复制 {pluginDir}/template/default/ 下对应主题 JSON 文件
2. 按用户需求修改颜色、阈值、布局等配置
3. 使用 --save-template 保存为新模板（会在 template/<名称>/ 下创建）：

python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --theme ocean --save-template my-custom

4d. 列出可用模板

python3 "$GEN_SCRIPT" --list-templates

4e. 定制方案（用户有特殊样式需求且模板无法满足）

不使用脚本，而是：

1. 读取 ./output/data_<ArchId>.json 数据
2. 参考 {pluginDir}/ReportDesignSpec.md 了解报告模块与样式规范
3. 根据用户样式要求直接生成自定义 HTML 报告
4. 输出到 ./output/report_<ArchId>.html

第五步（可选）：AI 报告分析

此步骤默认不启用。仅当用户明确要求生成 AI 分析摘要（如提到"分析一下"、"总结报告"、"AI 解读"等关键词）时才执行此步骤。默认流程直接从第四步跳到第六步。

如果用户要求启用 AI 分析，在生成 HTML 后、转 PNG 前，对巡检数据进行分析：

1. 读取 ./output/data_<ArchId>.json 中的关键数据
2. 生成简洁专业的中文分析文本（200-400字），具体要求参见 {pluginDir}/ReportDesignSpec.md
3. 保存到 ./output/summary_<ArchId>.txt
4. 重新生成报告（附带分析）：

python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --theme random --summary ./output/summary_<ArchId>.txt

也可同时指定自定义模板：--template <模板名> --summary ...

第六步：HTML 转 PNG

python3 {pluginDir}/scripts/html_to_png.py ./output/report_<ArchId>.html

最终输出 PNG 到 ./output/report_<ArchId>.png。

第七步：生成报告的结果处理

⚠️ 核心原则：报告图片优先！ 无论何种场景，都必须 优先尝试发送/展示报告图片，只有在确认图片无法发送时才降级。

报告生成完毕后，按以下优先级策略处理：

策略 A：IM 回复场景（Web端、企微、飞书等在线对话）

1. 优先发送报告图片（必须！）

   • 调用 read_image 工具读取 ./output/report_<ArchId>.png，让图片 直接内联显示 在对话消息中
   • 发送图片后，附上文字提示（见下方模板）

2. 降级方案：仅当图片确实无法发送时（如 read_image 工具不可用、图片文件生成失败、PNG 转换全部失败等）

   • 读取 ./output/data_<ArchId>.json 数据，将报告内容解读为 Markdown 格式文本 发送
   • 必须在消息开头添加降级说明，格式如下：

   > ⚠️ 图片报告未能发送（原因：{{具体原因，如"PNG截图工具均不可用"或"read_image工具调用失败"等}}），以下为文本版报告：
   

   • 然后输出 Markdown 格式的报告内容
   • 在末尾补充提示：💡 建议：升级至最新版 CLAW 客户端以获得图片报告的最佳体验

策略 B：本地 CLAW 场景（qclaw 等本地客户端）

如果检测到当前运行环境为本地 CLAW（如 qclaw）且不支持在对话中发送/内联图片：

1. 直接在本地打开报告图片：

   # macOS
   open ./output/report_<ArchId>.png
   # Linux
   xdg-open ./output/report_<ArchId>.png
   # Windows
   start ./output/report_<ArchId>.png
   

2. 在对话中回复：📷 报告图片已在本地打开，请查看。
3. 如果本地打开也失败，则降级为 Markdown 文本（同策略 A 的降级方案）

文字提示模板

发送图片后（或降级文本报告后），参考下面文字提示模板补充提示：

<简洁总结报告>
若需修改可以直接发送修改意见
🔗 查看更多： 如需查看完整架构详情、历史报告及更多风险分析，请前往 [腾讯云智能顾问控制台](https://console.cloud.tencent.com/advisor?archId={{ArchId}}&plugin=cloud-inspection-sdk)

⚠️ 重要： [腾讯云智能顾问控制台] 对应链接为免密登录链接每次都必须重新生成，不可缓存或复用之前生成的链接。每次向用户展示时，都必须重新调用 scripts/login_url.py 生成新的链接。

---

注意事项与安全规范

密钥安全

1. 严禁将 AK/SK 硬编码在代码中，必须通过环境变量传入
2. 建议使用子账号密钥，仅授予 QcloudAdvisorReadOnlyAccess 权限
3. 生产环境推荐使用 STS 临时密钥，设置 TENCENTCLOUD_TOKEN

API 限制

• 所有接口限制 20 次/秒（维度：API + 接入地域 + 子账号）
• 地域默认 ap-guangzhou，Region 为可选参数

平台兼容性

• 所有脚本均为 Python 实现，跨平台兼容 macOS、Linux 和 Windows

免密链接

• 默认有效期 30 分钟，可通过 TENCENTCLOUD_STS_DURATION 调整（最大 7200 秒）
• 当返回结果包含架构图时，只需为第一张架构图生成免密登录控制台链接
• 以 [腾讯云智能顾问控制台](免密登录URL) 超链接形式展示，严禁直接展示完整 URL
• 每次展示都必须重新调用 login_url.py 生成新链接，不可缓存或复用

错误处理

• 如果某个接口调用失败，报告中对应模块显示"数据获取失败"提示，不影响其他模块
• HTML 转 PNG 依赖 Python 截图能力，可能需要安装额外依赖

参考资料（按需加载）