Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

dsh-plugin-development

开发、维护、分发和验证 DeepSeek Harness (DSH) 插件的执行型 Skill。覆盖 host/client 形态判断、bundle/profile 契约、Service 与函数插件、工具、HTTP、持久化、slot、Conversation Node、客户端构建、HMR、GitHub 安装和真实组合验证。

GZX2211 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add GZX2211/dsh-Visual-Workflow --skill dsh-plugin-development

About this skill


name: dsh-plugin-development description: 开发、维护、分发和验证 DeepSeek Harness (DSH) 插件的执行型 Skill。覆盖 host/client 形态判断、bundle/profile 契约、Service 与函数插件、工具、HTTP、持久化、slot、Conversation Node、客户端构建、HMR、GitHub 安装和真实组合验证。 metadata: version: "3.1.0" date: "2026-08-13"

DSH 插件开发

这是正式版导向的执行清单。先判断运行面,再选择官方模板,实现后必须从真实组合和用户安装路径验证。不要把某个项目的偶然实现当成框架契约。

1. 开始前

  1. 用 pwd、git rev-parse --show-toplevel、git status --short --branch 确认项目与用户改动。
  2. 读取 package.json、cordis.patch.yml、tsconfig*.json、构建配置、相关 src/ 和测试。
  3. 不覆盖用户改动,不操作用户明确排除的 profile、端口或实例。
  4. 判断最小运行面:
    • 工具、system prompt、HTTP、持久化、provider:host。
    • slot、Conversation Node、浏览器状态和浮层:client。
    • host 能力且需要 Web 可视化:host + client。
    • 没有 Web 需求:不要声明 dsh.client,也不要构建 client bundle。
  5. 写下插件唯一职责、依赖的 service、贡献的配置行、持久化 owner 和用户可见验证面,再开始编码。

2. 证据与官方参考

2.1 取证顺序

行为不确定时按顺序取证,不猜:

  1. 当前项目及已安装 node_modules/@deepseek-ai/* 的 package.json、exports、types、README。
  2. 环境明确提供的 DeepSeek Harness checkout;只读分析,不修改。
  3. 克隆官方仓库取证(见 §2.3)。
  4. 信息仍不足时,以当前正式版 exports/types 为边界,选择可安全失败的最小实现并标注假设。

不要写死本机绝对路径,也不要访问或转述未授权的私有仓库内容。

2.2 官方模板选择

若提供了 Harness checkout(环境提供或按 §2.3 克隆),优先按插件形态阅读这些模板;路径以 checkout 根目录为基准:

目标主参考学习重点
Host Service / HTTPpackages/host/webserverService、static Config、Service.init、route disposer、连接清理
最小 client 插件packages/client/ui-message-feedbackinject、apply、locale、per-session controller、slot 注册与清理
Slot / Conversation Nodepackages/client/ui-conversation + packages/client/ui-slotsSlotMap、slot kind/scope、children 认领、keyed node renderer
Bundle 分层packages/bundle/base + packages/bundle/web-app顶层 patch 数组、行 id 覆盖、整段 config 替换、加载顺序
简单持久化 backendpackages/storage/storage-jsonregister → disposer → close、显式 root、并发打开门禁
崩溃安全日志packages/session/session-persistence-jsonl原子发布、fsync、并发 no-clobber、torn-tail 处理
工具插件packages/fs/tool-fsdefineTool、schema、render、可选能力挂载
Client 测试packages/test-support/client-runtimejsdom、SlotTestRuntime、mount/dispose、fake service

复杂插件只用于补证据,不作为起步模板。若要委派只读调研,提示词必须要求给出文件、行区间、契约与最小建议。

2.3 官方仓库兜底层

官方仓库 https://github.com/deepseek-ai/deepseek-harness 是公开、MIT 许可的可引用证据源(默认分支 master;开发者预览阶段无 release tag,不 pin 版本)。需要兜底取证时:

  1. 选临时目录:用用户或环境提供的目录,例如 SCRATCH="$(mktemp -d)";不要写死本机绝对路径。

  2. 复用已有 checkout:若 $SCRATCH/dsh-official 已存在,且 git remote -v 指向官方、根目录含 AGENTS.md 与 LICENSE,直接复用;需要更新时 git -C "$SCRATCH/dsh-official" fetch --depth 1 origin master && git -C "$SCRATCH/dsh-official" reset --hard origin/master(或删除后重克隆)。同一任务只维护这一个目录,避免反复克隆。

  3. 浅克隆(只读取证,无需 pnpm install):

    git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness.git "$SCRATCH/dsh-official"
    
  4. 只克隆官方 deepseek-ai/deepseek-harness;不要访问或转述未授权的私有仓库内容。对克隆内容同样只读分析,不修改。

进入后定位:

  1. 先读根 AGENTS.md(CLAUDE.md 是它的符号链接):仓库布局、命令与约定一次讲清,是官方给 agent 的入口。
  2. 再用 packages/README.md 的 group 表确认目标包位于哪个 packages/<group>/<pkg>。
  3. 按 §2.2 模板表读对应包的 README.md 与 src/;取证结论给出文件与行区间。

演进兜底:官方仓库处于开发者预览、迭代极快、无兼容承诺、无 release tag,§2.2 的模板路径只是索引,一切以当前 checkout 的实际代码为准;路径或名称漂移时,用 packages/README.md 定位新位置并回报修正,不要凭旧文档猜。需要复现一致证据时记录 git rev-parse HEAD。

3. Bundle、Profile 与 package 契约

3.1 两个概念

  • Bundle 是作者分发的包:package.json.dsh.bundle.patch 指向配置层。
  • Profile 是用户运行的组合:$DSH_HOME/profiles/<name>/package.json.dsh.profile.bundles 保存有序 bundle 列表。
  • 插件作者写 bundle;dsh plugin 创建和维护 profile。不要手写用户 profile manifest。

3.2 最小双面 package

{
  "name": "dsh-my-plugin",
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "exports": {
    ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
    "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" },
    "./cordis.patch.yml": "./cordis.patch.yml",
    "./package.json": "./package.json"
  },
  "files": ["lib", "cordis.patch.yml", "README.md"], // 目录或显式清单均可;官方仓库常用显式文件清单
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": ["@deepseek-ai/dsh-client-runtime"]
    }
  }
}

规则:

  • Host-only 包删除 ./client 与 dsh.client。
  • Client 包必须同时有 dsh.client.platform: "web" 和真实存在的 exports["./client"]。
  • dsh.client.inject 是随图下发的信息性元数据(预检展示 / HMR diff 用),不决定 client fiber 的激活顺序;预取由 dsh.client.immediately 驱动,真正的依赖等待来自 client bundle 导出的 export const inject(§5.1),两者互不替代。
  • dsh.client.immediately 是仅供启动关键入口使用的可选预取标记;普通第三方插件不要默认开启。
  • 当前权威字段是 dsh.client;历史兼容字段只有在目标正式部署仍明确读取时才添加。
  • exports、files 和 Git/发布产物必须一致;任何入口都不能指向不存在的文件。
  • DSH、Cordis、React 等共享运行时优先声明为 peer,避免复制 runtime identity;版本范围从目标正式版 package metadata 取证。

3.3 Patch 层

cordis.patch.yml 必须是顶层数组:

- insert:
    - id: my-plugin
      name: dsh-my-plugin
      config: {}

注意:

  • id 是配置树中稳定的行身份;name 是 Node 可解析的包名或导出路径。
  • 后层按 id 覆盖前层;目标行的 config 是整段替换,不是深合并,因此覆盖时要重述所需键。
  • 生效顺序是 profile bundles → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → 命令行 --patch;后者获胜。
  • 包没有 dsh.bundle 时只会成为普通依赖,不会自动成为 profile 层。

4. Host 面实现

4.1 函数插件

普通插件通常导出:

export const name = 'my-plugin'
export const inject = ['tools']
export interface Config { enabled: boolean }
export const Config = z.object({ enabled: z.boolean().default(true) })
export function apply(ctx: Context, config: Config): void {}
  • z 从 @deepseek-ai/schemastery 导入(不是 zod);static Config = Config 引用导出的 schema,与官方内联的 static Config: z<Config> = z.object({...}) 等价。
  • inject 是必需 service;未满足时 fiber 保持 pending,框架会在服务就绪后激活,不要用轮询模拟依赖注入。
  • Config 默认值放 schema;任何部署可能需要改变的值都应成为配置,而不是源码常量。
  • 可选 service 用 ctx.get() 判断或 ctx.inject([...], childCtx => ...) 惰性挂载;不要在 apply() 中抢跑兄弟 provider。

4.2 Service 插件

当插件提供稳定 service 时,参考 host/webserver:

export class MyService extends Service {
  static Config = Config
  constructor(ctx: Context, config: Config) {
    super(ctx, 'myService')
  }
  async [Service.init](): Promise<void> {}
}
  • 构
Read the complete source ↗