merge origin/staging into consult prep parallel (issue #62)

Docs-only catch-up; agent-loop rule A. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LutgzyJqNhPpZy1nFsJtN3
2026-10-14 11:14:51 +08:00
parent 9e29310941 f122f8b7d7
commit 4130d1dba9
14 changed files with 19397 additions and 18058 deletions
@@ -0,0 +1,44 @@
+# PROGRESS · 长报告出稿提速（2026-10-14）
+
+- 分支：`codex/report-reference-perf-20261013`
+- 实际基线：`origin/staging` `66cd60081f37a57680274633fcb3fb942d01bb2f`（任务书写的 `77057a819`、计划评论里的 `2994588ad` 都更早，按当前 staging 开工）
+- `scripts/jyotish_api_server.py`：10335 行，零改动
+- 历史最大号在本基线上是 BUG-1322。BUG-1323～1334 已被其它未合入任务书占用。本单用任务书指定的 BUG-1335、BUG-1336。
+
+## 做了什么
+
+1. 两个开关在调用时读环境变量。渲染快捷路径默认关，同盘缓存默认开。
+2. 中文和英文的大运密度补句：正则预编译，行内先看必出现的字面量，没有才不搜索；向前看的五行只在可能命中时才拼。术语替换：正文里没有这个词就原样返回，编译结果按词缓存。
+3. 溯源哈希在开关打开时，一次遍历同时删掉 `**.键` 并做键名规范化。覆盖范围和排除集没变。没有跳过中间那次绑定，因为那会改 `format=json` 的键顺序。
+4. 咨询卡缓存的单飞和两天清理多了一个子目录参数，咨询卡自己的键和目录不变。长报告只在完整数据版 + markdown、开关开、并且 `GITHUB_SHA` 是具体版本号时，才把整份响应放进 `scratch/local/report_reference_cache/`。查缓存发生在重计算之前。命中打一行不含资料的日志。
+
+## 自测
+
+| 检查 | 命令 | 结果 |
+| --- | --- | --- |
+| 任务书列出的 pytest | `.venv\Scripts\python.exe -m pytest` 后接任务书第 8 节那一串文件 `-q` | 退出码 0。缓存默认改成开之后又跑了一遍，仍是退出码 0 |
+| 屏蔽 PyJHora 的 A/B | `python scripts/research/report_reference_perf_ab.py --mask-pyjhora` | 四张盘五字段 sha 相同；端到端下降 20%～23%，未达 35%；缓存命中中位约 0.06 秒 |
+| 同一份解盘的 json / reference | 同上脚本 `--side-only` | 退出码 0。时钟钉死且复用同一次解盘后，两版 sha 相同 |
+| 不屏蔽 | 未跑 | 本机没有 PyJHora，和屏蔽走同一条导入失败路径 |
+
+数字见 `docs/testing/report-reference-perf-ab-20261013.md`。
+
+## 改既有断言
+
+无。原值 / 新值 / 原因：没有改旧断言。
+
+## 未做
+
+- 整篇替换逐条预检（让步顺序里最先砍的一项）。中文渲染只降了 20%～28%，不到 40%，没有为了过线改输出。
+- 跳过中间绑定。
+- 关掉没人读的质量门。任务书写明这要另开单，本单不动。
+- 旧路径退役。开关还在。
+
+## 默认值
+
+- `JYOTISH_REPORT_RENDER_FAST` 默认关。字节一致，内存还降了约 12%，但端到端没到 35%。
+- `JYOTISH_REPORT_REFERENCE_CACHE` 默认开。命中与未命中字节一致，命中中位约 0.06 秒。版本号缺失或是 `unknown` 时不缓存。
+
+## 第 1 次打回
+
+合并最新 `origin/staging` 后，把 `report_reference_cache` 登记进 `OFFLINE_SCRATCH_NAMES`。清理逻辑没改：这个目录仍由 `consult_full_data_cache.get_or_build` 在每次调用时删掉两天前的文件。没有改两个缓存模块的行为。
@@ -473,11 +473,12 @@
 | `TASK-home-sidebar-rerender-20261013.md` | `PROGRESS-home-sidebar-rerender-20261013.md` | 流式回答时侧栏每帧整栏重渲染（BUG-1329，A/B） | 待验收 | `codex/home-sidebar-rerender-20261013` |
 | `TASK-home-sidebar-rerender-fix-20261014.md` | `PROGRESS-home-sidebar-rerender-20261013.md` | **#59 第 1 次打回**：`63509431` 其余全过；`chat-navigation-a11y-contract` 按源码文本断言 `onOpenBilling` 旧写法未跟改（§7.8） | 待验收 | `codex/home-sidebar-rerender-20261013` |
 | `TASK-api-disk-cache-retention-20261013.md` | `PROGRESS-api-disk-cache-retention-20261013.md` | API 磁盘缓存只进不出、VedAstro 审计文件留存出生资料、失败快照久缓存、缓存键规范化（BUG-1330～1332，A/B） | 待验收 | `codex/api-disk-cache-retention-20261013` |
-| `TASK-report-reference-perf-20261013.md` | — | 长报告出稿提速：术语替换命中预检、哈希单次遍历、同盘复用（BUG-1335～1336，A/B） | 待领取 | `codex/report-reference-perf-20261013` |
-| `TASK-report-reference-perf-fix-20261014.md` | — | **#61 第 1 次打回**：`69c739fb` 本单全过（Linux 复跑逐字节一致、命中 0.03 s）；与 #60 合并后新缓存目录未登记进 `api_scratch_retention`，合同测试红 | 待领取 | `codex/report-reference-perf-20261013` |
+| `TASK-report-reference-perf-20261013.md` | `PROGRESS-report-reference-perf-20261013.md` | 长报告出稿提速：术语替换命中预检、哈希单次遍历、同盘复用（BUG-1335～1336，A/B） | 待验收 | `codex/report-reference-perf-20261013` |
+| `TASK-report-reference-perf-fix-20261014.md` | `PROGRESS-report-reference-perf-20261013.md` | **#61 第 1 次打回**：`69c739fb` 本单全过；与清理规则合并后，长报告缓存目录补进自行清理名单 | 待验收 | `codex/report-reference-perf-20261013` |
 | `TASK-consult-prep-parallel-20261013.md` | `PROGRESS-consult-prep-parallel-20261013.md` | 普通对话发问前准备步骤并行、模型版本短缓存、多领域并发开关（BUG-1337～1339，A/B） | 待验收 | `codex/consult-prep-parallel-20261013` |
 | `TASK-consult-prep-parallel-fix-20261014.md` | `PROGRESS-consult-prep-parallel-20261013.md` | **#62 第 1 次打回**：两条源码文本检查改认新位置，对照脚本挪进测试目录 | 待验收 | `codex/consult-prep-parallel-20261013` |
 | `TASK-frontend-dead-code-20261013.md` | — | 前端死代码 17 文件与无调用方接口删除，含未登录重计算接口（BUG-1342） | 待领取 | `codex/frontend-dead-code-20261013` |
+| `TASK-frontend-dead-code-fix-20261014.md` | — | **#63 第 1 次打回**：`1f9947a0` 其余全过；类名白名单留了已删组件的 `personal-report-additional-charts` | 待领取 | `codex/frontend-dead-code-20261013` |
 | `TASK-api-chart-subprocess-gate-20261013.md` | — | 合盘不带 skip 串行排盘、报告无效子进程、名额轻重混用（只模拟）（BUG-1333～1334，A/B） | 待领取（排队：api-disk-cache-retention + report-reference-perf） | `codex/api-chart-subprocess-gate-20261013` |
 | `TASK-answer-effort-ab-20261013.md` | — | 答题步推理强度开关 + A/B（需模型 key） | 待领取（排队：consult-prep-parallel） | `codex/answer-effort-ab-20261013` |
 | `TASK-consult-route-split-20261013.md` | — | consult POST 拆分第一阶段：开流前加载 + 计费结算 | 待领取（排队：consult-prep-parallel、answer-effort-ab） | `codex/consult-route-split-20261013` |
@@ -0,0 +1,33 @@
+# TASK · 前端死代码删除修复单（issue #63，第 1 次打回）
+
+- 日期：2026-10-14
+- 原任务书：`docs/tasks/TASK-frontend-dead-code-20261013.md`
+- 被验 SHA：`1f9947a0d733e34b7754cce058e20b023791fdd8`（`codex/frontend-dead-code-20261013`）
+- 执行方：Grok，同一分支续做（先 merge 最新 `origin/staging`，不改写已推历史）
+- BUG 编号：沿用 BUG-1342
+
+## 1. 验收结论：一条未通过，其余全部通过
+
+| 检查 | 结果 | 证据 |
+| --- | --- | --- |
+| 删除范围 | 通过 | 删掉的文件与三个路由都在原任务书清单内；全仓 grep 三个路由路径、被删模块名，`frontend/src`、`scripts`、`deploy`、`.gitea` 无残留引用 |
+| 改既有断言 | 通过 | 每处三栏齐全；否定合同（不得挂内部徽章 / 内部面板）保留；`/api/birth-rectification` 改成「路由不存在且无代理」 |
+| tsc / lint / next build | 通过 | 0 错 / 0 error（warning 125→123）/ `/` 仍 Static；首屏 gzip −312 字节 |
+| Python 改动的两份测试 | 通过 | — |
+| 前端全量 `npm test`（与 staging 逐名比对） | **未通过：新增 1 条** | `frontend/tests/class-name-definition-contract.test.ts`「the knownUnstyled allowlist has no stale entries」：`actual: ['personal-report-additional-charts']` |
+
+**根因**：`class-name-definition-contract.test.ts` 第 62 行的 `knownUnstyled` 白名单里有 `personal-report-additional-charts`，这个类名唯一的使用者是已删除的 `personal-report-document-view.tsx`。合同要求白名单里不能有已经没人用的条目。
+
+## 2. 修法要求
+
+1. 从 `knownUnstyled` 删掉 `"personal-report-additional-charts"` 这一项，旁边按 §7.3 写三栏（原值：白名单含该项；新值：删除；原因：唯一使用者随 BUG-1342 删除，白名单不得留陈旧条目）。
+2. 再查一遍：被删文件里用到的其它类名，是否还出现在别的白名单 / 合同里（`grep -rn "knownUnstyled\|allowlist" frontend/tests` 后逐个核对）。
+3. 业务代码不改。PROGRESS 末尾记一行。
+
+## 3. 验收标准
+
+前端全量 `npm test` 失败清单与 staging 基线逐名相同（本机 Docker 类失败除外）。
+
+## 4. 让步顺序
+
+无。第 1 次打回。
@@ -0,0 +1,61 @@
+# 长报告出稿 A/B（2026-10-14）
+
+Windows 本机，Python 3.11.7，`Windows-10-10.0.26200-SP0`。屏蔽 PyJHora（生产镜像不装这个库）。本机本身也没有 PyJHora，所以没有再跑一轮不屏蔽的重复计时。计时开了 tracemalloc，绝对秒数比任务书里的 Linux 基线高，只比较同一进程里的 A 和 B。
+
+A = 两个开关关。B = 两个开关开。四张虚构盘，每组 3 次。生产请求是完整数据版、markdown、中英都要、带事实表。没有模型钥匙。
+
+## 端到端（未命中，秒）
+
+| 盘 | A 三次 | A 中位 | B 三次 | B 中位 | 下降 |
+| --- | --- | --- | --- | --- | --- |
+| day | 71.31 / 64.03 / 64.01 | 64.03 | 51.05 / 50.77 / 51.74 | 51.05 | 20.3% |
+| night | 66.25 / 66.11 / 66.66 | 66.25 | 53.32 / 52.57 / 50.43 | 52.57 | 20.7% |
+| south | 66.03 / 66.00 / 62.69 | 66.00 | 49.97 / 52.79 / 52.68 | 52.68 | 20.2% |
+| section2 | 71.01 / 108.37 / 74.19 | 74.19 | 57.42 / 57.12 / 71.80 | 57.42 | 22.6% |
+
+门槛是未命中端到端下降至少 35%。四张盘都没到。渲染快捷路径默认关闭。
+
+## 分段中位数（秒）
+
+| 盘 | 中文渲染 A → B | 英文渲染 A → B | 建包 A → B |
+| --- | --- | --- | --- |
+| day | 23.55 → 17.04（−27.6%） | 8.27 → 8.67 | 22.55 → 16.08 |
+| night | 23.42 → 17.19（−26.6%） | 8.75 → 8.41 | 23.70 → 17.21 |
+| south | 23.89 → 17.39（−27.2%） | 8.66 → 8.74 | 22.90 → 16.87 |
+| section2 | 22.26 → 17.80（−20.0%） | 8.14 → 8.54 | 31.24 → 21.08 |
+
+中文渲染门槛是下降至少 40%。没到。没有继续加整篇替换的预检。
+
+## 内存与字节
+
+tracemalloc 峰值：B 约为 A 的 0.87 到 0.88，没有升高。
+
+五份输出（整份响应、中文、英文、事实表、适用性）A、B 未命中、缓存命中的 sha256 全部相同。
+
+| 盘 | 响应字节 | 响应 sha256 前 12 位 |
+| --- | --- | --- |
+| day | 2289867 | 5b542359d606 |
+| night | 2321638 | 89baa960c054 |
+| south | 2314369 | 250bf1ab246e |
+| section2 | 2238092 | 1d7afd481b1a |
+
+## 同盘缓存（命中，秒）
+
+| 盘 | 三次 | 中位 |
+| --- | --- | --- |
+| day | 0.059 / 0.054 / 0.057 | 0.057 |
+| night | 0.057 / 0.054 / 0.058 | 0.057 |
+| south | 0.059 / 0.054 / 0.057 | 0.057 |
+| section2 | 0.063 / 0.066 / 0.057 | 0.063 |
+
+命中字节与未命中相同，中位数远低于 1.5 秒。缓存开关默认开。`GITHUB_SHA` 缺失或为 `unknown` 时仍然关。
+
+## 单次溯源哈希（交付包，秒）
+
+关：1.132 / 1.099 / 1.115，中位 1.115。开：0.402 / 0.466 / 0.388，中位 0.402。下降 64%，过了 50% 那一档。它跟渲染快捷路径用同一个开关，所以默认也是关。
+
+## json 与 reference 版
+
+同一份解盘、时钟钉死后，`format=json` 和 reference 版 markdown 在快捷路径关与开时 sha256 相同（`aa1352619b7a`、`cbadf95f549a`）。对比的是整份响应，没有丢掉字段。
+
+连续两次重新解盘会对不齐：有的特质列表挂在类上，第二次会再追加。那不是这条快捷路径改出来的。生产要的完整数据 markdown 在多次重算里仍然逐字节相同。