# PROGRESS · 引擎卫生：限流状态、静默失败、功能吉凶兜底

- 日期：2026-10-15
- 分支：`codex/python-hygiene-20261013`
- 基线：`origin/staging` `e4ff62c73856d1e10d44f42f998e94835b8acdf0`
- 前置：`dbba127e715759f0e225fc57faf12508a01d2380` 是该基线的祖先
- BUG：BUG-1340。本分支最大已用编号是 BUG-1357，1340 空着，按任务书使用，不顺延。

## 做了什么

1. 免费层「是否在限流」改成读适配器里的真实判断：官方公共端点、没有 API key、配额窗口大于 0。三个旧变量名还在，只在诊断里标成已废弃，不能拿来关掉限流。网关离线排队仍用原来的另一组变量。
2. 功能吉凶兜底收成 `scripts/functional_layer.py` 一处。引擎、接口、MCP 都转发到它。正常成功的结果与原来逐字节一致。`functional_benefics.py` 未改。
3. 会让结果少一块的静默失败改为记下模块名、函数名和错误类型。预期内的失败保持安静，并写明原因。裸 `except` 里任务点名的两处引擎、星宿大运和星宿命令已改成 `except Exception`。
4. 快速门加入静默失败计数和 `scripts/` 根目录 `.py` 数量两条只许下降的守卫。

## T3 分类

写作时口径是 29 处。本基线多了 `scripts/api_scratch_retention.py::_loop`（前序单新增），收尾 30 处。A 类 14 处不计入守卫；B 类 16 处改为记日志。未收窄 A 类的异常类型：不能证明只会抛某一种。

| 类 | 位置 | 处理 |
| --- | --- | --- |
| A | `annual_tajika_pack._iana_timezone_id` | 时区名解析失败保持安静，`# noqa: BLE001` |
| A | `api_scratch_retention._loop` | 清理循环必须活着，保持安静 |
| A | `jyotishganit_shadbala_surface_probe.clean` | 探针清理失败保持安静 |
| A | `jyotish_engine.write_pl9_pdf` 字体循环 | 换下一个字体，最后仍可用 Helvetica |
| A | `local_oss_observation_inventory.git_commit` | 读不到提交号保持安静 |
| A | `muhurta` 导入 swisseph | Windows 上动态库失败不一定是 ImportError，保持安静 |
| A | `nakshatra_dasha.calc_nakshatra_dasha_breakdown` | 日期文本解析失败不改变年龄明细；裸 `except` 已改为 `except Exception` |
| A | `oracle_boundary_audit._date_delta_days` | 日期文本解析失败保持安静 |
| A | `tajika._resolve_external_pyjhora_python` | 外部解释器探测失败保持安静 |
| A | `vedastro_gateway._sdk_version` | 可选依赖版本读不到保持安静 |
| A | `vedastro_python_bridge` 序列化兜底 | 对象转 JSON 失败再走原兜底 |
| A | `yoga_engine` 自定义表达式 3 处 | 每条规则都可能失败，保持安静 |
| B | `cmd_muhurta._get_sun_moon_lons` | 记下错误类型后仍走近似日月位置 |
| B | `cmd_nakshatra_adv.cmd_nakshatra_dasha` | 过境位置失败记日志；裸 `except` 已改为 `except Exception` |
| B | `daily_guidance_service._current_mahadasha` | 记日志，返回值不变 |
| B | `jyotish_engine._conflict_arbitration` | 记日志；裸 `except` 已改为 `except Exception` |
| B | `jyotish_engine.cmd_planetary_congregation` | 记日志 |
| B | `jyotish_engine.cmd_full_reading` 过境位置 | 记日志；裸 `except` 已改为 `except Exception` |
| B | `muhurta` 日出、儒略日、日月位置 3 处 | 记日志，返回值不变 |
| B | `pl9_full_data_export` 中英 Sudarshana 各 1 处 | 记日志。报告正文不写「本段数据缺失」（需拍板） |
| B | `reference_transparency_contract._case_chart` | 记日志 |
| B | `solar_return._get_sun_lon_jd` | 记日志 |
| B | `tajika._year_lord_is_daytime` | 记日志 |
| B | `transit_trigger._get_transit_lon_precise` | 记日志 |
| B | `mcp_server.strict_workflow` | 记日志 |

引擎里另外三处裸 `except` 会赋值（记忆统计、两处年龄推算），不在本口径，未改。

## 断言

| 位置 | 原值 | 新值 | 原因 |
| --- | --- | --- | --- |
| `tests/test_api_server_security.py` 高严谨官方摘要 `queue_enabled` | False | True | 没设置已废弃开关时，官方免费层默认仍在限流 |
| `tests/test_vedastro_user_entrypoint.py` 两处 `free_tier_queue_enabled` / `queue_enabled` | True | True | 该用例没有 key、端点是官方地址、配额为正。字段跟随真实限流，不再跟随废弃开关 |

## 全量解读对照

同一虚构盘、同一随机种子、关闭网络。退出码 0，标准错误 20 字节。标准输出 5236527 字节，摘要哈希与开工前基线不同。逐项对比只有 29 处差异：缓存创建和过期时间、耗时、最慢阶段的名次、结果哈希、一份大运的参照时钟。`modules.functional_benefic_malefic` 排序后逐字节相同，长度 1442。

## 反向验证

人为在 `scripts/functional_layer.py` 加一处 `except Exception: pass`，并在根目录加一个空 `.py`，然后立刻删掉。

```
FAILED tests/test_python_hygiene_budget.py::test_silent_except_budget_does_not_grow
AssertionError: ['scripts/functional_layer.py:46']
assert 1 <= 0
FAILED tests/test_python_hygiene_budget.py::test_scripts_root_py_count_does_not_grow
AssertionError: 447
assert 447 <= 446
```

撤回后根目录仍是 446。守卫测试 2 通过。

## 检查

| 检查 | 命令 | 结果数字 |
| --- | --- | --- |
| 定向测试 | 任务书 Grok 自测清单，外加功能层快照 3 条、改过的安全断言 1 条 | 77 项，76 通过，1 失败 |
| 失败项 | `test_gateway_completion_archives_official_raw_response` | `st_mode & 511` 实得 438，期望 384 |
| 静默守卫 | `tests/test_python_hygiene_budget.py` | 2 通过；未标记静默 0；带 noqa 的 A 类 14 |
| 功能层快照 | `tests/test_functional_layer_snapshot.py` | 3 通过 |
| 根目录 `.py` | `scripts/*.py` | 446（含新建的 `functional_layer.py`） |

失败的那条断言检查归档文件权限必须是 `0o600`。本单在 `vedastro_gateway.py` 只加了一行静默原因注释，`os.chmod(..., 0o600)` 未改。Windows 回报的权限位是 `0o666`。断言不放宽。

## 偏离

- T4 测试脚本归位未做。任务书让步顺序第一项，避免搬动被证据索引或冻结清单钉住的文件。
- T5 第 2 条做了：根目录上限按收尾实测 446，只许下降。
- A 类没有收窄异常类型。
- 报告正文不增加「本段数据缺失」。
- `skills/jyotish-vedic-astrology/scripts/` 里的旧排队开关解析未改。任务书文件清单不含它，也没有字节对照测试。
- 不改前端、依赖、`.gitea/**`、生产配置、冻结文件。