@knyazevai/dsh-client-ui-settings-account 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,40 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-settings-account/README.md
+/:
+  en: 13d891a226092817
+  zh: 90bf6ff56dd3c096
+/knyazevai-dsh-client-ui-settings-account:
+  en: 1779d7e0cd54f663
+  zh: 1e8b6e87189a2664
+/knyazevai-dsh-client-ui-settings-account/summary:
+  en: 54da65ea807d7af1
+  zh: 359f85d16724d71d
+/knyazevai-dsh-client-ui-settings-account/table-of-contents:
+  en: c26f81e8adf0128b
+  zh: e11ab371f51f66bc
+/knyazevai-dsh-client-ui-settings-account/use-this-package:
+  en: 45aa7b44d5424d9b
+  zh: 20c7d344c4e9bce0
+/knyazevai-dsh-client-ui-settings-account/use-this-package/desktop-onboarding:
+  en: c1c4db71fd09ca13
+  zh: a40c0a01e9951945
+/knyazevai-dsh-client-ui-settings-account/understand-the-implementation:
+  en: 149d25b949a24036
+  zh: a432400e245bf48b
+/knyazevai-dsh-client-ui-settings-account/further-exploration:
+  en: f5ca95916ef486dc
+  zh: 1e238d8299e0d838
+/knyazevai-dsh-client-ui-settings-account/model-experience:
+  en: ee1df7ca3467ee3f
+  zh: 84904a5148da3862
+/knyazevai-dsh-client-ui-settings-account/model-experience/kv-cache-effect:
+  en: ca3015e252db0114
+  zh: ebca9253cf15e8e9
+/knyazevai-dsh-client-ui-settings-account/known-limitations-and-deferred-work:
+  en: 7afbd3f7afc20bd8
+  zh: f54c57e3d6738c7c
+/knyazevai-dsh-client-ui-settings-account/known-limitations-and-deferred-work/dev-note:
+  en: ebc93259d9f494e2
+  zh: dcc679e43cdbd594

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+---
+description: "Account settings display DeepSeek login state and offer browser authorization and cancellation; the sidebar account menu provides Platform sign-out."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @knyazevai/dsh-client-ui-settings-account
+
+English | [中文](README.zh.md)
+
+Desktop product events use the optional [product analytics service](../product-analytics/README.md); ordinary Web interactions are excluded. Workspace login dialogs emit no authentication events; native welcome owns authentication analytics.
+
+Server-expired account credentials clear the displayed account details and emit a localized sign-in reminder toast once; account snapshot replay does not repeat it.
+
+## Summary
+
+The Account settings section displays DeepSeek login state and offers browser sign-in and cancellation; the sidebar account menu provides Platform sign-out. Desktop users also receive a resumable introduction to account credit and presentation preferences.
+
+The sign-in dialog offers network troubleshooting only for `no-response` failures. HTTP, business, response-validation, storage, and account-stream failures retain the generic retry message.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+
+A new account-model sign-in-required event displays “Model unavailable. Please sign in and try again.” in a toast. The notice is transient: remounting or refreshing does not replay it.
+
+<a id="use-this-package"></a>
+## Use this package
+
+Desktop and plain Web clients both mount the sidebar account launcher, Account settings, the sign-in step of model onboarding, and the account-state subscription. Desktop main opens the authorization page in the system browser. A plain Web client, identified by the absent Desktop preload bridge, sends `login_source` web with its own origin as the callback origin, preopens a tab during the sign-in click, navigates it to the authorization URL with the same `theme` parameter once its attempt receives one, and closes it on failure, expiry, or cancellation; a blocked popup leaves the copy-link route. Embedded Platform pages, Desktop onboarding, and the native device reader stay Desktop-only, so Web Platform links open new tabs.
+
+The sidebar and Account settings display circular profile images with diameters of 24px and 32px respectively. Both observe one browser image load and show the account icon while no URL is available, loading is pending, or loading failed. A rendered image failure updates the shared result, so both surfaces return to the icon and remain eligible for retry; reports from a superseded picture attempt are ignored. Each Settings entry, or return from a Settings or quota-notice top-up page, retries a failed image once even when its URL is unchanged; pending and successful loads are reused, and success updates both surfaces. A changed picture URL starts a new load; account-state replacement, sign-out, and plugin unload discard the previous picture and its callbacks. The collapsed sidebar centers the avatar in a 36 × 36 px button. Before sign-in the sidebar launcher shows a More row instead, leading with the ellipsis glyph.
+
+The section registers through settings.section and uses the account Remote namespace. The stream survives carrier reconnects through the shared Remote supervisor. The page renders feature-owned English and Chinese copy and keeps API keys separate from account state.
+
+Account operations carry this UI's client identity to the Host: build version, active language, and the current UTC offset in seconds sampled as the operation is issued.
+
+Balances use Platform Web currency formatting: two decimal places and digit grouping, positive amounts truncated to cents, positive sub-cent amounts shown as <0.01, and negative amounts rounded with a minimum displayed magnitude of 0.01. Raw Host balance strings remain unchanged.
+
+Desktop usage, top-up, and onboarding recharge actions open one isolated native Platform view below a 48px return bar. The Desktop host owns a single such view, and opening a page destroys the previous one, so the plugin registers one shared host entry in `shell.overlay` and the Account settings page, the account quota notice, and the Desktop onboarding recharge page all request a page through its `PlatformPages` request channel instead of mounting their own container. Each request retires the previous owner before the newer page shows, and its identity-safe release clears only that request, so a stale owner cannot close a page it no longer owns. On Windows Electron the return bar and the native view start below the Desktop caption strip, so the Application and Edit menu text cannot cover the Back to DeepSeek Harness label. Back destroys the view, restores focus before any deferred Modal takes it, and preserves the Account settings page. Leaving a top-up page waits for any read already running and then reads again, because a top-up may have changed what the account holds. The Account settings page and the account quota notice re-read profile, balance, and unnotified bonus; the onboarding recharge return re-reads profile and balance only, so it never triggers the unnotified-bonus read. Superseding a page, releasing a request, plugin unload, and leaving usage all read nothing. Loading failures retain the return action and show a centered localized error with Retry. Retry reloads the same destination; renderer commands never receive the account token.
+
+Chat offers each live quota failure from a bound Session to the frame-wide `shell.quota-notice` chain from its host in `shell.overlay`, so the notice outlives the Chat panel that reported it. The account entry claims `ACCOUNT_QUOTA`: while an account credential is stored and the shared host entry exists, the Modal offers Cancel and Top up. While a page requested through the shared request channel is showing, the native view covers this document, so the entry paints neither the Modal nor the Toast. A quota failure that arrives while a Settings-opened page is already showing is not retained: it stays subject to newest-notice replacement, and the Modal appears after the viewer returns while that notice is still current. That Modal reports the failure of the original request, not the account's current balance: the top-up re-read is a separate read, and returning neither proves a successful payment nor dismisses the notice on its own. The notice's own Top up is the retained case: it calls `keepOpen()` and requests the `top-up` page through the shared request channel, keeping that notice and its page mounted through later quota failures. With the shared host entry the entry waits for the first account snapshot instead of rendering a Toast that its own timer could discard; a snapshot that reports no stored credential, or a failed account stream with no snapshot, then renders the same neutral warning Toast itself, and without that host entry the entry renders that Toast immediately, instead of relying on the chat host fallback. The entry owns the hold and its page request and releases both when it unmounts, so a later quota failure publishes again without replaying the dropped ones; dismissal or sign-out clears the hold and the page request. Close, Cancel, a sign-out, or leaving the notice's own embedded page takes the notice down without retrying the request.
+
+The account menu's Feedback entry opens the Feishu questionnaire in the system browser. Every click samples its context then: the account UID when the profile is ready and carries an id, the build version as harness_version, and device_info. The device_info value includes the physical screen resolution as screen_resolution=widthxheight, after rounding the screen dimensions multiplied by devicePixelRatio; unavailable screen dimensions omit this entry. Each context field also carries hide_*=1, stale prefill values for these fields are dropped from the configured form URL first, including uid, device_info and harness_version regardless of the configured URL. The URL carries no os_version, device_brand, app_locale or separate screen_resolution parameters; configured prefill and hide parameters for these fields are removed. Tokens and masked contact details stay out, and a signed-out, still-loading, or failed profile leaves prefill_uid out. In a plain browser, or when the Desktop bridge has no deviceInfo reader, the form opens with navigator.userAgent. Desktop exposes the optional dshDesktop.deviceInfo reader, whose field format the [Desktop README](../../../apps/desktop/README.md) owns; its answer replaces the user agent, a failed read still opens the form with any available screen resolution in device_info, and device_info describes the reported environment rather than a hardware model. Configure contactFormUrl on the ui-settings-account plugin to select another HTTPS form; contactSource defaults to empty until the questionnaire supports a Harness source option.
+
+Account profile and balance cards share the [settings card material and radius](../../../docs/web-styling.md#corner-radii-and-settings-cards). Usage and top-up links match standard Button geometry; authorization actions use the shared Button.
+
+The sidebar account menu uses the shared Menu surface and backdrop blur. The signed-in menu keeps the shared row typography; the signed-out menu carries its own wider rows. Both menus label the questionnaire entry Feedback. Its Settings row shows the effective key combination supplied by the shell. Closing Settings returns focus to the sidebar account launcher.
+
+The account card’s More account information link has no underline and opens the root of the Host-provided Platform usage URL in the system browser, following `platformOrigin`.
+
+Sign out first queries running account-token tasks and opens a confirmation dialog. The warning describes interruption when such tasks exist; otherwise it explains that data is retained and the account can be signed in again. Cancel, close, and Escape dismiss without signing out. Failed impact queries still open confirmation with an explicit unknown-task warning; failed sign-out keeps the dialog available for retry.
+
+A granted bonus appears as a server-authored notice above the sidebar account launcher without taking focus. The client reads the unnotified bonus when an account becomes active and once per Settings entry; it never polls. The server orders the candidates and owns the copy, so the client stacks every live notice in that order and renders its message verbatim. Only the foreground card is interactive and reports display for acknowledgement. Closing it promotes the next card with a 250ms ease-out position and scale transition, including changes in content height; reduced-motion preferences disable the transition. A server-supplied title replaces the localized bonus title; responses without title retain that default.
+
+The notice waits until Desktop onboarding no longer covers the workspace, including loading, completion saving, and the exit animation, and until model credential onboarding unmounts. Closing the application during onboarding leaves the bonus unacknowledged. In the main interface, the notice is painted as soon as the server offers it, including underneath the translucent settings panel, once the document is visible and the card has passed one presented frame. That painted frame is the whole display signal: the card measures no cover, so a card behind the open overlay counts exactly as any other, and closing the card counts as a display too. Displaying a card queues its acknowledgement, so one mounted card is acknowledged once. A failed acknowledgement retries with a capped backoff for the rest of the signed-in session and never surfaces as an account UI error. A read that fails leaves the visible card and its pending acknowledgement alone, so a transport reconnect keeps retrying. Nothing is written to browser storage. The second signed-in frame of one sign-in and a reconnected stream's replayed state are one session, not a new one, so they keep the card and its retries; signing out, replacing the credential with another account's, or unloading the plugin discards them. Identity-only updates do not reach the account UI stream. Every signed-in frame reads again, and a newer read supersedes one still in flight, so a credential swapped in place is named by a fresh read rather than inheriting the replaced account's; the batch's account id then drops the previous account's card and queue even with no intervening signed-out state. The next sign-in displays whatever the server still offers, including an order an earlier sign-in acknowledged, and a card the user has already seen stays up until it is closed, even when a later read returns no bonus.
+
+<a id="desktop-onboarding"></a>
+### Desktop onboarding
+
+The Desktop preload marker enables the introduction after account credentials are stored. Progress belongs to the local Host settings document, not the Platform account: unfinished steps resume after restart, and completing or skipping the flow prevents another run on that installation. Browser clients do not mount it. API-key presence comes from the native welcome backend through the boolean-only Desktop preload bridge, using the same credential discovery as login. A signed-out installation with a configured model API key bypasses the pages and applies standard process, detailed usage, and enabled Coding Tools.
+
+The welcome page requires Get started. The credit page always appears. A positive balance confirmed at first entry selects Continue as the primary action and Add credits as the secondary action. This choice stays fixed until the onboarding controller is recreated and is never persisted; late balance results cannot change the buttons. Only a confirmed absence of positive credit adds a confirmation before continuing without recharge; pending or failed queries do not block continuing. Purpose descriptions remain unchanged when selected. Returning from the native top-up view keeps the credit page and re-reads profile and balance in the background after any read already running, whether loading or payment succeeded. That read does not recompute the funded-mode choice, so a completed recharge leaves the buttons as first entered while continuing still evaluates the refreshed balance. Next confirms only a known zero balance; Skip uses the credit warning on the credit page and the setup warning on the question pages. Office-only use completes with compact presentation; development or both purposes also ask for process detail. Back preserves selections, and explicit skip from any supported step applies standard process, compact performance/usage, and disabled Coding Tools. This flow creates no workspace or demonstration task.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The Account section appears first in Settings only while signed in; it is hidden before account state loads and after sign-out. The plugin owns one Host snapshot stream shared through framework hooks by settings.section and settings.launcher. The launcher opens Settings and offers Sign out only while an account credential is stored. Platform failures leave the menu available for retry. It maintains no independent credential state.
+
+The desktop controller writes progress to `ui-settings-account` through Host settings. Completion first applies `ui-chat.transcriptView` and `ui-chat.performanceUsage` together, then calls the shared Coding Tools preference to persist `ui-settings.enabled`, and finally saves the done marker; a rejected write keeps the flow available for retry. Successful completion reveals the workspace through a 180ms fade; choices and ordinary navigation preview immediately while writes run in order. A failed final queued write restores saved progress and allows retry. Completion waits for queued choices and retains the page until preferences persist; reduced motion skips the fade. Onboarding choices compact, standard, and detailed apply directly to the corresponding Chat work-detail modes. API-key entry and explicit skip select standard; onboarding does not select verbose. Complete Figma illustration layers are bundled as transparent, lossless 3× WebP assets; welcome layers are merged with local sidebar blur; recharge uses a 70% opaque foreground window with local blur of the covered illustration, and headings use the bundled Montserrat brand font; English headings and descriptions use Light (300), except the DeepSeek Harness brand within headings uses Medium (500); card titles retain Regular (400) when selected. English footer navigation uses Light (300). Confirmed onboarding sets a 960px minimum window width and enlarges narrower windows; completion releases the minimum without restoring the previous size. Loading or already-completed onboarding does not resize the window. Empty footer navigation space passes pointer events through to the primary action. Cards exclude native window dragging and own the keyboard focus outline for their checkbox. The account package owns its onboarding overlay and control geometry. Each step and the confirmation dialog has a separate component; the flow coordinates navigation, transitions, and recharge. The overlay hides the workspace while initial account and progress state loads. Question headings and cards follow the Figma positions at 1440 × 920 and 960 × 600, independently of their action buttons. On macOS, content clears the body portal’s inherited no-drag region and a first-child drag band leaves an 8px native resize margin; interactive controls and later dialogs exclude their regions, and a native Platform page disables the underlying onboarding band. The upper workspace popup illustration has an opaque background in both languages and themes; the underlying sidebar omits its selected-row highlight. Welcome keeps its illustration at its original size, repositions and clips the artwork in narrow windows, and reveals the complete illustration on wide windows. The [historical onboarding decision](../../../.agents/notes/archived/feature/2026-09-16-desktop-onboarding.md) owns persistence and presentation trade-offs.
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+The [credentials subsystem](../../../docs/subsystems/credentials.md) owns storage APIs; the [architecture](../../../docs/architecture.md) explains application composition.
+
+Account login uses a dismissible dialog before the model onboarding credential editor. The dialog uses a compact, right-aligned action row with the primary action last. The sidebar displays the profile name, falling back to the server-masked phone number or email when the name is absent; it stays blank while the profile is loading. Dialog copy and the sidebar account label are not text-selectable; the copy-link button remains available and restores its label two seconds after each successful copy. Clipboard failures show Copy failed on the link for two seconds without interrupting sign-in. Waiting shows a copyable authorization link and a loading indicator; timeout and failure require an explicit retry. The dialog's Copy sign-in link and the Settings Open link append the resolved application palette as `theme=light` or `theme=dark` from the live theme snapshot, so both routes reach the Platform page in the current application theme without changing the theme preference Platform has saved. Sign-in failures render in that dialog; a failed sign-out keeps the menu open so the user can try again, and the launcher shows no failure of its own. Closing a waiting dialog cancels its Host attempt. The sidebar can reopen the same API-key editor through the settings coordinator.
+
+A terminal account-state stream failure appears in the sign-in dialog or Account settings. Plugin unload suppresses late failure reports.
+
+The balance card shows recharge funds and bonus credit in separate rows. While signed in, the bonus row appears during loading, after a failed wallet read, and when a wallet holds positive bonus credit; a successful read without positive bonus credit omits the row. A failed wallet read shows the existing unavailable copy as a link to Platform — the same destination and behavior as the Usage action, so the embedded page opens on Desktop and a new tab elsewhere — while the loading state stays plain text. Currencies retain their own amounts, and a notice date is rendered only inside the server’s own message.
+
+
+A successful login selects the first available `deepseek-account` model as the default when no other provider has a configured API key, even if a previous default was saved. Configured keys preserve the existing default even when their provider has no available models. Session-specific selections remain unchanged.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as account credentials affect HTTP authentication and never enter model prompts, Session logs, or tool results.
+
+#### KV Cache effect
+
+No model request prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Profile and recharge-wallet balances use the existing Platform Web endpoints through Host getProfile / getBalance. The page refreshes when opened and after login or reconnect, preserves server-masked contact data, and shows query failures independently without manufacturing a zero balance. Usage and top-up use Host-provided links derived from platformOrigin and the browser’s own login; the links never carry a DSH token.
+- Completed installations do not reapply defaults or overwrite later user preferences. Completion does not synchronize across devices or create a per-account history.
+- Onboarding follows the interface locale and theme, with four Figma illustration sets covering Chinese and English in light and dark appearance. Export canvases include the full illustration geometry; Finder artwork uses the same vertical fade in both themes.
+
+- The notice copy is server-localized for the UI language in effect when the client reads it. Switching language does not itself re-read the unnotified bonus, so a notice already on screen keeps the copy the server sent for the earlier language until the user refreshes or the account lifecycle restarts.
+
+- Web sign-in needs a loopback HTTP page origin (`localhost`, `127.0.0.1`, or `[::1]`), because the Host accepts only those callback origins. A Web UI reached through `--trusted-host` or an HTTPS reverse proxy still shows the entry, but starting sign-in fails with the generic retry state; such deployments add an API key instead.
+
+- The Platform view’s dialog marks every other document child inert, including the Desktop-owned caption menu host, so the Application and Edit menu stays visible but cannot be operated until the view closes. Exempting that host needs an inertness contract owned by the Desktop.
+
+<a id="dev-note"></a>
+### Dev Note
+
+The [desktop login decision](../../../.agents/notes/implemented/architecture/2026-09-14-deepseek-account-login.md) records cancellation and storage ownership.
+
+Usage and top-up show a centered 24px loading indicator without visible loading text until the native document loads; the return action remains available. The loading SVG is embedded locally from Figma node 2957:72553.
+
+Default-model initialization runs after publishing and accepting the sign-in frame, without delaying subsequent account frames. Failures are recorded with `console.error` in the renderer Console and do not mark the signed-in account as failed. Profile and balance reads also report only failures, without account data or raw exceptions; successful refreshes and account frames are silent.
+
+Read-only onboarding settings and a failed initial account stream leave the workspace accessible. A failed initial settings read exposes Retry, which reissues the shared settings read. Overlapping onboarding and Platform overlays release background interaction only after their last owner unmounts.

package/README.zh.md

@@ -0,0 +1,119 @@
+---
+description: "设置中的账号页面显示 DeepSeek 登录状态，并提供浏览器授权和取消；侧边栏账号菜单提供 Platform 退出登录。"
+kind: "package-reference"
+---
+
+# @knyazevai/dsh-client-ui-settings-account
+
+[English](README.md) | 中文
+
+桌面端产品事件使用可选的[产品埋点服务](../product-analytics/README.zh.md)，不包含普通 Web 交互。工作区内的登录弹窗不发送认证事件；认证埋点由原生欢迎页负责。
+
+账号凭据被服务端判定失效后，清空显示的账号详情，并弹出一次本地化的重新登录提示 toast；账号快照重放不会重复提示。
+
+## 概述
+
+设置中的账号页面显示 DeepSeek 登录状态，并提供浏览器登录和取消；侧边栏账号菜单提供 Platform 退出登录。Desktop 用户还会进入可恢复的引导，了解账号额度并选择展示偏好。
+
+登录弹窗仅对 `no-response` 失败提示检查网络。HTTP、业务、响应校验、存储和账号状态流失败仍显示通用重试提示。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+
+新的账号模型登录要求事件会弹出“当前模型暂不可用，请登录后再试”提示。提示仅保留在当前界面，重新挂载或刷新不会重放。
+
+<a id="use-this-package"></a>
+## 使用此包
+
+Desktop 与普通 Web 客户端都挂载侧边栏账号菜单、账号设置、模型引导中的登录步骤，并订阅账号状态。Desktop 主进程在系统浏览器中打开授权页面。普通 Web 客户端（以缺少 Desktop preload 桥接识别）以 `login_source` web 发起登录，并以自身 origin 作为回调 origin；它在点击登录时预先打开一个标签页，本次尝试获得授权 URL 后带上相同的 `theme` 参数导航该标签页，并在失败、过期或取消时关闭它；弹窗被拦截时仍可使用复制链接。内嵌 Platform 页面、Desktop 引导和原生设备信息读取器仅在 Desktop 中提供，因此 Web 中的 Platform 链接在新标签页打开。
+
+侧边栏和账号设置以正圆图片显示账号头像，直径分别为 24px 和 32px。两处共享一次浏览器图片加载，URL 缺失、加载中或加载失败时使用账号图标兜底。渲染图片失败时更新共享结果，两处一起恢复为图标，并保留重试机会；已被替换的图片加载尝试上报的失败会被忽略。每次进入设置，或从设置及余额不足提示打开的充值页面返回时，都会重试一次失败的图片，即使 URL 未变化；加载中和已成功的图片会复用，成功后两处一起展示。头像 URL 变化时开始新加载；账号状态替换、退出登录和插件卸载会丢弃旧头像及其回调。折叠侧边栏将头像居中放置在 36 × 36 px 的按钮内。登录前侧边栏入口改为「更多」行，以三点图标开头。
+
+该页面通过 settings.section 注册，并使用 account Remote 命名空间。共享 Remote 管理器负责连接恢复后的流重连。页面使用功能自有的中英文文案，将 API Key 与账号状态分开。
+
+账号操作会把本界面的客户端身份传给 Host：构建版本、当前语言，以及发起操作时采样的当前 UTC 偏移（秒）。
+
+余额沿用 Platform Web 的金额格式：两位小数和千分位分组，正金额截断至分，小于一分的正金额显示为 <0.01，负金额按舍入规则处理且显示绝对值至少为 0.01。Host 返回的原始余额字符串保持不变。
+
+Desktop 的用量、充值与引导充值操作在 48px 返回栏下方打开同一个隔离的原生 Platform 视图。Desktop 宿主只有一个这样的视图，打开新页面会销毁上一个，因此插件在 `shell.overlay` 注册一个共享宿主条目，Account 设置页、账号欠费提示与 Desktop 引导充值页都通过其 `PlatformPages` 请求通道申请页面，而不再各自挂载容器。新请求会在新页面显示前退掉上一个持有者，其身份安全的释放只清除本次请求，因此过期的持有者无法关闭它已不再持有的页面。在 Windows Electron 中，返回栏与原生视图都从 Desktop 顶栏下方开始，Application 和 Edit 菜单文字不会盖住“返回 DeepSeek Harness”。返回操作销毁视图并保留 Account 设置页，且先恢复焦点，再由任何被延后的 Modal 接管。从充值页返回时会等待任何已在进行的读取结束后再读取，因为充值可能改变账号持有的内容。Account 设置页与账号欠费提示会重读资料、余额与未通知赠金；引导充值返回则只重读资料与余额，因此不会触发未通知赠金的读取。替换页面、释放请求、插件卸载与从用量页返回均不读取。加载失败时保留返回操作，居中显示本地化错误提示和“重试”按钮。重试重新加载同一目标页面；渲染进程命令不接收账号 token。
+
+Chat 通过 `shell.overlay` 中的宿主把已绑定 Session 的实时欠费交给全局 `shell.quota-notice` 链，提示的生命周期因此长于上报它的 Chat 面板。账号条目认领 `ACCOUNT_QUOTA`：已存储账号凭证且存在共享宿主条目时，Modal 提供取消和去充值。只要通过该共享请求通道请求的页面正在显示，原生视图就会盖住本页，因此该条目既不绘制 Modal 也不绘制 Toast。在 Account 设置页已打开页面的情况下新到达的欠费不会被保持：它仍受最新提示替换规则约束，返回后若该提示仍是最新一条就显示 Modal。该 Modal 报告的是原始请求的失败，而不是账号当前余额：返回时的重读是一次独立读取，返回本身既不证明支付成功，也不会自动撤下该提示。提示自身的去充值属于被保持的情形：它调用 `keepOpen()` 并通过共享请求通道申请 `top-up` 页面，使该提示与其页面在后续欠费期间保持挂载。存在共享宿主条目时，该条目会等待首个账号快照，而不是渲染一个可能被自身计时器丢弃的 Toast；快照报告未存储凭证，或账号流失败且无快照时，才由该条目自行渲染同一段中立警告 Toast，缺少该宿主条目时则立即渲染该 Toast，而不依赖 Chat 宿主回退。该条目持有保持与页面请求，并在自身卸载时释放二者，因此后续欠费会重新发布而不重放已丢弃的提示；关闭与退出登录也会清除保持和页面请求。关闭、取消、退出登录或离开该提示自己的内嵌页面都会撤下提示，且不会重试请求。
+
+账号菜单的“意见反馈”入口在系统浏览器中打开飞书问卷。每次点击都按当时的上下文取值：profile ready 且带 id 时的账号 UID、以 harness_version 表示的构建版本，以及 device_info。device_info 以 screen_resolution=宽x高 包含屏幕物理分辨率，尺寸乘以 devicePixelRatio 后四舍五入；屏幕尺寸不可用时省略此项。所有上下文字段同时设置 hide_*=1，配置的表单 URL 中这些字段的 stale prefill 参数先被清除，uid、device_info 与 harness_version 的隐藏参数不依赖配置 URL 的取值。URL 不携带 os_version、device_brand、app_locale 或独立的 screen_resolution 参数；配置 URL 中这些字段的 prefill 与 hide 参数会被移除。不传 token 或脱敏联系方式；未登录、profile 仍在加载或读取失败时都不填写 prefill_uid。普通浏览器中，或 Desktop 桥接没有 deviceInfo 读取器时，打开的表单以 navigator.userAgent 作为 device_info。Desktop 端暴露可选的 dshDesktop.deviceInfo 读取器，其字段格式由 [Desktop README](../../../apps/desktop/README.zh.md) 负责；该读取器的结果取代 user-agent，读取失败时仍打开表单，device_info 保留可获取的屏幕分辨率，而 device_info 描述的是上报的环境而非硬件型号。可在 ui-settings-account 插件配置 contactFormUrl，切换到另一个 HTTPS 问卷；问卷支持 Harness 来源选项前，contactSource 默认为空。
+
+账号资料与余额卡片共用[设置卡片材质与圆角](../../../docs/web-styling.zh.md#corner-radii-and-settings-cards)。用量与充值链接与标准 Button 尺寸一致；授权操作使用公共 Button。
+
+侧边栏账号菜单使用公共 Menu 的表面和背景模糊。已登录菜单沿用公共菜单项排版；未登录菜单使用自己的较宽菜单项。两种菜单的问卷入口均为“意见反馈”。设置菜单项显示外壳传入的有效组合键。关闭设置后，焦点回到侧栏账号入口。
+
+账号卡片的“更多账号信息”链接不带下划线，通过系统浏览器打开 Host 提供的 Platform 用量 URL 的根路径，遵循 `platformOrigin` 配置。
+
+退出登录先查询正在使用账号 token 的任务，再打开确认弹窗。有此类任务时提示执行将被打断，否则提示数据保留且可重新登录。取消、关闭和 Escape 均不退登。影响查询失败仍打开确认弹窗，并明确提示无法确认任务状态；退登失败保留弹窗以便重试。
+
+赠金到账时，侧栏账号入口上方显示一条由服务端提供文案的通知，不抢占焦点。客户端仅在账号进入登录态时、以及每次进入设置页时读取一次未通知赠金，不做轮询。候选顺序与文案均由服务端决定，客户端按该顺序层叠展示全部未过期通知并原样渲染消息。只有最前面的卡片可交互，并在实际展示后触发确认。关闭前卡后，下一张卡片通过 250ms ease-out 的位置与缩放过渡（包括内容高度变化）进入前台；偏好减少动态效果时禁用过渡。服务端提供的 title 替换本地化赠金标题；未返回 title 时沿用默认标题。
+
+通知等待 Desktop 引导界面不再遮盖主界面且模型凭证引导卸载后才展示，Desktop 引导的等待范围包括加载、完成时的保存和退出动画。在引导期间关闭应用不会确认赠金通知。进入主界面后，服务端返回即绘制通知，包括在设置面板的半透明蒙层之下；同时要求文档可见且卡片已完成一帧绘制。这一帧绘制就是全部的展示信号：卡片不检测遮挡，因此处于打开蒙层之下的卡片与其他情形同样计数，用户关闭卡片同样计入展示。卡片展示后即排队确认，因此同一张挂载的卡只确认一次。确认失败会在本次登录会话内按带上限的退避重试，且不会在账号界面报错。读取失败不会影响已展示的卡片及其待确认队列，因此连接重连后仍会继续重试。不写入浏览器存储。同一次登录的第二个登录态帧以及重连后重放的登录态属于同一会话而非新会话，因此保留卡片与重试；只有退出登录、凭证被换成另一账号，或卸载插件才会丢弃。仅身份信息更新不会进入账号界面订阅流。每个登录态帧都会重新读取，且新的读取会取代仍在进行中的旧读取，因此就地更换的凭证会由一次全新的读取来识别，而不会沿用被替换账号的读取结果；读取结果中的账号 ID 随后会丢弃上一个账号的卡片与队列，即使没有中间的退出登录状态。下一次登录会展示服务端仍然下发的内容，包括上一次登录已确认过的订单；用户已看到的卡片会保留到关闭为止，即使之后的读取没有返回赠金。
+
+<a id="desktop-onboarding"></a>
+### Desktop 引导
+
+Desktop preload 标记在账号凭证已存储后启用引导。进度属于本地 Host 设置文档，不属于 Platform 账号：重启后恢复未完成的步骤，完成或跳过后不再于当前安装中重复运行。浏览器客户端不挂载此流程。API Key 是否存在由原生欢迎后端通过仅返回布尔值的 Desktop preload 桥接提供，与登录共用凭证发现逻辑。未登录但已配置模型 API Key 的安装会绕过这些页面，应用标准过程、详细用量和开启代码工作工具的配置。
+
+欢迎页必须点击“开始设置”。额度页始终展示。首次进入时若已确认有正余额，则主操作为“继续”，次操作为“去充值”。该选择在引导控制器重建前保持固定且不持久化，后到的余额结果不会改变按钮。仅在确认不存在正余额时，继续而不充值才需确认；查询中或失败时不阻止继续。用途卡片选中后描述不变。从原生充值视图返回后保留额度页，并在等待任何已在进行的读取结束后于后台重读资料与余额，不受页面加载或支付结果影响。该读取不会重新计算该选择，因此充值成功后按钮仍保持首次进入时的状态，而继续前行仍按刷新后的余额判断。“下一步”仅在确认零余额时提示；额度页的“跳过”使用充值提示，答题页使用设置提示。仅选办公用途时以简洁展示完成；选择开发或两种用途时还会询问过程详情。上一步保留已有选择，任意可跳过步骤均采用标准工作过程、简洁性能与用量以及关闭代码工作工具的默认值。此流程不创建工作区或示例任务。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+仅登录后在设置导航首位显示账号页；账号状态加载完成前以及退出登录后隐藏该页。 插件持有一条 Host 快照流，通过框架 hook 供 settings.section 和 settings.launcher 共享。入口菜单可打开设置，并仅在已存储账号凭证时提供退出登录。Platform 请求失败时保留菜单，以供重试。插件不维护独立凭证状态。
+
+桌面控制器通过 Host 设置将进度写入 `ui-settings-account`。完成时先一并应用 `ui-chat.transcriptView` 与 `ui-chat.performanceUsage`，再通过共享代码工作工具偏好保存 `ui-settings.enabled`，最后保存完成标记；写入被拒绝时保留引导以供重试。成功完成后通过 180ms 淡出显露工作区；选择和普通翻页立即预览，写入在后台按顺序执行。队列最后一次写入失败时恢复已保存进度，并允许重试。完成操作会等待选择队列及偏好保存成功，再关闭页面；减少动态效果偏好会跳过淡出。onboarding 选项 compact、standard、detailed 直接应用到对应的 Chat 工作过程模式。API Key 进入与显式跳过均采用 standard；onboarding 不选择 verbose。完整 Figma 示意图层以透明、无损编码的 3× WebP 资源打包；欢迎页图层合并并烘焙侧栏局部模糊；充值页前景窗口不透明度为 70%，仅烘焙其覆盖插图区域的模糊，标题使用已打包的 Montserrat 品牌字体，英文标题和描述使用 Light（300），标题中的 DeepSeek Harness 使用 Medium（500）；卡片标题选中前后均使用 Regular（400）。英文底部导航使用 Light（300）。确认进入引导后，窗口最小宽度设为 960px，较窄窗口自动放大；完成后解除宽度限制，但不恢复原尺寸。加载中或已完成引导的启动不改变窗口尺寸。底部导航空白区域透过鼠标事件，避免遮挡主操作。卡片区域不参与原生窗口拖动，复选框的键盘焦点仅在卡片外框展示。账号包负责引导覆盖层和控件尺寸样式。每个步骤和确认弹窗各有独立组件，流程组件协调导航、切换动画和充值。初始账号与进度加载期间，覆盖层隐藏工作区。答题标题和卡片独立于操作按钮，位置对齐 Figma 的 1440 × 920 和 960 × 600 断点。macOS 的内容层清除 body 浮层继承的 no-drag，位于内容之前的拖拽层保留 8px 原生缩放边缘；交互控件和后续弹窗排除自身区域；原生平台页面打开时禁用底层引导拖拽层。上方工作区弹窗插画在两种语言和主题下均使用不透明背景，下层侧边栏不绘制选中行高亮。欢迎页保持示意图的原始尺寸，在窄窗口内调整插图位置并裁切，在宽窗口内展示完整插图。[历史引导决策](../../../.agents/notes/archived/feature/2026-09-16-desktop-onboarding.md)记录持久化与展示方面的取舍。
+
+<a id="further-exploration"></a>
+## 深入探索
+
+[凭证子系统](../../../docs/subsystems/credentials.zh.md)定义存储接口；[架构](../../../docs/architecture.zh.md)说明应用组合。
+
+账号登录在模型引导的凭证编辑器之前显示可关闭的弹窗。弹窗底部采用紧凑的右对齐横排操作，主操作位于末尾。侧边栏优先显示昵称，缺少昵称时显示服务端返回的脱敏手机号或邮箱；资料加载期间保持留空。 弹窗文字和侧边栏账号状态文字不可选中，复制登录链接按钮始终可用，并在每次复制成功两秒后恢复原文案。剪贴板失败时，链接原位显示“复制失败”两秒，不中断登录。等待状态提供可复制的授权链接和加载图标；超时和失败均须用户手动重试。弹窗的“复制登录链接”和设置页的“打开”链接会从当前主题快照读取应用生效配色，追加 `theme=light` 或 `theme=dark`，使两条路径都以当前应用主题打开 Platform 页面，且不改变 Platform 已保存的主题偏好。登录失败在该弹窗内呈现；退出登录失败时菜单保持展开以便重试，入口本身不展示失败提示。关闭等待弹窗会取消对应 Host 登录流程。侧边栏通过设置协调器重新打开同一个 API Key 编辑器。
+
+账户状态流的终止错误会显示在登录对话框或账户设置中。插件卸载后不再报告延迟到达的错误。
+
+余额卡片分行展示充值余额与赠金余额。登录态下，赠金行在加载中、余额读取失败以及存在正额赠金时显示；读取成功但没有正额赠金时不显示该行。余额或赠金读取失败时，沿用既有的不可用文案并改为指向 Platform 的链接，目标与行为同“查询用量”一致：Desktop 打开内嵌页面，其它环境新开标签页；加载中仍为纯文本。不同币种分别显示；日期只在服务端自己的消息中出现。
+
+
+登录成功时，若其他提供方均未配置 API key，则将 `deepseek-account` 的第一个可用模型设为默认值，即使此前保存过默认选择。其他提供方只要配置了 key，就保留原默认值，即使其没有可用模型。会话内的显式选择保持不变。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为账号凭证只影响 HTTP 认证，不进入模型提示、Session 日志或工具结果。
+
+#### KV Cache effect
+
+不改变模型请求前缀。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 资料和充值钱包余额通过 Host getProfile / getBalance 复用已有 Platform Web 接口。页面在打开、登录及重连后刷新，原样显示服务端脱敏后的联系方式，并分别处理查询失败，不将失败显示为零余额。用量和充值使用 Host 按 platformOrigin 派生的链接，并沿用浏览器自身登录态，不携带 DSH token。
+- 已完成引导的安装不会重新应用默认值或覆盖用户后续调整的偏好。完成状态不跨设备同步，也不创建逐账号历史。
+- 引导跟随界面语言和主题，使用中文、英文分别搭配浅色、深色外观的四套 Figma 插图。导出画布包含完整插图范围，Finder 插图在两种主题下使用一致的纵向渐变。
+
+- 通知文案按客户端读取时的界面语言由服务端本地化。切换语言本身不会重新读取未通知赠金，因此已在屏幕上的通知会沿用服务端先前语言下发的文案，直到用户手动刷新或登录生命周期重新开始。
+
+- Web 登录要求页面 origin 为回环 HTTP（`localhost`、`127.0.0.1` 或 `[::1]`），因为 Host 只接受这些回调 origin。经 `--trusted-host` 或 HTTPS 反向代理访问的 Web UI 仍显示登录入口，但发起登录会进入通用的失败重试状态；这类部署应改为添加 API Key。
+
+- Platform 视图的弹窗会把文档内其它子节点设为 inert，其中包括 Desktop 拥有的顶栏菜单 host，因此 Application 和 Edit 菜单保持可见，但在视图关闭前无法操作。放行该 host 需要 Desktop 侧提供 inert 契约。
+
+<a id="dev-note"></a>
+### 开发备注
+
+[桌面登录决策](../../../.agents/notes/implemented/architecture/2026-09-14-deepseek-account-login.zh.md)记录取消和存储的职责。
+
+用量和充值在原生页面加载完成前显示居中的 24px 加载图标，不显示加载文字；返回操作始终可用。加载 SVG 从 Figma 节点 2957:72553 内嵌到本地样式。
+
+默认模型初始化在登录帧发布并确认接收后运行，不延迟后续账号帧。初始化失败通过 `console.error` 记录在渲染进程 Console 中，不会将已登录账号标记为失败。资料和余额读取也仅在失败时记录日志，不包含账号数据或原始异常；成功刷新和账号状态帧不输出日志。
+
+引导设置只读或初始账号流失败时，工作区保持可访问。首次设置读取失败会显示重试入口，重新发起共享设置读取。引导与 Platform 覆盖层重叠时，最后一个持有者卸载后才恢复背景交互。