@dp-bohrium/widget-sdk 0.5.0 → 0.6.0

package/schemas/widget-manifest.schema.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "widget-manifest.schema.json",
+  "description": "打包阶段生成的宿主 Widget 清单；name / description 仅用于首次展示默认值，widgetConfig 为冻结运行配置。",
+  "title": "Widget Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "widgetConfig"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "description": { "type": "string", "maxLength": 2000 },
+    "widgetConfig": { "$ref": "#/$defs/WidgetConfig" }
+  },
+  "$defs": {
+    "WidgetConfig": {
+      "description": "打包阶段生成的冻结 Widget 运行配置；字段由 CLI 从作者清单写入，作者不得再直接覆盖。",
+      "title": "WidgetConfig",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "hostApiVersion",
+        "widgetSdkVersion",
+        "entry",
+        "contribution",
+        "samples"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "hostApiVersion": { "const": 1 },
+        "widgetSdkVersion": { "$ref": "#/$defs/WidgetSdkVersion" },
+        "entry": { "$ref": "#/$defs/EntryPath" },
+        "contribution": { "$ref": "#/$defs/WidgetContributionConfig" },
+        "activationEvents": {
+          "description": "声明 Host 何时允许激活该 Widget；激活条件不授予事件读取能力。",
+          "$ref": "#/$defs/ActivationEvents"
+        },
+        "requestedCapabilities": {
+          "$ref": "#/$defs/RequestedCapabilities"
+        },
+        "requestedPermissions": { "$ref": "#/$defs/HostUserPermissions" },
+        "runtime": { "$ref": "#/$defs/RuntimeOptions" },
+        "samples": { "$ref": "#/$defs/Samples" }
+      }
+    },
+    "HostUserPermission": {
+      "description": "Widget 可申请读取的 Host 用户数据权限名：个人资料或邮箱。",
+      "title": "HostUserPermission",
+      "enum": ["host.user.profile.read", "host.user.email.read"]
+    },
+    "HostUserPermissions": {
+      "description": "Widget 申请的 Host 用户数据权限列表。",
+      "title": "HostUserPermissions",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 2,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/HostUserPermission" }
+    },
+    "RequestedCapabilities": {
+      "description": "Widget 申请的能力集合；声明仅表示申请，最终由 Host 按次授权。",
+      "title": "RequestedCapabilities",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "files": { "$ref": "#/$defs/FilesCapabilityRequest" },
+        "events": { "$ref": "#/$defs/EventsCapabilityRequest" },
+        "tasks": { "$ref": "#/$defs/TasksCapabilityRequest" },
+        "state": { "$ref": "#/$defs/StateCapabilityRequest" },
+        "actions": { "$ref": "#/$defs/ActionsCapabilityRequest" },
+        "network": { "$ref": "#/$defs/NetworkCapabilityRequest" },
+        "presentation": {
+          "$ref": "#/$defs/RequestedPresentationCapability"
+        },
+        "region": {
+          "$ref": "#/$defs/RequestedRegionCapability"
+        }
+      }
+    },
+    "FilesCapabilityRequest": {
+      "description": "文件能力的独立申请开关；保存已有文件必须单独申请 files.write 并获得 Host 授权，可写范围由 Host grant 决定。",
+      "title": "FilesCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "list": { "type": "boolean" },
+        "metadata": { "type": "boolean" },
+        "read": { "type": "boolean" },
+        "download": { "type": "boolean" },
+        "write": { "type": "boolean" }
+      }
+    },
+    "EventsCapabilityRequest": {
+      "description": "事件读取能力的申请；topics 声明要读取的事件主题。",
+      "title": "EventsCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["topics"],
+      "properties": {
+        "topics": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
+          }
+        }
+      }
+    },
+    "TasksCapabilityRequest": {
+      "description": "任务发现与观察能力的申请；list / watch 至少显式申请一项，已申请项固定为 true。",
+      "title": "TasksCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "list": { "const": true },
+        "watch": { "const": true }
+      }
+    },
+    "StateCapabilityRequest": {
+      "description": "受限 UI 状态读写能力的申请；read / write 分别声明。",
+      "title": "StateCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["read", "write"],
+      "properties": {
+        "read": { "type": "boolean" },
+        "write": { "type": "boolean" }
+      }
+    },
+    "ActionsCapabilityRequest": {
+      "description": "Host 自定义动作调用能力的申请；names 声明可调用的动作名。",
+      "title": "ActionsCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["names"],
+      "properties": {
+        "names": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
+          }
+        }
+      }
+    },
+    "NetworkCapabilityRequest": {
+      "description": "Host 托管网络能力的申请；fetch 固定为 true，目标域名由 Host 运行时按请求授权。",
+      "title": "NetworkCapabilityRequest",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fetch"],
+      "properties": {
+        "fetch": { "const": true }
+      }
+    },
+    "RequestedPresentationCapability": {
+      "description": "呈现能力的申请；surfaces 声明期望的呈现表面。",
+      "title": "RequestedPresentationCapability",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["surfaces"],
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "uniqueItems": true,
+          "items": { "enum": ["floating", "overlay"] }
+        }
+      }
+    },
+    "RequestedRegionCapability": {
+      "description": "会话右侧区域替换能力的申请；当前仅支持 session.rightRail + replace。",
+      "title": "RequestedRegionCapability",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["regions", "mode"],
+      "properties": {
+        "regions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "uniqueItems": true,
+          "items": { "const": "session.rightRail" }
+        },
+        "mode": { "const": "replace" }
+      }
+    },
+    "WidgetSdkVersion": {
+      "description": "构建该 Widget 时使用的 SDK 精确 SemVer 版本，不接受范围。",
+      "title": "WidgetSdkVersion",
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+    },
+    "EntryPath": {
+      "description": "包内 ESM 入口路径；仅允许包内相对 POSIX 路径。",
+      "title": "EntryPath",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*://).+\\.m?js$"
+    },
+    "RuntimeOptions": {
+      "description": "运行时申请；worker 与 webAssembly 均为可选布尔开关。",
+      "title": "RuntimeOptions",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "worker": { "type": "boolean" },
+        "webAssembly": { "type": "boolean" }
+      }
+    },
+    "ActivationEvents": {
+      "title": "ActivationEvents",
+      "description": "Host 可用于启动 Widget 的公开激活信号。多个值表示任一信号命中即可激活；它们不授予 events.read 权限。工具名形式为 tool-call-<阶段>:<工具名>。",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/ActivationEvent" }
+    },
+    "ActivationEvent": {
+      "description": "公开 Widget 激活信号。高层 WidgetContext.events 使用事件 type；低层 events.read 的 topic 不填写在这里。",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "session.start",
+            "turn-start",
+            "turn-end",
+            "step-start",
+            "step-end",
+            "tool-call-generating",
+            "tool-call-waiting",
+            "tool-call-running",
+            "tool-call-result",
+            "tool-call-error",
+            "workspace-file-changed",
+            "workspace-tree-refresh",
+            "workspace-file-opened",
+            "ui-tool-opened",
+            "ui-panel-focused",
+            "host-surface-changed"
+          ]
+        },
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^tool-call-(?:generating|waiting|running|result|error):[A-Za-z0-9_.:-]+$"
+        }
+      ]
+    },
+    "Samples": {
+      "description": "同版本 RenderRequest 测试样例；至少一个，request 为相对 .json 路径。",
+      "title": "Samples",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "request"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "title": { "type": "string", "minLength": 1, "maxLength": 128 },
+          "request": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*://).+\\.json$"
+          }
+        }
+      }
+    },
+    "WidgetContributionConfig": {
+      "description": "作者声明的扩展点配置：file-preview 声明扩展名集合，panel 绑定既有 Panel。",
+      "title": "WidgetContributionConfig",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "extensions"],
+          "properties": {
+            "type": { "const": "file-preview" },
+            "extensions": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 32,
+                "pattern": "^[a-z0-9][a-z0-9.-]*$"
+              }
+            }
+          }
+        },
+        { "$ref": "#/$defs/PanelContributionConfig" }
+      ]
+    },
+    "PanelContributionConfig": {
+      "title": "PanelContributionConfig",
+      "description": "绑定 Agent Widget 既有 Panel 的配置。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": {
+          "description": "Panel 贡献类型。",
+          "const": "panel"
+        },
+        "id": {
+          "description": "Host 注册和查找 Panel 时使用的稳定类型标识。",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_.:-]+$"
+        },
+        "placement": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind"],
+              "properties": {
+                "kind": { "const": "panel" }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "region", "mode"],
+              "properties": {
+                "kind": { "const": "region" },
+                "region": { "const": "session.rightRail" },
+                "mode": { "const": "replace" }
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/widget-plugin-manifest.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "widget-plugin-manifest.schema.json",
+  "title": "Widget Plugin Manifest",
+  "description": "插件作者维护的插件清单；打包阶段会生成宿主清单的运行时字段。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "version",
+    "contributes"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
+    },
+    "displayName": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 2000
+    },
+    "entry": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*://).+\\.(?:[cm]?js|tsx?|jsx?)$",
+      "description": "插件源码入口；CLI 默认使用 src/widget.ts。"
+    },
+    "activationEvents": {
+      "$ref": "widget-manifest.schema.json#/$defs/ActivationEvents"
+    },
+    "contributes": {
+      "$ref": "#/$defs/WidgetPluginContributions"
+    },
+    "capabilities": {
+      "$ref": "widget-manifest.schema.json#/$defs/RequestedCapabilities"
+    },
+    "runtime": {
+      "$ref": "widget-manifest.schema.json#/$defs/RuntimeOptions"
+    },
+    "samples": {
+      "$ref": "widget-manifest.schema.json#/$defs/Samples"
+    }
+  },
+  "$defs": {
+    "WidgetPluginContributions": {
+      "description": "插件声明的一组扩展点；当前仅支持 widget 贡献点。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "widget"
+      ],
+      "properties": {
+        "widget": {
+          "$ref": "#/$defs/WidgetContribution"
+        }
+      }
+    },
+    "WidgetContribution": {
+      "description": "作者贡献点联合：以 type 判别 Panel 或文件预览。",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/WidgetPanelContribution"
+        },
+        {
+          "$ref": "#/$defs/WidgetFilePreviewContribution"
+        }
+      ]
+    },
+    "WidgetPanelContribution": {
+      "description": "面板贡献：声明 panel 类型与 id；surfaces、title、placement 可选。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "id"
+      ],
+      "properties": {
+        "type": {
+          "const": "panel"
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9_.:-]+$"
+        },
+        "title": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "surfaces": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 3,
+          "uniqueItems": true,
+          "items": { "enum": ["workspace", "floating", "overlay"] }
+        },
+        "placement": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind"],
+              "properties": {
+                "kind": { "const": "panel" }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "region", "mode"],
+              "properties": {
+                "kind": { "const": "region" },
+                "region": { "const": "session.rightRail" },
+                "mode": { "const": "replace" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "WidgetFilePreviewContribution": {
+      "description": "文件预览贡献：声明一组小写且不含前导点的扩展名。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "extensions"
+      ],
+      "properties": {
+        "type": {
+          "const": "file-preview"
+        },
+        "extensions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 32,
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          }
+        }
+      }
+    }
+  }
+}