feat(onboarding): write a question for every consultation domain and stop generating an unread greeting

The home screen renders all ten domains from the consultation registry,
but the Agent only ever wrote three of them; the other seven were static
registry prompts dressed up as personalized starting points. The payload
now has to cover every domain in registry order, validated as a set
rather than per item, so a short or misordered answer is rejected whole
instead of silently leaving cards on static copy.

The greeting went the other way. Nothing has rendered it since the hero
note was removed, so it leaves the schema, the prompt, and the client
contract rather than costing tokens for text no one reads.

Ten questions take much longer to generate than three, so the route,
the server generation budget, and the client request deadline all grow
together, and the cache version bump forces existing payloads to be
regenerated once under the new shape.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Jesse_Chen
2026-08-18 15:18:09 +08:00
parent fc811d2c39
commit a6d4473ef0
10 changed files with 170 additions and 82 deletions
+9 -7
View File
@@ -3996,20 +3996,22 @@
- 复发自:无
- 修复版本:`a12f5797`staging
## BUG-270 | 首页 hero 第三行重复问候被删除,真实性边界随之迁移;同时暴露首页十个主题里只有三个由 Agent 生成
## BUG-270 | 首页 hero 第三行重复问候被删除,真实性边界随之迁移;onboarding 契约去掉无渲染点的欢迎语并扩展到全部十个主题
- 状态:resolved(本地修复,待提交与发布)
- 首次发现:2026-08-18
- 最近更新:2026-08-18
- 影响面:`/` 首页 hero 文案层级、主题区小标题承载的出生时间边界声明、Onboarding 起点加载文案、`onboarding.greeting` 字段的渲染状态
- 用户现象:BUG-269 把 Agent 欢迎语放进 hero 说明行后,用户评审首页时指出这一行「有点累赘」,要求删掉整段 `starter-hero-note`。同一次反馈里还指出「首页可不是三个问题啊,有好多问题」。
- 影响面:`/` 首页 hero 文案层级、主题区小标题承载的出生时间边界声明、Onboarding 起点加载文案、`/api/onboarding` 的 payload 契约与缓存版本、onboarding 生成超时预算、首页十张主题卡的文案来源
- 用户现象:BUG-269 把 Agent 欢迎语放进 hero 说明行后,用户评审首页时指出这一行「有点累赘」,要求删掉整段 `starter-hero-note`。同一次反馈里还指出「首页可不是三个问题啊,有好多问题」,并追问首页标题是否由 Agent 生成(答:不是,来自 `onboarding-client.ts` 的本地时段变体表,5 个时段 × 3 条问句)
- 触发条件:任何账号打开首页;hero 连续三行都在做同一件事(称呼、提问、再一次欢迎并再问一次「想从哪里开始」)。
- 根因:两处独立问题。
1. hero 的信息层级在 BUG-269 之后变成三行同义内容。`starter-greeting` 已经完成称呼、`h1` 已经完成提问,Agent 欢迎语在句式上又重复了这两件事,因此第三行没有新增信息。但这一行同时是「无可用出生分钟」账号的真实性边界声明所在(BUG-200 约束,`starter-questions.test.ts` 有断言钉住),直接整段删除会连边界声明一起删掉。
2. 首页主题卡渲染的是 `consultationDomainRegistry` 的全部十个域,而 `/api/onboarding``suggestions``career`/`marriage`/`timing` 的固定三元组。其余七个域(wealth、health、education、migration、family、annual、general)恒定回落到 registry 里的静态 `prompt`。加载态文案「根据你的资料整理三个起点。」也因此与实际渲染的十张卡不符。
- 修复:删除 `starter-hero-note` 元素及其两处 CSS 规则,hero 收敛为称呼加提问两行。出生时间边界声明迁到主题区小标题,按 `personalChartAvailable` 分支——读者正要挑主题时才看到这句限制,位置比 hero 更贴近实际动作。加载态文案改为「根据你的资料整理今天的起点。」,不再声明具体条数。`onboarding.greeting` 由此重新失去渲染点,本次保留字段未动 Agent 契约,因为移除它需要提升 onboarding 缓存版本并让所有用户的三个问题重新生成一次;此事作为待跟进项,不在本次改动内
- 验证:`onboarding-presentation.test.ts` 的 hero 断言改为同时检查 `page.tsx``globals.css` 中不再出现 `starter-hero-note`,避免只删元素留下死样式;`starter-questions.test.ts` 的边界声明断言从「文件里存在这句话」收紧为「这句话出现在主题区小标题且受 `personalChartAvailable` 分支控制」,防止下一次挪动文案时悄悄丢掉。四个相关套件 54/54 通过,`tsc --noEmit``page.tsx` ESLint 清洁。未做的验证:**没有在浏览器里确认删掉第三行后 hero 的留白比例**,以及边界声明迁到小标题后在窄屏上的折行;两者都要等 staging 发布后目视确认
- 防复发:删除一个 UI 元素前必须先确认它有没有在承载与自身样式无关的合规或真实性文案——`starter-hero-note` 表面是装饰性说明行,实际是 BUG-200 边界声明的唯一落点。删元素时同步删样式,并用测试同时钉住两个文件,否则死 CSS 会在下一次改版时被误当作现有设计复用。声明数量的文案(「三个起点」)不要写死在与数据源无关的地方;主题卡数量由 registry 决定,Agent 只覆盖其中三个域,任何写死条数的文案都会在 registry 增删域时失真
2. 首页主题卡渲染的是 `consultationDomainRegistry` 的全部十个域,而 `/api/onboarding``suggestions``career`/`marriage`/`timing` 的固定三元组。页面按主题 id 逐个 `find`,找不到就回落到 registry 的静态 `prompt`,因此其余七个域(wealth、health、education、migration、family、annual、general)恒定是写死文案,个性化只覆盖三分之一的入口,而界面上十张卡看起来完全同级,用户无法分辨哪些是为自己生成的。加载态文案「根据你的资料整理三个起点。」也与实际渲染的十张卡不符。
- 修复:分两步
1. 界面收敛:删除 `starter-hero-note` 元素及其两处 CSS 规则,hero 收敛为称呼加提问两行。出生时间边界声明迁到主题区小标题,按 `personalChartAvailable` 分支——读者正要挑主题时才看到这句限制,位置比 hero 更贴近实际动作。加载态文案改为「根据你的资料整理今天的起点。」,不再声明具体条数
2. 契约收敛(用户评审后决定,同一分支内完成):`onboarding.greeting` 从 Agent 契约里彻底移除——schema、fallback、prompt、客户端响应校验与 `OnboardingContent` 类型全部不再有这个字段,不再为无渲染点的内容付费。`suggestions``career`/`marriage`/`timing` 的固定三元组改成按 `consultationDomainIds` 顺序覆盖全部十个域,校验用 refine 钉住「长度与顺序都必须与 registry 一致」,于是首页十张卡全部是 Agent 写的,静态 `prompt` 退回纯兜底角色。fallback 直接由 `generalGuidedJyotishTopics` 派生,避免手写十条又与 registry 漂移。生成十条比三条显著更慢,预算随之上调:路由 `maxDuration` 30→60 秒、服务端生成超时 18→45 秒、客户端单次请求超时 25→50 秒。缓存版本 `ayanam-onboarding-v4``v5`,让所有存量 v4 payload 重新生成一次
- 验证:`onboarding-presentation.test.ts` 的 hero 断言改为同时检查 `page.tsx``globals.css` 中不再出现 `starter-hero-note`,避免只删元素留下死样式;`starter-questions.test.ts` 的边界声明断言从「文件里存在这句话」收紧为「这句话出现在主题区小标题且受 `personalChartAvailable` 分支控制」,防止下一次挪动文案时悄悄丢掉。契约部分新增 5 条回归:只覆盖三个域的旧形态响应必须整体拒绝并落到覆盖全域的兜底、主题顺序被交换必须拒绝(否则问题会挂到错误的主题标签下)、fallback 自身必须能通过 payload schemaregistry 里的 prompt 一旦不再第一人称就会被这条抓住)、prompt 与 payload/client 源码中不得再出现 greeting 字段、路由必须把 registry 主题列表发给 Agent。客户端请求超时断言从 25 秒下限改到 45 秒下限,与服务端生成预算对齐。全量套件 1720/1729 通过,9 个失败全部是本机 Docker/PostgreSQL fixture(与 BUG-265、BUG-269 同一类环境失败);`tsc --noEmit` 清洁,ESLint 仅存量 4 条 warning`next build` 成功。未做的验证:**没有在浏览器里看过改动后的首页**,也没有真实调用过新契约的生成——本机没有模型密钥,十条问题的实际生成耗时是否落在 45 秒预算内、十张卡的文案是否彼此重复、以及 hero 删掉第三行后的留白与边界声明在窄屏的折行,都要等 staging 发布后确认。若线上出现大量 `fallback`,第一嫌疑就是 45 秒预算仍然不够。
- 防复发:删除一个 UI 元素前必须先确认它有没有在承载与自身样式无关的合规或真实性文案——`starter-hero-note` 表面是装饰性说明行,实际是 BUG-200 边界声明的唯一落点。删元素时同步删样式,并用测试同时钉住两个文件,否则死 CSS 会在下一次改版时被误当作现有设计复用。声明数量的文案(「三个起点」)不要写死在与数据源无关的地方,数量必须跟着 registry 走。Agent 契约里的字段数量变化必须同步三件事:缓存版本、生成超时预算、客户端请求超时;只改 schema 不改预算的结果是全量用户静默落到 fallback,而 fallback 看起来是「正常内容」,不会报错。契约收紧时要用 refine 校验「集合与顺序」而不是只校验单项,否则模型少写几项或错位映射都能通过。
- 相关记录:BUG-269(本次推翻其 hero 说明行处置)、BUG-200(首页真实性边界声明的原始约束,本次迁移未削弱)
- 复发自:无
- 修复版本:`a12f5797`staging