ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 最小复现怎么做:一个 cordis.yml、一个入口与三条诊断命令就够

插件开发发布于 2026-11-05作者: DeepSeek Plugin 插件市场
DSH plugin最小复现求助诊断DeepSeek Harness
插件不生效,整仓库又不方便给出去?把问题缩成一个能跑的目录:一行 patch、一个入口文件、三条诊断命令,再按模板交付,别人十分钟能复现。

插件不生效时,最亏的一件事是:你花了两个小时删代码,最后发出去的还是一整个仓库,对方回一句「我这边跑不起来」。最小复现不是给别人看的礼貌,它是你自己定位问题的最后一步。

什么时候值得做 DSH plugin 复现包

DSH plugin 复现包只在环境差异、公开求助和自查混乱这三种情况下值得做。

不是每个问题都要做。三种情况做了收益最大:

第一种,问题只在某些环境出现。 你本机能跑,同事那边不行,说明差异在环境或配置,不在代码逻辑。复现包能把差异压缩到具体某一行。第二种,要在 issue 或群里求助。 没有复现包,讨论会退化成「你试试这个」「还是不行」,来回几轮之后问题还在。

第三种,你自己越改越乱。 加了一堆日志、注释掉一半代码,已经说不清原始状态。重新做一个最小目录,比在废墟上排查快。

反过来,能稳定复现且五分钟能定位的问题,不要做复现包。 直接把错误日志和命令贴出来就够。

DSH plugin 复现包只要三样东西

一个能跑的最小复现,目录里通常只有三个文件:

text
repro/
├── cordis.yml      # 一行 patch,指向入口
├── entry.ts        # 插件入口,只保留触发问题的最少代码
└── README.md       # 版本、命令、期望与实际

cordis.yml 用最小的一行插入:

yaml
- insert:
    - id: repro
      name: './entry.ts'

入口文件要能独立运行,不 import 项目里的私有包。 一旦依赖内部工具库,别人拿到也跑不起来,复现包就失效了。README 不是可选项。 三行就够:dsh 版本、复现命令、期望结果与实际结果。缺了期望,对方无法判断自己有没有复现成功。

DSH plugin 复现包五步删减,每步都要复跑

删减 DSH plugin 复现包时每一步只删一类,删完必须复跑确认问题还在。

删减的顺序决定了效率。按下面五步走:

  1. 先删无关插件行:把 cordis.yml 里与本问题无关的插件全部去掉,只留一个;删完重启,问题还在才继续;
  2. 再删无关配置:配置项只保留触发问题的那几个字段,其余用默认值;
  3. 删代码分支:入口里只保留触发路径,事件监听、工具注册、后台任务按需保留;
  4. 删依赖:把项目内的 import 替换成最小实现或直接内联,确保目录能独立跑;
  5. 确认边界:把剩下的最后一段再删一次,问题消失,说明它就是触发点;问题还在,说明还能继续删。

每一步只删一类,删完必须复跑。 一次删三类,问题突然消失时你不知道是哪一类导致的,只能退回重来。别怕删过头——删到问题消失,再把最后删掉的那一段加回来,你就得到了精确的触发条件,这比「大概和这个插件有关」有价值得多。

一份可以直接贴的 DSH plugin 复现模板

一份可粘贴的 DSH plugin 复现模板要写清环境、步骤、期望、实际与已排除五项。

复现包的说明按这个结构写,读的人不需要追问:

markdown
## 环境
- dsh: <dsh --version 输出>
- Node: <node -v>
- 系统: <macOS 14 / Ubuntu 24.04>
- profile: web

## 复现步骤
1. 解压 repro 目录
2. 执行:dsh --profile web --patch ./repro/cordis.yml
3. 打开终端输出

## 期望
日志出现 [repro] loaded,工具列表出现 repro_tool

## 实际
日志停在等待服务,进程没有退出

## 已排除
- 换端口无效
- 删除其他插件无效

「已排除」这一节的价值最高。 它告诉对方哪些方向不用再试,能省掉一半往返。版本信息要贴原始输出,不要转述——「最新版」这种描述在三天后就不再是最新。

四条让 DSH plugin 复现失效的写法

第一,复现包里引用了私有包。 别人装不上依赖,第一步就卡住。

第二,只给截图不给命令。 截图看不出启动参数、端口、profile,差一个参数结果就不同。

第三,把安装、构建、启动写成一个长脚本。 脚本中途失败时,无法判断是环境问题还是插件问题。

第四,删掉「看起来无关」的配置。 有些问题恰恰由默认值触发;删配置前先确认默认值与现值不同。

拿到别人的 DSH plugin 复现包,先跑这三条

拿到别人的 DSH plugin 复现包,先核对版本、换临时 DSH_HOME、原样执行命令。

角色互换时,顺序反过来。收到复现包先做三件事:

  1. 核对版本:dsh --version 与说明里的版本是否一致,不一致先记录;
  2. 用临时 DSH_HOME 跑:DSH_HOME=$(mktemp -d),避免污染自己的 profile;
  3. 原样执行复现命令,不要先「优化」参数;确认能复现,再开始改。

第 3 条常被违反。 一上来就换端口、换版本、加日志,最后复现不出来,双方都以为是对方环境的问题。如果复现不了,先别下结论。 把版本、Node、系统、命令逐项对照,差异通常就在其中一项。

最小复现的终点不是「让对方看到错误」,而是「让对方看到同一个错误」。看到同一个错误,讨论才有共同前提。想看常见故障的修法,读 DSH plugin 开发常见错误;想看调试命令怎么组合,读 DSH plugin 本地调试;想按四层自测,读 DSH plugin 怎么测。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 不生效时,可以直接把整个项目打包发出去求助吗?

不建议直接发整包,DSH plugin 的最小复现只需要一行 patch、一个入口文件与三条诊断命令。整包包含无关插件、私有依赖与配置,别人很难判断哪一部分触发了问题,而这些文件交付成本低、定位也更快。

做 DSH plugin 最小复现时,最先应该删掉的是什么?

先删无关的插件行,再删与复现路径无关的代码分支。每次只删一类,删完复跑一次,确认问题还在。删到再删就不复现的那一刻,剩下的就是最小面。

提交 DSH plugin 复现包时,需要带上哪些版本与运行环境信息?

至少三个:dsh --version 的输出、Node 版本、以及插件所在 profile 名称。缺了版本,别人可能用另一代行为跑出不同结果,最后讨论的不是同一个问题。

DSH plugin 复现命令要不要写成一条可以直接粘贴的脚本?

建议写成一条可直接粘贴的 DSH plugin 复现命令,包含 --patch 路径与端口。脚本能减少「少写一个参数」造成的差异,但不要把安装、构建、启动全塞进去,否则失败时又分不清是哪一步。

相关术语

最小复现
最小复现是把问题缩减到仍能触发的最少代码与配置,让其他人按同样步骤得到同样结果。— DeepSeek Harness 开发文档
复现包
复现包是交付给他人运行的最小目录,通常包含一份配置文件、一个插件入口与一段说明。— DeepSeek Harness 开发文档
覆盖层
覆盖层是通过 --patch 传入的配置 patch 文件,用来在不改 profile 的情况下插入或覆盖插件行。— DeepSeek Harness CLI 行为参考
dump-config
dump-config 是不启动服务、直接输出组合后配置树的命令,用于确认 patch 叠加后的实际配置。— DeepSeek Harness CLI 行为参考

来源