SuperAPI AI 工具集

announcing-behavior-changes

通用与其它

查看项目

更新于 10-16 03:45

技能介绍

用途:当某个修复纠正了错误行为却改变了用户看到的结果(数字变化、图表偏移、计数下降)时,判断是否需要应用内变更提示,并给出实现方式。核心原则是提示只发给受影响用户,否则会让人习惯性忽略横幅。

判定条件:仅当四条同时成立才需要提示——用户什么都不做也会看到不同结果;用户无法从界面自行理解原因;差异足够明显;能在代码中识别受影响人群。若无法用客户端已有状态表达“该用户受影响”,应改用其他机制:仅后端可知时用 API 响应上的逐对象字段(参考 Action.selector_warning #80653);永久性条件用计算出的警告而非限时提示;影响广泛但变更轻微只写 changelog;旧行为明显有错、新行为显然正确则什么都不做。

实现模式(五部分,与行为变更同一 PR 发布):一、导出的、带注释说明对应后端规则的命名谓词函数,可脱离渲染单元测试;二、在 frontend/src/lib/constants.tsx 声明带 owner 注释的特性开关;三、默认返回 null 的组件,先查开关再查谓词,使用 LemonBanner type="info",dismissKey 与开关键一致并保持稳定;四、渲染在结果出现处,优先选共享渲染点(如 DateFilter.tsx 可一次覆盖洞察、仪表盘、Web 分析等);五、组件上方写明移除日期注释,并同步到开关描述。

文案:调用 /writing-user-facing-copy 的语态规则,结构为两句——具体说明改了什么、结果可能不同。用用户可见行为描述,不写内部实现;明确说数字可能不同以免被误报为 bug;不道歉、不称其为修复或改进;两句不够则链接文档。

测试:谓词写参数化单元测试覆盖受影响与不受影响两类,参考 SqlInsightDateFilterNotice.test.ts 的 it.each 写法;不必测试组件渲染。

关键限制:关闭开关可立即停用提示且无需部署,但不会删除代码;仓库没有自动清理过期开关的机制,移除日期只是给人看的备注。关闭开关后应手动删除组件、测试、开关常量和渲染点,切勿对提示开关使用 /cleaning-up-stale-feature-flags,因为该技能会保留启用路径导致横幅对所有人永久显示。具体步骤和文件路径以所提供资料为准,其他细节暂未提供。