DSHIO-DEV · 开发规范

插件怎么写才算合格。六条要求，每条都给出正确写法和常见错误。

这条标准的边界。 它不规定插件「应该做什么功能」，只规定「怎么交付才算合格」。功能好坏是作者的自由，能不能被可靠安装和加载是标准管的事。

1. 项目结构

一个可安装的插件包至少要有三个文件：

package.json          ← 必需，声明 dsh.bundle
cordis.patch.yml      ← 必需，声明要插入的插件
lib/index.js          ← 必需，导出 apply(ctx)

要求	说明
1.1	`package.json` 的 `main` 或 `exports` 指向真实存在的入口文件
1.2	不打包 `node_modules`、`.git`、测试文件
1.3	仓库根目录有 README，说明插件做什么、怎么装

2. manifest 规范

这是最常被拒的一条。DSH 只认 dsh.bundle，光有 dsh.client 装不上。

正确写法：

{
  "name": "your-plugin",
  "version": "1.0.0",
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  },
  "engines": { "dsh": ">=0.2.0" }
}

错误写法（装了但不会加载）：

{
  "dsh": { "client": { "platform": "web" } }   // ← 只有 client，没有 bundle
}

要求	说明
2.1	`dsh.bundle.patch` 必须存在，指向真实文件
2.2	`cordis.patch.yml` 里 `name` 与 package name 一致
2.3	`engines.dsh` 只写下界，不封顶

关于 2.3 —— 这是装不上最常见的原因。

❌ "dsh": ">=0.2.0-rc.2 <0.2.2-0"   // 排除了 0.2.2，用户在最新版装不上
✅ "dsh": ">=0.2.0"                // 只写下界

我们实测的 122 个头部插件里，有 8 个因为这个封顶写法装不上。

3. 权限声明

插件的能力必须显式声明，因为用户需要据此判断风险。

取值	含义	风险
`none`	不访问外部资源	低
`network`	发起网络请求	中
`filesystem`	读写工作区文件	高
`shell`	执行系统命令	高
`device`	访问硬件（摄像头/麦克风等）	高

要求	说明
3.1	在 README 里列出用到的权限
3.2	不声明未使用的权限（过度声明会拉高风险等级）
3.3	多个权限同时使用时，风险取最高

4. 版本策略

要求	说明
4.1	遵循 SemVer：MAJOR 破坏性变更、MINOR 新增、PATCH 修复
4.2	破坏性变更要在 CHANGELOG 说明，并同步抬 `engines.dsh` 下界
4.3	不重复发布同一个版本号

5. 错误处理

DSH 的加载器在旧版本里有个特性：任何一个插件抛错，可能拒绝整棵加载树。

要求	说明
5.1	`apply(ctx)` 里对可能失败的步骤做 try/catch
5.2	缺少依赖时降级或禁用自身，不要抛到宿主
5.3	错误信息要能定位（包含插件名和出错步骤）

6. 安全红线

违反任何一条，永久移出目录。

编号	禁止行为
6.1	写入工作区之外的系统路径
6.2	读取或上传用户凭据（API key、token、cookie）
6.3	未经用户明确同意建立常驻进程或计划任务
6.4	把用户数据外发到第三方（不告知、无开关）
6.5	安装时执行破坏性命令（删除、格式化、批量改权限）
6.6	伪装成官方插件（名称、图标、作者信息）

自查清单

发布前逐条对照。全部通过即符合 DSHIO-DEV v1.0。

[ ] package.json 有 dsh.bundle.patch
[ ] cordis.patch.yml 的 name 与 package name 一致
[ ] engines.dsh 只写下界，没有封顶
[ ] README 列出声明的权限
[ ] 没有声明未使用的权限
[ ] apply() 对失败步骤有 try/catch
[ ] 不违反 6.1 - 6.6 任何一条

下一步

写完对照 DSHIO-TEST 自测，通过后按 DSHIO-GRADE 拿等级。

版本历史

版本	标准号	发布日期	变更内容
v1.0	`DSHIO/T 01—2026`	2026-11-06	首次发布

条款变更时版本号递增，旧版本保留可查。