dbx-plugin-skill 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2024] [ eryajf of copyright https://github.com/eryajf ]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,238 @@
+# dbx-plugin-skill
+
+一个用于 **DBX 插件开发** 的 agent skill（技能包），覆盖从创建到上架官方商店的全链路：
+
+**创建 → 开发 → 调试 → 打包 → 发布 Release → 提交 dbx-store 候选 PR → 审核签名**
+
+技能名：`dbx-plugin`（安装到 `~/.dsh/skills`、`~/.claude/skills`、`~/.agents/skills`）。
+
+---
+
+## 快速安装
+
+```bash
+# 方式一：直接安装（推荐）
+npx dbx-plugin-skill install
+
+# 方式二：全局安装后使用
+npm install --global dbx-plugin-skill
+dbx-plugin-skill install
+```
+
+安装后**重启 agent 会话**（技能目录在会话启动时扫描），然后即可通过自然语言触发，例如：
+
+> 帮我创建一个 DBX 插件，用 Svelte 模板，id 是 com.example.demo
+> 我的 DBX 插件打包报错 `manifest UI entry ... is not covered by [package].include`，帮我看下
+> 帮我把这个插件发布到 dbx-store，生成候选 JSON
+> 检查一下这个 .dbxp 包里有没有不该发布的东西
+
+### 安装选项
+
+```bash
+dbx-plugin-skill install [--target all|dsh,claude,agents] [--scope user|project] [--link] [--force]
+
+dbx-plugin-skill status     # 查看各目标安装状态
+dbx-plugin-skill doctor     # 环境自检（Node / dbx-plugin CLI / skill 安装 / 当前项目）
+dbx-plugin-skill path       # 打印安装路径
+dbx-plugin-skill uninstall  # 卸载（仅移除本安装器写入的内容）
+```
+
+| 选项 | 说明 |
+| --- | --- |
+| `--target` | 安装目标，默认 `all`：`dsh` = DeepSeek Harness，`claude` = Claude Code，`agents` = 共享 agents 目录 |
+| `--scope` | `user`（默认，家目录）或 `project`（当前目录下的 `.dsh/skills`、`.claude/skills`、`.agents/skills`） |
+| `--link` | 安装为符号链接，便于从源码仓库直接迭代（仅 user scope 下最有用） |
+| `--force` | 覆盖非本安装器写入的同名目录 |
+
+安装器会在目标目录写入 `.dbx-plugin-skill.json` 标记文件；卸载时据此判断归属，**不会误删手工安装的同名技能**。
+
+---
+
+## 前置依赖
+
+| 依赖 | 版本 | 用途 |
+| --- | --- | --- |
+| Node.js | ≥ 18（`dbx-plugin dev` 需 **≥ 22**） | 运行随附脚本与安装器 |
+| `@dbx-app/plugin-cli` | 建议最新 | 创建/调试/打包插件 |
+
+```bash
+npm install --global @dbx-app/plugin-cli
+dbx-plugin --help
+```
+
+> 检查版本：`dbx-plugin version`。若明显落后于 npm 上的最新版，建议 `npm install --global @dbx-app/plugin-cli@latest`。
+
+---
+
+## Skill 内容
+
+```
+skill/
+├── SKILL.md                          # 入口：心智模型、路由表、标准工作流、硬性约束
+├── references/
+│   ├── manifest.md                   # Manifest v1 字段、权限、入口、国际化、打包期重写
+│   ├── contributions.md              # 5 类贡献点、连接表单/binding、文件系统 RPC
+│   ├── host-api.md                   # window.dbxPlugin、context 规则、主题、CSP、资源
+│   ├── sidecar-protocol.md           # 协议 v1、JSONL/framed、Rust/Go SDK、错误码
+│   ├── cli.md                        # create / dev / package / keygen 全参数与环境变量
+│   ├── debugging.md                  # dev host、DBX_UI_BUILD_SUCCESS、诊断 API、能力边界
+│   ├── packaging.md                  # dbx-plugin.toml、打包流程、.dbxp 结构、体积限制
+│   ├── publishing.md                 # .dbx-store.json、候选 JSON、审核签名、校验规则
+│   └── troubleshooting.md            # 报错原文 → 原因 → 修法 对照表
+└── scripts/
+    ├── check-project.mjs             # 打包前预检
+    ├── inspect-dbxp.mjs              # 解包检查（含 ZIP 读取与 checksums 校验）
+    ├── make-candidate.mjs            # 生成候选与 release-candidates.json
+    └── dev-logs.mjs                  # 读取 dev host 脱敏日志
+```
+
+### 随附脚本
+
+四个脚本都是**零依赖**的 Node 程序（只用内置模块），可直接运行：
+
+```bash
+# 1) 打包前预检：manifest / dbx-plugin.toml / include 覆盖 / 资源存在 / 前后端一致 / 权限语法
+node skill/scripts/check-project.mjs [项目目录] [--json] [--quiet]
+
+# 2) 解包检查 .dbxp：条目、manifest、checksums 逐条校验、签名状态、bin target 一致性
+node skill/scripts/inspect-dbxp.mjs dist/my-plugin-0.1.0-universal.dbxp [--json] [--extract DIR] [--no-verify]
+
+# 3) 生成上架 JSON，并复核每个包的 sha256/size
+node skill/scripts/make-candidate.mjs [项目目录] [--repo owner/name] [--tag v1.0.0] [--release-notes "..."]
+
+# 4) 读取 dev host 日志（自动沿用 nextAfter + instanceId 游标）
+node skill/scripts/dev-logs.mjs --port 5190 [--level error] [--follow] [--json]
+```
+
+`check-project.mjs` 与 `make-candidate.mjs` 以退出码表达结果：`0` 通过，`1` 发现问题（错误详情在 stderr 或 `--json` 的 `findings` 里）。
+
+安装 skill 后，agent 会自动在合适的时机调用这些脚本；你也可以手动跑。
+
+---
+
+## 开发本仓库
+
+```bash
+git clone https://github.com/eryajf/dbx-plugin-skill.git
+cd dbx-plugin-skill
+npm test                      # 运行 65 项端到端自检
+
+# 以符号链接方式边改边用
+node bin/dbx-plugin-skill.mjs install --link --target dsh
+```
+
+`npm test` 覆盖：skill 结构完整性（frontmatter / 引用完整性）、预检脚本的正反例、`.dbxp` 校验与篡改检测、候选生成与哈希复核、安装器完整生命周期（在临时 HOME 中进行，不触碰真实环境）。
+
+常用脚本：
+
+```bash
+npm test                      # 端到端自检（CI 在 Node 18/20/22 上跑）
+npm run verify:package        # 校验 npm 打包内容与元数据
+npm run upstream:check        # 对比上游 DBX 契约是否变化
+npm run upstream:update       # 更新后重新基线化
+```
+
+---
+
+## 仓库与仓库设置
+
+仓库地址：<https://github.com/eryajf/dbx-plugin-skill>（公开仓库，`--provenance` 需要公开仓库才能生成可验证的来源证明）。
+
+如果你要 fork 成自己的包发布，记得同步改 `package.json` 里的 `name`、`repository`、`homepage`、`bugs`，以及 `.github/workflows/release.yml` 里 Trusted Publisher 相关的注释。
+
+仓库维护者需要在 GitHub **Settings** 里确认：
+
+| 位置 | 建议 |
+| --- | --- |
+| Secrets and variables → Actions | 加 `NPM_TOKEN` —— 仅首次发布 npm 需要，之后切 Trusted Publishing 就可以删掉（见下） |
+| Features → Issues | 保持开启（`upstream-drift.yml` 会开 issue 提醒） |
+| Actions → General → Workflow permissions | **无需修改**。三个 workflow 都显式声明了自己的 `permissions:`（`contents: write` / `id-token: write` / `issues: write`），会覆盖仓库默认值。只有当组织策略禁止 workflow 申请写权限时才需要处理 |
+
+> 排查提示：判断 `GITHUB_TOKEN` 的能力**不要**看 `GET /repos/{owner}/{repo}` 里的 `.permissions.push` —— 那个字段描述的是**用户角色**，对 app token 恒为 `false`，会造成误判。
+
+---
+
+## 自动化（GitHub Actions）
+
+仓库内置三个 workflow：
+
+| Workflow | 触发 | 作用 |
+| --- | --- | --- |
+| `ci.yml` | push `main` / PR / 手动 | 在 Node 18/20/22 上跑 `npm test`；单独 job 校验 npm 打包内容并产出 `dbx-plugin-<version>.zip` 构建产物 |
+| `release.yml` | 打 `v*` tag / 手动（可 dry-run） | 校验 tag 与版本一致 → 跑测试 → 校验打包 → **发布 npm** → 创建 GitHub Release 并附带 `.tgz`、`.zip`、`SHA256SUMS.txt` |
+| `upstream-drift.yml` | 每周一 02:00 UTC / 手动 | 抓取上游 `manifest.schema.json`、`plugin-candidate.schema.json` 指纹与 npm 上 `@dbx-app/plugin-cli` 版本，与基线对比；有变化就创建或更新一个 `upstream-drift` issue |
+
+### 发一个新版本
+
+```bash
+npm version patch            # 或 minor / major：更新 package.json 并打 tag
+git push --follow-tags       # 推送提交与 tag → 自动触发 release.yml
+```
+
+`release.yml` 会做四件事：**校验 tag 与 `package.json` 版本一致**（不一致直接失败）、跑测试、发布 npm、创建 Release。想先空跑一次可以手动触发并勾选 `dry-run`。
+
+### npm 发布认证
+
+> ⚠️ **2025 年 11 月起 npm 只支持 Granular Access Token，经典 / Automation token 已被移除。**
+> 另外，**带 Bypass 2FA 的「直接发布」token 正在被废弃，2027 年 1 月起将无法再用它直接发布新版本**。
+> 因此长期方案是 **Trusted Publishing（OIDC）**，token 只用于完成首次发布。
+
+**第 1 步：首次发布（二选一）**
+
+- **本地手动发布（最省事）**：`npm login && npm publish --access public`。交互式 2FA 能正常完成，不必建 token。
+- **用 Granular Access Token**：npmjs.com → Access Tokens → Generate New Token → **Granular Access Token**，然后：
+  - **勾选 `Bypass two-factor authentication (2FA)`** —— CI 里没有交互式 2FA，不勾选会在发布时卡在 2FA 校验上失败；
+  - `Packages and scopes` → **`Read and write (publish and stage)`**；
+  - `Select packages` → 首次发布只能选 **`All packages`**（包还不存在，下拉里选不到它）；发布成功后建议收窄到 `dbx-plugin-skill`；
+  - `Organizations` → **`No access`**（组织权限只用于管理组织设置与成员，**与发布包无关**，给读写属于越权）；
+  - `Expiration` → 记下到期日，到期后 CI 会直接认证失败。
+  - 把 token 加到仓库 Secret `NPM_TOKEN`。
+
+**第 2 步：切到 Trusted Publishing（推荐，长期方案）**
+
+包首次发布后，在 npmjs.com 该包的 **Settings → Trusted Publisher** 添加：
+
+| 字段 | 值 |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `eryajf` |
+| Repository | `dbx-plugin-skill` |
+| Workflow filename | `release.yml`（只填文件名，必须与 `.github/workflows/` 下的文件同名） |
+| Allowed actions | 勾选允许 **`npm publish`**（否则只能 `npm stage publish`） |
+
+然后**从仓库删掉 `NPM_TOKEN`**，`release.yml` 会自动走 OIDC，不再有 token 过期问题。
+
+要求：npm CLI ≥ 11.5.1 且 Node ≥ 22.14.0（`release.yml` 已 `npm install -g npm@latest`）。仅支持 GitHub 托管 runner，自建 runner 不支持。
+
+`release.yml` 会先判断 `NPM_TOKEN` 是否存在：有就用 token，没有就走 OIDC —— 两种配置都能跑，可平滑迁移；发布失败时会额外打印常见原因提示。
+
+### 上游漂移检查
+
+skill 大量记录 DBX 的**契约细节**（字段枚举、权限语法、协议常量、商店校验规则）。上游一改，文档就可能过期。`upstream-drift.yml` 每周把这个契约的指纹与 `.github/upstream-baseline.json` 里的基线比对：
+
+- **只开 issue，不自动改基线** —— 保证提醒不会被静默吞掉。
+- 维护者按 issue 里的步骤核对并更新 `skill/references/*.md`，然后 `npm run upstream:update` 重新基线化并提交。
+- 只有 sha256 变化、事实无差异时，通常只是上游排版变动，确认后直接重新基线化即可。
+
+---
+
+## 更新已安装的 skill
+
+```bash
+dbx-plugin-skill doctor      # 会对比 npm 上的最新版本并给出升级提示
+npm install --global dbx-plugin-skill@latest && dbx-plugin-skill install
+```
+
+`install` 是幂等的：重新执行即覆盖为当前版本。想从源码跟随（不装 npm 包）就用 `--link`。
+
+---
+
+## 事实来源
+
+本 skill 的内容对齐以下权威来源，并在文档中标注了「文档 vs 脚本」的已知冲突：
+
+- 官方文档：<https://dbxio.com/cn/docs/plugin-development>
+- 上游平台仓库 `t8y2/dbx`：`plugins/manifest.schema.json`、`plugins/README.md`（完整贡献点与协议）、`plugins/RELEASING.md`、`plugins/sdk/{cli,packager,dev-host,rust,go}`
+- 官方商店仓库 `t8y2/dbx-store`：`CONTRIBUTING.md`、`schemas/plugin-candidate.schema.json`、`scripts/validate.mjs`、同步与签名 Workflow
+
+> 插件上架 PR 提到 **`t8y2/dbx-store`**，不是 `t8y2/dbx`。普通插件源码留在你自己的仓库。