goaiapi — 插件化 AI API 中继

一个一切皆插件的 AI API 流量中继。内核只是加载器：负责启动插件、版本管理、依赖解析、插件互调与动态加载/更新。中继的全部业务能力（反向代理转发、用量解析、留存、管理界面）都由独立进程插件实现，经内核 InvocationBroker 用 gRPC 互相调用。

设计要点

进程隔离插件：每个插件是独立二进制，经 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、编译内核与全部插件）：

.\scripts\build.ps1

运行（内核默认监听 :8080 收流量、:8082 控制端口，自动加载 build/plugins/ 下的插件）：

.\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）。

3.7 KiB Raw Blame History Unescape Escape