vedic-astro-skills 是一个吠陀占星（Vedic/Jyotish）AI 分析工具包，可以从出生信息直接排盘并进入完整本命分析。它的排盘引擎采用fail-fast（快速失败）容错设计：缺依赖、时间非法或关键校验失败时直接停止并给出修复路径，绝不回退到"能跑但会算错"的备用算法——因为对占星分析而言，一个看似完整的错误结果，比没有结果更糟。

为什么"差不多对"的结果最危险？

普通计算工具算错一个数，用户可能看不出来；但占星分析里，一个错误会沿着整条链路放大：

• Lagna（上升点）偏一点 → 12 宫全部错位 → 宫主表、分盘、Dasha 全错；
• Shadbala 百分比错 → 行星强弱判断反转 → 分析结论直接带偏；
• Dasha 大运边界偏几天 → "某年某月发生的事"对不上，验前事彻底失真。

这套工具包在 v6.1 之前就有过真实教训：早期版本在依赖缺失时会悄悄切换到备用算法（fallback）。事后逐一对账才发现，备用 SAV 有 5/12 个星座值不同，备用 Shadbala 的 6 个子项全错，备用 Dasha 偏差 6~9 天——报告格式完好、数字却不可信。正是这次对账促使 v0.5 版引擎移除所有 fallback，确立了 fail-fast 架构。相关记录可查 CHANGELOG.md。

fail-fast 是什么？和 fallback 差在哪？

fail-fast 的核心信念：宁可让你多花 1 分钟修环境，也不让你拿着错误星盘做几周分析。

第一层防线：依赖加载即校验，不达标不进计算

排盘引擎 engine.py 启动时会做两件事：

1. 核心模块"全有或全无"

SAV（Ashtakavarga）、Shadbala、Dasha 三个核心模块必须全部加载成功，任何一项缺失就打印FATAL错误、列出每个失败原因，并直接提示运行 setup_env.py 修复——而不是"缺哪块用哪块"：

❌ FATAL: 以下核心模块加载失败: Dasha → dasha_pyjhora: ... ╔══════════════════════════════════════════╗ ║ PyJHora 未正确安装！请运行: ║ ║ python vedic-calculator/scripts/setup_env.py ║ ╚══════════════════════════════════════════╝

2. 空壳依赖主动识别

pysweph 是 C 扩展，某些系统 Python 里装的只是"空壳"（只有元数据、没有真正的.pyd）。引擎检测到这种情况会给出可执行的纠正指令（改用 skill 自带 venv 的 Python），而不是抛一个让人摸不着头脑的 ImportError。

配套的环境诊断脚本 check_env.py 让这套防线前移到"第一次使用前"：它自动定位 venv、检查 pysweph / PyJHora / pytz 三项依赖、检测 swisseph 空壳、验证星历表文件，并用一个最小计算测试SAV 总和 = 337做终检。输出 🎉 就按它报告的 Python 路径直接用，输出 ⚠️ 就按提示跑 setup_env.py 修复。

💡 SAV=337 是一个天然的"金丝雀"：12 星座 × 最多 28 分，正确算法的总和恒为 337。它把"算法对不对"压缩成一次== 337的判断。

第二层防线：输入端严格化，拒绝"猜"你的时间

出生时间是占星计算的命根，引擎在输入端埋了两道"不猜"的闸门：

• 夏令时严格定位：_localize_strict使用pytz.localize(is_dst=None)——如果出生时刻落在夏令时切换的跳过时段（该时刻不存在）或重复时段（钟表回拨，该时刻出现两次），直接抛出带解释的ValueError，告诉你"请确认出生记录用的是夏令时还是标准时间"，而不会静默猜一个（错 1 小时 = 上升和 Dasha 全错）。
• 时区只认 IANA 名称：传数字偏移（如8、5.5）直接报错并提示改填时区名。因为中国 1986–1991 年夏季实际是 UTC+9，"固定 +8" 会让整个计算中心偏 1 小时。

这一层的设计哲学：输入有歧义时，停下来问，而不是默默选一个分支。

第三层防线：输出端 12 项校验，✅ 必须"挣"出来

引擎算完后，formatter.py 生成的structured_data.md末尾带 12 项自动校验。其中有一段"打假"历史：曾有 8 条校验项是写死的 ✅——格式上像校验了，实际什么都没验。后来全部改为真判定，且刻意走与引擎不同的推导路径才算交叉验证，例如：

• Nakshatra：由行星经度独立重算 pada，再比对引擎结果；
• Chara Karaka：按度数独立降序重排，比对 DK 归属；
• Rahu–Ketu：在 D9 分盘中必须恒差 6 座；
• 燃烧行星：必须落在 Sun 最宽 orb 内，且 Sun 不得自列。

团队还用9 个篡改探针做了反向测试（故意喂错数据看校验是否变红）：8 项确认变红；"缺星"那项根本走不到校验区——上游表格已因KeyErrorfail-fast 崩掉，这恰好证明了防线在更早就生效了。

此外，Dasha 时间线必须满足9 段大运 + 81 段小运 + 729 段三级运，每层区间[start,end)无缝连续；分盘 D1/D9/D10/D4/D5 会在出生时间的不确定区间内逐分钟重算 Lagna，分别标记"稳定 / 边界敏感 / 未审计"——"算得出"和"输入稳定"是两件事，绝不混为一谈。这些规则在 SKILL.md 的 Step 4 有完整清单。

第四层防线：旧 API 变成"响亮的路障"

最容易被忽视的是遗留入口。引擎里旧的自建calc_vimsottari_dasha（基于 365.25 天近似）被彻底禁用：

def calc_vimsottari_dasha(...): raise RuntimeError( "calc_vimsottari_dasha is disabled: use calculate_full_chart() ..." )

为什么不直接删掉？因为删掉会让老调用方报"函数不存在"，而保留一个立即抛错的 shim（占位壳），则老代码一碰就响，且报错信息直接告诉你正确入口是什么。这是 fail-fast 在"代码演化"维度的延伸：让错误死得响，而不是让旧算法在暗处复活。

把 fail-fast 用起来：新手检查清单 📋

如果你是第一次在这套工具里排盘，按这个顺序走，防线会自动护住你：

1. 先跑环境诊断：python <skill目录>/scripts/check_env.py，看到 🎉 再排盘；
2. 用对 Python：优先 skill 目录下的 venv，别用系统 Python（空壳重灾区）;
3. 出生时间给全：日期 + 24 小时制时间 + 城市 + 时区名；夏令时地区按提示确认"墙上钟"；
4. 看校验区：structured_data.md生成后核对 SAV=337、10 颗行星齐全、Dasha 三层无缝；
5. 报错时照做：每条 ❌ 都附修复路径（通常是 setup_env.py），不需要猜。

小结：容错的最高形式是"不产出错误"

vedic-astro-skills 的 fail-fast 设计可以概括为一句话：把"错误"从结果里搬到过程里。

对 AI 工具来说，模型天然倾向于"把话说圆"，而这套工具包用确定性的工程手段给它立了边界：算不准就停，停得明白，修得清楚。这也是为什么它的 README 敢于把"容错 = fail-fast"写进技术架构表，而不是含糊地写一个"准确率 >97%"（README.md 明确放弃了那种无法持续审计的笼统说法）。

如果你要搭建自己的 AI 计算类工具，这个思路值得直接抄：在依赖、输入、输出、遗留接口四个位置都设"响亮的路障"，宁可报错，不可算错。