tsa-risk

# 腾讯云智能顾问 — 架构风险巡检分析报告 本 skill 用于分析用户在腾讯云智能顾问产品下的架构图风险巡检情况，自动拉取数据并生成可视化报告。 ## 接口约束 > **重要**：本 skill 仅允许调用以下 `references/` 中定义的 4 个智能顾问接口，不得调用任何 references 之外的接口： | # | Action | 说明 | 文档 | |---|--------|------|------| | 1 | `DescribeArchScanReportLastInfo` | 获取最新巡检报告ID | `{baseDir}/references/api/DescribeArchScanReportLastInfo.md` | | 2 | `DescribeArchScanOverviewInfo` | 查询巡检概览信息 | `{baseDir}/references/api/DescribeArchScanOverviewInfo.md` | | 3 | `DescribeArchRiskTrendInfo` | 查询风险趋势信息 | `{baseDir}/references/api/DescribeArchRiskTrendInfo.md` | | 4 | `DescribeScanPluginRiskTrendListInfo` | 查询风险明细列表 | `{baseDir}/references/api/DescribeScanPluginRiskTrendListInfo.md` | 所有接口统一通过 `{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。 ### 第二步：环境检查 ```bash python3 {baseDir}/check_env.py ``` ### 第三步：拉取数据 ```bash python3 {pluginDir}/scripts/risk_fetch_data.py <ArchId> ``` 该脚本自动完成以下工作： 1. **自动获取 ResultId**：首先调用 `DescribeArchScanReportLastInfo` 接口，通过 ArchId 获取最新的报告 ID - 如果接口调用失败（报错），**中断整个流程**，脚本会输出错误信息，需向用户提示异常原因 - 如果 ResultId 为空，说明该架构图尚未进行过巡检，**中断整个流程**，需提示用户前往 [腾讯云智能顾问控制台](https://console.cloud.tencent.com/advisor?archId={{ArchId}}) 发起巡检 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` 始终保持不变作为基线 ```bash # 如需修改生成逻辑，先创建自定义副本（仅首次） 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` 指定模板目录： ```bash # 同样优先使用 _custom 版本 python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --template <自定义模板名> ``` #### 4c. 保存自定义模板 当用户对主题有自定义修改需求时： 1. 复制 `{pluginDir}/template/default/` 下对应主题 JSON 文件 2. 按用户需求修改颜色、阈值、布局等配置 3. 使用 `--save-template` 保存为新模板（会在 `template/<名称>/` 下创建）： ```bash python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --theme ocean --save-template my-custom ``` #### 4d. 列出可用模板 ```bash 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. 重新生成报告（附带分析）： ```bash python3 "$GEN_SCRIPT" ./output/data_<ArchId>.json --theme random --summary ./output/summary_<ArchId>.txt ``` > 也可同时指定自定义模板：`--template <模板名> --summary ...` ### 第六步：HTML 转 PNG ```bash 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. **直接在本地打开报告图片**： ```bash # 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 截图能力，可能需要安装额外依赖 ## 参考资料（按需加载） | 文档 | 说明 | |------|------| | `{baseDir}/references/api/DescribeArchScanReportLastInfo.md` | 获取最新报告ID接口 | | `{baseDir}/references/api/DescribeArchScanOverviewInfo.md` | 巡检概览接口 | | `{baseDir}/references/api/DescribeArchRiskTrendInfo.md` | 风险趋势接口 | | `{baseDir}/references/api/DescribeScanPluginRiskTrendListInfo.md` | 风险明细列表接口 | | `{pluginDir}/ReportDesignSpec.md` | 报告内容与样式规范 |