Jyotisha/docs/tasks/PROGRESS-python-hygiene-20261013.md

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/**、生产配置、冻结文件。