Jyotisha/docs/tasks/TASK-consult-latency-quickwins-20261005.md

TASK：普通对话耗时——外部服务不再白等 + 补分段计时 — 2026-10-05

基线

• 开工时 git fetch origin --prune 之后的最新 origin/staging。写本单时是 1252de3e，已部署。
• 分支 codex/consult-latency-quickwins-20261005，工作树 .worktrees/consult-latency-quickwins-20261005。
• 依据：10-04 只读审计（Claude 子代理）。测量脚本与原始数据在 Claude scratchpad bench/，不入库；结论摘要见下面「事故实证」。

事故实证

一轮普通对话（问父母、问年运）全程串行，分为：分类（thinking 关，≤3 s）→ 第 0 步（thinking 开，决定调用排盘工具）→ 引擎 /api/consultation_workflow（每个领域一次，最多 2 个领域）→ 第 1 步写答案（thinking 开）。

1. 校正闸每个领域白等 4 秒。
   • 咨询链里的 rectification gate（jyotish_api_server._compute_rectification_gate → vedastro_gateway.run_gateway_packet）会走到 vedastro_service_adapter 中调用 _try_official_capability_runner_snapshot_bundle 的那一段（按符号定位）。它起一个子进程，撞上 DEFAULT_TIMEOUT_SECONDS = 4。
   • 本机装上 vedastro SDK、按产品路径（defer_optional_external_evidence: true）实测，每次 4.6 s，第二轮仍是 4.6 s。原因：失败结果不写缓存。
   • 同一份响应里，顶层 vedastro_gateway 是 official_verified（BUG-727 的缓存在起作用），但 rectification.vedastro_gateway.official_closure_reason = official_raw_response_missing。
   • 屏蔽外网时，引擎每个领域 0.75 s；这 4 s 是额外的等待。
   • 这些数字在沙箱网络下测得，生产 VPS 是否同样撞超时，须在 staging 先确认（T0）。
2. 看不到分段时间。
   • 现有埋点（[agent-observability]、/admin/usage）有 first_byte、工具耗时、answer.first_output、run.total、总 token。
   • 没有：推理 token 数；第 0 步、第 1 步各自的耗时；分类耗时进不了 usage。
   • 推理慢的主因（答题步约 1 万推理 token、约 45 秒）因此无法在线上逐轮核对，后续「限制推理强度」「精简说明」两单也没有办法验证。

决策记录（产品负责人 2026-10-05）

1. 做「不白等外部服务」和「补分段计时」两项，也就是审计建议的 ③ 和 ⑤。
2. 「限制推理强度」「精简说明」「第 0 步关 thinking」不在本单，等产品提供临时模型 key、跑名人回测之后另开单。
3. 不推翻 BUG-301：顶层前台 VedAstro 照旧调用。本单只处理咨询链里校正闸那一处注定拿不到结果的等待。

硬红线

1. 遵守 jyotish_api_server.py 的增长冻结（AGENTS §6）：类方法数不增长，JyotishAPIHandler.__new__ 伪造点不增长。改动放进 scripts/vedastro_service_adapter.py / scripts/vedastro_gateway.py，或新模块。
2. 不改生时校正的打分：v5 77 例与改动前逐项相同；冻结身份文件（references/rectification_sealed_holdout.v1.json → production_scoring_files）原则上不动。确实要动，就按 ERR-110 重新冻结，并同步 frontend/tests/rectification-confirmation-gate.test.ts 的两处路径（三栏）和 tests/test_sealed_holdout_contract_freshness.py。
3. 生时校正面自己调用 VedAstro 的行为（若与咨询共用同一函数）不得改变；只对咨询路径生效，或者用开关区分。改动前后，生时校正的官方证据字段要逐项相同。
4. 埋点只记数字和状态（毫秒、token 数、步骤号、是否超时），不记提示词、答案正文、出生资料、用户 ID（AGENTS §8、§5.6）。
5. 不改普通对话提示词和数据卡内容。
6. 验收要跑 Python 全量 pytest tests 并与开工基线对比失败名单（BUG-1220 的教训），不能只跑快速门。
7. 不用 git stash；不切换别人的工作树；开工前先 df -h /。

任务分解

T0 staging 先确认（只读，不改代码）

• 用 staging 的公开接口或测试账号，对一位公开名人发一次 /api/consultation_workflow（或经普通对话发一次），记录：
  • rectification.vedastro_gateway.official_closure_reason；
  • 该请求的耗时。
• 拿不到登录态时，在进度记录里写明「T0 环境缺口」，并给产品一条可照做的检查方法：在 /admin/usage 或容器日志里看工具耗时是否接近「领域数 × 4 s 以上」。
• T0 不阻断 T1。

T1 校正闸不再同步白等官方快照子进程

• 咨询路径下（以请求里已有的 defer_optional_external_evidence 或同等标记区分），校正闸遇到官方快照 runner 时：
  • 优先：复用顶层 vedastro_gateway 已经拿到的官方结果（同一份「出生数据 + 岁差 + 交点 + UTC 日期」缓存键，BUG-727）。
  • 拿不到时，不再前台起 4 秒子进程，直接标 official_closure_reason = deferred_in_consultation（或同义的明确状态），不伪装成 verified。
  • 失败或超时的结果按同一个缓存键写入负缓存，有效期到当日 UTC 结束，避免同日每轮重复等待。
• 验收：
  • 本机装 vedastro SDK 后，按产品路径实测：每个领域的耗时从约 4.6 s 降到不超过 1.0 s（测 3 位名人 × 父母 / 年运，冷、热各两轮），数字写进进度记录；
  • 咨询响应里的 rectification.vedastro_gateway 状态如实；
  • 生时校正面的 VedAstro 证据字段改动前后逐项相同；
  • 新增测试：咨询路径不调用 snapshot runner 子进程（mock 断言）；负缓存同日命中；跨日失效。

T2 补分段计时

• [agent-observability]（frontend/src/lib/agent-observability.ts、stream-agent-response.ts、普通对话 route）新增字段：
  • 分类：classification.durationMs（已有的话，确认它进了 usage）；
  • 第 0 步、第 1 步各自的 durationMs、reasoningTokens、outputTokens、inputTokens、cachedInputTokens（取供应商返回的 usage；拿不到的写 null，不估算）；
  • 工具调用：各领域的 durationMs（已有的话保持不变）；
  • answer.reasoning_ms：第 1 步开始到第一个正文字符的时间。
• 同样的数字写进 /admin/usage 记录的 metadata（不动表结构，只用已有的 JSON 字段；若没有可用的 JSON 字段，写进进度记录，留给另单，本单不加迁移）。
• /admin/usage 页面能看到这些数字最好；需要改 UI 时只加一列或一个展开区，并同步 frontend/DESIGN.md。
• 验收：
  • 新增单元测试：给定一组模拟的步骤结果，日志 / usage metadata 的字段齐全，并且不含正文；
  • 进度记录写明产品在哪里看、每个字段的含义（一张表）。

T3 记录

• docs/BUG_HISTORY.md：T1、T2 各一条（T1 关联 BUG-727、BUG-301；T2 关联 10-04 审计）。
• CHANGELOG.md；docs/tasks/PROGRESS-consult-latency-quickwins-20261005.md（T0 结果或环境缺口、T1 前后耗时表、T2 字段表）；docs/tasks/README.md 改为「已实现待验收」。

让步顺序

T2 → T1 → T0 → T3。T2 风险最低且是后续两单的前置；T1 若发现生时校正与咨询共用路径、难以隔离，先交 T2，T1 写清阻塞点。

开工前置命令

cd /workspace/Jyotisha && git status -sb | head -1
git fetch origin --prune
git worktree add -b codex/consult-latency-quickwins-20261005 .worktrees/consult-latency-quickwins-20261005 origin/staging
df -h /
grep -oE "BUG-1[0-9]{3}" docs/BUG_HISTORY.md | sort -u | tail -1
python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45

外部引擎改动需先读 docs/research/pre_work_error_ledger.md（AGENTS §9），并检索 docs/BUG_HISTORY.md 里的 VedAstro / BUG-301 / BUG-727 记录。

验收口径

• Python：快速门 + 全量 pytest tests 与基线对比 + 英文对照 + 隐私测试；v5 逐项相同。
• 前端：tsc 0 错；lint 0 error；npm test 失败名单与开工基线逐条相同。
• 不 push，由 Claude 验收后推 staging；部署后由产品在 /admin/usage 看一轮真实分段。

BUG 编号起点

BUG-1231（10-05 实测最大号 BUG-1230；开工时再核对）。