x-iztro
x-iztroRustPythonGo

排盘入口

by_solar、by_lunar、rearranged 与 JSON 便捷版本。

排盘是一切的起点：给出生日期、时辰、性别，得到一张 Astrolabe。 本页是四个排盘入口的完整参考。

收外部输入的入口（by_solar、by_lunar、两个 JSON 版本、get_horoscope）都返回 Result：日期格式与存在性、公历年份范围、时辰索引在核心层前置校验，非法输入返回 IztroError 而不是 panic。入参全是枚举、无非法值的函数（rearranged、 astrolabe_to_prompt）直接返回结果。错误类型见错误处理。

by_solar

用途　由公历日期排出本命盘。

斗数含义　紫微斗数以农历为算法基础，但绝大多数人只记得公历生日。 本函数先把公历转农历（含年干支、月干支、日干支、时干支四柱），再据此安星。 换年的时点受 year_divide 影响——正月初一与立春之间出生的人，两种配置会得到不同的年干支， 进而影响四化、命主身主与全部年系星。

签名

pub fn by_solar(
    solar_date: &str,
    time_index: u8,
    gender: Gender,
    fix_leap: bool,
    language: Language,
    config: Config,
) -> Result<Astrolabe, IztroError>

参数

参数类型必填默认说明
solar_date&str是—公历日期，格式 YYYY-M-D，月日不必补零。支持 1583–9999 年
time_indexu8是—时辰索引 0–12。0 为早子时（00:00–01:00），12 为晚子时（23:00–24:00）
genderGender是—Gender::Male 或 Gender::Female。决定大限顺逆与长生、博士十二神的排列方向
fix_leapbool是—是否调整农历闰月。为 true 时闰月十六日起按下月算（晚子时除外，见下）
languageLanguage是—输出语言，影响 DTO 中所有译名字段；*_key 标识字段不受影响
configConfig是—排盘配置，六个开关加自定义表。取默认值用 Config::default()

返回值　Astrolabe——十二宫、四柱、命主身主、五行局俱全的完整星盘。字段清单见数据结构。

示例

use x_iztro::*;

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;

println!("{} | {} | {}", chart.solar_date, chart.lunar_date, chart.chinese_date);
println!("{} {} {}", chart.sign, chart.zodiac,
    translate_five_elements_class(chart.five_elements_class, Language::ZhCN));
println!("命主 {} 身主 {}",
    translate_star(chart.soul, Language::ZhCN),
    translate_star(chart.body, Language::ZhCN));

five_elements_class、soul、body 是强类型枚举而非字符串—— 判断时直接比较，要展示则经 i18n::translate_* 转成当前语言的文本。

输出

2000-8-16 | 二〇〇〇年七月十七 | 庚辰 甲申 丙午 庚寅
狮子座 龙 木三局
命主 破军 身主 文昌

边界与陷阱

by_lunar

用途　由农历日期排出本命盘。

斗数含义　农历日期是斗数的原生输入，跳过公历转换这一步。 知道自己农历生日的人直接用它，结果与用对应公历日期调 by_solar 完全一致。

签名

pub fn by_lunar(
    lunar_date: &str,
    time_index: u8,
    gender: Gender,
    leap: LeapMonth,
    language: Language,
    config: Config,
) -> Result<Astrolabe, IztroError>

参数

除以下两项外，其余与 by_solar 相同；by_solar 的 fix_leap 在这里并入 leap。

参数类型必填默认说明
lunar_date&str是—农历日期，格式 YYYY-M-D，月份写正数（闰月由下一参数标记）
leapLeapMonth是—NotLeap 非闰月；Leap 闰月、按闰月本身排；LeapFixed 闰月且十五之后视作次月（iztro fixLeap）。标为闰月但那年那月没有闰月时按普通月处理

返回值　同 by_solar。

示例

use x_iztro::*;

let a = by_lunar("2000-7-17", 2, Gender::Female, LeapMonth::NotLeap, Language::ZhCN, Config::default())?;
let b = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;

assert_eq!(a.solar_date, b.solar_date);
println!("{}", a.solar_date);

输出

2000-8-16

边界与陷阱

标错闰月的静默失效是刻意的

leap 标为闰月但那个月并非闰月时，按普通月排盘，不报错（与 iztro 一致）。 如果需要严格校验，调用前先自行确认该年该月确实有闰月。 LeapMonth::from_flags(is_leap_month, fix_leap) 可从 iztro 风格的两个布尔换算。

rearranged

用途　以指定干支为命宫重排本盘，返回新盘；原盘不变。

斗数含义　中州派把同一组出生数据看作三张盘：天盘以命宫干支起五行局， 地盘以身宫干支起，人盘以福德宫干支起。起局的干支一变，五行局就变， 紫微天府落点、十二宫名、长生十二神、大限小限随之全部重算。 本方法把这个能力放开到任意干支，不限于那三种。

签名

pub fn rearranged(&self, from_stem: HeavenlyStem, from_branch: EarthlyBranch) -> Astrolabe

参数

参数类型必填默认说明
from_stemHeavenlyStem是—新命宫的天干
from_branchEarthlyBranch是—新命宫的地支

返回值　新的 Astrolabe。重算：命宫身宫、五行局、十四主星、十二宫名、长生十二神、大限小限， 以及随命宫挪位的天伤、天使、天才。沿用原盘：辅星、其余杂耀、博士十二神、岁前与将前十二神。

示例

use x_iztro::*;

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;

// 从原盘身宫的干支起盘，等价于地盘
let body = chart.palaces.iter().find(|p| p.is_body_palace).unwrap();
let earth = chart.rearranged(body.heavenly_stem, body.earthly_branch);

println!("天盘 {} → 地盘 {}",
    translate_five_elements_class(chart.five_elements_class, Language::ZhCN),
    translate_five_elements_class(earth.five_elements_class, Language::ZhCN));

输出

天盘 木三局 → 地盘 土五局

边界与陷阱

常规三盘不必用这个方法

天盘、地盘、人盘用 Config::default().with_astro_type(AstroType::Earth) 直接排即可， 两个排盘入口都支持。rearranged 是为「从任意干支起盘」准备的。

by_solar_json / by_lunar_json

用途　排盘并直接返回 DTO 的 JSON 字符串，省掉调用方自己序列化。

签名

pub fn by_solar_json(
    solar_date: &str,
    time_index: u8,
    gender: Gender,
    fix_leap: bool,
    language: Language,
    config: Config,
) -> Result<String, IztroError>

pub fn by_lunar_json(
    lunar_date: &str,
    time_index: u8,
    gender: Gender,
    leap: LeapMonth,
    language: Language,
    config: Config,
) -> Result<String, IztroError>

参数　与对应的排盘函数完全相同。

返回值　String——DTO 的 JSON 序列化结果， camelCase 键、值按 language 翻译，另带 *Key 语言无关标识。

示例

use x_iztro::*;

let json = by_solar_json("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let v: serde_json::Value = serde_json::from_str(&json)?;

println!("{} {}", v["solarDate"], v["palaces"][0]["nameKey"]);

输出

"2000-8-16" "wealthPalace"

边界与陷阱

这两个函数只是 by_solar(...)?.to_dto() 加序列化的快捷方式。 Rust 侧要做进一步分析时用 by_solar 拿 Astrolabe，能用上全部查询方法； 只是要把结果丢给别的进程或前端时才用 JSON 版本。

get_horoscope

用途　以某张本命盘为起点计算目标日期的运限。

斗数含义　运限是把大限、小限、流年、流月、流日、流时六个层级叠在本命盘上， 每一层各有自己的宫位起点、干支与流耀。

签名

pub fn get_horoscope(
    astrolabe: &Astrolabe,
    solar_date: &str,
    time_index: u8,
    language: Language,
) -> Result<HoroscopeData, IztroError>

参数

参数类型必填默认说明
astrolabe&Astrolabe是—本命盘
solar_date&str是—目标公历日期，格式 YYYY-M-D，支持 1583–9999 年
time_indexu8是—目标时辰索引 0–12
languageLanguage是—输出语言

返回值　Result<HoroscopeData, IztroError>。详见运限对象。

示例

use x_iztro::*;

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let h = get_horoscope(&chart, "2025-1-1", 0, Language::ZhCN)?;

println!("大限宫位索引 {}，流年干支 {:?}{:?}",
    h.decadal.index, h.yearly.heavenly_stem, h.yearly.earthly_branch);

输出

大限宫位索引 2，流年干支 JiaChen

边界与陷阱

要连着做运限查询（取某层级的宫位、判断流耀）时，用星盘方法 chart.horoscope(...) 拿 HoroscopeRef——它同时持有本命盘， 查询不必再把星盘传进去。这里的自由函数只返回数据本身。

astrolabe_to_prompt / horoscope_to_prompt

用途　把星盘或运限渲染成适合喂给大模型的纯文本。

签名

pub fn astrolabe_to_prompt(astrolabe: &Astrolabe, lang: Language) -> String
pub fn horoscope_to_prompt(
    astrolabe: &Astrolabe,
    horoscope: &HoroscopeData,
    lang: Language,
) -> String

参数

参数类型必填默认说明
astrolabe&Astrolabe是—本命盘
horoscope&HoroscopeData是—get_horoscope 的结果
langLanguage是—输出语言，随之切换段落标题与星耀译名

返回值　String，分节的纯文本。

示例

use x_iztro::*;

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
print!("{}", astrolabe_to_prompt(&chart, Language::ZhCN));

输出

=== 基本信息 ===
性别: 女
阳历: 2000-8-16
农历: 二〇〇〇年七月十七
干支: 庚辰 甲申 丙午 庚寅
时辰: 寅时 (03:00~05:00)
星座: 狮子座
生肖: 龙
命宫地支: 午
身宫地支: 戌
命主: 破军
身主: 文昌
五行局: 木三局
生年四化: 太阳禄, 武曲权, 太阴科, 天同忌

=== 十二宫 ===

--- 财帛 ---
天干地支: 戊寅
大限: 43-52
小限虚岁: 9, 21, 33, 45, 57, 69, 81, 93, 105, 117
十二神: 绝, 飞廉, 吊客, 岁驿
主星: 武曲(得)[权], 天相(庙)
辅星: 天马
杂耀: 解神, 三台, 天寿, 天巫, 天厨, 阴煞, 天哭

（以下十一宫格式相同，此处从略）

完整输出与逐字段说明见生成 AI 提示词。

这是 x-iztro 在 iztro 之外自加的功能，三语言均可用。 用法与提示词写法见让 AI 解读命盘。

概览

crate 结构、类型体系与阅读本参考的方式。

星盘对象

Astrolabe 的字段、定位方法与三方四正判断。

本页目录

by_solarby_lunarrearrangedby_solar_json / by_lunar_jsonget_horoscopeastrolabe_to_prompt / horoscope_to_prompt