SuperAPI AI 工具集

core-guidelines

编程与开发

查看项目

更新于 10-26 09:19

技能介绍

React Native ExecuTorch 架构与编码规范指南用于帮助开发者以符合项目习惯、干净且一致的方式扩展该代码库。在实现功能或修改代码前,应按指南索引找到 .agents/skills/ 下对应的技能目录并阅读其 SKILL.md。

设计理念 库按职责划分为两层。底层 API 灵活且与领域无关,以 C++ 暴露原生 ExecuTorch 能力的原始绑定,包括张量、模型、运行时执行及基础数学/CV 操作,不含任务专用代码,允许开发者在 TypeScript 中直接定制。上层 API 透明且负责编排,完全以 TypeScript 构建在底层原生绑定之上,预处理、模型推理与输出后处理都在 TS 中动态组合。与不透明的原生流水线相比,这种方式更透明、易调试、易定制,也无需编写复杂 C++ 即可扩展。

对称架构(Core 与 Extensions) 代码库严格采用 C++ 层(cpp/)与 TypeScript 层(src/)对称布局。新增能力通常需要在两层对应子目录中修改或新增文件。

Core(cpp/core/ 与 src/core/):实现底层 API 的绝对最小必要部分,负责张量与模型管理原语、JSI 绑定以及 ExecuTorch 运行时执行逻辑。Core 与领域无关,不得加入计算机视觉、分词器、语音预处理等任务或领域专用代码。

Extensions(cpp/extensions/ 与 src/extensions/):包含全部领域专用逻辑,按领域(如 cv、math、llm、speech)组织。原生操作放在 cpp/extensions/<domain>/;JSI 安装通过 cpp/extensions/<domain>/install.cpp 注册,并挂载到全局 JSI 对象的 rnexecutorch_jsi.<domain> 下;对应的 TypeScript 包装放在 src/extensions/<domain>.ts 或 src/extensions/<domain>/;高层任务流水线(模型加载、输入预处理、推理、输出后处理的编排)完全用 TypeScript 写在 src/extensions/<domain>/tasks/ 下;React Hooks(围绕任务流水线的轻量状态/生命周期包装)放在 src/hooks/。

技能索引 新增原生算子或 C++ 绑定时,参考实现 C++ 函数、通过 JSI 暴露并编写 TypeScript 桥接包装的流程指南;创建任务流水线或 Hook 时,参考构建端到端 TS 流水线(如目标检测)并通过 React Hook 暴露的指南;验证、重建或排查改动时,参考重新构建 TS/C++ 及解决常见 JSI 运行时错误的工作流;测试 TypeScript 改动时,参考覆盖 src/ 的 Jest API 套件及其模拟原生运行时;校验模型约束与 schema 时,参考指定模型规格、动态形状和运行时约束的指南;抛出、捕获或分类错误时,参考错误码集合、RnExecuTorchError、C++ 侧 RnExecuTorchException/guarded 及新增错误码的方法;维护或重构代码库模式时,参考保持工作区技能与代码库状态同步、防止文档过时的指南。

关键编码约定 直接包装原生 JSI 调用的 TypeScript 函数应以 worklet 指令开头,以兼容基于 worklet 的库(如 React Native Reanimated)。函数与方法选项参数一律命名为 options,可用 Opts 作为类型或属性后缀(如 ModelOpts、TaskOpts、modelOpts)。库抛出的每个失败都携带字符串错误码:TypeScript 使用 RnExecuTorchError('CODE', msg)(它是函数而非类,以便跨越 worklet 边界),C++ 使用 error::InvalidArgument(msg) 加 error::guarded(...);不得依据消息文本分支。编写 JSI 原生 C++ 代码时需注意 JSI 引用管理并安全处理 ExecuTorch 生命周期状态。始终基于 core 原语构建,除非修复基础运行时缺陷,不要修改 cpp/core/ 或 src/core/ 中的文件。

包注册与导出 新增扩展、任务流水线或 Hook 时,必须在包级别注册并导出:在 src/index.ts 导出新任务流水线(如 export * from './extensions/cv/tasks/myTask')和 Hook(如 export * from './hooks/useMyTask')。src/models.ts 与 src/constants.ts 是预导出模型、选项和标签结构的唯一事实来源,不得在其他位置临时定义。模型注册规则要求 models.ts 只导出单一的 models 对象注册表,不导出单个模型配置常量,配置以私有 const 定义并在注册表相应类别下登记;引入标准预配置模型时,在此添加元数据配置及 HuggingFace/本地 URI 端点映射。

通过示例应用检查与测试模型 工作区采用 monorepo 结构,apps/ 下按领域放置示例应用(如 apps/computer-vision、apps/nlp),用于在设备上检查模型和测试流水线。Inspect 页面(如 apps/computer-vision/app/inspect/index.tsx)可粘贴任意 .pte 模型 URL,动态加载并打印元数据、输入和输出;交互式测试页面(如 apps/nlp/app/tokenizer/index.tsx)可交互测试任务流水线,新增任务时应在相应领域应用中添加对应的测试卡片/流程;Camera 页面(如 apps/computer-vision/app/camera/index.tsx)可用任务流水线运行实时摄像头推理。

验证与重建 编译 TS/C++、重建 iOS pods 和排查原生改动时,按验证与构建技能的完整检查清单执行。