【实践笔记】DSH 0.1.7 删掉了 settings 的双向绑定：插件要改三处，还有一个“改完不生效”的坑

[wangzhanchao883]

0.1.7 这次把 settings 改得挺彻底：插件以前那套"注册命名空间 + 双向绑定"整个没了，也没留别名。
我把自己的一个插件迁过去，迁移很快就完了，但是迁移过去以后在"设置面板能显示、但改完不生效"
这个BUG上栽了。写出来省得别人再绕。

一句话说清：0.1.7 的 settings 变成了单向投影——宿主只把 Loader 里插件条目的 Config
投影成表单，写入落到 profile 的 cordis.patch.yml 上，但它不会再通知插件。旧的 scope.watch()
是实时回调，删掉之后，插件如果只在加载那一刻读一次配置，你在面板里改什么它都不知道。

改法就三处：host 侧把 settingsSchema 改成 export const Config 并给每个可写字段盖 .volatile()；
读取从 scope.get()/scope.watch() 改成 settings.describe()；客户端把
ctx.settingsScope.bind({namespace}) 换成 ctx.configForms.get(条目 id)。组件体一行都不用动。

真要提醒的是第三条之后那件事：watch 没了，你得自己保证"读的是新鲜值"。我一开始没意识到这点，
面板里加了扫描目录、点插件自己的按钮，它回我"还没设置要扫描的文件夹"——配置明明写进文件了。

--- 后面是AI助手提供的具体技术细节，不关心的可以跳过 ---

具体是什么变了

以前（0.1.5/0.1.6）插件这么写：

ctx.inject(["settings"], (c) => {
  const scope = c.settings.register(NS, settingsSchema, { base: liveConfig });
  liveConfig = { ...liveConfig, ...scope.get() };
  scope.watch((next) => { liveConfig = { ...liveConfig, ...next }; });   // 实时回调
});

0.1.7 这套全没了。settings 服务现在只做一件事：把 Loader 里本插件条目的 Config
投影成一份可编辑的表单文档。命名空间就是 profile 里那个条目的 id。

export const Config = z.object({
  enabled: vol(z.boolean().default(true)),
  dbPath:  vol(z.string().default("")),
  // ...
});

两个硬要求，都不报错，所以特别容易踩：

1. 必须是有名导出，不能有 export default——剥壳的时候会把 Config 一起带走，条目被静默过滤。
2. 每个可写字段都要盖 .volatile()。一个都没盖的话，volatileForm() 返回 undefined，
   整个条目被 describe() 静默过滤：面板直接消失，日志里一个字都没有。

.volatile() 需要 schemastery >= 3.18.4，低版本上会在模块求值阶段抛错。写个降级包装就行：

const vol = (s) => (typeof s.volatile === "function" ? s.volatile() : s);

客户端侧：

const scope = ctx.configForms.get(SETTINGS_NAMESPACE);   // 旧：ctx.settingsScope.bind({...})
// inject 里的服务名也要跟着换：settingsScope -> configForms

快照结构没变（getSnapshot / subscribe / set / unset / mutate 都在），所以渲染组件的代码不用改。

---

然后是那个把我骗了两天的坑

watch 没了之后，"改设置"这件事的语义变了：写进去 ≠ 插件知道。

迁移完我以为行为跟以前一样，结果是这样：

面板里加了扫描目录 D:\工作  ->  点插件页面的「立即扫描一次」
->  "还没设置要扫描的文件夹"

去看 profile 的 cordis.patch.yml，值明明在里面（写入链路是好的）。查了一圈才发现：
插件只在 apply 那一刻读了一次配置，之后一直用内存里那份旧快照，而宿主这次写入并没有
重新 apply 插件。所以表现成"面板显示正常、值也落盘了、插件就是不认"。

这跟"改完要重启一次才生效"很容易混。在 0.1.5 上 scope.watch() 是实时的，所以这是 0.1.7
引入的行为变化，不是老毛病。

改法很土，但很有效：把"取配置"改成每次用之前都重读一遍。

let settingsService = null;

function syncFromSettings() {
  if (!settingsService) return false;
  const row = settingsService.describe().find((it) => it && it.ns === SETTINGS_NS);
  if (!row || row.value == null) return false;
  liveConfig = { ...liveConfig, ...row.value };
  return true;
}

function freshConfig() { syncFromSettings(); return liveConfig; }   // 每个入口第一行调

需要覆盖的入口别漏：每个工具的 execute、每个斜杠命令的 handler、还有挂在生命周期钩子上的
自动任务（比如我那个"打开 DSH 时检查要不要补扫"）。describe() 是内存操作，多调几次不心疼。

顺手记一个定位法，遇到"面板写了但插件不认"按顺序做三步就够了：

1. 读 $DSH_HOME/profiles/web/cordis.patch.yml，看 id 那段里值写进去没有
2. 比时间：这个文件的 mtime vs 实例启动时间。写入晚于启动 -> 必然还在用旧值，别往下查了
3. 数 describe() 的调用点。只有 1 个（在 apply/inject 里）-> 就是这个坑

---

最后两句

客户端那一半（settingsScope 被移除导致插件 boot 卡住、报错却指向 client-half failed）已经有人
报过了：#7445。我这篇补的是 host 侧和运行期那一半——它们症状更隐蔽，因为面板看起来完全正常。

我的插件是直接要求 0.1.7+ 的，没做向下兼容。如果谁手里的插件还要同时跑 0.1.6，欢迎说说你那段
兼容探测是怎么写的（我猜得靠"settings 服务上有没有 describe"来判断，但没实测过，不敢乱给）。

如果你也踩了同一处，或者你那边是完全另一副症状，回帖说一声。

---

以下是AI助手提供的技术细节，不关心的可以跳过

附：实测环境与验证方式

• 环境：DSH 0.1.7-rc.2（npm），Windows 11，web profile，Node 22
• 对象插件：dsh-lost-and-found（文件索引类，自研），0.1.2 完成迁移，0.1.3 修掉运行期读取
• 验证方式：另起一个隔离实例（独立 DSH_HOME + 端口 + node_modules junction，不动正在用的那个），
  全新 profile、没有任何配置，然后在设置面板里加目录并把库位置填成一个文件夹，
  不重启直接点插件页面上的扫描按钮 -> 报"扫描完成 · 看了 3 个文件 · 新增 3 个"。
  0.1.2 在同一步会报"还没设置要扫描的文件夹"。

附：新旧 API 对照

项目             0.1.5 / 0.1.6                                     0.1.7
---------------- ------------------------------------------------- --------------------------------
声明配置         settings.register(ns, schema, { base })           export const Config = z.object({...})
                                                                   （每个可写字段 .volatile()）
命名空间来源     插件自己起的 ns                                     profile 条目 id（不是包名）
读取             scope.get()                                       settings.describe() 里按 ns 找
变更通知         scope.watch(fn) 实时回调                          没有了 —— 自己按需重读
写入             插件 scope.set(...)                               宿主设置服务写进 profile 补丁文件
客户端绑定        ctx.settingsScope.bind({ namespace })             ctx.configForms.get(条目 id)
客户端 inject     settingsScope                                    configForms

附：两个容易连坐的相邻坑

1. 命名空间 = profile 条目 id，不是包名。如果插件是被插件市场"热挂载"起来的，条目 id 会变成
   mkt-<包名>，插件里写死的包名就对不上，表现是"路由都 200、面板却报配置面板不可用"。
   重启后由 bundle 层加载，id 才恢复成 cordis.patch.yml 里写的那个。前置条件是包已经在
   dsh.profile.bundles 里。
2. 一个纯工程坑，跟 settings 无关但同一轮踩到：路径型配置（比如数据库存放位置）要同时容错
   文件和目录。用户很可能把文件夹填进"文件路径"那一格，而 SQLite 拿目录当库文件会直接
   unable to open database file，整条链路挂掉。判定"像目录"（已存在的目录 / 以分隔符结尾 /
   没有扩展名）就拼成 <目录>/index.db。

附：几篇相关的既有帖子

• 0.1.7-alpha.1: legacy client service settingsScope silently removed — third-party plugins hang on boot and the failure surfaces as a misleading client-half failed #7445 —— 客户端 settingsScope 被静默移除，第三方插件 boot 卡住（同一个迁移，客户端那一半）
• From 0.1.5 to 0.1.7: an upgrade recovery checklist — back up, pin, roll back #7654 —— 0.1.5 到 0.1.7 的升级恢复清单，里面也点了 0.1.7-alpha.1: legacy client service settingsScope silently removed — third-party plugins hang on boot and the failure surfaces as a misleading client-half failed #7445
• [Bug] Settings watchers can outlive their registration owner #1447 / [Bug] An old settings write can leave a replacement registration stale #1454 / [Bug] In-flight settings write can leave a replacement registration indefinitely stale #164 —— 更早的 watcher 老 bug（watcher 活过注册者、写入留下 stale 注册）
• Plugin settings namespaces cannot be exposed to the settings UI | 插件注册的 settings namespace 无法暴露给设置界面 #2239 / feat(settings): let plugin-registered namespaces opt into the configuration-client exposure boundary #1606 —— 设置命名空间暴露给设置界面的历史讨论

附：非官方实践笔记，与 DeepSeek 官方无关。

---

[Practice note] DSH 0.1.7 turned settings into a one-way projection: three things plugins must change, plus a "the panel renders but edits do nothing" bug

0.1.7 rebuilt settings thoroughly: the plugin-side "register a namespace + two-way binding" model is
gone, with no alias left behind. Porting my plugin was quick — what took the time was a bug that
showed up afterwards: the settings panel renders fine, but edits never take effect. Writing it down
so nobody has to rediscover it.

The short version: in 0.1.7 settings are a one-way projection. The host projects the Config of your
Loader entry into an editable form and writes your edits into the profile's cordis.patch.yml — but
it never notifies the plugin. The old scope.watch() was a live callback; with it gone, a plugin that
reads its config once at apply time simply never sees what you changed in the panel.

Three changes fix the API half: host side, turn settingsSchema into export const Config with every
writable field marked .volatile(); read through settings.describe() instead of scope.get()/watch();
and on the client, replace ctx.settingsScope.bind({namespace}) with ctx.configForms.get(entryId).
The component body itself needs no changes.

The part worth flagging is what comes after: with watch gone, keeping a fresh config is now your job.
I found out the hard way — I added a scan folder in the panel, clicked the plugin's own button, and
it answered "no folders configured yet", while the value was already sitting in the config file.

--- Technical details below are provided by an AI assistant; skip if you are not interested ---

What actually changed

Before 0.1.7:

ctx.inject(["settings"], (c) => {
  const scope = c.settings.register(NS, settingsSchema, { base: liveConfig });
  liveConfig = { ...liveConfig, ...scope.get() };
  scope.watch((next) => { liveConfig = { ...liveConfig, ...next }; });   // live callback
});

In 0.1.7 none of that exists. The settings service only projects the Config of your Loader entry
into a document, and the namespace is that entry's id.

export const Config = z.object({
  enabled: vol(z.boolean().default(true)),
  dbPath:  vol(z.string().default("")),
  // ...
});

Two hard requirements, both silent when you get them wrong:

1. It must be a named export — no export default, or the Config is dropped when the module is
   unwrapped and the entry is filtered out silently.
2. Every writable field must be marked .volatile(). Mark none and volatileForm() returns undefined,
   the whole entry is filtered out of describe(): the panel just disappears, with nothing logged.

.volatile() needs schemastery >= 3.18.4 and throws at module evaluation time on older versions, so
guard it: const vol = (s) => (typeof s.volatile === "function" ? s.volatile() : s);

Client side: the snapshot shape is unchanged (getSnapshot / subscribe / set / unset / mutate), so
only the binding and the inject entry change.

---

The trap that cost me two days

Added scan folder D:\work in the panel  ->  clicked the plugin's own "Scan now"
->  "no folders configured yet"

The value was in cordis.patch.yml the whole time. The plugin had read its config once, at apply
time, and the host's write did not re-apply the plugin — so it kept answering from a stale snapshot.
It looks exactly like "settings need a restart, it's a legacy quirk": on 0.1.5 scope.watch() made
edits live, so this is a 0.1.7 behaviour change, not an old wart.

The fix is unglamorous but reliable: re-read before every use.

let settingsService = null;

function syncFromSettings() {
  if (!settingsService) return false;
  const row = settingsService.describe().find((it) => it && it.ns === SETTINGS_NS);
  if (!row || row.value == null) return false;
  liveConfig = { ...liveConfig, ...row.value };
  return true;
}

function freshConfig() { syncFromSettings(); return liveConfig; }   // first line of every entry

Cover every entry point: each tool's execute, each slash command's handler, and anything you hung
on a lifecycle hook. describe() is an in-memory call; calling it often is cheap.

A three-step triage for "the panel writes, the plugin disagrees":

1. read $DSH_HOME/profiles/web/cordis.patch.yml — is the value there under your entry id?
2. compare timestamps: file mtime vs instance start. Written after start -> it is stale, stop here
3. count describe() call sites. Exactly one (inside apply/inject) -> this is the trap

---

Two closing notes

The client half — settingsScope removed, plugins hanging on boot, reported as a misleading
"client-half failed" — is already covered by #7445. This post adds the host half and the runtime
half, which are sneakier because the settings panel looks perfectly healthy.

My plugin now requires 0.1.7+, so I did not build a compatibility shim. If your plugin still has to
run on 0.1.6 as well, I would like to hear how you probe for it — my guess is checking whether the
settings service exposes describe(), but I have not tested that, so I will not pretend otherwise.

Non-official practice note, not affiliated with DeepSeek. If you hit the same thing — or a
completely different symptom — say so below.

---

Technical details (appendix)

Environment: DSH 0.1.7-rc.2 (npm), Windows 11, web profile, Node 22. Plugin: dsh-lost-and-found
(a local file index), ported in 0.1.2, runtime read fixed in 0.1.3.

How it was verified: a separate isolated instance (own DSH_HOME, own port, node_modules junction —
the live instance was never touched), a fresh profile with no configuration at all. Added a folder
and set the database location to a folder through the settings panel, then clicked the plugin's own
scan button without restarting: "scan finished, looked at 3 files, added 3". On 0.1.2 the same step
answers "no folders configured yet".

API map:

Item             0.1.5 / 0.1.6                                0.1.7
--------------- -------------------------------------------- ---------------------------------
Config           settings.register(ns, schema, { base })     export const Config = z.object({})
                                                              (every writable field .volatile())
Namespace        whatever the plugin chose                   profile entry id (not the package name)
Read             scope.get()                                 find your ns in settings.describe()
Change notice    scope.watch(fn), live                       gone - re-read on demand
Write            plugin-side scope.set(...)                  host writes into the profile patch file
Client binding   ctx.settingsScope.bind({ namespace })       ctx.configForms.get(entryId)
Client inject    settingsScope                               configForms

Two adjacent traps:

1. The namespace is the profile entry id, not the package name. If the plugin was hot-mounted by the
   plugin market, the entry id becomes mkt-; a hard-coded package name no longer matches and
   you get "configuration panel unavailable" while every route still answers 200. After a restart the
   bundle layer loads it with the id from cordis.patch.yml. Prerequisite: the package is listed in
   dsh.profile.bundles.
2. Unrelated to settings but hit in the same round: a path-typed config field (say, where to store a
   database) should accept both a file and a folder. Users will type a folder, and SQLite answers
   "unable to open database file" when handed a directory, taking the whole pipeline down. Treat
   "looks like a directory" (existing directory / trailing separator / no extension) as a folder and
   append index.db.

Related threads: #7445 (client-side settingsScope removal), #7654 (0.1.5 -> 0.1.7 recovery checklist),
#1447 / #1454 / #164 (older watcher bugs), #2239 / #1606 (settings namespace exposure discussion).

[PerryLink]

"改完不生效"这条最值得单独提——它比"要改三处"更容易修

1. 请把两类问题分开

你的实践笔记里其实混了两件事，而它们的处置完全不同：

1. 迁移成本（插件要改三处）——这是有意的破坏性变更，合理的诉求是升级指引 + 兼容提示；
2. "改完不生效"——这是缺陷：用户按新写法改对了却看不到效果，没有反馈。这类最该修，因为它会让人怀疑自己。

建议把第 2 条单独拆出来，并给出最小复现：改了哪一处、期望看到什么、实际看到什么、以及重启后是否生效。

2. 我能提供的一条已核实事实（与 settings 的写入有关）

settings 的写入走原子替换 + 跨进程写锁（dsh-atomic-write）。而在最新版里有一条相关修复值得你知道：

fix(atomic-write): take over a writer lock whose holder exited
fix(atomic-write): keep the PID-only lock record

⇒ 也就是说：如果"改完不生效"表现为"写没落盘"，那在 0.1.7-rc.2 上可能已经被修（旧行为是：持有锁的进程已退出时，锁仍在、后来者只能超时）。请先在最新版上复现一次——这一条很可能直接决定你的现象还在不在。

3. 请补三样

1. 你改的那三处的路径与内容（是 profile 的 YAML？插件的 package.json？还是别处）；
2. dsh --version；
3. 是否重启后才生效——这一条能区分"没落盘"与"落盘了但没被重新读取"。

4. 你的"实践笔记"这个形式很好

它比单点 bug 报告更有价值（能帮同迁移的人少踩坑）。建议结构固定成：变更点 → 旧写法 → 新写法 → 不生效的表现 → 规避。这样它既能被维护者用来补迁移文档，也能被插件作者直接照抄。

5. 版本提醒

⚠️ 当前最新是 0.1.7-rc.2（tag dsh-v0.1.7-rc.2）。别装 latest（npm 上它仍停在 0.1.5-rc.3，更旧）：

npm i -g @deepseek-ai/dsh@next      # 当前 = 0.1.7-rc.2

一条边界

我确认的是 settings 写入是原子替换 + 跨进程锁、且 rc.2 修过"锁持有者已退出"这一类——这是我对"改完不生效"最可能的成因给出的方向。你那三处具体是什么、以及不生效的确切表现以你补充的为准。

[wangzhanchao883]

顺着 PerryLink 那条补实测，他问的三样都跑过了。

先说结论：不是"写没落盘"。三处我都核过——cordis.patch.yml 里的值确实写进去了、mtime 也对；问题是写完之后没人重新 apply 插件。我用探针插件量过：apply 打点 + 通过设置服务写一次自己的命名空间，等到 45 秒仍然没有第二次 apply。所以 atomic-write 那个写锁不是这里的成因，重启才生效只是因为重启会重新 compose。

三处指的是：profile 的 package.json（dsh.profile.bundles）、profile 的 cordis.patch.yml（条目 config / disabled 行）、还有插件市场自己的 .dsh-market/state.json 禁用列表。版本 0.1.7-rc.2。

再补一条这两天才踩到的，跟"谁权威"直接相关：宿主传给 apply(ctx, input) 的 input 是解析后的完整配置，每个 .volatile() 字段都是盒（{get}）；而 describe() 三层里 value / base 都带 schema 默认值，只有 row.user 是用户显式配过的。拿 value 当覆盖层去 merge，会把自己 config.json 里的库路径冲成默认空串——插件看着在跑，功能静默失效，能查很久。反过来，设置面板里显式写过的值也确实压过 config.json，这个方向别踩。