dsh-plugin-dev-skill

An AI Skill for developing DeepSeek Harness (dsh) plugins.

English | 中文

---

What is this?

This project provides a knowledge-packed Skill file (SKILL.md) that teaches AI coding assistants how to write dsh plugins. When loaded into a TraeCode, Cursor, Claude Code, or any Agent Plugins v1-compatible client, it gives the AI instant access to:

• dsh's Cordis-based "Everything is a Plugin" architecture
• Complete extension point map (15+ mechanisms)
• Copy-paste templates for 5 plugin types (Tool, Hook, LLM Adapter, UI, Session Event)
• Package structure conventions and naming rules
• Turn flow reference and event dispatch modes
• Verification checklist and best practices

It is NOT a dsh runtime plugin itself — it is a development-time knowledge asset that makes AI assistants write better dsh plugins, faster.

Why use this skill?

Writing dsh plugins requires understanding Cordis services, typed events, the session log invariant, tool execution contracts, and 15+ extension points. Without this skill, an AI assistant has to guess or hallucinate API shapes. With it, the AI gets it right the first time.

Without skill	With skill
Hallucinated ctx.registerTool()	Correct ctx.tools.register(defineTool({...}))
Wrong event names	Correct tools/pre-execute waterfall
Missing inject field	Correct export const inject = ['tools']
Impure UI presenters	Pure presentCall / presentResult
Manual load-order hacks	Declarative inject dependency

Quick Start

Option A: TraeCode / Trae IDE

Copy the skills/dsh-plugin-dev/ directory to your project's .trae/skills/ folder:

cp -r skills/dsh-plugin-dev /your/project/.trae/skills/

The skill auto-triggers when you ask the AI about dsh plugins.

Option B: Cursor / Claude Code / Other Agent Plugins v1 clients

Copy skills/dsh-plugin-dev/SKILL.md to your project's .agents/skills/dsh-plugin-dev/SKILL.md or equivalent skills directory.

Option C: Reference only

Read skills/dsh-plugin-dev/SKILL.md directly as a cheat sheet.

Project Structure

dsh-plugin-dev-skill/
├── README.md                         # This file
├── LICENSE                           # MIT
├── .gitignore
├── skills/
│   └── dsh-plugin-dev/
│       └── SKILL.md                  # The core skill file (knowledge base)
├── examples/
│   ├── tool-plugin/
│   │   ├── index.ts                  # Example: JSON formatter tool
│   │   └── cordis.yml                # Plugin loading config
│   ├── hook-plugin/
│   │   └── index.ts                  # Example: Safety-gate permission hook
│   └── llm-adapter/
│       └── index.ts                  # Example: Custom LLM provider adapter
└── docs/
    ├── architecture-zh.md            # dsh 架构速览（中文）
    └── quickstart-zh.md              # 快速上手（中文）

What's inside the Skill?

Extension Point Map (15+ mechanisms)

Goal	Mechanism
Add a model provider	ctx.llm.registerAdapter()
Add a model-facing tool	ctx.tools.register(defineTool({...}))
Permission gate / policy	tools/pre-execute waterfall
Add a human command	ctx.commands.register()
Background work	ctx.jobs.start()
Filesystem access/policy	ctx.fs provider or fs/* events
Sandbox confinement	ctx.sandbox backend
Intercept request/tool/turn	agent/* or tools/* events
Inject model-facing context	agent.inject()
UI / editor integration	ctx.agents + session/event
Durable session state	extend SessionEventMap
System prompt section	ctx.systemPrompt.section()
Scheduled tasks (cron)	timer → followup() when idle
MCP server adapter	discover → ctx.tools.register()
Session title generation	ctx.sessionTitle provider

Plugin Type Templates

1. Tool Plugin — The most common type. Registers a model-callable tool with typed parameters, canonical output, and optional UI cards.
2. Hook Plugin — Intercepts tool calls for permission gating, audit logging, or policy enforcement.
3. LLM Adapter — Connects a new model provider to dsh's streaming pipeline.
4. UI Plugin — Renders from the session/event feed and drives input back through agent.followup().
5. Session Event — Extends durable session state with model-visible data.

Best Practices (9 rules)

1. Prefer events for interception; prefer service methods for direct calls
2. Every registration needs a disposer
3. Keep tool executors focused — put policy in tools/pre-execute
4. UI presenters must be pure (they run on streaming AND replay)
5. Secrets via Cordis Config — never read key files in code
6. Name by responsibility (Controller/Store/Registry/Runtime/etc.)
7. One ctx key per concept
8. Honor exec.signal for cancellation
9. Model-visible = logged

Compatibility

• dsh version: Target @deepseek-ai/dsh 0.1.0-rc.5+
• Node.js: 22.19+ or 24+
• Skill clients: TraeCode, Cursor, Claude Code, OpenCode, Kimi Code, ZCode, Codex, or any Agent Plugins v1.0.0 conformant client

Contributing

Contributions are welcome! If you find an outdated API reference, missing extension point, or have a new template to add:

1. Fork this repo
2. Edit skills/dsh-plugin-dev/SKILL.md
3. Add/update examples in examples/
4. Submit a PR

Related Resources

• DeepSeek Harness GitHub — Official repo
• Official Docs — Developer documentation
• Community Plugins — 300+ community plugins
• Cordis Framework — The underlying plugin framework
• Architecture Doc — Deep dive
• Extension Cookbook — Feature-to-mechanism map
• Awesome DSH Plugins — Plugin ecosystem radar

License

MIT

---

中文说明

本项目是一个 AI Skill 知识库，帮助 AI 编程助手正确地编写 DeepSeek Harness (dsh) 插件。

它本身不是 dsh 运行时插件，而是一个开发期的知识资产，让 AI 助手在写 dsh 插件时不再猜测 API 形状。

使用方式

TraeCode / Trae IDE：

cp -r skills/dsh-plugin-dev /your/project/.trae/skills/

Cursor / Claude Code 等： 将 SKILL.md 复制到项目的 .agents/skills/ 目录下。

包含内容

• Cordis 微内核架构概述和 5 大核心概念
• 15+ 扩展点映射表（从添加工具到沙箱配置）
• 5 种插件类型的完整代码模板
• 包结构规范和命名规则
• Turn 执行流程和事件分发模式
• 验证清单和 9 条最佳实践
• 3 个可运行的示例插件

相关文档

• 架构速览
• 快速上手