nullable-new-params

可空的新参数

当某项更改将新参数或类型成员设为可选时，请使用此技能。在 Remotion 内部代码中，新输入必须是必填且可空的，以便每个调用方都明确作出选择。

规则

• 内部契约：写作 name: T | null，而不是 name?: T。
• 不存在值时，调用点必须显式传入 null。
• 当 null 用作表示缺失的标记时，检查实现时应优先使用 value === null / value !== null。
• 除非周边的本地契约已统一使用 undefined，否则不要在新的内部 API 中使用 undefined 作为表示缺失的标记。
• 反模式包括冗余形式，例如 frozenFrame?: number | null；应改为 frozenFrame: number | null。

公共 API 是例外。如果更改后的签名、props 类型或选项对象从包的公共入口点导出，或记录在 packages/docs/docs 中，那么将新字段／参数设为必填会造成破坏性更改。请保持其可选，或添加向后兼容的重载／选项路径，然后酌情记录并提供默认值。

工作流

1. 检查差异，查找新添加的可选成员或参数：

bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts

实用变体：

bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts origin/main...HEAD
bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts --cached

2. 对每个候选项，判断它是否为公共 API：

   • 公共：从包入口点导出、包含在包的 exports 中，或记录在 packages/docs/docs 中。
   • 内部：本地辅助函数、内部组件 props、跨文件 monorepo 辅助函数、测试工具、内部上下文数据，以及未通过包入口点公开的类型。
   • 如果不确定，请先搜索包入口点和文档，再更改 API 形式。

3. 对内部候选项，将类型从可选改为必填且可空：

type Before = {
  readonly frame?: number;
};

type After = {
  readonly frame: number | null;
};

对于函数参数：

const before = (frame?: number) => {};
const after = (frame: number | null) => {};

4. 更新每个调用方／对象字面量，显式传入值：

   • 缺失时使用 field: null。
   • 仅当 undefined 仍可能从周边代码传入时，才使用 field: maybeValue ?? null 保留现有值。
   • 避免通过解构默认值来掩盖必须作出的选择。

5. 更新实现逻辑：

   • 当 0、'' 或 false 是有效值时，替换真值检查。
   • 对可空的数字／字符串／布尔值，优先使用 value !== null，而不是 value。
   • 更新现有测试或夹具时，保持显式传值；不要仅为规避新字段而将大型夹具改为 Partial<T>。

6. 对于公共候选项，保持向后兼容：

   • 在公共类型中保持新字段可选。
   • 在边界处解析出具体的内部值，通常使用 const internal = publicValue ?? null。
   • 内部下游类型仍须为必填且可空。

7. 验证：

   • 再次运行扫描器，直到只剩有意保留的公共 API 例外。
   • 对修改过的包运行针对性测试或构建，例如 bunx turbo run make --filter='<package-name>'。
   • 如果文档有更改，请遵循 writing-docs 技能。

审查清单

• 不再有新添加的内部 ?: 成员或 param?: 参数。
• 每个内部调用方都传入实际值或 null。
• 公共 API 保持向后兼容。
• 可空值检查不会将有效的假值视为缺失。
• 当行为取决于值是否缺失时，使用现有检查或手动验证显式的 null 路径。