Yichen Jiang
4.6 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 所有、设置路径为空的 deepseek-official 可配置提供方条目，读取生效的 apiKeyEnv，并检查对应的凭据描述符。同一提供方 ID 下的存活路由若没有匹配的可配置提供方声明，首次使用引导会将其视为适配器缺失。若 apiKey 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发浮层；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
设置外壳只贡献导航状态，不持有提供方策略。ui-settings 声明一个根作用域的 settings.onboarding list slot，并告知注册方当前界面是否为空白 Hero。其私有 openSection(id) 回调会打开设置面板并切换到一个已注册分区。ui-models 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 浮层，因此插件加载顺序不会成为契约。
**浮层只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 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 组合，依照浮层操作前往 Models，通过该页面把生成的密钥存入该目录的 .env，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。完整的无密钥 Web 回放链路还固化了同一提供方 ID 下的不可配置回放路由不会阻塞无关流程。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。