34 lines
4.9 KiB
Markdown
34 lines
4.9 KiB
Markdown
# Agent Note: DeepSeek 官方首次使用凭据配置
|
||
|
||
Status: implemented
|
||
|
||
[English](2026-07-30-deepseek-onboarding-credential-setup.md) | 中文
|
||
|
||
## 问题
|
||
|
||
[web 配置平面](../architecture/2026-07-30-web-config-plane.md)让提供方设置与凭据可以实时编辑，但首次使用的用户仍会进入空白对话 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 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发页面；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
|
||
|
||
**设置外壳只贡献排序与导航，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-models` 通过 `slots.inject()` 注册 DeepSeek 步骤及其 Models 分区，使每项贡献都跟随自身的声明生命周期，不让插件加载顺序成为契约；独立贡献的对话框也无法堆叠。排在它之前的产品级欢迎步骤由[版本化欢迎决策](2026-07-30-versioned-gui-welcome-onboarding.md)单独持有。
|
||
|
||
**首次使用页面只负责跳转到唯一的凭据编辑器。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示一个操作按钮，用于打开「设置」的 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，通过该页面把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的页面报告已配置。完整的无密钥 Web 回放也固定了同 id 的不可配置回放路由不会阻塞无关流程。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、导航、取消、外部失效和协调器移交行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。
|