jesse-uxandGrok (agent loop)
81e2e1cfed
排盘缓存、官方快照、负缓存、网关任务和分盘段过期后会删掉。同一张盘的数字写法合成一把缓存键。失败快照只用短期限。自测留存、异步任务、增长合同、安全缓存和隐私标记；一万个文件的清理慢于 2 秒，命中率提升不到 2.5 倍，都按实测写入记录。 Co-Authored-By: Grok (agent loop)
52 lines
5.1 KiB
Markdown
52 lines
5.1 KiB
Markdown
# PROGRESS · API 磁盘缓存留存（2026-10-14）
|
||
|
||
- 分支：`codex/api-disk-cache-retention-20261013`
|
||
- 任务书基线写的是 `77057a819`。本分支从当时的 `origin/staging` `66cd60081f37a57680274633fcb3fb942d01bb2f` 拉出。A/B 的父提交用的是这个 SHA，不是任务书里的旧基线。
|
||
- 接口文件行数：10946（验收口径 ≤ 10970）。类方法数和伪造点没有增加。
|
||
|
||
## 做了什么
|
||
|
||
- T1：新增 `scripts/api_scratch_retention.py`。启动时清理全部已登记目录，并按 `JYOTISH_SCRATCH_PRUNE_INTERVAL_SECONDS`（默认 1800，0 表示不启后台线程）周期清理。排盘缓存新文件改为仅本人可读，先写临时文件再换上。`prune_expired_async_jobs` 只留同名薄包装。
|
||
- T2：`VEDASTRO_WRITE_AUDIT_ARTIFACTS` 默认关。关掉时不写审计文件，`artifact_path` 为 `None`。打开时写紧凑 JSON，仅本人可读，先写临时文件再换上。成功快照仍用原 TTL；失败、不完整、被挡住的用短 TTL，默认 300 秒，并且不超过成功 TTL。旧缓存没有 `negative` 标记时仍按成功的长期限读。状态接口改报含回落的成功期限，并多报失败期限。`.env.cn.example` 只加了注释，两个 604800 没改。
|
||
- 成功的判据：`available is True` 且 `status == "ok"`。`partial` 即使 `available` 为真也算失败缓存。
|
||
- T3：年月日能整除才收成整数，不截断 1990.5。时分秒和经纬度、时区能解析成有限数字就收成浮点，不四舍五入。解析不了的保持原值。日期取前 10 位，空值仍是空值。缓存格式版本 5 → 6。快速排盘和完整排盘仍是两把键。
|
||
- T4：前台快照、负缓存、网关任务、分盘段都进了登记表。只删符合原文件名的过期文件。网关排队中和进行中的不删。读写逻辑和键没改。
|
||
- T5：脚本在 `scripts/research/api_disk_cache_ab.py`，逐字节比较在 `scripts/research/api_chart_cache_byte_diff.py`。记录在 `docs/testing/api-disk-cache-retention-ab-20261013.md`。
|
||
- T6：没有改咨询卡片缓存。数字用任务书 §2.5，没有重测：未命中构建 1.9 秒；文件 5097751 字节；命中时解析中位 68.5 毫秒；整次命中 82.5 毫秒；两天大约每个活跃用户 10 MB。可选方向仍是两条：按领域切片只读需要的部分；清理改为每隔几分钟一次，而不是每次读取都扫全目录。没有做进程内已解析包缓存。
|
||
- T7：BUG-1330、BUG-1331、BUG-1332。变更说明一句。任务索引改为待验收。没有改界面说明。
|
||
|
||
## 命令和结果
|
||
|
||
| 检查 | 命令 | 结果 |
|
||
| --- | --- | --- |
|
||
| 新留存、异步任务、增长合同 | `pytest tests/test_api_scratch_retention.py tests/test_api_async_job_contract.py tests/test_api_server_growth_contract.py -q` | 26 通过 |
|
||
| 安全缓存 | `pytest tests/test_api_server_security.py -q -k cache` | 6 通过 |
|
||
| 任务书列出的 VedAstro / 咨询套件 | 见任务书 §8 那一条 | 4 失败，见下。其余通过 |
|
||
| 需要审计文件的执行器测试 | `pytest tests/test_vedastro_service_adapter_executor.py::test_vedastro_range_scan_records_hashes_and_artifact_path -q` | 1 通过 |
|
||
| 逐字节比较与 A/B | `python scripts/research/api_disk_cache_ab.py` | 退出码 0。命中率 B/A = 1.333。七天后 B 剩 40 个文件，等于当天键数。审计文件 0。负缓存剩 1。一万个文件的清理 20.174 秒 |
|
||
| 接口行数 | 按换行计数 | 10946 |
|
||
|
||
既有断言改动只有一处，在 `tests/test_vedastro_service_adapter_executor.py`：原值是子进程沿用进程环境；新值是显式打开审计落盘；原因是默认关闭后这条测试仍要检查文件存在。这是测试前置，不是放宽断言。
|
||
|
||
## 未达到的目标（目标不改）
|
||
|
||
- 混合写法再重复 3 次时，命中率只是 A 的 1.333 倍，不是 2.5 倍。重复本身已经让 A 命中三分之二。
|
||
- 一万个过期文件的清理用了 20.174 秒，不是 2 秒内。清理不在请求线程。默认间隔和失败短期限没有因此改掉。
|
||
|
||
## 本机套件里原先就会红的三条
|
||
|
||
- `tests/test_vedastro_gateway.py` 要求原始响应文件权限是 0600。Windows 报出来的是可写，不是 0600。这条断言没改。新测试在 Linux 上仍检查 0600，Windows 上只检查文件写出来了。
|
||
- `tests/test_vedastro_runtime_ops.py` 要求已安装的 VedAstro 是 1.23.25，本机是 1.23.30。与这次缓存改动无关。
|
||
- `tests/test_three_engine_parity_runner.py` 的公开盘回放把 PyJHora 记成 raw_imported，不是 structured_captured，同时在下载星历。运行器没改。
|
||
|
||
## 环境缺口
|
||
|
||
- 生产和测试环境里成功缓存的实际秒数，这份仓库读不到。部署后看状态接口的两个期限数字即可。
|
||
- 生产卷上已经堆了多少文件，这里不知道。
|
||
- 主测量挡住了 VedAstro 导入。本机有 SDK，官方端口能连通。不挡 SDK 的探针仍关闭外网取数，一次完整排盘 4.167 秒，没有报错，没有拉真实快照。
|
||
|
||
## 未做
|
||
|
||
- 没有改部署文件、生产环境变量、数据库，也没有手工清生产卷。
|
||
- 没有把咨询卡片缓存并进周期清理。
|