|
1 | 1 | # airgate-sdk — Claude 开发指南 |
2 | 2 |
|
3 | | -> 叠加在 monorepo 根 `../CLAUDE.md` 之上。SDK 是 core 与所有插件之间的**契约层**,改动影响面最大,务必先读「🚫 红线」。 |
| 3 | +> 叠加于根 `../CLAUDE.md`。SDK 为 core 与全部插件之间的**契约层**,改动影响面最大,先读「🚫 红线」。 |
4 | 4 | > 生态边界依据见 `../airgate-core/docs/architecture/ecosystem-v2.md`。 |
5 | 5 |
|
6 | 6 | ## 🚫 红线 |
7 | 7 |
|
8 | | -- **不要把 core 的产品逻辑塞进 SDK**。SDK 只放:协议 ABI、插件接口、运行时桥、devkit、前端 theme。用户/账号/计费/调度等业务是 **core** 的事(这是 ecosystem-v2 明确的边界审计结论)。 |
9 | | -- **`protocol/proto/` 是 ABI**:改了必须 `make proto` 重新生成并提交 `*.pb.go`;**保持向后兼容**(字段只增不改不删、不复用 tag 号)。破坏性变更会同时打挂 core 与所有插件。 |
10 | | -- **`sdkgo/` 的插件接口是公共 API**:`GatewayPlugin`/`ExtensionPlugin`/`MiddlewarePlugin`/`宿主能力` 签名变更属于破坏性变更,需同步评估所有插件仓。 |
| 8 | +- **勿将 core 产品逻辑写入 SDK**。SDK 仅放协议 ABI、插件接口、运行时桥、devkit、前端 theme;用户/账号/计费/调度等业务归 **core**(ecosystem-v2 边界审计结论)。 |
| 9 | +- **`protocol/proto/` 为 ABI**:改后须 `make proto` 重新生成并提交 `*.pb.go`,并保持向后兼容(字段只增不改不删、不复用 tag 号);破坏性变更将打挂 core 与全部插件。 |
| 10 | +- **`sdkgo/` 插件接口为公共 API**:`GatewayPlugin`/`ExtensionPlugin`/`MiddlewarePlugin`/宿主能力 签名变更属破坏性变更,须同步评估全部插件仓。 |
11 | 11 | - 改 `theme/` 后 `make theme`,提交生成的 `dist`/devserver CSS。 |
12 | 12 | - 生成代码(`*.pb.go`、theme `dist`)不可手改。 |
13 | 13 |
|
|
16 | 16 | | 目录 | 角色 | |
17 | 17 | |---|---| |
18 | 18 | | `protocol/proto/` | gRPC 协议定义 = ABI(core ↔ 插件) | |
19 | | -| `sdkgo/` | Go 插件接口:`gateway.go` / `extension.go` / `capability.go` / `event.go` / `errors.go` 等 | |
20 | | -| `runtimego/grpc/` | 插件运行时桥(把 Go 实现接到 gRPC) | |
| 19 | +| `sdkgo/` | Go 插件接口:`gateway.go` / `extension.go` / `capability.go` / `event.go` / `errors.go` | |
| 20 | +| `runtimego/grpc/` | 插件运行时桥(Go 实现接入 gRPC) | |
21 | 21 | | `devkit/devserver/` | 插件脱离 core 的独立调试服务 | |
22 | 22 | | `theme/` | 前端主题包 `@doudou-start/airgate-theme` + devserver theme.css | |
23 | 23 |
|
24 | | -## 命令(从 `airgate-sdk/`) |
| 24 | +## 命令(`airgate-sdk/`) |
25 | 25 |
|
26 | 26 | ```bash |
27 | 27 | make proto # 改 proto 后重新生成(装固定版本 protoc) |
28 | 28 | make proto-check # 校验 proto 生成代码无漂移 |
29 | 29 | make theme # 构建 theme 包 + devserver theme.css |
30 | | -make test # 带 race + coverage 的 Go 测试 |
31 | | -make ci # 完整 CI:lint+test+vet+build+proto-check+theme-check |
| 30 | +make test # Go 测试(race + coverage) |
| 31 | +make ci # 完整 CI:lint + test + vet + build + proto-check + theme-check |
32 | 32 | ``` |
33 | 33 |
|
34 | | -提交前跑 `make ci`,proto/theme 的漂移检查在这里把关。 |
| 34 | +提交前运行 `make ci`,proto/theme 漂移检查在此把关。 |
0 commit comments