插件开发技能 green-dalii/dsh-plugin-dev-skill

DeepSeek Harness (DSH) 插件开发技能

一个让任何 AI 编码 Agent 都能正确开发 DeepSeek Harness（DSH） 插件的 Agent Skill——高效、符合官方规范。

加载 SKILL.md，Agent 即可获得心智模型、可直接照抄的代码模板、分步开发流程与验证清单；深度背景见 References/ 下的 11 篇精简提炼文档。

别称 / 检索关键词：DSH 插件开发技能、DeepSeek Harness 插件开发、dsh-plugin-dev-skill。

目录

- 为什么需要这个技能
- 你能得到什么
- 三步上手
- 结构
- 自检能力
- 安装
- 作为 DSH 技能
- 在其他 Agent 宿主中使用（Claude Code、Codex）
- 常见问题（FAQ）
- 资料来源
- 相关项目
- 贡献
- 许可

为什么需要这个技能

写一个 DSH "Hello World" 插件只需一行。但要写出正确的插件——defineTool 输出契约遵守、可逆效应替代手工清理、inject 依赖语义、Standard Schema 配置校验、事件分发模式选型、真正能装上车的打包——才是本技能编码的内容。

技能基于第一性原理：每条铁律都基于底层框架 Cordis 的学术基础（arXiv:2608.25512），并把这些原理落地成可直接照抄的代码模板。SKILL.md 里每条 API 陈述都对照真实 SDK 类型在声明基线（@deepseek-ai/ 0.2.1-alpha.4、cordis 4.0.5-alpha.1）实测过，模板通过 tsc --strict。

你能得到什么

- 心智模型先行：Cordis「可逆效应 + 反应式余效应」理论，凝练成 6 条任何插件作者都必须遵守的铁律。
- 覆盖五类插件面：tool（defineTool）、llm（adapter）、service（definition + provider + consumer）、event（dispatch modes）、bundle（profile + manifest + Plugin Manager）。
- 模板经过真实 SDK 验证：代码样例通过 tsc --strict，并在真实 Cordis loader 下端到端跑通。
- 自带自检：附带 scripts/verify.sh——一行基线复核（版本一致性 + SKILL.md frontmatter 合法性 + 上游 URL 存活），项目自身的 CI 在每次 push 上都会跑它。
- Tag-pinned 更新检查：见 SKILL.md §0.1 与 AGENTS.md 「Mandatory flow on entry」。
- 可追踪上游：每篇参考文档末尾附官方文档 URL。

Agent 介入仓库时的约定（加载、检查、不能动哪些文件）见 AGENTS.md。

三步上手

1. 安装本技能（推荐符号链接——见 安装）。
2. 打开 SKILL.md；Agent 会自动跑 §0.1 的更新检查并提示是否有新版本。
3. 照着 SKILL.md §11 的四阶段流程（侦察 → 实现 → 验证 → 交付）走。
4. Agent 写工具时：用 SKILL.md §4 里的 defineTool 模板（整段照抄，只需改四个字段 name / description / parameters / output.schema）。
5. 发版或提 PR 前：跑 bash scripts/verify.sh——绿灯意味着版本、frontmatter 与所有上游链接都一致。

结构

dsh-plugin-dev-skill/
├── SKILL.md # 主技能文件：操作手册（Agent 接入后先读这个） ├── VERSION # 技能版本号；SKILL.md §0.1 要求载入时检查它 ├── AGENTS.md # CLI Agent 自动读取的约定文件 ├── README.md # 英文说明（默认） ├── README.zh-CN.md # 本文件（中文说明） ├── CHANGELOG.md # 变更日志 ├── CONTRIBUTING.md # 贡献指南 ├── SECURITY.md # 安全政策 ├── LICENSE # MIT ├── References/ # 人机可读的精简提炼参考资料 │ ├── 00-INDEX.md # 索引 │ ├── 01-dsh-architecture.md # DSH 架构总览 │ ├── 02-plugin-basics.md # 插件基础：形态/生命周期/effect/HMR │ ├── 03-tools.md # 工具开发完整参考（defineTool） │ ├── 04-config.md # 插件配置与 Schemastery │ ├── 05-llm-adapter.md # LLM 适配器指南 │ ├── 06-framework-services-events.md # 服务与依赖、事件系统 │ ├── 07-publish.md # 打包/安装/profile/配置层 │ ├── 08-capability-layering.md# 三种角色能力设计与 seam 目录 │ ├── 09-cordis-primer.md # Cordis 入门与 ctx API 速查 │ ├── 10-spatiotemporal.md # 论文解读（时空可组合性） │ └── 11-cookbook.md # 扩展模式（钩子/UI/协议桥/功能→机制） ├── scripts/ │ └── verify.sh # 基线复核（版本/frontmatter/链接），CI 在每次 push 上跑 └── .github/workflows/ci.yml # GitHub Actions：verify.sh + 上游 release 信号

自检能力

scripts/verify.sh 是本项目自身的质量门。它检查三件事：

1. 版本一致：VERSION、SKILL.md frontmatter metadata.version、最新 CHANGELOG 标题、README 徽章读到的值必须一致。
2. SKILL.md frontmatter 合法：name 必须是 kebab-case（^[a-z0-9]+(?:-[a-z0-9]+)$）；description 与 metadata.{version, upstream, sdk-baseline} 必须存在。
3. 上游 URL 存活：.md 内所有指向 deepseek-harness.github.io、github.com/deepseek-ai/、cordis、arxiv.org、私有 registry.npmmirror.com 与 raw.githubusercontent.com 的 URL 必须返回 2xx。CDN 临时 000 会重试；npmjs.org 上 @deepseek-ai/dsh- 包返回 403 是允许的（这些包只在私有 registry）。

macOS bash 3 兼容；支持 SKIP_FRONT=1 / SKIP_VERSION=1 / SKIP_URLS=1 局部跳过。

bash scripts/verify.sh # 绿灯退出 0；任何漂移退出 1

安装

作为 DSH 技能

DSH 的 skill 系统接受「目录包（<name>/SKILL.md）」或「平铺 Markdown（<name>.md）」两种形态；发现不递归（刻意不支持 */SKILL.md）。本地发现根目录按优先级：

| 根目录 | 适用场景 |
| <项目根>/.dsh/skills | 项目级（rank 100） |
| <项目根>/.agents/skills | 项目级（rank 200） |
| customSkillDirs（宿主配置） | 宿主指定（rank 300） |
| $DSH_HOME/skills（即 ~/.dsh/skills） | 用户级（rank 400） |
| $DSH_HOME/../agents/skills（即 ~/.agents/skills） | 用户 agents 目录（rank 500） |
| 内置技能目录 | 随 DSH 发行（rank 600） |

例如安装为用户级技能：安装目录名必须与 SKILL.md frontmatter 中的 name 一致（dsh-plugin-dev-skill），且需符合 kebab-case：

推荐：符号链接到 git 检出，之后一句 git pull 即可保持最新
git clone https://github.com/green-dalii/dsh-plugin-dev-skill.git ~/src/dsh-plugin-dev-skill
ln -s ~/src/dsh-plugin-dev-skill ~/.dsh/skills/dsh-plugin-dev-skill

或者：普通拷贝（更新时需要重新拷贝）
mkdir -p ~/.dsh/skills/dsh-plugin-dev-skill
cp SKILL.md VERSION ~/.dsh/skills/dsh-plugin-dev-skill/
cp -r References ~/.dsh/skills/dsh-plugin-dev-skill/References

保持最新：本技能自带 VERSION，并在 SKILL.md §0.1 要求 Agent 载入后的第一件事就是检查是否有新版本——git ls-remote --tags 取最新发布 tag，再读 ${TAG}/VERSION（tag 钉死，避开 main 分支 CDN 缓存延迟），做语义化比较；若远端更新则先更新（符号链接/git 检出走 git pull；普通拷贝走重新 clone + rsync），更新完再使用本技能。推荐的安装形态就是上面的符号链接：一句 git pull 就地把已加载的技能更新掉；DSH 会跟随符号链接的技能目录（watchFollowSymlinks 默认开启），Claude Code 与 Codex 同样支持。如果无法检查（离线、无网络、无写权限），Agent 应明确说明「未能检查更新」，并基于本地版本继续，而不是假装检查过。

在其他 Agent 宿主中使用（Claude Code、Codex）

本技能遵循开放的 Agent Skills 标准：一个包含 SKILL.md 与 YAML frontmatter（name / description / whenToUse）及配套 References/ 目录的文件夹——与 Claude Code、Codex 及众多 Agent 宿主使用的形态一致，凡是支持 Agent Skills 的地方都可以安装。

方式 A：让 Agent 自己安装（推荐）——直接把仓库地址告诉它，让它自行克隆安装。例如在 Claude Code 会话里粘贴：

请把 https://github.com/green-dalii/dsh-plugin-dev-skill 这个技能安装到 ~/.claude/skills/dsh-plugin-dev-skill/，之后我处理 DeepSeek Harness 插件开发时加载 SKILL.md。

或者在 Codex CLI 会话里粘贴：

请把 https://github.com/green-dalii/dsh-plugin-dev-skill 这个技能安装到 ~/.agents/skills/dsh-plugin-dev-skill/。

通用说法（适用于任何 Agent）：

请把 https://github.com/green-dalii/dsh-plugin-dev-skill 安装到你的技能目录（文件夹 dsh-plugin-dev-skill，内含 SKILL.md 与 References/），当任务涉及开发 DeepSeek Harness（DSH）插件时使用它。

方式 B：手动安装

| Agent / 宿主 | 安装位置 | 调用方式 |
| Claude Code（个人级） | ~/.claude/skills/dsh-plugin-dev-skill/SKILL.md | /dsh-plugin-dev-skill，或描述匹配时自动加载 |
| Claude Code（项目级） | <仓库>/.claude/skills/dsh-plugin-dev-skill/SKILL.md | 同上 |
| Codex CLI（用户级） | ~/.agents/skills/dsh-plugin-dev-skill/SKILL.md | /skills 浏览，$dsh-plugin-dev-skill 提及 |
| Codex CLI（仓库级） | <仓库>/.agents/skills/dsh-plugin-dev-skill/SKILL.md | 同上 |
| DSH | ~/.dsh/skills/dsh-plugin-dev-skill/SKILL.md | 见上方作为 DSH 技能 |
| 任意 Agent Skills 宿主 | <技能目录>/dsh-plugin-dev-skill/SKILL.md | 按宿主说明 |

git clone https://github.com/green-dalii/dsh-plugin-dev-skill.git ~/.claude/skills/dsh-plugin-dev-skill
或改为符号链接： ln -s /path/to/dsh-plugin-dev-skill ~/.claude/skills/dsh-plugin-dev-skill

注意事项：

- 文件夹名请保持 dsh-plugin-dev-skill——必须与 frontmatter 中的 name 一致（Claude Code 会用它作为命令名）。
- 不支持的宿主会忽略 whenToUse 等扩展 frontmatter 字段，不影响加载。
- 彩蛋：DSH 同样读取项目级 .agents/skills，所以在 <仓库>/.agents/skills/dsh-plugin-dev-skill/ 放一份，Codex 与 DSH 可以共用。

常见问题（FAQ）

DeepSeek Harness（DSH）是什么？

DeepSeek Harness 是一个 Agent Harness SDK：其中每一项能力——工具、LLM 适配器、文件访问、沙箱、持久化，乃至 agent loop 本身——都是挂载到共享上下文上的插件。它没有「特权内核」可供打补丁，扩展方式就是挂载插件。上游仓库：deepseek-ai/deepseek-harness；官方文档：deepseek-harness.github.io。

不装这个技能就不能写 DSH 插件吗？

能写。最小插件只是一个导出 apply(ctx) 函数的模块，官方文档也讲了。本技能的价值在于一次写对：defineTool 的规范输出契约、用可逆效应替代手工清理、inject 的依赖语义、Standard Schema 配置校验、事件分发模式选型，以及真正能装上车的打包方式。

用它可以做出什么？

用 defineTool 注册的工具、LLM 适配器（LlmAdapter.stream()）、服务定义/提供方/消费方、监听 tools/ 与 agent/ 的钩子插件、UI 插件、协议桥（ACP、SDK）、后台任务，以及可发布的组合包与 profile。

哪些 Agent 能加载它？

任何实现 Agent Skills 标准的宿主，包括 DSH（项目级与用户级技能目录）、Claude Code（~/.claude/skills/）与 Codex CLI（~/.agents/skills/）——详见安装。

技能内容是英文的吗？

技能正文（SKILL.md）与参考资料以中文撰写（与官方 DSH 文档一致）；代码模板、API 名与命令行与语言无关。README 提供英文与中文两个版本。

它适配哪个 DeepSeek Harness 版本？

@deepseek-ai/ 0.2.1-alpha.1 与 cordis 4.0.5-alpha.1——所有 API 陈述都是对该版本实测验证的。0.2.0 落地了几个关键改名（ctx.codeRuntime → ctx.ptcRuntime、Plugin Manager 随发行版交付、E2B 系提供方移除改由 SSH 家族接管远程能力）；0.2.1-alpha.1 主要是 Web 体验与 bug 修复，对 tool/LLM/service 插件公共 API 0 破坏。完整差异记录在 CHANGELOG.md 与各参考文档中。

如何保持最新？

推荐把技能安装为指向 git 检出的符号链接，git pull 即可就地把已加载的技能更新掉。此外，技能在每次载入时会检查自身版本：把本机 VERSION 与最新发布 tag 比对，若有新版本则先更新再使用（SKILL.md §0.1）。远端检查只取一个极小的文件，离线时会优雅降级。

可以让 Agent 自己安装吗？

可以。把仓库地址告诉 Agent，让它把技能装进自己的技能目录即可——可直接复制上文方式 A 里的提示词。

发现 API 写错或链接失效怎么办？

欢迎开 Issue 或 PR——见 CONTRIBUTING.md。每篇参考文档末尾都附有官方文档 URL，便于核对并修正上游漂移。

资料来源

- 官方文档站（中文/英文）：https://deepseek-harness.github.io/deepseek-harness/develop/basic/
- 源码仓库：https://github.com/deepseek-ai/deepseek-harness
- 最新 tag 发布：https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-alpha.4
- 论文：《A Programming Paradigm for Spatiotemporal Composability》（Cordis 框架的学术基础，arXiv:2608.25512）：https://arxiv.org/abs/2608.25512

所有参考文档均为精简提炼（不是官方文档照搬），以「开发出正确、高效、符合规范的插件」为目标组织。

相关项目

同一作者的其它项目：

| 项目 | 简介 |
| green-dalii/dsh-shift-router | DSH 的双层模型路由器：LLM Judge 路由、多模型回退链、指数退避的运行时故障转移，以及任务级编排。同时也是一个按本技能所讲规范构建的真实 DSH 插件实例。 |
| green-dalii/pi-shift-router | dsh-shift-router 所改编的原版 Pi coding-agent 扩展：由 LLM judge 把每一轮 agent 交给合适的模型——例行工作走快速执行，难题走强推理——并带多模型故障转移。主页 |
| GD4AI/obsidian-llm-wiki | Obsidian 社区插件（id karpathywiki），实现 Karpathy 的 LLM Wiki：把笔记与 PDF 变成互相链接的 LLM 知识库——实体页/概念页、图驱动的问答、本地优先隐私。主页 |
| green-dalii/obsidian-llm-wiki-cli | 无头摄取 CLI（npm karpathywiki-cli，llm-wiki 可执行文件）：在 Node 下直接跑插件生产环境的 WikiEngine，不需要 Obsidian 渲染器、零 obsidian 导入。 |

贡献

欢迎提交 Issue 与 PR！请先阅读 CONTRIBUTING.md。安全相关问题见 SECURITY.md。提 PR 前先本地跑 bash scripts/verify.sh——CI 也会跑一遍。

许可

MIT © 2026 green-dalii