DSH plugin 最小复现怎么做:一个 cordis.yml、一个入口与三条诊断命令就够
插件不生效时,最亏的一件事是:你花了两个小时删代码,最后发出去的还是一整个仓库,对方回一句「我这边跑不起来」。最小复现不是给别人看的礼貌,它是你自己定位问题的最后一步。
什么时候值得做 DSH plugin 复现包
DSH plugin 复现包只在环境差异、公开求助和自查混乱这三种情况下值得做。
不是每个问题都要做。三种情况做了收益最大:
第一种,问题只在某些环境出现。 你本机能跑,同事那边不行,说明差异在环境或配置,不在代码逻辑。复现包能把差异压缩到具体某一行。第二种,要在 issue 或群里求助。 没有复现包,讨论会退化成「你试试这个」「还是不行」,来回几轮之后问题还在。
第三种,你自己越改越乱。 加了一堆日志、注释掉一半代码,已经说不清原始状态。重新做一个最小目录,比在废墟上排查快。
反过来,能稳定复现且五分钟能定位的问题,不要做复现包。 直接把错误日志和命令贴出来就够。
DSH plugin 复现包只要三样东西
一个能跑的最小复现,目录里通常只有三个文件:
repro/
├── cordis.yml # 一行 patch,指向入口
├── entry.ts # 插件入口,只保留触发问题的最少代码
└── README.md # 版本、命令、期望与实际
cordis.yml 用最小的一行插入:
- insert:
- id: repro
name: './entry.ts'
入口文件要能独立运行,不 import 项目里的私有包。 一旦依赖内部工具库,别人拿到也跑不起来,复现包就失效了。README 不是可选项。 三行就够:dsh 版本、复现命令、期望结果与实际结果。缺了期望,对方无法判断自己有没有复现成功。
DSH plugin 复现包五步删减,每步都要复跑
删减 DSH plugin 复现包时每一步只删一类,删完必须复跑确认问题还在。
删减的顺序决定了效率。按下面五步走:
- 先删无关插件行:把
cordis.yml里与本问题无关的插件全部去掉,只留一个;删完重启,问题还在才继续; - 再删无关配置:配置项只保留触发问题的那几个字段,其余用默认值;
- 删代码分支:入口里只保留触发路径,事件监听、工具注册、后台任务按需保留;
- 删依赖:把项目内的 import 替换成最小实现或直接内联,确保目录能独立跑;
- 确认边界:把剩下的最后一段再删一次,问题消失,说明它就是触发点;问题还在,说明还能继续删。
每一步只删一类,删完必须复跑。 一次删三类,问题突然消失时你不知道是哪一类导致的,只能退回重来。别怕删过头——删到问题消失,再把最后删掉的那一段加回来,你就得到了精确的触发条件,这比「大概和这个插件有关」有价值得多。
一份可以直接贴的 DSH plugin 复现模板
一份可粘贴的 DSH plugin 复现模板要写清环境、步骤、期望、实际与已排除五项。
复现包的说明按这个结构写,读的人不需要追问:
## 环境
- 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、原样执行命令。
角色互换时,顺序反过来。收到复现包先做三件事:
- 核对版本:
dsh --version与说明里的版本是否一致,不一致先记录; - 用临时 DSH_HOME 跑:
DSH_HOME=$(mktemp -d),避免污染自己的 profile; - 原样执行复现命令,不要先「优化」参数;确认能复现,再开始改。
第 3 条常被违反。 一上来就换端口、换版本、加日志,最后复现不出来,双方都以为是对方环境的问题。如果复现不了,先别下结论。 把版本、Node、系统、命令逐项对照,差异通常就在其中一项。
最小复现的终点不是「让对方看到错误」,而是「让对方看到同一个错误」。看到同一个错误,讨论才有共同前提。想看常见故障的修法,读 DSH plugin 开发常见错误;想看调试命令怎么组合,读 DSH plugin 本地调试;想按四层自测,读 DSH plugin 怎么测。
常见问题
不建议直接发整包,DSH plugin 的最小复现只需要一行 patch、一个入口文件与三条诊断命令。整包包含无关插件、私有依赖与配置,别人很难判断哪一部分触发了问题,而这些文件交付成本低、定位也更快。
先删无关的插件行,再删与复现路径无关的代码分支。每次只删一类,删完复跑一次,确认问题还在。删到再删就不复现的那一刻,剩下的就是最小面。
至少三个:dsh --version 的输出、Node 版本、以及插件所在 profile 名称。缺了版本,别人可能用另一代行为跑出不同结果,最后讨论的不是同一个问题。
建议写成一条可直接粘贴的 DSH plugin 复现命令,包含 --patch 路径与端口。脚本能减少「少写一个参数」造成的差异,但不要把安装、构建、启动全塞进去,否则失败时又分不清是哪一步。
相关术语
- 最小复现
- 最小复现是把问题缩减到仍能触发的最少代码与配置,让其他人按同样步骤得到同样结果。— DeepSeek Harness 开发文档
- 复现包
- 复现包是交付给他人运行的最小目录,通常包含一份配置文件、一个插件入口与一段说明。— DeepSeek Harness 开发文档
- 覆盖层
- 覆盖层是通过 --patch 传入的配置 patch 文件,用来在不改 profile 的情况下插入或覆盖插件行。— DeepSeek Harness CLI 行为参考
- dump-config
- dump-config 是不启动服务、直接输出组合后配置树的命令,用于确认 patch 叠加后的实际配置。— DeepSeek Harness CLI 行为参考
来源
- DeepSeek Harness 开发文档:第一个插件· deepseek-harness
- DeepSeek Harness 开发文档:插件配置· deepseek-harness
- DeepSeek Harness CLI 行为参考· deepseek-ai