用途
Build Nitro Modules 是一个端到端技能，用于构建 React Native Nitro Module：通过 Nitrogen 搭建 monorepo 脚手架、用 TypeScript 编写 HybridObject 规格、生成原生代码、实现各平台原生代码（C++/Swift/Kotlin）、接线示例应用以及准备发布。
工作原理
Nitro Modules 使用代码生成流水线（nitrogen），读取 .nitro.ts 规格文件并生成原生 C++/Swift/Kotlin 样板代码，然后由开发者填充实现。这与旧式 turbo modules 有本质不同。nitrogen/generated/ 下的生成文件是输出，应修改 .nitro.ts 规格或原生实现源码，再重新运行 nitrogen，而不是手动编辑生成文件。这些文件可以提交到 git（许多 Nitro 库确实会提交），但仓库策略可另行选择。它们必须包含在 npm 包中，以便使用者构建原生库。
与其他技能的配合
- 塑造公开 TypeScript、JavaScript、React 或 React Native API 时，先使用 api-design。本技能在此基础上补充 Nitro 专属约束：HybridObject 状态、生成的规格、原生资源所有权、零拷贝数据、线程处理、平台实现、代码生成和真机验证。
- 通用公开 API 规则和 API 时效性检查交由 api-design 负责。本技能只补充 Nitro 专属的时效性检查。
- 如果用户构建的是纯 JS 的 React 或 React Native 库，不要应用本技能，除非任务涉及 Nitro、HybridObjects、原生模块、代码生成、C++/Swift/Kotlin 绑定或 react-native-nitro-modules。
- 实现或审查 Swift、Kotlin、C++ 支撑的 HybridObjects 时，分别配合 swift、kotlin、cpp 技能。
仓库与发布参考
- 仅在创建仓库、重组布局、添加示例/文档/CI 或更改工作流策略时，加载 repo-structure-and-workflow.md。
- 仅在设置或审查 bun release / release-it 时，加载 release-it-publishing.md。
Nitro API 设计规则（要点）
- 原生模块优先使用 Nitro Modules 而非 TurboModules 或手写 JSI；仅在需要 Nitro 的 Raw JSI Methods 时使用原始 JSI。
- 保持根 HybridObject 可默认构造以支持自动链接；通过工厂方法创建依赖参数的对象。
- 用 HybridObjects 承载原生状态（原生资源、预热引擎、文件、图像、数据库、传感器会话、流等）。
- 若需要原生设置，工厂方法应为 async 并解析出就绪的 HybridObject，如 createCameraSession(...): Promise<CameraSession>。
- 一个面向 JS 的 HybridObject 规格可有多个原生具体类实现，用于在单一 TypeScript 类型背后隐藏后端策略。
- 导出的 JS 工厂对象使用产品/领域名词命名，避免与生成的规格类型名冲突。
- 每个 HybridObject 限定于一个用途或生命周期。
- 不要只按领域名词划分 HybridObject 边界。
- 当返回的 HybridObjects 在选项、结果、生命周期或未来平台支持上不同时，按稳定的语义能力拆分。
- 工厂可以合法地报告某能力不可用或拒绝在不支持该能力的平台上创建。
- 平台专属能力在其概念稳定时仍可作一等 HybridObjects。
- 用工厂方法分离工作流并强化返回的 HybridObjects。
- 返回已配置的句柄以避免过期状态；重配置应替换或使原生目标已变更的句柄失效。
- 原生协商时，将请求意图与解析后的状态分开建模。
- 能力字段用于工作流发现、可选偏好和真正可变支持，不要用来掩盖过大的 HybridObject。
- 将 HybridObjects 视为主要 API 对象，每个主要 HybridObject 有独立 .nitro.ts 文件。
- 只有在文件以基类 HybridObject 命名且子对象几乎不添加成员时，才把继承族放在一个 .nitro.ts 文件中。
- 具名代码生成类型（字面量联合/枚举、结构体/接口、选项对象、事件对象、回调选项结构体、辅助类型）放在各自 .ts 文件。
- 在方法签名中内联简单函数回调；除非函数类型在多处 API 复用，否则不要创建一次性别名。
- 用 HybridObject 继承表示共享原生状态加专用结果形状，以及异构原生结果族。
- 不要把状态族建模为带大量可空字段的单个结构体或 HybridObject。
- 将公开 Nitro HybridObjects 视为命令式 API，按其本意 1:1 导出生成的 Nitro API。
- JS/TS 层适合有意设计的高层 API（React hooks、组件、UI 组合助手），或当 HybridObject 仅为内部实现细节时。
- 仅对 JS 必须直接构造的公开根、工厂、视图或全局工具启用自动链接。
- 原生扩展点：将面向 JS 的基类 HybridObject 规格与公开原生协议/接口配对。
- Nitro 结构体用于领域形状、选项组和同类型参数簇，不要仅为减少参数数量而包装。
- TypeScript 可选字段在生成的原生代码中变为 optional，仅在缺失是预期契约时使用。
- 高频原生结果、解析负载、图像、缓冲区等不要建模为扁平结构体，优先使用带惰性属性的有状态 HybridObjects。
- 每个结果是结构体还是 HybridObject 需明确决定。
- 小量或真正零拷贝的原生数据访问使用 ArrayBuffer；大型媒体、照片、扫描、模型输出或字节负载返回 HybridObject 并提供惰性方法。
- 重复事件优先使用 addOn...Listener(callback): ListenerSubscription，让每个订阅拥有自己的清理。
- 监听器订阅应为带 remove 函数字段的扁平结构体，而非 HybridObject。
- 监听器清理应停止未来发射。
- 默认不要对监听器添加、移除和回调调用加锁。
- 仅对由对象拥有的单个热路径回调使用 setOn... 风格 API。
- Sync 回调仅用于必须在特定 JS 运行时或 worklet 线程同步执行的罕见线程绑定热路径。
- Nitro Views 暴露原始 getHostComponent 包装器；仅在能消除重复设置代码时添加 React 组件或 hooks。
- 命名、平台抽象、同步/异步边界、监听器清理、错误、变体、TypeScript 门面和 JSDoc 契约遵循 api-design。
Nitro 原生实现规则（要点）
- 调试奇怪构建失败前，先检查 Nitro 当前最低要求。当前 Nitro 文档列出：React Native 0.75+、Xcode 16.4+、Swift 5.9+、Android compileSdkVersion 34+、NDK 27+；Nitro Views 当前要求 React Native 0.78+ 和新架构。
- 每个原生 HybridObject 实现必须实现或继承该平台生成的 Hybrid*Spec，不能独立实现原生类并期望 Nitro 发现它。
- 原生实现类默认设为 final，除非确实需要继承。
- 每个文件恰好保留一个顶层原生实现类型。
- 不要为了减少文件拆分而在主要类型中嵌套辅助类型。
- 将原生文件名视为作用域契约。
- 用行数作为原生文件审查信号：在满足每文件一个类型和无工厂内辅助类型规则后，约 300 行以下通常可接受。若体积来自可单独命名的辅助类型，应拆分。