TrueHOOHA/dsh-plugin-dev-skill

dsh-plugin-dev-skill

一个用于辅助开发 DeepSeek Harness（dsh）插件的 AI Skill。

DeepSeek Harness 是基于 Cordis 的 agent 框架，插件是导出 apply(ctx: Context) 的 TypeScript 模块，通过 cordis.yml 组合装配。本 skill 为 AI 助手提供创建、修改、调试、打包 dsh 插件所需的知识，覆盖工具（tool）、服务（service）、LLM 适配器（adapter）、事件监听（event listener）等能力。

使用方式

将 dsh-plugin-dev/ 目录放入你的 skill 目录（如 .claude/skills/、.config/opencode/skills/），并开启插件开发模式。当用户提到以下内容时，本 skill 会被自动触发：

- 创建 / 修改 / 调试 / 打包 dsh 插件
- 编写 tool、service、LLM adapter、event listener
- 配置 cordis.yml 补丁
- 打包插件用于分发
- 提到 Cordis 生命周期、Fiber 状态、inject、ctx.effect、defineTool、Service 子类、LlmAdapter、Schemastery 配置、dsh.bundle 等

仅限 dsh 相关开发，不用于其他 agent / LLM 集成场景。

目录结构

dsh-plugin-dev/
├── SKILL.md            # Skill 主文件：核心概念速查 + 参考文档索引
├── agents/
│   └── openai.yaml     # Agent 元数据（显示名、默认提示词）
└── references/         # 离线文档库
├── basic/          # 入门教程：第一个插件、工具、配置、发布
│   ├── index.md    # 第一个插件：编写 apply(ctx) 并通过 --patch 加载
│   ├── tool.md     # 注册 tool：defineTool + ctx.tools.register
│   ├── config.md   # 插件配置：Config interface + Schemastery schema
│   └── publish.md  # 发布：dsh.bundle 清单、profile、dsh plugin add
├── cordis-tutorial/  # Cordis 框架分步教程（7 章，无需 API Key 即可运行）
│   ├── 01-first-plugin.md        # 最小插件 hello.ts
│   ├── 02-lifecycle-and-effects.md # 生命周期与 ctx.effect 清理
│   ├── 03-services.md            # 服务：提供与注入（inject）
│   ├── 04-events.md              # 事件：ctx.on / ctx.emit
│   ├── 05-config.md              # 配置校验与加载失败
│   ├── 06-composition-and-hmr.md # 插件树、group、isolate、HMR
│   ├── 07-into-the-harness.md    # 注册模型可调用的工具
│   └── index.md                  # 教程总览与环境准备
├── framework/      # 框架概念速查
│   ├── index.md    # 插件模型与 Fiber 状态机
│   ├── events.md   # 事件机制与 Harness 事件
│   └── service.md  # 服务注入、提供与隔离
└── practice/       # 进阶设计模式与集成
├── index.md    # 三层能力设计：定义 → 提供 → 消费
└── llm-adapter.md  # 接入新模型提供商：LlmAdapter.stream()

内容概览

SKILL.md 核心速查

| 主题 | 要点 |
| --- | --- |
| 插件结构 | 三种形式：函数 / 对象 { name, inject, apply } / 类（继承 Service） |
| 依赖注入 | export const inject = ['tools', 'llm']，依赖未就绪时插件处于 PENDING |
| 自动清理 | 所有经 ctx 注册的内容都是 effect，卸载自动回收；自定义资源用 ctx.effect() 包裹 |
| Fiber 状态 | PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED（可 FAILED） |
| 工具 | defineTool 自动生成 JSON Schema、校验参数、卸载时注销 |
| 配置 | 需同时导出 interface Config 与 const Config: Schema |
| 服务 | 提供方继承 Service，消费方声明 inject，group: true + isolate 实现隔离 |
| 事件 | emit / parallel / serial / bail / waterfall 五种模式 |
| LLM 适配器 | 继承 LlmAdapter 实现 stream()，按块顺序产出 StreamChunk |
| 发布 | 本地用 --patch，分发用 npm 包 + dsh.bundle，dsh plugin add 安装 |
| HMR | 加载 cordis-plugin-hmr + logger + timer 实现保存即重载 |

核心代码示例

// 最小插件
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-plugin'typescript
export function apply(ctx: Context) { /* 注册能力 */ }

// 注册一个工具
import { defineTool } from '@deepseek-ai/dsh-tools'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'greet', description: '...',
parameters: { name: { type: 'string', required: true } },
output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
async execute(args) { return Hello, ${args.name}! },
}))
}

许可证

Apache License 2.0