dbx-plugin-skill 0.1.0

package/skill/references/manifest.md

@@ -0,0 +1,229 @@
+# Manifest v1 参考
+
+`manifest.json` 是**运行时契约**，必须位于插件包根目录。DBX 与 CLI 都会校验它。
+
+- 编辑器 Schema（上游，`main` 分支）：`https://raw.githubusercontent.com/t8y2/dbx/main/plugins/manifest.schema.json`
+- Manifest v1 **拒绝任何未声明的字段**（`additionalProperties: false`）。Schema 只是编辑期辅助，**运行时校验才是边界**。
+
+> ⚠️ CLI 生成的模板里 `$schema` 指向 `.../t8y2/dbx/plugin-sdk-v1/plugins/manifest.schema.json`，该 ref 当前**不存在（404）**。需要编辑器提示就改成 `main` 或某个版本 tag。
+
+## 1. 顶层字段
+
+| 字段 | 必需 | 约束 |
+| --- | --- | --- |
+| `$schema` | 否 | 任意字符串，不参与身份校验 |
+| `manifest_version` | **是** | 必须为数字 `1` |
+| `id` | **是** | `^[a-z0-9][a-z0-9._-]*$`，Schema/商店上限 128 字符；CLI 宽松到 256，但**上架请控制在 128 内**。发布后不可更改 |
+| `name` | **是** | 非空字符串 |
+| `icon` | 否 | 包内相对路径，见 §4 路径规则 |
+| `version` | **是** | 严格 SemVer（CLI 用 semver 解析，如 `1.0.0`、`1.0.0-beta.1`）。相同 `id`+`version` 的正式包不可覆盖 |
+| `publisher` | **是** | 非空字符串。Schema 不限格式，但**上架时商店要求**候选 `publisher` 匹配 `^[a-z0-9][a-z0-9._-]{0,127}$` 且已登记，且与包内 manifest 完全一致。实践：用小写标识符 |
+| `description` | 否 | 字符串 |
+| `source` | 否 | `^https?://\S+$`，源码仓库地址 |
+| `homepage` | 否 | `^https?://\S+$` |
+| `engines` | **是** | 至少含 `host_api`，见 §2 |
+| `permissions` | 否 | 见 §2 |
+| `entrypoints` | 否 | 有贡献点/后端时按需声明，见 §3 |
+| `contributions` | 否 | 见 `contributions.md` |
+| `localizations` | 否 | 见 §5 |
+
+**因未知字段被拒的典型**：手写 `signingKeyId`（属于商店 artifact metadata，不是 Manifest 字段）、`verified`、`author`、`license`、`repository` 等自造键。
+
+## 2. `engines` 与 `permissions`
+
+```json
+{
+  "engines": { "dbx": ">=0.5.68", "host_api": "1" },
+  "permissions": [
+    "host.workbench",
+    "host.events",
+    "host.filesystem",
+    "host.binary",
+    "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.network:https://<host>[:port]`：
+  - **必须 HTTPS**；主机名只允许 `[A-Za-z0-9._-]`，端口可选数字；
+  - **不允许路径、通配符、Token**；
+  - **最多 8 个**，重复会被拒绝；
+  - 作用仅是把这些 origin 加入沙箱 CSP 的 `connect-src`，**仍受目标服务 CORS 约束**；
+  - 它**不是** Sidecar 的防火墙 —— 原生后端不受此限制。
+- `permissions` 数组本身要求 `uniqueItems`。只声明真正用到的权限；reviewer 会逐一核对调用点。
+
+## 3. `entrypoints`
+
+```json
+{
+  "entrypoints": {
+    "ui": { "root": "ui", "entry": "ui/index.html" },
+    "backend": {
+      "protocol_versions": [1],
+      "transport": "stdio-jsonl",
+      "executable": "bin/linux-x64/backend"
+    }
+  }
+}
+```
+
+### ui
+- 只要求 `entry`（`minLength: 1`）；`root` 可选，默认 `ui`。
+- **`entry` 必须位于 `root` 内**：`root` = `ui` 时写 `ui/index.html`，**不是** `index.html`。路径按字符串前缀判断。
+- `entrypoints.ui.kind` 已废弃，打包时**直接报错**（UI 永远是沙箱化）。
+
+### backend
+- 只要求 `executable`（`assetPath`）。
+- `transport` 枚举 `stdio-jsonl`（默认）| `stdio-framed`；需要二进制帧时必须用 `stdio-framed` **并**声明 `host.binary`。
+- `protocol_versions`：正整数数组，`minItems: 1`，unique；当前协议只有 `1`。
+- 已废弃字段会导致打包失败：`binaries`、`protocol`。
+
+**打包时 CLI 会重写 backend 入口**（`package` 阶段，只影响包内那份 manifest）：
+
+1. `executable` 被强制改写为 `bin/<target>/<binary>`（`<binary>` 来自 `dbx-plugin.toml` 的 `[backend].binary`，Windows 追加 `.exe`）；
+2. `protocol_versions` 恰为 `[1]` 时**删除该字段**；
+3. `transport` 恰为 `"stdio-jsonl"` 时**删除该字段**。
+
+所以源码 manifest 里写 `bin/<platform>/...` 没有意义，按 §4 的规则，实际由 `target` 决定。
+
+## 4. 包内路径规则（`assetPath`）
+
+所有包内路径（`icon`、`ui.root`、`ui.entry`、`backend.executable`、Contribution 的 `icon`）：
+
+- **不能**以 `/` 开头；
+- **不能**包含反斜杠 `\`；
+- **不能**包含 `.` 或 `..` 作为路径段；
+- **不能**出现重复斜杠 `//`；
+- 必须相对包根且实际存在。
+
+CLI 打包还会校验：`icon` / `ui.entry` 指向的文件必须存在，且**被 `[package].include` 覆盖**，否则报
+`manifest UI entry 'ui/index.html' is not covered by [package].include`。
+
+## 5. `localizations`
+
+覆盖插件级与贡献点级文案。locale key 形如 `^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$`（如 `zh-CN`、`en`）。
+
+```json
+{
+  "localizations": {
+    "zh-CN": {
+      "name": "示例文件",
+      "description": "示例插件说明。",
+      "contributions": {
+        "com.example.files.connection": {
+          "label": "示例服务",
+          "description": "由插件声明的连接表单。",
+          "fields": {
+            "host": { "label": "主机", "placeholder": "请输入主机" }
+          },
+          "actions": {
+            "refresh": { "label": "刷新元数据" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+- 可覆盖：`name`、`description`；每个 Contribution 的 `label`、`description`、`fields`（`label`/`description`/`placeholder`/`options`）、`actions`（`label`/`description`）。
+- `fields.<key>.options` 是 **`value → 显示文案` 的映射对象**（`{"readonly": "只读"}`），不是数组。
+- DBX 匹配顺序：精确 locale → 基础语言 → manifest 默认文案。
+- **它不翻译插件 UI 自己的文本**，UI 文案要按 `window.dbxPlugin.locale` 自行处理。
+
+## 6. 最小可用示例
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/t8y2/dbx/main/plugins/manifest.schema.json",
+  "manifest_version": 1,
+  "id": "com.example.files",
+  "name": "Example Files",
+  "version": "0.1.0",
+  "publisher": "example",
+  "description": "Browse files from an example service.",
+  "icon": "assets/plugin.svg",
+  "source": "https://github.com/example/dbx-plugin-files",
+  "homepage": "https://github.com/example/dbx-plugin-files",
+  "engines": { "host_api": "1", "dbx": ">=0.5.68" },
+  "permissions": [],
+  "entrypoints": { "ui": { "root": "ui", "entry": "ui/index.html" } },
+  "contributions": [
+    {
+      "type": "workbench",
+      "id": "com.example.files.main",
+      "label": "Files",
+      "icon": "assets/plugin.svg"
+    }
+  ]
+}
+```
+
+## 7. 带原生后端的完整示例
+
+```json
+{
+  "manifest_version": 1,
+  "id": "com.example.files",
+  "name": "Example Files",
+  "version": "0.1.0",
+  "publisher": "example",
+  "description": "Browse files from an example service.",
+  "icon": "assets/plugin.svg",
+  "engines": { "dbx": ">=0.6.0", "host_api": "1" },
+  "permissions": ["host.workbench", "host.events", "host.binary", "host.network:https://s3.example.com:443"],
+  "entrypoints": {
+    "ui": { "root": "ui", "entry": "ui/index.html" },
+    "backend": {
+      "protocol_versions": [1],
+      "transport": "stdio-framed",
+      "executable": "bin/darwin-arm64/dbx-plugin-example-files"
+    }
+  },
+  "contributions": [
+    {
+      "type": "connection-provider",
+      "id": "com.example.files.connection",
+      "label": "Example Service",
+      "icon": "assets/connection.svg",
+      "database_type": "example-files",
+      "fields": [
+        { "key": "display_name", "label": "Name", "type": "text", "binding": "name", "required": true },
+        { "key": "endpoint", "label": "Endpoint", "type": "text", "binding": "host", "required": true },
+        { "key": "port", "label": "Port", "type": "number", "binding": "port", "default": 443 },
+        { "key": "token", "label": "Access token", "type": "password", "binding": "secret", "required": true }
+      ],
+      "workbench": "com.example.files.main",
+      "capabilities": ["test", "connect", "disconnect"]
+    },
+    {
+      "type": "workbench",
+      "id": "com.example.files.main",
+      "label": "Files",
+      "icon": "assets/plugin.svg"
+    }
+  ]
+}
+```
+
+## 8. CLI 与 Schema 的差异（容易踩）
+
+| 项 | Schema / 运行时 | CLI `package` |
+| --- | --- | --- |
+| `id` 长度 | ≤128 | ≤256（更宽松，但商店按 128 校验） |
+| `version` 格式 | 正则 `^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$` | semver crate 严格解析（`1.0.0-alpha+build` 只在 semver 侧通过） |
+| `icon` 存在性 | 不校验 | **必须存在且被 `[package].include` 覆盖** |
+| UI entry 在 root 内 | 不校验 | **校验** |
+| backend 与 toml 一致 | 不校验 | **校验**（要么都有要么都没有） |
+| 未知字段 | `additionalProperties: false` | 打包时显式拒绝并列出字段名 |
+| `executable` | 按声明 | **改写为 `bin/<target>/<binary>`** |
+
+## 9. 自检
+
+```bash
+node <skill-root>/scripts/check-project.mjs <项目目录>
+```
+
+它覆盖：未知字段、id/version 格式、`engines.host_api`、权限语法与数量、`ui.entry` 是否在 `root` 内、资源是否存在、是否被 `include` 覆盖、manifest 与 `dbx-plugin.toml` 的后端一致性、已废弃字段。

package/skill/references/packaging.md

@@ -0,0 +1,183 @@
+# 打包参考
+
+## 1. `dbx-plugin.toml`（构建配置，不进入插件包）
+
+```toml
+schema_version = 1
+
+# 只有原生后端项目才有这一段；纯前端项目必须完全省略
+[backend]
+language = "rust"        # rust | go | golang
+directory = "backend"    # 相对项目根的相对路径
+binary = "dbx-plugin-my-plugin"   # 纯文件名，不能含 / 或 \
+
+[package]
+include = ["assets", "ui"]        # 只有这里声明的目录才会被打包
+
+[dev]
+ui_build = ["npm", "run", "build"]
+ui_watch = ["npm", "run", "build:watch"]
+```
+
+校验规则：
+
+- `schema_version` 必须为 `1`，否则 `Unsupported dbx-plugin.toml schema version N`。
+- `[backend].directory` 必须是安全相对路径；`[backend].binary` **必须是文件名**（不含路径分隔符）。
+- `[package].include` 每一项必须是安全相对路径（不能绝对、不能含 `.`/`..`），且**不能包含 `.dbx-dev` 组件**，否则 `Package input cannot contain .dbx-dev development data`。
+- `[dev]` 的子段是**字符串数组**（`ui_build="npm run build"` 会解析失败）。`[dev]` 使用 `deny_unknown_fields`，写错键会报错。
+- `[backend]` 存在性与 `manifest.json` 的 `entrypoints.backend` **必须一致**，否则
+  `dbx-plugin.toml and manifest.json must either both declare a backend or both omit it`。
+
+## 2. 打包流程
+
+```bash
+dbx-plugin package .
+```
+
+1. 解析 `dbx-plugin.toml`，校验 `schema_version`、backend 与 include 路径。
+2. 读取并校验 `manifest.json`：拒绝未知顶层字段、校验 `manifest_version`、`id`、`name`、`version`、`publisher`、`engines.host_api`；比对 backend 一致性。
+3. 决定 target（`--target` → `DBX_PLUGIN_TARGET` → 原生项目当前主机 → `universal`），校验 target 字符集，原生项目还会校验 target 与构建主机一致。
+4. 校验 `icon` 与 `ui.entry`：文件存在、路径安全、`entry` 在 `root` 内、且**被 `[package].include` 覆盖**。
+5. 建临时 stage 目录 `dist/.stage-<id>-<target>`，原生项目先构建 Sidecar 到 `bin/<target>/`。
+6. 生成**包内 manifest**（见 §4），与 include 的内容一起复制进 stage。
+7. 用 `dbx-plugin-packager` 打成 ZIP 容器 `dist/<id>-<version>-<target>.dbxp`，写入 `checksums.json`。
+8. 写 `dist/<id>-<version>-<target>.artifact.json`。
+9. 清理临时 stage / build 目录（成功与失败都会清理）。
+
+## 3. `.dbxp` 内部结构
+
+```
+<id>-<version>-<target>.dbxp        # ZIP 容器
+├── manifest.json                   # 已被 CLI 重写过的那份
+├── checksums.json                  # {"algorithm":"sha256","files":{路径: sha256}}
+├── signature.json                  # 仅签名后存在（未签名候选包没有）
+├── bin/<target>/<binary>           # 仅原生项目；保留可执行权限
+├── assets/…                        # 由 [package].include 决定
+└── ui/…
+```
+
+未签名候选包**故意不含 `signature.json`**，其 `.artifact.json` 也**不含 `signingKeyId`**。
+
+## 4. 包内 manifest 的重写规则
+
+CLI 在打包时会改写**包内那份** `manifest.json`（你的源码文件不变）：
+
+1. 拒绝已废弃字段：`entrypoints.ui.kind`、`entrypoints.backend.binaries`、`entrypoints.backend.protocol`。
+2. `entrypoints.backend.executable` 被强制设为 `bin/<target>/<binary>`（Windows 加 `.exe`）。
+3. 若 `protocol_versions` 恰为 `[1]`，删除该字段。
+4. 若 `transport` 恰为 `"stdio-jsonl"`，删除该字段。
+
+含义：源码里 `backend.executable` 写什么都会被覆盖，**真正决定路径的是 target**；默认值不必显式写出来。
+
+## 5. target 规则
+
+| 项目类型 | 默认 target | 说明 |
+| --- | --- | --- |
+| 纯前端（`frontend` / `svelte`） | `universal` | 跨平台单包 |
+| 原生（`rust` / `go`） | 当前主机 | `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`windows-x64`、`windows-arm64` |
+
+- target 只允许 `[a-z0-9-]`，长度 ≤64。
+- **原生项目不能交叉打包**：显式指定与构建主机不同的 target 会报错。正式发布用 CI 矩阵在各自平台构建。
+- 商店目录实际使用的 target 词表：`darwin-arm64`、`darwin-x64`、`linux-arm64`、`linux-x64`、`windows-arm64`、`windows-x64`。
+- 只有「同一个包在所有支持的 DBX 平台都有效」时才用 `universal`。
+
+## 6. 体积与数量限制
+
+| 限制 | 值 | 触发时机 |
+| --- | --- | --- |
+| 输出包大小 | 512 MiB | packager，`Output package exceeds N bytes` |
+| 解压后总大小 | 1 GiB | packager，`Package source exceeds N uncompressed bytes` |
+| 单文件 | 256 MiB | packager，`Package file '<name>' exceeds N bytes` |
+| 归档条目数 | 10000 | packager，`Package source contains more than N files` |
+| 商店候选 `size` | 1 … 512 MiB | 商店 `validate.mjs` |
+
+> 打包时还会做**读取期间一致性校验**：如果源文件在读取过程中被改动，会报
+> `Package source changed while reading <path>`。所以不要在打包过程中同时改文件。
+
+## 7. 被拒绝的输入
+
+- **符号链接**：`Package input cannot contain symbolic link <path>`（packager 也会检查）。
+- **`.dbx-dev`**（含嵌套）：`Package input cannot contain .dbx-dev development data`。
+- **越界路径**：绝对路径、含 `.`/`..` 的路径 → `... must be a safe relative path`。
+- **不存在的 include**：`Package include <path> does not exist`。
+- **输出位置不安全**：输出包必须在源目录之外（`Output package must be outside the source directory`）；artifact metadata 也必须在源目录之外且不能等于包路径。
+- **扩展名**：输出必须是 `.dbxp`。
+- **源目录缺 manifest**：`<dir> is missing manifest.json`。
+- **未覆盖的资源**：`manifest icon 'assets/plugin.svg' is not covered by [package].include`。
+
+**不要把 `dist/` 或 `.dbx-dev/` 再作为 include 输入。**
+
+## 8. `.artifact.json`
+
+```json
+{
+  "target": "universal",
+  "url": "com.example.my-plugin-0.1.0-universal.dbxp",
+  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "size": 123456
+}
+```
+
+- `sha256` / `size` 绑定**确切字节**。任何字节变化都必须递增插件版本并重新审核。
+- `url` 默认是文件名；用 `--artifact-url` 写入发布后的 HTTPS 地址：
+
+```bash
+dbx-plugin package . --artifact-url https://github.com/me/my-plugin/releases/download/v0.1.0/com.example.my-plugin-0.1.0-universal.dbxp
+```
+
+- 签名后 packager 才会补上 `signingKeyId`。**候选包里不要有它。**
+- 上游 `.artifact.json` 与商店侧的最终 `.artifact.json` **同名但不同物**：前者由你生成（用于聚合 `release-candidates.json`），后者由签名步骤生成并随包发布。
+
+## 9. Release 工作流
+
+`dbx-plugin create` 生成的 `.github/workflows/plugin-release.yml` 在发布 GitHub Release 时构建候选包：
+
+```yaml
+name: Release DBX plugin
+on:
+  release:
+    types: [published]
+permissions:
+  contents: write
+jobs:
+  release:
+    uses: t8y2/dbx/.github/workflows/plugin-release-reusable.yml@plugin-sdk-v1
+    with:
+      release-tag: ${{ github.event.release.tag_name }}
+      package-command: dbx-plugin package .
+      package-path: dist/*.dbxp
+      metadata-path: dist/*.artifact.json
+      plugin-cli-version: 0.1.6
+      # 纯前端插件加这一行，只构建一个 universal 包：
+      build-matrix: '{"include":[{"runner":"ubuntu-24.04","target":"universal"}]}'
+```
+
+- **同时 pin 住 reusable workflow 的 ref 与 `plugin-cli-version`**，保证本地与 CI 用同一套 SDK 契约。
+- 原生项目的默认矩阵覆盖 `darwin-arm64`、`darwin-x64`、`windows-x64`、`linux-x64`、`linux-arm64`。
+- 工作流会：安装 pin 的 CLI → 各 target 构建 → 拒绝含 `signature.json` 或含 `signingKeyId` 的候选 → 校验 target/sha256/size/包名与统一 Manifest 身份 → 上传候选包与合并的 `release-candidates.json`。
+- **官方作者不需要配置任何签名 Secret 或 Key ID。**
+
+## 10. 打包后自检
+
+```bash
+node <skill-root>/scripts/check-project.mjs .                       # 打包前：项目自洽
+node <skill-root>/scripts/inspect-dbxp.mjs dist/*.dbxp              # 打包后：包内容 + checksums 校验
+node <skill-root>/scripts/make-candidate.mjs .                      # 生成候选 JSON 并复核 sha256/size
+```
+
+`inspect-dbxp.mjs` 会逐条重算 `checksums.json` 里的 SHA-256，并检查 `bin/` 下的 target 是否与文件名一致、是否存在 `signature.json`。
+
+## 11. 常见错误
+
+| 报错 | 原因 |
+| --- | --- |
+| `Invalid dbx-plugin.toml: ...` | TOML 语法错，或 `[dev]` 里写了未支持的键 |
+| `Unsupported dbx-plugin.toml schema version N` | `schema_version` 不是 1 |
+| `dbx-plugin.toml and manifest.json must either both declare a backend or both omit it` | 两边不一致 |
+| `manifest.json contains unknown top-level field(s): X` | 写了 Manifest v1 不接受的字段 |
+| `manifest UI entry 'ui/index.html' is not covered by [package].include` | include 里没有 `ui` |
+| `manifest icon 'assets/plugin.svg' does not exist at ...` | 图标文件缺失 |
+| `Package include <path> does not exist` | include 声明了不存在的目录 |
+| `Native plugin target 'X' does not match build host 'Y'` | 交叉打包；请在目标平台构建 |
+| `Target directory is not empty; use --force`（create） | 与打包无关，但常一起遇到 |
+| `Package source cannot contain symbolic link ...` | 删掉符号链接或改成真实文件 |