Croupier API 文档

// Agent 注册请求
message RegisterRequest {
  string agent_id = 1;              // Agent 唯一 ID
  string version = 2;               // Agent 版本
  repeated FunctionDescriptor functions = 3;  // 函数列表
  string rpc_addr = 4;              // Agent 可达 gRPC 地址
  string game_id = 5;               // 游戏 ID (多租户必需)
  string env = 6;                   // 环境 (prod/stage/test)
  repeated AgentProcess processes = 7;  // 注册的进程
}

// Agent 注册响应
message RegisterResponse {
  string session_id = 1;            // 会话 ID
  int64 expire_at = 2;              // 过期时间 (Unix 秒)
}

// 心跳请求
message HeartbeatRequest {
  string agent_id = 1;
  string session_id = 2;
}

// Provider 能力注册
message RegisterCapabilitiesRequest {
  ProviderMeta provider = 1;        // Provider 元信息
  bytes manifest_json_gz = 2;       // Gzip 压缩的 manifest.json
}

// 函数描述符（包含 UI/RBAC 元数据）
message FunctionDescriptor {
  string id = 1;                   // 函数 ID，如 "player.ban"
  string version = 2;              // SemVer，如 "1.2.0"
  string category = 3;             // 分组类别
  string risk = 4;                 // 风险级别: low/medium/high
  string entity = 5;               // 实体类型，如 "player"
  string operation = 6;            // 操作类型: create/read/update/delete
  bool enabled = 7;                // 是否启用

  // UI/i18n/权限元数据
  croupier.common.v1.I18nText display_name = 20;
  croupier.common.v1.I18nText summary = 21;
  repeated string tags = 22;
  croupier.common.v1.Menu menu = 23;
  croupier.common.v1.PermissionSpec permissions = 24;
}

// 函数调用请求
message InvokeRequest {
  string function_id = 1;           // 函数 ID
  string idempotency_key = 2;       // 幂等键（可选）
  bytes payload = 3;                // 请求载荷 (JSON/Proto)
  map<string, string> metadata = 4; // 元数据
}

// 函数调用响应
message InvokeResponse {
  bytes payload = 1;                // 响应载荷
}

// 作业事件
message JobEvent {
  string type = 1;                  // 事件类型: progress/log/done/error
  string message = 2;               // 消息内容
  int32 progress = 3;              // 进度 0-100 (type=progress 时)
  bytes payload = 4;               // 最终结果 (type=done 时)
}

message GetJobResultRequest {
  string job_id = 1;
}

message GetJobResultResponse {
  string state = 1;      // 作业状态
  bytes payload = 2;     // 结果载荷
  string error = 3;      // 错误信息
}

message I18nText {
  string en = 1;  // 英文
  string zh = 2; // 中文
}

message Menu {
  string section = 1;   // 菜单分区
  string group = 2;     // 菜单分组
  string path = 3;      // 路由路径
  int32 order = 4;      // 排序
  string icon = 5;      // 图标
  string badge = 6;     // 徽章
  bool hidden = 7;      // 是否隐藏
}

message PermissionSpec {
  repeated string verbs = 1;           // 权限动词: read/invoke/write
  repeated string scopes = 2;          // 权限范围
  repeated RoleBinding defaults = 3;   // 默认角色绑定
  map<string, string> i18n_zh = 10;    // 中文国际化
}