deepseek-harness/packages/client/ui-models/README.zh.md

@deepseek-ai/dsh-client-ui-models

English | 中文

模型设置插件：提供方配置页和按条件显示的 DeepSeek 官方首次使用引导步骤。它把三个协议领域汇聚为一个共享快照：llm.providers（可配置提供方目录，含每条路由的存活／休眠状态）、settings.describe（序列化 schema、分层脱敏值、secret 槽位）与 credentials.describe（不含值的 configured/source/writable 徽标）；页面据此渲染提供方行，一次只展开一张编辑卡片，且不把路由存活状态呈现为提供方状态。

行是已配置的提供方（其 profile 在所属 namespace 中解析得出）；密钥未在任何地方配置的整分节提供方（DeepSeek 的首次运行姿态）会渲染为其展开的设置卡片而非一行，「新增」流程则是一张承载休眠目录提供方选择框的卡片——裸挂载的 llm-pi-ai 在任何路由存在之前就能提供其完整的已安装 catalog。编辑器是每个适配器家族各一张的手写卡片：主字段是单独一个 API 密钥输入框——页面从不询问环境变量名；键入的密钥经 credentials.set 以只写方式存入 profile 的引用之下，profile 没有引用时便派生 <ROUTE>_API_KEY，pi-ai profile 会把这次派生记录为 apiKeyEnv，因此 settings.yaml 从不携带密钥值。收起的「自定义设置」折叠区承载精选的额外字段——两个家族都有 baseURL（deepseek 的占位符显示公共端点），另有 reasoningEffort（deepseek）或 reasoning（pi-ai），以及直接 DeepSeek 适配器的建议性模型目录。每条 DeepSeek 模型行可编辑 id、可选的显示名称 name 与可选的 contextWindow；精选集合以外的现有字段会在编辑后保留，其余每个 profile 字段仍归 settings.yaml 所有。只有当某行仅由用户层承载时它才可删除（删除会还原组合 base），而且必须先在本地化对话框中确认，页面才会提交这次破坏性的 unset。

前序首次使用引导页面完成后，DeepSeek 步骤会从同一个联接快照得出 deepseek-official 的就绪状态。它通过 llm-deepseek 的可配置提供方声明识别官方适配器，因此同 id 但未声明的存活路由不属于可修复配置。若 apiKey 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，该步骤会直接完成而不渲染，其中包括来自启动环境且只读的凭据。只有已挂载且活跃、引用可写但尚未配置的适配器才会显示前往「设置」Models 分区的页面；密钥输入和 credentials.set 仅由该分区已有的设置卡片负责，该步骤绝不持有 secret。适配器缺失、路由不活跃、联接失败、部署只读或设置／凭据能力不可用时，该步骤均不渲染并直接完成，以免首次使用引导阻塞产品；Models 页仍是诊断界面。

每一次编辑都以 settings.mutate 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除提供方行则是单独一条 unset。页面自始至终只持有脱敏后的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。DeepSeek 的 models 是一个按值整体替换的数组：编辑器会显示继承而来的生效模型行，直到第一次模型编辑将完整数组具化到用户层；重置则会取消该覆盖。每个模型行承载模型 ID 与显示名称，其上下文窗口与最大输出 token 数则收在该行自己的折叠区里，与 pi-ai 提供方表单采用的形态相同。两项容量都按数值键入，可带十进制的 K 或 M 后缀（256K、1M；1M 即 1000K），存储为纯数值，回显时写成能够往返的最短形式。空 ID、重复 ID、显式填写的空名称，以及无法读取、非正数或非整数的容量都会在写入前失败。每次写入都携带该卡片打开时的 revision，因此来自另一个标签页或对 settings.yaml 的外部编辑所产生的并发写入会以 settings-conflict 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（settings/changed、credentials/changed、models/changed 与 connection/reset）上重拉，因此外部的 settings.yaml 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。

模型体验

无。该分区渲染浏览器配置 UI；这里没有任何内容进入模型请求。

KV Cache 影响

无；该包既不组装也不发送提供方请求。

已知限制与暂缓事项

• 卡片上可编辑的只有 API 密钥与精选折叠区字段：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（Agent Note）。DeepSeek 公开 baseURL、reasoningEffort 与模型的 id/name/contextWindow/maxTokens；pi-ai 公开 baseURL 与 reasoning。重试策略、超时、DeepSeek 模型说明及其他进阶字段仍留在 settings.yaml 中；编辑器未展示的现有模型字段会予以保留。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 llm-deepseek/llm-pi-ai 这两个 namespace 的名字为键。
• 删除一行会把它已存储的密钥留在 .env 里：删除取消设置的是 settings profile，却刻意不清除那条派生凭据；重新添加该提供方时会发现密钥已配置。显式的密钥移除控件暂缓。
• 未声明的存活路由无处渲染：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。