goaiapi/proto/README.md

proto — 跨语言 API 契约

本目录是系统的语言中立契约源。contract.proto 定义了内核与插件之间、以及外部系统与本系统交互所需的全部 gRPC 服务与消息。任何语言都可以从这里生成客户端/服务端代码来接入本系统。

proto/
  contract/v1/contract.proto   契约源（唯一可信来源）

Go 生成代码位于 src/go/proto/contract/v1/（已入库，克隆即可 go build）。其它语言的生成代码不入库，由各使用方按需生成。

契约内容

contract.v1 package 定义：

通用服务（每个插件都实现）

• PluginManifest — GetManifest、HealthCheck
• InvocationBroker — Invoke（内核托管，插件互调入口）、ListPlugins

枚举与基础消息

• PluginTier — BASE / MID / COMPLEX
• Dependency、Capability、PluginInfo、TrafficEntry、UsageInfo

业务服务（由插件实现）

• EchoService、TransformService、StreamingDemo — 样例（验证三层与流式）
• RecorderService — 留存与查询（Save/List/ReadBlob/Stats）
• UsageService — 用量解析（ParseBody/ParseStream）
• ProxyService — 外部流量处理入口（Handle）
• DashboardService — 只读管理界面渲染（Render）

跨语言生成示例

先确保安装了 protoc 及对应语言插件，然后从仓库根目录执行（--proto_path 指向本目录）。

Python

python -m grpc_tools.protoc \
  --proto_path=proto \
  --python_out=out/python --grpc_python_out=out/python \
  contract/v1/contract.proto

TypeScript / JavaScript（ts-proto）

protoc \
  --proto_path=proto \
  --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=out/ts \
  contract/v1/contract.proto

Java

protoc \
  --proto_path=proto \
  --java_out=out/java --grpc-java_out=out/java \
  contract/v1/contract.proto

Go（已配置在 scripts/genproto.ps1，无需手动）

.\scripts\genproto.ps1   # 从 proto/ 生成到 src/go/proto/

互调约定

插件间调用全部经内核 InvocationBroker.Invoke：

• target_plugin — 目标插件名（如 "echo-base"）
• method — gRPC 方法全路径（如 "/contract.v1.EchoService/Echo"）
• payload — 目标请求消息的 proto-wire 字节（用本契约生成的类型序列化）

返回的 result 是目标响应消息的 proto-wire 字节，用同一契约反序列化即可。内核不感知具体类型，只透传字节——这正是契约必须语言中立、独立存在的原因。

修改契约

改 contract.proto 后：

1. 重新生成 Go 代码：.\scripts\genproto.ps1
2. 提交更新后的 proto/contract/v1/contract.proto 与 src/go/proto/contract/v1/*.pb.go
3. 通知各语言使用方按上面的命令重新生成