SuperAPI AI 工具集

nullable-new-params

编程与开发

查看项目

更新于 10-15 21:09

技能介绍

用途:在 Remotion 单体仓库的 diff 中,处理新加入的可选参数、可选 React props 和可选类型/接口成员。内部代码的新输入必须为必填且可空,让每个调用方显式做出选择。

主要规则:内部契约写 name: T | null,而非 name?: T;调用点无值时显式传 null;当 null 表示缺失时,实现检查优先用 value === null / value !== null;除非周边本地契约已统一用 undefined,否则新内部 API 不用 undefined 作缺失标记;避免 frozenFrame?: number | null 这类冗余写法,改为 frozenFrame: number | null。公开 API 是例外:若签名、props 类型或 options 对象从包公开入口导出或在 packages/docs/docs 中有文档,把新字段/参数改为必填属于破坏性变更,应保持可选或增加向后兼容的重载/options 路径,并适当记录与设默认值。

工作流:先用扫描脚本查找新增可选成员或参数,例如 bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts,可加 origin/main...HEAD 或 --cached 变体。对每个候选项判断是否公开:公开指从包入口导出、包含在 package exports 中或在 packages/docs/docs 有文档;内部指本地辅助函数、内部组件 props、跨文件单体仓库辅助、测试工具、内部上下文数据及未通过包入口暴露的类型。不确定时先 grep 包入口和文档。

内部候选项:把类型从可选改为必填可空,如 frame?: number 改为 frame: number | null;函数参数同理。更新所有调用方/对象字面量显式传值:缺失时用 field: null;仅当 undefined 仍可能从周边代码进入时用 field: maybeValue ?? null 保留原值;避免用解构默认值隐藏必填选择。更新实现逻辑:当 0、''、false 是有效值时替换真值检查;可空数字/字符串/布尔优先用 value !== null 而非 value;测试与 fixture 保持显式,不要为躲避新字段把大 fixture 改成 Partial<T>。

公开候选项:保持新字段在公开类型中可选;在边界处解析出具体内部值,通常用 const internal = publicValue ?? null;下游内部类型保持必填可空。

验证:再次运行扫描器,直到只剩有意的公开 API 例外;对受影响包运行聚焦测试或构建,例如 bunx turbo run make --filter='<package-name>';若文档变更,遵循 writing-docs 技能。

审查清单:不残留新的内部 ?: 成员或 param?: 参数;每个内部调用方传真实值或 null;公开 API 保持向后兼容;可空检查不把有效假值当作缺失;当行为依赖缺失时,测试至少覆盖一条显式 null 路径。