dbx-plugin-skill 0.1.0

package/skill/references/publishing.md

@@ -0,0 +1,374 @@
+# 发布与上架（dbx-store）参考
+
+> 本文件的结论来自 `t8y2/dbx-store` 当前源码（`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` 为准。
+
+## 1. 四类产物，四个归属
+
+| 产物 | 存放在哪 | 谁维护 |
+| --- | --- | --- |
+| 插件源码 | 你自己的仓库 | 你 |
+| 未签名候选 `.dbxp` + `.artifact.json` + `release-candidates.json` | 你自己仓库的 GitHub Release / CDN / 对象存储 | 你的 CI（`dbx-plugin package`） |
+| 最终签名 `.dbxp` + `.artifact.json` + `.signing-receipt.json` | DBX Store 控制的 R2（`https://dl.dbxio.com/plugins/...`） | DBX Store 受保护 Workflow |
+| 目录元数据 `plugins/<id>.json`、`catalog/index.json` | `t8y2/dbx-store` Git 仓库 | 签名 Workflow 生成，维护者合并 |
+
+**开发者永远不接触官方私钥。**
+
+## 2. 提交位置速查
+
+| 你要改的 | 提到哪 |
+| --- | --- |
+| 插件功能代码 | 你自己的仓库 |
+| 上架 / 版本更新 / 商店文案 | `t8y2/dbx-store` → `main` |
+| Host / SDK / CLI / Schema / 官方示例 / 插件文档 | `t8y2/dbx` → `main` |
+| 第三方插件自身的 Bug | 那个插件的仓库 |
+
+## 3. 插件仓库里的 `.dbx-store.json`（可选）
+
+放在**插件源码仓库根目录**（路径由 `dbx-store/automation/plugin-sources.json` 的 `metadataPath` 配置，默认 `.dbx-store.json`）。它在**每个 Release tag** 上被读取，用于商店展示字段。
+
+```json
+{
+  "name": "Example Files",
+  "description": "Browse files from an example service.",
+  "icon": "assets/plugin.svg",
+  "tags": ["files", "storage"],
+  "permissions": ["host.workbench"],
+  "source": "https://github.com/example/dbx-plugin-files",
+  "homepage": "https://github.com/example/dbx-plugin-files",
+  "license": "Apache-2.0",
+  "releaseNotes": "Initial release.",
+  "localizations": {
+    "zh-CN": { "name": "示例文件", "description": "浏览示例服务的文件。" }
+  }
+}
+```
+
+- **允许字段恰好是这 10 个**：`name`、`description`、`icon`、`tags`、`permissions`、`source`、`homepage`、`license`、`releaseNotes`、`localizations`。多任何键 → `Unsupported store metadata field '<k>'`。
+- **首次上架必需**：`name` 和 `license`（否则 `New plugins require store metadata 'name'` / `'license'`）。
+- `icon` 写相对路径时会被自动转成该 tag 下的 `raw.githubusercontent.com` HTTPS 地址；写绝对 URL 则原样使用。**必须是 `.svg` 或 `.png`**。
+- `releaseNotes` 是**唯一**进入目录 `versions[].releaseNotes` 的来源 —— GitHub Release 的正文不会被读取。
+- **身份与 target 不能从这里设置**：`id`、`publisher`、`version`、`targets`、`schemaVersion`、`verified`、`latestVersion`、`releasedAt` 及所有 artifact 字段都由别处决定。
+- 版本更新时**不需要**改它；只在首次登记或确实要改展示信息时更新。但它每次同步都会被重新读取，所以改了就会带进下一次候选。
+
+## 4. `release-candidates.json`（Release 资产）
+
+由你的 Release 工作流产出，作为 **Release 资产**上传，文件名必须**恰好**是 `release-candidates.json`。
+
+```json
+{
+  "plugin": {
+    "id": "com.example.plugin",
+    "publisher": "example",
+    "version": "1.0.0",
+    "name": "Example Plugin",
+    "description": "Browse files from an example service."
+  },
+  "artifacts": [
+    {
+      "target": "darwin-arm64",
+      "url": "com.example.plugin-1.0.0-darwin-arm64.dbxp",
+      "sha256": "0f0e...（64 位十六进制，未签名候选包）",
+      "size": 12345678
+    }
+  ]
+}
+```
+
+**最关键的一条：`artifacts[].url` 必须是纯文件名，不是 URL。**
+
+同步脚本用 `path.posix.basename` + 正则 `^[A-Za-z0-9._-]+\.dbxp$` 校验，然后**自己拼出**
+`https://github.com/<你的仓库>/releases/download/<tag>/<文件名>`。
+
+| `url` 写法 | 结果 |
+| --- | --- |
+| `a.dbxp` | ✅ |
+| `a.dbxp?x=1` | ✅（query 被忽略） |
+| `sub/a.dbxp` | ❌ `Invalid candidate artifact` |
+| `https://github.com/.../a.dbxp` | ❌ 完整 URL 被拒 |
+| `a.zip` | ❌ 必须以 `.dbxp` 结尾 |
+| `a-1.2.3+build.dbxp` | ❌ `+` 不在允许字符集内 |
+
+其他硬约束：
+
+- `plugin.id` / `plugin.publisher` / `plugin.version` 必需；`artifacts` 非空。
+- `target` 必须匹配 `^[a-z0-9-]{1,64}$` 且唯一。
+- `sha256` 64 位十六进制；`size` 1 … 512 MiB。
+- **`+build` 版本号会破坏自动化链路**（拼出的文件名含 `+`）—— 上架版本不要用 build metadata。
+
+用随附脚本从 `dist/*.artifact.json` 生成，避免手写出错：
+
+```bash
+node <skill-root>/scripts/make-candidate.mjs . --release-notes "Initial release."
+# 产出 dist/candidates/<id>.json 与 dist/release-candidates.json，并复核每个包的 sha256/size
+```
+
+## 5. 候选文件 `candidates/<plugin-id>.json`
+
+这是提到 `dbx-store` 的 PR 内容。**允许的顶层键恰好 15 个**：
+
+`schemaVersion`、`id`、`publisher`、`version`、`releaseNotes`、`name`、`description`、`icon`、`tags`、`permissions`、`source`、`homepage`、`license`、`localizations`、`targets`。
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "com.example.plugin",
+  "publisher": "example",
+  "version": "1.0.0",
+  "name": "Example Plugin",
+  "description": "One-line description shown in the marketplace.",
+  "icon": "https://example.com/icon.svg",
+  "tags": ["files"],
+  "permissions": ["host.events"],
+  "source": "https://github.com/example/dbx-plugin/tree/v1.0.0",
+  "homepage": "https://github.com/example/dbx-plugin",
+  "license": "Apache-2.0",
+  "releaseNotes": "Initial release.",
+  "targets": [
+    {
+      "target": "darwin-arm64",
+      "url": "https://github.com/example/dbx-plugin/releases/download/v1.0.0/com.example.plugin-1.0.0-darwin-arm64.dbxp",
+      "sha256": "0f0e...64 位十六进制...",
+      "size": 12345678
+    }
+  ]
+}
+```
+
+| 字段 | 必需 | 约束 |
+| --- | --- | --- |
+| `schemaVersion` | 是 | 必须 `1` |
+| `id` | 是 | `^[a-z0-9][a-z0-9._-]{0,127}$`；**文件名必须是 `<id>.json`** |
+| `publisher` | 是 | 同 id 规则，且**必须在 `publishers/` 已登记**并拥有该插件 |
+| `version` | 是 | SemVer；不能已列出，不能已撤销 |
+| `name` | **新插件必需** | 非空 |
+| `source` | **新插件必需** | 必须 `https://` |
+| `license` | **新插件必需** | 非空 |
+| `description` / `icon` / `homepage` / `tags` / `permissions` / `releaseNotes` / `localizations` | 否 | 出现时必须**非空**；`icon`/`homepage` 允许 http(s)；`tags`/`permissions` 为唯一非空字符串数组；`localizations` 每项只允许 `name`、`description` |
+| `targets` | 是 | 非空数组 |
+
+`targets[]` 每项**恰好 4 个键**：`target`（`^[a-z0-9-]{1,64}$`，唯一）、`url`（**HTTPS**）、`sha256`（64 位十六进制）、`size`（1 … 512 MiB）。
+
+### 绝对不要放进候选
+
+- `signingKeyId` —— 属于商店 artifact metadata，候选里出现会报 `contains unknown field(s): signingKeyId`。
+- `verified` —— 候选里出现同样报未知字段。`verified` 由维护者决定，签名时硬编码为 `false`。
+- **指向 `t8y2/dbx-store` Release 的 URL** → `candidate URLs must not reference DBX Store releases; submit the unsigned candidate artifact`。
+- 任何非 HTTPS URL。
+
+## 6. 发布者记录 `publishers/<publisher-id>.json`
+
+**只在首次上架时需要**，且只允许 3 个字段：
+
+```json
+{ "id": "example", "name": "Example", "status": "unverified" }
+```
+
+- `id` 匹配 `^[a-z0-9][a-z0-9._-]{0,127}$`，文件名必须是 `<id>.json`，不可重复。
+- `name` 非空；`status` 非空（实践中只用 `verified` / `unverified`）。
+- **不含联系人/邮箱/URL 要求**，也不含任何密钥。
+- `publisher` 字段引用的是记录的 **`id`**，不是 `name`。
+
+> ⚠️ **实测坑（文档未提）**：签名 Workflow 会先把 base 分支的 `publishers/` 覆盖回 PR 分支，**PR 里新增的 `publishers/<新id>.json` 会被删除**，随后校验失败 `publisher '<id>' is not registered`。
+> **实践做法**：新发布者记录必须先落到 `main`（单独提一个只加 publisher 的 PR 并合并，或请维护者登记），**再**在候选 PR 上运行 `/sign`。
+
+## 7. 首次上架流程
+
+1. 插件源码放在**公开可审阅**的仓库。
+2. 每个支持的 target 构建未签名 `.dbxp`，发布到不可变 HTTPS 地址（Release / 对象存储 / CDN）。
+3. Fork `t8y2/dbx-store`，向 `main` 提**一个** PR：
+   - `publishers/<publisher-id>.json`（仅首次，**但要先合并到 main**，见 §6 的坑）；
+   - `candidates/<plugin-id>.json`。
+4. 按 PR 模板填写：插件 ID/版本/发布者、源码仓库 + 精确 tag、capabilities、**每一项 Manifest 权限**以及数据/网络访问、原生 Sidecar 行为（纯前端写 None）、license、主页/支持地址。
+5. CI 会**故意保持红色**：`open candidate(s) awaiting DBX Store signing` —— 这是为了阻止未签名内容被合并。
+6. 维护者审核后运行受保护签名 Workflow（PR 下评论 `/sign`，或手动 `workflow_dispatch` 指定 PR 号）。
+7. Workflow 回写 `plugins/<id>.json`、重建的 `catalog/index.json` 并删除 `candidates/<id>.json`，同时把签名包发到 R2。
+8. CI 转绿后由维护者合并。
+
+## 8. 版本更新流程
+
+1. 改代码 → **递增 `manifest.json` 的 `version`**（不要复用旧版本号）。
+2. 打新源码 Tag、发新 Release；**旧 Release 资产不可覆盖**。
+3. 若仓库已登记 `autoUpdate: true`，Store 的**每小时**同步 Workflow 会在最新 Release 中找到 `release-candidates.json`，自动创建/更新候选 PR：
+   - 分支 `automation/plugin-release/<plugin-id>/<version>`
+   - PR 标题 `feat(store): submit <plugin-id>@<version>`
+   - 候选内容未变化时**不提交不推送**（幂等）
+4. 未登记则手工提 `candidates/<plugin-id>.json`，**只写新版本**。
+5. 审核 → `/sign` → 合并。
+
+**省略的展示字段保持当前值，写了的字段会替换。** 新版本不需要动 `.dbx-store.json`。
+
+## 9. 只改商店展示信息
+
+更新 `.dbx-store.json` 并在**新 Release tag** 上发布 → 同步器读取该 tag 下的文件 → 带进下一次候选。
+
+注意：同步是**由 Release 驱动**的，而且候选只有在签名后才最终生效。所以「只改文案」也要走一次 Release + 审核 + 签名。
+
+## 10. 自动同步的登记与触发
+
+`dbx-store/automation/plugin-sources.json`：
+
+```json
+{
+  "version": 1,
+  "plugins": [
+    { "repository": "owner/repo", "metadataPath": ".dbx-store.json", "autoUpdate": true }
+  ]
+}
+```
+
+- 只有 `autoUpdate: true` 的条目会被处理（缺省即跳过）。
+- `repository` 必须匹配 `^[^/]+/[A-Za-z0-9._-]+$`；`metadataPath` 不能含 `..`。
+- 同步只在**最新**的（非 draft、非 prerelease）Release 中查找名为 `release-candidates.json` 的资产；找不到就静默跳过（`No published candidate release found for <repo>`）。只拉取最近 30 个 Release。
+- 想让你的仓库加入自动同步，向 `dbx-store` 提一个登记 PR，或请维护者登记。**插件仓库不需要配置任何自动化 Secret。**
+
+## 11. 审核与签名
+
+### `/sign` 触发
+
+- 在候选 PR 下评论 `/sign`（目前只有维护者账号 `t8y2` 可以触发；命令以 `issue_comment` 事件运行，用的是默认分支的 Workflow 定义，PR 无法篡改这道闸门）。
+
+### 手动签名 Workflow 输入
+
+`candidate-url`、`candidate-sha256`、`candidate-size`、`output-name`、`plugin-id`、`publisher`、`version`、`target`、`sdk-ref`。
+
+- `output-name` 必须**恰好等于** `<plugin-id>-<version>-<target>.dbxp`。
+- `sdk-ref` 决定用哪个 DBX 版本里的 packager 契约。
+
+### 签名前会验证什么
+
+1. 输入格式（HTTPS、64 位十六进制 sha256、size 范围、id/publisher/version/target/output-name 规则）。
+2. 仓库密钥已登记、`status: "active"`、未撤销。
+3. 下载候选包，重算 SHA-256 与 size，必须与审核值一致。
+4. 包内**没有 `signature.json`**（`Official signing accepts only unsigned candidates`）。
+5. 包内 `manifest.json` 的 `id`/`publisher`/`version` 与候选完全一致。
+
+### 签名后产出
+
+- `<id>-<version>-<target>.dbxp`（含 Ed25519 签名）
+- `<id>-<version>-<target>.artifact.json`（含 `signingKeyId`）
+- `<id>-<version>-<target>.signing-receipt.json`
+
+发布路径（R2，全部**不可覆盖**）：
+
+```
+plugins/<plugin-id>/<version>/<id>-<version>-<target>.dbxp
+plugins/<plugin-id>/<version>/<id>-<version>-<target>.artifact.json
+plugins/<plugin-id>/<version>/<id>-<version>-<target>.signing-receipt.json
+```
+
+已存在同名对象 → `R2 object already exists and cannot be overwritten`。**改字节就必须升版本。**
+
+## 12. 目录与密钥
+
+生成后的 `plugins/<id>.json`（不要手工编辑）形如：
+
+```json
+{
+  "id": "com.example.plugin",
+  "name": "Example Plugin",
+  "description": "...",
+  "publisher": "example",
+  "verified": false,
+  "icon": "https://dl.dbxio.com/plugins/com.example.plugin/1.0.0/icon.svg",
+  "tags": ["files"],
+  "permissions": ["host.events"],
+  "source": "https://github.com/example/dbx-plugin/tree/<commit>",
+  "homepage": "https://github.com/example/dbx-plugin",
+  "license": "Apache-2.0",
+  "latestVersion": "1.0.0",
+  "versions": [
+    {
+      "version": "1.0.0",
+      "releasedAt": "2026-09-16T05:28:49.440Z",
+      "releaseNotes": "Initial release.",
+      "artifacts": [
+        {
+          "target": "darwin-arm64",
+          "url": "https://dl.dbxio.com/plugins/com.example.plugin/1.0.0/com.example.plugin-1.0.0-darwin-arm64.dbxp",
+          "sha256": "5e5c...",
+          "signingKeyId": "dbx-store-release-2026",
+          "size": 30810286
+        }
+      ]
+    }
+  ],
+  "localizations": { "zh-CN": { "name": "示例插件", "description": "..." } }
+}
+```
+
+- **没有 `$schema` 字段**，也没有 `releases[]` —— 结构是 `versions[]`（每版一项）→ `artifacts[]`（每 target 一项，恰好 5 个键）。
+- `releasedAt` 由签名者设置；`latestVersion` 由签名流程按 semver 重算。
+- **图标在目录里被硬编码重写为 `https://dl.dbxio.com/plugins/<id>/<latestVersion>/icon.<svg|png>`**，扩展名取自原图标，只接受 SVG/PNG。
+- 目录消费地址：
+
+```text
+https://raw.githubusercontent.com/t8y2/dbx-store/main/catalog/index.json
+```
+
+### 签名密钥与撤销
+
+- `signing-keys.json` 的 key 状态：`preview`（**目录里禁止使用**）、`active`、`retired`。`algorithm` 必须是 `ed25519`，`purpose` 必须是 `repository-package-signing`，`publicKey` 必须是 base64 的 32 字节。
+- 自定义/私有仓库才用 `dbx-plugin keygen`；官方商店作者不需要。
+- 轮换：**换新 Key ID**，先让支持的 DBX 版本信任新公钥，再停用旧 key。泄露的 key 记入 `revoked.json`，旧 ID 永不复用。
+- `revoked.json` 可撤销插件版本（`{ "pluginId": "...", "version": "..." }`）或签名 key ID。
+
+## 13. 提交 PR 中不能包含
+
+- 插件源码目录、完整源码副本
+- `.dbxp` 二进制（仓库校验器会拒绝**任何**位置的 `.dbxp`）
+- Ed25519 私钥、Token、下载凭据
+- `plugins/*.json` 或 `catalog/index.json` 的手工改动
+- 把未签名候选 URL 当作最终下载地址
+- 自行伪造 `verified: true`
+- 工作区中任何 **> 1 MiB** 的文件（`validate.mjs` 会扫描整个工作树，包括未跟踪/被 gitignore 的文件）
+
+## 14. 已确认的「文档 vs 脚本」冲突
+
+| # | 文档说 | 脚本实际 |
+| --- | --- | --- |
+| 1 | `CONTRIBUTING.md` 说首次 PR 携带 `publishers/<id>.json` 即可 | 签名 overlay 会删除 PR 新增的 publisher 记录 → **必须先在 main 上登记** |
+| 2 | `CONTRIBUTING.md` 说候选要「把 `verified` 保持 `false`」 | 候选**根本不能含** `verified` 字段 |
+| 3 | 上游 `RELEASING.md` 描述「先开 Issue，再开 catalog PR」 | 当前流程是**一个 PR**，无 Issue |
+| 4 | `README.md` 列的手动签名输入 | 实际还必需 `output-name`（且必须等于 `<id>-<version>-<target>.dbxp`）与 `sdk-ref` |
+| 5 | 校验器描述 | 实际还检查 1 MiB 文件上限、preview key 禁用、publisher 归属、禁止 dbx-store Release URL、图标必须 SVG/PNG |
+| 6 | 目录读取地址只写了 raw.githubusercontent | R2 上也发布了同一份 catalog，仓库未说明客户端实际读哪个 |
+
+## 15. 校验错误对照
+
+| 报错 | 原因 |
+| --- | --- |
+| `contains unknown field(s): X` | 多写了字段（候选/目标/插件/版本/artifact/本地化/publisher/密钥/撤销记录全部是严格键集） |
+| `filename must match plugin id '<id>.json'` | 文件名与 `id` 不一致 |
+| `publisher '<p>' is not registered` | publisher 记录不在 base 分支 |
+| `publisher '<p>' does not own plugin '<id>'` | 该 publisher 不是现有插件的所有者 |
+| `version '<v>' is already listed for plugin '<id>'` | 复用了已上架版本 |
+| `plugin version '<id>@<v>' is revoked` | 该版本已被撤销 |
+| `candidate URLs must use HTTPS` | 用了 http 或相对地址 |
+| `candidate URLs must not reference DBX Store releases; submit the unsigned candidate artifact` | 指向了已签名的官方产物 |
+| `name is required for a new plugin listing` / `license is required ...` | 新插件缺 `name`/`license` |
+| `'<f>' must be a non-empty string when provided` | 字段存在但为空字符串 |
+| `invalid target '<t>'` | target 含大写/下划线等非法字符 |
+| `duplicate target '<t>'` | 同一版本重复 target |
+| `invalid SHA-256 for target '<t>'` | 不是 64 位十六进制 |
+| `invalid size for target '<t>'` | 不是 1 … 512 MiB 的安全整数 |
+| `Candidate SHA-256 mismatch: expected <e>, got <a>` | 写了哈希之后重新打包了 |
+| `Candidate size mismatch: expected <e>, got <a>` | 同上 |
+| `Official signing accepts only unsigned candidates` | 提交了已签名的包 |
+| `Expected plugin <id>, got <x>` / publisher / version | 候选与包内 manifest 身份不一致 |
+| `preview signing key '<k>' cannot publish catalog artifacts` | 目录引用了 preview key |
+| `Binary plugin package must not be committed: <path>` | 仓库里有 `.dbxp` |
+| `Repository file exceeds 1 MiB: <path>` | 工作树里有大文件（含未跟踪文件） |
+| `Invalid candidate artifact '<v>'` | `release-candidates.json` 里的 `url` 不是纯 `.dbxp` 文件名 |
+| `No published candidate release found for <repo>` | 最新 Release 里没有名为 `release-candidates.json` 的资产，或 Release 是 draft/prerelease |
+| `Unsupported store metadata field '<k>'` | `.dbx-store.json` 写了不在白名单的键 |
+
+## 16. 自检脚本
+
+```bash
+node <skill-root>/scripts/make-candidate.mjs . --release-notes "..."
+node <skill-root>/scripts/inspect-dbxp.mjs dist/*.dbxp
+```
+
+`make-candidate.mjs` 会检测：`id`/`publisher`/`version` 一致性、target 合法性、`sha256`/`size` 与实际字节一致、文件名是否符合 `<id>-<version>-<target>.dbxp`、是否误含 `signingKeyId`，并生成候选与聚合 JSON。

package/skill/references/sidecar-protocol.md

@@ -0,0 +1,242 @@
+# Sidecar Protocol v1 参考
+
+## 1. 什么时候需要原生后端
+
+只有**浏览器沙箱无法完成**的能力才需要 Sidecar：
+
+- 原生协议客户端（S3、SSH、SFTP、数据库 wire protocol）
+- 系统凭据 / 系统 API / 本地文件系统读写
+- 长连接、PTY、流式传输
+- 高性能计算或大文件处理
+
+> Sidecar **不是 OS 沙箱**，以当前用户权限运行。签名只证明「哪个仓库批准并发布了这个包」，**不保证代码无害**。能纯前端实现就不要加后端。
+
+## 2. 进程模型
+
+- Sidecar 是**持久子进程**，按插件共享（不是每个 Tab 一个）。插件自己维护内部会话注册表。
+- **stdout 只用于协议消息**；所有日志/诊断写 **stderr**。
+- 宿主支持并发在途请求、按请求超时、严格 JSON-RPC 校验、崩溃传播、状态上报、有界事件缓冲；握手/协议/输出失败会自动终止子进程。
+- 安装/回滚/替换/卸载前，DBX 会先拆除插件拥有的连接池；**仍有已保存连接引用该插件时不允许卸载**。
+
+## 3. 初始化握手
+
+DBX 启动每个 Sidecar 后首先发送 `plugin/initialize`：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "plugin/initialize",
+  "params": {
+    "host": { "dbxVersion": "0.5.68", "hostApiVersion": "1.0.0", "protocolVersions": [1] },
+    "plugin": { "id": "vendor.example", "version": "1.0.0" },
+    "permissions": ["host.events"]
+  }
+}
+```
+
+插件必须回应（**使用相同的 `id`**）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": 1,
+    "capabilities": ["connections", "events"],
+    "plugin": { "id": "vendor.example", "version": "1.0.0" }
+  }
+}
+```
+
+- 响应至少包含 `protocolVersion`、`capabilities`、`plugin: { id, version }`。
+- `plugin.id` / `plugin.version` **必须与 `manifest.json` 完全一致**，否则报
+  `Sidecar identity or protocol does not match manifest`。
+- 协议版本必须在双方支持范围内，否则返回 `-32001`。
+- **初始化 `capabilities` 描述后端能力，不等于 Manifest 的 Host 权限列表** —— 两者是不同概念。
+
+## 4. JSON-RPC 消息
+
+请求/响应遵循 JSON-RPC 2.0；插件的**事件是 JSON-RPC 通知**（无 `id`）。
+
+- 请求必须声明 `jsonrpc: "2.0"`；缺失会被拒绝。
+- `id` 必须支持**并发关联** —— 响应可以乱序，但必须回填相同 `id`。
+- **方法名规则**：非空、长度 ≤256、**不含任何空白字符**。违反返回 `-32600`。
+- 通知（无 `id`）**不发送响应**。
+
+### 错误码
+
+| 码 | 含义 |
+| --- | --- |
+| `-32600` | 非法请求（缺 `jsonrpc`、方法名非法、消息过大） |
+| `-32601` | 方法不存在（SDK 的 `method_not_found` / `MethodNotFound`） |
+| `-32602` | 参数非法 |
+| `-32603` | 内部错误 |
+| `-32000` | 通用失败（IO 错误、锁中毒、二进制传输未启用） |
+| `-32001` | DBX 与插件没有共同协议版本 |
+
+## 5. 传输
+
+### `stdio-jsonl`（默认）
+
+一行一个 JSON 值，以 `\n` 分隔。**单条 JSON 消息 ≤ 8 MiB。**
+
+### `stdio-framed`
+
+需要 PTY / SFTP / 文件传输等二进制流时使用，**并同时声明 `host.binary`**。
+
+```
+kind: u8 | payload_length: u32 big-endian | payload
+```
+
+- `kind = 0`：UTF-8 JSON payload。
+- `kind = 1`：`channel_length: u16 big-endian | channel UTF-8 | binary bytes`。
+- 二进制单帧 **≤ 64 MiB**；channel 名同样受方法名规则约束。
+
+### 尺寸限制总表
+
+| 位置 | 上限 |
+| --- | --- |
+| Sidecar JSON 单条消息 | 8 MiB |
+| Sidecar 二进制单帧 | 64 MiB |
+| UI ↔ 宿主 JSON 桥参数 | 2 MiB |
+| UI ↔ 宿主 二进制消息 | 8 MiB |
+| Workbench context 快照 | 2 MiB |
+| 显式桥接超时 | 1–120000 ms |
+
+**大文件传输必须自己做分块、偏移、确认、取消与进度事件**，不要塞进一个巨大的 JSON/base64 值。
+
+## 6. 连接生命周期方法
+
+固定方法名（详见 `contributions.md` §2）：
+
+| 方法 | 说明 |
+| --- | --- |
+| `connection/test` | 校验连接，通常返回 `{ "success": true, "message": "..." }` |
+| `connection/connect` | 建立会话，用 `connection.id` 作为 key；**幂等** |
+| `connection/disconnect` | 拆除会话；**幂等**（重复断开不应报错） |
+| `connection/action` | 自定义表单动作，参数额外含 `action: { id }` |
+| `contextMenu/<contribution-id>` | 连接右键菜单，返回 `{ "message": "..." }` 弹 toast |
+| `filesystem/*` | 声明 filesystem-provider 时实现 |
+
+`connection` 只在**后端生命周期请求**中携带补齐的 Secret；`runtime.host` / `runtime.port` 是经过 DBX 隧道/代理后的**最终端点**，直接连它。
+
+## 7. 事件
+
+插件通过 emitter 主动推送事件（JSON-RPC 通知）：
+
+```
+{"jsonrpc":"2.0","method":"<plugin>/progress","params":{...}}
+```
+
+前端用 `window.dbxPlugin.onEvent(fn)` 接收，**需要 `host.events` 权限**。转发后端事件必须有该权限。
+
+**绝对不要在事件、context 或错误消息中泄露 Secret。**
+
+## 8. Rust SDK
+
+`dbx-plugin-sdk`（协议 v1，支持 JSONL 与 framed）。
+
+```rust
+use dbx_plugin_sdk::{PluginEmitter, PluginError, PluginHandler, PluginMetadata, PluginServer, RequestContext};
+use serde_json::{json, Value};
+
+struct Plugin;
+
+impl PluginHandler for Plugin {
+    fn handle(&self, _context: RequestContext, method: &str, params: Value, emitter: &PluginEmitter)
+        -> Result<Value, PluginError> {
+        match method {
+            "example/echo" => {
+                emitter.event("example/progress", json!({ "done": true }))?;
+                Ok(params)
+            }
+            _ => Err(PluginError::method_not_found(method)),
+        }
+    }
+}
+
+fn main() -> std::io::Result<()> {
+    let metadata = PluginMetadata::new("com.example.files", env!("CARGO_PKG_VERSION"))
+        .with_capability("connections");
+    PluginServer::new(metadata, Plugin).serve()
+}
+```
+
+API 速览：
+
+| 项 | 说明 |
+| --- | --- |
+| `PluginMetadata::new(id, version)` | `.with_capability(name)` 追加能力 |
+| `PluginServer::new(metadata, handler)` | `.transport(PluginTransport::Framed)`、`.worker_threads(n)`、`.work_queue_capacity(n)`、`.serve()` |
+| `PluginHandler::handle(ctx, method, params, emitter)` | 主分发；`ctx` 含 `request_id`、`driver` |
+| `PluginHandler::handle_binary(channel, data, emitter)` | framed 下的宿主→插件二进制；默认返回「不支持」 |
+| `PluginError::new(code, msg)` / `PluginError::method_not_found(m)` | 错误构造 |
+| `PluginEmitter::event(method, params)` / `PluginEmitter::binary(channel, data)` | 事件与二进制输出 |
+
+- 默认 **2–16 个 worker 线程**（按可用并行度）与 **256 任务队列**；`worker_threads(0)` / `work_queue_capacity(0)` 会被 clamp 到 1。
+- `PluginTransport::Framed` 需要在 manifest 声明 `"transport": "stdio-framed"`。
+
+## 9. Go SDK
+
+```go
+metadata := dbxpluginsdk.Metadata{
+    ID:           "vendor.example",
+    Version:      "1.0.0",
+    Capabilities: []string{"connections"},
+}
+server := dbxpluginsdk.NewServer(metadata, handler)
+if err := server.Serve(); err != nil {
+    log.Fatal(err)   // 日志走 stderr
+}
+```
+
+API 速览：
+
+| 项 | 说明 |
+| --- | --- |
+| `Metadata{ID, Version, Capabilities}` | 身份与能力 |
+| `NewServer(metadata, handler)` | `.WithTransport(TransportFramed)`、`.WithIO(in, out, errOut)`、`.Serve()` |
+| `Handler` / `HandlerFunc` | `Handle(ctx, method, params json.RawMessage, emitter) (any, *PluginError)` |
+| `BinaryHandler` | `HandleBinary(channel string, data []byte, emitter *Emitter) *PluginError` |
+| `Emitter.Event(method, params)` / `Emitter.Binary(channel, data)` | 事件与二进制输出 |
+| `NewError(code, msg)` / `MethodNotFound(method)` | 错误构造 |
+
+- Go SDK 当前支持 JSONL；**framed 也支持**（`TransportFramed`）。
+- 不要只改 Manifest 的 `transport` 就认为 Go 已具备二进制帧处理能力 —— 必须真正用 framed 并实现 `HandleBinary`。
+
+## 10. 构建集成
+
+模板生成的项目已经接好 SDK，正常路径是直接用 CLI：
+
+```bash
+dbx-plugin package .          # Rust: cargo build --release；Go: go build -trimpath
+dbx-plugin dev                # Rust 用 debug target；Go 用缓存输出目录
+```
+
+- 生成项目的 `Cargo.toml` 依赖 `dbx-plugin-sdk`（版本号由 CLI 注入），`go.mod` require `github.com/t8y2/dbx/plugins/sdk/go/dbx-plugin-sdk`。
+- CLI 会通过 `DBX_PLUGIN_SDK_ROOT` 把依赖 **patch/replace 到自带或指定的 SDK 源码**（npm 包内置 `sdk-root`，所以默认即生效）。
+- **不要绕过 CLI 直接 `cargo build` / `go build`**，除非你自己设置了 `DBX_PLUGIN_SDK_ROOT`，或把依赖改成显式 path/git。
+- 开发未发布的 SDK：`dbx-plugin create ... --sdk-root /path/to/dbx`，或打包前 `export DBX_PLUGIN_SDK_ROOT=/path/to/dbx`。
+
+## 11. 工程约束清单
+
+- [ ] stdout 只输出协议消息，日志一律 stderr。
+- [ ] `plugin/initialize` 里的 id/version 与 manifest 一致。
+- [ ] 请求 ID 支持并发关联（响应可乱序）。
+- [ ] `connect` / `disconnect` 幂等。
+- [ ] 长任务有超时、取消、分块确认。
+- [ ] 不在事件/context/错误消息里泄露 Secret。
+- [ ] 用 framed 时 manifest 声明 `stdio-framed` + `host.binary`。
+- [ ] release 构建开启 strip/lto 控制体积（模板已配置）。
+
+## 12. 常见错误
+
+| 报错 | 原因 |
+| --- | --- |
+| `Sidecar identity or protocol does not match manifest` | 初始化响应的 `plugin.id`/`version` 与 manifest 不一致，或协议版本不兼容 |
+| 后端启动后立即退出 | 用了 `println!` 污染 stdout；或 `jsonrpc` 字段缺失 |
+| 请求一直不返回 | 没有用请求的 `id` 回填响应；或方法名含空格被拒 |
+| `Binary messages require framed transport` | 没切换到 framed，或 manifest 未声明 |
+| `plugin JSON line is too large` | 单条消息超过 8 MiB，需要分块 |
+| 手动 `cargo build` 找不到 `dbx-plugin-sdk` | 没设置 `DBX_PLUGIN_SDK_ROOT`，请改用 `dbx-plugin package` |