dsh-plugin-dev-skills/examples/hello-plugin

One-Line Description

This is a minimal runnable example that comes with the dsh-plugin-dev-skills repository. It registers a placeholder plugin named hello-plugin with DSH to demonstrate the standard pattern for plugin loading and automatic ctx.effect cleanup. It provides no business functionality—it's merely a reference template for developers learning DSH plugin development.

Core Capabilities

• Upon loading, outputs [hello-plugin] plugin loaded! in the host log as a visual indicator that the plugin layer was loaded correctly
• Registers a 5-second heartbeat timer via ctx.effect that continuously outputs [hello-plugin] heartbeat
• Demonstrates the standard Cordis plugin model entry point: export name and apply(ctx), with no build steps required
• Demonstrates the composite package declaration in package.json via dsh.bundle.patch pointing to cordis.patch.yml
• Demonstrates the insert写法 in cordis.patch.yml: declares id and name so Node module resolution can locate the installed plugin code
• Serves as a copy-paste runnable example accompanying the dsh-plugin-dev skill references/plugin-anatomy.md documentation

Technical Implementation

• Language: JavaScript (ESM, "type": "module")
• Key Dependencies: No runtime dependencies; relies solely on ctx.effect provided by the host Cordis container (from @deepseek-ai/dsh or its runtime packages)
• Architecture Pattern: Cordis plugin model—registers cleanable side effects via ctx.effect in apply(ctx); the returned cleanup function is automatically called by the host when the plugin is unloaded
• Entry File: examples/hello-plugin/index.js

Use Cases

Suitable for developers learning DSH plugin development who want to complete the full chain of "plugin loading and lifecycle cleanup." After reading the references/plugin-anatomy.md documentation and wanting a minimal example you can directly run with dsh plugin add, install this example and observe the [hello-plugin] plugin loaded! message in the terminal logs along with the heartbeat every 5 seconds. This lets you visually confirm whether the plugin layer is loaded correctly and whether ctx.effect cleanup is working. For production scenarios, extend this example as needed.

Prerequisites & Compatibility

Installation

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

Configuration

This plugin requires no additional configuration. All behaviors (startup logs, heartbeat interval, cleanup timing) are directly written in the index.js source code, with no configuration options exposed.

FAQ

Q: What practical functionality does this plugin provide after installation?

A: None. It only prints a log line upon loading, then prints a heartbeat every 5 seconds. Its entire value lies in demonstrating the minimal skeleton of a DSH plugin and the lifecycle cleanup mechanism, allowing you to visually observe whether the plugin layer is loaded correctly.

Q: Does this plugin require a build step?

A: No. index.js is pure ESM JavaScript that the host loads directly as a Node module; the package.json files field also only publishes index.js and cordis.patch.yml—no TypeScript compilation or bundling steps.

Q: After installation, once I see [hello-plugin] plugin loaded!, how long until I see the heartbeat?

A: 5 seconds. The setInterval interval is hardcoded to 5000ms in index.js:11, printing [hello-plugin] heartbeat every 5 seconds from the moment the plugin finishes loading.

Q: Does the heartbeat stop immediately after uninstalling the plugin?

A: Yes. The cleanup function returned by ctx.effect is automatically called by the host when the plugin is unloaded; the clearInterval inside it clears the timer and stops the heartbeat output. This is the standard paradigm this example emphasizes: all side effects requiring cleanup must be placed in ctx.effect, otherwise they will leak upon unload.

Q: What's the difference between this example and the greet-tool example in the same repository?

A: hello-plugin is a minimal lifecycle example that only demonstrates plugin loading and automatic ctx.effect cleanup; greet-tool is a model-callable tool example that demonstrates the three-part defineTool pattern: parameters, execute, and output. The two focus on different aspects—reading both is recommended.

Q: Why is id written as hello instead of hello-plugin in cordis.patch.yml?

A: This is a naming choice for the Cordis layer id; there's no mandatory correspondence with the name field exported in index.js. The id is the layer identifier in the configuration graph, while name is the logical name of the plugin at runtime—they can differ.

Q: What are the core knowledge points one can learn from reading the hello-plugin source code?

A: Three things: package.json dsh.bundle.patch must point to cordis.patch.yml; index.js only needs to export name and apply(ctx); any side effects registered through ctx (here, setInterval) must be placed in ctx.effect to avoid leaking upon unload.

Difficulty Level

Beginner — the example itself is only 15 lines of code: one setInterval call plus a cordis.patch.yml. Getting it to run means you've already mastered the standard skeleton of DSH plugin loading and lifecycle cleanup.

Known Issues & Limitations

• The heartbeat interval 5000 ms and the heartbeat message '[hello-plugin] heartbeat' are both hardcoded inside the setInterval callback in index.js—the source code has no configuration reads or environment variable branches; to modify the interval or message, you must edit the source (evidence: examples/hello-plugin/index.js:11-13)
• Both id: hello and name: dsh-hello-plugin in cordis.patch.yml are hardcoded strings; if a plugin id with the same name already exists in the user's environment, a naming conflict will occur (evidence: examples/hello-plugin/cordis.patch.yml:2-3)
• No engines, peerDependencies, os, or cpu fields are declared in the source code—DSH version compatibility must be validated by the host side (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 提问"开发一个 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。