从 iztro 迁移：API 对照

适合：开发者，尤其是从 JS iztro 迁移过来的

x-iztro 是 iztro v2.6.1 的移植。 iztro 的每个公开 API 在 Rust、Python、Go 三侧都有等价物， 三侧能力完全一致，形式各随语言习惯。

这一页写给从 iztro 迁移过来的人：名字对不上时来这里查。 逐个 API 的用法见各语言的 API 参考。

名字直接对得上的

其余同理：JS 的 camelCase 在 Rust / Python 下是 snake_case，在 Go 下是 PascalCase。

换了形状的

这几处不是照抄，因为照抄会把 JS 的限制一起搬过来。

排盘视角（天盘 / 地盘 / 人盘）

iztro 把 astroType 放在 astro.withOptions 的选项对象上， 是因为它的 astro.config() 是全局单例、装不下按盘变化的值。

x-iztro 的配置本来就随每次排盘传入，因此 astroType 直接收进 Config， 两个排盘入口都能用，不必再记一个入口：

from x_iztro import Astro, ChartConfig

chart = Astro().by_solar("2000-8-16", 2, "female",
                         config=ChartConfig(astro_type="earth"))

从任意干支起盘对应 rearrangeAstrolable，三侧都是星盘方法 rearranged(干, 支)。

没有全局配置与全局语言

iztro 的 astro.config()、i18n.setLanguage() 改的是模块级单例， 因此还需要 astro.getConfig() 把值读回来。

x-iztro 没有全局状态：配置与语言都随每次调用传入，由调用方自己持有。 所以不提供 getConfig 与 setLanguage —— 想读回来，读你自己那份就是。

大限小限

astro/palace 的 getHoroscope(param) 收一份 AstrolabeParam。 x-iztro 的 get_decadals_and_ages 直接收命宫索引与五行局， 不必先凑出一份出生数据，能力是 iztro 那个的超集。

农历入口的闰月参数

byLunar(lunarDateStr, timeIndex, gender, isLeapMonth?, fixLeap?, language?) 用两个相邻的布尔 描述闰月：写反了不报错，盘会静默错一个月，而 fixLeap 又只在输入是闰月时才有意义。 x-iztro 把两者合成一个三态值：Rust LeapMonth::{NotLeap, Leap, LeapFixed}、 Go NotLeapMonth / LeapMonthKeep / LeapMonthFixed；Python 保留两个布尔但改为只能按关键字传入 （is_leap_month=、fix_leap=）。绑定层的 JSON 线协议仍是 isLeapMonth/fixLeap 两个键， 与 iztro 一致。阳历入口的 fixLeap 单独一个布尔，没有写反的余地，保持不变。

Go 侧同理把 gender、language 做成具名字符串类型 Gender / Language （GenderFemale、LanguageZhCN），字面量仍可直接传，但别的字符串变量传错位置会在编译期被挡下。

插件

iztro 的 loadPlugin / use(plugin) 是运行期往星盘对象上挂函数 —— 这是 JS 缺少其他扩展手段的产物。三侧各按语言给出的答案实现同一能力， 都是编译期或加载期完成，不牺牲类型检查：

写法见扩展星盘。

反查译名时的消歧

kot(value, k) 的第二个参数在三侧是独立入口： key_of_in（Rust）、key_of(text, key_filter)（Python）、KeyOfIn（Go）。 取值与 iztro 逐例一致，包括 horse、dragon、유시（韩语的酉时）这类同形译名落到哪个标识。

不提供的

行为上要注意的几处

自定义四化表与亮度表只收标识

Config 的 mutagens / brightness 两张覆盖表只接受语言无关标识： "ziweiMaj" 可以，"紫微" 不行 —— 收译名会让配置绑死在某种盘面语言上。

覆盖表长度严格校验

四化表必须给满 4 项（禄权科忌），亮度表必须给满 12 项（第一项是寅宫）， 多一项少一项都直接报 invalid_argument，不做补齐也不做截断。 见 Config 详解。

覆盖表不回显在输出的 config 里

星盘上回显的 config 只有六个开关。覆盖表是排盘的输入， 放进 DTO 会破坏与 iztro 的字段契约，所以读回来是空的 —— 要留档自己存。

比 iztro 多的

格局判定（iztro 无对应 API）

iztro 没有格局相关的 API，x-iztro 在排盘之上加了一层格局判定引擎： 64 条格局，本命盘与运限盘共用同一套规则，命中带成格宫位、口径（variant）、 破格标记（broken）与证据星。规则条目、示例盘与古籍引文取自 iztro-docs 的《格局》页 （MIT License，作者 Sylar Long），判定实现、六语言格局名与多种说法之间的取舍是 x-iztro 的工作。

三侧的入口：Rust 的 Astrolabe::patterns / HoroscopeRef::patterns、 Python 的 Astrolabe.patterns / Horoscope.patterns、 Go 的 Astrolabe.Patterns / Horoscope.Patterns， 另有语言无关的格局标识（Rust PatternKey、Python PatternKey、Go PatternXxx 常量）。 概念与 64 条总表见格局。

因为 iztro 没有对应实现，这部分没有金标数据，正确性由四层测试守着： 每条规则的单测、来源页 32 张示例盘的真实盘复现、tier1 那 1,560 张盘上的批量不变量检查， 以及三侧共读的输出快照。

知识包（iztro 无对应 API）

iztro 只给事实，星耀与格局的解读文本在它的文档站上、不在库里。 x-iztro 把解读做成一份协议化的数据：知识包是「语言无关标识 → 文本与属性」的 JSON， 库里内嵌一份默认包（107 颗星、64 条格局、12 宫、4 化、49 条术语， 取自 iztro-docs 的《学习》各页，MIT License，作者 Sylar Long）， 不认同其中说法可以写覆盖包按字段合并。

三侧的入口：Rust 的 KnowledgePack::builtin / merged、 Python 的 KnowledgePack.builtin / merged、 Go 的 BuiltinKnowledgePack / Merged，合并只在 Rust 内核实现一处。 星耀的阴阳五行、斗分、化气这类属性也在包里而不进核心数据表—— 核心的 StarInfo 与 iztro 逐值一致，属性是门派说法。 见知识包。

反推（iztro 无对应 API）

iztro 只有「生辰 → 盘」一个方向。x-iztro 加上了反方向：solar_dates_by_bazi 由八字四柱反查公历生辰——四柱按传入 Config 的分界口径解释， 与 raw_dates.chinese_date 同一套语义；reverse_chart 由星盘特征 （命宫身宫地支、五行局、星耀落宫、生年四化）反查候选生辰。 两者都是「剪枝枚举 + 正排终验」，结果与正向排盘零分歧。 一组四柱约每 60 年重复一次，因此天然多解，候选拿去正排即可复现目标。

三侧的入口：Rust 的 solar_dates_by_bazi / reverse_chart、 Python 的 solar_dates_by_bazi / reverse_chart、 Go 的 SolarDatesByBazi / ReverseChart（各带 Context 变体）。 见反推。

其余增补

• 语言无关标识：星盘每个字段在译名之外同时给出 *key / *Key， 取值是 iztro 的 i18n key。判断逻辑因此不受盘面语言影响， 不必再反查译名。详见标识体系
• 语义化文本投影（to_text）：把星盘、运限、宫位或三方四正投影成自然语言文本， 喂大模型或直接给人读，见语义化文本
• 入口前置校验：非法日期、越界时辰等在入口返回错误而非 panic， 且带机器可读的分类码，见错误处理
• 自定义四化表与亮度表：按标识整表替换内置数据， 见 Config 详解
• all_keys：一次取全部 260 个可翻译标识

数值一致性

功能对齐之外，排盘结果与 iztro 逐字段零差异，由 716,314 例金标数据守着。 覆盖矩阵与验证方式见准确性保证。