[REQ-085] Home 在正式路由中可靠创建 Session

[jinjunnn]

简明目的

首页要像正常页面一样工作：状态说清楚、首条消息失败不丢内容，也不再靠 Portal 盖住旧首页。

Outcome（专业定义）

AlphaHome 作为正式 Home leaf surface 被 route composition 唯一挂载，使用显式项目/sidecar/composer contract 创建 Session 和提交首条 prompt；加载、离线、错误、重试与无障碍状态可观察且 fail honest。Portal takeover 已完成移除，剩余交付聚焦生产行为与证据。

Complexity

M — 涉及 UI 状态机、Session 创建幂等、route wiring 与无障碍，但边界位于单一产品 surface。

Context

Portal → typed surface 的结构转换基本完成；尚缺首条消息失败恢复、不同 readiness/error 状态、错误脱敏、导航契约和完整 a11y。旧正文仍要求一个发布周期的 legacy 回退，当前没有既有用户，不再需要。

Scope

• 通过 [REQ-084] Alpha 页面通过窄 typed surface 接入路由 #199 typed Home surface 唯一挂载 AlphaHome。
• 明确项目加载、空状态、离线、sidecar 未就绪、配置损坏与渲染错误。
• 让 Session 创建与首条 prompt 提交可重试、去重且不丢输入。
• 使用 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204 的 canonical route helper 导航，不拼接路径。
• 完成键盘、读屏、焦点、窄宽和明暗主题的产品基线。

Non-goals

• 不实现 Draft 或 Session Workspace；见 [REQ-086] Draft 在正式路由中可恢复地晋升为 Session #201/[REQ-088] Alpha Session Shell 稳定挂载并管理生命周期 #203。
• 不定义完整 route table；见 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204。
• 不保留 legacy Home、Portal、隐藏 anchor、DOM observer 或发布回退开关。
• 不重新设计 AlphaComposer 协议或新增视觉体系。

Acceptance criteria

AC1. / 在 Alpha 产品中只挂载一个 Home root，不存在 Portal、隐藏 upstream Home 或重复交互层。
AC2. 项目加载失败、配置文件损坏、引擎连不上、页面区域崩溃这四种情况各有一条可操作(可重试/可打开配置/可恢复)的提示,且提示文字互不混用。 (2026-09-17 按 owner 裁决改写,原文见编辑历史)
AC3. 首条消息失败时输入和选择保持可恢复；重试或重复点击不会意外创建重复 Session 或重复 prompt。
AC4. 成功后只通过 canonical route helper 导航到正确 Session，back/forward、reload 与 deep link 返回 Home 行为一致。
AC5. 错误 UI 不泄漏 token、认证头、未脱敏绝对路径或 provider secret。
AC6. composer、autocomplete 和主要动作具备正确读屏名称、焦点顺序、键盘操作与 IME 行为(工作区选择器的读屏语义已按裁决移出本需求)。 (2026-09-17 按 owner 裁决改写,原文见编辑历史)
AC7. Portal/隐藏 CSS/observer 等 takeover 资产被删除，结构性 takeover ratchet 不回升。

Evidence map

AC	Evidence surface
AC1	#263 + packages/ui-mac/src/renderer/route-composition.test.ts:28
AC2	AlphaHome.tsx:120-134 两条横幅 + packages/app/src/app.tsx:525 ConnectionGate + surface-boundary.tsx:12-23
AC3	#259 test-component/alpha-composer-model.cases.ts:981
AC4	shared/route-manifest.test.ts:155/:256(route-composition.test.ts:40-54 不驱动路由器,owner 2026-09-17 裁决接受);#264 已关
AC5	#261 alpha-ui/boundary-error-text.ts
AC6	#477 composer-autocomplete.tsx:627/:643 + alpha-composer.tsx:697;#262 已关
AC7	#263(已关)

Acceptance owner

@jinjunnn — 按 AC 逐条验收并手工关闭；PR 不得关闭父需求。

设计要点

• Session admission 与首条 prompt delivery 分开建模，防止“Session 已建但 UI 报失败”导致重复提交。
• readiness 状态来自正式 adapter，不读取或点击隐藏 DOM。
• 页面错误边界按区域恢复，保留用户尚未发送的输入。
• 导航字符串由 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204 集中生成。

潜在问题与风险

• 首条消息失败可能造成 false success、重复 Session 或输入丢失。
• 把 offline、loading 和 sidecar-not-ready 混成一个 spinner 会让用户无法判断下一步。
• 错误对象直接渲染可能泄漏路径或凭据。
• 结构完成但生产入口仍挂旧页面时会出现“测试通过、产品未生效”。

过时性与兼容性结论

需求有效且结构层已部分完成。旧 Home、Portal 和 legacy reload 回退均不再兼容；直接删除。必须保留的是创建事务的幂等、失败恢复与当前输入不丢失，这些属于正确性。

关联与职责边界

• 依赖 [REQ-084] Alpha 页面通过窄 typed surface 接入路由 #199 提供 typed seam；[REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204 提供最终 route helper。
• [REQ-086] Draft 在正式路由中可恢复地晋升为 Session #201 拥有 Draft 生命周期；[REQ-088] Alpha Session Shell 稳定挂载并管理生命周期 #203 拥有 Session shell。
• [VERIFY][cap:session-surface] Router/MemoryRouter leaf-XOR、preload、provider remount、fatal reload 矩阵 #322 提供共享 route/surface 验证。

Delivery plan / 建议子票

• [REQ-085] AlphaHome formal route surface #178 — Home 正式 surface 基础实现。
• [REQ-085][CODE] Make Home session creation and first-prompt submission retry-safe #259 — 首条消息 retry-safe（PR [#259][REQ-085] Home startChat retry reuses session — no orphan sessions #1063）。
• [REQ-085][CODE] Render distinct Home project-loading, offline, and sidecar-not-ready states #260 — 明确 Home readiness/error states。 2026-09-17 按 owner 裁决不做关闭（AC2 已改写）。
• [REQ-085][CODE] Redact surface errors before rendering recovery UI #261 — 错误脱敏（PR [#261][REQ-085] Redact surface errors before recovery UI #1062）。
• [REQ-085][CODE] Add complete screen-reader semantics to Home workspace and autocomplete controls #262 — 读屏与键盘语义。 2026-09-17 按 owner 裁决不做关闭（AC6 已改写）。
• [REQ-085][CODE] Remove residual Home overlay CSS and hidden-anchor takeover #263 — 删除残余 overlay/takeover（已关）。
• [REQ-085][CODE] Add deterministic Home state and navigation contract coverage #264、[VERIFY][cap:session-surface] Router/MemoryRouter leaf-XOR、preload、provider remount、fatal reload 矩阵 #322 — 状态、导航与正式 route 验证（[REQ-085][CODE] Add deterministic Home state and navigation contract coverage #264 于 2026-09-17 按 owner 裁决不做关闭；[VERIFY][cap:session-surface] Router/MemoryRouter leaf-XOR、preload、provider remount、fatal reload 矩阵 #322 已关）。

Dependencies

• 原生依赖：[REQ-084] Alpha 页面通过窄 typed surface 接入路由 #199。
• 最终导航契约依赖 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204；这不要求保留 legacy route。

[jinjunnn]

需求收口(REQ-085,S40):唯一实现子项 #178 已按验收标准交付并关闭(PR #238,证据见该 issue 评论与 docs/audits/2026-07-12-req084-086-visual/)。父级验收契约(见 docs/requirements/ 冻结档)已由实现覆盖;ADR-027 决策门同变更集落笔。按交付标准关闭为 completed。

[jinjunnn]

按 2026-07-14 逐需求独立审计(alpha-work/governance/audits/2026-07-14-s40-s49-per-requirement-audit.md),REQ-085 完整度 = partial,未满足全部原始 AC,故 reopen 并移出 Done。

核心缺口:Portal→surface 迁移成立;首条消息不可重试、错误未脱敏直显、a11y FAIL

处置(v2 关闭契约):残余工作以本 REQ 身份补窄 [REQ-085][CODE|VERIFY] 子票(待 triage,不换 REQ 编号)。完整 file:line 证据见审计档同名目录 REQ-085.md。父需求在全部 required 子票关闭且每条 AC 有证据 PASS 前保持 open;安全类缺口如已单列 bug 票以其为准。