开发与运行时
plugin-template
omdsh-dev/plugin-template · ★ 13
插件模板仓库(基于 turtle-ui 官方仓库)。
查看 manifest 检查详情
安装
dsh plugin --profile web add github:omdsh-dev/plugin-templateGitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试
安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗
项目说明
English | 中文
面向 DeepSeek Harness 0.2.2-rc.3 的 ESM Cordis 插件自包含独立仓库模板。仓库用到的每个源文件、编译器配置、测试夹具、贡献说明、skill 和构建辅助都位于本目录以下。DSH 宿主是成品包的运行时消费者,不是源码或构建输入。
文档地图
| 需要 | 阅读 |
|---|---|
| 契约规则:插件形态、manifest、依赖、展示、生命周期、组合、client、分发 | docs/dsh-plugin-contracts.md |
| 端到端工作流与阶段路由 | .agents/skills/dsh-plugin-development/SKILL.md |
| 源码、测试与补丁布局 | src/LAYOUT.md、tests/LAYOUT.md、patches/LAYOUT.md |
| 命令、CI 与发布流程 | 本 README 与 .github/workflows |
仓库布局
.
├── .agents/skills/ # 仓库本地插件开发工作流
│ ├── dsh-plugin-development/ # 端到端协调器
│ └── dsh-plugin-*/ # 阶段 skill
├── docs/
│ └── dsh-plugin-contracts.md # 权威的包与集成契约
├── patches/
│ └── LAYOUT.md # 依赖补丁与 DSH host patch 契约
├── scripts/
│ ├── extract-patch.mjs # host patch 再生成
│ └── patch.sh # 幂等的 host patch 应用
├── src/
│ ├── assets/
│ │ ├── icon.svg # 通过 `./icon` 导出的插件图标
│ │ └── locale/
│ │ ├── en.json # 展示元数据
│ │ └── zh.json
│ ├── LAYOUT.md # 源码模块增长规则
│ ├── config.ts # Schemastery schema 与默认值
│ ├── index.ts # Loader 面向的函数插件命名空间
│ └── runtime.ts # 宿主边界与激活
├── tests/
│ ├── LAYOUT.md # 测试约定
│ ├── harness.ts # 共享的真实 Cordis 测试挂载
│ ├── plugin.test.ts # Loader 与激活测试
│ └── snapshots/
│ └── LAYOUT.md # 可选的产品可见 fixture
├── .oxlintrc.json # 类型感知 Oxlint 配置
├── AGENTS.md # 贡献者常驻规则与导航
├── cordis.patch.yml # profile bundle 贡献
├── package.json # 导出、peers、engines 与 bundle 元数据
├── pnpm-lock.yaml # 可复现依赖图
├── pnpm-workspace.yaml # 包管理器策略
├── tsconfig.json # 编译器与类型感知 lint 工程
├── tsdown.config.ts # 源码到运行时/声明的构建
└── vitest.config.ts # 测试运行器配置
包契约
完整契约由 docs/dsh-plugin-contracts.md 拥有。以下是方向性要点:
- 函数插件以同一个 ESM 命名空间导出
name、inject、Config和apply,不提供 default export。 engines.node为>=24.9.0;engines.dsh声明支持的 DSH 范围;dsh.manifestVersion与dsh.bundle.patch描述公开的 bundle 层。- Plugin Manager 通过导出的
./locale/*.json与./icon读取展示元数据。本模板把物理文件放在src/assets/并列入files。 @deepseek-ai/cordis与@deepseek-ai/schemastery是宿主提供的 peer,同时在devDependencies中供本地检查;详见 dependencies。- 有浏览器面的包声明
dsh.client,并在./client导出构建后的 bundle。
创建你的插件
- 在
package.json、Loader 属主、配置/运行时属主、聚焦测试、bundle 元数据、TypeScript 元数据、两份 README、AGENTS.md与src/assets/中替换包身份。 - 选择完整的 npm 包名。它可以是 scoped 或 unscoped;不要默认继承模板的
@your-scope/dsh-前缀。只在身份属主中替换,不要在.agents/skills/里全局替换。 - 把
engines.dsh设为实际支持的范围;除非有意采用不同宿主契约,保持engines.node为 Node 24 LTS 或更高。 - 更新
keywords、LICENSE、cordis.patch.yml以及展示标题、描述和图标。 - 只加入实现实际使用的 DSH 宿主服务;放置每个包时按 dependencies 分类。
- 在运行时/服务属主中实现激活与宿主边界行为,让注册归插件 fiber 所有,并在测试中证明销毁。
- 保持每个源码、编译器、文档和工程引用路径都在本仓库内。不要添加
link:或file:依赖。 - 只有当包的公共依赖与分发产物就绪时,才把
private设为false。
不要给函数插件添加 default export。Cordis Loader 会解包 exports.default ?? exports;多余的 default export 会丢弃 inject、Config 和 apply。
内置开发 skills
完整流程从 dsh-plugin-development 开始,也可以直接调用某一阶段:
| Skill | 用途 |
|---|---|
| plan | 决定形态、依赖、配置、兼容性、展示、组合、证据与分发。 |
| scaffold | 从模板实例化并基线验证新仓库。 |
| align | 在不改变行为的前提下迁移现有仓库到本工具链。 |
| implement | 实现生命周期安全的行为、配置、元数据、文档与测试。 |
| client | 添加 dsh.client 浏览器面、slot、settings 表单与 ModuleLoader 检查。 |
| i18n | 用类型化字典与销毁证据本地化浏览器 UI。 |
| compose | 把 bundle 安装进 profile,并证明激活与兼容性。 |
| test | 为 Loader、行为、销毁、组合与产物选择最小证据。 |
| release | 在不发布的前提下检查 packed、Git 或 npm 发布就绪度。 |
复制模板时保留这些目录。
独立开发
在本仓库根目录运行:
pnpm install
pnpm run fmt:check
pnpm run lint
pnpm test
pnpm run build
pnpm pack --dry-run --json
lint 是类型感知的静态分析门;test 使用 Vitest forks 池,禁止子进程 fork 的受限宿主可在本地运行 vitest run --pool=threads;build 生成可直接打包的 lib/ 运行时与声明,不运行安装期构建。
CI
- check.yml:在
main推送、pull request 与手动触发时运行检查,两个构建 workflow 都会调用它。 - test-build.yml:只能手动触发,构建测试包。
- release-build.yml:由
v*.*.*tag 或手动触发构建发布包。 - npm-publish.yml:先校验 SHA256,再通过 OIDC trusted publishing 把成功的 test 或 release 构建发布到 npm。
普通 main 推送只运行检查,不会触发发布。包配置好 trusted publisher 后,test 与 release 构建会进入 npm 发布流程。
npm 配置、版本规则与 provenance 限制见 release skill。
Profile 激活
通过插件通道安装:
dsh plugin --profile <profile> add <package-or-tarball>
Profile 启动时检查 engines.dsh,按 bundle 顺序应用 dsh.bundle.patch,并在不激活插件的情况下读取展示元数据。见 manifest 与兼容性 与 bundle 组合。
插件形态
export const name = 'plugin-template'
export const inject: string[] = []
export { Config } from './config.ts'
export { apply } from './runtime.ts'
// src/config.ts
import Schema from '@deepseek-ai/schemastery'
export interface PluginConfig { /* 可序列化字段 */ }
export const Config: Schema<PluginConfig> = Schema.object({ /* 校验与默认值 */ })
// src/runtime.ts
export function apply(ctx: Context, config: PluginConfig): void { /* effects */ }
Config 是 Cordis Loader 校验的 schema 值;PluginConfig 是公开的 TypeScript 配置形状。将两者分开命名可以避免声明合并与 no-redeclare 的误报。服务提供者改为 default-export 它的 Service 子类;两种形态不要混用。
分发
打包前先构建并检查归档:
pnpm run build
pnpm pack --dry-run --json
归档必须包含 main、types、exports 与 files 承诺的每个文件,以及 bundle patch 与展示资源的物理文件。见 构建与分发。Git 安装获取源码;只有确实要通过这种方式分发时,才添加自包含的 prepare 构建,并说明消费方需要授予的构建脚本批准。
测试
自带测试证明 Loader 安全的 ESM 导出与 schema 解析后的激活。把激活断言替换为对每个 registry 贡献的可观察行为与销毁断言。产品可见插件还应在消费它的 DSH 应用中添加真实 Loader/profile 组合测试;见 tests/LAYOUT.md 与 证据。