DSH plugin 接入 SettingsNamespace：三层解析、owner scope 与热提交

DSH plugin 的设置不是另写一套表单，而是把插件自己的 Config 字段投影成 UI，键就是当前 profile 里那个条目的 id。 理解这一点能避开两个常见误解：第一，命名空间不是包名——同一个包挂载两次、条目 id 不同，就会有两个独立表单；第二，写入不是直接改文件——设置服务校验完整 Config、比对修订号，再通过配置编辑器以 Cordis patch 持久化。业务代码读取配置仍然走自己 Config 引用的 .get()，表单只是同一份数据的另一个视图。

DSH plugin 的设置表单从哪来：Config 投影与命名空间

一句话结论：设置服务把活动 profile 条目的 volatile Config 字段投影成表单，消费者读的仍是自己的 Config 引用。

1. 投影来源：设置服务从当前活动 profile 的条目里取 Config 字段，生成表单描述符。
2. 命名空间规则：命名空间是条目在本 profile 内的本地 id；多个实例只要条目 id 不同，表单就互相独立。
3. 普通字段被排除：不是所有字段都会进表单，只有可编辑的 volatile 字段才出现。
4. 业务侧读值：插件在自己的 Config 引用上调用 .get()，不要绕到设置服务去读最终值。
5. 持久化路径：配置编辑器通过 Cordis patch 写回，因此改动会落在 profile 的补丁层，而不是某个私有配置文件。

DSH plugin 的三层值与修订号：这个值到底从哪来

一句话结论：描述符同时给继承值、显式覆盖值与实际值，再加一个修订号——配置来源与并发冲突都能一眼看清。

1. 排查配置不符：先看实际值是否等于显式覆盖值，再确认继承值来自哪一层。
2. 写入必须带修订号：expectedRevision 不传表示无条件写，传了就必须是刚读到的那个。
3. 过期即拒绝：每次写入都会验证完整 Config，并在持久化前拒绝过期修订号，不会「尽力写入」。
4. 冲突处理：重新 describe 拿新修订号，合并后再提交，而不是原地重试旧修订号。

DSH plugin 的三种写入：update、replace 与 mutate 怎么选

一句话结论：改字段用 update、整段重填用 replace、按路径改数组或避开秘密值用 mutate。

1. update(ns, patch, expectedRevision?)：把提交的字段合并进条目的配置，未提交的字段保持不变。
2. replace(ns, section, expectedRevision?)：先把即时字段重置为继承配置，再应用提交的整段表单值——适合「恢复默认后整体重填」。
3. mutate(ns, ops, expectedRevision?)：按路径独立编辑；客户端响应里没有的秘密值会被保留，不会因为回传而丢失；把某个数组下标 unset 会删除该元素。
4. 统一校验：三者都会验证完整 Config，非法组合在写入前被拒。
5. 选型判据：不确定客户端是否拿到全部字段时，优先 mutate，避免把脱敏后的空值写回去。

DSH plugin 实例级页面策略：configure 与 owner scope

一句话结论：configure 只改这个实例的页面呈现策略，不碰 Config；归属默认是调用方 fiber。

const dispose = ctx.settings.configure({ auto: true }, owner)
// auto 默认 true；返回 disposer，记得挂到插件的 effect 上

1. 只影响呈现：策略控制自动页面等 UI 行为，不改变配置值。
2. 一个实例只能注册一次：重复注册会抛错，说明你在两个地方各配了一遍。
3. 显式指定 owner：默认归属调用方 fiber；要在别的插件实例上注册策略时传 owner。
4. 用 disposer 清理：把返回的 disposer 注册进 effect，插件卸载时策略一起撤销。
5. 需要原生编辑时：prepareDocument() 返回已存在的 profile patch 路径，供外部编辑器打开。

DSH plugin 的远程读写与脱敏：settingsController

一句话结论：远程命名空间背后是 settingsController，读一律脱敏，写失败被分成冲突与拒绝两类。

1. 读强制脱敏：每个远程读都带 redactSecrets: true，role('secret') 的字段不可能出现在响应里。
2. 写复用同一套语义：远程写暴露 merge、replace 与路径寻址三种操作，与本地 API 对应。
3. 错误分类：提供方拒绝会被归为 settings/conflict（修订号冲突）或 settings/rejected（内容被拒），并带上服务原话。
4. 两个事件别混用：settings/document-updated 表示某个条目的表单值、可用性或页面策略变了，UI 收到后应重新读取 schema、解析值与修订号；只有需要刷新注册信息时才用 loader/volatile-update。
5. 验证：改一个字段后观察 settings/document-updated 是否带新修订号，能确认整条链路通。

DSH plugin 排查注意事项

一句话结论：设置类问题先分「值不对」「写不进」「看不见字段」三类，分别对应解析、修订号与 schema。

1. 值不对 → 对比继承值、显式覆盖值、实际值三层，判断是默认还是覆盖问题。
2. 写不进 → 查修订号是否过期、Config 校验是否失败。
3. 看不见字段 → 检查该字段是否属于可编辑的 volatile 字段。
4. 秘密值被清空 → 用了 update 或 replace 回传脱敏空值；改用 mutate 按路径编辑。
5. 同包两个实例互相影响 → 确认命名空间用的是条目 id，而不是包名。
6. 修复状态如实：本文命名空间定义、三层值、三种写入语义与远程脱敏规则均取自官方「插件配置表单」页面；ctx.settings 与 ctx.settingsController 的完整签名以该页 Cordis API 区块与你所用版本为准。

来源：插件配置表单、settings 服务 README、LLM 流式与适配器约定。