feat(sdk): 呈现 hints 便捷层——SetFieldHint/SetFieldWidget 全语言对齐（F14）

- Go builder：SetFieldHint/SetFieldWidget（空 schema 建骨架、重复
  覆盖、x_ 归一 x-、非法键入 builder errors），8 例单测
- JS：setFieldHint/setFieldWidget（不可变返回），5 例单测
- Python：set_field_hint/set_field_widget（支持 str schema 合并），
  6 例单测
- SDK_FEATURE_MATRIX L2 新增能力行（Go/Python/JS ✅）；
  docs/sdks/{go,python,js} 同步示例；F 系列状态行更新为全部完成

Author: cuihairu

docs/sdks/go/index.md

@@ -15,6 +15,20 @@ title: Go SDK
 - 与 monorepo 中的 `proto/**` 保持演进一致
 - 支持函数描述符、会话管理与错误处理
 - 适合服务端高并发集成
+- 呈现 hints 便捷层（x-ui-* 契约，见 [呈现 Hints 契约](/architecture/presentation-hints)）：
+
+```go
+metadata, _ := function.NewMetadataBuilder().
+    SetID("player.ban").
+    SetInputSchema(`{"type":"object","properties":{"id":{"type":"string"}}}`).
+    SetFieldWidget("id", "Select").
+    SetFieldHint("id", "x-options-source", map[string]interface{}{
+        "functionId": "player.list",
+        "labelPath":  "/items/*/name",
+        "valuePath":  "/items/*/id",
+    }).
+    Build()
+```
 
 ## 安装
 

docs/sdks/js/index.md

@@ -17,6 +17,23 @@ TypeScript 优先的 Node.js SDK，用于连接 Croupier Agent、注册函数并
 - 提供函数描述符与处理器注册能力
 - 面向 monorepo 统一协议演进
 
+- 呈现 hints 便捷层（x-ui-* 契约，见 [呈现 Hints 契约](/architecture/presentation-hints)）：
+
+```ts
+import { setFieldWidget, setFieldHint } from "croupier-sdk";
+
+let desc = setFieldWidget(
+  { id: "player.ban", version: "1.0.0" },
+  "id",
+  "Select",
+);
+desc = setFieldHint(desc, "id", "x-options-source", {
+  functionId: "player.list",
+  labelPath: "/items/*/name",
+  valuePath: "/items/*/id",
+});
+```
+
 ## 安装
 
 ```bash

docs/sdks/python/index.md

@@ -16,6 +16,19 @@ Python SDK 是 Croupier 的官方 Python 客户端，面向函数注册、调用
 - 基于单连接会话模型与 Agent 通信
 - 内置心跳、重连和基础类型注解
 
+- 呈现 hints 便捷层（x-ui-* 契约，见 [呈现 Hints 契约](/architecture/presentation-hints)）：
+
+```python
+from croupier import set_field_widget, set_field_hint
+
+desc = set_field_widget(FunctionDescriptor(id="player.ban"), "id", "Select")
+desc = set_field_hint(desc, "id", "x-options-source", {
+    "functionId": "player.list",
+    "labelPath": "/items/*/name",
+    "valuePath": "/items/*/id",
+})
+```
+
 ## 安装
 
 ```bash

sdks/SDK_FEATURE_MATRIX.md

@@ -46,6 +46,7 @@
 | 能力                                                                   | 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`） | ❌                  | ❌                          | ❌   | ❌                   | ❌  | ❌                       |

sdks/go/function/builder.go

@@ -2,7 +2,9 @@
 package function
 
 import (
+	"encoding/json"
 	"fmt"
+	"strings"
 )
 
 // MetadataBuilder builds FunctionMetadata using the builder pattern.
@@ -123,6 +125,86 @@ func (b *MetadataBuilder) SetBehavior(behavior *FunctionBehavior) *MetadataBuild
 	return b
 }
 
+// SetFieldHint 向 InputSchema 的 properties[field] 合并单个呈现 hint
+// （F14，x-ui-* 呈现契约的 SDK 便捷层，docs/architecture/presentation-hints.md）。
+// schema 为空时自动创建 object 骨架；属性不存在时创建空属性；重复设置覆盖。
+// hint 必须是 x-/x_ 扩展键（归一为 x- 形式），否则记入校验错误。
+func (b *MetadataBuilder) SetFieldHint(field, hint string, value interface{}) *MetadataBuilder {
+	if strings.TrimSpace(field) == "" {
+		b.errors = append(b.errors, fmt.Errorf("field key is required for SetFieldHint"))
+		return b
+	}
+	normalizedHint, ok := normalizeHintKey(hint)
+	if !ok {
+		b.errors = append(b.errors, fmt.Errorf("hint %q must be an x- extension key (e.g. x-widget)", hint))
+		return b
+	}
+	schema, err := ensureSchemaObject(b.metadata.InputSchema)
+	if err != nil {
+		b.errors = append(b.errors, err)
+		return b
+	}
+	properties, _ := schema["properties"].(map[string]interface{})
+	if properties == nil {
+		properties = map[string]interface{}{}
+		schema["properties"] = properties
+	}
+	property, _ := properties[field].(map[string]interface{})
+	if property == nil {
+		property = map[string]interface{}{}
+		properties[field] = property
+	}
+	property[normalizedHint] = value
+	out, err := json.Marshal(schema)
+	if err != nil {
+		b.errors = append(b.errors, fmt.Errorf("marshal input schema: %w", err))
+		return b
+	}
+	b.metadata.InputSchema = string(out)
+	return b
+}
+
+// SetFieldWidget 等价于 SetFieldHint(field, "x-widget", widget)。
+func (b *MetadataBuilder) SetFieldWidget(field, widget string) *MetadataBuilder {
+	if strings.TrimSpace(widget) == "" {
+		b.errors = append(b.errors, fmt.Errorf("widget is required for SetFieldWidget"))
+		return b
+	}
+	return b.SetFieldHint(field, "x-widget", widget)
+}
+
+// normalizeHintKey 校验并归一 hint 键：x_/X- 变体统一为 x- 形式。
+func normalizeHintKey(hint string) (string, bool) {
+	trimmed := strings.TrimSpace(hint)
+	if trimmed == "" {
+		return "", false
+	}
+	lower := strings.ToLower(trimmed)
+	switch {
+	case strings.HasPrefix(lower, "x_"):
+		return "x-" + trimmed[2:], true
+	case strings.HasPrefix(lower, "x-"):
+		return trimmed, true
+	default:
+		return "", false
+	}
+}
+
+// ensureSchemaObject 解析既有 InputSchema（空串创建 object 骨架）；
+// 非法 JSON 返回错误。
+func ensureSchemaObject(raw string) (map[string]interface{}, error) {
+	schema := map[string]interface{}{}
+	if strings.TrimSpace(raw) != "" {
+		if err := json.Unmarshal([]byte(raw), &schema); err != nil {
+			return nil, fmt.Errorf("input schema is not valid JSON: %w", err)
+		}
+	}
+	if schema["type"] == nil {
+		schema["type"] = "object"
+	}
+	return schema, nil
+}
+
 // SetRisk sets the function risk.
 func (b *MetadataBuilder) SetRisk(risk *FunctionRisk) *MetadataBuilder {
 	b.metadata.Risk = risk

sdks/go/function/hints_test.go

@@ -0,0 +1,140 @@
+package function
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// F14：SetFieldHint/SetFieldWidget 向 InputSchema 注入 x-ui 呈现 hints。
+func hintsOf(t *testing.T, schema string) map[string]interface{} {
+	t.Helper()
+	var out map[string]interface{}
+	if err := json.Unmarshal([]byte(schema), &out); err != nil {
+		t.Fatalf("schema not valid JSON: %v", err)
+	}
+	return out
+}
+
+func TestMetadataBuilder_SetFieldHint(t *testing.T) {
+	t.Run("merge into existing schema", func(t *testing.T) {
+		metadata, err := NewMetadataBuilder().
+			SetID("player.ban").
+			SetInputSchema(`{"type":"object","properties":{"id":{"type":"string","title":"玩家 ID"}}}`).
+			SetFieldHint("id", "x-widget", "Select").
+			SetFieldHint("id", "x-options-source", map[string]interface{}{
+				"functionId": "player.list",
+				"labelPath":  "/items/*/name",
+				"valuePath":  "/items/*/id",
+			}).
+			Build()
+		if err != nil {
+			t.Fatalf("Build: %v", err)
+		}
+		schema := hintsOf(t, metadata.InputSchema)
+		props := schema["properties"].(map[string]interface{})
+		id := props["id"].(map[string]interface{})
+		if id["x-widget"] != "Select" {
+			t.Fatalf("x-widget = %v", id["x-widget"])
+		}
+		source := id["x-options-source"].(map[string]interface{})
+		if source["functionId"] != "player.list" {
+			t.Fatalf("x-options-source = %v", source)
+		}
+		// 既有 title 保留
+		if id["title"] != "玩家 ID" {
+			t.Fatalf("title lost: %v", id["title"])
+		}
+	})
+
+	t.Run("empty schema creates object skeleton", func(t *testing.T) {
+		metadata, err := NewMetadataBuilder().
+			SetID("f").
+			SetFieldWidget("level", "Slider").
+			Build()
+		if err != nil {
+			t.Fatalf("Build: %v", err)
+		}
+		schema := hintsOf(t, metadata.InputSchema)
+		if schema["type"] != "object" {
+			t.Fatalf("type = %v", schema["type"])
+		}
+		props := schema["properties"].(map[string]interface{})
+		level := props["level"].(map[string]interface{})
+		if level["x-widget"] != "Slider" {
+			t.Fatalf("x-widget = %v", level["x-widget"])
+		}
+	})
+
+	t.Run("override previous hint", func(t *testing.T) {
+		metadata, err := NewMetadataBuilder().
+			SetID("f").
+			SetFieldWidget("a", "Input").
+			SetFieldWidget("a", "TextArea").
+			Build()
+		if err != nil {
+			t.Fatalf("Build: %v", err)
+		}
+		schema := hintsOf(t, metadata.InputSchema)
+		a := schema["properties"].(map[string]interface{})["a"].(map[string]interface{})
+		if a["x-widget"] != "TextArea" {
+			t.Fatalf("x-widget = %v (expected override)", a["x-widget"])
+		}
+	})
+
+	t.Run("x_ prefix normalized to x-", func(t *testing.T) {
+		metadata, err := NewMetadataBuilder().
+			SetID("f").
+			SetFieldHint("a", "x_widget", "Input").
+			Build()
+		if err != nil {
+			t.Fatalf("Build: %v", err)
+		}
+		schema := hintsOf(t, metadata.InputSchema)
+		a := schema["properties"].(map[string]interface{})["a"].(map[string]interface{})
+		if _, ok := a["x-widget"]; !ok {
+			t.Fatalf("expected normalized x-widget key, got %v", a)
+		}
+	})
+
+	t.Run("invalid hint rejected", func(t *testing.T) {
+		_, err := NewMetadataBuilder().
+			SetID("f").
+			SetFieldHint("a", "widget", "Input").
+			Build()
+		if err == nil || !strings.Contains(err.Error(), "x- extension key") {
+			t.Fatalf("expected hint validation error, got %v", err)
+		}
+	})
+
+	t.Run("empty field rejected", func(t *testing.T) {
+		_, err := NewMetadataBuilder().
+			SetID("f").
+			SetFieldHint("", "x-widget", "Input").
+			Build()
+		if err == nil || !strings.Contains(err.Error(), "field key is required") {
+			t.Fatalf("expected field validation error, got %v", err)
+		}
+	})
+
+	t.Run("empty widget rejected", func(t *testing.T) {
+		_, err := NewMetadataBuilder().
+			SetID("f").
+			SetFieldWidget("a", "  ").
+			Build()
+		if err == nil || !strings.Contains(err.Error(), "widget is required") {
+			t.Fatalf("expected widget validation error, got %v", err)
+		}
+	})
+
+	t.Run("invalid existing schema rejected", func(t *testing.T) {
+		_, err := NewMetadataBuilder().
+			SetID("f").
+			SetInputSchema(`not-json`).
+			SetFieldHint("a", "x-widget", "Input").
+			Build()
+		if err == nil || !strings.Contains(err.Error(), "not valid JSON") {
+			t.Fatalf("expected schema parse error, got %v", err)
+		}
+	})
+}

sdks/js/src/hints.test.ts

@@ -0,0 +1,63 @@
+/**
+ * F14 验收测试：setFieldHint/setFieldWidget 便捷层
+ */
+import { setFieldHint, setFieldWidget, type FunctionDescriptor } from "./index";
+
+function base(): FunctionDescriptor {
+  return { id: "player.ban", version: "1.0.0" };
+}
+
+describe("F14: setFieldHint", () => {
+  test("空 schema 自动创建 object 骨架并合并 hint", () => {
+    const descriptor = setFieldWidget(base(), "id", "Select");
+    const schema = descriptor.inputSchema as Record<string, unknown>;
+    expect(schema.type).toBe("object");
+    const props = schema.properties as Record<string, Record<string, unknown>>;
+    expect(props.id["x-widget"]).toBe("Select");
+  });
+
+  test("保留既有字段属性，重复设置覆盖", () => {
+    const descriptor = setFieldWidget(
+      {
+        ...base(),
+        inputSchema: {
+          type: "object",
+          properties: { id: { type: "string", title: "玩家 ID", "x-widget": "Input" } },
+        },
+      },
+      "id",
+      "TreeSelect",
+    );
+    const props = (descriptor.inputSchema as Record<string, unknown>).properties as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(props.id.title).toBe("玩家 ID");
+    expect(props.id["x-widget"]).toBe("TreeSelect");
+  });
+
+  test("x-options-source 完整对象", () => {
+    const descriptor = setFieldHint(base(), "id", "x-options-source", {
+      functionId: "player.list",
+      labelPath: "/items/*/name",
+      valuePath: "/items/*/id",
+    });
+    const props = (descriptor.inputSchema as Record<string, unknown>).properties as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(props.id["x-options-source"]).toEqual({
+      functionId: "player.list",
+      labelPath: "/items/*/name",
+      valuePath: "/items/*/id",
+    });
+  });
+
+  test("非 x- hint 拒绝", () => {
+    expect(() => setFieldHint(base(), "a", "widget", "Input")).toThrow(/x- extension key/);
+  });
+
+  test("空 field 拒绝", () => {
+    expect(() => setFieldHint(base(), "  ", "x-widget", "Input")).toThrow(/field key is required/);
+  });
+});