4

README.md

@@ -0,0 +1,74 @@
+# goaiapi — 插件化 AI API 中继
+
+一个**一切皆插件**的 AI API 流量中继。内核只是加载器：负责启动插件、版本管理、依赖解析、插件互调与动态加载/更新。中继的全部业务能力（反向代理转发、用量解析、留存、管理界面）都由独立进程插件实现，经内核 InvocationBroker 用 gRPC 互相调用。
+
+## 设计要点
+
+- **进程隔离插件**：每个插件是独立二进制，经 [hashicorp/go-plugin](https://github.com/hashicorp/go-plugin) 用 gRPC 与内核通信。插件崩溃不会拖垮内核。
+- **内核中转互调**：插件之间从不直连。A 调 B 时，A → 内核 Broker → B，请求/响应是 proto-wire 字节，内核不感知任何插件的具体类型。
+- **三层插件**（由内核依据依赖图复算校验，不信插件自报）：
+  - **base**：无插件依赖（如 `echo-base`、`recorder-base`、`usage-base`）
+  - **mid**：仅依赖 base（如 `transform-mid`、`dashboard`）
+  - **complex**：依赖至少一个非 base（如 `proxy`、`streaming-demo`）
+- **版本管理**：依赖用 semver 约束声明，内核加载时校验已注册版本是否满足，并支持热升级（原子换 + 旧进程延迟排空）。
+- **流量路径**：外部 HTTP（默认 `:8080`）→ 内核 → Broker → `proxy` 插件 → 上游；`proxy` 再经 Broker 调 `usage-base` 解析、`recorder-base` 留存。
+
+## 目录结构
+
+| 目录 | 说明 |
+|---|---|
+| `proto/` | **语言中立的 API 契约源**（`contract.proto`）。其它语言从此生成客户端 |
+| `src/` | 全部源码（见 `src/go/`） |
+| `scripts/` | 构建与代码生成脚本（`build.ps1`、`genproto.ps1`） |
+| `build/` | 编译产物（`relay.exe` + `plugins/`）与运行数据。**不入库** |
+| `tools/` | 预留的本地工具目录（当前为空） |
+
+每个一级子目录另有自己的 README。跨语言接入本系统，先看 `proto/README.md`。
+
+## 快速开始
+
+构建（生成 proto、编译内核与全部插件）：
+
+```powershell
+.\scripts\build.ps1
+```
+
+运行（内核默认监听 `:8080` 收流量、`:8082` 控制端口，自动加载 `build/plugins/` 下的插件）：
+
+```powershell
+.\build\relay.exe -u https://your-upstream.example.com
+```
+
+内核入口的命令行参数（见 `src/go/cmd/relay/main.go`）：
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `-l` | `127.0.0.1:8080` | 外部流量监听地址 |
+| `-pd` | `build/plugins` | 插件目录（扫描 `*.exe` 自动加载；空字符串则不自动加载） |
+| `-pa` | `127.0.0.1:0` | 内核 Broker gRPC 地址（`:0` = 随机端口） |
+| `-ca` | `127.0.0.1:8082` | 插件管理控制端口（空字符串关闭） |
+| `-proxy` | `proxy` | 处理外部流量的代理插件名 |
+| `-drain` | `5000` | 热升级时旧插件进程排空等待毫秒数 |
+
+> 上游地址（`-u`）等参数由 `proxy` 插件接收。
+
+## 控制端口 API（默认 `:8082`）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/plugins` | 列出已加载插件 |
+| GET | `/api/plugins/{name}` | 单个插件详情 |
+| POST | `/api/plugins/load` | `{"binary_path"}` 加载注册 |
+| POST | `/api/plugins/unload` | `{"name"}` 卸载（被依赖则拒绝） |
+| POST | `/api/plugins/upgrade` | `{"name","binary_path"}` 热升级 |
+
+## 工具链
+
+构建依赖外部工具链（不在 PATH 上时脚本内已硬编码路径，按本机实际调整）：
+
+- Go 1.26.3
+- protoc + `protoc-gen-go` / `protoc-gen-go-grpc`（仅在改 `contract.proto` 时需要；生成代码已入库）
+
+## 主要依赖
+
+`github.com/hashicorp/go-plugin`（插件进程框架）、`google.golang.org/grpc`（互调传输）、`github.com/Masterminds/semver/v3`（版本约束）、`modernc.org/sqlite`（留存索引，纯 Go 无需 CGO）。