ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发的可诊断性:日志、事件与只读状态怎么留证据,线上故障怎么复现

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发日志可观测
插件线上出问题,日志里只有一句 undefined,重启后现场又没了。本文按日志、事件与只读状态三条通道,讲清一条日志只带一个事实、事件何时用作诊断、状态查询怎么设计,以及敏感值怎么脱敏。

插件开发做到能上线,只差一步:让故障自己说话。 很多插件出问题时,日志里只有一句 undefined,重启之后现场消失,剩下只能靠猜。DSH插件 的诊断能力不靠框架赠送,而是你在写代码时决定留下哪些证据。

DSH plugin 出问题时你希望看到什么

先假想一次故障,再倒推该记哪些字段。(来源)

拿三个问题问自己:

  1. 它在做什么? 当前处于初始化、就绪还是已停止,最近一次成功是什么时候。
  2. 它为什么停下? 错误码、失败阶段、是否被取消,而不是只有一句“失败了”。
  3. 它现在是什么状态? 条目数、队列长度、上次读到哪个位置。

这三个问题的答案,决定了你要暴露哪些状态字段、在哪些位置打日志。反过来,如果一个问题都答不上来,说明插件的内部状态对外完全不可见。

诊断设计的目标不是“日志多”,而是“一条日志能定位到一段代码,一个状态能回答一个疑问”。

日志:DSH plugin 一条只带一个事实

把多个事实塞进一行日志,等于把可检索性换成可读性。(来源)

一条好日志通常长这样:固定前缀 + 一个动作 + 一个结果。固定前缀让 grep 能命中,动作说明发生了什么,结果说明成败。

三条实践:

  1. 前缀固定 — 例如统一带插件名,避免与其他插件的输出混在一起。
  2. 一条一个事实 — “读取完成”和“解析失败”分成两条,不要写成“读取完成但解析失败、条目 3 个”。
  3. 错误带阶段 — 初始化失败、注册失败、调用失败是三种问题,日志里要能区分。

热路径上还要克制:每个请求都打印完整对象,会让日志量和 CPU 一起上涨。把细节留给状态查询,日志只留“发生了”和“结果如何”。

事件作为 DSH plugin 的诊断通道

事件适合广播“发生了什么”,不适合承载“必须完成什么”。(来源)

进程内事件没有持久化、没有重放,监听器抛错也不该影响发布方。这三点决定了它的定位:通知与观察。

适合用事件表达的内容:

  1. 阶段变化 — 索引构建开始、完成、失败。
  2. 外部可见的副作用 — 写入了哪个文件、刷新了哪个缓存。
  3. 给其他插件的扩展点 — 允许别人在你的流程里插入行为。

不适合的:必须送达的通知、需要重试的任务、会改变主流程结果的分支。这些应该用方法调用或后台任务,否则一旦没有监听器,行为就悄悄不同了。

只读状态比日志更适合 DSH plugin 排障

状态能随时查,日志只能等下一次复现。(来源)

只读状态的写法很简单:在插件里维护一组字段(就绪标记、条目数、最近一次错误、上次成功时间),通过一个查询入口返回快照。查询时不做重活,也不触发初始化。

它的价值在三个场景特别明显:

  1. “现在到底有没有数据” — 直接看条目数,不用翻日志。
  2. “是不是卡在初始化” — 看就绪标记与最近错误,比猜快得多。
  3. “泄漏有没有发生” — 隔一段时间查一次计数,趋势一眼可见。

状态字段要跟着 Fiber 走:插件卸载后这些字段应当失效,而不是留在一个模块级对象里,让下一次加载读到上一轮的残留。

DSH plugin 不要把敏感值写进日志

“打印出来方便排查”是泄漏凭据最常见的原因。(来源)

凭据在配置里是引用,值由提供方持有;一旦你把 resolve 的结果写进日志,就等于绕过了整条脱敏链路。遥测侧还有 session-telemetry/record 这条 waterfall 负责变换记录,但那只覆盖走遥测通道的数据,不覆盖你自己 console.log 的内容。

可以打印的元信息:来源层(env、file、user-env)、是否已配置、长度、解析耗时。不能打印的:值本身、完整的请求头、文件内容片段。

DSH plugin 诊断自检五条

上线前过一遍,能省掉一半“无法复现”的工单。(来源)

  1. 每个失败分支都有日志,且带错误码与阶段。
  2. 关键流程有阶段事件,外界能知道“开始、完成、失败”。
  3. 暴露了只读状态,能回答“现在是什么情况”。
  4. 日志里没有凭据、文件内容与完整请求头。
  5. 状态字段随插件卸载失效,不会跨实例残留。

验证:让故障可复现

诊断能力的验收标准是:不看代码也能定位。(来源)

  1. 人为制造一次初始化失败,断言日志里能读到失败阶段与错误码,而不只是“失败”。
  2. 让一次调用抛错,断言只读状态里的“最近错误”同步更新。
  3. 连续触发两次热重载,断言状态字段没有残留上一轮的计数。
  4. 把凭据引用指向已配置的值,断言日志只出现来源层与长度,不出现值。
  5. 订阅阶段事件,断言开始与完成各收到一次,且没有重复通知。

如果第 3 步看到计数翻倍,说明状态存在模块作用域;第 4 步出现明文,说明日志绕过了脱敏约定。

遥测侧的脱敏与通道分工,可以对照会话遥测与脱敏;加载阶段的排查手段见插件本地调试。

一句话收束: 一条日志只讲一个事实,事件只负责通知与观察,状态字段随时可查且随实例失效,凭据永不落日志;三样凑齐,故障才不用靠猜。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件开发时日志打多少才算够,打多了会不会影响性能?

DSH plugin 的日志按“一条日志只带一个事实”来打,关键路径各一条即可。运行期不限制你打日志,但同步打日志会占加载与请求的时间,热路径上应避免拼接大对象;需要细节时用只读状态查询补,而不是把每个变量都打印出来。

DSH plugin 里事件能不能直接当业务通道用,还是只适合做诊断?

DSH plugin 的事件建议只做诊断与通知。事件是进程内广播,没有持久化与重放,监听器抛错也不该影响发布方;把它当业务通道会在“没人监听时怎么办”上失守。业务流程用方法调用或服务,事件用来告诉外界发生了什么。

DSH plugin 插件开发要不要暴露只读状态,和写日志相比优势在哪?

DSH plugin 的只读状态在排障时比日志更完整。日志只是时间点快照,只能看到打日志那一刻;只读状态能随时查询当前条目数、就绪标记与最近一次错误,不用等下一次复现。把关键计数做成状态字段,是最省成本的诊断投入。

DSH plugin 的日志里能不能打印配置值和请求头,方便排查?

不能,DSH plugin 的日志不该直接打印配置值与请求头。凭据以引用形式存在配置里,值由提供方持有,明文落日志等于绕过脱敏;遥测侧还有 session-telemetry/record 这条 waterfall 负责脱敏。日志只打印来源层、是否配置、长度这类元信息,不要打印值本身。

相关术语

ctx.emit
ctx.emit 是发布进程内事件的入口,事件没有持久化与重放,适合通知与诊断,不适合承载必须送达的业务流程。— DeepSeek Harness 官方文档 - 插件与生命周期
session-telemetry/record
session-telemetry/record 是每条导出遥测记录必经的 waterfall,监听器可变换记录,不调用 next 即替换下层全部逻辑。— DeepSeek Harness 官方参考 - 会话遥测
只读状态
只读状态是插件对外暴露的当前快照,查询时现算或读缓存,不触发副作用,适合排障时替代追加日志。— DeepSeek Harness 官方文档 - 插件与生命周期
Fiber
Fiber 是每个插件实例的生命周期作用域,插件卸载后其登记被清理,诊断字段也应随实例一起失效。— DeepSeek Harness 官方文档 - 插件与生命周期

来源