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 次打回。