[Feature]: 支持插件在注册期声明 settings 命名空间暴露（落地 2026-08-10-web-plugin-configuration 笔记中暂缓的备选方案）

[huantuoshen-prog]

背景

Web 设置页的插件配置区只渲染编译期硬编码白名单 WEB_SETTINGS_NAMESPACES（packages/host/apiproxy/src/api-proxy.ts）中的命名空间。settings.describe RPC 对结果做 filter(descriptor => exposed.has(ns))，名单之外的命名空间即使已被插件注册也会得到与未注册完全相同的 settings-not-exposed，客户端 settings scope 停在 unavailable。

官方设计笔记 .agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.zh.md 明确这是预期行为（"暴露仍是 Host 的白名单"），并把"用注册期的暴露声明取代白名单"列为暂缓的备选方案（顾虑：seam 契约变更、全部现有注册点、fail-closed 脱敏路径）。

实际问题

第三方插件无法向 Web 设置页暴露自己的配置命名空间，除非本地修改 harness 包。

实例：dsh-web-ui 全家桶（@linxin666/dsh-web-ui-all@0.1.9/0.1.10，社区最热门的 Web 增强插件集）通过 settings.register() 注册了 pet / task-board / live-stats / remote-web-ui / dsh-ssh / skin-background 等命名空间，但因白名单过滤，其「Web UI 插件」设置组 5 张配置卡片中 4 张静默隐形（PluginSettingsCard 在 scope unavailable 时 return null），配置不可读也不可写。用户唯一出路是手工修改 dsh-host-apiproxy 的编译期白名单（社区已实测可行）。

相关报告：zhu1090093659/dsh-web#92（open）。

请求

1. 实现注册期暴露声明（例如 settings.register(ns, schema, { expose: true })），并配套 fail-closed 的 secret 脱敏校验（笔记中提到的前置条件）；或
2. 短期方案：把白名单开放为可配置（如允许 profile patch / 插件 Config 追加暴露的命名空间），使 rc.6 等已发布版本无需升级 harness 即可支持第三方插件设置卡片。

影响面

• 所有需要向 Web 设置页暴露配置的第三方插件（不仅是 dsh-web-ui 家族）；
• 当前 npm 最新仍为 0.1.0-rc.6，白名单机制未变。

[weijiafu14]

你这帖有两样别的同类帖没有的东西：最大的实测影响面，和一个短期方案。我想把这两样都加固一下，因为你的短期方案可能比长期方案更值得先推。

一、先说规模：这已经是第七个独立线程了

这堵墙现在被至少七个线程各自撞到过，而且每个都带着不同的插件：

帖	被卡住的插件	症状
本帖 #1144	@linxin666/dsh-web-ui-all（pet / task-board / live-stats / remote-web-ui / dsh-ssh / skin-background）	5 张配置卡片 4 张静默隐形
#903	dsh-tool-vision / dsh-soul-md / dsh-tdai-memory	设置页显示"namespace 不可用"，写入被拒
#1877	dsh-sampling-sliders / dsh-friendly-errors / dsh-smart-route	写入 settings-not-exposed；smart-route 的卡片永远停在 loading
#1183	dsh-auto-continue	同上，作者已发布 scripts/patch-expose.mjs
#1196	——	引了官方设计笔记原文（见下）
#3114	——	已写成带完整 API 设计的 RFC
#2239	——	同一诉求

十三个以上具名插件、七个线程、至少三份各自独立写的 patch 脚本。 其中 #903 那份最激进——插件在运行时通过模块缓存定位并改写宿主安装目录下的 lib/index.js，而且设计成"dsh 更新后自愈"。

（顺带我这边也算一个：我维护 pi2dsh，它的产品页在 DSH Web 里从没调过 ctx.settings.register——调了也拿不到配置面，只能用 ctx.webServer.register 起一条自己的路由把数据面重写一遍。代价是丢掉 base 分层解析、applies、validate 和 settings.yaml 的统一落盘语义，等于每个插件各造一个更差的 settings。）

这份名单本身就是论据。 设计笔记把注册期声明"暂缓"时，成本是"加第四个插件要改一次白名单"；现在的实际成本是十三个插件、三份 patch 脚本、和一个会自愈的宿主文件改写器。建议把这张表放进原帖开头——这一族现在最缺的不是又一个提案，是有人把规模摆出来。

二、你的短期方案（把白名单开放为可配置）比它看上去更强

你的方案 2 是：

把白名单开放为可配置（如允许 profile patch / 插件 Config 追加暴露的命名空间）

我认为这条恰好绕开了设计笔记列出的全部三个暂缓理由，值得单独强调。#1196 引的笔记原文把顾虑写得很清楚：seam 契约变更、全部现有注册点、fail-closed 脱敏路径。逐条对：

暂缓理由	注册期声明（方案 1）	profile patch 可配置（方案 2）
改 seam 契约	要给 settings.register 加选项	不动 seam，一个字都不改
影响全部现有注册点	每个注册点都要复核	零注册点受影响
需要 fail-closed 脱敏路径	插件能暴露任意 schema，所以必须先有脱敏	暴露的仍是人挑的那几个，风险模型和今天一模一样

最后一行是关键。设计笔记坚持的那句是——

「暴露仍是 Host 的白名单……因此本页的覆盖面是 Host 的决定而非插件的决定。」

而 profile patch 就是 Host 的决定。 部署方在自己的配置文件里写一行"我要暴露 pet 这个命名空间"，和今天有人在 api-proxy.ts 里加一行，在信任模型上是同一件事——只是前者不需要动 node_modules。这不是放松边界，是把同一个边界从编译期常量搬到部署方够得着的地方。

所以我建议把你的方案 2 从"短期方案"提成独立提案：

让 WEB_SETTINGS_NAMESPACES 可以被 profile 配置追加（不是替换）。 默认值不变，插件不能自行加入，只有部署方能加。

它可以和 #3114 那份 RFC 并行推进而不冲突——RFC 解决的是"插件自己声明"（需要脱敏、需要改契约，慢），这条解决的是"用户今天怎么用上已经装好的插件"（不需要任何前置条件，快）。两者不是二选一，是不同时间尺度上的两件事。

三、给今天被卡住的人：一条不改宿主文件的路

在上面任何一条落地之前，@linxin666/dsh-web-ui-all 这类插件其实还有一条不需要动 node_modules 的路——把 UI 和数据面拆开：

1. UI 照常走 settings.section——slot 体系对仓库外插件没有白名单，卡片注册得上；
2. 数据不走 settings.* wire，改用 ctx.webServer.register 挂一条自己的前缀路由，卡片直接读写它。

我们就是这么落地的，跑在真 DSH loop 上，全程没有改动宿主目录下的任何一个字节。代价前面说过了（丢掉分层解析 / applies / validate / 统一落盘），它是绕法不是修复——但比"运行时改写宿主 lib/index.js 并自愈"安全得多：后者在只读安装上会失败、多个插件同时干会打架、而且上游若因安全原因收紧白名单会被静默改回。

边界与利益相关

我们不修 DSH 自家组件——apiproxy、settings seam 都在 DSH 里。第二节那张对照表是我对着 #1196 引的设计笔记原文逐条推的，我没有读过 apiproxy 的完整实现，如果 profile patch 那条路在实现上有我没看到的障碍，以维护者的判断为准。

利益相关：我维护 pi2dsh，是这个提案的直接受益者之一，先说在前面。这条不推销：第三节那条绕法用的 ctx.webServer.register 是任何插件都能直接用的公开面，两行起步，不需要经过我们。