配置分层覆盖 XMoon/dsh-profile-settings

@xmoon76/dsh-profile-settings

一个 DSH profile bundle 插件：在官方用户设置 seam 之上增加按 profile 隔离的 Settings 覆盖层。$DSH_HOME/settings.yaml 继续作为全局基线；每个 profile 可以通过自己的 $DSH_HOME/profiles//settings.patch.yml 覆盖任意 Settings namespace —— object 递归合并，array/scalar 整体替换，!unset 显式删除继承值。

Schema Defaults
↓
Composition Base
↓
~/.dsh/settings.yaml （全局用户层） ↓ ~/.dsh/profiles//settings.patch.yml （profile 用户层） ↓ Effective Settings

已有插件仍然只使用 ctx.settings，完全感知不到覆盖层的存在。写操作（update / replace / mutate）只落在 profile 覆盖层；replace({}) 回退到 global 层而不是 composition 默认。官方 schema 校验、revision 语义、 expectedRevision 冲突检测、watcher 与事件全部保持不变。

安装

要求 profile 的 bundles 包含 @deepseek-ai/dsh-base（官方 web / headless 模板都满足）。为每个需要独立覆盖层的 profile 安装：

dsh plugin --profile web add @xmoon76/dsh-profile-settings
dsh plugin --profile pi-tui add @xmoon76/dsh-profile-settings

dsh plugin --profile add 会自动把声明了 dsh.bundle 的包 reconcile
进该 profile 的 dsh.profile.bundles。下次启动时 bundle patch （cordis.patch.yml）会：

1. 禁用 base 的 settings 行（@deepseek-ai/dsh-settings-file）；
2. 插入 profile-settings 行成为 ctx.settings 的唯一 owner。

一个 composition 只能有一个 ctx.settings owner：如果 base 行仍然活跃，启动会 fail loud（Cordis 重复服务注册错误），绝不静默覆盖。

配置

插入的行不需要配置（下方为默认值）；profile 自己的 cordis.patch.yml 可以按行 id 覆盖 config：

| key | 默认值 | 含义 |
| profile | 自动检测 | 显式指定 profile 名 |
| globalPath | $DSH_HOME/settings.yaml | 全局 settings 文档 |
| profileFile | settings.patch.yml | profile 目录内的覆盖文件名 |
| dshHome | $DSH_HOME 或 ~/.dsh | harness home |
| watch | true | 热加载两个文档 |
| debounceMs | 100 | watcher 写稳定窗口 |
| writable | true | 允许进程内写入覆盖层 |

当前 profile 按以下顺序解析（绝不通过 cwd 猜测）：显式 profile 配置 → 安装位置（profiles//node_modules/…，即 dsh plugin 布局）→ launcher --profile / --profile= → DSH_PROFILE 环境变量。无法确认时启动 fail loud。

覆盖文件

$DSH_HOME/profiles/web/settings.patch.yml
agent-default-model:
provider: pi-ai
model: gpt-5.6

permission:
mode: danger-full-access

some-plugin:
endpoint: !unset

普通 YAML 值 = override；!unset = 显式 mask（删除下层继承值，回退 schema 默认，除非覆盖层自己提供值）。mask 永不进入解析后的 JSON 文档 —— UI 不会把它当作普通值。文件可以手工编辑，也可以通过 settings 命令修改；进程内写入只落在这个文件，绝不写 settings.yaml。

settings 命令

命令运行时挂载后，ctx.profileSettings 与 settings 命令族可用：

settings layers [ns [path]] 每个叶子值的来源链 settings get 读取生效值 settings set 写入 profile 覆盖层 settings unset 删除覆盖值（重新继承） settings mask 写入 !unset settings unmask 移除 mask settings reset 对覆盖层执行 replace({}) settings promote 把值提升到全局文档 settings demote 把值降级到 profile 覆盖层 settings migrate [--copy] 把全局值迁入 profile（先备份 .bak.；--copy 保留全局） settings diff [ns] 全局与覆盖层的叶子级差异 settings ui [ns] 机器可读 JSON 快照（供 Web 页面预览） settings profile 当前 profile 与文档路径

Web UI（Profile Settings 页面）

bundle 自带浏览器半端（client/）：Web 设置面板新增 Profile Settings 页面——每个字段带来源徽标（默认 / 组合 / 全局 / 本 profile / 已屏蔽）、生效值，以及 set / unset / mask / unmask / promote / reset 操作。页面通过 host 半端注册的 /profile-settings loopback RPC 通道通信，不依赖会话上下文、不写命令日志。

配置链与设计说明

Provider 保持官方基类的 document 为 profile raw section，因此 update/replace/mutate/revision/expectedRevision/describe 的语义完全不变；global 层被折进每个注册的合成 base
（applyMasks(merge(composition, global), masks)）。对基类 TS-private 成员
只通过一个窄类型 facade 访问 —— 不 fork 任何 Settings 机制。完整 M0 调研见 docs/research.md。

Fail-loud（启动）：无法解析 profile、覆盖文件根非 map、namespace section 非 object、数组内出现 !unset、不支持的 YAML tag（!!js/、!!python/、自定义 tag）、覆盖路径逃逸 profile 目录、global 与覆盖文件同路径、重复 ctx.settings owner。

Warn + 保留 last good（热加载）：任一文档临时无效 YAML、未注册 namespace （原样保留，等待对应插件稍后加载）。

并发边界与限制

| 范围 | 保证 |
| 同进程普通 set/replace/mutate | 官方 Settings 语义（per-namespace 串行写队列、expectedRevision 冲突检测） |
| 跨进程文件完整性（read-modify-write） | 双文档写锁 + 原子 rename |
| 跨进程自定义层操作（promote/demote/migrate/mask/unmask） | 真事务：固定顺序双锁、锁内 fence 校验、layer fence 随每次写入推进 |
| 跨进程对同一 profile、同一 namespace 的普通 update/mutate | 继承官方 seam 限制：官方 revision 是进程内写队列的，跨进程 CAS 尽力而为（文件锁下后写者胜） |

开发

npm run typecheck # tsc（src + tests）
npm test # vitest
npm run build # tsc 构建 + copy-lib（lib/）
npm pack # prepack 构建 + postpack tarball 冒烟（防泄漏检查）

需要 Node ≥ 22.6（type stripping）与 DSH harness（0.1.1-rc.2 系列）提供 peer 依赖 —— 运行时从安装环境解析，包自身不打包 harness 副本，避免 module twin。

License

MIT