docs(tasks): consult latency quick wins (no 4s VedAstro wait in consult gate; per-step timing)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4f2nya58RoRu4yEmJgRGE

docs/tasks/README.md

@@ -421,3 +421,4 @@
 | `TASK-astrologer-rulings-batch5-20261004.md` | `PROGRESS-astrologer-rulings-batch5-20261004.md` | 占星师第六轮：Rath 双主星按 p.43(a)–(e)、罗计尊贵按 Rath Table 9（仅 Narayana 内）、子运方向 p.51 例外与书内分歧标注、Wadiyar 两对标软件特例；年主选不出时不再用 Muntha 主星顶替（对齐上游 03bea6ed）；Rath 替换校正 v5 重试算（研究）（BUG 从 1223 起） | 已实现待验收（T2–T5 完成；T1 按红线停下 blocked；T6 研究分支已跑） | 分支 `codex/astrologer-rulings-batch5-20261004`（未推送；BUG-1223～1227；校正分数不变、未升版本）；研究分支 `codex/narayana-rath-rectification-trial-20261004`（不合入） |
 | `TASK-astrologer-rulings-batch6-20261004.md` | `PROGRESS-astrologer-rulings-batch6-20261004.md` | 第七轮裁定（共享仓书面回复，产品采用；问 1 选 A）：Rath 版双主星按 p.43 (a)–(e)（BUG-1227 解除 blocked，推翻第五批红线 2 的 Table 17 年数底线）；第 5 级宫主度数只倒算计都（p.71 脚注 42）；罗计旺陷 ±1 年；同宫两主比经度；BUG 从 1228 起 | 待验收 | 分支 `codex/astrologer-rulings-batch6-20261004`（BUG-1227～1229；校正分数文件未改、未升版本） |
 | `TASK-gate-log-volume-20261004.md` | `PROGRESS-gate-log-volume-20261004.md` | 门禁 validate 单步日志 4.4 万行 / 2 MB 网页打不开（run 3170）：快速门只打摘要（失败给末 200 行 + 日志文件）、前端测试门禁上 dot + 失败汇总（本机仍 TAP）、拆分 validate 为 7 个 step（产品授权改 workflow，只限拆分与重定向）；检查一项不少 | **已实现待验收**（BUG-1230；未推送、未部署；Gitea 各 step 页面是否打得开留待推送后由产品确认） | 分支 `codex/gate-log-volume-20261004` |
+| `TASK-consult-latency-quickwins-20261005.md` | `PROGRESS-consult-latency-quickwins-20261005.md` | 普通对话耗时两项快修：咨询链校正闸不再同步白等 VedAstro 官方快照子进程（每域约 4 s，复用顶层缓存 + 负缓存，不推翻 BUG-301）；补分段计时（第 0/1 步耗时、推理 token、分类耗时进日志与 usage）。推理强度/精简说明待模型 key 另单（BUG 从 1231 起） | 待领取 | 分支 `codex/consult-latency-quickwins-20261005` |

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

@@ -0,0 +1,101 @@
+# 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 写清阻塞点。
+
+## 开工前置命令
+
+```bash
+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；开工时再核对）。