Jyotisha/docs/tasks/PROGRESS-consult-first-frame-and-pacing-20260928.md

PROGRESS · 普通对话发出即有反馈，正文按打字节奏（2026-09-28）

任务书：TASK-consult-first-frame-and-pacing-20260928.md（产品已确认 D1、D2、D3；D4 160 字阈值不动；D5 工具 / 扣点 / 分类模型不动）。执行方：Claude fork 子代理（直接执行模式）。

基线

• origin/staging = 584ad05c（2026-09-28）；分支 codex/consult-first-frame-and-pacing-20260928，工作树 .worktrees/consult-first-frame-and-pacing-20260928。
• 开工实测（Node 22.14，npm test）：4197 条 / pass 4143 / fail 24 / skipped 30 / cancelled 0；24 条失败均为无 Docker 的 DB / 部署套件（清单存 scratchpad baseline2-fails.txt）。
• 首屏 rootMainFiles gzip(9) 基线：130,933 B（PROGRESS-consult-answer-the-question-20260927 口径，4 个文件）。
• 分类耗时的真实分位数：无法从本机取得（staging 观测日志需登录后台）。代码上限是 SMALLTALK_TIMEOUT_MS = 3_000（fail-open）；在 R2 的开流前序列里它前面还有会话读取（1 次查询）、prepareConsultationRoute（资料 / 档案 / 区间，2～3 次查询）、reserve_consultation_usage（1 次 RPC + 1 次计价查询）、append_consultation_question（1 次 RPC）。部署后用 classification.<outcome> 与本单新增的 first_byte 阶段 durationMs 复核。

做了什么

T1 客户端首帧（BUG-1074，提交 86d99115）

• chat-message-row.tsx：删 awaitingClassification，quiet 只由 responseKind === "smalltalk" 决定。
• consultation-run-timeline.tsx：QUEUED_TIMELINE_ROW.label 改 CONSULTATION_RECEIVED_LABEL（「收到，正在看你的问题…」，新增在 consultation-activity-labels.ts，服务端首帧共用）。
• DESIGN.md §9、docs/VOICE.md 新段。

T2 服务端先建流（BUG-1074，提交 0bc66590，补修 891e9c62）

• 新 frontend/src/lib/stream-first-response.ts：streamFirstResponse({ requestId, run, onFirstFrame, onUnhandled }) 先返回 NDJSON Response，start() 里同步写首帧 activity（phase received），再 await run()：内层 NDJSON Response 逐字节透传，内层 JSON 拒绝转成一条 run.failed request_rejected（consultationRejectionEvent(status, payload)：句子按 recovery → message → error 取，与客户端 payloadMessage 同一优先级；原 code 作 reason），run 抛错则写通用 run.failed 并回调日志；外层 cancel() 把断连传给内层 reader（内层 continueAfterDisconnect 照旧结算）。
• route.ts：const runTurn = async (): Promise<Response> => { … } 包住从 prepareConsultationRoute 到最后 catch 的整段（正文缩进未动，保持 diff 最小、源码断言不变）；shouldUseAgenticRuntime(user) 为假走原顺序（legacy 的 text/plain 回复不能走 NDJSON），为真 return streamFirstResponse({...})；onFirstFrame 记 consultation-stream-first-v1 / first_byte（毫秒，不含原文）。寒暄分支、streamSmalltalkResponse、免费结算 RPC 与参数一行未改（任务书写「改成可写 controller 的函数」，实际用逐字节中继达到同一效果、少改一处结算代码；见偏离）。
• consultation-agent-events.ts：publicActivityPhaseSchema 加 received；run.failed 的 code 加 request_rejected，可选 status（400–599）与 reason（≤ 80），union 级 superRefine：status / reason 只允许 request_rejected，且 request_rejected 必须带 status。
• use-consultation-run.ts：删 x-jyotish-response-kind 响应头读取（只认 run.completed.responseKind）；request_rejected 事件与 HTTP 非 2xx 走同一个 rejectRun(status, message, code)（401 跳登录、402 开充值、抛 ConsultationResponseError），后续按 status / code 的回滚、session_full、session_not_consultation、request_conflict 处理不变；首帧 activity(received) 不带已完成轨迹。chat-message-row.tsx 的 phase → 状态映射加 received: "working"。

开流前 / 流内对照表（agentic 运行时）

失败	以前	现在	客户端
Supabase 未配置	JSON 503	仍开流前 JSON 503	不变
未登录	JSON 401	仍开流前 401	跳 /login
请求体不合法	JSON 400	仍开流前 400	不变
会话读取失败 / 不存在 / 是校正会话 / 模型已变化	JSON 503 / 404 / 409(session_not_consultation) / 409	仍开流前	不变（session_not_consultation 仍切到校正会话）
会话模型不可用；旧版校正入口；提示词提取	JSON 503 / 409 / 400	仍开流前	不变
计费配置不可用（pricing_configuration_unavailable）	JSON 503	流内 request_rejected status 503 reason 同	同句、同状态
咨询计划不可用（上限 / 模式不一致）	JSON 409	流内 status 409	409 → 回滚问题到输入框
主体 / 资料失败（consultationSubjectFailureResponse、ConsultationProfileTruthError）	JSON 4xx/503	流内，status 原值	不变
预留失败 / 模型不可用	JSON 503 / 409	流内	不变
点数不足	JSON 402	流内 status 402	开充值 + 回滚
保存问题失败 / 对话已写满	JSON 503 / 409(session_full)	流内，reason: "session_full"	「开新对话」提示不变
生成失败（最后的 catch）	JSON 503（recovery 句）	流内，句子取 recovery	不变
寒暄	NDJSON + 响应头	流内 NDJSON 透传，无响应头	只认 run.completed.responseKind

T3 客户端节奏（BUG-1075，提交 3f8b8172，补修 891e9c62）

• stream-frame-buffer.ts：STREAM_RELEASE_MAX_CHARS = 4（普通积压每帧上限）、STREAM_RELEASE_CATCHUP_CHARS = 600（超过才按 1/12 追赶）、STREAM_SETTLE_MAX_FRAMES = 90；settle({ paced: true }) 按 max(4, 剩余/90) 每帧写完剩余、最后一帧 settled: true、返回 Promise；无参 settle() 保持一帧全放；页面隐藏一帧全放；写出期间 dispose() 延到写完；reset() 结束写出。
• use-consultation-run.ts：流正常结束 → settleFrames(false)：先给 streaming reply 打 settling: requestId，frames.settle({ paced: true })；停止 / 截断 / 失败 → 无参 settle 立即全放。数据层（入库、persistSession、结算、completeConsultationInterface）不等动画；completeConsultationInterface 不再清掉正在写出的回复（函数式更新）；每个写出帧只在 current.settling === requestId 时更新，最后一帧清空；新一轮发送覆盖 streaming reply 后旧帧自然落空。
• chat-message-view.ts：settlingChatMessageView(last, loading, streamingText)，latestAssistantView / chatMessageViews 在 loading 为假、释放文本是已存回复严格前缀时用同一 renderKey 渲染前缀（settling: true）；chat-message-row.tsx 写出期间时间线不 live。home-types.ts StreamingReply.settling。
• 滚动跟随不新写：useConversationScrollAnchor 观察内容增长，写出期间与流式期间同一路径。

T4 记录（本提交）

• docs/BUG_HISTORY.md：BUG-1074、BUG-1075（fixed_pending_acceptance）。
• CHANGELOG.md 一条；docs/testing/consult-first-frame-and-pacing-20260928.md 7 条；BLOCKED.md 新段；docs/tasks/README.md 行状态「已实现待验收」。

测试

新增

• frontend/tests/consult-first-frame-and-pacing-20260928.test.tsx（13 条）：T3 前缀覆盖 view / 行渲染、非前缀 / loading / 全文不覆盖、hook 源码（完成走节奏、停止 / 截断 / 失败立即、completeConsultationInterface 不清 settling、只一处 settle({ paced: true })）；T2 ① 分类挂起首帧已出（onFirstFrame 40 ms）② 真实 streamSmalltalkResponse 流内完成、免费结算 1 次、无响应头 ③ 402 / 409 / 503 三种 JSON → request_rejected 字段逐一对照 + schema 约束 ④ NDJSON 首帧后逐字节一致、断连传内层、run 抛错通用失败；route 源码开流前 / 流内两张清单、分流、first_byte；客户端源码事件判寒暄、rejectRun 两处调用、计数不变。
• stream-frame-buffer.test.ts +3：160 字 40 帧；600 以上仍 12 帧追赶；剩余 300 字 paced settle ≤ 90 帧、单调、最后一帧 settled、无参 settle 一帧；dispose 延后。

改既有断言（原值 / 新值 / 原因，注释也写在测试里）

文件	原值	新值	原因
chat-stream-settle-contract.test.ts	live 时间线含「正在处理…」	含「收到，正在看你的问题…」、不含旧句	D1 / BUG-1074
consultation-smalltalk-ui.test.tsx	分类回来前不渲染时间线、不出现「正在处理 / 正在分析」	渲染排队行（唯一一行、无 think / write 步）；只有 smalltalk 行静默	D1 / BUG-1074
consultation-smalltalk.test.ts	/const quiet = smalltalk || awaitingClassification/	/const quiet = smalltalk;/ 且无 awaitingClassification	D1 / BUG-1074
consultation-agentic-runtime.test.ts	writerToSend 的 phase 手写四值联合	PublicActivityPhase（多 received）	D2 / BUG-1074
chat-navigation-a11y-contract.test.ts	/if \(response\.status === 402\) openAccountDialog(...)/	/if \(status === 402\) openAccountDialog(...)/（rejectRun 里）	D2；调用点计数 3 / 2 不变
consultation-recovery.test.ts	/!response\.ok[\s\S]*throw new ConsultationResponseError\([\s\S]*response\.status/	rejectRun(status, message, code): never 抛 ConsultationResponseError(status, …)，!response.ok 调 rejectRun(response.status, …)	D2 / BUG-1074：HTTP 体与流内事件共用一处
stream-frame-buffer.test.ts	settle() 同步放完	settle({ paced: true }) 在 90 帧内写完、最后一帧 settled；无参 settle 仍一帧	D3 / BUG-1075

chat-stream-layout.test.ts 的 /正在处理…/ 仍成立（活动面板兜底文案未改，那是无时间线行的 fallback）。

门禁数字（完工实测，Node 22.14，本工作树，顺序执行）

项	结果
tsc --noEmit	0 错
npm run lint	0 error（128 条既有 warning 未动）
npm test	4212 条（基线 4197，+15）/ pass 4158 / fail 24 / skipped 30 / cancelled 0；退出码 1 = 那 24 条
失败清单比对	24 条失败按名称与基线逐条一致（diff 为空，均为无 Docker 的 DB / 部署套件）。全部测试名对比（基线取自 9d01757f 同代码的验收全量 TAP）：新增 17 个名字；消失 2 个 = 本单按三栏改名的两条（classification wait does not invent a thinking step before any activity → the classification wait shows the queued row from the send frame; only a smalltalk reply is quiet；many events collapse into one flush per frame and settle releases everything synchronously → … and a paced settle writes the rest out within the budget），原名在测试注释的原值里
next build --webpack	exit 0；/、/chart、/ephemeris、/people 均 ○ Static
首屏 rootMainFiles gzip(9)	130,950 B（4 个文件），基线 130,933 B，+17 B（+0.013%，±2% 内）；量于 891e9c62，其后只改了测试与文档
page.tsx	未动
python3 -m pytest tests/test_repo_privacy_markers.py -q	通过（写了实测数字的文档推送前必跑）

提交

SHA	内容
86d99115	T1 客户端首帧
3f8b8172	T3 放字节奏与 paced settle（首版默认 paced）
0bc66590	T2 先建流、事件、客户端
891e9c62	T2/T3 补修：paced 改 opt-in、rejectRun 合并两条拒绝路径（全量跑出 7 条新失败后改）
（本提交）	T4 记录 + consultation-recovery.test.ts 三栏（第二次全量跑出的最后 1 条源码断言）

偏离与说明

1. 寒暄流没改成「写 controller 的函数」（任务书 T2 第 1 条）：外层流把内层 streamSmalltalkResponse 的 Response 逐字节中继，效果相同（先免费结算再发 answer.delta + run.completed），且不动 BUG-976 那组结算代码；本机无 Docker 跑不了它的真实 PG 测试，少改一处更稳。假模型层的断言补在新测试 ②。
2. paced settle 改成 opt-in：首版把 settle() 默认改成按节奏，全量跑出 7 条新失败——校正面 rectification-chat-turn-run.ts 两处 settle() 之后同步合并快照（rectification-dup-question、rectification-opening-plain、rectification-activity-receipt 5 条），以及 Node 无 window.requestAnimationFrame 的未捕获异常。改成 settle({ paced: true }) 只在普通对话完成路径用，校正面契约不动；校正面要同样节奏另立单（BUG-1075 防复发写明）。另 2 条是 chat-navigation-a11y-contract 数 window.location.assign("/login") / openAccountDialog("billing", …) 的调用点，首版在事件分支复制了两句，改成 rejectRun 共用后计数回到 3 / 2。
3. legacy 运行时不先建流：CONSULTATION_AGENTIC_RUNTIME=legacy / canary 非成员仍是原顺序（text/plain 回复无法走 NDJSON）。staging / 生产 compose 都是 enabled。
4. route.ts 的 runTurn 正文没有重新缩进：包一层箭头函数但保留原缩进，避免上千行的纯缩进 diff 打破十几个按源码文本断言的合同测试；lint 无缩进规则报错。
5. 首帧的 activity(received) 在时间线 reducer 里不加行（返回原状态），客户端从发送那一帧起已经显示同一句排队行；这样那一帧到达时字不变、行不跳。
6. next build 默认 Turbopack 对软链 node_modules 报错（同前几单），用 --webpack 量 / 与 gzip。
7. 真机、真实耗时、真实 PG 结算测试：见 BLOCKED.md。

Claude 验收（2026-09-28，Node 22.14，本工作树独立复跑）

项	结果
tsc --noEmit	0 错
npm run lint	0 error
npm test	4212（基线 4197，+15）；pass 4158 / fail 24 / skipped 30；24 条失败按名称与基线逐条一致
next build --webpack	exit 0；/ 仍 ○ Static；gzip 以执行方实测 +0.013% 为准
代码走查	先建流只包 agentic 运行时，runTurn 在该运行时下只返回 NDJSON（runAgenticConsultation）或 JSON 拒绝，无 text/plain 路径落入包装器；客户端原先读的 x-jyotish-* 头在 agentic 下本就不存在；completeConsultationInterface 在 paced settle 之后立即执行，输入框不等动画
真机	未做（无登录态、无模型凭据），见 docs/testing/consult-first-frame-and-pacing-20260928.md

结论：T1–T4 通过，推 staging 后核对 /api/health 的 deployment.gitCommit 与 first_byte 埋点。