ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 照 Cookbook 加设置卡:Host 半、浏览器半与字段落盘

插件开发发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin设置卡VolatileCookbook
官方 Cookbook 的设置卡分 Host 半与浏览器半:Volatile 字段负责即时值,唯一 profile id 负责实例,client 半只挂在裸包名那一行。本文按五步走完,并给字段没落盘时的四处验收。

设置卡不是「写一个表单」那么简单:Host 半负责字段与落盘,浏览器半负责展示与交互,两者靠 profile 条目 id 和客户端模块系统对齐。 官方 Cookbook 把这条链路拆成五步(来源)。这篇按五步走一遍,再补上「字段没落盘」时最该看的四处。

DeepSeek Harness Volatile 字段:声明与读取时机

设置卡里的字段不是普通变量,而是可即时更新的 Volatile 引用。 官方示例在 Config schema 里用 .volatile() 声明,并导出一个包含 Volatile<T> 的 Config 接口(来源):

ts
export interface Config {
  endpoint: Volatile<string | undefined>
  retries: Volatile<number>
}

export const Config = z.object({
  endpoint: z.string().volatile(),
  retries: z.number().step(1).min(0).default(3).volatile(),
})

读取时机很关键:在操作开始时调用 .get(),一次请求需要一致快照时,一次性捕获所需值。不要在模块顶层读一次就缓存,否则保存后的新值不会生效。

跨字段校验用 .check(),由 Host 在持久化前执行,不进入序列化的表单 schema。也就是说,.check() 负责「这组值能不能一起保存」,而不是「单个字段长什么样」。

如果字段涉及凭据,不要用普通字段传明文。官方建议使用凭据引用;role('secret') 可以阻止值进入表单响应,但凭据域管理的值仍应走引用。

DeepSeek Harness 组合插件:唯一 id 与 secret

设置卡能工作,前提是插件实例能被唯一识别。 官方要求为每个实例分配唯一的 profile 条目 id;基础组合包挂载 settings 与 config-editor,自定义 profile 在挂载这些服务前要先读对应包的 README(来源)。

三个容易出错的点:

  1. id 不能复用 — 保存按 id 定位,复用会让两次写入落到同一个条目;
  2. secret 不是万能的 — role('secret') 只阻止值进入表单响应,不替代凭据引用;
  3. 普通字段不进设置 schema — 不要把运行时状态塞进设置字段,否则每次保存都会覆盖它。

组合插件的顺序也会影响设置卡:settings 与 config-editor 必须先可用,表单才有宿主。顺序错了,表现通常是「页面能开,但保存按钮没有反应」。

一个实用检查:列出当前 profile 的条目 id,确认你的插件实例 id 唯一且稳定。id 变了,已有设置就可能找不到归属。

DeepSeek Harness 验证编辑:四处对齐

保存成功不等于落盘成功,至少要看四处。 官方给出的验证口径是:profile patch、消费者下一次操作、插件实例标识不变、重启后的恢复(来源)。

检查点看什么常见失败
profile patch对应条目是否写入新值写到了另一个 id
消费者操作下一次操作是否读到新值.get() 读得太早或缓存了旧值
实例标识id 是否保持不变保存过程重建了实例
重启恢复重启后值是否还在只改了内存,没有持久化

除了正向验证,还要做一次反向验证:提交一个无效值,确认配置文件和 Volatile 当前值都没有改变。如果无效值也能写进去,说明 .check() 或 Host 校验链路有缺口。

这四正一反,是设置卡最值得保留的验收习惯。只测「保存后页面显示新值」,很可能只是前端状态变了,后端并没有落盘。

DeepSeek Harness 向别人的页面贡献内容

设置卡不一定要独占一个页面,也可以向其他插件的页面贡献内容。 官方提供三个插槽:plugins.detail.actions(页头控件)、plugins.detail.badge(标题旁标签)、plugins.detail.section(页面内容之下的区块)(来源)。

每个条目都以页面的 subject 渲染:{ kind: 'bundle', pkg }、{ kind: 'row', pkg, row } 或 { kind: 'item', id }。对无话可说的 subject 返回 null,不要渲染空区块。

这种贡献方式适合「我的插件想给别人的设置页加一条提示或一个操作」。它比新建一个独立页面轻,但要求你正确处理 subject;处理错了,内容会出现在不该出现的页面上。

一个判断标准:如果你的内容只对自己的插件有意义,放自己的页面;如果它是对某个 bundle 或 item 的补充说明,才用 detail 插槽。

DeepSeek Harness 浏览器半挂在哪:裸包名规则

浏览器半不加载,十有八九是挂错了行。 官方说明:客户端模块系统扫描已启用的 Loader 条目,找出声明了 dsh.client 的包,只把一个包的半侧挂在说明符恰为裸包名的那一行上;从子路径导出挂载的行永远不带半侧(来源)。

这条规则带来三个实践结论:

  1. 拆成多行的组合包,半侧留在根行 — 根行关闭,注册的页面一起消失;
  2. 子路径导出不会带半侧 — 想让页面独立存活,应作为独立包发布;
  3. 构建产物必须是 lazy-CJS factory — 向页面模块加载器登记包名与 factory(require)。

dsh.client 里的 platform 与 inject 也要写对:platform: 'web' 决定它只在 Web 侧加载,inject 决定它依赖哪些客户端模块。写错不会报错,只会表现为「代码在,但页面没有」。

如果浏览器半完全没加载,先查包是不是挂在子路径行,再查 dsh.client 是否存在,最后查构建产物格式。三步都不对,才去看客户端模块系统本身。

DeepSeek Harness 失败分支:字段没落盘怎么查

字段没落盘,按「写入、定位、读取、重建」四个方向查,比盲改表单快。 对应四条分支(来源):

  1. 写入失败 — 看 Host 是否拒绝、.check() 是否拦住、保存接口是否返回成功;
  2. 定位错误 — 看 profile 条目 id 是否唯一、是否写到了另一个实例;
  3. 读取错误 — 看消费者是否在操作开始时 .get(),有没有缓存旧值;
  4. 重建覆盖 — 看保存过程是否重建了实例,导致 id 或默认值变化。

最常见的组合是「定位错误 + 读取错误」:保存写到了另一个 id,消费者又从旧实例读值,表现就是「保存成功但没生效」。先确认 id,再确认读取时机,能解决大部分问题。

设置卡的完整契约见旧文 dev-settings-namespace 与 develop-plugin-ui;本篇补的是官方 Cookbook 的走查与验收。把 Host 半、浏览器半、唯一 id 三件事对齐,设置卡就不会再是黑箱。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 设置卡里的 Volatile 字段是什么,和普通配置有什么区别?

DeepSeek Harness 的 Volatile 字段是可即时更新的配置引用,操作开始时用 .get() 读取当前值。它让保存后的修改在下一次操作生效,而不需要重启插件或进程。

DeepSeek Harness 插件设置卡为什么必须用唯一的 profile 条目 id?

因为 DeepSeek Harness 的设置写入按 profile 条目 id 定位。同一个 id 被多个实例复用,保存时可能改到另一个实例;每个插件实例应有唯一 id。

DeepSeek Harness 设置卡保存后,怎么确认字段真的落盘了?

DeepSeek Harness 里,看四处:profile patch 是否写入、消费者下一次操作是否读到新值、插件实例标识是否不变、重启后是否恢复。四处对齐,才算落盘成功。

DeepSeek Harness 插件的浏览器半为什么有时完全不加载?

DeepSeek Harness 里,常见原因是包被拆成多行,而客户端模块系统只把半侧挂在说明符恰为裸包名的那一行。子路径导出的行不会带半侧,页面应作为独立包发布或挂到根行。

相关术语

Volatile
Volatile 是 DeepSeek Harness 设置里可即时更新的配置引用,操作开始时通过 .get() 读取,保存后在下一次操作生效。— DeepSeek Harness 官方文档 - 即时配置表单
profile 条目 id
profile 条目 id 是 DeepSeek Harness 在 profile 中标识一个插件实例的唯一标识,设置写入与热更新都按它定位。— DeepSeek Harness 官方文档 - 即时配置表单
浏览器半
浏览器半是 DeepSeek Harness 插件在 Web 客户端运行的部分,通过 dsh.client 声明并由客户端模块系统作为 lazy-CJS factory 送到页面。— DeepSeek Harness 官方文档 - 即时配置表单
plugins.detail.section
plugins.detail.section 是 DeepSeek Harness 设置页的插槽,允许插件向其他插件的详情页贡献一段内容,并按页面 subject 决定是否渲染。— DeepSeek Harness 官方文档 - 即时配置表单

来源