Tianyi Cui
356453d6cb
Adapter schemas now carry only credential references, but the Models join, onboarding readiness, shipped overlays, SDK scaffolding, fixtures, and active decision prose still treated a redacted literal apiKey as a supported compatibility state. That residue made an unsupported field look contractual and pinned Schemastery silent-dropping as behavior. Delete those branches and examples, and let compositions and scaffolds use adapter-owned reference and environment resolution. Do not add a tombstone validator or change generic unknown-key behavior: literal adapter credentials have no migration contract to preserve.
4.8 KiB
Agent Note: DeepSeek 官方首次使用凭据配置
Status: implemented
English | 中文
问题
web 配置平面让提供方设置与凭据可以实时编辑，但首次使用的用户仍会进入空白对话 Hero；当随产品提供的 deepseek-official 路由缺少凭据时，界面没有给出可采取操作的说明。Models 页能修复该状态，但要求用户自行发现这个入口会削弱首次使用引导。界面不得混淆凭据缺失与适配器缺失：浏览器可以为现有凭据引用存入值，但无法动态挂载 llm-deepseek Cordis 插件。
决策
Models 与首次使用引导共享同一个就绪状态投影。ui-models 维护一个 store，把 llm.providers({})、脱敏后的 settings.describe({}) 和批量调用的 credentials.describe({refs}) 联接为同一份状态。首次使用投影选取由 llm-deepseek namespace 与空 settings path 持有的 deepseek-official 可配置提供方条目，读取生效的 apiKeyEnv，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
设置外壳只贡献排序与导航，不持有提供方策略。 ui-settings 声明一个根作用域的 settings.onboarding list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 complete() 和私有 openSection(id) 回调；完成当前步骤后，所有权转交给下一项。ui-models 通过 slots.inject() 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由版本化欢迎决策单独持有。
**首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 Models 分区。该分区已有的 DeepSeek 设置卡片全权负责密码输入框、credentials.set({ref, value})、写入失败处理和写入后刷新；首次使用页面绝不持有或提交 secret。
不可用状态不会占住产品。 可配置提供方条目缺失、路由不活跃、初始联接失败、部署只读或设置／凭据能力无法解析时，都会直接完成而不渲染该步骤，因为首次使用引导无法修复这些状态。Models 页仍是部署诊断与重试界面。「稍后配置」只会完成协调器当前这一次缺少凭据的步骤，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可完成已打开的步骤。
曾考虑的替代方案
为首次使用引导单设 store 与就绪状态 RPC 调用序列：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 槽位的伴随信息、凭据引用及失效事件顺序。
在首次使用引导中增设第二个 API key 编辑器：不予采用，因为 Models 页已为这一状态渲染 DeepSeek 设置卡片。复制其中的 secret 草稿、写入错误处理和已配置状态收敛会增加第二个安全敏感的 UI，却不会带来新的用户能力。
把 API key 写入提供方设置：不予采用，因为字面量 secret 会进入设置变更路径，而整个分节替换无法安全重建脱敏值。凭据存储已经是产品 seam，并能立即发出失效事件。
llm-deepseek 缺失时仍显示浮层：不予采用，因为浏览器导航没有任何受支持的操作可以挂载缺失的 Cordis 插件。
后果
有序流程从产品声明页开始，无需重启即可引导用户前往随产品提供的适配器已有的编辑器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认声明后依照 DeepSeek 页面前往 Models，通过该页面把生成的密钥存入该目录的 .credentials.yaml，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。完整的无密钥 Web 回放也固定了同 id 的不可配置回放路由不会阻塞无关流程。纯就绪状态测试与 React 测试固化了受管文件凭据与进程环境凭据、提供方与能力缺失、导航、取消、外部失效和协调器移交。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。