DSH 插件调试避坑：client.js 设置面板、热重载与高频报错排查表

CFzjyAI Engineer▍深耕领域AI Agent 架构设计Harness 插件开发Context Engineering多智能体协同 RAG▍技术底座PythonTypeScript·Cordis 插件MCP Skills·FastAPIDocker▍工程能力专注 Agent 运行时与 Harness 插件开发、长上下文与流式交互优化、LLM 全链路工程化落地「 让 AI 交互更智能让技术落地更高效 」欢迎技术探讨 / 项目合作关注解锁大模型与智能交互的无限可能DSH 插件调试避坑client.js 设置面板、热重载与高频报错排查表《DeepSeek Harness 插件架构》连载专栏 · 第 09 篇开发实战篇到这里收尾07 搭工程骨架、08 写工具契约这一篇解决最憋屈的问题——插件写对了却装不活不报错、不输出、界面也不显示。DSH 的调试和传统框架最大的不同是它默认安静依赖没就绪的插件停在 PENDING 状态既不报错也不提示热重载缺一个辅助服务就静默停摆客户端卡片写错了只回退、不报错。这一篇把三条装死链路全部拆开给你一套从猜到查的排查方法。痛点一插件装进 profile 不生效日志里干干净净。没有报错、没有异常、没有提示——因为它根本停在 PENDING压根没进 apply。痛点二改代码保存了热重载没反应。你以为 HMR 坏了其实它缺个 timer 服务早就静默停在 PENDING 等死。痛点三客户端 UI 面板 / 工具卡片写好了界面上就是不显示。没有报错只回退到通用卡片——因为你踩了 keyed slot 的注册约定。网上讲 DSH 的教程大多只讲怎么写不讲写坏了怎么查。本文专注后者把官方文档里散落的诊断手段FiberState 枚举、--dump-config、HMR 依赖链、keyed slot 回退规则收拢成一条可复用的排查链。读完你会拿到三个反直觉的调试前提、客户端插件的两种形态与四条硬规则、HMR 的完整链路与两大静默陷阱、一张高频报错速查表。想追完整系列下一篇解剖官方真实插件可以先关注我的 CSDN 主页。文章目录DSH 插件调试避坑client.js 设置面板、热重载与高频报错排查表一、为什么 DSH 插件装死是常态三个反直觉的调试前提1.1 PENDING 是特性不是 bug1.2 静默是常态报错是例外1.3 先问它在哪个状态再问它为什么报错二、client.js 客户端插件两种形态与调试盲区2.1 client.js 是什么Client 端沙箱里的第二套代码2.2 形态一UI 插件会话渲染 输入驱动2.3 形态二工具卡片展示tool.call.toolview keyed slot2.4 四条硬规则客户端展示的红线三、HMR 热重载完整链路与静默 PENDING 陷阱3.1 HMR 三件套hmr logger timer3.2 卸载 → 加载的完整链路3.3 id 稳定器与配置变更触发四、装不活的三大诊断工具4.1 FiberState 枚举一眼看穿装死4.2 --dump-config验证层到底有没有生效4.3 日志服务与 consoleHMR 的眼睛五、实战避坑指南高频报错与一键解决速查表结语一、为什么 DSH 插件装死是常态三个反直觉的调试前提1.1 PENDING 是特性不是 bug传统框架的惯性是启动即报错——组件少个依赖进程直接抛异常红字告诉你缺什么。DSH 走的是依赖驱动加载一个插件声明了inject它不会在启动时急着运行而是等所有必需服务就绪才进入 apply。官方 Cordis 教程第六章的原话点破了这个反差“如果插件的 inject 指定了无人提供的服务它就会一直等待不输出任何内容。这不是错误因为 PENDING 是合法状态提供方可能稍后才挂载。”用一个生活化类比它像一个在站台等公交的人车没来就安静站着不哭不闹。你不能因为这个人没上车就断定他出了错——他只是还没等到那班车。同样一个inject: [timer]的插件只要timer服务没被任何插件提供它就永远站在 PENDING 站台安静得让你以为它坏了。1.2 静默是常态报错是例外DSH 的哲学里只有真正的异常才会响亮。配置 Schema 校验失败会加载失败并给出明确错误对应第 02 篇的 FAILED 状态但依赖缺失、HMR 缺服务、客户端卡片格式不对这三类高频问题全部走静默路径。所以调试 DSH 的第一课是不要等报错要学会主动查状态。1.3 先问它在哪个状态再问它为什么报错Fiber 状态机第 02 篇讲过给了每个插件六个状态PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED外加FAILED分支。排查的起点不是看报错日志而是枚举当前注册表里每个 fiber 停在哪个状态——一个停在 PENDING 的插件和报错的插件是两码事前者查依赖、后者查异常。这一套在第四章展开成完整工具。二、client.js 客户端插件两种形态与调试盲区2.1 client.js 是什么Client 端沙箱里的第二套代码第 07 篇的工程结构里client.js是可选的可视化设置面板入口通过package.json的exports[./client]暴露。它的关键特性是跑在 Client 端沙箱——与宿主端的index.js是两套隔离的运行环境。这意味着你在宿主端能用的 ctx 能力客户端插件未必能用反之亦然。调试客户端插件时第一步永远是确认这段代码到底跑在哪一端。2.2 形态一UI 插件会话渲染 输入驱动官方《实操手册》把 UI 插件的职责拆成两半把持久化的事件流渲染出来把用户的输入喂回去。它组合两类数据源——持久的session/eventrecord助手结算、轮次/步骤边界、工具活动和瞬态的agent/assistant-streamframe实时 token 呈现再通过agent.followup()/agent.steer()把输入驱动回会话importtype{Context}fromdeepseek-ai/cordisimport{brandString}fromdeepseek-ai/dsh-brandimport{createUserMessage}fromdeepseek-ai/dsh-llmimporttype{SessionId}fromdeepseek-ai/dsh-sessiondeclarefunctionrender(text:string):voiddeclarefunctiononUserInput(handler:(text:string)void):voidexportconstnamemy-uiexportconstinject[agents]exportfunctionapply(ctx:Context){// 监听瞬态流:把模型的实时文本增量画到界面上ctx.on(agent/assistant-stream,({frame}){if(frame.typechunkframe.chunk.typetext-delta){render(frame.chunk.text)}})// 监听输入:把用户打的话驱动回会话onUserInput(textctx.agents.get(brandStringSessionId(client-session))?.followup(createUserMessage({content:[{type:text,text}],source:{kind:user},})))}这段代码的调试要点有两条inject: [agents]是客户端插件能拿到会话能力的前提少了它ctx.agents就是空输入回驱动靠followup而不是自己构造事件绕过它会导致会话状态不一致。官方还提醒如果浏览器插件要向内建 Web Client 贡献业务行应注册ConversationNodeDefinition与 keyed Chat renderer——这是 UI 插件的进阶版但约定更严。2.3 形态二工具卡片展示tool.call.toolview keyed slot第 08 篇讲过宿主端用presentCall/presentResult定义工具卡片但官方明确点了一句内置 Web Client 不消费这两个方法。客户端要渲染工具卡片走的是另一条路——在 keyed slottool.call.toolview里注册自己的 wire 工具名称从ToolCallBlock的参数、内容、错误、metadata、父调用 id 与 Session 路径事实里派生组件 props。这条路的调试盲区集中在注册约定上slot 是 keyed 的注册名必须精确匹配 wire 工具名派生 props 的来源是ToolCallBlock而不是宿主端的args/result结构。写错了不会报错只会回退到 generic 行。2.4 四条硬规则客户端展示的红线官方给客户端派生展示立了四条硬规则违反任何一条都会静默回退或崩溃规则含义违反后果本地校验 wire 值格式错误或不受支持的输入要回退 generic不校验 → 组件拿到脏数据崩溃不在 metadata 存 React props不把 UI 实现细节序列化进持久数据回放时 props 失效或报错不把 Host 工具实现导入浏览器 bundle客户端不 import 宿主端实现bundle 体积爆炸或运行时报错不建第二套 Client presenter registry只定义 Host 展示方法不另起炉灶两端展示逻辑漂移这四条的共同心法是第 08 篇那句展示层要软——客户端卡片写错只能回退绝不能影响核心会话。调试时如果发现客户端卡片不显示但会话正常先查这四条别急着改渲染代码。三、HMR 热重载完整链路与静默 PENDING 陷阱3.1 HMR 三件套hmr logger timer热重载不是 DSH 开箱即用的默认能力它依赖三个插件协同。官方教程第六章的 cordis.yml 是标准配置-id:loggername:deepseek-ai/cordis-plugin-logger-console-id:timername:deepseek-ai/cordis-plugin-timer-id:hmrname:deepseek-ai/dsh-hmrconfig:root:[.]-id:helloname:./hello.ts这里藏着两个极易踩的静默陷阱官方原话写得很细陷阱一缺 logger看不到 HMR 日志。“HMR 通过 Cordis logger 服务记录日志因此没有控制台导出器时看不到其消息”——HMR 还在工作但它的 reload 日志你看不见于是你以为它没生效。陷阱二缺 timerHMR 直接停摆。“它还会 inject timer 服务来实现去抖如果没有 timer它就会永远停在 PENDING而且不发出任何提示”——这才是真正的装死HMR 插件自己变成了一个 PENDING 的 fiber安静地等一个永远不来的服务。这就是第一章说的静默是常态最典型的现场。3.2 卸载 → 加载的完整链路第 02 篇讲过卸载会释放 effect加载遵循依赖。HMR 就是这套机制的复用——先卸载旧插件回卷它所有 effect再加载新代码再执行新的 apply。因为注册都属于 effect 并会自动清理热替换后不会残留旧实例的任何注册。这条链路的含义是你的 apply 必须对随时被重载友好不要假设它只跑一次。否(缺 timer)是保存源文件dsh-hmr是否 ACTIVE?静默停摆无任何提示卸载旧实例回卷 effect重新加载新代码执行新的 apply3.3 id 稳定器与配置变更触发HMR 不仅盯插件源文件编辑 cordis.yml 本身也会触发更新loader 按id比较 Cordis 配置项只挂载、卸载或重新配置发生变化的部分。这就是为什么配置项要显式带id——官方原话点破“不带该字段的配置项在每次读取时都会获得一个新生成的 id所以只要配置文件发生任何编辑即使自身文本未变它也会被视为先删除再添加并重新挂载。”id就是配置项的稳定身份证。此外还有两个相关的配置语义值得记住disabled: true会卸载插件但不删除其配置项改回原值后插件连同依赖它的 PENDING 插件都会再次加载配置变更触发热替换第 07 篇 3.3 讲过旧实例卸载、新实例加载、无残留。四、装不活的三大诊断工具4.1 FiberState 枚举一眼看穿装死官方教程第六章给出的诊断代码是整个排查链的核心。每个上下文都能枚举插件注册表逐个检查 fiber 状态import{FiberState,typeContext}fromdeepseek-ai/cordisexportconstnamediagnoseexportfunctionapply(ctx:Context){setTimeout((){for(construntimeofctx.registry.values()){for(constfiberofruntime.fibers){if(fiber.stateFiberState.PENDING){console.log(${fiber.name}is PENDING — a required service is missing)}}}},500)}这段代码回答的正是第一章那个问题“它在哪个状态”。FiberState.PENDING命中说明依赖缺失回到第 03 篇查 injectFiberState.FAILED命中说明 apply 抛异常回到第 02 篇查 FAILED 分支。官方还提醒不加 PENDING 过滤条件迭代时你会看到 loader 自身的插件处于 ACTIVE——因为配置文件本身也是通过插件挂载的别把它们误判成问题。4.2 --dump-config验证层到底有没有生效第 05 篇讲过四层层序组合包层 → profile 层 → home 层 → overlay 层。当插件装了不生效第一步不是读代码而是先确认你的层到底有没有被应用dsh--profiledemo --dump-config# 输出里应出现 # dsh-hello-plugin 这一层如果--dump-config里看不到你的 bundle 层问题在装配层第 05 篇的 dsh.bundle.patch 声明、层序、整行替换语义如果能看到层但插件还是 PENDING问题在依赖层第 03 篇的 inject。先定位到层还是依赖再动手省一半时间。4.3 日志服务与 consoleHMR 的眼睛第三章的陷阱一已经埋了伏笔HMR 的日志走 logger 服务不是裸 console。所以调试热重载时先确保cordis-plugin-logger-console已挂载否则 reload 日志对你是隐形的。挂上 logger 后编辑源文件你会看到两行关键日志hmr watching [ . ] hmr reload plugin at hello.ts第一行证明 HMR 在监视、第二行证明触发了重载。看到这两行HMR 链路才真正打通看不到回头查第三章的 timer 陷阱。五、实战避坑指南高频报错与一键解决速查表序号遇到的报错或现象背后的真正原因一句话解决办法1插件装进 profile 不生效,零报错停在 PENDING,inject 的依赖没人提供用 FiberState 枚举查,补上提供方插件2保存源文件热重载没反应HMR 缺 timer 服务,自己停在 PENDINGcordis.yml 加 deepseek-ai/cordis-plugin-timer3热重载在干活但看不到日志缺 logger 服务,HMR 消息走 logger 不走 console挂 cordis-plugin-logger-console4客户端工具卡片不显示但会话正常没在 keyed slot 注册 wire 名,或 props 派生错了在 tool.call.toolview 按 wire 名注册,校验回退5客户端组件拿到脏数据崩溃没本地校验 wire 值格式错/不支持一律回退 generic6配置改了不生效配置值读进了模块级常量,或整行替换语义从 apply 的 config 参数读;覆盖需重述全部键7git 直装的 TS 插件加载失败没有构建产物,无 lib/ 输出作者加 prepare 脚本,用户配 allowBuilds这张表的心法和前几篇一致DSH 的正确用法都写成了契约踩坑的根因几乎永远是凭直觉绕过契约解法永远是一句话回到官方约定。区别只在于——调试篇的契约不在功能上而在状态与生命周期上先查状态、再查层、再查依赖顺序对了装死问题基本三分钟定位。结语这一篇把插件装不活拆成了三条链路客户端插件client.js 双形态 四条展示红线、热重载HMR 三件套 两个静默陷阱、诊断工具FiberState 枚举 --dump-config 日志服务。核心心法一句话DSH 默认安静调试的第一动作不是看报错而是主动查状态——先问它在哪个 Fiber 状态再决定查依赖、查层还是查异常。开发实战篇到此收尾下一篇开始解剖官方真实插件从官方已经交付的插件里学生产级写法。知识要点文字回顾① PENDING 是合法状态装死≠报错先查 fiber 状态② 客户端插件双形态 UI 插件(会话渲染followup 驱动) 工具卡片(keyed slot 注册)四条红线里本地校验回退最关键③ HMR 三件套 hmrloggertimer缺 logger 瞎、缺 timer 死④ 编辑 cordis.yml 也触发热替换id 是稳定身份证⑤ 三大诊断 FiberState 枚举、–dump-config 验层、logger 服务看 HMR 日志。下一篇连载预告《解剖官方插件:从 tool-bash / tool-fs 学生产级插件怎么写》——把官方真实交付的插件逐行拆开关注 CSDN 主页 不错过更新。你在调 DSH 插件时最常卡在哪个静默装死的现场是 HMR 没反应还是客户端卡片不显示评论区聊聊我挨个回。本文事实基于 DeepSeek Harness 官方文档Cordis 教程第六章、实操手册、工具编写参考2026-10 版本API 迭代快有出入评论区提醒我。参考资料正文数据来源DeepSeek Harness 官方文档《插件与生命周期》《组合与 HMR》《插件配置》《打包与安装插件》《实操手册扩展插件形态》《工具编写参考》。