Third-party plugins cannot expose Web settings sections (WEB_SETTINGS_NAMESPACES allowlist)

[Scorp1o117]

Third-party plugins cannot expose Web settings sections (WEB_SETTINGS_NAMESPACES allowlist)

TL;DR: the Web settings client only serves namespaces hard-coded in dsh-host-apiproxy's WEB_SETTINGS_NAMESPACES allowlist. Any namespace registered by a third-party plugin through installSettingsSection / settings.register() answers settings-not-exposed on stock installs, even though it is fully registered host-side. A first-class expose flag on settings.register() would fix this cleanly.

Where

@deepseek-ai/dsh-host-apiproxy/lib/index.js:

const WEB_SETTINGS_NAMESPACES = [
  "agent-loop", "shell", "locale", "permission",
  "ui-conversation", "ui-theme", "web-search-deepseek",
];

exposedNamespaces() = configurable model providers + this allowlist + product namespaces. The code comment next to the list already acknowledges the design gap:

"Moving that declaration to settings.register(), so a plugin can expose its own configuration without a change in this package, is deferred work."

Impact

We maintain three third-party plugins (dsh-tool-vision, dsh-soul-md, dsh-tdai-memory) that register settings-backed configuration (secret API keys, model endpoints, persona paths). On any stock install:

• settings.describe filters their namespaces out → the Web settings page shows "settings namespace is not available"
• settings.update/mutate refuses with settings-not-exposed

The only workarounds today are editing dsh-host-apiproxy/lib/index.js by hand (lost on every dsh update) or giving up the settings UI entirely. Meanwhile the harness marketing is literally "Everything is a Plugin" — the settings surface is the one seam where third-party plugins are second-class.

Proposed fix (opt-in exposure)

1. settings.register(ns, schema, options) gains an expose option (default false), and installSettingsSection passes expose: true — or add an explicit installSettingsSection(..., { expose: true }) hook flag.
2. The registration descriptor carries the flag; dsh-host-apiproxy's exposedNamespaces() collects exposed namespaces from the live settings registry instead of a hard-coded array.
3. Namespaces without the flag stay private (current security posture preserved: nothing crosses the wire unless the owner opts in).

This keeps the "decision made by the registering plugin" model the comment asks for, without a change to this package for every new plugin.

Bonus (small): JSON.parse chokes on UTF-8 BOM

dsh-client-modules and dsh-app-boot read plugin package.json with bare JSON.parse(readFileSync(..., "utf8")). A UTF-8 BOM (easy to produce with editors on Windows) throws Unexpected token '\uFEFF' and crashes dsh web at boot / dsh plugin reconcile. A defensive JSON.parse(text.replace(/^\uFEFF/, "")) would make the harness robust to editor defaults.

Our current workaround (shipping today)

Our plugins locate the dsh-host-apiproxy file through the host process module cache and idempotently insert their namespace into the allowlist at startup (self-healing after dsh updates). It works, but it is exactly the kind of hack a first-class expose flag would make unnecessary — and it edits files under the user's dsh installation, which is not something plugin authors should have to do.

Happy to contribute a PR if pull requests are accepted; we just couldn't file an issue since issues are disabled on this repo, so posting here per the repo's feedback channel.

[StarsMilky]

English

Confirmed independently — reproducing the BOM "Bonus" issue

We hit this on a stock install and can add exact call sites to your Bonus section:

• packages/boot/app-boot/src/profile.ts → readProfileManifest: JSON.parse(readFileSync(path, 'utf8')), called from both apps/cli/src/plugin.ts (exportsPatch per-dependency during dsh plugin reconcile, runPlugin before/after pnpm) and loadProfile (boot-time validation that every dsh.profile.bundles entry declares dsh.bundle).
• packages/client/modules/src/index.ts:344 → bare JSON.parse(readFileSync(pkgPath, 'utf8')) while scanning a plugin's dsh.client manifest.

The failure mode is worse than a crash: dsh plugin --profile web add <pkg> lets pnpm finish successfully, then reconciliation dies with SyntaxError: Unexpected token '\uFEFF' and exit 1 — leaving the dependency written to package.json but dsh.profile.bundles unreconciled (a half-updated profile the user has to clean up by hand). A bundle package with a BOM'd manifest also fails dsh web at boot.

Real-world case: dsh-mcp-manager@0.5.0 ships a package.json starting with EF BB BF. Its own scripts/build.mjs even reads it via JSON.parse(readFileSync(...).replace(/^\uFEFF/, '')) — the author knew, and robust consumers strip the BOM. The harness is the outlier.

Minimal fix, no behavior change otherwise:

const parsed = JSON.parse(raw.replace(/^\uFEFF/, '')) as ProfileManifest | null

plus the same one-liner in client/modules and a unit test with a BOM'd fixture. Happy to contribute a PR if pull requests are accepted.

中文

独立复现确认 —— 补充 Bonus 小节的确切位置

我们在干净安装上踩到了同一问题，可以给你 Bonus 小节补上精确调用点：

• packages/boot/app-boot/src/profile.ts 的 readProfileManifest：JSON.parse(readFileSync(path, 'utf8'))，被 两处 调用——apps/cli/src/plugin.ts 的 exportsPatch（dsh plugin 归对账时逐个读依赖的 package.json）和 runPlugin（pnpm 前后），以及 loadProfile（boot 时校验 dsh.profile.bundles 每个条目声明 dsh.bundle）。
• packages/client/modules/src/index.ts:344：扫描插件 dsh.client 清单时同样是裸 JSON.parse(readFileSync(pkgPath, 'utf8'))。

失败模式比单纯崩溃更糟：dsh plugin --profile web add <pkg> 时 pnpm 已经成功装完，归对账才因 SyntaxError: Unexpected token '\uFEFF' 退出（exit 1）——依赖已写进 package.json，但 dsh.profile.bundles 没有对账，留下半完成状态，用户得手动清理。带 BOM 的 bundle 包还会让 dsh web 在 boot 阶段直接挂。

真实案例：dsh-mcp-manager@0.5.0 发布的 package.json 以 EF BB BF 开头；它自己的 scripts/build.mjs 读这份文件时都专门写了 JSON.parse(readFileSync(...).replace(/^\uFEFF/, ''))——作者自己知道，健壮的消费方都会剥 BOM，harness 反而是那个例外。

最小修复，无其他行为变化：

const parsed = JSON.parse(raw.replace(/^\uFEFF/, '')) as ProfileManifest | null

另在 client/modules 同样加一行，并补一个带 BOM fixture 的单测。如果接受 PR，我们很乐意直接提。

[Scorp1o117]

English

Thanks for the independent confirmation — we just verified every call site against the shipped dsh 0.1.0-rc.6 code and it all checks out:

• readProfileManifest (packages/boot/app-boot → built lib/index.js:453): bare JSON.parse(readFileSync(path, "utf8")), used by both the dsh plugin reconcile path (exportsPatch per dependency) and loadProfile's boot-time bundle validation.
• The bundle-manifest read at loadProfile (built lib/index.js:548) is also bare.
• dsh-client-modules scans plugin manifests with the same bare JSON.parse (built lib/index.js:248).

The half-updated profile failure mode is exactly as you describe: pnpm completes, then reconcile throws SyntaxError: Unexpected token '\uFEFF' and exits 1, leaving the dependency written to package.json without the reconciled dsh.profile.bundles entry. We've been bitten by BOMs ourselves — our plugin repo ships a CI BOM check for exactly this reason.

We fully support the minimal fix (JSON.parse(raw.replace(/^\uFEFF/, "")) in both call sites plus a BOM'd fixture unit test) and would be happy to review/test the PR if you open one.

Separately — the main topic of this discussion (a first-class expose flag on settings.register() so third-party plugins can open their own settings namespaces without editing the allowlist) is still open and, as far as we can tell, hasn't received a maintainer response yet. We'd love to hear whether a PR in that direction would be welcome; our current workaround (idempotent allowlist patch at plugin startup, self-healing after dsh updates) keeps working in the meantime.

中文

感谢独立复现确认——我们在发行版 dsh 0.1.0-rc.6 上逐点核对了调用位置，全部属实（dsh-app-boot 的 readProfileManifest 与 loadProfile 的 bundle 清单读取、dsh-client-modules 的清单扫描都是裸 JSON.parse）。"pnpm 已成功、对账才炸、留下半更新 profile"的失败模式也和我们的观察一致。我们自己也被 BOM 坑过（插件仓库为此专门加了 BOM 检查 CI），完全支持这个最小修复方案，欢迎开 PR，我们可以帮忙验证。

另外主帖的 settings.register expose 方案（让第三方插件无需改白名单即可开放自己的设置命名空间）目前还没有 maintainer 回复，想确认一下这个方向是否接受 PR。我们的临时方案（插件启动时幂等补白名单，dsh 更新后自愈）在正式方案落地前会继续工作。

[weijiafu14]

提案我完全支持（另外两个帖子在要同一件事：#1877 和 #3114，后者已经写成了带 API 设计的完整 RFC）。我想说的是你们正在出货的那个变通方案——它有几个风险，而且有一条更安全的路今天就能走。

那个自愈式改写宿主文件的做法，风险比看上去大

我们的插件通过 host 进程的模块缓存定位 dsh-host-apiproxy 文件，在启动时幂等地把自己的 namespace 插进 allowlist（dsh 更新后自愈）。

我理解为什么会走到这一步，也认同你自己的判断（"这正是一等公民 expose 标志该消灭的那种 hack"）。但有四个后果值得摆出来：

1. "更新后自愈"是双刃的。 这条 allowlist 是一个安全控制点。如果哪天上游因为安全原因收紧它，你们的插件会在用户毫不知情的情况下把它改回去。这不是假想——自愈的定义就是"不管上游改成什么，我都改回我要的样子"。
2. 两个插件同时这么干会打架。 你们的三个插件加上别人的（这一族至少还有 dsh-sampling-sliders、dsh-smart-route、dsh-friendly-errors），并发改写同一个 lib/index.js，交错写入的结果是文件损坏而不是合并。
3. 只读安装直接失败。 全局安装、容器镜像、被 MDM 管控的机器上，插件对宿主目录没有写权限——失败形态多半还是静默的。
4. 它会让插件进不了受管环境。 任何做过软件审计的组织，看到"插件在运行时改写宿主安装目录下的文件"这一条就会直接拒。这对你们插件的可分发性是实打实的损失。

顺带一个具体的坑（另一个帖子刚踩过）：改写 node_modules 的补丁会被静默还原——dsh plugin add 任何一次执行都会让 pnpm 从 store 重建 node_modules，你们的插入就没了。你们的自愈逻辑能救回来，但只在下次启动时；这中间用户看到的是"设置页刚才还好好的，现在又不可用了"。

一条不碰宿主文件的路

白名单挡住的是 settings 的数据面（settings.describe 不列你的 namespace → 客户端 settingsScope 停在 unavailable）。但 slot 体系对仓库外插件没有白名单——settings.section 你注册得上。

所以把两半拆开：

1. UI：照常往 settings.section 注册卡片组件；
2. 数据：不走 settings.* wire，改用 ctx.webServer.register 挂一条自己的前缀路由，卡片直接读写它。

我们（一个仓库外的第三方插件）在 DSH Web 里的管理页就是这么落地的，跑在真 DSH loop 上：ctx.settings.register 一次都没调过，因为调了也拿不到配置面。全程没有改动宿主安装目录下的任何一个字节。

代价照说（我们付了）：丢掉 base 那层组合级解析、applies（live 还是要重启）、validate、以及 settings.yaml 统一的落盘语义——等于每个插件各造一个更差的 settings。这恰恰是第 1 条该被修的理由，不是它已经被解决的证据。 但至少它不动宿主的文件，也不会在安全更新面前自愈。

关于 BOM 那条"Bonus"

@StarsMilky 补的调用点和你的复核已经很完整了。我只想说这条不该当 bonus：你们描述的失败形态是半更新的 profile（pnpm 成功了、reconcile 抛了、依赖写进了 package.json 但 dsh.profile.bundles 没对齐，用户得手工收拾）。

一个让用户的配置停在中间状态的崩溃，比设置页少一个 section 严重。 建议把它单独开一帖，标题直接写后果（"BOM in a plugin manifest leaves a half-updated profile after dsh plugin add"），正文就用你们俩已经核实的那几个调用点。同一份证据装在"bonus"里和装在独立标题里，得到的处理速度会差很多。

一件对 RFC 有用的事

#3114 那份 RFC 最缺的是"有真实消费者"。这一族现在被卡住的插件已经能列成表了：

插件	症状
dsh-tool-vision / dsh-soul-md / dsh-tdai-memory	设置页显示"namespace 不可用"，写入被拒
dsh-sampling-sliders	浏览器写入全部 settings-not-exposed
dsh-smart-route	设置卡片永远停在 loading
（我们的兼容层产品页）	只能自建 webServer 数据面绕过

六个用途完全不同的插件撞同一堵墙，其中一个已经被逼到改写宿主文件。这份名单贴到 #3114 去比留在各自帖里有用。

边界与利益相关

我们不修 DSH 自家组件——apiproxy、settings seam 都在 DSH 里。上面第一节是风险提示、第二节是绕法不是修复。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销：ctx.webServer.register 是任何插件都能直接用的公开面，两行起步，不需要经过我们。