4

proto/README.md

@@ -0,0 +1,79 @@
+# 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**
+```bash
+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）**
+```bash
+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**
+```bash
+protoc \
+  --proto_path=proto \
+  --java_out=out/java --grpc-java_out=out/java \
+  contract/v1/contract.proto
+```
+
+**Go**（已配置在 `scripts/genproto.ps1`，无需手动）
+```powershell
+.\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. 通知各语言使用方按上面的命令重新生成