Prowler 产品 Tour 对齐检查报告output-format.md规范深度解析【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler导读本文围绕 Prowler 仓库中skills/prowler-tour/references/output-format.md定义的Tour Alignment Report产品引导对齐检查报告输出格式规范展开。该规范是prowler-tour技能的核心产出契约当 UI 组件、路由或文案变更波及产品引导product tour时技能负责检测 tour 定义与真实 UI 之间的“漂移”drift并以一种下游可机器消费、字段顺序不可变动的固定结构输出报告。读完本文你将掌握该报告的完整模板、每条字段的承载语义、多 tour 场景下的报告拆分规则、无漂移时的兜底输出以及BUMP/NO bump版本判定树的用法并结合仓库源码理解其底层支撑。一、报告的本质一份“字段即契约”的机器可读输出output-format.md开篇即点明这份报告的定位The report is consumed downstream. Field names, order, and headings are load-bearing — do not rename, reorder, or omit them.这句话是整个规范的主心骨报告不是给人看的自由文本而是被下游流程CI 门禁、版本决策工具、自动化维护管线消费的结构化数据。字段名、字段顺序、标题层级都是承重结构任何重命名、重排或省略都会破坏下游解析。这一点在 SKILL.md 中再次被强调——“The structure is mandatory because the report is consumed downstream and tolerates no field reordering”结构是强制的因为报告被下游消费且不容忍字段重排。从仓库源码看这份报告对应的运行上下文是 Prowler 前端的产品引导体系tour 定义文件位于 ui/lib/tours/每个*.tour.ts通过defineTour(...)声明id、version、coversFiles和steps并由 use-driver-tour.ts 在运行时驱动。coversFiles正是技能判断“本次变更是否波及某个 tour”的匹配依据详见下文“早期退出规则”。二、报告模板逐字段解析规范给出了唯一合法的报告模板原文逐字继承如下## Tour Alignment Report **Tour:** tour-idvversion **Files touched:** comma-separated list of files in the change ### Drift detected - one bullet per drift item; include file:line where available ### Recommended actions 1. numbered, actionable steps the developer should take ### Version bump verdict - BUMP | NO bump — one-line rationale各字段语义与约束如下字段格式承载语义与约束## Tour Alignment Report二级标题固定文本报告的唯一顶层标识不可改名**Tour:**tour-idvversion标识受影响的具体 tour 及其版本例如add-providerv2版本号必须与 tour 定义中的version字段一致**Files touched:**逗号分隔的文件列表本次变更涉及的文件清单供下游定位问题范围### Drift detected每个漂移项一个 bullet每项尽量携带file:line定位信息便于开发者直接跳转修复### Recommended actions有序编号列表开发者应采取的、可执行的修复步骤### Version bump verdictBUMP或NO bump 一行理由版本判定结论任何情况下都必须输出见“无漂移兜底”小节注意**Tour:**使用的是 Markdown 粗体而非标题tour-idvversion这种idv版本的写法与 tour-config.ts 中 driver.js 的激活方式以及 localStorage 的持久化键prowler.tour.id.vversion一脉相承——身份与版本始终绑定出现。三、三条强制性规则规范正文只有三条规则但每一条都直接决定了报告的合规性规则 1一个 tour 一份报告多 tour 用---分隔One report per affected tour. If multiple tours are affected, separate reports with a---line.一次 UI 变更可能同时命中多个 tour 的coversFiles例如同时重构了 Scans 页面和 Providers 页面。此时必须为每个受影响 tour 独立输出一份报告并用---分隔线隔开确保下游能按 tour 粒度分别消费、分别决策。规则 2无漂移也要输出报告兜底模板If no drift is detected for an affected tour, still emit the report: put No drift detected. under Drift detected and None required. under Recommended actions. The verdict line is still mandatory.只要某个 tour 被判定为“受影响”即使零漂移也必须输出报告且填充值是精确指定的Drift detected下写No drift detected.Recommended actions下写None required.Version bump verdict行仍然必须存在结论通常是NO bump这条规则保证了报告结构在任何分支下都完整一致下游解析器永远不会遇到“缺字段”的异常输入。规则 3verdict 只能二选一The verdict is exactly one ofBUMPorNO bump— see the version-bump decision tree inSKILL.md.判定结论是离散枚举不允许出现第三种写法或含糊表述。判定依据在 SKILL.md 的 “Version-bump decision tree” 一节下一节详解。四、版本判定树BUMP还是NO bump虽然判定树位于 SKILL.md但它是报告Version bump verdict字段的唯一合法取值来源与输出格式规范构成闭环必须一并理解NO bump不升版本变更是**外观性cosmetic**的。规范给出的例子包括修正拼写错误、软化文案措辞、重命名data-tour-id选择器但保持同一 step、替换某张截图、收紧措辞等。BUMP version升级版本号用户可见流程发生实质性变化。例如新增或删除了 step、step 顺序改变、锚点目标被重新指向另一个面板、tour 开始覆盖面上的新功能等。兜底判据当不确定时问一个问题——Would a user who already saw the previous version miss something useful by not seeing this one?看过旧版本的用户如果看不到这一版是否会错过有用的东西——答案是“是”则BUMP。这一判定在源码中有真实案例。例如 view-first-scan.tour.ts 中的view-first-scantour 当前为version: 2注释明确说明 v2 的变更内容是“lands on the In Progress tab and highlights the running scan when there is one”落点在 In Progress 标签页并高亮正在运行的扫描——这是 step 顺序与锚点目标的实质改变属于典型的需要BUMP的场景。同理add-provider.tour.ts 中add-provider为version: 2注释说明 v2 “now drives the user into the wizard body ... instead of ending at type selection”现在引导用户进入向导主体而不再止步于类型选择——新增了 step同样触发BUMP。五、报告产生的前置流程早期退出与漂移检查清单报告不是凭空生成的prowler-tour技能在执行中遵循一套严格流程理解它才能正确解读报告内容。完整流程见 SKILL.md摘要如下1. 早期退出规则Early-exit rule技能必须先跑这个检查因为绝大多数 UI 编辑与 tour 无关用 Glob 匹配ui/lib/tours/*.tour.ts对每个 tour检查其coversFiles中的任意 glob 是否匹配当前变更中的文件若无任何 tour 命中则精确回复No tour affected — skipping alignment check并退出不生成报告若有至少一个 tour 命中则进入该 tour 的漂移检查清单。这一机制在源码层面直接依赖 tour-types.ts 中TourDefinition.coversFiles字段注释明确写着“coversFilesis consumed by theprowler-tourskill to scope drift checks”。2. 六类漂移检查清单Drift checklist对每个受影响的 tour逐项评估跳过明显不适用的项但必须显式列出检查了哪些项。这六类漂移正是报告中Drift detected小节 bullet 的内容来源Orphan selectors孤儿选择器每个 step 的target会组合成data-tour-idtour-id-step.target必须能在代码库中解析到真实元素grep 不到即视为孤儿。Renamed selectors选择器被改名变更中编辑了data-tour-id属性需要反向匹配引用了旧值的 tour step。Outdated copy文案过期popover 的title/description引用了页面上已不存在的按钮标签、标题或术语。Obsolete steps步骤过时step 描述的区块、面板或流程已被移除。Missing steps缺失步骤覆盖面上新增了功能新面板、新主操作、新向导阶段却没有对应 step。Reordered flow流程重排用户路径改变如查询构建器移到扫描选择之前而 step 顺序未同步。3. 选择器约定的底层原理要准确判断第 1、2 类漂移必须理解选择器约定详见 tours-architecture.mdstep 通过data-tour-idtour-id-step.target锚定 DOMuse-driver-tour.ts 的getTourTargetSelector(tourId, target)在运行时组合选择器adaptStep()将其转换为 driver.js 的DriveStep.elementtour 作者只需在step.target中写 step 名禁止使用基于 class、ID 结构的选择器——它们会把 tour 耦合到本可合理变更的样式决策上。从源码结构看target的字符串字面量被 tour-types.ts 的defineTourconst TTarget extends string(...)保留为字面量联合类型从而让useDriverTour能对stepHandlers的键和waitForStep的参数做编译期类型校验——这是“选择器是承重结构”这一设计理念在类型系统层面的落实。六、报告背后从驱动钩子到持久化的完整链路为了让报告的Version bump verdict决策更有依据有必要了解 tour 版本在运行时如何被消费。整条链路详见 tours-architecture.md 的 Code map如下文件职责ui/lib/tours/tour-types.ts公开类型面TourDefinition、TourStep、TourId、TourCompletionRecord、完成状态常量表导出defineTour(...)作者辅助函数ui/lib/tours/tour-config.tsbaseDriverConfig、getDriverConfig(theme, overrides?)、遮罩颜色映射ui/lib/tours/store/tour-completion-store.ts持久化接口契约get/set/clear未来可平滑替换为 API 适配器ui/lib/tours/store/local-storage-adapter.ts目前唯一的适配器存储键格式prowler.tour.id.vversionui/lib/tours/use-driver-tour.tsReact 钩子初始化 driver.js、从useTheme()派生遮罩色、持久化完成状态ui/lib/tours/id.tour.ts每个 tour 一个文件通过defineTour({...})声明由选择加入的页面导入ui/styles/tours.css.driver-popover.prowler-theme所有颜色经var(--...)从globals.css解析几个与报告决策直接相关的关键实现细节身份与版本绑定tour 是{ id, version }二元组localStorage 键同时包含两者实质内容变更才BUMP version外观性编辑不升版——这与报告 verdict 字段的判定完全同源。持久化作用域为“每用户、跨租户”用户在租户 A 完成attack-pathsv1后即使在租户 B 可访问该功能也不会再次看到 tour。这意味着版本决策直接影响真实用户是否会被重复打扰。漂移是头号风险如果没有维护技能和可选的 CI 门禁ui/scripts/check-tour-alignment.mjs该文件在仓库中作为可选门禁被引用tour 会随着覆盖 UI 的演进静默腐化silently decay——这正是报告规范存在的原因。七、技能边界报告只读绝不代改最后需要强调prowler-tour的定位见 SKILL.md 的 “What this skill MUST NOT do”只报告Report-only技能从不修改 tour 文件或 UI 文件只检查变更、报告漂移、给出建议不编辑*.tour.ts不新增或重命名data-tour-id属性不发明新 tour——创作新 tour 是开发者的独立决策不标记coversFiles未命中当前变更的 tour 的漂移严格遵守早期退出规则。因此报告的Recommended actions小节永远是对开发者的建议而不是技能自身的行动清单。这也解释了为什么报告要求“numbered, actionable steps the developer should take”——它是一份给人类开发者的可执行工作交接单。结语output-format.md虽然只有三十余行却是 Prowler 产品引导维护体系中承上启下的“契约文件”上承prowler-tour技能的漂移检查与版本判定逻辑下接需要稳定字段结构的自动化消费方。理解它就等于掌握了如何在 Prowler 前端演进时让产品引导ui/lib/tours/ 下的各 tour 定义始终与真实 UI 保持同步——这既是文档的原始意图也是本仓库 tours-architecture.md 所强调的“漂移 头号风险”的应对之道。【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考