Keel — 架构

Keel 是专为 AI Builder 设计的 React Native 框架——把 AI 生成的代码跑起来、构建成真原生 app、OTA 热更、一键上架。它跟 Expo 一样分两层：框架（SDK + CLI）+ 云服务 KAS（Keel Application Services，≡ Expo 的 EAS）。KAS 是付费云的伞名，下辖 KAS Build / Update / Submit / Credentials（一一对应 EAS Build/Update/Submit/credentials），外加配套 Keel Go（free tester app）和 Dev Client（自定义 tester）。每层可独立用、独立计费；China-friendly 但不锁国内——能连任意后端、部署到任何地方。

命名口径：KAS = Keel Application Services 是云伞名（对标 EAS），不是单指凭据金库——那是 KAS Credentials。CLI 动词仍是 keel build / submit / publish / rollback / credentials；云端进程仍是 keel-{build,update,push,submit} + credentials-server（即 KAS Credentials）。

Keel 专注 iOS + Android mobile target。Web app 用独立 Next.js / Vite stack；WeChat Mini Program 在 路线图（独立 WXML pipeline，不复用 RN 代码）。

Keel 与 Mortar 的关系：完全解耦，没有依赖关系。Keel works with any backend；用户接 Mortar 跟接 Supabase / Firebase / 自家 一样的方式（标准 Mortar SDK，没有 Keel-specific plugin）。

5 层架构

                    ┌──────────────────────────────────────────────┐
                    │  开发者机器                                   │
                    │  ┌──────────┐   ┌────────────┐                │
                    │  │ Keel CLI │   │ Keel Go    │ ← QR 扫码     │
                    │  └────┬─────┘   └────────────┘    粘 URL     │
                    │       │                                       │
                    │       │  push tarball                         │
                    └───────┼───────────────────────────────────────┘
                            │
                            ▼
              ┌────────────────────────────────────────┐
              │  KAS Build （云端构建）                 │
              │   metro → Hermes byte-compile          │
              │   → ipa / apk                          │
              │   [构建机：阿里云 ECI / FC]             │
              └────┬─────────────────────────┬─────────┘
                   │                         │
            artifact 落 Keel OSS         metadata
                   │                         │
                   ▼                         ▼
            ┌─────────────────┐      ┌─────────────────┐
            │  KAS Update     │      │  KAS Submit     │
            │  (manifest +    │      │  (App Store +   │
            │   bsdiff + CDN  │      │   华为/小米/    │
            │   + 灰度)        │      │   OPPO/vivo/    │
            │                 │      │   应用宝)        │
            └────────┬────────┘      └─────────────────┘
                     │
                client 拉 bundle
                     │
                     ▼
       ┌─────────────────────────────────────────────┐
       │  Keel SDK（在用户 app 里）                    │
       │                                              │
       │  iOS: KeelModuleCore.xcframework                      │
       │  Android: keel-module-core.aar                      │
       │                                              │
       │  Optional plugins:                          │
       │   import { mortar } from '@mortar/client'    ← 如果接 Mortar 后端 │
       │   import { Stack } from '@keel-ai/router'     ← 如果用 App Router │
       │   import { wechat } from '@keel-ai/wechat'    ← 国内一等模块     │
       └──────────────────────────────────────────────┘

第 1 层：Native SDK

引入到现有 RN app 或新 app 的核心 runtime。

两个产物

分发渠道（iOS）

iOS 双轨分发，SPM 为默认，CocoaPods 为兼容路径：

SPM 是 Apple 官方推荐的依赖管理方式，新建 iOS 项目原生支持、零配置。Keel 默认走 SPM，对齐未来 iOS 生态方向；底层第三方 SDK 暂未提供 Package.swift 的少量模块保留 CocoaPods 集成路径，等其上游迁移完成后逐步收归 SPM。客户集成不需要在两种工具间二选一——核心走 SPM，需要哪个 pod-only 模块就额外引入哪个，互不冲突。

iOS 的 SPM 入口在 keel/modules-core/。keel/sdk/ 现在是纯 JS umbrella——两端的 native（foundation + substrate）都已折入 modules-core（iOS 2026-05-29，Android 在 Z 重构中），对称交付为 KeelModuleCore.xcframework（SPM）+ keel-module-core.aar（maven com.appunvs:keel-module-core）。所以 keel/sdk/ 下没有 android/ / ios/ / Package.swift / Keel.podspec：

• keel/modules-core/Package.swift —— iOS 唯一的 SPM 包：.binaryTarget 指向 keel/build/ios/KeelModuleCore.xcframework，外加 KeelMacros source plugin。host 按 path: 直接消费。
• keel/modules-core/KeelModuleCore.podspec —— 仅 build-time recipe（react-native.config.js 里 ios:null，从不被 autolink；只在烤 xcframework 时用一次）。
• npm 侧 @keel-ai/keel（umbrella）的 dependencies 直接列出 @keel-ai/modules-core，避免靠 leaf peer-dep 传递（与 Expo expo umbrella 同模式）。

iOS 分发形态——按层不同（过渡中）

Package.swift 与 *.podspec 在每一层的存在状态：

modules-autolinking 两条路都已实现：link / install 为单模块 emit Podfile + Gradle snippet（iOS 侧内部已无消费者——signin 也于 2026-06-03 转 SPM；该 snippet 仅外部 standalone 分发时用）；autolink 扫描 <host>/node_modules 后生成 KeelModulesProvider.{swift,kt}，把每个模块注册进 KeelModuleRegistrar。React-free 的 SPM 模块仍由 host 的 Package.swift / project.yml 按 path: 手写声明，但其注册条目由 autolink 生成。

发版流程见 keel/packaging/release.sh（本地一键产 release 片段；零 CI）；私有 / 企业渠道见 enterprise-distribution.md。

Android 单一渠道：keel-module-core.aar 经 Maven 分发（Maven Central 规划中），无需多渠道。

公开 API（在 native 层）

类名：KeelRuntimeHost / KeelSDK。模块 / 框架名（KeelModuleCore.xcframework / import KeelModuleCore / keel-module-core.aar）一直是 Keel-branded。

公开 API（在 JS 层）

// 后端 —— 可选 plugin（@mortar/client 不是默认 bundle）
import { mortar } from '@mortar/client';
mortar.from('todos').select(...);
mortar.auth.signIn(...);

// 文件路由 —— 可选 plugin（已加入）
import { Stack, Tabs } from '@keel-ai/router';
// 或者沿用 react-navigation imperative 风格也可（兼容）

// 国内一等模块 —— 可选（按需 npm install）
import { wechat } from '@keel-ai/wechat';
import { alipay } from '@keel-ai/alipay';

New Architecture 默认开启

Keel SDK 跟随 RN 0.85.2，默认开启 New Architecture：

• Fabric（new renderer）—— 异步、并发渲染
• TurboModules（new native modules）—— 按需加载、启动延迟降低 30%+
• Bridgeless（不用 RN bridge）—— JS / native 之间无序列化开销

不像 Expo 那样保守等用户主动 opt-in；Keel 把 New Architecture 当产品特性——bundle 启动速度 / 性能比 Old Architecture RN bundle 优 30%+，是 Keel 相对于普通 RN 项目的卖点之一。

内部技术细节（开发者层面无感）

每个 KeelRuntimeHost 自带独立 Hermes runtime，跨实例 JS state 不互通。给 super-app / 多租户 / 上层应用 multi-bundle 并存场景开门。一般 RN 开发者用单实例就够，跟 Expo 行为一致。

第 2 层：CLI（@keel-ai/cli）

类比 npx expo / npx eas，但走国内 npm 镜像 + 中文界面默认。

npm install -g @keel-ai/cli

keel create my-app                  # 新项目（5 个 templates 选一）
keel start                          # 本地 dev server（metro + Keel Go 配对）
keel doctor                         # 检查环境（Node / Java / Xcode / iOS SDK 版本兼容）
keel install <pkg>                  # RN-aware 依赖安装（版本兼容性校验）
keel build ios                      # 触发云端 iOS 构建
keel build android                  # Android
keel build dev-client               # 构建项目的 Dev Client
keel publish <bundle>               # 推新 bundle（OTA: upload + promote）
keel submit ios --to=appstore       # iOS App Store 自动提审（路线图）
keel submit android --to=huawei     # 华为应用市场（路线图）

实现：Node 写的 CLI（npm 上分发），调用 Keel 后端的 HTTP API。本地不做构建，只打 tarball + 上传。

注：没有 keel build web / keel deploy --target=web——Keel 不做 web target（见顶部说明）。

第 3 层：Build

类比 EAS Build。云端构建服务。用户 keel build ios 触发：

1. CLI 把项目源码（带 package.json）打成 tarball，上传到 Build endpoint
2. 后端在阿里云 ECI / FC 起一个临时容器，pull 镜像（pre-installed metro + Hermes + iOS / Android toolchain）
3. 容器跑 metro bundle → hermesc → 平台对应的打包脚本
4. 产物（.ipa / .apk）落到 Keel 自营 OSS bucket
5. 给 CLI 回 download URL；CLI 拉到本地或者直接进 Update / Submit 流程

代码路径：keel/cloud/build-image/（metro + Dockerfile）+ keel/cloud/internal/cloudbuild/（Go 服务）+ keel/cloud/cmd/build-server/（HTTP 入口）。对外产品名是 KAS Build（KAS = Keel Application Services，云伞名）。

第 4 层：Update

类比 EAS Update。OTA 协议层 + 生产级分发基础设施一体。包含：

• 协议：manifest API + 客户端 SDK（TS / iOS Swift / Android Kotlin）
• 传输优化：bsdiff4 patch 增量更新
• 存储：bundle blob store（当前 LocalFS，阿里云 OSS / S3 规划中）
• 分发：CDN edge cache（规划中，阿里云 CDN）+ 自定义域名 + HTTPS
• 发布控制：channel（production / staging / development）+ 灰度（10%→50%→100%，规划中）+ 一键回滚（规划中）
• 监控：拉取成功率 / 延迟 / 错误率（规划中，飞书 / 钉钉告警）
• 可选推送（@keel-ai/push）：极光 / 个推，触发客户端立即拉新 bundle

自营，跟 Mortar 解耦：KAS Update 自管 manifest DB（PG / SQLite）+ 自营阿里云 OSS + 自营 CDN。不依赖 Mortar primitives。用户跑 KAS Update 不需要付 Mortar 账单。

代码路径：keel/cloud/internal/update/（Go 服务）+ keel/cloud/cmd/update-server/（HTTP 入口）+ keel/packages/updates/（@keel-ai/updates npm 包：TS + Swift + Kotlin 三套客户端实现）。

详见 update.md。

第 5 层：Submit

类比 EAS Submit。把 keel build 出的 ipa / apk 自动上传到应用市场提审。规划中。

支持目标：

• iOS：App Store Connect API
• Android 国内 5 大市场：华为 / 小米 / OPPO / vivo / 应用宝（每家 API 不同，按市场份额优先级实装）
• Android 国际：Google Play Console API（可选，海外用户）

每个市场审核机制不同，CLI 帮用户填写元数据（截图 / 描述 / 隐私政策），监控审核状态，审核失败时给反馈。

先打通 iOS App Store + 华为 + 小米 + OPPO 三家；vivo / 应用宝 后续。

详见 roadmap.md 的 Submit 一节。

Modules API（横向扩展，对位 Expo Modules API）

5 层之上的横向扩展——@keel-ai/modules-core 让 Keel 团队（或任何 RN 模块作者）写一个 Keel 模块发到 npm，consumer 项目 npm install + autolink 即可使用。对位 Expo Modules API（声明式 spec + native iOS/Android + TS bindings 一起打包），但不依赖 expo runtime。

平铺分发模型

跟 Expo 一样无 tier 层级。两类产物从本仓库出：

无论是 Keel 自己的 Keel Go tester、还是 Fabric 的 host shell、还是第三方 RN 项目，都走同一条 autolink 路径——根据 host package.json 里声明的依赖决定哪些 native 模块进 binary。没有”SDK 内嵌的特殊模块”——除了 KeelRuntimeHost 这一个核心 runtime 之外，每个能力都是独立 npm 包（包括 OTA Update，见 @keel-ai/updates）。

下游 app 如果要 gate AI bundle 能 import 哪些模块，在自己一侧维护 allowlist——Keel 不内置 tier 来支持这种 gating。

module.yml 声明

name: keel-module-wechat
platforms: [ios, android]
ios:    { pod: KeelModuleWeChat,    min_ios: "13.0" }
android: { aar: keel-module-wechat,  min_sdk: 23 }
js:     { entry: ./src/index.ts }
peer_runtime: "^1.0.0"

当前 Keel 官方模块

按职能分布在三个顶层目录：feature 包在 keel/packages/、vendor 模块在 keel/modules/、开发辅助在 keel/tools/。

Platform utilities —— keel/packages/（对位 expo-* 平台元数据 + OTA）：

• @keel-ai/application — app 元数据（bundle ID / 名字 / 版本 / 构建号）
• @keel-ai/constants — runtime 常量（status bar 高度 / 平台标识 / 模拟器检测）
• @keel-ai/device — 设备信息（型号 / 制造商 / OS 名 + 版本）
• @keel-ai/asset — bundle asset 解析 + 远程 asset 缓存下载
• @keel-ai/font — 运行时自定义字体注册
• @keel-ai/updates — OTA bundle 分发客户端（manifest + bsdiff + channel + 回滚），对位 expo-updates。三套并行实现：TS（JS 侧自更新）、Swift（iOS host shell native launcher）、Kotlin（Android）

China-first vendor 集成 —— keel/modules/（国内 RN 模块洼地，由 create-keel-module scaffold 出来）：

• keel-module-wechat — 微信支付 / 登录 / 分享 / 跳小程序
• keel-module-alipay — 支付宝支付 / 实名 / 小程序跳转
• keel-module-amap — 高德地图 / 定位 / 路径规划
• keel-module-push — 推送抽象层（极光 + 个推 backend）
• keel-module-umeng — 友盟统计

Auth providers —— @keel-ai/apple-signin / @keel-ai/google-signin（原生、React-free SPM，在 keel/packages/，作为默认 kernel 被 @keel-ai/keel pull；2026-06-03 从 modules/ 迁入）/ @keel-ai/auth-session（纯 TS，在 keel/packages/）

App framework —— keel/packages/：@keel-ai/router（基于 file-system routing，对位 expo-router）。配套编译插件 router-metro-plugin 在 keel/tools/

开发辅助 —— keel/tools/：bundle-atlas（bundle 内容审计）/ create-keel-project / create-keel-module

CLI

# 脚手架在独立的 create-keel-module 包里(Expo 模式)
npm create keel-module <name>

# modules-core 的 keel-module CLI 只做 daily-dev
keel-module validate          # 校验 module.yml + sources
keel-module link              # 加进 host app 的 package.json + emit autolink snippet
keel-module install           # 把 snippet 写进 Podfile / settings.gradle.kts（幂等）
keel-module test              # run module tests in a minimal host-app context
keel-module publish           # validate + bump version + npm publish

详见 modules-core/README.md。

配套：Keel Go + Dev Client

Keel Go

跟 Expo Go 同套用法：开发者上 App Store / 国内 5 大市场下载 Keel Go free app；扫码 / 粘 URL 加载任意 Keel bundle。

• 能跑什么：Keel Go 自己 package.json 编译期声明的 Keel 模块，binary 里就有哪些；bundle 只用这些就开箱即用
• 优点：零配置，5 分钟内能在真机上看到效果

Dev Client

keel build dev-client 给项目自动生成一个 sideload-able tester app：

• 包含项目所有 native 模块（package.json 里的 + 自动 autolink 的）
• iOS：sideload 到测试机 / TestFlight 分发
• Android：sideload .apk / 国内市场 enterprise 分发

类比 Expo Dev Client。用途：项目用的 native 模块超出了 Keel Go binary 已链接的范围时，Dev Client 重新 link 一份包含本项目所需 native 模块的 tester。

跟 Mortar 的关系（完全解耦，没有依赖）

Keel 跟 Mortar 没有特殊集成——Mortar 只是众多 BaaS 选项之一：

• 默认不 bundle：Keel SDK 不自动注入 Mortar 客户端
• 没有 @keel-ai/mortar 这种 plugin 包：用户接 Mortar 走标准 Mortar SDK（npm install @mortar/client），跟接 Supabase 走 @supabase/supabase-js、接 Firebase 走 firebase 是同一种方式
• 使用：

// 自家后端:
fetch('/api/todos');

// Mortar:
import { mortar } from '@mortar/client';
mortar.from('todos').select(...);

// Supabase / Firebase / ...:
import { createClient } from '@supabase/supabase-js';
// 三方都 OK，互不冲突

为什么彻底解耦：

• 让 Keel 用户不被迫接受 Mortar（接 Supabase / 自家后端 / Firebase 都行）
• 让 Mortar 用户不被迫用 Keel（接任何 RN / web / native，包括 Expo）
• 两边各自能独立卖给非交叉客户，不互相反向引用
• Mortar 文档里不出现 Keel；Keel 文档里只把 Mortar 当”众多 BaaS 选项之一”提一句
• 内部 dogfood：appunvs 走标准接入路径，不开后门

内部技术（不在产品 marketing 表面）

• per-instance Hermes：每个 KeelRuntimeHost 一个独立 Hermes runtime（不是共享 + 隔离 context；是真独立 runtime）。给 super-app / 多 bundle 共存场景开门
• SDK ABI 版本：keel/version.json 的 sdk_version 字段；新增 / 移除 / 改签 native 公开 API = bump

演进路径

详见 roadmap.md。当前进度：

• 已上线：SDK + Build ✅ 已实装
• 进行中：CLI + 文档站 + Update（OTA 协议 + 客户端 SDK 三端）✅ 完成；Update production 化（CDN / 自定义域名 / 灰度 / 监控）+ App Router + Keel Go + Open Governance 待做
• 规划中：Modules API + Dev Client + 5 China 模块 + @keel-ai/push + Submit（含国内 5 大 Android 市场）
• 后续：Bundle Atlas + VS Code 扩展 + 监控 dashboard 等开发者工具
• 后续：企业版（cross-cutting：私有部署 / SSO / audit log / SLA）

治理 + 开源

Keel 是 Apache 2.0 开源项目。详见 governance.md。

• 公开 GitHub 仓库 + RFC 流程
• 公开 roadmap
• 商业服务（Pro / Team / Enterprise）卖的是托管 + SLA + 一等运营，不阉割开源功能