@clipbus/plugin-sdk 0.8.7 → 0.9.1

package/docs/item-context.md

@@ -2,7 +2,7 @@
 
 > 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md) · capability 真相源见 [API.md](../API.md)
 
-每个 handler 的 `input` 都遵守 **ItemContext envelope**：
+Detector / attachment renderer 的 `input` 遵守 **ItemContext envelope**：
 
 ```ts
 interface ItemContext {
@@ -12,7 +12,18 @@ interface ItemContext {
 }
 ```
 
-各 handler 在此之上附加专属字段，详见 [entry.md](./entry.md)。
+Action 使用对应的稳定 envelope：
+
+```ts
+interface ActionInput {
+  sourceItem: PluginClipboardItem;
+  content: PluginContentEnvelope;
+  attachments: PluginAttachmentRef[];
+}
+```
+
+其中 `sourceItem` 始终是打开 Action Panel 时的原始 item 身份，
+`content` 是当前级联值。各 handler 的专属字段见 [entry.md](./entry.md)。
 
 ## `PluginContentEnvelope`：三种 kind，字段平铺在顶层
 
@@ -68,7 +79,8 @@ interface PluginClipboardItem {
 
 ## 图片懒副本机制
 
-`input.content`（image 情形）只携带元信息，不带像素。当 detector / action 需要读字节时：
+`input.content`（image 情形）只携带元信息，不带像素。Detector/renderer
+读取原始 item 图片：
 
 ```ts
 const { path } = await ctx.host.item.materializeImagePath();
@@ -77,6 +89,15 @@ const { path } = await ctx.host.item.materializeImagePath();
 
 同一 invocation 多次调用幂等返回同一路径。
 
+Action 读取的是当前级联图片值，必须使用：
+
+```ts
+const { path } = await ctx.host.action.materializeInputImagePath();
+```
+
+当前值可能由上一步从 text/path_reference 生成，因此不能根据
+`sourceItem.type` 决定是否可读取。
+
 ## Attachment 按需读
 
 ```ts
@@ -89,7 +110,10 @@ if (payloadJson) {
 }
 ```
 
-`input.attachments` 给出当前 item 已有的附件引用列表（`{attachmentType, attachmentKey}`）。`readAttachment` 按需拉取真正内容，避免把所有附件塞进入参。
+Detector / attachment renderer 的 `input.attachments` 给出当前 item 已有的附件引用列表（`{attachmentType, attachmentKey}`）。`readAttachment` 按需拉取真正内容，避免把所有附件塞进入参。
+
+Action envelope 为保持协议形状稳定也包含 `attachments`，但 SDK 0.9.0
+宿主当前固定传入 `[]`；Action 不应依赖这里枚举原始 item 的附件。
 
 ## Action 返回图片
 
@@ -105,8 +129,9 @@ module.exports = definePlugin({
   actions: {
     'generate-image': {
       async runAutoAction(input, ctx) {
+        const { path: sourcePath } = await ctx.host.action.materializeInputImagePath();
         const { path } = await ctx.host.action.allocateImageTempPath({ formatHint: 'png' });
-        await fs.writeFile(path, await generateImageBytes(input));
+        await fs.copyFile(sourcePath, path);
         return actionResult.image(path, { imageFormatHint: 'png' });
       },
     },
@@ -126,6 +151,8 @@ WebView 沙箱禁止 `file://`，且 SDK **从不**把真实文件路径暴露
 |---|---|---|---|---|
 | `clipbus.asset.currentItemImageUrl()` | UI | `{}` | `{ url?: string }` | 当前 item **自身**的图（item 非 image kind → `url` 缺失） |
 | `clipbus.asset.pathReferenceImageUrl({ index })` | UI | `{ index }` | `{ url?: string }` | 当前 item 第 `index` 个 `path_reference` 条目的图（越界 / 非图片文件 → `url` 缺失） |
+| `clipbus.asset.currentActionInputImageUrl()` | UI/action | `{}` | `{ url?: string }` | 当前 Action image 值，与原始 item type 无关 |
+| `clipbus.asset.currentActionInputPathReferenceImageUrl({ index })` | UI/action | `{ index }` | `{ url?: string }` | 当前 Action path_reference 中第 `index` 张图 |
 | `host.asset.registerImage({ path })` | runtime | `{ path }` | `{ url: string }` | 把 **Node 产出 / 已有**的本地图注册进当前 session，签发 URL |
 
 capability 完整签名见 [API.md](../API.md)。
@@ -183,4 +210,7 @@ imageUrl.value = url;   // <img :src="imageUrl">
 ```
 
 > **token 生命周期：** URL 绑定当前 session owner，invocation / WebView 释放时一并失效，且跨 owner 隔离——不要持久化或跨会话复用。
-> **何时用哪个：** 显示「当前剪贴板项的图」用 `currentItemImageUrl`；显示「`path_reference` 里的某张图」用 `pathReferenceImageUrl`；显示「插件自己算出来 / 从别处读来的图」用 runtime `registerImage`。
+> **何时用哪个：** renderer 显示原始 item 用 `currentItemImageUrl` /
+> `pathReferenceImageUrl`；Draft Action 显示当前级联值用
+> `currentActionInputImageUrl` / `currentActionInputPathReferenceImageUrl`；
+> 插件自己算出的图用 runtime `registerImage`。

package/docs/manifest.md

@@ -10,7 +10,7 @@
 
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `schemaVersion` | `number` | 是 | 固定 `2` |
+| `schemaVersion` | `number` | 是 | 固定 `3` |
 | `plugin` | `object` | 是 | 插件身份信息 |
 | `install` | `object` | 否 | 安装期 hook 配置 |
 | `runtime` | `object` | 是 | runtime 与 UI 根目录 |
@@ -25,7 +25,7 @@
 
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `plugin.id` | `string` | 是 | 稳定命名空间，建议反向域名（`plugin.example.demo`） |
+| `plugin.id` | `string` | 是 | 稳定命名空间，建议反向域名（`plugin.example.demo`）；仅允许小写字母、数字与 `-` `.` `_`，不含 `..`、不以 `.` 开头，长度 ≤128 |
 | `plugin.title` | `string` | 是 | 显示名称 |
 | `plugin.version` | `string` | 是 | 版本号；宿主按字符串处理 |
 
@@ -98,7 +98,7 @@
 |---|---|---|---|
 | `id` | `string` | 是 | 局部 ID |
 | `title` | `string` | 是 | 显示名称 |
-| `supportedItemTypes` | `string[]` | 是 | `'text' \| 'image' \| 'path_reference'`；非空 |
+| `supportedInputKinds` | `string[]` | 是 | `'text' \| 'image' \| 'path_reference'`；非空；按当前级联值过滤 |
 | `lifecycle` | `'auto-run' \| 'draft'` | 是 | action 生命周期 |
 | `keywords` | `string[]` | 否 | Action catalog 搜索关键词 |
 | `uiEntry` | `string` | 否 | `lifecycle: 'draft'` 时必填 |
@@ -109,7 +109,7 @@
 
 ```json
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "plugin": {
     "id": "plugin.example.sample",
     "title": "Sample Plugin",
@@ -141,7 +141,7 @@
     {
       "id": "sample-apply",
       "title": "Apply Sample",
-      "supportedItemTypes": ["text"],
+      "supportedInputKinds": ["text"],
       "lifecycle": "draft",
       "keywords": ["sample", "apply"],
       "uiEntry": "actions/sample/index.html"
@@ -149,3 +149,11 @@
   ]
 }
 ```
+
+## 从 schema v2 升级
+
+schema v3 是有意的 breaking change。将每个 Action 的
+`supportedItemTypes` 改为 `supportedInputKinds`，并移除
+`inputConstraints`、`possibleResultKinds`（若曾自行添加）。宿主不会把
+v2 Action 适配为 v3；已安装或开发插件会显示“需要更新”，直到 manifest
+和构建产物通过 v3 校验。

package/docs/permissions.md

@@ -23,7 +23,7 @@
 | `setAttachment` | `host.item.setAttachments` |
 | `setSearchExtension` | `host.item.setSearchExtension` |
 
-**不受门控：** `host.clipboard.*`、`host.navigation.*`、`host.settings.*`（只读）、`host.console.log`、`host.action.allocateImageTempPath`、`host.item.materializeImagePath`、`host.item.readAttachment`、所有 `clipbus.*` 中的 UI 专属 verb（`window.*`、`action.setButtons`、`action.complete`、`attachmentRenderer.setButtons` 等）。
+**不受门控：** `host.clipboard.*`、`host.navigation.*`、`host.settings.*`（只读）、`host.console.log`、`host.action.allocateImageTempPath`、`host.action.materializeInputImagePath`、`host.action.allocateOutputFilePath`、`host.item.materializeImagePath`、`host.item.readAttachment`、所有 `clipbus.*` 中的 UI 专属 verb（`window.*`、`action.setButtons`、`action.complete`、`attachmentRenderer.setButtons` 等）。
 
 各 verb 的完整签名见 [API.md](../API.md)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipbus/plugin-sdk",
-  "version": "0.8.7",
+  "version": "0.9.1",
   "type": "module",
   "description": "Typed SDK for authoring Clipbus plugins — runtime (Node.js) and UI (WebView) helpers generated from the Clipbus plugin wire contract.",
   "keywords": [