# dsh-plugin-dev-skills

> DSH 插件开发技能包中的最小生命周期示例，演示插件加载与 ctx.effect 自动清理的标准写法。

## Metadata

- Author: [@zimodzh](https://github.com/zimodzh)
- Repo: <https://github.com/zimodzh/dsh-plugin-dev-skills.git>
- GitHub: [zimodzh/dsh-plugin-dev-skills](https://github.com/zimodzh/dsh-plugin-dev-skills)
- Stars: 38
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://github.com/zimodzh/dsh-plugin-dev-skills>
- Topics: `agent`, `agent-skill`, `agent-skills`, `ai`, `ai-agent`, `awesome-dsh-plugin`, `claude-code`, `codex`, `deepseek`, `deepseek-harness`, `dsh`, `dsh-plugin`, `llm-agent`, `skill`, `skills`
- Forks: 1
- Open Issues: 0
- Last push: 2026-08-18T07:33:42.000Z
- Added: 2026-08-19T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills/examples/hello-plugin
```

## Wiki

## 一句话定位
这是 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 依赖 |

## 安装方式
```bash
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）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-plugin-dev-skills](https://deepseek-plugin.org/plugins/zimodzh/dsh-plugin-dev-skills/examples/hello-plugin)
Wiki generated by AI (model: `MiniMax-M3`)