协议与生成

契约先行

在 grpc-kit 中，Proto 定义消息与 RPC 服务，Gateway YAML 定义 HTTP 映射，OpenAPI YAML 描述文档和方法标签。它们共同决定 Go、HTTP 与 MCP AutoBridge 的接口形态。

公共契约位于 api 仓库；生成后的公共 Go API 位于 pkg 的 api 目录。业务契约位于 CLI 生成应用的 api/<产品>/<服务>/<版本> 下。不要直接修改生成代码。

应用生成流程

1. 修改 Proto 消息、服务与对应 Gateway/OpenAPI 配置。
2. 检查 package、go_package、RPC selector 与 HTTP 路径一致。
3. 使用项目固定的 protoc、插件和 include 来源执行 make generate。
4. 审查 Proto、Go、Gateway、Swagger 与依赖变化，运行 make test 和 make build。
5. 启动服务执行黑盒 E2E；若标记 MCP tag，另外验证工具列表、授权和错误转换。

添加模型时修改 modeler/ent/schema，ent 输出同样通过生成更新。参见代码维护边界。

跨仓库生成边界

api 仓库 Makefile 使用 GOPATH 路径，并把部分生成文件和 OpenAPI 资产写入 pkg checkout。执行前确认目录与 branch，执行后审查两个仓库的 diff；不是只提交 api 即可完成同步。该 Makefile 未独立提供完整工具版本锁定，应在验证记录中保存实际 protoc/插件版本。

本轮快照中 pkg 存在 actions.pb.go，但 api 树中未找到对应 actions.proto。这属于待核对的生成来源差异，不应删除或手工修补生成代码以消除差异；维护者需先定位历史来源和兼容要求。

版本依据见版本与兼容，消息演进见Proto3 约定。

来源：api Makefile、应用生成脚本。