Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record DeepSeek onboarding credential flow

Browse Source
This commit is contained in:
Yichen Jiang
2026-07-30 12:41:32 +08:00
parent 0b689e0d2c
commit 819a7a6751
9 changed files with 85 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
2026-07-30-deepseek-onboarding-credential-setup.md: e715b3ee9bf4b082f52cf1229b0488799cb2dab6
2026-07-30-deepseek-onboarding-credential-setup.zh.md: 0b81182ab074c2a41cae1290e6e3f2c7e43891fa

31
.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md Normal file
View File

@@ -0,0 +1,31 @@
# Agent Note: official DeepSeek first-run credential setup
Status: implemented
English | [中文](2026-07-30-deepseek-onboarding-credential-setup.zh.md)
## Problem
The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) makes provider settings and credentials live-editable, but a first-time user still lands on the empty conversation Hero without an actionable explanation when the shipped `deepseek-official` route has no credential. The Models page can repair that state, yet requiring the user to discover it weakens onboarding. A prompt must not confuse a missing credential with a missing adapter: the browser can store a value for an existing credential reference, but it cannot dynamically mount the `llm-deepseek` Cordis plugin.
## Decision
**One readiness projection owns both Models and onboarding facts.** `ui-models` keeps a single store that joins `llm.providers({})`, redacted `settings.describe({})`, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry, resolves its `settingsNs` and `settingsPath`, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A configured literal `apiKey` secret sidecar is also ready, so compatibility configuration does not trigger a false prompt; a configured process-environment credential is ready and remains read-only.
**The settings shell contributes navigation state, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and tells registrants whether the current surface is the empty Hero. Its private `openSection(id)` callback opens the settings panel on one registered section. `ui-models` registers the DeepSeek overlay through the same declaration-aware deferred-registration path as its Models section, so plugin load order does not become a contract.
**The prompt is a credential-only write path.** A mounted, active adapter with a resolved, writable, unconfigured reference presents a password input. Submit calls only `credentials.set({ref, value})`, clears the React draft after success, refetches the shared join, and closes only when the new descriptor reports `configured: true`. Business failures and transport rejections keep the dialog open, restore its busy state in `finally`, and redact the submitted value from rendered error text. The prompt never writes `apiKey`, `baseURL`, or a redacted settings section; advanced configuration opens Models instead.
**Unavailable capability states stay honest.** An absent configurable-provider entry suppresses the form because it cannot repair the composition. A present provider whose settings or credential capability cannot be resolved renders an actionable deployment diagnostic. Cancel dismisses the overlay for the current mounted surface and writes no completion fact. Settings, credential, provider-topology, and connection invalidations all refresh the shared join, so an external credential update closes an open prompt without a reload.
## Alternatives considered
**A separate onboarding store and readiness RPC sequence** — rejected because it would create a second client-side interpretation of provider identity, settings paths, secret sidecars, credential references, and invalidation ordering beside the Models page.
**Writing the API key into provider settings** — rejected because a literal secret would enter the settings mutation path and whole-section replacement cannot safely reconstruct redacted values. Credential storage is already the product seam and supplies immediate invalidation.
**Showing the same key form when `llm-deepseek` is absent** — rejected because success would only store an unused environment reference; the browser has no supported operation that mounts the missing Cordis plugin.
## Consequences
The first-run flow now repairs the shipped adapter without restarting: a keyless browser test boots the real Web composition under an isolated harness home, observes the dialog, stores a generated key into that home's `.env`, verifies no key reaches DOM, ARIA, or browser console output, and confirms the running Models page reports configured. Pure readiness and React tests pin literal, file, process-environment, missing-provider, missing-capability, business-error, transport-error, cancellation, and external-invalidation behavior. The flow deliberately inherits the configuration plane's documented base limitations rather than adding local secret storage, redaction, or settings replacement workarounds.

31
.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md Normal file
View File

@@ -0,0 +1,31 @@
# 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})` 联接为同一份状态。首次使用投影选取 `deepseek-official` 可配置提供方条目，解析其 `settingsNs` 与 `settingsPath`，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，也会判定为就绪，兼容配置因此不会误触发浮层；通过进程环境提供的凭据若已配置，同样判定为就绪并保持只读。
**设置外壳只贡献导航状态，不持有提供方策略。**`ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并告知注册方当前界面是否为空白 Hero。其私有 `openSection(id)` 回调会打开设置面板并切换到一个已注册分区。`ui-models` 沿用 Models 分区所使用、感知 slot 声明的延迟注册路径来注册 DeepSeek 浮层，因此插件加载顺序不会成为契约。
**浮层只通过凭据写入路径提交。**适配器已挂载且处于活跃状态，其引用可解析、可写但尚未配置时，界面会显示密码输入框。提交时只调用 `credentials.set({ref, value})`；成功后清空 React 草稿、重新拉取共享联接，并且仅在新描述符报告 `configured: true` 时关闭浮层。业务失败与传输层拒绝都会让对话框保持打开，在 `finally` 中解除忙碌状态，并从渲染的错误文本中脱敏已提交的值。该浮层绝不写入 `apiKey`、`baseURL` 或经过脱敏的设置分节；高级配置会转到 Models。
**能力不可用时如实呈现。**可配置提供方条目缺失时不显示表单，因为它无法修复当前组合。提供方存在，但设置或凭据能力无法解析时，界面会显示可采取操作的部署诊断。取消只会在当前已挂载界面中关闭浮层，不写入任何完成状态。设置、凭据、提供方拓扑和连接失效事件都会刷新共享联接，因此外部凭据更新无需重新加载页面即可关闭已打开的浮层。
## 曾考虑的替代方案
**为首次使用引导单设 store 与就绪状态 RPC 调用序列**：不予采用，因为这会在 Models 页之外，再建立一套客户端解释，用于判定提供方身份、设置路径、secret 槽位的伴随信息、凭据引用及失效事件顺序。
**把 API key 写入提供方设置**：不予采用，因为字面量 secret 会进入设置变更路径，而整个分节替换无法安全重建脱敏值。凭据存储已经是产品 seam，并能立即发出失效事件。
**`llm-deepseek` 缺失时仍显示同一个密钥表单**：不予采用，因为提交成功也只会存储一个无人使用的环境引用；浏览器没有任何受支持的操作可以挂载缺失的 Cordis 插件。
## 后果
首次使用流程无需重启即可修复随产品提供的适配器：无密钥浏览器测试在隔离的 harness 家目录下启动真实 Web 组合，确认对话框出现，把生成的密钥存入该目录的 `.env`，验证密钥未进入 DOM、ARIA 或浏览器控制台输出，并确认运行中的 Models 页报告已配置。纯就绪状态测试与 React 测试固化了字面量凭据、文件凭据、进程环境凭据、提供方缺失、能力缺失、业务错误、传输错误、取消和外部失效行为。该流程直接继承配置平面已记录的基础限制，不会另加局部的机密存储、脱敏或设置替换变通方案。