# 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` 在每次调用时删掉两天前的文件。没有改两个缓存模块的行为。