@gencode/plugin-sdk 0.0.4 → 0.0.6

package/README.md

@@ -125,34 +125,117 @@ export default function register(api: PluginApi) {
     label: "收集用户反馈",
     description: "Collect structured feedback from the user.",
     schema: {
+      type: "object",
       title: "用户反馈",
-      fields: [
-        { name: "rating", label: "评分", type: "number", required: true },
-        { name: "comment", label: "评论", type: "textarea" },
-      ],
+      properties: {
+        rating: { type: "number", title: "评分" },
+        comment: { type: "string", title: "评论" },
+      },
+      required: ["rating"],
+    },
+    extra: {
+      ui: {
+        fields: {
+          comment: { widget: "textarea" },
+        },
+      },
     },
   });
 }
 ```
 
-### 字段类型
+### JSON Schema 约定
 
-`schema.fields` 中每个字段的 `type` 支持以下值：
+`schema` 现在遵循 JSON Schema 风格的对象定义，推荐至少提供：
 
-| 类型 | 说明 |
+| 字段 | 说明 |
 |------|------|
-| `string` | 单行文本 |
-| `number` | 数值 |
-| `boolean` | 布尔开关 |
-| `date` | 日期 |
-| `select` | 单选下拉，需配合 `options` |
-| `multiselect` | 多选，需配合 `options` |
-| `textarea` | 多行文本 |
-| `file` | 文件路径或 data URI |
+| `type: "object"` | UI tool 顶层 schema 必填 |
+| `properties` | 表单字段定义 |
+| `required` | 必填字段列表 |
+| `description` | 表单或字段说明 |
+| `default` | 默认值 |
+| `enum` | 单选枚举 |
+| `format: "date"` | 日期输入 |
+| `items.enum` | 多选枚举数组 |
+
+示例：
+
+```ts
+schema: {
+  type: "object",
+  title: "报告参数",
+  properties: {
+    format: {
+      type: "string",
+      title: "输出格式",
+      enum: ["markdown", "pdf", "html"],
+    },
+    tags: {
+      type: "array",
+      title: "标签",
+      items: {
+        type: "string",
+        enum: ["tech", "ops", "finance"],
+      },
+    },
+    startDate: {
+      type: "string",
+      title: "开始日期",
+      format: "date",
+    },
+  },
+}
+```
+
+### `extra` 扩展字段
+
+有些场景不适合完全按 JSON Schema 的标准字段渲染。此时可以通过 `extra` 透传一份 JSON-safe 扩展配置给前端，由接入方自行解释并渲染更高自定义的 UI。
+
+```ts
+api.registerUiTool({
+  name: "custom_summary_form",
+  label: "自定义摘要表单",
+  description: "Collect values through a custom-rendered panel.",
+  schema: {
+    type: "object",
+    title: "摘要确认",
+    properties: {
+      approved: { type: "boolean", title: "是否确认" },
+      comment: { type: "string", title: "补充说明" },
+    },
+    required: ["approved"],
+  },
+  extra: {
+    renderer: "summary-card",
+    sections: [
+      { kind: "markdown", title: "摘要", content: "这里放自定义摘要内容" },
+    ],
+    ui: {
+      fields: {
+        comment: { widget: "textarea", placeholder: "可选补充说明" },
+      },
+    },
+  },
+});
+```
+
+约束：
+
+- `extra` 只负责扩展前端渲染，不参与内置 JSON Schema 校验
+- 用户提交结果仍然统一回传到 `values`
+- 建议保持 JSON-safe，避免函数、类实例或不可序列化对象
+
+推荐把非标准控件语义放在 `extra.ui.fields` 中，例如：
+
+- `widget: "textarea"`
+- `widget: "file"`
+- `placeholder`
+- `enumLabels`
 
 ### 自定义校验
 
-内置 schema 校验（required、类型检查、select 选项范围）之外，可以提供 `validate` 函数做跨字段校验：
+内置 JSON Schema 校验之外，可以提供 `validate` 函数做跨字段校验：
 
 ```ts
 api.registerUiTool({
@@ -160,11 +243,13 @@ api.registerUiTool({
   label: "选择日期范围",
   description: "Collect a date range with cross-field validation.",
   schema: {
+    type: "object",
     title: "日期范围",
-    fields: [
-      { name: "startDate", label: "开始日期", type: "date", required: true },
-      { name: "endDate", label: "结束日期", type: "date", required: true },
-    ],
+    properties: {
+      startDate: { type: "string", title: "开始日期", format: "date" },
+      endDate: { type: "string", title: "结束日期", format: "date" },
+    },
+    required: ["startDate", "endDate"],
   },
   validate(values) {
     const start = values.startDate as string;
@@ -187,16 +272,16 @@ api.registerUiTool({
 | 维度 | `registerTool` | `registerUiTool` |
 |------|---------------|-----------------|
 | 用途 | 通用工具 | 收集前端表单输入 |
-| 开发者关注点 | 完整 `execute` 实现 | 只需提供表单 schema |
+| 开发者关注点 | 完整 `execute` 实现 | 只需提供 JSON Schema + 元数据 |
 | sessionId | 需要自行处理 | 框架自动绑定 |
 | 暂停/恢复 | 需要手动抛出信号 | 框架自动处理 |
-| 结果校验 | 自行实现 | 内置 schema 校验 + 可选自定义 validator |
+| 结果校验 | 自行实现 | 内置 JSON Schema 校验 + 可选自定义 validator |
 
 ### 运行流程
 
 1. LLM 调用 UI 工具 → 自动抛出 `UiToolPauseSignal` 暂停 agent
 2. Runner 捕获信号，发出 `ui_tool_request` 进度事件（包含表单 schema）
-3. 前端根据 schema 渲染表单
+3. 前端根据 schema 渲染标准表单，或结合 `extra` 渲染自定义 UI
 4. 用户提交后，CLI 带 `uiToolResume` 重新调用 agent
 5. 框架自动校验数据（内置 + 自定义 validator）
 6. 校验通过 → 工具返回提交值给 LLM → agent 继续执行
@@ -208,7 +293,8 @@ api.registerUiTool({
 - `PluginUiToolDescriptor` — `registerUiTool` 的参数类型
 - `PluginUiToolOptions` — 可选参数（如 `optional`）
 - `UiToolSchema` — 表单 schema
-- `UiToolFieldSchema` — 单个字段定义
-- `UiToolFieldType` — 字段类型联合类型
+- `UiToolJsonSchemaProperty` — 单个字段的 JSON Schema 定义
+- `UiToolJsonSchemaType` — 支持的 JSON Schema `type`
+- `UiToolExtra` — 前端扩展渲染负载
 - `UiToolValidationError` — 校验错误
 - `UiToolValidationResult` — 校验结果

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export type { MemoryProvider, MemoryProviderContext, MemoryProviderFactory, Memo
 export type { EmbeddingProvider, EmbeddingProviderContext, EmbeddingProviderFactory, EmbeddingProviderRegistration, } from "@gencode/agents";
 export type { PluginHookName, PluginHookHandlerMap, PluginHookAgentContext, PluginHookBeforeModelResolveEvent, PluginHookBeforeModelResolveResult, PluginHookBeforePromptBuildEvent, PluginHookBeforePromptBuildResult, PluginHookLlmInputEvent, PluginHookLlmOutputEvent, PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult, PluginHookAfterToolCallEvent, PluginHookAgentEndEvent, PluginHookBeforeCompactionEvent, PluginHookAfterCompactionEvent, PluginHookSessionStartEvent, PluginHookSessionEndEvent, PluginHookSessionResetEvent, PluginHookMemoryChangedEvent, } from "@gencode/agents";
 export type { PluginRuntime } from "@gencode/agents";
-export type { UiToolFieldType, UiToolFieldSchema, UiToolSchema, UiToolValidationError, UiToolValidationResult, } from "@gencode/shared";
+export type { UiToolExtra, UiToolJsonSchemaProperty, UiToolJsonSchemaType, UiToolSchema, UiToolValidationError, UiToolValidationResult, } from "@gencode/shared";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,wBAAwB,EACxB,SAAS,EACT,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,iCAAiC,EACjC,kCAAkC,EAClC,gCAAgC,EAChC,iCAAiC,EACjC,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,4BAA4B,EAC5B,uBAAuB,EACvB,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,wBAAwB,EACxB,SAAS,EACT,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,iCAAiC,EACjC,kCAAkC,EAClC,gCAAgC,EAChC,iCAAiC,EACjC,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,4BAA4B,EAC5B,uBAAuB,EACvB,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,yBAAyB,EACzB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,YAAY,EACV,WAAW,EACX,wBAAwB,EACxB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gencode/plugin-sdk",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,8 +17,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@gencode/agents": "0.0.40",
-    "@gencode/shared": "0.0.12"
+    "@gencode/agents": "0.0.42",
+    "@gencode/shared": "0.0.14"
   },
   "devDependencies": {
     "typescript": "^5.9.3"