# 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. 通知各语言使用方按上面的命令重新生成