feat(dsh-settings): let plugins declare their settings namespace as web-exposable, removing the apiproxy allowlist as the only opt-in path

[a1phaboy]

现状

• ctx.settings.register(ns, schema, { base, applies, validate }) 只解决"注册 + 分层解析"，不表达任何暴露语义：任何插件都能注册命名空间，但注册本身不会让配置面可读写。
• 浏览器配置页（settings.* wire）能服务的命名空间由 packages/host/apiproxy/src/api-proxy.ts 里硬编码的白名单决定：可配置模型提供方 + WEB_SETTINGS_NAMESPACES（agent-loop/shell/locale/permission/ui-conversation/ui-theme/web-search-deepseek）+ PRODUCT_SETTINGS_NAMESPACES（ui-onboarding、agent-presets）。
• 后果：仓库之外的第三方插件（例如自研的 elasticsearch-plugins）注册了自己的 settings 分节后，网页「插件配置」卡片永远拿到 settings-not-exposed——卡片不渲染、写入被拒。要让它的配置出现在网页上，必须改动 apiproxy 这一行白名单，等于要求每个第三方插件的消费者 fork 框架。
• 源码注释里已把这件事记为 deferred work：「Moving that declaration to settings.register(), so a plugin can expose its own configuration without a change in this package」。

需求

1. 通用性：开源框架应允许任何插件（含仓库外分发的插件）把自己的 settings 命名空间暴露给部署级配置客户端（目前唯一客户端是 Web 配置页），且无需修改 apiproxy。
2. 安全边界不后退：仅仅 register() 绝不能让一个分节变得可被远程读写。暴露必须是 owner 在注册时的显式声明；部署方的决策保持为"挂载了哪些插件"。
3. 生命周期一致：暴露声明跟随注册的 fiber——插件被 dispose/重载时，其声明与注册一起消失，配置面实时收敛。
4. 面向未来：暴露词汇按"配置面（surface）"建模，API 形状要为后续新增配置面（如 ACP/TUI 客户端）留好接口，且一个 surface 只能取回声明给自己的命名空间。

代码改动点

1. packages/settings/settings/src/index.ts

新增类型 + 注册选项：

 /** When a namespace's changes take effect for its owner. */
 export type SettingsApplies = 'live' | 'restart'
 
+/**
+ * Where a namespace's owner opted into having it served to a deployment-wide
+ * configuration client. The vocabulary is deliberately narrow: each member
+ * names one remote configuration surface, and a surface is expected to check
+ * it before reading or writing the namespace.
+ */
+export type SettingsExposure = 'web'
+
 /** Registration options beyond the namespace schema. */
 export interface SettingsRegisterOptions<T> {
   /** Composition-layer values resolved below the user layer (entry-config subset). */
   base?: Partial<T>
   /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
   applies?: SettingsApplies
+  /**
+   * The remote configuration surface that may serve this namespace, overriding
+   * the default of none. A registration alone never makes a section remotely
+   * readable or writable: a wire surface serves only the namespaces whose
+   * owner declared it (see {@link SettingsProvider.exposedNamespaces}), so
+   * exposing configuration is the owner's explicit opt-in rather than a side
+   * effect of registering. The deployment still decides which plugins it
+   * mounts at all.
+   */
+  expose?: SettingsExposure
   /**
    * Reject a resolved section the owner could not act on, for constraints its
    * schema cannot express — ...

注册记录与 register() 透传：

 interface SettingsRegistration {
   ns: SettingsNamespace
   schema: z<unknown>
   base: unknown
   applies: SettingsApplies
+  /** Remote configuration surfaces the owner opted into; none by default. */
+  expose?: SettingsExposure
   /** Owner-supplied check for constraints the schema cannot express. */
   validate?: (value: unknown) => void

     const registration: SettingsRegistration = {
       ns,
       schema: schema as z<unknown>,
       base: options?.base,
       applies: options?.applies ?? 'live',
+      ...options?.expose === undefined
+        ? {}
+        : { expose: options.expose },
       ...options?.validate === undefined
         ? {}
         : { validate: options.validate as (value: unknown) => void },

新增查询方法（放在 get(ns) 之后）：

   get(ns: SettingsNamespace): unknown {
     return this.registrations.get(ns)?.resolved
   }
 
+  /**
+   * The registered namespaces whose owner opted into remote configuration
+   * serving through `expose`. Read live on every call: a registration is an
+   * effect on its owner's fiber, so a disposed (or reloaded) plugin leaves
+   * this set the moment its registration does. A wire surface unions the set
+   * for ITS OWN surface with its internal allowlists before serving a
+   * namespace — the filter is the check the declaration promises.
+   * @param surface - only namespaces declared for this surface; every declared
+   *   namespace when omitted.
+   * @returns the currently exposed namespaces.
+   */
+  exposedNamespaces(surface?: SettingsExposure): ReadonlySet<SettingsNamespace> {
+    const exposed = new Set<SettingsNamespace>()
+    for (const registration of this.registrations.values()) {
+      if (registration.expose === undefined) continue
+      if (surface === undefined || registration.expose === surface) exposed.add(registration.ns)
+    }
+    return exposed
+  }

installSettingsSection 的 hooks 与透传：

   validate?: (value: T) => void
+  /**
+   * The remote configuration surface that may serve this section, forwarded
+   * to the registration when a settings service exists. See
+   * {@link SettingsRegisterOptions.expose}.
+   */
+  expose?: SettingsExposure
 }

     const scope = sctx.settings.register(ns, schema, {
       base: entry,
+      ...hooks.expose === undefined
+        ? {}
+        : { expose: hooks.expose },
       ...hooks.validate === undefined ? {} : { validate: hooks.validate },
     })

2. packages/host/apiproxy/src/api-proxy.ts

白名单注释（删除 deferred work 表述）：

-/**
- * Non-model settings namespaces intentionally served to the Web client. The
- * plugin-owned entries (`agent-loop`, `bash`, `web-search-deepseek`) are the
- * host-plane sections the plugin configuration page edits; a namespace absent
- * here answers `settings-not-exposed` even when its owner registered it, so
- * adding a section to that page is a decision made here rather than by the
- * registering plugin. Moving that declaration to `settings.register()`, so a
- * plugin can expose its own configuration without a change in this package,
- * is deferred work.
- */
+/**
+ * Non-model settings namespaces intentionally served to the Web client beyond
+ * the registrant-declared ones (see {@link exposedNamespaces}). The
+ * plugin-owned entries (`agent-loop`, `bash`, `web-search-deepseek`) are the
+ * host-plane sections the plugin configuration page edits; a namespace absent
+ * from both this list and its owner's `expose: 'web'` declaration answers
+ * `settings-not-exposed` even when its owner registered it. The list exists
+ * for the product's own sections; a third-party plugin exposes its
+ * configuration by declaring `expose` at registration, so it needs no change
+ * in this package.
+ */
 const WEB_SETTINGS_NAMESPACES = [
   'agent-loop', 'shell', 'locale', 'permission', 'ui-conversation', 'ui-theme', 'web-search-deepseek',
 ] as const

门禁并入插件声明集合（读、写共用同一函数）：

   function exposedNamespaces(): Set<string> {
     const exposed = modelProviderNamespaces()
     for (const ns of WEB_SETTINGS_NAMESPACES) exposed.add(ns)
     for (const ns of PRODUCT_SETTINGS_NAMESPACES) exposed.add(ns)
+    // Read live on every call: registrations ride their owner's fiber, so a
+    // disposed or reloaded plugin leaves this set the moment it unregisters.
+    // The surface filter is this wire's check: a namespace declared for some
+    // other configuration client is not thereby served to the browser.
+    const settings = ctx.get('settings')
+    if (settings !== undefined) {
+      for (const ns of settings.exposedNamespaces('web')) exposed.add(String(ns))
+    }
     return exposed
   }

3. 插件侧用法（零 apiproxy 改动）

installSettingsSection(ctx, ES_SETTINGS_NAMESPACE, Config, config, {
  setSource: (source) => { this.current = source },
  onChange: () => { this.reconfigure() },
  expose: 'web', // ← 唯一需要加的声明
})

4. 测试

packages/settings/settings/tests/settings.spec.ts：

it('exposes only the namespaces whose owner declared it, for as long as that owner lives', async () => {
  const { ctx } = await boot()
  // No declaration, no exposure: registering is not enough on its own.
  ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
  expect(ctx.settings.exposedNamespaces()).toEqual(new Set())
  expect(ctx.settings.exposedNamespaces('web')).toEqual(new Set())

  ctx.settings.register(settingsNamespace('workspace'), NestedSchema, { expose: 'web' })
  expect([...ctx.settings.exposedNamespaces()]).toEqual(['workspace'])
  // The surface filter answers for one configuration client: a web wire
  // asking for its own surface sees exactly the same set today.
  expect([...ctx.settings.exposedNamespaces('web')]).toEqual(['workspace'])

  // The exposure rides the registrant fiber: disposing it removes the
  // namespace and its declaration together.
  const fiber = ctx.plugin({
    inject: ['settings'],
    apply: (child: Context) => {
      child.settings.register(settingsNamespace('helper-ns'), ThemeSchema, { expose: 'web' })
    },
  })
  await fiber
  expect([...ctx.settings.exposedNamespaces('web')].sort()).toEqual(['helper-ns', 'workspace'])
  await fiber.dispose()
  expect([...ctx.settings.exposedNamespaces('web')]).toEqual(['workspace'])
})

it('forwards the exposure declaration to the registration', async () => {
  const { ctx } = await boot()
  const entry = { theme: 'entry' }
  const consumer = ctx.plugin({
    inject: ['settings'],
    apply: (child: Context) => {
      installSettingsSection(child, settingsNamespace('helper-ns'), HelperSchema, entry, {
        setSource: () => {},
        onChange: () => {},
        expose: 'web',
      })
    },
  })
  await consumer
  expect([...ctx.settings.exposedNamespaces()]).toEqual(['helper-ns'])
})

packages/host/apiproxy/tests/api-proxy-config.spec.ts：

it('serves a namespace whose owner declared exposure, and refuses one that did not', async () => {
  const ctx = await harness()
  ctx.settings.register(settingsNamespace('third-party-exposed'), z.object({ token: z.string() }), { expose: 'web' })
  ctx.settings.register(settingsNamespace('third-party-private'), z.object({ token: z.string() }))
  const api = createApiProxy(ctx, DEFAULTS)

  const described = expectOk(await api.settings.describe(request({})))
  expect(described.namespaces.map(view => view.ns)).toEqual(['third-party-exposed'])

  const written = expectOk(await api.settings.mutate(request({
    ns: 'third-party-exposed',
    ops: [{ op: 'set', path: ['token'], value: 'abc' }],
  })))
  expect(written.value).toEqual({ token: 'abc' })

  expect(expectErr(await api.settings.update(request({
    ns: 'third-party-private',
    patch: { token: 'abc' },
  }))).code).toBe('settings-not-exposed')
  // The refusal happened before the seam: the section kept whatever it had.
  expect(ctx.settings.describe().find(d => String(d.ns) === 'third-party-private')?.value).toEqual({})
})

使用方式：自定义卡片 + expose: 'web'

expose: 'web' 只解决数据面（让命名空间可被浏览器读写），它不会自动生成卡片。完整流程需要两半各做一步：

1. Host 侧：插件注册分节时声明 expose: 'web'；
2. 浏览器侧：插件（或其配套 client 包）把卡片组件注册进 settings.plugin.item slot。

① Host 侧：注册 + 声明暴露

// example-card-plugin/src/index.ts
import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'

export const EXAMPLE_CARD_PLUGIN_SETTINGS_NAMESPACE = settingsNamespace('example-card-plugin')

export const Config: z<Config> = z.object({
  servers: z.array(z.string()).default(['http://localhost:8080']),
  username: z.string(),
  apiToken: z.string().role('secret'),   // secret：浏览器永远读不回，只能写入
  strictMode: z.boolean().default(true),
})

export default class ExampleCardPluginService extends Service {
  private current: () => Config

  constructor(ctx: Context, config: Config) {
    super(ctx, 'example-card-plugin')
    this.current = () => config
    installSettingsSection(ctx, EXAMPLE_CARD_PLUGIN_SETTINGS_NAMESPACE, Config, config, {
      setSource: (source) => { this.current = source },
      onChange: () => { this.reconfigure() },   // 配置提交后重派生派生状态
      expose: 'web',   // ← 唯一需要加的一行：声明本分节允许 Web 配置页读写
    })
  }
}

不写 expose 的字段/分节，对浏览器依旧完全不可见——默认拒绝不变。

② 浏览器侧：注册卡片（需要 browser half）

卡片的宿主是 ui-settings-plugins 声明的 settings.plugin.item 列表 slot。插件要自带卡片，需要以 dsh.client.platform: "web" 的 client 插件形态注册一个贡献：

// 客户端插件 apply(ctx) 里
const controller = new ExampleCardController(ctx.settingsScope.bind({ namespace: EXAMPLE_CARD_NS }))

ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
  name: 'settings.plugin.item',
  id: 'example-card-plugin',   // 卡片 id，唯一即可
  order: 30,                   // 卡片排序
  locale: NS,                  // 文案字典命名空间
  inject: () => controller.inject(),  // 状态 store + save/discard/edit 动作
}, ExampleCard))

卡片控制器复用 ui-settings-plugins 的表单设施（CardForm 暂存式表单、PluginCard 外壳、ValueField/SecretField 控件）：

export class ExampleCardController {
  constructor(scope: SettingsScope<ExampleCardSettings>) {
    this.form = new CardForm(
      scope,
      [serversField(), textField('username')],                              // 常规字段：format/parse 规格
      [{ field: 'apiToken', write: text => scope.set('apiToken', text) }],  // secret 只写不读
    )
  }
  inject(): ExampleCardFace {
    return { hooks: { exampleCard: this.store }, ...this.form.actions() }
  }
}

[weijiafu14]

这个提案我举双手赞成，而且我大概是最有资格证明它必要的人之一：我们就是你描述的那种"仓库之外的第三方插件"，而且我们已经被这条白名单逼着绕过去了。 下面是第一手的现状报告——它同时是给你的一条"今天就能用"的路，和一份支持你这个 RFC 的证据。

我们撞上的就是这堵墙，绕法是自己造一整个数据面

我维护 pi2dsh（把 Pi 生态插件翻译成 DSH 原生插件的兼容层）。它的产品层 dsh-work-x 在 DSH Web 里有一个 MCP 管理页和一个 Settings 里的全局视图。

按理说这该是 ctx.settings.register 的活。实际实现是这样的：

1. UI 那一半走 client slot：往 settings.section 注册一个组件——这条路是通的，slot 体系对仓库外插件没有白名单。
2. 数据那一半完全自建：拿 ctx.webServer，注册一个 /pi2dsh 前缀路由，自己解析 method/path、自己收 POST body、自己 JSON.parse、自己写响应。

也就是说：ctx.settings.register 我们一次都没调过。 不是因为不需要分层配置，是因为调了也没用——配置面拿不到，卡片渲染不出来。

这正好印证你写的那句"等于要求每个第三方插件的消费者 fork 框架"：我们没 fork，我们付的是另一种代价——重写一遍配置的数据面。

这条绕法对你有用，但它的代价值得写进提案

如果你现在就要让 elasticsearch-plugins 的配置出现在网页上，上面两步今天可用（我们在真 DSH loop 上跑着）。但我建议你把这个代价明确写进 RFC 的动机段，因为它比"要 fork 框架"更能说明问题——绕得过去，恰恰证明这不是安全边界，只是摩擦：

• 丢掉分层解析：base 那一层（composition-layer values resolved below the user layer）没了。我们自己的路由只知道自己那个文件，不知道 profile/entry-config 的叠加。
• 丢掉 applies：配置面无从知道这个改动是 live 生效还是要重启，只能在 UI 里写死一句话。
• 丢掉 validate：owner 用来表达 schema 表达不了的约束的那个钩子，自建路由里得自己重新发明。
• 丢掉落盘语义：settings.yaml 那套统一的读写和冲突处理，变成每个插件各写各的文件、各定各的格式。

换句话说：白名单没有挡住任何东西，它只是把插件推去实现一个更差的 settings。 这比"第三方插件配不了"更值得写——前者听起来像功能缺失，后者是安全性没提升、一致性却在流失。

对 API 形状的两点意见

你的设计我基本认同（声明式 opt-in、跟随 fiber 生命周期、按 surface 建模）。两点：

1. SettingsExposure = 'web' 这个联合类型的扩展成本。
你写了"为后续新增配置面（如 ACP/TUI 客户端）留好接口"，但字符串联合意味着每加一个 surface 都要改 dsh-settings 这个包并发版，而 surface 恰恰可能由第三方引入（比如某天有人写了个 TUI 配置面板——顺带说，我们自己就在往 dsh-TUI 和 dsh-pi-tui 两个终端投影 UI，第三方 surface 不是假想）。

建议至少在文档上把它定成"开放词汇"（type SettingsExposure = 'web' | (string & {})），或者干脆让 exposedNamespaces(surface: string) 按字符串匹配。由 surface 自己声明身份、由 owner 按名字 opt-in，比中央枚举更符合你第 1 条"无需修改 apiproxy"的目标——否则你只是把白名单从 apiproxy 搬到了 dsh-settings 的类型定义里。

2. expose 的粒度可能不够。
现在是"这个 namespace 能不能被这个 surface 服务"，一个布尔式的门。但配置里常有该显示但不该远程写的项（只读诊断值），以及该写但不该回显的项（凭证引用）。如果第一版就把 expose?: SettingsExposure 定成标量，后面想区分读/写只能加新字段。可以考虑现在就留成 expose?: SettingsExposure | { surface: SettingsExposure, mode?: 'read' | 'readwrite' }——不用实现，只是别把形状锁死。

（凭证这条对我们尤其现实：我们的铁律是凭证只经环境变量注入、永不落盘、永不回显，配置里只放 apiKeyEnv 这样的引用名。一个配置面如果只能"全暴露或全不暴露"，带凭证引用的 namespace 就会一直被 owner 保守地关着。）

边界与利益相关

我们不修 DSH 自家组件——dsh-settings、apiproxy 都在 DSH 里，上面全是现状报告和意见，不是我能替你落地的。

这条不推销：你要的是这个 RFC 被接受，装我们的东西对此毫无帮助。上面那条 webServer 绕法是任何插件都能自己做的通用手法（就是 ctx.webServer.register 两行起步），不需要经过我们。

最后一句实在话：你这份提案里最有力的部分是那段源码注释引用——"Moving that declaration to settings.register(), so a plugin can expose its own configuration without a change in this package"。DSH 自己已经把这件事记成了 deferred work，你等于是把它做完了。这比任何外部论证都管用，建议把它提到动机段的最前面。