[Bug][Web][0.2.0-rc.2] 预览版说明弹窗：确认状态保存失败被压成一句不可行动的「请重试」，且弹窗无法关闭

[zh0122]

现象

dsh 0.2.0-rc.2 / Windows 11 / dsh web（profile web，监听 127.0.0.1）。

每次打开 Web 界面都弹出「预览版说明」模态框，并带一行红色错误：

暂时无法保存确认状态，请重试。

点「继续」无效，刷新无效，重启无效。该模态框无法被关闭（OnboardingModal 屏蔽 Escape、遮罩点击，并把背景置为 inert），因此引导流程被完全卡死，拿不到任何可据以行动的信息。

根因

失败原因在 store 里已经区分好了，但渲染层把它丢掉了。

packages/client/ui-settings-models/src/client/welcome-store.ts 有两个不同的失败来源：

// L93  acknowledge()：写入后回读仍不达标
state.error = 'the acknowledgement did not persist'

// L124 derive()：scope 报 unavailable，即宿主没有暴露该 namespace
state.error = 'welcome acknowledgement settings are unavailable'

而 packages/client/ui-settings-models/src/client/WelcomeNotice.tsx:64 只判断了 null，随后硬编码渲染同一个键：

{state.error === null ? null : <p className={css.error} role="alert">{t('welcomeError')}</p>}

state.error 的值从未被读取。于是两种语义完全相反的失败——结构性的、重试永远不会成功的（宿主没暴露 namespace）和瞬时的、值得再试一次的（写入被拒）——对用户呈现为同一句「请重试」。

进一步说，这两句字符串是机器可读的原因标识，却既没有类型约束也没有被消费；WelcomeNoticeState.error 声明为 string | null，任何拼写漂移都不会被发现。

信息丢失链

宿主其实返回了更细的信号，一路被逐层丢弃：

1. settings-mirror.ts 捕获了宿主的错误消息（response.error.message）→ 存入 mirror.error
2. config-form-types.ts 的 ConfigFormSnapshot 没有 error 字段 → 消息在此丢失，只剩 status: 'unavailable'
3. welcome-store.ts 自己另编两个自由字符串
4. WelcomeNotice.tsx 连 state.error 都不看

第 2 步要动 dsh-client-ui-settings 的公开契约、影响所有设置页，范围过大。但第 3、4 步完全可以在 ui-settings-models 包内闭合，已经足够把「不可行动」变成「可行动」。

复现

最可靠的一条是走 unavailable 分支：让宿主的 settings.describe() 返回不含 ui-settings-general 的 namespace 列表即可。仓库现有测试已经覆盖到这个状态：

packages/client/ui-settings-models/tests/welcome-store.client.spec.ts → reports a missing namespace as an error instead of a silent skip

该用例断言 store 进入 status: 'error'，但没有任何用例断言此时弹窗渲染了什么——渲染层丢弃原因这件事因此不在覆盖范围内。

现场触发条件（我这边的实际情况）：~/.dsh/profiles/web/cordis.patch.yml 自创建起一直是 []，即该确认从未被持久化过。

建议修复

已实现并推到 fork 分支（本仓库 PR 功能已关闭，故只给分支）：

https://github.com/zh0122/deepseek-harness/tree/fix/welcome-notice-error-copy

commit 42c4499aa，8 文件 +56/-15：

• welcome-store.ts：error 由 string | null 收窄为闭合联合 WelcomeNoticeErrorReason | null（'settings-unavailable' | 'not-persisted'）
• WelcomeNotice.tsx：文案映射 { [Reason in WelcomeNoticeErrorReason]: keyof typeof en } 对该联合是全射，因此新增一个原因若没配套文案就无法通过类型检查，不会再退化成静默走通用文案
• locales.ts：en/zh 各两条可行动文案——不可达时明说重试无益并指回 dsh 启动时打印的地址；写入被拒时仍提示可再试
• 补一个渲染层用例，断言不可达场景渲染的是自己那句、且不等于写入被拒那句（防止两条路径再次合并）
• README.md / README.zh.md 同步，并按 docs/i18n 契约重录 README.i18n.yaml 配对哈希

验证：

Test Files  2 passed (2)
     Tests  14 passed (14)

staged oxlint 干净；全包 oxlint 与 git stash 基线逐条对比 81 = 81，findings 完全相同（该包在未 build:lib:host 时本就有 81 条 no-unsafe-* 类型感知告警）；verify-translation-pairing 重录后复检通过。

环境

• dsh 0.2.0-rc.2（npx @deepseek-ai/dsh@latest web）
• Windows 11 Pro for Workstations 10.0.26300
• Node v24.14.0
• profile：web，bundles = dsh-base / dsh-web-app / dsh-plugin@1.4.8 / dsh-better-sidebar@0.16.1

备注

同类问题可能不止这一处：任何把宿主错误压成单句通用文案、又运行在不可关闭容器里的界面，都会产生同样"卡死且无从下手"的效果。若维护者认为值得，可以把「模态不可关闭 ⇒ 错误文案必须可行动」作为一条约定。

[zh0122]

补充验证（比正文里那两条更强）：

1. 整包测试全绿，不只是我改的两个 spec：

pnpm exec vitest run packages/client/ui-settings-models/tests/

 Test Files  11 passed (11)
      Tests  304 passed (304)
   Duration  13.62s

2. 类型检查零增量。 该包在未跑 build:lib:host 时本就有一批既有类型错误（typert 生成的 */remote 子路径契约与 ClientRemote 的补充字段缺失），用 git stash 取上游 master 基线后逐条对比：

tsc -b packages/client/ui-settings-models [--force]

BASELINE errors: 63
MINE     errors: 63
diff: IDENTICAL — my change adds zero type errors

63 条全部落在 operations.ts / store.ts / config-form.ts / settings-mirror.ts / api/remotes/src/client/index.ts，我改的 5 个文件一条都没有。oxlint 同样做过基线对比，81 = 81，findings 完全一致。

也就是说：这个补丁在类型和 lint 两个维度上都不引入新问题；仓库既有的那批错误是缺少生成契约导致的，与本改动无关。

3. 分支：https://github.com/zh0122/deepseek-harness/tree/fix/welcome-notice-error-copy （commit 42c4499aa，基于 639ed0153 = 0.2.0-rc.2）

未能完成的验证：仓库的 typecheck 脚本要求先 build:lib:host 生成契约，我没有跑完整条链，因此没有拿到绝对干净的 tsc 输出——只有上面这个"相对基线零增量"的结论。

[zh0122]

再补一条状态更新，方便维护者取用。

1. 该缺陷在当前 master 上仍然存在。 我核对了 da00f7f5（本文发布时的 master tip）：

packages/client/ui-settings-models/src/client/WelcomeNotice.tsx:64
  {state.error === null ? null : <p className={css.error} role="alert">{t('welcomeError')}</p>}

packages/client/ui-settings-models/src/client/welcome-store.ts:93
  state.error = 'the acknowledgement did not persist'
packages/client/ui-settings-models/src/client/welcome-store.ts:124
  state.error = 'welcome acknowledgement settings are unavailable'

行号与正文里给的完全一致，未被修掉。

2. 分支基线是发布 tag dsh-v0.2.0-rc.2（639ed01539），也就是出问题的那个版本本身。

3. 上游 master 在我 clone 之后前进了 258 个提交，但没有一个动过 packages/client/ui-settings-models/src/。 唯一的重叠在 README，且是不同小节——上游改的是 known-limitations-and-deferred-work/dev-note（删掉一句 Runtime invariant），我改的是 understand-the-implementation/onboarding-coordinator。因此这个补丁可以干净地 cherry-pick 到当前 master。

4. 我确实变基到当前 master 并复跑了全部验证，结论与正文一致：

rebase onto da00f7f535 → 0c9e30f506（无冲突）

vitest run packages/client/ui-settings-models/tests/
  Test Files  11 passed (11)
       Tests  304 passed (304)

oxlint 全包 vs git stash 基线：  81 = 81，findings 逐条相同
tsc -b  vs git stash 基线：  63 = 63，findings 逐条相同
  我改的 5 个文件：0 条
staged oxlint（复刻 pre-commit）：干净
verify-translation-pairing：consistent
git diff --check：clean
diff --stat 与变基前一致：8 files, +56/-15

5. 但变基后的那个提交我推不上去，所以 fork 上的分支仍停在 rc.2 基线（42c4499aa）。原因与权限无关，是 OAuth scope：那 258 个上游提交里有一个改了 .github/workflows/ci-master.yml，推送/服务端同步都会被 GitHub 拒绝：

! [remote rejected] (refusing to allow an OAuth App to create or update
  workflow `.github/workflows/ci-master.yml` without `workflow` scope)

POST /repos/zh0122/deepseek-harness/merge-upstream → HTTP 422，同一句

给 gh 补上 workflow scope 后一条命令即可把分支换成变基版：

gh auth refresh -h github.com -s workflow
git push --force-with-lease fork rebased-onto-current-master:fix/welcome-notice-error-copy

考虑到本仓库 Pull requests 功能已关闭（repos/.../pulls 返回 404，导航栏无 Pull requests 标签，全仓 type:pr 搜索 total_count 为 0），分支停在 rc.2 基线对 cherry-pick 没有影响，故未强求。

[zh0122]

补一条：我把正文末尾那句「同类问题可能不止这一处」实际查了，结论是没有同类需要一起改的，补丁是完整的。把边界记在这里，免得维护者以为我漏查。

判据用正文那条：可区分的失败原因被压成单句通用文案，且运行在不可关闭的容器里。两条都要满足——只满足前一条是 UX 取舍，只满足后一条不构成"卡死"。

先确认容器这一条成立。OnboardingModal.tsx 确实是硬阻塞：

L29-31  const previous = appRoot.inert
        appRoot.inert = true
        return () => { appRoot.inert = previous }
L42     onClose={ignoreImplicitDismiss}

它只有两个使用方，逐个查：

1. WelcomeNotice.tsx —— 就是本条报告的缺陷。 已修。

2. DeepSeekOnboardingDialog.tsx —— 不是同类。 它压根没有错误渲染分支（全文无 role="alert"），内部的 ProviderEditor 自带错误处理。不存在"把原因压成一句"这回事。

然后是容器外那几处，逐个说明为什么不该跟着改：

3. ui-settings-general/src/client/SettingsDocumentAction.tsx:40

{state.error === null ? null : <span className={css.error} role="alert">{t('openDocument.error')}</span>}

形状看着一模一样，但 store 的字段注释写明了这是有意的设计决定：

// settings-document-store.ts:16
/** Last metadata/native-open diagnostic; UI exposes only localized copy. */
error: string | null

宿主原始诊断（result.error.message、mirrored.error）被刻意留在 state 里不呈现，UI 只出本地化文案。而且它是按钮旁边一个小 <span>，用户不会被困住。改它等于推翻一条写明的决定，且没有"卡死"这个危害做理由——不动。

（若维护者认为宿主诊断值得露出，那是独立的 i18n 取舍：宿主消息是英文的，直接渲染会牺牲本地化。ui-agent-preset/src/client/AgentPresetSection.tsx:100 走的就是直接渲染 {state.error} 这条路，两种做法仓库里都有先例。）

4. ui-settings-account/src/client/onboarding-state.ts —— 潜在，非现存。

error 已经是正规联合类型 private error: 'settings' | null（L30），DesktopOnboarding.tsx:114 渲染固定的 t('onboardingSaveFailed')。但联合只有一个成员，所以今天没有任何信息被丢掉。L224 的 error: unavailable || readFailed ? 'settings' : this.error 把两种情况并成同一个原因，等哪天加第二个成员才会显形。提一句备忘，不构成缺陷。

顺带一提，仓库里已有正确写法的先例，我的改法就是照它来的：

// ui-user-questions/src/client/QuestionComposer.tsx:609
{error === null ? null : 'key' in error ? t(error.key) : error.text}

判别联合 + 按键取文案，和本补丁的 { [Reason in WelcomeNoticeErrorReason]: keyof typeof en } 是同一思路，只是我用全射映射类型把"漏配文案"变成编译错误。

结论：不需要扩大改动范围。8 文件 +56/-15 就是全部。

[zh0122]

最后补一块证据缺口：前面所有验证跑的都是源码（vitest 直接吃 .tsx），而实际发布物是 tsdown 产出的 lib/client.js。确认改动能活过真实构建管线：

pnpm --filter @deepseek-ai/dsh-client-ui-settings-models run bundle

[ESM] lib\index.js    1.05 kB
[CJS] lib\client.js  189.09 kB │ gzip: 46.33 kB
✔ Build complete

对产物 lib/client.js 逐项核对：

检查	结果
新 zh 文案「当前浏览器会话读不到这项偏好…」	命中 1
新 zh 文案「确认状态没有保存成功…」	命中 1
新 en 文案 "not reachable from this browser session"	命中 1
新 en 文案 "The acknowledgement was not saved"	命中 1
原因字面量 settings-unavailable	命中 2（store 赋值 + 文案映射键）
原因字面量 not-persisted	命中 2（同上）
新键名 welcomeErrorUnavailable / welcomeErrorNotSaved	各 3（en 字典 / zh 字典 / 映射表）
旧键 welcomeError	0
旧文案「暂时无法保存确认状态」	0

最后两行是重点：用户在界面上实际看到的那句字符串，在构建产物里已经完全不存在；新键名出现 3 次说明「原因 → 文案」的映射没有被打包过程消解掉。

至此四条独立验证全部闭合：源码单测（304 全绿）、lint 与 tsc 相对基线零增量、双语配对一致、构建产物携带新文案且旧文案归零。

唯一的局限仍是正文和第一条评论里说过的那条：仓库 typecheck 脚本要求先 build:lib:host 生成 typert 契约，我没跑完整条链，所以 tsc 只有「相对基线零增量」而不是「绝对零错误」。