dbx-plugin-skill 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbx-plugin-skill",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "DBX 插件开发 skill：覆盖插件创建、开发、调试、打包、发布到 dbx-store 上架的全流程，安装到 DSH / Claude Code / agents 技能目录",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -162,7 +162,7 @@ dbx-plugin package .
 **权限**
 - 只声明真正用到的权限，取最小集合：`host.workbench`、`host.events`、`host.filesystem`、`host.binary`、`host.plans:read`、`host.network:https://host[:port]`（HTTPS、无路径/通配符/Token，最多 8 个）。`host.plans:read` 仅开放宿主生成的估算执行计划读取。
 - `host.network` 只影响浏览器 CSP 的 `connect-src`，**不是** Sidecar 的网络防火墙，也仍受目标服务 CORS 约束。
-- 估算执行计划 API 属于 Host API 1.2：需要 `host.plans:read`，并同时检查初始化能力 `capabilities.planApi` 与连接级支持；若插件无法在缺少该能力时工作，在 `engines.host_api` 声明 `^1.2`。
+- 估算执行计划 API 属于 Host API 1.2：需要 `host.plans:read`，并同时检查初始化能力 `capabilities.planApi` 与连接级支持；若插件无法在缺少该能力时工作，在 `engines.host_api` 声明 `^1.2`。工作台持久化小状态使用 `host.storage` 与 `window.dbxPlugin.storage`（单值 256 KiB、插件总量 1 MiB），并检查初始化能力 `capabilities.storage`。
 
 **安全**
 - 密码、Token、私钥**绝不**放进 `config`、Workbench context、事件或日志；需要持久化的敏感值用 `binding: "secret"`。

package/skill/references/host-api.md

@@ -35,6 +35,7 @@ const locale = window.dbxPlugin.locale;
 | `openWorkbench(id, context)` | 打开本插件另一个工作台 | `host.workbench` |
 | `openFilesystem(id, context)` | 打开本插件的文件系统入口 | `host.filesystem` |
 | `getPlanCapabilities(connectionId)` / `explainPlan(request)` | 读取指定连接的估算执行计划 | `host.plans:read` |
+| `storage.get(key)` / `storage.set(key, value)` / `storage.delete(key)` | 持久化本插件工作台的小型 JSON 状态 | `host.storage` |
 | `fileTransfer` | 桌面端经用户明确同意后的本地文件选择、保存和系统拖放流；Web 宿主通常不提供 | — |
 | `onInit(fn)` | 监听初始化/环境变化 | — |
 | `onEvent(fn)` | 监听后端事件 | `host.events` |
@@ -46,6 +47,19 @@ const locale = window.dbxPlugin.locale;
 
 计划 API 属于 Host API 1.2。若插件不能在旧宿主上降级，应在 Manifest 中声明 `engines.host_api: "^1.2"`；即使声明了版本下限，也要保留 `capabilities.planApi` 的运行时检查。
 
+### 持久化 UI 状态
+
+`window.dbxPlugin.storage` 为每个插件隔离的 JSON 键值存储，数据位于宿主的 `plugin-data/<id>` 下。单个值最大 256 KiB，插件总量最大 1 MiB；大数据应放到 Sidecar 的 `DBX_PLUGIN_DATA_DIR`。旧宿主不会提供该能力，调用前检查初始化消息中的 `capabilities.storage`，并在无法降级时把 `host.storage` 作为必要权限、把 `engines.host_api` 设置为对应的最低版本。
+
+```js
+await window.dbxPlugin.ready;
+if (window.dbxPlugin.capabilities.storage) {
+  await window.dbxPlugin.storage.set("filters", { sort: "name" });
+  const filters = await window.dbxPlugin.storage.get("filters");
+  await window.dbxPlugin.storage.delete("filters");
+}
+```
+
 ### 桌面文件传输与系统拖放
 
 桌面宿主可通过 `window.dbxPlugin.fileTransfer` 将用户明确选择或拖入工作台的本地文件按分块提供给插件。使用 `pick`/`beginSave` 打开原生对话框，使用 `read` 逐块读取；拖放通过 `onDrop` 接收。Web 宿主没有 `fileTransfer` 时应回退到 `<input type="file">` 或 Sidecar 自己的上传协议，不要假设浏览器可读取客户端绝对路径。

package/skill/references/manifest.md

@@ -40,14 +40,16 @@
     "host.filesystem",
     "host.binary",
     "host.plans:read",
+    "host.storage",
     "host.network:https://s3.example.com:443"
   ]
 }
 ```
 
 - `engines.host_api` 必需（`minLength: 1`，推荐 `"1"` 或 `"^1.0"`）；依赖估算执行计划 API 的插件应声明 `"^1.2"`，并仍在运行时检查 `capabilities.planApi`；`engines.dbx` 可选，是产品版本范围（模板默认 `>=0.5.68`）。
-- 固定权限枚举：`host.events`、`host.binary`、`host.workbench`、`host.filesystem`、`host.plans:read`。
+- 固定权限枚举：`host.events`、`host.binary`、`host.workbench`、`host.filesystem`、`host.plans:read`、`host.storage`。
 - `host.plans:read` 只允许读取宿主生成的**估算执行计划**，不允许执行 SQL、写入、DDL/DML 或实际计划；调用前检查初始化能力中的 `planApi`。
+- `host.storage` 只允许使用工作台专属的小型 JSON 状态存储；单个值上限 256 KiB、每个插件总量上限 1 MiB，不能借此访问任意文件。调用前检查初始化能力中的 `storage`。
 - 网络权限 `host.network:https://<host>[:port]`：
   - **必须 HTTPS**；主机名只允许 `[A-Za-z0-9._-]`，端口可选数字；
   - **不允许路径、通配符、Token**；

package/skill/scripts/check-project.mjs

@@ -34,7 +34,7 @@ const MANIFEST_TOP_FIELDS = [
   "localizations",
 ];
 
-const STATIC_PERMISSIONS = ["host.events", "host.binary", "host.workbench", "host.filesystem"];
+const STATIC_PERMISSIONS = ["host.events", "host.binary", "host.workbench", "host.filesystem", "host.plans:read", "host.storage"];
 const NETWORK_PERMISSION = /^host\.network:https:\/\/[A-Za-z0-9._-]+(?::[0-9]+)?$/;
 const MAX_NETWORK_PERMISSIONS = 8;