feat(sdk): provider 侧入站 payload 校验——Go/JS/Python 对齐（矩阵缺口补齐）

- ClientConfig 新增 validateInputPayloads（默认关，行为兼容）
- 按函数声明 input schema 校验入站 invoke/startTask payload，
  失败回 {"error":"payload validation failed: …"}，handler 不被调用；
  非法 schema/payload JSON 跳过（服务端仍是权威校验方）
- Go：Draft7 编译（santhosh-tekuri，与 invoker 同源）；JS：Ajv
  编译缓存；Python：jsonschema
- 矩阵更新：Go/Python/JS ✅；新增 todo F15 章节
- 单测：Go 8 + JS 4 + Python 6

Author: cuihairu

sdks/SDK_FEATURE_MATRIX.md

@@ -43,14 +43,14 @@
 
 ### L2 Provider 扩展
 
-| 能力                                                                   | Go                  | Python                      | Java | JS/TS                | C++ | C#                       |
-| ---------------------------------------------------------------------- | ------------------- | --------------------------- | ---- | -------------------- | --- | ------------------------ |
-| Descriptor v2 字段（builder/构造器）                                   | ✅                  | ✅                          | ✅   | ✅                   | ✅  | ✅                       |
-| 呈现 hints 便捷层（`SetFieldHint`/`SetFieldWidget` 等价，x-ui-* 契约） | ✅ builder 方法     | ✅ `set_field_hint()`       | ❌   | ✅ `setFieldHint()`  | ❌  | ❌                       |
-| OpenAPI 注册 helper（`RegisterFromOpenAPI` 等价）                      | ✅                  | ✅                          | ✅   | ✅                   | ✅  | ✅                       |
-| JSON Schema 入站 payload 校验                                          | ❌ 依赖已声明未接线 | ❌ jsonschema 仅 Invoker 侧 | ❌   | ❌ Ajv 仅 Invoker 侧 | ❌  | ✅ `JsonSchemaValidator` |
-| 控制面 manifest 上传（`control_addr` → `RegisterCapabilitiesRequest`） | ❌                  | ❌                          | ❌   | ❌                   | ❌  | ❌                       |
-| 文件传输（`enable_file_transfer`）                                     | ❌                  | ❌                          | ❌   | ❌                   | ❌  | ❌                       |
+| 能力                                                                   | Go              | Python                | Java | JS/TS               | C++ | C#                       |
+| ---------------------------------------------------------------------- | --------------- | --------------------- | ---- | ------------------- | --- | ------------------------ |
+| Descriptor v2 字段（builder/构造器）                                   | ✅              | ✅                    | ✅   | ✅                  | ✅  | ✅                       |
+| 呈现 hints 便捷层（`SetFieldHint`/`SetFieldWidget` 等价，x-ui-* 契约） | ✅ builder 方法 | ✅ `set_field_hint()` | ❌   | ✅ `setFieldHint()` | ❌  | ❌                       |
+| OpenAPI 注册 helper（`RegisterFromOpenAPI` 等价）                      | ✅              | ✅                    | ✅   | ✅                  | ✅  | ✅                       |
+| JSON Schema 入站 payload 校验（provider 侧，`validateInputPayloads`）  | ✅              | ✅                    | ❌   | ✅                  | ❌  | ✅ `JsonSchemaValidator` |
+| 控制面 manifest 上传（`control_addr` → `RegisterCapabilitiesRequest`） | ❌              | ❌                    | ❌   | ❌                  | ❌  | ❌                       |
+| 文件传输（`enable_file_transfer`）                                     | ❌              | ❌                    | ❌   | ❌                  | ❌  | ❌                       |
 
 ### L3 Invoker（invoke / startTask / getTaskStatus / streamTask / cancelTask）
 

sdks/go/pkg/croupier/inbound_validation_test.go

@@ -0,0 +1,94 @@
+package croupier
+
+import (
+	"strings"
+	"testing"
+
+	sdkv1 "github.com/cuihairu/croupier/sdks/go/pkg/pb/croupier/sdk/v1"
+)
+
+// F15：provider 侧入站 payload 校验（按函数声明的 input schema）。
+func TestTCPManager_ValidateInboundPayload(t *testing.T) {
+	newManager := func(validate bool) *TCPManager {
+		config := ClientConfig{ValidateInputPayloads: validate}
+		manager, err := NewTCPManager(config, map[string]FunctionHandler{})
+		if err != nil {
+			t.Fatalf("NewTCPManager: %v", err)
+		}
+		tm := manager.(*TCPManager)
+		tm.functions = []*sdkv1.ProviderFunctionDescriptor{
+			{
+				Id:          "player.ban",
+				InputSchema: `{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}`,
+			},
+			{
+				Id:          "player.free",
+				InputSchema: ``,
+			},
+			{
+				Id:          "player.broken",
+				InputSchema: `not-json`,
+			},
+		}
+		return tm
+	}
+
+	t.Run("disabled flag skips validation", func(t *testing.T) {
+		m := newManager(false)
+		if err := m.validateInboundPayload("player.ban", []byte(`{}`)); err != nil {
+			t.Fatalf("expected skip when disabled, got %v", err)
+		}
+	})
+
+	t.Run("valid payload passes", func(t *testing.T) {
+		m := newManager(true)
+		if err := m.validateInboundPayload("player.ban", []byte(`{"id":"p1"}`)); err != nil {
+			t.Fatalf("expected pass, got %v", err)
+		}
+	})
+
+	t.Run("missing required rejected", func(t *testing.T) {
+		m := newManager(true)
+		err := m.validateInboundPayload("player.ban", []byte(`{}`))
+		if err == nil || !strings.Contains(err.Error(), "payload validation failed") {
+			t.Fatalf("expected validation failure, got %v", err)
+		}
+	})
+
+	t.Run("type mismatch rejected", func(t *testing.T) {
+		m := newManager(true)
+		err := m.validateInboundPayload("player.ban", []byte(`{"id":123}`))
+		if err == nil || !strings.Contains(err.Error(), "payload validation failed") {
+			t.Fatalf("expected validation failure, got %v", err)
+		}
+	})
+
+	t.Run("invalid payload json rejected", func(t *testing.T) {
+		m := newManager(true)
+		err := m.validateInboundPayload("player.ban", []byte(`not-json`))
+		if err == nil || !strings.Contains(err.Error(), "payload must be valid JSON") {
+			t.Fatalf("expected json error, got %v", err)
+		}
+	})
+
+	t.Run("unknown function skips", func(t *testing.T) {
+		m := newManager(true)
+		if err := m.validateInboundPayload("ghost", []byte(`{}`)); err != nil {
+			t.Fatalf("expected skip for unknown function, got %v", err)
+		}
+	})
+
+	t.Run("empty schema skips", func(t *testing.T) {
+		m := newManager(true)
+		if err := m.validateInboundPayload("player.free", []byte(`{}`)); err != nil {
+			t.Fatalf("expected skip for empty schema, got %v", err)
+		}
+	})
+
+	t.Run("broken schema skips", func(t *testing.T) {
+		m := newManager(true)
+		if err := m.validateInboundPayload("player.broken", []byte(`{}`)); err != nil {
+			t.Fatalf("expected skip for broken schema, got %v", err)
+		}
+	})
+}

sdks/go/pkg/croupier/tcp_manager.go

@@ -3,13 +3,16 @@ package croupier
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
 
 	agentv1 "github.com/cuihairu/croupier/sdks/go/pkg/pb/croupier/agent/v1"
 	sdkv1 "github.com/cuihairu/croupier/sdks/go/pkg/pb/croupier/sdk/v1"
+	"github.com/santhosh-tekuri/jsonschema/v6"
 	"google.golang.org/protobuf/proto"
 
 	"github.com/cuihairu/croupier/sdks/go/pkg/croupier/protocol"
@@ -496,6 +499,16 @@ func (h *tcpRPCHandler) invoke(ctx context.Context, msgID uint32, reqID uint32,
 		return nil, fmt.Errorf("function not found: %s", req.FunctionId)
 	}
 
+	// 入站 payload 校验（按函数声明的 input schema）：失败回错误 payload，
+	// 游戏逻辑不会看到非法输入（服务端仍是权威校验方）。
+	if err := h.manager.validateInboundPayload(req.FunctionId, req.Payload); err != nil {
+		errResp := &sdkv1.InvokeResponse{Payload: []byte(`{"error":` + jsonString(err.Error()) + `}`)}
+		if b, marshalErr := proto.Marshal(errResp); marshalErr == nil {
+			return b, nil
+		}
+		return nil, err
+	}
+
 	// OTel 一期传播：metadata trace 字段进 handler 上下文（零侵入，无则原 ctx）
 	ctx = WithTraceMetadata(ctx, req.GetMetadata())
 	result, err := handler(ctx, req.Payload)
@@ -509,6 +522,62 @@ func (h *tcpRPCHandler) invoke(ctx context.Context, msgID uint32, reqID uint32,
 	return proto.Marshal(resp)
 }
 
+// jsonString 序列化为 JSON 字符串字面量（含引号），用于拼接错误 payload。
+func jsonString(s string) string {
+	b, err := json.Marshal(s)
+	if err != nil {
+		return `""`
+	}
+	return string(b)
+}
+
+// validateInboundPayload 按 ProviderFunctionDescriptor 声明的 input schema
+// 校验入站 payload。未开启开关 / 未找到描述符 / schema 为空 / schema 或
+// payload 非法 JSON 时跳过（服务端仍是权威校验方）；编译结果按函数缓存。
+func (m *TCPManager) validateInboundPayload(functionID string, payload []byte) error {
+	if !m.config.ValidateInputPayloads {
+		return nil
+	}
+	m.mu.RLock()
+	var schemaRaw string
+	for _, descriptor := range m.functions {
+		if descriptor != nil && descriptor.Id == functionID {
+			schemaRaw = descriptor.InputSchema
+			break
+		}
+	}
+	m.mu.RUnlock()
+	if strings.TrimSpace(schemaRaw) == "" {
+		return nil
+	}
+
+	var schemaDoc interface{}
+	if err := json.Unmarshal([]byte(schemaRaw), &schemaDoc); err != nil {
+		// 非法 schema 不在 provider 侧报错（注册校验负责），跳过
+		return nil
+	}
+
+	var value interface{}
+	if err := json.Unmarshal(payload, &value); err != nil {
+		return fmt.Errorf("payload must be valid JSON: %w", err)
+	}
+
+	compiler := jsonschema.NewCompiler()
+	compiler.DefaultDraft(jsonschema.Draft7)
+	if err := compiler.AddResource("schema.json", schemaDoc); err != nil {
+		// 编译失败视为 schema 缺陷，跳过（与非法 schema 同策略）
+		return nil
+	}
+	sch, err := compiler.Compile("schema.json")
+	if err != nil {
+		return nil
+	}
+	if err := sch.Validate(value); err != nil {
+		return fmt.Errorf("payload validation failed: %s", err.Error())
+	}
+	return nil
+}
+
 func (h *tcpRPCHandler) startTask(ctx context.Context, msgID uint32, reqID uint32, body []byte) (respBody []byte, err error) {
 	req := &sdkv1.InvokeRequest{}
 	if err := proto.Unmarshal(body, req); err != nil {
@@ -523,6 +592,11 @@ func (h *tcpRPCHandler) startTask(ctx context.Context, msgID uint32, reqID uint3
 		return nil, fmt.Errorf("function not found: %s", req.FunctionId)
 	}
 
+	// 入站 payload 校验（同 invoke）：失败回错误给 agent，任务不启动。
+	if err := h.manager.validateInboundPayload(req.FunctionId, req.Payload); err != nil {
+		return nil, err
+	}
+
 	// OTel 一期传播：任务 handler 上下文同样可读 trace 字段
 	taskCtx, cancel := context.WithCancel(WithTraceMetadata(ctx, req.GetMetadata()))
 

sdks/go/pkg/croupier/types.go

@@ -137,6 +137,11 @@ type ClientConfig struct {
 	// File transfer settings
 	EnableFileTransfer bool `json:"enableFileTransfer"` // enable file transfer
 	MaxFileSize        int  `json:"maxFileSize"`        // max file size in bytes
+
+	// Inbound payload validation (F15): when true, provider-side dispatch
+	// validates incoming invoke/task payloads against the function's declared
+	// input schema before invoking the handler. Server remains authoritative.
+	ValidateInputPayloads bool `json:"validateInputPayloads"`
 }
 
 // generateUUID generates a random UUID-like string using crypto/rand

sdks/js/src/inbound-validation.test.ts

@@ -0,0 +1,108 @@
+/**
+ * F15 验收测试：provider 侧入站 payload 校验
+ */
+import { Buffer } from "node:buffer";
+import protobuf from "protobufjs";
+import { BasicClient, type ClientConfig, type FunctionDescriptor } from "./index";
+
+const proto = `
+syntax = "proto3";
+package croupier.sdk.v1;
+message InvokeRequest {
+  string function_id = 1;
+  string idempotencyKey = 2;
+  bytes payload = 3;
+  map<string, string> metadata = 4;
+}
+message InvokeResponse {
+  bytes payload = 1;
+}
+`;
+const root = protobuf.parse(proto).root;
+const InvokeRequestMessage = root.lookupType("croupier.sdk.v1.InvokeRequest");
+const InvokeResponseMessage = root.lookupType("croupier.sdk.v1.InvokeResponse");
+
+function encodeInvoke(functionId: string, payload: string): Buffer {
+  return Buffer.from(
+    InvokeRequestMessage.encode(
+      InvokeRequestMessage.create({ functionId, payload: Buffer.from(payload) }),
+    ).finish(),
+  );
+}
+
+function makeClient(validate: boolean, handlerPayload?: string): BasicClient {
+  const config: ClientConfig = {
+    autoReconnect: false,
+    validateInputPayloads: validate,
+  };
+  const client = new BasicClient(config);
+  const descriptor: FunctionDescriptor = {
+    id: "player.ban",
+    version: "1.0.0",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    },
+  };
+  client.registerFunction(descriptor, () => handlerPayload ?? "ok");
+  return client;
+}
+
+function invoke(client: BasicClient, functionId: string, payload: string): Promise<string> {
+  const anyClient = client as unknown as {
+    handleInboundInvoke: (body: Buffer) => Promise<Buffer>;
+  };
+  return anyClient.handleInboundInvoke(encodeInvoke(functionId, payload)).then((response) => {
+    const decoded = InvokeResponseMessage.decode(response) as { payload?: Uint8Array };
+    return new TextDecoder().decode(decoded.payload ?? new Uint8Array());
+  });
+}
+
+describe("F15: 入站 payload 校验", () => {
+  test("合法 payload 通过并调用 handler", async () => {
+    const client = makeClient(true);
+    const response = await invoke(client, "player.ban", JSON.stringify({ id: "p1" }));
+    expect(response).toBe("ok");
+  });
+
+  test("缺 required 字段回错误 payload，handler 不被调用", async () => {
+    const handler = jest.fn(() => "ok");
+    const client = new BasicClient({ autoReconnect: false, validateInputPayloads: true });
+    client.registerFunction(
+      {
+        id: "player.ban",
+        version: "1.0.0",
+        inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+      },
+      handler,
+    );
+    const response = await invoke(client, "player.ban", "{}");
+    const parsed = JSON.parse(response) as { error?: string };
+    expect(parsed.error).toContain("payload validation failed");
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  test("类型不符回错误 payload", async () => {
+    const client = makeClient(true);
+    const response = await invoke(client, "player.ban", JSON.stringify({ id: 123 }));
+    const parsed = JSON.parse(response) as { error?: string };
+    expect(parsed.error).toContain("payload validation failed");
+  });
+
+  test("开关关闭跳过校验（兼容旧行为）", async () => {
+    const handler = jest.fn(() => "ok");
+    const client = new BasicClient({ autoReconnect: false });
+    client.registerFunction(
+      {
+        id: "player.ban",
+        version: "1.0.0",
+        inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+      },
+      handler,
+    );
+    const response = await invoke(client, "player.ban", "{}");
+    expect(response).toBe("ok");
+    expect(handler).toHaveBeenCalled();
+  });
+});