refactor(contract): wire metadata 控制键统一小驼峰——17 键原子重命名 + 文档全面对齐

按契约命名规范把 wire 调用链 metadata 控制键从 snake_case 统一为
lowerCamelCase（禁止双读兼容，同一变更改完所有读写方）：

gameId/serviceId/targetServiceId/hashKey/timeoutMs/traceId/taskId/
agentId/scheduleId/sdkLanguage/sdkVersion/sdkName/approvalBypass/
pageSnapshotGovernance/approvalActor/approvalId/idempotencyKey
（traceparent 保留——W3C 标准名）

- Go 平台侧：dispatcher/function helpers/agent(local_handler·upstream·
  app·task_runner)/approval/task/scheduler/logic/console/telemetry 常量
- SDK：Go/Python/JS trace 辅助键、JS handler context 的 idempotencyKey
- 范围外数据面（本轮明确不动，避免误伤）：analytics 事件 schema（数仓
  SQL 惯例）、审计/审批 REST details map、ops 快照归一化层（双读别名
  为历史数据兼容）、C++ SDK 配置文件键——均已登记为后续对齐项
- 文档对齐：wire 协议文档（超时小节/字段分层）、otel 传播文档、
  REST API 文档漂移修正（targetServiceId/hashKey 对齐代码实际键）、
  SDK 配置推荐表改 canonical 小驼峰、data-flow Instance.Metadata 键、
  architecture index serviceId

验证：go test ./internal/... ./cmd/... 0 FAIL；go/python/js SDK 全绿
（python 489+ / js 350）；docs build 通过。

Author: cuihairu

CLAUDE.md

@@ -175,8 +175,9 @@ cmd/                      # Binary entry points (server, agent, unified CLI)
 proto/                    # Protobuf definitions (Buf workspace)
 internal/server/          # Server business logic (control, function, http, registry)
 internal/agent/           # Agent logic (tunnel, local server, jobs)
-internal/auth/            # RBAC, JWT, TOTP, user management
-internal/function/        # Descriptor loading and validation
+internal/security/          # RBAC, JWT, TOTP, identity providers (local/LDAP/OIDC)
+internal/api/               # REST API handlers (auth, admin, role, permission, approval, audit, ...)
+internal/function/          # Descriptor loading and validation
 internal/jobs/            # Job state machine and execution
 internal/loadbalancer/    # Load balancing strategies (RR, consistent hash, least conn)
 sdks/                     # Multi-language SDKs (go, python, java, js, cpp, csharp)
@@ -224,9 +225,9 @@ examples/                 # Demo game servers and invokers
 
 Unit tests focus on:
 
-- RBAC policy grant/deny logic (`internal/auth/rbac/`)
+- RBAC policy grant/deny logic (`internal/security/rbac/`)
 - Job executor state transitions and idempotency (`internal/agent/jobs/`)
-- Sensitive field masking (`internal/server/http/`)
+- Sensitive field masking (`internal/api/` response helpers)
 - Pack import/export workflows
 - Registry agent session management
 

docs/api/function.md

@@ -231,8 +231,8 @@ type FunctionInvokeRequest struct {
 	Env string `json:"env,optional"`     // 兼容字段；生效 scope 以 X-Game-ID/X-Env 请求头为准
 	Mode string `json:"mode,optional"`
 	Route string `json:"route,optional"`
-	TargetServiceID string `json:"target_service_id,optional"`
-	HashKey string `json:"hash_key,optional"`
+	TargetServiceID string `json:"targetServiceId,optional"`
+	HashKey string `json:"hashKey,optional"`
 }
 ```
 

docs/architecture/data-flow.md

@@ -70,9 +70,9 @@ sequenceDiagram
 
 当一个 Agent 后挂多个游戏服务（service）时，Agent 内部按 **Nacos 风格的双层索引**选择目标实例：
 
-- **注册期**：SDK 的 `ProviderConnectRequest` 携带 `service_id` 与 `Metadata`（`sdk_language`/`sdk_version`/`game_id`/`env` 等）。Agent 以 `functionId → serviceId → []Instance` 双层索引登记，实例带 `LastSeen` 用于健康判断（`internal/platform/agentlocal/store.go`）。
+- **注册期**：SDK 的 `ProviderConnectRequest` 携带 `service_id` 与 `Metadata`（proto 字段 `sdk_language`/`sdk_version`/`game_id`/`env` 等）。Agent 以 `functionId → serviceId → []Instance` 双层索引登记，实例带 `LastSeen` 用于健康判断（`internal/platform/agentlocal/store.go`）。
 - **调用期**：`pickInstance`（`internal/agent/local_handler.go`）先按 `functionId` 取 service 索引；若 invoke metadata 带 `service_id` 则精确落到该 service 的实例集合，否则合并该函数下所有 service 的实例；再按 `LastSeen` 过滤健康实例并做负载均衡。
-- `Instance.Metadata` 负责透传 SDK 元信息（`sdk_language`/`sdk_version` 等），最终经 `AgentProcess → ProviderSession` 暴露到 opsNodes。
+- `Instance.Metadata` 负责透传 SDK 元信息（键为 `sdkLanguage`/`sdkVersion`/`gameId` 等小驼峰），最终经 `AgentProcess → ProviderSession` 暴露到 opsNodes。
 
 ## 3. SDK 注册到 Agent
 

docs/architecture/index.md

@@ -25,7 +25,7 @@ Croupier 当前的目标架构已经从"多条回拨链路 + 历史 旧传输/gR
 - `env` 表达逻辑生命周期阶段，不直接表示物理部署位置
 - `scope` 与 `target` 必须分离
 - **数据库采用按游戏分库架构**
-- **多服务可共享同一个 Agent**：一个 Agent 可接入多个 game service，函数路由按 `functionId → serviceId → Instance` 双层索引（Nacos 风格），invoke 可在 metadata 带 `service_id` 精确路由
+- **多服务可共享同一个 Agent**：一个 Agent 可接入多个 game service，函数路由按 `functionId → serviceId → Instance` 双层索引（Nacos 风格），invoke 可在 metadata 带 `serviceId` 精确路由
 
 ## 总体拓扑
 

docs/architecture/sdk-agent-transport-redesign.md

@@ -393,7 +393,7 @@ Agent 至少需要实现：
 - `trace_id`
 - `game_id`
 - `env`
-- `timeout_ms`
+- `timeoutMs`（metadata 键）
 - `retry` / `priority` 这类平台治理字段
 
 应留在 JSON payload 的字段：
@@ -580,20 +580,20 @@ SDK 收到这些信号后，可以：
 
 所有 SDK 建议统一收敛到以下字段语义：
 
-| Field                          | 说明             |
-| ------------------------------ | ---------------- |
-| `transport.kind`               | 固定优先为 `tcp` |
-| `transport.address`            | Agent 地址       |
-| `transport.connect_timeout_ms` | 连接超时         |
-| `transport.request_timeout_ms` | 请求超时         |
-| `transport.tls`                | TLS 配置         |
-| `reconnect.enabled`            | 是否自动重连     |
-| `reconnect.initial_delay_ms`   | 初始退避         |
-| `reconnect.max_delay_ms`       | 最大退避         |
-| `reconnect.backoff_multiplier` | 指数退避倍率     |
-| `reconnect.jitter_factor`      | 抖动因子         |
-| `backpressure.max_concurrency` | 本地并发上限     |
-| `backpressure.max_queue_size`  | 本地排队上限     |
+| Field                         | 说明             |
+| ----------------------------- | ---------------- |
+| `transport.kind`              | 固定优先为 `tcp` |
+| `transport.address`           | Agent 地址       |
+| `transport.connectTimeoutMs`  | 连接超时         |
+| `transport.requestTimeoutMs`  | 请求超时         |
+| `transport.tls`               | TLS 配置         |
+| `reconnect.enabled`           | 是否自动重连     |
+| `reconnect.initialDelayMs`    | 初始退避         |
+| `reconnect.maxDelayMs`        | 最大退避         |
+| `reconnect.backoffMultiplier` | 指数退避倍率     |
+| `reconnect.jitterFactor`      | 抖动因子         |
+| `backpressure.maxConcurrency` | 本地并发上限     |
+| `backpressure.max_queue_size` | 本地排队上限     |
 
 ### 废弃字段
 

docs/architecture/sdk-otel-propagation.md

@@ -40,7 +40,7 @@ Croupier 的实现遵循两个业界标准，使用者无需学习私有概念
                            │ trace 开始（或延续外部 traceparent）
                            │ telemetry.InjectContext(ctx, metadata)
                            │   metadata["traceparent"] = "00-<traceId>-<spanId>-01"
-                           │   metadata["trace_id"]    = "<traceId>"   ← 冗余明文，便于弱端读取
+                           │   metadata["traceId"]     = "<traceId>"   ← 冗余明文，便于弱端读取
                            ▼
                       function.dispatch.invoke (SpanKind=Client)
                            │ ExtractContext 延续 trace → 选 Agent → TCP 转发
@@ -86,7 +86,7 @@ SpanKind 语义：`Server` = 承接入站请求，`Client` = 发起出站调用
 | ------------- | ----------------------------------------------------------- | --------------------------------------------- |
 | `traceparent` | W3C：`00-{32位hex traceId}-{16位hex spanId}-{2位hex flags}` | 标准跨进程传播字段，otel SDK 可直接 Extract   |
 | `tracestate`  | W3C：厂商扩展键值对（通常为空）                             | 透传保留                                      |
-| `trace_id`    | 32 位 hex 明文                                              | 冗余字段：不解析 `traceparent` 的简单端直接读 |
+| `traceId`     | 32 位 hex 明文                                              | 冗余字段：不解析 `traceparent` 的简单端直接读 |
 
 W3C `traceparent` 示例：
 
@@ -168,7 +168,7 @@ OTEL_ENABLE_TRACING=true
 ```
 
 未开启 tracing（或 collector 不可达）时：**传播字段照常注入 metadata**
-（`traceparent`/`trace_id` 仍存在），但 span 不会被导出，响应 `traceId`
+（`traceparent`/`traceId` 仍存在），但 span 不会被导出，响应 `traceId`
 为空。属部署配置，非代码缺口。
 
 ### Dashboard 跳转（决定"能不能一键跳"）
@@ -188,14 +188,14 @@ docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest
 
 ## SDK 现状（六语言）
 
-| 语言   | 响应透出 traceId             | 请求注入 traceparent                         | Provider 提取延续                                                                        | 备注                     |
-| ------ | ---------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------ |
-| Go     | ✅（DTO `TraceID`）          | ❌                                           | ✅ 一期（ctx 注入 `WithTraceMetadata` + `TraceParentFromContext`/`TraceIDFromContext`）  | 一期                     |
-| Python | ✅（invoker `trace_id`）     | ❌                                           | ✅ 一期（context JSON 随 metadata 透传 + `croupier.trace` 读取辅助）                     | 一期                     |
-| JS     | ✅（`InvokeResult.traceId`） | ❌                                           | ✅ 一期（context JSON 随 metadata 透传 + `traceParentFromContext`/`traceIdFromContext`） | 一期                     |
-| Java   | ❌                           | ❌                                           | ❌                                                                                       | 二期按需                 |
-| C#     | ❌                           | ❌                                           | ❌                                                                                       | 二期按需                 |
-| C++    | 部分（task 状态）            | 部分（`trace_id` 明文注入 metadata，非 W3C） | ❌                                                                                       | `InvokeOptions.trace_id` |
+| 语言   | 响应透出 traceId             | 请求注入 traceparent                        | Provider 提取延续                                                                        | 备注                    |
+| ------ | ---------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------- |
+| Go     | ✅（DTO `TraceID`）          | ❌                                          | ✅ 一期（ctx 注入 `WithTraceMetadata` + `TraceParentFromContext`/`TraceIDFromContext`）  | 一期                    |
+| Python | ✅（invoker `trace_id`）     | ❌                                          | ✅ 一期（context JSON 随 metadata 透传 + `croupier.trace` 读取辅助）                     | 一期                    |
+| JS     | ✅（`InvokeResult.traceId`） | ❌                                          | ✅ 一期（context JSON 随 metadata 透传 + `traceParentFromContext`/`traceIdFromContext`） | 一期                    |
+| Java   | ❌                           | ❌                                          | ❌                                                                                       | 二期按需                |
+| C#     | ❌                           | ❌                                          | ❌                                                                                       | 二期按需                |
+| C++    | 部分（task 状态）            | 部分（`traceId` 明文注入 metadata，非 W3C） | ❌                                                                                       | `InvokeOptions.traceId` |
 
 一期口径说明：Provider 侧"提取延续"当前为**无 otel 依赖的传播**——trace
 字段进入 handler 上下文（Go 为 context value，Python/JS 为 context JSON

docs/architecture/sdk-wire-protocol.md

@@ -120,15 +120,15 @@ v1 不引入独立 `Magic`，而是直接用首条应用层消息识别子协议
 - `responseMsgID = requestMsgID + 1` 仍是默认约定
 - 像 `TaskEvent` 这样的单向事件消息不属于标准 request/response 配对
 
-### 同步调用超时：metadata `timeout_ms` 约定
+### 同步调用超时：metadata `timeoutMs` 约定
 
 调用方声明的一次同步调用预算（毫秒，字符串十进制），放在 invoke 请求的
 metadata map 中端到端传播，各跳取 **min(本跳配置, 声明值)** 生效（Go
 context deadline 的天然 min 语义）：
 
 | 层          | 行为                                                                                                    |
 | ----------- | ------------------------------------------------------------------------------------------------------- |
-| HTTP API    | 请求体 `timeoutMs`（可选）→ 注入 `metadata["timeout_ms"]`                                               |
+| HTTP API    | 请求体 `timeoutMs`（可选）→ 注入 `metadata["timeoutMs"]`                                                |
 | Server 派发 | `requestTimeoutBudget`：clamp [1000, 60000]，收紧 ctx；全局默认 15s 只作上限                            |
 | Agent       | `providerCallDeadline`：clamp [1000, Agent 配置上限]，与默认（`agent.invokeTimeoutMs`，默认 15000）取小 |
 
@@ -306,11 +306,11 @@ v1 默认规则：
 - `function_id`
 - `session_id`
 - `idempotency_key`
-- `trace_id`
+- `traceId`
   - W3C trace 传播详见 `docs/architecture/sdk-otel-propagation.md`（SDK 只做传播不做导出）
-- `game_id`
+- `gameId`
 - `env`
-- `timeout_ms`
+- `timeoutMs`
 - `priority`
 - 能力协商、限流、重试、审计相关字段
 

docs/operations/config-agent.md

@@ -26,14 +26,14 @@ tag:
 
 ### agent（身份与可达性）
 
-| 键                           | 默认            | 说明                                                                                                 |
-| ---------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- |
-| `agent.id`                   | `""`            | 留空自动生成；多 Agent 部署建议显式指定（拓扑页可读性）                                              |
-| `agent.gameId` / `agent.env` | `""`            | 作用域绑定；留空由注册的游戏服声明                                                                   |
-| `agent.localAddr`            | `0.0.0.0:19091` | 本地 TCP 监听（游戏服函数注册入口）                                                                  |
-| `agent.httpAddr`             | 必填            | **Server→Agent 回调地址**，必须是 Server 视角可达的地址（容器网络用服务名，裸机用 IP）               |
-| `agent.labels`               | `{}`            | 自定义标签（机房/机型等，节点页过滤用）                                                              |
-| `agent.invokeTimeoutMs`      | `15000`         | Agent→游戏服同步调用默认预算（毫秒）；请求 `metadata["timeout_ms"]` 声明更小值时取更小者，上限 60000 |
+| 键                           | 默认            | 说明                                                                                                |
+| ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
+| `agent.id`                   | `""`            | 留空自动生成；多 Agent 部署建议显式指定（拓扑页可读性）                                             |
+| `agent.gameId` / `agent.env` | `""`            | 作用域绑定；留空由注册的游戏服声明                                                                  |
+| `agent.localAddr`            | `0.0.0.0:19091` | 本地 TCP 监听（游戏服函数注册入口）                                                                 |
+| `agent.httpAddr`             | 必填            | **Server→Agent 回调地址**，必须是 Server 视角可达的地址（容器网络用服务名，裸机用 IP）              |
+| `agent.labels`               | `{}`            | 自定义标签（机房/机型等，节点页过滤用）                                                             |
+| `agent.invokeTimeoutMs`      | `15000`         | Agent→游戏服同步调用默认预算（毫秒）；请求 `metadata["timeoutMs"]` 声明更小值时取更小者，上限 60000 |
 
 > `httpAddr` 是最常见的部署错误：写 `0.0.0.0` 或 `localhost` 会导致 Server 回调失败——job 下发/文件传输走不通。
 

internal/agent/local_handler.go

@@ -68,7 +68,7 @@ type LocalHandler struct {
 	expectedGameID   string // Agent 配置的 gameId，用于校验 SDK 注册
 	expectedEnv      string // Agent 配置的 env，用于校验 SDK 注册
 	// providerCallTimeout 是 Agent → Provider 同步调用的默认预算；
-	// 请求 metadata["timeout_ms"] 声明更小值时取更小者（Go deadline
+	// 请求 metadata["timeoutMs"] 声明更小值时取更小者（Go deadline
 	// min 语义）。此前硬编码 10s 与 Server 派发层 15s 倒挂。
 	providerCallTimeout time.Duration
 	mu                  sync.RWMutex
@@ -124,7 +124,7 @@ func (h *LocalHandler) providerCallDeadline(meta map[string]string) time.Duratio
 	if def <= 0 {
 		def = 15 * time.Second
 	}
-	raw := strings.TrimSpace(meta["timeout_ms"])
+	raw := strings.TrimSpace(meta["timeoutMs"])
 	if raw == "" {
 		return def
 	}
@@ -248,8 +248,8 @@ func (h *LocalHandler) handleInvoke(ctx context.Context, data []byte) ([]byte, e
 		trace.WithAttributes(
 			attribute.String("function.id", functionID),
 			attribute.String("agent.id", h.agentID),
-			attribute.String("service.id", req.GetMetadata()["service_id"]),
-			attribute.String("task.id", req.GetMetadata()["task_id"]),
+			attribute.String("service.id", req.GetMetadata()["serviceId"]),
+			attribute.String("task.id", req.GetMetadata()["taskId"]),
 		),
 	)
 	defer span.End()
@@ -307,7 +307,7 @@ func (h *LocalHandler) callProvider(ctx context.Context, functionID string, meta
 	sessions := h.providerSessions
 	h.mu.RUnlock()
 	if sessions != nil {
-		serviceID := metadata["service_id"]
+		serviceID := metadata["serviceId"]
 		if serviceID != "" {
 			if session, ok := sessions.GetByServiceID(serviceID); ok && session.Conn() != nil {
 				_, response, err := session.Conn().Call(ctx, msgID, data)
@@ -385,7 +385,7 @@ func (h *LocalHandler) pickInstance(functionID string, metadata map[string]strin
 	}
 
 	// 按 service_id 路由（一级过滤）
-	targetService := metadata["service_id"]
+	targetService := metadata["serviceId"]
 	var arr []agentlocal.Instance
 	if targetService != "" {
 		arr = serviceMap[targetService]
@@ -462,7 +462,7 @@ func (h *LocalHandler) executeTask(ctx context.Context, req *sdkv1.InvokeRequest
 		trace.WithAttributes(
 			attribute.String("function.id", req.GetFunctionId()),
 			attribute.String("agent.id", h.agentID),
-			attribute.String("task.id", req.GetMetadata()["task_id"]),
+			attribute.String("task.id", req.GetMetadata()["taskId"]),
 		),
 	)
 	defer span.End()
@@ -818,11 +818,11 @@ func (h *LocalHandler) handleProviderConnect(ctx context.Context, data []byte) (
 		}
 		// 提取元数据（参考 Nacos metadata）
 		metadata := map[string]string{
-			"sdk_language":     req.SdkLanguage,
-			"sdk_version":      req.SdkVersion,
-			"sdk_name":         req.SdkName,
+			"sdkLanguage":      req.SdkLanguage,
+			"sdkVersion":       req.SdkVersion,
+			"sdkName":          req.SdkName,
 			"protocol_version": req.ProtocolVersion,
-			"game_id":          req.GameId,
+			"gameId":           req.GameId,
 			"env":              req.Env,
 		}
 		// Use empty addr here; the TCP onConnect path sets the real address.