Keel 源码模块关系归档

Keel 仓内全部源码模块 + 各模块的责任 / 依赖 / 产出物。归档目的：人 / AI 接手时一眼看清每个目录是干什么的、产物给谁用。

同名歧义提醒：keel/docs/modules.md 说的是 Keel 维护的 5 个国内一等 npm 模块（微信 / 支付宝 / 高德 / 极光 / 友盟）。本文说的是 Keel 仓内自己的代码模块（source/ + packages/* + cli/ + cloud/ 等）。

0. 一图看全

┌─────────────────────────────────────────────────────────────────────────┐
│                       Keel 源码模块拓扑                                 │
└─────────────────────────────────────────────────────────────────────────┘

【ship binaries】
   keel/build/ios/Keel.xcframework      ← packaging/build-ios.sh
   keel/build/android/keel-sdk.aar      ← packaging/build-android.sh
   appunvs/cloud-build-mobile:latest (Docker)  ← cloud/packaging/build-cloud-build.sh
   keel/go/build/{ios.ipa,android.aab}  ← packaging/build-keel-go.sh

【消费这些产物的下游】
   host apps             ←  Keel.xcframework / keel-sdk.aar
   Keel Go tester app    ←  Keel.xcframework / keel-sdk.aar
   build orchestrators   ←  appunvs/cloud-build-mobile:latest (via DockerBuilder)

────────────────────────────────────────────────────────────────────────────

【源码模块】顶层目录直接对应职能分类。

🟦 1. SDK 二进制源 (`sdk/`)         ← @keel-ai/keel umbrella + Keel.xcframework / keel-sdk.aar
   sdk/
   ├─ package.json                  npm: @keel-ai/keel
   ├─ Keel.podspec                  iOS autolinking entry
   ├─ react-native.config.js        Android sourceDir → android/keel-sdk
   ├─ ios/Keel/
   │  ├─ Keel.h / Keel.mm           ObjC++ 头 + 桥
   │  ├─ KeelView.swift             开放基类 (host shell subclass it)
   │  ├─ KeelHostModule.mm          HostBridge native impl
   │  └─ KeelJSIInstall.{h,mm}      bootstraps __keel namespace per Hermes runtime
   ├─ android/
   │  ├─ settings.gradle            standalone gradle root (publishToMavenLocal)
   │  └─ keel-sdk/
   │     ├─ build.gradle            srcDirs += [../../modules-core/android/src/main/java]
   │     ├─ src/main/cpp/CMakeLists.txt    builds libkeel.so (pulls modules-core/cpp/)
   │     └─ src/main/java/com/appunvs/keel/   KeelView.kt / KeelHostModule.kt / KeelJSI.kt
   └─ src/index.ts                  TS surface (KeelSDK.isAvailable())

   产出: Keel.xcframework / keel-sdk.aar / @keel-ai/keel npm
   消费者: host apps, Keel Go, Keel Gallery

🟦 2. Module framework (`modules-core/`)   ← @keel-ai/modules-core + Swift Macros + Kotlin KSP
   modules-core/
   ├─ cpp/                          KeelJSIBinding + KeelMarshal (cross-platform C++)
   ├─ ios/KeelModuleCore/           Swift KeelModule base + KeelInstallContext
   ├─ android/                      Kotlin runtime, included into keel-sdk.aar via srcDirs
   ├─ android-ksp/
   │  ├─ keel-annotations/          @KeelModule + @Constant + @AsyncFunction
   │  └─ keel-ksp/                  SymbolProcessor: emits <Class>_KeelGenerated.kt
   ├─ macros/                       SwiftPM CompilerPlugin
   │  ├─ KeelMacros (declarations)
   │  ├─ KeelMacrosImpl (SwiftSyntax)
   │  └─ KeelTSGen (CLI: @KeelModule sources → __keel.d.ts)
   ├─ src/                          TS surface (requireKeelModule + defineAsyncMethods)
   ├─ src/cli.ts                    keel-module install / link / test / publish
   └─ templates/                    create-keel-module 模板源

   产出: @keel-ai/modules-core npm + KeelModuleCore pod + 嵌入 keel-sdk.aar
   消费者: 所有 @keel-ai/* feature 包 + 所有 keel-module-* vendor 包

🟦 3. Feature packages (`packages/<name>/`)   ← @keel-ai/* Expo-style 平台能力
   (note: `@keel-ai/keel` umbrella + `@keel-ai/modules-core` 已搬出 packages/，
    分别在顶层 sdk/ 和 modules-core/。packages/ 现在只放 feature 包。)
   ├─ application/   bundle metadata
   ├─ asset/         remote asset cache
   ├─ apple-signin / google-signin / auth-session
   ├─ constants/     status bar / platform / simulator
   ├─ device/        model / manufacturer / OS
   ├─ font/          runtime font registration
   ├─ router/ + router-metro-plugin/   file-based routing
   └─ updates/       OTA client (TS + Swift + Kotlin 并行实现)

   产出: 每个一个 npm 包 + podspec / aar (RN autolink)
   集成: host app `yarn add @keel-ai/<name>`

🟦 4. Vendor modules (`modules/<name>/`)   ← create-keel-module 产出的国内一等模块
   ├─ keel-module-alipay/   支付宝
   ├─ keel-module-amap/     高德地图
   ├─ keel-module-push/     极光 + 个推抽象层
   ├─ keel-module-umeng/    友盟统计
   └─ keel-module-wechat/   微信支付 / 登录 / 分享

   每个都用 @KeelModule + @AsyncFunction (KSP/Macros 驱动)，模板化产出。
   `modules/` 只放 `create-keel-module` scaffolder 的输出形态。

🟦 5. End-user apps (`apps/<name>/`)   ← create-keel-project 产出的 app
   └─ keel-gallery/    从 blank template scaffold 出来，演示典型 Keel app 结构

   `apps/` 严格只放 `create-keel-project` 产出形态的 app。

🟦 6. Tools (`tools/`)                  ← scaffolders + dev tools
   ├─ create-keel-project/                 `npm create keel-project my-app`
   ├─ create-keel-module/              `npm create keel-module my-mod`
   ├─ bundle-atlas/                    bundle 内部可视化
   └─ router-metro-plugin/             build-time route discovery（编译插件）

🟦 2. CLI (`cli/`, npm publishable `@keel-ai/cli`)
   └─ cli/
      ├─ src/commands/
      │  ├─ build.ts              远端 Cloud Build 触发
      │  ├─ doctor.ts             env 自检
      │  ├─ manifest.ts           查 / 改远端 manifest
      │  ├─ publish.ts            上传 bundle → Update server
      │  ├─ rollback.ts           rotate "current" pointer
      │  ├─ start.ts              本地 dev server (metro + QR for Keel Go)
      │  ├─ submit.ts             Submit 5+2 市场
      │  ├─ dev-client.ts         Dev Client (V1 scaffold; V1.5 实拨)
      │  ├─ install.ts            RN-aware npm install
      │  ├─ login.ts / logout 
      │  └─ stubs.ts              native module 的 stub 生成
      ├─ src/api/                 Update / CloudBuild HTTP clients
      └─ src/util/

   产出: bin/keel (npm bin)
   依赖: HTTP 调 Update server + Cloud Build server
   消费者: 终端 RN 开发者

🟧 3. Cloud Build (`cloud/`)
   ├─ cloud/build-image/         Docker 构建上下文
   │  ├─ Dockerfile
   │  ├─ build-bundle.sh
   │  ├─ metro.config.js
   │  └─ fixture-rn/
   ├─ cloud/cmd/build-server/   HTTP 入口
   └─ cloud/internal/cloudbuild/      job queue, runner, artifact

   产出: appunvs/cloud-build-mobile:latest Docker image + keel-build-server
   消费者: keel/cli/src/commands/build.ts

🟧 4. Update (`cloud/`)
   ├─ cloud/cmd/update-server/   HTTP 入口
   └─ cloud/internal/update/     manifest / patch / rollout / blob / monitoring

   产出: keel-update-server
   依赖: SQLite (默认) / Postgres + S3-compat (含阿里云 OSS) + CDN
   消费者: Keel runtime + keel cli publish/rollback

🟧 5. Submit (`cloud/internal/submit/`)
   ├─ submit.go + registry_test.go
   └─ drivers/{appstore,googleplay,huawei,xiaomi,oppo,vivo,yyb}/

   产出: 库 (无独立 binary, 通过 cli `keel submit` 触发)

🟧 Push 服务端 (`cloud/cmd/push-server/`)
   极光 + 个推 dispatcher。

🟪 配套：Keel Go (tester app)
   └─ go/
      ├─ src/{App,HomeScreen,PreviewScreen,NativeKeelView,ScannerOverlay,recents}.tsx
      ├─ ios/                     Xcode project (links Keel.xcframework)
      └─ android/                 Gradle project (links keel-sdk.aar)

   产出: KeelGo.ipa + keel-go.aab
   消费者: 终端 RN 开发者

🟪 配套：Keel Snack (浏览器 playground)
   └─ snack/
      Next.js + Monaco 编辑器 + RN Web fallback（importmap → esm.sh RN Web，
      浏览器内 Babel 转 TS+JSX，zero-server）

🟪 Examples
   └─ apps/examples/0[1-5]-* (5 个端到端示例)

🟫 共用底层 (`cloud/internal/`)
   ├─ keelauth/                  API key / OIDC SSO / RBAC / 审计日志
   └─ billing/                   订阅 / 套餐 + 微信支付 / 支付宝

🟫 文档 (`docs/`)
   ├─ architecture.md            5 层产品总览
   ├─ source-modules.md          👈 本文
   ├─ modules.md                 5 个一等 npm module spec
   ├─ deployment-sop.md          自建实例运维手册
   ├─ deployment.md              部署架构总览
   ├─ enterprise-distribution.md 私有渠道方案
   ├─ update.md / submit.md / build.md
   ├─ governance.md / roadmap.md / pricing.md
   ├─ tutorial.md                从零到上架教程
   ├─ examples.md / keel-go.md / snack.md
   ├─ custom-domain.md / github-actions.md / source-modules.md
   └─ ...

🟫 Packaging (`packaging/`)
   ├─ build-ios.sh               产 Keel.xcframework（操作 source/）
   ├─ build-android.sh           产 keel-sdk.aar（操作 source/）
   ├─ build-fixture.sh           产 RuntimeRoot.jsbundle
   ├─ release.sh                 一键收集 release 物料
   └─ build-keel-go.sh           产 KeelGo ipa + aab

🟫 Site (`site/`)
   Astro 4 marketing site + i18n（zh 默认 / en 在 /en/）

🟫 Deploy (`cloud/deploy/helm/keel/`)
   Helm chart：update-server + build-server + push-server

1. 各模块 SLA / 接口稳定性等级

模块	公开 API	兼容承诺
Native SDK	native class names (KeelView 等)	semver；breaking 改动需 major bump
CLI (`@keel-ai/cli`)	命令行 + flag 表	semver；命令重命名要保留 alias 1 个 minor
Update server	REST endpoints (`/v1/{project}/...`)	加 endpoint 自由；改 schema 要 v1→v2
Open Monitoring API	`/v1/monitoring/{health,metrics,diagnostics}`	固定 JSON schema，加字段自由，改 / 删要 major
Submit drivers	内部接口 `Submitter`	内部 unstable；CLI flags 是公开面
Cloud Build	HTTP REST (`POST /jobs`)	同 Update server
Keel Go	UX	不算公开 API；终端用户体验

2. 依赖图（编译时 + 运行时）

                           host shell / Keel Go
                                      ↓ embeds
                                Keel SDK binary
                                ↑           ↓ runtime fetch
                      ┌─────────┴───┐   ┌───┴────────┐
                      │ Cloud Build  │  │  Update    │
                      │   server     │  │  server    │
                      └──────┬───────┘  └────┬───────┘
                             ↓ artifact      ↓ blob
                       ┌─────┴──────────────┴─────┐
                       │  OSS / S3 + CDN          │
                       └──────────────────────────┘
                                   ↑ submit upload
                            ┌──────┴────────┐
                            │ Submit drivers│
                            └────────────────┘
                                   ↑
                            (CLI `keel submit ...`)

3. 谁可以独立替换 / 拆出去

模块	独立性	备注
SDK (`sdk/`)	❌	KeelView ABI 绑了 host bridge；改了所有消费者得重编
Module framework (`modules-core/`)	❌	所有 `@keel-ai/` feature 包 + 所有 `keel-module-` 都依赖；改 install API 是 ABI 事件
Feature packages (`packages/<name>/`)	✅	每个 npm 包独立 semver，可单独发版
Vendor modules (`modules/keel-module-*/`)	✅	每个独立 npm 包；scaffolder 产出形态
CLI (`cli/`)	✅	纯 npm 包，可单独发版
create-keel-project / -module (`tools/`)	✅	独立 npm 包，自带 templates
Update server (`cloud/cmd/update-server`)	✅	独立 Go 服务 + 独立 DB
Cloud Build server	✅	独立 Go 服务 + Docker daemon
Push server	✅	独立 Go 服务，前置极光 / 个推
Submit drivers	✅	每个 driver 独立 package
Keel Go (`go/`)	✅	独立 RN 项目；只 consume SDK 二进制
Keel Snack (`snack/`)	✅	独立 Next.js web app

4. 命名歧义对照表

文件 / 概念	说什么
`keel/docs/modules.md`	Keel 维护的 5 个一等 npm module 的 spec（微信 / 支付宝 / 高德 / 极光 / 友盟）
`keel/docs/source-modules.md`	本文：Keel 仓内自己的代码模块拓扑
`keel/sdk/`	SDK 源码（iOS Swift + Android Kotlin + JNI）→ Keel.xcframework / keel-sdk.aar
`keel/modules-core/`	Module framework：Swift Macros + KSP + KeelModule 基类 + KeelInstallContext + 跨平台 JSI 桥
`keel/modules/`	`create-keel-module` 产出的国内一等模块（alipay/amap/push/umeng/wechat）
`keel/packages/<name>/`	`@keel-ai/*` feature 包（constants/device/font/router/updates/…）
`keel/apps/<name>/`	`create-keel-project` 产出的端用户 app（目前只有 keel-gallery）
`keel/go/` / `keel/snack/`	平台第一方 tester app（RN）+ playground（Next.js）
`@keel-ai/keel` (npm)	用户安装的主库 umbrella（`import { KeelSDK } from '@keel-ai/keel'`），源码在 `keel/sdk/`
`Keel.xcframework` / `keel-sdk.aar`	host app 嵌入的 native 二进制 SDK artifact

修改本文

修改本文 = 修改架构事实。改之前请同步更新：

architecture.md 的 5 层图
../README.md 的”5 层产品”段