dbx-plugin-skill 0.1.6 → 0.1.8

package/package.json

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

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: DBX 插件开发全流程。Use when 创建、开发、调试、打
 | --- | --- | --- |
 | Manifest v1 | `manifest.json` | 插件身份、权限、入口、贡献点、国际化。运行时契约，**拒绝未声明字段** |
 | 构建配置 | `dbx-plugin.toml` | 打包包含哪些目录、是否有原生后端、dev 构建命令。**不进入插件包** |
-| Host API 1.x | `window.dbxPlugin` / Sidecar callback | 沙箱 UI 与 DBX 宿主通信；Host API 1.1 支持 `host/requestUserInput` |
+| Host API 1.x | `window.dbxPlugin` / Sidecar callback | 沙箱 UI 与 DBX 宿主通信；Host API 1.1 支持 `host/requestUserInput`，Host API 1.2 增加估算执行计划 API |
 | Sidecar Protocol v1 | stdin/stdout JSON-RPC | 可选原生后端与 DBX 通信 |
 | 包格式 | `.dbxp`（ZIP 容器） | DBX 实际安装的东西 |
 
@@ -162,6 +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`。工作台持久化小状态使用 `host.storage` 与 `window.dbxPlugin.storage`（单值 256 KiB、插件总量 1 MiB），并检查初始化能力 `capabilities.storage`。
 
 **安全**
 - 密码、Token、私钥**绝不**放进 `config`、Workbench context、事件或日志；需要持久化的敏感值用 `binding: "secret"`。
@@ -238,6 +239,7 @@ node <skill-root>/scripts/dev-logs.mjs --port 5190 [--level error] [--follow] [-
 
 - `Sidecar identity or protocol does not match manifest`：初始化响应里的 `plugin.id`/`version` 与 `manifest.json` 不一致，或协议版本不在双方支持范围内。
 - 改完 UI 页面不刷新：编译型前端需要 `[dev].ui_watch`，且构建成功必须打印**独立一行** `DBX_UI_BUILD_SUCCESS`。
+- 桌面端文件选择、保存和系统拖放通过 `window.dbxPlugin.fileTransfer` 流式处理；Web 宿主没有该对象时回退到 `<input type="file">` 或 Sidecar 自己的传输协议。
 - `manifest.json contains unknown top-level field(s): ...`：写进了 Manifest v1 不接受的字段（常见于手写 `signingKeyId`、`verified`、自定义键）。
 - `... is not covered by [package].include`：`icon` / `ui.entry` 所指文件不在 `[package].include` 声明的目录内。
 - 原生插件 `target 'X' does not match build host 'Y'`：原生包必须在目标平台构建，用 CI 矩阵而不是本机交叉打包。

package/skill/references/host-api.md

@@ -35,6 +35,8 @@ 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` |
 
@@ -43,6 +45,25 @@ const locale = window.dbxPlugin.locale;
 
 计划 API 仅支持宿主允许的只读估算模式；实际执行计划和会产生副作用的语句会被宿主拒绝。初始化消息中的 `capabilities.planApi` 为假或缺失时，应隐藏相关 UI，而不是用请求试探能力。
 
+计划 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 自己的上传协议，不要假设浏览器可读取客户端绝对路径。
+
 ## 3. context 与快照规则
 
 跨边界传递的 context 是 **JSON 数据快照**，宿主会递归剥离 Vue 响应式包装并发送独立副本。因此插件**不能**依赖 Vue ref、Proxy、DOM 节点、函数、组件实例或凭据。

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"`）；`engines.dbx` 可选，是产品版本范围（模板默认 `>=0.5.68`）。
-- 固定权限枚举：`host.events`、`host.binary`、`host.workbench`、`host.filesystem`、`host.plans:read`。
+- `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.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;