dbx-plugin-skill 0.1.4 → 0.1.6

package/package.json

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

package/skill/SKILL.md

@@ -160,7 +160,7 @@ dbx-plugin package .
 - 已废弃字段会被 CLI 拒绝：`entrypoints.ui.kind`、`entrypoints.backend.binaries`、`entrypoints.backend.protocol`。
 
 **权限**
-- 只声明真正用到的权限，取最小集合：`host.workbench`、`host.events`、`host.filesystem`、`host.binary`、`host.network:https://host[:port]`（HTTPS、无路径/通配符/Token，最多 8 个）。
+- 只声明真正用到的权限，取最小集合：`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 约束。
 
 **安全**

package/skill/references/contributions.md

@@ -205,6 +205,18 @@ SSH 作为最后一层时，路由是该跳板的动态 SOCKS5 端点；配置 S
 | `filesystem/delete` | `uri`、`recursive` | `{ success, message?, entry? }` |
 | `filesystem/rename` | `sourceUri`、`targetUri`、`overwrite` | `{ success, message?, entry? }` |
 
+### 宿主托管下载（`filesystem/download/*`）
+
+需要把远端对象保存到用户本地文件时，DBX 桌面宿主会管理保存对话框、临时文件、取消和进度，并调用插件后端的下载生命周期：
+
+1. `filesystem/download/open`：接收完整的下载选择参数（其中必须包含 `downloadId`，以及插件所需的 `providerId`、`connectionId` 等字段），返回对象元数据，至少包含 `size`。
+2. `filesystem/download/read`：重复读取分块，返回 `{ dataBase64, done }`。每个分块解码后不得超过 1 MiB；未完成时不能返回空分块。
+3. `filesystem/download/close`：无论成功、取消还是失败都会调用，用于释放插件侧会话。
+
+从 DBX `1511f11be1de3060e9ecdc51d86c90a1757a70a0` 的 `src-tauri/src/commands/plugin_download.rs` 变更起，`read` 与 `close` 的控制参数固定为 `{ downloadId, providerId, connectionId }`，不再重复携带 `open` 的完整选择参数。插件应按 `downloadId` 保存会话状态，并允许 `close` 幂等；不要假设每个分块请求都带有对象路径、筛选器或其它大字段。
+
+这条宿主托管下载通道与 `stdio-framed` 大文件流不同：它通过 JSON/base64 分块写入用户选择的本地文件；需要双向流、PTY/SFTP 或更大分块时，仍使用 framed 二进制通道和插件自定义的确认、取消、进度协议。
+
 ### 目录项与分页规则
 
 - 每项包含：`name`（**单个文件名**，不含 `/`、`\`，不能是 `.` 或 `..`）、完整 `uri`、`kind`（`file` | `directory` | `symlink` | `other`），可选 `size`、`modifiedAt`、`contentType`。

package/skill/references/host-api.md

@@ -34,12 +34,15 @@ const locale = window.dbxPlugin.locale;
 | `readAssetUrl(path)` | 读取包内资源并返回对象 URL | — |
 | `openWorkbench(id, context)` | 打开本插件另一个工作台 | `host.workbench` |
 | `openFilesystem(id, context)` | 打开本插件的文件系统入口 | `host.filesystem` |
+| `getPlanCapabilities(connectionId)` / `explainPlan(request)` | 读取指定连接的估算执行计划 | `host.plans:read` |
 | `onInit(fn)` | 监听初始化/环境变化 | — |
 | `onEvent(fn)` | 监听后端事件 | `host.events` |
 
 常用 Host 内部方法（通过 `request` 调用）：`host.getContext`、`ui.readAsset`。
 **只调用协议中声明的方法**，不要调用未公开的 DBX 内部函数。
 
+计划 API 仅支持宿主允许的只读估算模式；实际执行计划和会产生副作用的语句会被宿主拒绝。初始化消息中的 `capabilities.planApi` 为假或缺失时，应隐藏相关 UI，而不是用请求试探能力。
+
 ## 3. context 与快照规则
 
 跨边界传递的 context 是 **JSON 数据快照**，宿主会递归剥离 Vue 响应式包装并发送独立副本。因此插件**不能**依赖 Vue ref、Proxy、DOM 节点、函数、组件实例或凭据。

package/skill/references/manifest.md

@@ -39,13 +39,15 @@
     "host.events",
     "host.filesystem",
     "host.binary",
+    "host.plans:read",
     "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.events`、`host.binary`、`host.workbench`、`host.filesystem`、`host.plans:read`。
+- `host.plans:read` 只允许读取宿主生成的**估算执行计划**，不允许执行 SQL、写入、DDL/DML 或实际计划；调用前检查初始化能力中的 `planApi`。
 - 网络权限 `host.network:https://<host>[:port]`：
   - **必须 HTTPS**；主机名只允许 `[A-Za-z0-9._-]`，端口可选数字；
   - **不允许路径、通配符、Token**；

package/skill/references/publishing.md

@@ -2,7 +2,7 @@
 
 > 本文件的结论来自 `t8y2/dbx-store` 当前源码（`CONTRIBUTING.md`、`scripts/validate.mjs`、`scripts/sync-release-candidate.mjs`、`scripts/discover-plugin-releases.mjs`、`scripts/finalize-candidates.mjs`、`.github/workflows/*`）与 `t8y2/dbx/plugins/RELEASING.md`。**当文档与脚本冲突时，以脚本为准** —— 文末列出已确认的冲突点。
 >
-> 上游 `plugins/RELEASING.md` 仍描述「先开 Issue、再开 catalog PR」的两段式流程；**当前实际流程是「一个 PR」**，以 `dbx-store/CONTRIBUTING.md` 为准。
+> `dbx-store/CONTRIBUTING.md` 是当前提交流程的事实来源：**一个 PR** 同时承载候选、审核、受保护签名和目录回写。上游 `plugins/RELEASING.md` 中仍保留的“先开 Issue”文字已过时，不要照做。
 
 ## 1. 四类产物，四个归属
 
@@ -187,7 +187,7 @@ node <skill-root>/scripts/make-candidate.mjs . --release-notes "Initial release.
 
 1. 改代码 → **递增 `manifest.json` 的 `version`**（不要复用旧版本号）。
 2. 打新源码 Tag、发新 Release；**旧 Release 资产不可覆盖**。
-3. 若仓库已登记 `autoUpdate: true`，Store 的**每小时**同步 Workflow 会在最新 Release 中找到 `release-candidates.json`，自动创建/更新候选 PR：
+3. 若仓库已登记 `autoUpdate: true`，Store 的同步 Workflow 每小时左右（每 15 分钟排程以抵御 GitHub 调度丢失）会在最新 Release 中找到 `release-candidates.json`，自动创建/更新候选 PR：
    - 分支 `automation/plugin-release/<plugin-id>/<version>`
    - PR 标题 `feat(store): submit <plugin-id>@<version>`
    - 候选内容未变化时**不提交不推送**（幂等）