DSH plugin 本地调试：--patch 覆盖层怎么用、--dump-config 看配置、改了不生效怎么排查

DSH plugin 本地调试有两条通道：改源码阶段用 --patch 覆盖层挂载绝对路径的插件文件（改完重启即生效），要验证分发产物才用 dsh plugin --profile <name> add 装进 profile；两者验证的目标不同，混用会把「没挂载」误判成「代码有问题」。 无论你叫它 DSH插件 还是 DeepSeek插件，这两条通道的边界都一样。

DSH plugin 两条调试通道怎么选

判断标准只有一条：你要验证的是「加载」还是「安装」。（来源）

调试源码时永远先用覆盖层，因为它的反馈链路最短：不需要 package.json 齐备、不需要打包、不需要走 pnpm 安装。

用 --patch 覆盖层挂载 DSH plugin 源码

覆盖层的两条硬规则：插件路径必须绝对，patch 只贡献配置。 官方教程的写法分三步（来源）：

1. 取绝对路径：先 pwd 拿到检出根，写进配置的必须是完整绝对路径。
2. 写覆盖层配置：在 ./scratch-plugin/cordis.yml 里插入插件行：

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

3. 带覆盖层启动：pnpm dsh web --patch ./scratch-plugin/cordis.yml，预期插件随之加载、改完源码重启即生效。

为什么「写在 patch 里却没加载」多半不是语法问题：patch 不改变 loader 解析模块路径所用的 profile 目录，所以相对路径、软链、拼错的绝对路径都会静默失效。

用 --dump-config 看 DSH plugin 的配置树

不看配置树就调试，等于闭眼改代码。 dsh 提供两个不启动就能看合成结果的开关（来源）：

1. 看合成后的配置树：dsh --profile demo --dump-config，预期输出含各层 patch 叠加结果。
2. 看默认配置树：dsh --profile demo --dump-default-config，用于与合成结果对照。

合成顺序决定了「谁压过谁」：

1. 各 bundle 的 patch（按 dsh.profile.bundles 顺序）
2. profile 自己的 cordis.patch.yml
3. 家目录的 $DSH_HOME/cordis.patch.yml
4. --patch 覆盖层（优先级最高）

越靠后越优先，所以覆盖层能压过 profile 配置。理解了这层顺序，就能解释「明明改了配置却不生效」。

按 Fiber 状态定位 DSH plugin 加载到哪一步

插件的生命周期是一个状态机，卡在哪一步就说明问题在哪一类。（来源）

PENDING ──▶ LOADING ──▶ ACTIVE
                │
                └──▶ FAILED        ACTIVE ──▶ UNLOADING ──▶ DISPOSED

• 根本没进入状态机：加载器没解析到这个模块——回去查路径与 patch。
• 停在 LOADING 或 FAILED：依赖没就绪（inject 里声明的服务不存在）或 apply 抛了异常。
• ACTIVE 但行为不对：插件加载成功，问题在注册逻辑或事件模式选择。
• 卸载后还在跑：手动资源没交给 ctx.effect。

处置器的一个坑：逆序开始调用，但异步处置器并发执行、不保证逐个完成；有顺序依赖的清理必须合并进同一个 ctx.effect。

DSH plugin 改了不生效的五步排查

按成本从低到高查，通常第一步就命中。

1. 确认 patch 被带上：启动命令里有没有 --patch，文件路径是否正确。
2. 确认你的行进了配置树：dsh --profile demo --dump-config 搜索插件 id。
3. 确认路径是绝对路径：相对路径不会报错，只会静默不加载。
4. 确认源码已重新编译：跑的是入口产物还是源码，改的文件是否是真正入口引用的那个。
5. 确认不是被上层覆盖：同一 id 是否在 profile 或家目录配置里被改写（合成顺序见上一节）。

DSH plugin 清理与卸载验证

调试阶段就要验证清理，否则问题会推迟到用户机器上爆发。 两条规则：通过 ctx 注册的东西（事件监听、工具、定时器）会在插件卸载时自动清理；手动资源（网络连接、文件句柄）必须包进 ctx.effect() 交出处置器（来源）。

验证手段：卸载插件后观察日志是否停止、服务是否仍可访问。服务类问题（如重复注册）见 服务重复注册的排查；插件压根没激活见 插件没激活的排查。

最后补几条容易忘的命令与前提：

• 源码运行需要先 pnpm run build（生产运行需要构建产物），再用 pnpm dsh <args...> 转发参数；
• launcher 只解析自己的参数，第一个它不认识的 token 开始算应用参数——两者顺序不能颠倒；
• web 与 headless profile 首次使用时从模板自动初始化，其他 profile 必须通过 dsh plugin 创建；
• 无效命令、错误配置与启动失败都会以非零码退出——退出码非零就是真的失败，不要忽略。

环境本身没搭好的先看 开发环境搭建；调试通过后按 开发规范 过自检，再进 打包成 bundle。