@gencode/plugin-sdk 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,245 @@
+# `@gencode/plugin-sdk`
+
+`@gencode/plugin-sdk` 提供插件作者需要的稳定类型导出，避免直接依赖 `@gencode/agents` 的内部文件路径。
+
+## 最小插件结构
+
+```text
+my-plugin/
+├── aimax.plugin.json
+└── index.ts
+```
+
+`aimax.plugin.json`:
+
+```json
+{
+  "id": "progress-demo",
+  "name": "Progress Demo",
+  "description": "Demonstrates custom plugin progress events.",
+  "version": "0.0.1",
+  "configSchema": {}
+}
+```
+
+`index.ts`:
+
+```ts
+import type { PluginApi } from "@gencode/plugin-sdk";
+
+export default function register(api: PluginApi) {
+  const progress = api.createProgressEmitter();
+
+  api.registerHook("session_start", async () => {
+    await progress.emit({
+      name: "progress_demo.session.started",
+      label: "Plugin initialized",
+      data: { source: "hook" },
+    });
+  });
+}
+```
+
+## `createProgressEmitter`
+
+插件现在可以通过 `api.createProgressEmitter()` 主动发出自定义进度事件。
+
+```ts
+const progress = api.createProgressEmitter();
+
+await progress.emit({
+  name: "my_plugin.step.completed",
+  label: "Downloaded source data",
+  data: {
+    step: "download",
+    itemCount: 12,
+  },
+});
+```
+
+事件字段说明：
+
+- `name`: 稳定事件名，建议使用 `plugin_namespace.action` 或 `plugin.namespace.action`
+- `label`: 面向用户的短文案，可直接展示在 Web/H5 时间线
+- `data`: JSON-safe 结构化扩展字段，供 callback/WebSocket 消费方解析
+
+运行时约束：
+
+- 只能在插件运行期调用，例如 hook handler 或 plugin tool 的 `execute`
+- 不能在模块顶层或 `register()` 执行期间直接调用
+- `pluginId`、`sessionId`、`messageId`、`depth` 由框架注入，插件不需要也不能手工传入
+
+## 事件流向
+
+插件发出的 custom progress event 会复用现有的统一事件链路：
+
+1. `@gencode/agents` 产出 `AgentProgressEvent { type: "custom", ... }`
+2. `@gencode/cli` 继续通过 stdout / HTTP callback / websocket 分发
+3. `@gencode/console` 将其映射为 `agent.custom`
+
+stdout 文本输出示例：
+
+```text
+[plugin:progress-demo] progress_demo.task.completed Task completed {"step":"run","count":3}
+```
+
+WebSocket / callback 中的事件载荷核心字段：
+
+```json
+{
+  "type": "custom",
+  "pluginId": "progress-demo",
+  "name": "progress_demo.task.completed",
+  "label": "Task completed",
+  "data": {
+    "step": "run",
+    "count": 3
+  }
+}
+```
+
+## 建议
+
+- 优先让 `name` 稳定，便于服务端和前端做事件聚合
+- `label` 保持短句，适合直接展示
+- `data` 放结构化上下文，不要塞大段文本
+- 如果一个插件需要多个阶段事件，建议统一前缀，例如：
+  - `progress_demo.fetch.started`
+  - `progress_demo.fetch.completed`
+  - `progress_demo.report.generated`
+
+## `registerUiTool`
+
+插件可以通过 `api.registerUiTool()` 注册 UI 工具，让 LLM 在需要时暂停 agent 并通过前端表单收集结构化用户输入。
+
+与 `registerTool` 不同，插件只需要提供表单 schema 和基本元数据 — session 绑定、暂停/恢复流程、结果校验都由框架自动完成。
+
+### 基本用法
+
+```ts
+import type { PluginApi } from "@gencode/plugin-sdk";
+
+export default function register(api: PluginApi) {
+  api.registerUiTool({
+    name: "collect_feedback",
+    label: "收集用户反馈",
+    description: "Collect structured feedback from the user.",
+    schema: {
+      title: "用户反馈",
+      fields: [
+        { name: "rating", label: "评分", type: "number", required: true },
+        { name: "comment", label: "评论", type: "textarea" },
+      ],
+    },
+  });
+}
+```
+
+### 字段类型
+
+`schema.fields` 中每个字段的 `type` 支持以下值：
+
+| 类型 | 说明 |
+|------|------|
+| `string` | 单行文本 |
+| `number` | 数值 |
+| `boolean` | 布尔开关 |
+| `date` | 日期 |
+| `select` | 单选下拉，需配合 `options` |
+| `multiselect` | 多选，需配合 `options` |
+| `textarea` | 多行文本 |
+| `file` | 文件路径或 data URI |
+
+### `uiExtension` 扩展字段
+
+有些场景不适合完全按 `schema.fields` 渲染标准表单。此时可以通过 `uiExtension` 透传一份 JSON-safe 扩展配置给前端，由接入方自行解释并渲染更高自定义的 UI。
+
+```ts
+api.registerUiTool({
+  name: "custom_summary_form",
+  label: "自定义摘要表单",
+  description: "Collect values through a custom-rendered panel.",
+  schema: {
+    title: "摘要确认",
+    fields: [
+      { name: "approved", label: "是否确认", type: "boolean", required: true },
+      { name: "comment", label: "补充说明", type: "textarea" },
+    ],
+  },
+  uiExtension: {
+    renderer: "summary-card",
+    sections: [
+      { kind: "markdown", title: "摘要", content: "这里放自定义摘要内容" },
+    ],
+  },
+});
+```
+
+约束：
+
+- `uiExtension` 只负责扩展前端渲染，不参与内置字段校验
+- 用户提交结果仍然统一回传到 `values`
+- 建议保持 JSON-safe，避免函数、类实例或不可序列化对象
+
+### 自定义校验
+
+内置 schema 校验（required、类型检查、select 选项范围）之外，可以提供 `validate` 函数做跨字段校验：
+
+```ts
+api.registerUiTool({
+  name: "date_range",
+  label: "选择日期范围",
+  description: "Collect a date range with cross-field validation.",
+  schema: {
+    title: "日期范围",
+    fields: [
+      { name: "startDate", label: "开始日期", type: "date", required: true },
+      { name: "endDate", label: "结束日期", type: "date", required: true },
+    ],
+  },
+  validate(values) {
+    const start = values.startDate as string;
+    const end = values.endDate as string;
+    if (start && end && start > end) {
+      return {
+        valid: false,
+        errors: [{ field: "endDate", message: "结束日期不能早于开始日期。" }],
+      };
+    }
+    return { valid: true };
+  },
+});
+```
+
+`validate` 支持同步和异步返回。内置校验失败时不会调用 `validate`。
+
+### 与 `registerTool` 的区别
+
+| 维度 | `registerTool` | `registerUiTool` |
+|------|---------------|-----------------|
+| 用途 | 通用工具 | 收集前端表单输入 |
+| 开发者关注点 | 完整 `execute` 实现 | 只需提供表单 schema |
+| sessionId | 需要自行处理 | 框架自动绑定 |
+| 暂停/恢复 | 需要手动抛出信号 | 框架自动处理 |
+| 结果校验 | 自行实现 | 内置 schema 校验 + 可选自定义 validator |
+
+### 运行流程
+
+1. LLM 调用 UI 工具 → 自动抛出 `UiToolPauseSignal` 暂停 agent
+2. Runner 捕获信号，发出 `ui_tool_request` 进度事件（包含表单 schema）
+3. 前端根据 schema 渲染标准表单，或结合 `uiExtension` 渲染自定义 UI
+4. 用户提交后，CLI 带 `uiToolResume` 重新调用 agent
+5. 框架自动校验数据（内置 + 自定义 validator）
+6. 校验通过 → 工具返回提交值给 LLM → agent 继续执行
+
+### 导出类型
+
+`@gencode/plugin-sdk` 导出以下 UI 工具相关类型：
+
+- `PluginUiToolDescriptor` — `registerUiTool` 的参数类型
+- `PluginUiToolOptions` — 可选参数（如 `optional`）
+- `UiToolSchema` — 表单 schema
+- `UiToolFieldSchema` — 单个字段定义
+- `UiToolFieldType` — 字段类型联合类型
+- `UiToolValidationError` — 校验错误
+- `UiToolValidationResult` — 校验结果

package/dist/index.d.ts

@@ -2,9 +2,10 @@
  * @gencode/plugin-sdk
  * Thin re-export layer for plugin authors.
  */
-export type { PluginApi, PluginRegistry, PluginRecord, PluginDiagnostic, PluginKind, PluginOrigin, PluginManifest, PluginManifestLoadResult, PluginConfigUiHint, } from "@gencode/agents";
+export type { AgentCustomProgressEvent, PluginApi, PluginRegistry, PluginRecord, PluginDiagnostic, PluginKind, PluginOrigin, PluginManifest, PluginManifestLoadResult, PluginConfigUiHint, PluginProgressEmitter, PluginCustomProgressInput, PluginUiToolDescriptor, PluginUiToolOptions, } from "@gencode/agents";
 export type { MemoryProvider, MemoryProviderContext, MemoryProviderFactory, MemoryProviderRegistration, MemorySearchOptions, MemoryChangeSource, MemoryChangedEvent, MemoryChangedHandler, } from "@gencode/agents";
 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 { UiToolUiExtension, UiToolFieldType, UiToolFieldSchema, 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,SAAS,EACT,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,kBAAkB,GACnB,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"}
+{"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,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gencode/plugin-sdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@gencode/agents": "0.0.6"
+    "@gencode/agents": "0.0.41",
+    "@gencode/shared": "0.0.13"
   },
   "devDependencies": {
     "typescript": "^5.9.3"