DSH plugin 界面开发：设置卡片怎么注册、Host 半与浏览器半怎么配合、client 打包怎么写

DSH plugin 的界面开发不是「写个前端页面」，而是在同一个包里写两半代码：Host 半用 ctx.settings.installSection() 注册一个设置命名空间，浏览器半向 settings.plugin.item 槽注册一张卡片；两半靠同一个命名空间自动配对，无需改动宿主仓库。 无论叫 DSH插件 还是 DeepSeek插件，界面开发的这套两半结构完全一致。

DSH plugin 界面开发的两半结构：一个包，两个入口

设置页由 Host 半与浏览器半组成，缺一半卡片不会出现。 官方 Cookbook 的原话是：Host 服务每个已注册的设置命名空间，「Plugins」区按卡片编辑的命名空间给它们配对，两半都在一个包里——Host 半在 src/，浏览器半在 src/client/，通过 exports['./client'] 导出并用 dsh.client 声明（来源）。

my-plugin/
├── src/index.ts          # Host 半：注册命名空间
├── src/client/index.tsx  # 浏览器半：注册卡片
└── package.json          # exports['./client'] + dsh.client

配对键只有一个：命名空间。 建议把它写成常量（如 MY_PLUGIN_NS = 'my-plugin'），两半引用同一个常量，避免拼写漂移导致「卡片没出现」。

DSH plugin 的 Host 半：注册设置命名空间

已有 cordis.yml 条目的插件走 ctx.settings.installSection()，它会把条目分层放在用户文档之下，并且在没有设置提供方挂载时依然工作。 官方给出的宿主半写法如下：

import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-settings'
import z from '@deepseek-ai/schemastery'

export const MY_PLUGIN_NS = 'my-plugin'

export interface Config {
  endpoint?: string
  retries?: number
}

export const Config: z<Config> = z.object({
  endpoint: z.string(),
  retries: z.number().step(1).min(0).default(3),
})

export function apply(ctx: Context, config: Config) {
  let source = () => config
  ctx.inject(['settings'], (settingsCtx) => {
    settingsCtx.settings.installSection(ctx, MY_PLUGIN_NS, Config, config, {
      // schema 表达不了的约束：拒绝这次写入，而不是留到下次使用才报错。
      validate: value => void assertReachable(value.endpoint),
      setSource: (current) => { source = current },
      onChange: () => { rebuildFromSettings(source()) },
    })
  })
}

两个容易忽略的声明：给字段加 role('secret') 会让它的值不出现在任何响应里（卡片要么把它写进 update/mutate 载荷，要么通过 credentials 域引用凭据）；applies: 'restart' 告诉配置界面「拥有者要到下次启动才真正生效这次变更」。

DSH plugin 的浏览器半：把卡片挂进槽位

卡片注册进 settings.plugin.item 槽，key 必须与 Host 半的命名空间一致。 官方示例：

import type { Context as ClientContext } from '@deepseek-ai/cordis'
// 仅类型导入：该槽位的声明。跨插件协作一律走 cordis 服务，
// 值导入会被 client 的 bundle-purity 关卡拦下。
import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'

export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope']

export function apply(ctx: ClientContext): void {
  const card = new MyPluginCardController(ctx.settingsScope.bind({ namespace: MY_PLUGIN_NS }))
  ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
    name: 'settings.plugin.item',
    key: MY_PLUGIN_NS,
    locale: 'settings.myPlugin',
    inject: () => card.inject(),
  }, MyPluginCard))
}

卡片拥有自己内部的一切：外观、控件、文案。注意上面那行 import type {}——跨插件只能用类型导入，值导入会被 bundle-purity 关卡拒绝。

DSH plugin 配置读写语义：value / base / user 三层

作用域快照携带表单需要的三层信息，判断「是否被覆盖」看的是键的存在性而不是值。（来源）

写操作用 scope.set(field, value) 存单个字段，scope.unset(field) 把它清回组合层。每次写入都用读到的 revision 做栅栏——这能避免两个设置面板同时修改时互相覆盖。

DSH plugin 界面显示规则与打包要求

显示规则很直接：Host 服务该键且卡片注册了该键才渲染；Host 没服务就整张卡片不出现；Host 服务了但没有卡片认领，则什么都不渲染——这正是 ui-theme、permission、llm-* 这些命名空间不出现在该标签页的原因。卡片顺序等于注册顺序，带 key 的条目不能自己声明 order。

打包三条硬要求（来源）：

1. package.json 用 exports['./client'] 暴露浏览器半，并声明 dsh.client（含 platform 与它依赖的 client 包）；
2. bundle 必须是加载器期望的 lazy-CJS 工厂产物——仓库外没有公开 preset，需要自行复现同样的输出格式；
3. 不能跨插件值导入：卡片要自带外观与暂存模型，自己拥有暂存与 revision 栅栏。

只要 cordis.yml 挂上这个插件，它就出现在页面上，无需重建 Web 应用——因为客户端模块系统是扫描已启用条目、按 dsh.client 服务构建产物的。

DSH plugin 界面开发自检与下一步

发布前过一遍：

1. 命名空间常量是否两半共用；
2. Host 半是否处理了 validate（schema 表达不了的约束）、setSource、onChange；
3. 敏感字段是否加了 role('secret')，需要在下次启动才生效的是否标了 applies: 'restart'；
4. 卡片是否只用类型导入跨插件；
5. exports['./client'] 与 dsh.client 是否齐备，bundle 是否为 lazy-CJS 工厂产物。

工具调用的卡片呈现是另一条线（presentCall / presentResult，且必须是纯函数），见 怎么写工具插件。界面之外的配置声明见 插件配置怎么用；打包与发布见 打包成 bundle 与 发布到插件中心。