DeepSeek Harness 照 Cookbook 加设置卡:Host 半、浏览器半与字段落盘
设置卡不是「写一个表单」那么简单:Host 半负责字段与落盘,浏览器半负责展示与交互,两者靠 profile 条目 id 和客户端模块系统对齐。 官方 Cookbook 把这条链路拆成五步(来源)。这篇按五步走一遍,再补上「字段没落盘」时最该看的四处。
DeepSeek Harness Volatile 字段:声明与读取时机
设置卡里的字段不是普通变量,而是可即时更新的 Volatile 引用。 官方示例在 Config schema 里用 .volatile() 声明,并导出一个包含 Volatile<T> 的 Config 接口(来源):
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(来源)。
三个容易出错的点:
- id 不能复用 — 保存按 id 定位,复用会让两次写入落到同一个条目;
- secret 不是万能的 —
role('secret')只阻止值进入表单响应,不替代凭据引用; - 普通字段不进设置 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 的包,只把一个包的半侧挂在说明符恰为裸包名的那一行上;从子路径导出挂载的行永远不带半侧(来源)。
这条规则带来三个实践结论:
- 拆成多行的组合包,半侧留在根行 — 根行关闭,注册的页面一起消失;
- 子路径导出不会带半侧 — 想让页面独立存活,应作为独立包发布;
- 构建产物必须是 lazy-CJS factory — 向页面模块加载器登记包名与
factory(require)。
dsh.client 里的 platform 与 inject 也要写对:platform: 'web' 决定它只在 Web 侧加载,inject 决定它依赖哪些客户端模块。写错不会报错,只会表现为「代码在,但页面没有」。
如果浏览器半完全没加载,先查包是不是挂在子路径行,再查 dsh.client 是否存在,最后查构建产物格式。三步都不对,才去看客户端模块系统本身。
DeepSeek Harness 失败分支:字段没落盘怎么查
字段没落盘,按「写入、定位、读取、重建」四个方向查,比盲改表单快。 对应四条分支(来源):
- 写入失败 — 看 Host 是否拒绝、
.check()是否拦住、保存接口是否返回成功; - 定位错误 — 看 profile 条目 id 是否唯一、是否写到了另一个实例;
- 读取错误 — 看消费者是否在操作开始时
.get(),有没有缓存旧值; - 重建覆盖 — 看保存过程是否重建了实例,导致 id 或默认值变化。
最常见的组合是「定位错误 + 读取错误」:保存写到了另一个 id,消费者又从旧实例读值,表现就是「保存成功但没生效」。先确认 id,再确认读取时机,能解决大部分问题。
设置卡的完整契约见旧文 dev-settings-namespace 与 develop-plugin-ui;本篇补的是官方 Cookbook 的走查与验收。把 Host 半、浏览器半、唯一 id 三件事对齐,设置卡就不会再是黑箱。
常见问题
DeepSeek Harness 的 Volatile 字段是可即时更新的配置引用,操作开始时用 .get() 读取当前值。它让保存后的修改在下一次操作生效,而不需要重启插件或进程。
因为 DeepSeek Harness 的设置写入按 profile 条目 id 定位。同一个 id 被多个实例复用,保存时可能改到另一个实例;每个插件实例应有唯一 id。
DeepSeek Harness 里,看四处:profile patch 是否写入、消费者下一次操作是否读到新值、插件实例标识是否不变、重启后是否恢复。四处对齐,才算落盘成功。
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 官方文档 - 即时配置表单
来源
- DeepSeek Harness 官方文档 - 即时配置表单· deepseek-harness
- DeepSeek Harness 官方文档 - 插件设置包· deepseek-ai