DSH 插件开发技能包中的最小生命周期示例，演示插件加载与 ctx.effect 自动清理的标准写法。
ⓘ 此插件是大仓库 zimodzh/dsh-plugin-dev-skills 的子包，星数与活跃度统计的是整个仓库。
- License
- MIT
- 分支
- master
安装
$ dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills/examples/hello-plugin在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
对话式安装
帮我安装 DeepSeek Harness 插件 zimodzh/dsh-plugin-dev-skills/examples/hello-plugin：先查看仓库 https://github.com/zimodzh/dsh-plugin-dev-skills.git 确认安全性，然后执行安装命令并验证插件加载成功。
把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。
一句话定位
这是 dsh-plugin-dev-skills 仓库自带的一个最小可运行示例，向 DSH 注册一个名为 hello-plugin 的占位插件，用于演示插件加载与 ctx.effect 自动清理的标准写法。它不提供任何业务功能，只是给想学习 DSH 插件开发的用户的参考样板。
核心能力
- 加载时在宿主日志输出一行
[hello-plugin] plugin loaded!，作为插件层被正确加载的视觉信号 - 通过
ctx.effect注册一个 5 秒一次的心跳定时器，持续输出[hello-plugin] heartbeat - 演示 Cordis 插件模型的标准入口：export
name与apply(ctx)，无需任何构建步骤 - 演示
package.json通过dsh.bundle.patch指向cordis.patch.yml的组合包声明方式 - 演示
cordis.patch.yml的insert写法：声明id与name，让 Node 模块解析找到已安装的插件代码 - 作为 dsh-plugin-dev 技能
references/plugin-anatomy.md文档配套的可复制运行示例
技术实现
- 语言: JavaScript（ESM，
"type": "module"） - 关键依赖: 无任何运行时依赖，仅依赖宿主 Cordis 容器提供的
ctx.effect（来自@deepseek-ai/dsh或其运行包） - 架构模式: Cordis 插件模型，
apply(ctx)中通过ctx.effect注册可清理的副作用；返回的清理函数在插件卸载时由宿主自动调用 - 入口文件:
examples/hello-plugin/index.js
适用场景
适合正在学习 DSH 插件开发、想跑通"插件加载与生命周期清理"完整链路的开发者。当你读完 references/plugin-anatomy.md 文档想要一份能直接 dsh plugin add 跑起来的最小例子时，装上这个示例并观察终端日志里出现的 [hello-plugin] plugin loaded! 与每 5 秒一次的 heartbeat，就能直观确认 plugin 层是否被正确加载，以及 ctx.effect 的清理是否生效。生产场景请基于该示例自行扩展。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 未声明 | 仅依赖宿主自带的 Cordis 容器与 ctx.effect 接口，未在 package.json 中声明 engines |
| Node | 未声明 | 仅使用 ESM 语法，未在 package.json 中声明 engines |
| 平台 | 跨平台 | 纯 JavaScript 实现，无原生模块 |
| 原生模块 | 无 | package.json 中无 native 依赖 |
安装方式
dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills/examples/hello-plugin
配置项
本插件无需额外配置。所有行为（启动日志、心跳间隔、清理时机）都直接写在 index.js 源码里，没有暴露任何配置项。
常见问题
Q: 安装后这个插件能做什么实际功能？
A: 没有业务功能。它只在加载时打印一行日志，然后每 5 秒打印一次心跳。它的全部价值在于演示 DSH 插件的最小骨架与生命周期清理机制，让你用肉眼观察到 plugin 层是否被正确加载。
Q: 这个插件需要构建步骤吗？
A: 不需要。index.js 是纯 ESM JavaScript，宿主直接当 Node 模块加载；package.json 的 files 字段也只发布 index.js 和 cordis.patch.yml 两个文件，没有 TypeScript 编译或打包步骤。
Q: 安装后看到 [hello-plugin] plugin loaded! 之后要等多久会看到心跳？
A: 5 秒。setInterval 间隔在 index.js:11 写死为 5000 毫秒，从插件加载完成时刻开始每 5 秒打印一次 [hello-plugin] heartbeat。
Q: 卸载插件后心跳会立即停止吗？
A: 是的。ctx.effect 返回的清理函数会在插件卸载时被宿主自动调用，里面的 clearInterval 会清掉这个定时器，停止继续输出心跳。这也是这个示例想强调的标准范式：所有需要清理的副作用都必须放进 ctx.effect，否则卸载时会泄漏。
Q: 这个示例和同仓库的 greet-tool 示例有什么区别？
A: hello-plugin 是最简生命周期示例，只演示插件加载与 ctx.effect 自动清理；greet-tool 是模型可调用的工具示例，演示 defineTool 的 parameters、execute、output 三段式写法。两者侧重点不同，建议一起读。
Q: 为什么 cordis.patch.yml 里 id 写成 hello 而不是 hello-plugin？
A: 这是 Cordis 层 id 的命名选择，与 index.js 里 export 的 name 字段没有强制对应关系。id 是配置图里的层标识，name 是插件在运行时的逻辑名，二者可以不同。
Q: 看 hello-plugin 源码能学到的核心知识点是什么？
A: 三个：package.json 的 dsh.bundle.patch 必须指向 cordis.patch.yml；index.js 只需要 export name 和 apply(ctx)；任何通过 ctx 注册的副作用（这里是 setInterval）必须放进 ctx.effect，卸载时才不会被泄漏。
上手难度
入门 — 示例本身只有 15 行代码，一个 setInterval 调用加一个 cordis.patch.yml，跑通即代表已经掌握了 DSH 插件加载与生命周期清理的标准骨架。
已知问题与限制
- 心跳间隔
5000毫秒与心跳文案'[hello-plugin] heartbeat'都直接写在index.js的setInterval回调里，源码中没有读取任何配置或环境变量分支，想要修改间隔或文案只能改源码（evidence: examples/hello-plugin/index.js:11-13） cordis.patch.yml中id: hello和name: dsh-hello-plugin都是硬编码字符串，如果用户环境里已有同名插件 id 会产生命名冲突（evidence: examples/hello-plugin/cordis.patch.yml:2-3）- 源码中未声明任何
engines、peerDependencies、os、cpu字段，DSH 版本兼容性需由宿主侧校验（evidence: examples/hello-plugin/package.json:1-8）
中文 · English
一套遵循 Agent Skills 规范 的技能，用于开发 DeepSeek Harness（DSH） 插件。
DSH 是一个插件化的 Agent Harness SDK：模型适配器、工具注册表、会话日志、甚至 agent loop 本身，全都是可以从配置里替换的 Cordis 插件。本技能把官方文档里散落在教程、参考手册与生成目录中的约定，收敛成一套可执行的标准——任何加载了它的 agent，都能用同一种方式开发 DSH 插件。
注意： 本技能为社区维护项目，与 DeepSeek 官方无隶属关系，亦未获官方背书。
技能里有什么
dsh-plugin-dev/
├── SKILL.md # 入口：frontmatter、8 条硬规则、6 个场景工作流、决策速查表、完成前检查清单
├── references/ # 12 份详细标准，按需加载；索引见 references/README.md
├── examples/ # 两个可复制、可运行的最小示例
│ ├── hello-plugin/
│ └── greet-tool/
└── evals/ # description 的触发评测集与评测方法
references 覆盖：插件形态与生命周期 · 服务与依赖注入 · 五种事件分发模式 · 插件配置 · 上下文/Fiber/注册表 API · 三种角色能力设计（Definition/Provider/Consumer）· 工具开发 · LLM 适配器协议 · 插件形态扩展（工具/钩子/UI/协议桥）· 打包与安装 · 仓库内 workspace 包 · 完整能力 seam 目录。
目录结构
dsh-plugin-dev/
├── SKILL.md # 技能入口：frontmatter、8 条硬规则、6 个场景工作流、检查清单
├── LICENSE # MIT 许可证
├── README.md / README.en.md # 本说明（中文主 / 英文附）
├── references/ # 12 份详细标准（渐进式披露，按需加载）
│ ├── README.md / README.en.md # 目录索引：文件｜内容｜何时读
│ ├── plugin-anatomy.md # 插件形态、生命周期、Fiber、自动清理、HMR
│ ├── services.md # 服务定义/提供/消费、inject、隔离
│ ├── events.md # 五种事件分发模式、命名
│ ├── config.md # 插件配置与 cordis.yml 行
│ ├── context-api.md # 上下文 API、Fiber 类、注册表、继承的框架 API
│ ├── three-roles.md # 能力三种角色（seam）设计
│ ├── tools.md # 工具开发完整约定
│ ├── llm-adapter.md # LLM 适配器协议
│ ├── plugin-forms.md # 四种扩展形态 + 功能→机制映射
│ ├── packaging.md # 打包、安装与层序
│ ├── workspace-package.md # monorepo 内新建包的清单与命名
│ └── seams.md # 核心 seam 与能力服务全表、架构映射
├── examples/ # 可复制、可运行的最小示例
│ ├── README.md / README.en.md # 示例索引
│ ├── hello-plugin/ # 最小插件（生命周期 / 自动清理）
│ │ ├── README.md / README.en.md
│ │ ├── index.js
│ │ ├── package.json
│ │ └── cordis.patch.yml
│ └── greet-tool/ # 最小模型工具（defineTool）
│ ├── README.md / README.en.md
│ ├── index.js
│ ├── package.json
│ └── cordis.patch.yml
└── evals/ # description 触发评测集
├── README.md / README.en.md # 评测方法（训练/验证集划分）
└── trigger-queries.json # 12 正例 + 9 负例
安装
技能名为 dsh-plugin-dev，Agent Skills 规范要求所在文件夹同名；本仓库名为 dsh-plugin-dev-skills。克隆时直接指定目标文件夹名即可一步到位：
git clone https://github.com/zimodzh/dsh-plugin-dev-skills.git ~/.claude/skills/dsh-plugin-dev
把目标目录换成你所用 agent 的对应路径（见下表）；也可以下载 release 压缩包，解压后把文件夹改名为 dsh-plugin-dev。
无需构建、无需脚本依赖、无需任何配置——以上说的是技能本身。实际开发 DSH 插件则需要一个可用的 DSH 环境：Node.js、pnpm，以及示例中用到的 dsh。
| Agent | 项目级 | 用户级 |
|---|---|---|
| DeepSeek Harness | <project>/.dsh/skills/（rank 100）或 <project>/.agents/skills/（rank 200） | ~/.dsh/skills/（rank 400） |
| Claude Code | <project>/.claude/skills/ | ~/.claude/skills/ |
| Codex | <project>/.codex/skills/ | ~/.codex/skills/ |
| VS Code Copilot | <project>/.agents/skills/ | ~/.agents/skills/ |
| 其它兼容 agent | 按该 agent 的技能目录约定 | 同上 |
验证：向 agent 提问"开发一个 DSH 插件 / 写一个 DSH 工具"，技能应被触发；在 DSH 里也可以直接用 skill(dsh-plugin-dev) 工具加载确认。
版本对应
内容蒸馏自 DeepSeek Harness 官方文档站（2026-08 快照），并遵循官方「接口以生成参考为准」的原则：技能内容与仓库生成参考不一致时，以生成参考为准。发现偏差欢迎提 issue 或 PR。
触发评测
evals/trigger-queries.json 是 description 的回归评测集（12 条正例 + 9 条负例）。修改 description 前请先跑评测并记录通过率；方法论（含训练/验证集划分、防过拟合）见 evals/README.md。
示例
examples/hello-plugin—— 最小插件（bundle 格式）：dsh plugin --profile demo add ./examples/hello-plugin后dsh --profile demo启动，应看到加载日志和每 5 秒一次的心跳，卸载时自动清理。examples/greet-tool—— 最小模型工具：安装后对 agent 说 "Use the greet tool to greet Ada."，应收到 "Hello, Ada!"。
完整步骤见 examples/README.md。
范围边界
覆盖仓库内、文件式的 DSH 插件开发：插件包、cordis.yml 行、patch overlay、工具、适配器、组合包、profile、仓库内 workspace 包。不覆盖会话内动态插件（cordis_define/cordis_run 流）与 agent preset 组合编辑——这两类由各部署的专项技能或官方工具负责。
维护与贡献
- 更新任何 references 前，先核对官方文档对应页面（文档站或源码生成区块），并在 PR 中注明来源。
- 遵守 Agent Skills 约束：name 为 kebab-case 且与目录一致；description ≤ 1024 字符（DSH 目录注入提醒默认 500）；正文渐进式披露。
- 欢迎 PR：修正、更多示例、扩充评测集、其它语言版本。
License
MIT——见 LICENSE。
收录徽章
[](https://deepseek-plugin.org/plugins/zimodzh/dsh-plugin-dev-skills/examples/hello-plugin)把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。