# 文档 (/zh/docs)
紫微斗数排盘引擎：与 JS iztro 逐字段零差异，附格局判定、知识包与生辰反推，一次调用转成大模型可读文本。Rust 核心，Rust / Python / Go 直接调用。
把出生时间算成一张完整的紫微斗数命盘，并能一键转成大模型读得懂的文字 ——
**排盘归它算，解读归 AI**。
一次调用得到的就是这样一段 Markdown——下面是完整的基本信息、十二宫总览、格局与第一宫，
其余十一宫同款列全，直接贴进任何大模型就能开始问：
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座
- 五行局: 木三局 · 命主: 破军 · 身主: 文昌
- 命宫: 午 · 身宫: 戌 (官禄) · 来因宫: 辰 (夫妻)
- 生年四化: 太阳化禄→子女, 武曲化权→财帛, 太阴化科→仆役, 天同化忌→疾厄
## 十二宫总览
| 宫位 | 主星 | 辅星 | 大限 |
|---|---|---|---|
| **命宫** 午 | 紫微(庙) | 文曲(陷) | 3-12 |
| 兄弟 巳 | 天机(平) | — | 13-22 |
| 夫妻 辰 [来因宫] | 七杀(庙) | 右弼, 火星(陷) | 23-32 |
| 子女 卯 | 太阳(庙)化禄, 天梁(庙) | — | 33-42 |
| 财帛 寅 | 武曲(得)化权, 天相(庙) | 天马 | 43-52 |
| 疾厄 丑 | 天同(不)化忌, 巨门(不) | 天魁, 地劫 | 53-62 |
| 迁移 子 | 贪狼(旺) | 铃星(陷) | 63-72 |
| 仆役 亥 | 太阴(庙)化科 | — | 73-82 |
| 官禄 戌 [身宫] | 廉贞(利), 天府(庙) | 左辅 | 83-92 |
| 田宅 酉 | — | 地空, 擎羊(陷) | 93-102 |
| 福德 申 | 破军(得) | 文昌(得), 禄存 | 103-112 |
| 父母 未 | — | 天钺, 陀罗(庙) | 113-122 |
## 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
## 十二宫
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
…（其余十一宫依次列全）
```
排盘结果对不对，有一条可验证的硬标准：**与 JS [iztro](https://github.com/SylarLong/iztro)
v2.6.1 逐字段零差异**——这是复现口径，不是流派裁决——由 716,314 例金标测试守着，
见[准确性保证](/zh/docs/guide/about/accuracy)。默认口径与 iztro 一致，
中州派与各分界点[可切换](/zh/docs/guide/guides/config)。
## 从哪开始 [#从哪开始]
## iztro 没有的三件事 [#iztro-没有的三件事]
排盘之上的语义层，也是 AI 管线真正要用的部分——上游 iztro 没有对应 API：
## 按身份找路 [#按身份找路]
* **懂命理、不写代码** → [不写代码怎么用它](/zh/docs/guide/guides/for-non-developers)
* **后端 / AI 应用工程师** → [快速开始](/zh/docs/guide/getting-started)，然后看 [LLM 接入](/zh/docs/guide/guides/llm)
* **不了解紫微斗数** → [紫微斗数概念](/zh/docs/guide/concepts)，从干支与十二宫讲起
## 三种编程语言，同一套结果 [#三种编程语言同一套结果]
三套绑定调用同一份 Rust 核心，因此排盘结果逐字段相同。
判断方法基于语言无关标识，同一条分析规则用三种编程语言写出来，结果也一致。
```rust
use x_iztro::*;
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let soul = chart.palace(Palace::Soul).unwrap();
println!("{}", soul.has(&[StarKey::ZiweiMaj]));
```
```python
from x_iztro import Astro
chart = Astro().by_solar("2000-8-16", 2, "female")
soul = chart.palace("soulPalace")
print(soul.has(["ziweiMaj"]))
```
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.Has(iztro.StarZiweiMaj))
```
三段代码给出同一个判断：这张盘的命宫里有紫微星（Python 打印 `True`，
Rust 与 Go 打印 `true`）。三段用的都是语言无关标识 `ziweiMaj`——
就算把盘换成英文或日文输出，判断结果也不变。
# 介绍 (/zh/docs/guide)
把出生时间算成一张完整的紫微斗数命盘，并一键转成大模型读得懂的文字。Rust 核心，供 Rust、Python、Go 调用，结果与 JS iztro 逐字段一致。
*适合：开发者 · 命理爱好者 · 产品与决策者*
把出生时间算成一张完整的紫微斗数命盘，并能一键转成大模型读得懂的文字 ——
**排盘交给它算准，解读交给 AI**。
一行调用得到的就是这段 Markdown，直接贴进任何大模型就能开始问：
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座
- 五行局: 木三局 · 命主: 破军 · 身主: 文昌
- 命宫: 午 · 身宫: 戌 (官禄) · 来因宫: 辰 (夫妻)
- 生年四化: 太阳化禄→子女, 武曲化权→财帛, 太阴化科→仆役, 天同化忌→疾厄
## 十二宫总览
| 宫位 | 主星 | 辅星 | 大限 |
|---|---|---|---|
| **命宫** 午 | 紫微(庙) | 文曲(陷) | 3-12 |
| 兄弟 巳 | 天机(平) | — | 13-22 |
| 夫妻 辰 [来因宫] | 七杀(庙) | 右弼, 火星(陷) | 23-32 |
（其余九行略）
## 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
## 十二宫
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
（其余十一宫略）
```
排出来的盘准不准，有一条硬标准：**与 JS [iztro](https://github.com/SylarLong/iztro) v2.6.1 逐字段零差异**，
由 716,314 例金标测试守着。
核心用 Rust 实现，通过三套绑定暴露给上层编程语言：
## 它解决什么问题 [#它解决什么问题]
紫微斗数排盘看似只是查表，实际上牵扯一连串容易出错的历法与流派细节：农历闰月的处理、
晚子时算今天还是明天、年干支按正月初一还是立春换年、虚岁怎么进位、不同流派的四化表差异。
任何一处取舍不同，排出的盘就不是同一张。
社区里最完整的开源实现是 JavaScript 的 [iztro](https://github.com/SylarLong/iztro)，
但它只能在 JS 运行时里用。x-iztro 把这套逻辑完整移植到 Rust，
让服务端、数据分析脚本、命令行工具、移动端也能用上同一套排盘结果。
x-iztro 是 iztro v2.6.1 的移植，不是重新发明。凡是 iztro 有的功能与数据，
两者结果必须逐字段一致 —— 这条由 716,314 例金标测试守着，
详见[准确性保证](/zh/docs/guide/about/accuracy)。
## 特性 [#特性]
### 一键转成 AI 能读的文字 [#一键转成-ai-能读的文字]
内置语义化文本投影（to\_text）：把一张盘或一段运限投影成上面那种自然语言文本，
直接交给大模型分析，不必自己拼接命盘描述。见[语义化文本](/zh/docs/guide/guides/to-text)。
### 排盘与运限完整 [#排盘与运限完整]
本命盘、大限、小限、童限、流年、流月、流日、流时，六个层级的宫位、星耀、四化与
三方四正全部可取。年系杂耀、岁前十二神、将前十二神、博士十二神、长生十二神一应俱全。
### 流派与分界点可配置 [#流派与分界点可配置]
`Config` 的六个开关覆盖了实践中会分歧的每一处：年分界点、运限分界点、虚岁分界点、
晚子时归属、算法派别（默认 / 中州派）、排盘视角（天盘 / 地盘 / 人盘），
另可整表替换四化表与亮度表。默认值与 JS iztro 一致，
细节见 [Config 详解](/zh/docs/guide/guides/config)。
### 六种盘面语言 [#六种盘面语言]
简体中文、繁体中文、英文、日文、韩文、越南文。同一张盘换盘面语言只是换一次翻译，
排盘结果不受影响。
### 中文盘、英文盘，判断结果一样 [#中文盘英文盘判断结果一样]
给开发者
星名宫名在不同盘面语言下文本不同，但每个实体都额外带一个稳定的标识（key）。
Python 的枚举与 Go 的常量就建立在这些标识上，
所以「命宫有没有紫微星」这类判断，在任何盘面语言的盘上写法与结果都一样。
见 [key 契约](/zh/docs/guide/guides/keys)。
## 一分钟上手 [#一分钟上手]
```python
from x_iztro import Astro
astro = Astro()
chart = astro.by_solar("2000-8-16", 2, "female") # 2 = 时辰索引，寅时 03:00-05:00
soul = chart.palace("soulPalace") # 命宫
print(chart.five_elements_class, chart.soul, chart.body)
print(soul.name, soul.heavenly_stem + soul.earthly_branch)
print([s.name for s in soul.major_stars])
```
```text
木三局 破军 文昌
命宫 壬午
['紫微']
```
三种编程语言的完整安装与示例见[快速开始](/zh/docs/guide/getting-started)。
## 从哪读起 [#从哪读起]
# 概览 (/zh/docs/guide/getting-started)
排盘要准备哪些输入、每个参数取什么值，以及三种编程语言的安装方式。
*适合：所有人。参数表不需要会写代码也能看懂*
三套绑定共用同一个 Rust 核心，因此参数含义与排盘结果完全一致，只是写法不同。
先看清楚要准备什么，再挑你的编程语言。
## 你需要准备的输入 [#你需要准备的输入]
无论哪种编程语言，排盘都从这几个参数开始。前三个是必须的，后三个都有默认值。
| 参数 | 含义 | 取值 |
| --------------------------- | ------ | --------------------------------------------------------------- |
| `solar_date` / `lunar_date` | 出生日期 | `"YYYY-M-D"`，如 `"2000-8-16"`。公历范围 1583–9999 年 |
| `time_index` | 出生时辰 | 整数 0–12，见下表 |
| `gender` | 性别 | `"male"` / `"female"`（Rust 为 `Gender` 枚举） |
| `fix_leap` | 是否修正闰月 | 布尔值，默认 `true` |
| `language` | 盘面语言 | `"zh-CN"`（默认） `"zh-TW"` `"en-US"` `"ja-JP"` `"ko-KR"` `"vi-VN"` |
| `config` | 分界点与流派 | 见 [Config 详解](/zh/docs/guide/guides/config)，缺省即 iztro 默认 |
排盘只需要出生日期、时辰、性别三样。把它们按上面的格式写清楚交出去，
工程师那边一行调用就能出盘。想知道这个库能做什么、典型怎么用，
看[不写代码怎么用它](/zh/docs/guide/guides/for-non-developers)。
### 时辰索引 [#时辰索引]
紫微斗数按十二时辰计时，且把子时拆成首尾两段，所以索引是 0–12 共 13 个值。
| 索引 | 时辰 | 时间 | 索引 | 时辰 | 时间 |
| -- | --- | ----------- | -- | --- | ----------- |
| 0 | 早子时 | 00:00–01:00 | 7 | 未时 | 13:00–15:00 |
| 1 | 丑时 | 01:00–03:00 | 8 | 申时 | 15:00–17:00 |
| 2 | 寅时 | 03:00–05:00 | 9 | 酉时 | 17:00–19:00 |
| 3 | 卯时 | 05:00–07:00 | 10 | 戌时 | 19:00–21:00 |
| 4 | 辰时 | 07:00–09:00 | 11 | 亥时 | 21:00–23:00 |
| 5 | 巳时 | 09:00–11:00 | 12 | 晚子时 | 23:00–24:00 |
| 6 | 午时 | 11:00–13:00 | | | |
23:00–24:00 出生的人用索引 `12` 而不是 `0`。这两个索引排出的盘不同：
默认配置下晚子时按**次日**推算日柱，早子时按当日。
这个行为由 `day_divide` 开关控制，见 [Config 详解](/zh/docs/guide/guides/config#晚子时归属-day_divide)。
### 关于 `fix_leap` [#关于-fix_leap]
农历闰月没有独立的月建，排盘时要决定闰月的日子算上个月还是下个月。
`fix_leap = true`（默认）时按 iztro 的规则修正：闰月前半月算本月，后半月算下月。
设为 `false` 则整个闰月都算本月。
只有出生在闰月的人会受影响，其余情况该参数无作用。
## 选择编程语言 [#选择编程语言]
## 输入校验 [#输入校验]
给开发者
日期与时辰在**核心层**前置校验，三种编程语言共用同一道防线；非法输入不会 panic，
而是按各自的惯例报错：
| 编程语言 | 表现 |
| ------ | ------------------------------------------ |
| Rust | 返回 `Err(IztroError)`，`.code()` 给出机器可读分类 |
| Python | 抛 `IztroError`（继承 `ValueError`），`.code` 同上 |
| Go | 返回 `*iztro.Error`，可用 `errors.Is` 匹配哨兵 |
| C FFI | 返回 `{"error":"...","code":"..."}` JSON |
核心层校验的是日期格式与真实存在性、公历 1583–9999 范围、时辰索引 0–12。
性别、盘面语言、配置开关这些以字符串传入的参数，在**绑定层**解析时校验 ——
Rust 侧它们本来就是枚举，不存在非法取值。
详见[错误处理](/zh/docs/guide/guides/errors)。
# Rust (/zh/docs/guide/getting-started/rust)
安装 x-iztro crate，排出第一张盘，读懂枚举与翻译函数的分工。
*适合：开发者*
## 安装 [#安装]
```bash
cargo add x-iztro
```
或写进 `Cargo.toml`：
```toml
[dependencies]
x-iztro = "0.3"
```
crate 名为 `x-iztro`，代码中的库名是 `x_iztro`。无 C 依赖，纯 Rust 构建。
## 排盘 [#排盘]
```rust
use x_iztro::{by_solar, IztroError};
use x_iztro::data::types::*;
fn main() -> Result<(), IztroError> {
let astrolabe = by_solar(
"2000-8-16", // 阳历生日
2, // 时辰索引：寅时
Gender::Female, // 性别
true, // fix_leap：修正闰月
Language::ZhCN, // 盘面语言
Config::default(), // 分界点与流派，默认同 JS iztro
)?;
println!("阳历：{}", astrolabe.solar_date);
println!("农历：{}", astrolabe.lunar_date);
println!("干支：{}", astrolabe.chinese_date);
println!("时辰：{} ({})", astrolabe.time, astrolabe.time_range);
Ok(())
}
```
```text
阳历：2000-8-16
农历：二〇〇〇年七月十七
干支：庚辰 甲申 丙午 庚寅
时辰：寅时 (03:00~05:00)
```
农历排盘用 [`by_lunar`](/zh/docs/rust/astro#by_lunar)：`by_solar` 的 `fix_leap` 在这里换成
三态的 `LeapMonth`（`NotLeap` 非闰月 / `Leap` 闰月 / `LeapFixed` 闰月且十五之后视作次月），
一个参数说清闰月怎么处理，不会把两个布尔写反：
```rust
by_lunar("2000-7-17", 2, Gender::Female, LeapMonth::NotLeap, Language::ZhCN, Config::default())?;
```
## 接下来 [#接下来]
上面的例子只用到了排盘入口。完整的 API——十二宫定位、星耀判断、飞星、
运限、安星模块、数据表、翻译——在 **[Rust API 参考](/zh/docs/rust)** 一栏，
每个函数、类型与方法都有独立条目，附真实运行输出与边界说明。
# Python (/zh/docs/guide/getting-started/python)
pip 安装，dataclass 类型化 API，用枚举做与语言无关的判断。
*适合：开发者*
## 安装 [#安装]
```bash
pip install x-iztro
```
要求 Python 3.10 及以上。包内是 PyO3 编译的原生扩展（abi3），
安装后零运行期依赖 —— 不需要 pydantic，也不需要本机的 Rust 工具链。
只有在改动 Rust 侧代码时才需要：
```bash
pip install maturin
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 maturin develop --features python
```
## 排盘 [#排盘]
```python
from x_iztro import Astro
astro = Astro()
chart = astro.by_solar("2000-8-16", 2, "female")
print(chart.solar_date) # 阳历
print(chart.lunar_date) # 农历
print(chart.chinese_date) # 四柱干支
print(chart.time, chart.time_range)
print(chart.sign, chart.zodiac) # 星座、生肖
print(chart.soul, chart.body) # 命主、身主
print(chart.five_elements_class) # 五行局
```
```text
2000-8-16
二〇〇〇年七月十七
庚辰 甲申 丙午 庚寅
寅时 03:00~05:00
狮子座 龙
破军 文昌
木三局
```
`solar_date` 原样回显入参字符串，不补零 —— 传 `"2000-08-16"` 就回 `"2000-08-16"`。
要结构化的日期用 `chart.raw_dates`。
农历排盘用 `by_lunar`，比 `by_solar` 多一个 `is_leap_month`。`gender` 之后的参数
（`is_leap_month`、`fix_leap`、`language`、`config`）只能按关键字传入——两个布尔相邻，
位置传参写反了不报错：
```python
chart = astro.by_lunar("2000-7-17", 2, "female", is_leap_month=False)
```
返回的 `Astrolabe` 是 dataclass，字段有类型标注，IDE 能自动补全。
所有文本字段已按盘面语言翻译好。
## 接下来 [#接下来]
上面的例子只用到了排盘入口。完整的 API——十二宫定位、星耀判断、飞星、
运限、安星模块、数据表、翻译——在 **[Python API 参考](/zh/docs/python)** 一栏，
每个函数、类与方法都有独立条目，附真实运行输出与边界说明。
# Go (/zh/docs/guide/getting-started/go)
go get 即用，内嵌 WebAssembly，无 cgo，保留交叉编译能力。
*适合：开发者*
## 安装 [#安装]
```bash
go get github.com/x-haose/x-iztro/go/iztro
```
包里内嵌了核心库编译出的 WebAssembly 模块（`wasm32-wasip1`），
经纯 Go 实现的 [wazero](https://wazero.io) 运行时调用。
这意味着：**不需要 cgo，不需要本机安装 Rust 工具链，交叉编译照常可用**。
wazero 的编译器后端只支持 amd64 与 arm64，其余架构走解释器，速度慢但结果相同。
单个 wasm 实例不能并发使用，包内维护一个实例池（上限 `GOMAXPROCS`），
多 goroutine 调用互不串行化，能真正并行。
首次调用要编译 wasm 模块。编译产物落盘缓存（`os.UserCacheDir()` 下），
所以只有第一次是 \~200ms，之后每个进程的首次调用 \~30ms。
服务进程想让第一个请求就走热路径，在启动时调一次 `iztro.Warmup(ctx)`。
热路径上一次排盘（含 JSON 编解码与内存拷贝）在 0.5ms 量级。
## 排盘 [#排盘]
```go
package main
import (
"fmt"
"log"
"github.com/x-haose/x-iztro/go/iztro"
)
func main() {
chart, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.SolarDate) // 阳历
fmt.Println(chart.LunarDate) // 农历
fmt.Println(chart.ChineseDate) // 四柱干支
fmt.Println(chart.Time, chart.TimeRange)
fmt.Println(chart.Sign, chart.Zodiac)
fmt.Println(chart.Soul, chart.Body) // 命主、身主
fmt.Println(chart.FiveElementsClass)
}
```
```text
2000-8-16
二〇〇〇年七月十七
庚辰 甲申 丙午 庚寅
寅时 03:00~05:00
狮子座 龙
破军 文昌
木三局
```
最后一个参数是 `*Config`，传 `nil` 即取默认配置。`gender` 与 `language` 是具名类型
`iztro.Gender` / `iztro.Language`（`iztro.GenderFemale`、`iztro.LanguageZhCN`，字面量也能直接传）。
农历排盘用 `ByLunar`：`BySolar` 的 `fixLeap` 换成三态的 `iztro.LeapMonth`
（`NotLeapMonth` / `LeapMonthKeep` / `LeapMonthFixed`），一个参数说清闰月怎么处理：
```go
iztro.ByLunar("2000-7-17", 2, iztro.GenderFemale, iztro.NotLeapMonth, iztro.LanguageZhCN, nil)
```
每个入口都有 `*Context` 变体（`BySolarContext`、`ByLunarContext` 等），
`ctx` 用于取消等待实例池的排队。
## 错误处理 [#错误处理]
失败一律返回 `*iztro.Error`，带机器可读的 `Code`；用 `errors.Is` 按类别匹配：
```go
_, err := iztro.BySolar("2000-13-1", 2, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
if errors.Is(err, iztro.ErrInvalidDate) {
var e *iztro.Error
errors.As(err, &e)
fmt.Println(e.Code, e.Message)
}
```
```text
invalid_date invalid solar date '2000-13-1': month must be within 1-12
```
详见[错误处理](/zh/docs/guide/guides/errors)。
## 接下来 [#接下来]
上面的例子只用到了排盘入口。完整的 API——十二宫定位、星耀判断、飞星、
运限、安星模块、数据表、翻译——在 **[Go API 参考](/zh/docs/go)** 一栏，
每个导出函数、类型与方法都有独立条目，附真实运行输出与边界说明。
# 一张盘由什么构成 (/zh/docs/guide/concepts)
紫微斗数的最小知识集，不懂代码也能读：一张盘是什么、由哪些部分组成、每一部分决定什么。
*适合：所有人。不懂代码也能读；每页末尾另有「在代码里怎么取」一节*
这一章不教你怎么解读命盘，只解释**一张盘由什么构成**——
读完你就知道排盘结果里那些名词各自在说什么。
## 排盘做了什么 [#排盘做了什么]
排盘的输入只有四样东西：出生的**日期**、**时辰**、**性别**，以及一组决定流派与分界点的**配置**。
输出是一张固定形状的盘：**十二个宫格**，每格有自己的干支、宫名，
以及落在里面的若干**星耀**。这张盘一生不变，称为**本命盘**。
在本命盘之上，再按时间推算出**运限**：这一步十年（大限）、这一年（流年）、
这一月、这一日、这一时的宫位与四化各是什么。运限随查询日期变化。
```
出生日期 + 时辰 + 性别 + 配置
│
├─→ 本命盘（十二宫 + 星耀 + 四化） ← 一生固定
│
└─→ 运限（大限/小限/流年/流月/流日/流时）← 随目标日期变化
```
## 四个必须先搞清的概念 [#四个必须先搞清的概念]
### 干支 [#干支]
天干十个（甲乙丙丁戊己庚辛壬癸）、地支十二个（子丑寅卯辰巳午未申酉戌亥），
两两配对循环六十次，用来纪年、纪月、纪日、纪时。
出生时刻的四组干支叫**四柱**，也就是排盘结果里那串「庚辰 甲申 丙午 庚寅」。
十二个宫也各有自己的天干（宫干），它是四化飞星的依据。
### 命宫与身宫 [#命宫与身宫]
**命宫**是整张盘的起点，由农历生月与生时定位。十二宫名从命宫开始安放。
**身宫**不是第十三个宫，它是十二宫中的某一个被额外标记，表示后天着力之处。
### 五行局 [#五行局]
由命宫的干支推出，取值是水二局、木三局、金四局、土五局、火六局之一。
局数（2 到 6）后面要用两次：
1. **起紫微**：用农历日除以局数，定出紫微星落在哪一宫 —— 十四主星的位置全由这一步铺开。
2. **定大限起运岁数**：水二局从虚岁 2 起，火六局从 6 起，此后每宫管十年。
### 四化 [#四化]
天干各自带一组「化禄、化权、化科、化忌」的指派，指向四颗具体的星。
排盘时，年干的四化会标记在对应的星上；运限层级还各有自己的四化。
这是紫微斗数里动态信息的主要来源，见[四化与飞星](/zh/docs/guide/concepts/mutagen)。
## 盘面的排列 [#盘面的排列]
紫微斗数的盘是十二个格子围成一圈，每格对应一个**地支**。
排盘结果里的十二宫按固定顺序存放，**第一格是寅宫**：
| 位置 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| -- | - | - | - | - | - | - | - | - | - | - | -- | -- |
| 地支 | 寅 | 卯 | 辰 | 巳 | 午 | 未 | 申 | 酉 | 戌 | 亥 | 子 | 丑 |
位置对应的是**地支**，不是宫名顺序。命宫可能落在这十二格中的任意一格，
第一格不一定是命宫。要取命宫请按宫名查，不要写死位置。
十二个**宫名**（命宫、父母、福德……）则是排盘算出来的，
从命宫所在的那一格起，逆时针依次安放。所以每张盘的「命宫在哪一格」都可能不同 ——
这正是排盘的第一步。详见[十二宫](/zh/docs/guide/concepts/palaces)。
## 一张盘上的信息层次 [#一张盘上的信息层次]
逐字段的类型与含义见[数据结构字典](/zh/docs/guide/data-model)。
## 继续读 [#继续读]
# 干支与五行 (/zh/docs/guide/concepts/stems-branches)
天干、地支、五行、阴阳各自决定排盘的哪一部分，宫干从哪来，命主身主怎么查。
*适合：所有人。代码在页尾*
排盘从头到尾都建立在干支之上。看懂这一页，盘上那些两字一组的名词就都有着落了。
## 十天干与十二地支 [#十天干与十二地支]
天干十个：甲乙丙丁戊己庚辛壬癸。地支十二个：子丑寅卯辰巳午未申酉戌亥。
两者依次配对循环，10 与 12 的最小公倍数是 60，因此一轮是**六十甲子**。
年、月、日、时各配一组干支，合称**四柱**：
```text
庚辰 甲申 丙午 庚寅
年柱 月柱 日柱 时柱
```
## 每一柱决定什么 [#每一柱决定什么]
四柱不是并列的装饰，各自驱动排盘的不同部分：
| 柱 | 驱动 |
| ------ | --------------------------- |
| **年柱** | 生年四化、命主身主、十二宫的宫干、大限顺逆、全部年系星 |
| **月柱** | 展示用；月份本身（而非月柱）决定命宫与左辅右弼等月系星 |
| **日柱** | 展示用；农历日决定紫微起宫与三台八座等日系星 |
| **时柱** | 展示用；时辰本身决定命宫、身宫与文昌文曲等时系星 |
换年时点（正月初一还是立春）之所以是个配置开关，正因为年干支牵动的东西最多——
一旦改变，四化、命主身主、宫干全跟着变。见 [Config 详解](/zh/docs/guide/guides/config)。
## 阴阳 [#阴阳]
干支各自有阴阳，按序号奇偶交替：甲、丙、戊、庚、壬为阳，乙、丁、己、辛、癸为阴；
子、寅、辰、午、申、戌为阳，丑、卯、巳、未、酉、亥为阴。
六十甲子只配同阴阳的干与支（甲子、乙丑…），所以**一组干支的干与支阴阳必然相同**，
「年干阴阳」与「年支阴阳」永远给出同一个答案。x-iztro 一律按**年支**判定。
阴阳在排盘里只做一件事，但这件事影响很大——**定顺逆**：
| 用途 | 规则 |
| ----- | -------------------- |
| 大限方向 | 性别阴阳与年支阴阳相同则顺行，相异则逆行 |
| 长生十二神 | 同上 |
| 博士十二神 | 同上 |
性别也算阴阳：男为阳、女为阴。所以「阳男阴女顺行，阴男阳女逆行」这句口诀，
说的就是这三处。小限不在其中——小限的方向只看性别，见[十二宫](/zh/docs/guide/concepts/palaces#小限)。
## 五行 [#五行]
金木水火土。每个天干、每个地支各自属一行。
两个概念名字像，作用完全不同：
* **五行**：单个干支的属性，参考信息
* **五行局**：由**命宫干支**推出的水二局、木三局、金四局、土五局、火六局，
决定紫微起宫与大限起运岁数
做判断时别搞混：前者是干支的 `fiveElements` 字段，后者是星盘的 `five_elements_class`。
## 对冲 [#对冲]
地支两两相对，相隔六位即为对冲：子午、丑未、寅申、卯酉、辰戌、巳亥。
这正是**对宫**的由来——十二宫排成一圈，本宫与隔六位的那一宫地支恰好对冲，
所以对宫的影响最直接。天干也有对冲（甲庚、乙辛、丙壬、丁癸），戊己居中无冲。
## 宫位的干支从哪来 [#宫位的干支从哪来]
十二宫的地支是**固定**的：第一格永远是寅宫，最后一格永远是丑宫，从不改变。
天干则由年干经**五虎遁**推出：先定寅宫天干，其余十一宫依次顺排。
以本页这张盘为例，生年干为庚，庚年寅宫起戊，于是十二宫干支是：
```text
戊寅 己卯 庚辰 辛巳 壬午 癸未 甲申 乙酉 丙戌 丁亥 戊子 己丑
```
宫干不是摆设——它决定该宫**飞出**哪四颗四化星，是飞星派全部判断的起点。
见[四化与飞星](/zh/docs/guide/concepts/mutagen)。
另有**五鼠遁**，由日干推子时天干，用于定时柱。
## 命主与身主 [#命主与身主]
每个地支各自对应一颗命主星与一颗身主星，查表即得。两者查表的依据不同：
| | 按什么查 | 换命宫重排时 |
| ------- | -------- | ------ |
| 命主（默认派） | **命宫地支** | 会变 |
| 命主（中州派） | **生年地支** | 不变 |
| 身主 | **生年地支** | 不变 |
`algorithm = zhongzhou` 下命主改按生年地支查，因此换命宫起盘（`rearranged`、
或天盘/地盘/人盘切换）时命主星不再变化。默认派下命主会跟着命宫走。
见 [Config 详解](/zh/docs/guide/guides/config#算法派别-algorithm)。
## 在代码里怎么取 [#在代码里怎么取]
干支、五行、五虎遁五鼠遁、命主身主全部以数据表形式提供，不必自己抄表。
```python
from x_iztro import data
data.heavenly_stems()["jiaHeavenly"].five_elements # 木
data.earthly_branches()["ziEarthly"].yin_yang # 阳
data.earthly_branches()["ziEarthly"].crash # wuEarthly（子午冲）
data.heavenly_stems()["wuHeavenly"].crash # None（戊无冲）
data.constants().tiger_rule["jiaHeavenly"] # bingHeavenly（甲年寅宫起丙）
data.constants().rat_rule["jiaHeavenly"] # jiaHeavenly
data.constants().five_elements_class # {'water2nd': 2, ... 'fire6th': 6}
zi = data.earthly_branches()["ziEarthly"]
zi.soul # tanlangMaj —— 命主
zi.body # huoxingMin —— 身主
```
四柱的语言无关标识在 `raw_dates.chinese_date` 下的
`yearly_keys` / `monthly_keys` / `daily_keys` / `hourly_keys`；
顶层 `chinese_date` 是展示串。
| 概念 | 数据表 | 常量 |
| ----- | ------------------------- | --------------------------------- |
| 天干信息 | `data.heavenly_stems()` | — |
| 地支信息 | `data.earthly_branches()` | — |
| 五虎遁 | — | `constants().tiger_rule` |
| 五鼠遁 | — | `constants().rat_rule` |
| 性别阴阳 | — | `constants().gender` |
| 五行局局数 | — | `constants().five_elements_class` |
逐字段说明见 [Rust](/zh/docs/rust/data)、[Python](/zh/docs/python/data)、[Go](/zh/docs/go/data) 的数据表一页。
# 十二宫 (/zh/docs/guide/concepts/palaces)
十二个宫名各自代表什么，身宫与来因宫的判定，宫干的用途，以及大限小限如何挂在宫上。
*适合：所有人。代码在页尾*
## 十二宫名 [#十二宫名]
十二宫覆盖人生的十二个领域。它们从**命宫**起，按固定顺序**逆时针**安放在盘上：
| 顺序 | 盘上写作 | 常见别名 | 大致含义 |
| -- | ---- | ------- | ------------ |
| 1 | 命宫 | 本命宫 | 本性、总纲，整张盘的核心 |
| 2 | 父母 | 父母宫、相貌宫 | 父母、长辈、上级、庇荫 |
| 3 | 福德 | 福德宫 | 精神生活、兴趣、福分 |
| 4 | 田宅 | 田宅宫 | 不动产、家庭环境 |
| 5 | 官禄 | 官禄宫、事业宫 | 事业、职业、学业 |
| 6 | 仆役 | 交友宫、奴仆宫 | 朋友、同事、下属 |
| 7 | 迁移 | 迁移宫 | 外出、变动、外界际遇 |
| 8 | 疾厄 | 疾厄宫 | 身体、疾病 |
| 9 | 财帛 | 财帛宫 | 财务、收入 |
| 10 | 子女 | 子女宫 | 子女、晚辈、创造力 |
| 11 | 夫妻 | 夫妻宫、配偶宫 | 配偶、亲密关系 |
| 12 | 兄弟 | 兄弟宫 | 兄弟姐妹、平辈 |
只有命宫例外。中文盘上第六宫写作**仆役**，不是坊间常见的「交友宫」。
别名列只是各家说法，不会出现在排盘结果里 —— 要做判断请用标识，见页尾。
「宫名的顺序」与「宫在盘上的位置」是两回事。宫名顺序永远是上表这个循环，
但命宫落在哪个地支格由排盘算出，其余十一宫跟着排。
所以十二宫数组的位置对应地支，不对应宫名顺序。
## 命宫怎么定 [#命宫怎么定]
命宫由**农历生月**与**生时**共同定位：从寅宫起正月顺数到生月，再从该宫起子时逆数到生时。
这个位置决定了整张盘的格局，也是五行局与大限的推算起点。
## 身宫 [#身宫]
身宫用同样的月时数据但顺数生时得到，落点必定是十二宫中的某一宫。
它不是独立的第十三宫，而是给某个宫加上一个标记。
传统上命宫看先天本质，身宫看后天着力与中年后的走向。
## 来因宫 [#来因宫]
来因宫是**宫干与出生年干相同**，且不在子、丑二宫的那一宫。
它标示这张盘的「来处」，是飞星派的重要起点。
一张盘上**恒有且仅有一个**来因宫。理由在宫干的安法里：
十二宫的宫干从寅宫起按五虎遁顺排，十个天干排十二个宫，
所以只有开头两个（寅、卯）会在末尾（子、丑）重复一次 ——
与年干相同的宫因此恰好有两个，且必定是「寅或卯」与「子或丑」这一对。
排除子丑之后，剩下的正好一个。
## 宫干与宫支 [#宫干与宫支]
每个宫都有自己的一组干支：
* **宫支**：由宫在盘上的位置固定决定（第一格是寅，见[总览](/zh/docs/guide/concepts#盘面的排列)），一生不变。
* **宫干**：由出生年干按五虎遁推出。
宫干的用途是**四化飞星**：一个宫的宫干决定它「飞出」哪四颗化星，
由此判断宫与宫之间的关系。见[四化与飞星](/zh/docs/guide/concepts/mutagen#飞星)。
## 大限 [#大限]
大限是十年一步的运程，每个宫掌管一段。起始虚岁由[五行局](/zh/docs/guide/concepts#五行局)决定：
| 五行局 | 局数 | 起运虚岁 | 首个大限区间 |
| --- | -- | ---- | ------ |
| 水二局 | 2 | 2 | 2–11 |
| 木三局 | 3 | 3 | 3–12 |
| 金四局 | 4 | 4 | 4–13 |
| 土五局 | 5 | 5 | 5–14 |
| 火六局 | 6 | 6 | 6–15 |
行进方向由**性别阴阳与年支阴阳**共同决定：两者相同则顺行，相异则逆行，
即口诀「阳男阴女顺行，阴男阳女逆行」。
（年干与年支的阴阳恒同，所以按年干说也是同一回事，见[阴阳](/zh/docs/guide/concepts/stems-branches#阴阳)。）
出生到起运虚岁之间的年份不属于任何大限，这段时间用**童限**推算，
由运限接口返回。见[运限](/zh/docs/guide/concepts/horoscope#童限)。
## 小限 [#小限]
小限是一年一步的运程，与大限并行，每年走一宫，同一个宫每十二年轮到一次。
小限的规则与大限**不同**，两条独立：
* **起点**由年支所属的三合组决定（寅午戌年起辰宫、申子辰年起戌宫、
巳酉丑年起未宫、亥卯未年起丑宫）
* **方向只看性别**：男顺行、女逆行，与年支阴阳无关
## 在代码里怎么取 [#在代码里怎么取]
按宫名取宫，判断宫里有什么：
```rust
let soul = astrolabe.palace(Palace::Soul).unwrap();
soul.has(&[StarKey::ZiweiMaj]); // 是否同时有这些星
soul.has_one_of(&[StarKey::ZiweiMaj, StarKey::TianfuMaj]); // 是否有任意一颗
soul.has_mutagen(Mutagen::Lu); // 是否有化禄
soul.is_empty(); // 是否空宫（无十四主星）
soul.is_body_palace; // 是否身宫
soul.is_original_palace; // 是否来因宫
soul.decadal.range; // 该宫掌管的大限区间，(3, 12)
soul.ages; // 小限经过该宫的虚岁列表
```
```python
from x_iztro.enums import PalaceName, MajorStar, Mutagen
soul = chart.palace(PalaceName.SOUL)
soul.has([MajorStar.ZIWEI])
soul.has_one_of([MajorStar.ZIWEI, MajorStar.TIANFU])
soul.has_mutagen(Mutagen.LU)
soul.is_empty()
soul.is_body_palace
soul.is_original_palace
soul.decadal.range # (3, 12)
soul.ages # 例如 [5, 17, 29, 41, 53, 65, 77, 89, 101, 113]
```
```go
soul := chart.Palace(iztro.PalaceSoul)
soul.Has(iztro.StarZiweiMaj)
soul.HasOneOf(iztro.StarZiweiMaj, iztro.StarTianfuMaj)
soul.HasMutagen(iztro.MutagenLu)
soul.IsEmpty()
soul.IsBodyPalace
soul.IsOriginalPalace
soul.Decadal.Range
soul.Ages
```
「空宫」指的是没有十四主星，不代表宫里没有任何星 —— 辅星与杂耀通常还在。
空宫在解读上要借对宫的星来看，这也是[三方四正](/zh/docs/guide/concepts/surrounded)存在的原因之一。
### 宫名的语言无关标识 [#宫名的语言无关标识]
判断用标识，不要匹配宫名文本 —— 换一种盘面语言，匹配文本的分支会静默失效。
| 宫 | 标识 |
| -- | ---------------- |
| 命宫 | `soulPalace` |
| 父母 | `parentsPalace` |
| 福德 | `spiritPalace` |
| 田宅 | `propertyPalace` |
| 官禄 | `careerPalace` |
| 仆役 | `friendsPalace` |
| 迁移 | `surfacePalace` |
| 疾厄 | `healthPalace` |
| 财帛 | `wealthPalace` |
| 子女 | `childrenPalace` |
| 夫妻 | `spousePalace` |
| 兄弟 | `siblingsPalace` |
另有两个只能用于查询、不会作为宫名出现的标识：`bodyPalace`（身宫）与
`originalPalace`（来因宫），把它们传给取宫方法即可拿到被标记的那一宫。
Python 的 `PalaceName` 枚举与 Go 的 `Palace*` 常量取值就是上表的标识，
在任何盘面语言的盘上都成立。见 [key 契约](/zh/docs/guide/guides/keys)。
# 星耀 (/zh/docs/guide/concepts/stars)
三组星耀各自装什么，星耀分八类，亮度与四化标记怎么读，四组十二神是什么，以及星名对照表。
*适合：所有人。代码与标识对照表在页尾*
每个宫位上的星耀分三组存放，另外还有四组「十二神」以单值形式挂在宫上。
## 主星 [#主星]
十四颗主星，是解读命盘的骨架。它们按紫微与天府两个系列的规则安放，
十二宫里有的宫会有两颗，有的一颗都没有（称为**空宫**）。
| 紫微系（六颗） | 天府系（八颗） |
| ------- | ------- |
| 紫微 | 天府 |
| 天机 | 太阴 |
| 太阳 | 贪狼 |
| 武曲 | 巨门 |
| 天同 | 天相 |
| 廉贞 | 天梁 |
| | 七杀 |
| | 破军 |
「空宫」判断的就是这一组是否为空。
## 辅星 [#辅星]
十四颗辅星，按性质分四类：
| 类别 | 成员 |
| ------ | ----------------- |
| 吉星（六吉） | 左辅、右弼、文昌、文曲、天魁、天钺 |
| 煞星（六煞） | 擎羊、陀罗、火星、铃星、地空、地劫 |
| 禄存 | 禄存 |
| 天马 | 天马 |
它们在传统分法里既非纯吉也非纯煞：禄存主财禄但畏空劫，天马主动主变但需见禄。
判断时常要把它们与六吉六煞分开处理，因此各占一个类别，
筛选时按类别过滤即可，不必按星名硬编码。
## 杂耀 [#杂耀]
数十颗辅助性质的星，按来源分成年干系、年支系、月系、日系、时系几类，安星依据各不相同。
杂耀分三类：
| 类别 | 数量 | 成员 |
| ---- | -- | --------------------------------------------------- |
| 桃花星 | 4 | 红鸾 `hongluan`、天喜 `tianxi`、天姚 `tianyao`、咸池 `xianchi` |
| 解神 | 2 | 解神 `jieshen`、年解 `nianjie` |
| 其余杂耀 | 32 | 见下 |
默认派的 32 颗其余杂耀，按性质分组：
| 分组 | 成员 |
| ----- | ---------------------------------------------------------------------------------------------------------------------------- |
| 贵显助力 | 三台 `santai`、八座 `bazuo`、恩光 `engguang`、天贵 `tiangui`、台辅 `taifu`、封诰 `fenggao`、龙池 `longchi`、凤阁 `fengge`、天官 `tianguan`、天福 `tianfu` |
| 才艺与庇荫 | 天才 `tiancai`、天寿 `tianshou`、天巫 `tianwu`、天厨 `tianchu`、天德 `tiande`、月德 `yuede`、华盖 `huagai` |
| 空亡类 | 天空 `tiankong`、旬空 `xunkong`、截路 `jielu`、空亡 `kongwang` |
| 刑忌孤克 | 天刑 `tianxing`、孤辰 `guchen`、寡宿 `guasu`、破碎 `posui`、蜚廉 `feilian`、阴煞 `yinsha`、天哭 `tianku`、天虚 `tianxu`、天月 `tianyue` |
| 伤使 | 天伤 `tianshang`、天使 `tianshi` |
桃花星与情感、异性缘、人际吸引力相关，是解读感情与人际时最先看的一组。
四颗里红鸾天喜偏正缘与喜庆，天姚咸池偏情欲与应酬。
默认派安的是**截路**与**空亡**两颗独立的星，不要写成「截空」。
中州派（`algorithm = zhongzhou`）则改安**截空**、**劫杀**、**大耗**、**龙德**，
不安截路与空亡，杂耀总数由 32 变成 34。见
[Config 详解](/zh/docs/guide/guides/config#算法派别-algorithm)。
判断某宫有没有某个四化时，只检查主星与辅星，**不检查杂耀** —— 与 iztro 行为一致。
## 星耀分八类 [#星耀分八类]
上面三组加起来正好覆盖全部类别：
| 类别标识 | 出现在哪一组 | 一句话 |
| ----------- | ------ | ---------- |
| `major` | 主星 | 十四主星，定盘面骨架 |
| `soft` | 辅星 | 六吉 |
| `tough` | 辅星 | 六煞 |
| `lucun` | 辅星 | 禄存，单独成类 |
| `tianma` | 辅星 | 天马，单独成类 |
| `flower` | 杂耀 | 桃花星 |
| `helper` | 杂耀 | 解神 |
| `adjective` | 杂耀 | 其余杂耀 |
判断「某宫见不见煞」这类需求，按类别过滤最稳 —— 换盘面语言星名会变，类别不会。
## 亮度 [#亮度]
亮度描述一颗星落在某个地支位置上的强弱，共七级：
| 盘上写作 | 全称 | 强弱 |
| ---- | --- | -- |
| 庙 | 庙旺 | 最强 |
| 旺 | 旺相 | |
| 得 | 得地 | |
| 利 | 利益 | |
| 平 | 平和 | 中性 |
| 不 | 不得地 | |
| 陷 | 落陷 | 最弱 |
同一颗星在不同宫位亮度不同，这由星与地支的固定对照表决定。杂耀通常没有亮度。
英文、韩文等语言的词表没有亮度译名，输出的是 `[+3]`（庙）到 `[-3]`（陷）的记号。
判断亮度请用标识而非文本，见[多语言输出](/zh/docs/guide/guides/i18n)。
## 四组十二神 [#四组十二神]
除了三组星耀，每个宫还挂着四个**单值**字段，各自来自一套十二神的循环安法。
每组的十二个成员排满十二宫，每宫恰好一个。
### 长生十二神 [#长生十二神]
依据**五行局与阴阳男女**起。描述一件事从萌生到消亡再重来的十二个阶段。
长生 `changsheng` / 沐浴 `muyu` / 冠带 `guandai` / 临官 `linguan` /
帝旺 `diwang` / 衰 `shuai` / 病 `bing` / 死 `si` / 墓 `mu` / 绝 `jue` /
胎 `tai` / 养 `yang`
### 博士十二神 [#博士十二神]
依据**禄存位置与阴阳男女**起。偏重才能、财禄与是非。
博士 `boshi` / 力士 `lishi` / 青龙 `qinglong` / 小耗 `xiaohao` /
将军 `jiangjun` / 奏书 `zhoushu` / 飞廉 `faylian` / 喜神 `xishen` /
病符 `bingfu` / 大耗 `dahao` / 伏兵 `fubing` / 官府 `guanfu`
### 岁前十二神 [#岁前十二神]
依据**年支**起，恒顺行。偏重一年之内的吉凶事件。
岁建 `suijian` / 晦气 `huiqi` / 丧门 `sangmen` / 贯索 `guansuo` /
官符 `gwanfu` / 小耗 `xiaohao` / 大耗 `dahao` / 龙德 `longde` /
白虎 `baihu` / 天德 `tiande` / 吊客 `diaoke` / 病符 `bingfu`
中州派把这一组里的**大耗**换成**岁破**（`suipo`）。
### 将前十二神 [#将前十二神]
依据**年支三合组**起，恒顺行。偏重动向、驿马与人事阻碍。
将星 `jiangxing` / 攀鞍 `panan` / 岁驿 `suiyi` / 息神 `xiishen` /
华盖 `huagai` / 劫煞 `jiesha` / 灾煞 `zhaisha` / 天煞 `tiansha` /
指背 `zhibei` / 咸池 `xianchi` / 月煞 `yuesha` / 亡神 `wangshen`
`faylian`（飞廉）、`gwanfu`（官符）、`xiishen`（息神）、`zhaisha`（灾煞）
这几个标识与拼音不一致 —— 它们沿用 iztro 的原始词表键名，用来与同音的
`feilian`（蜚廉，杂耀）、`guanfu`（官府，博士十二神）、`xishen`（喜神，博士十二神）区分。
照抄标识，不要按拼音自己拼。
运限层级还会带自己的岁前十二神与将前十二神，它们按运限年支重新起算，
与本命盘上的这四组是两回事。见[运限](/zh/docs/guide/concepts/horoscope)。
## 在代码里怎么取 [#在代码里怎么取]
### 遍历一个宫的星耀 [#遍历一个宫的星耀]
```python
soul = chart.palace("soulPalace")
for s in soul.major_stars + soul.minor_stars + soul.adjective_stars:
print(s.key, s.name, s.type, s.brightness, s.mutagen)
```
```text
ziweiMaj 紫微 major 庙 None
wenquMin 文曲 soft 陷 None
fengge 凤阁 adjective None None
tianfu 天福 adjective None None
jielu 截路 adjective None None
feilian 蜚廉 adjective None None
nianjie 年解 helper None None
```
单颗星的字段：
| 字段 | 含义 |
| ------------------------------ | ------------------------------------------- |
| `name` | 星名，按盘面语言翻译 |
| `key` | 语言无关标识，如 `ziweiMaj` |
| `type` | 八个类别之一 |
| `scope` | 所属层级：`origin` 本命、`decadal` 大限、`yearly` 流年…… |
| `brightness` / `brightnessKey` | 亮度，只有部分星有 |
| `mutagen` / `mutagenKey` | 四化标记，只有被化到的星有 |
### 四组十二神 [#四组十二神-1]
```python
for p in chart.palaces:
print(p.name, p.changsheng12, p.boshi12, p.suiqian12, p.jiangqian12)
```
每个字段另有 `*_key` 版本（`changsheng12_key` 等），判断用它。
### 查一颗星在哪 [#查一颗星在哪]
```rust
if let Some(star) = astrolabe.star(StarKey::ZiweiMaj) {
// StarRef 解引用即 Star，另可取所在宫
println!("{:?} {:?}", star.brightness, star.palace().name);
}
```
```python
from x_iztro.enums import MajorStar
star = chart.star(MajorStar.ZIWEI) # 只要星
star, palace = chart.star_in_palace(MajorStar.ZIWEI) # 连所在宫一起
```
```go
star, palace := chart.Star(iztro.StarZiweiMaj)
```
查找会遍历三组，所以主星、辅星、杂耀都能查到；查不到返回空值。
### 星名对照表 [#星名对照表]
同一颗星在不同盘面语言下文本不同，标识不变。英文词表来自 iztro 原词表，
是意译而非音译，也不是英文命理界的通行译法 —— 只做展示，判断一律用标识。
| 标识 | 中文 | 英文 |
| -------------- | -- | --------- |
| `ziweiMaj` | 紫微 | emperor |
| `tianjiMaj` | 天机 | advisor |
| `taiyangMaj` | 太阳 | sun |
| `wuquMaj` | 武曲 | warrior |
| `tiantongMaj` | 天同 | fortunate |
| `lianzhenMaj` | 廉贞 | judge |
| `tianfuMaj` | 天府 | empress |
| `taiyinMaj` | 太阴 | moon |
| `tanlangMaj` | 贪狼 | wolf |
| `jumenMaj` | 巨门 | advocator |
| `tianxiangMaj` | 天相 | minister |
| `tianliangMaj` | 天梁 | sage |
| `qishaMaj` | 七杀 | marshal |
| `pojunMaj` | 破军 | rebel |
| `zuofuMin` | 左辅 | officer |
| `youbiMin` | 右弼 | helper |
| `wenchangMin` | 文昌 | scholar |
| `wenquMin` | 文曲 | artist |
| `tiankuiMin` | 天魁 | assistant |
| `tianyueMin` | 天钺 | aide |
| `qingyangMin` | 擎羊 | driven |
| `tuoluoMin` | 陀罗 | tangled |
| `huoxingMin` | 火星 | impulsive |
| `lingxingMin` | 铃星 | spark |
| `dikongMin` | 地空 | ideologue |
| `dijieMin` | 地劫 | fickle |
| `lucunMin` | 禄存 | money |
| `tianmaMin` | 天马 | horse |
杂耀与十二神的标识见上文各节。任意标识与任意语言之间的换算用翻译与反查函数，
见[多语言输出](/zh/docs/guide/guides/i18n#标识与译名的换算)。
# 四化与飞星 (/zh/docs/guide/concepts/mutagen)
禄权科忌从哪来、十天干四化全表、自化与飞化怎么判断。
*适合：所有人。代码与完整方法表在页尾*
四化是紫微斗数里最重要的动态信息。同一张盘，四化把静态的星耀连成有方向的关系网。
## 四种化 [#四种化]
| 四化 | 标识 | 常见理解 |
| -- | ----------- | -------- |
| 化禄 | `sihuaLu` | 顺遂、收获、缘起 |
| 化权 | `sihuaQuan` | 掌控、扩张、力度 |
| 化科 | `sihuaKe` | 名声、贵人、缓和 |
| 化忌 | `sihuaJi` | 阻滞、执着、变数 |
## 四化从天干来 [#四化从天干来]
每个天干固定指派四颗星，分别化禄、化权、化科、化忌。这是一张查表：
| 天干 | 化禄 | 化权 | 化科 | 化忌 |
| -- | -- | -- | -- | -- |
| 甲 | 廉贞 | 破军 | 武曲 | 太阳 |
| 乙 | 天机 | 天梁 | 紫微 | 太阴 |
| 丙 | 天同 | 天机 | 文昌 | 廉贞 |
| 丁 | 太阴 | 天同 | 天机 | 巨门 |
| 戊 | 贪狼 | 太阴 | 右弼 | 天机 |
| 己 | 武曲 | 贪狼 | 天梁 | 文曲 |
| 庚 | 太阳 | 武曲 | 太阴 | 天同 |
| 辛 | 巨门 | 太阳 | 文曲 | 文昌 |
| 壬 | 天梁 | 紫微 | 左辅 | 武曲 |
| 癸 | 破军 | 巨门 | 太阴 | 贪狼 |
庚干化科历来有太阴、天府、天同等不同说法。x-iztro 采用**太阴化科**，与 JS iztro 一致。
`algorithm` 开关**不改四化表** —— 中州派与默认派用的是同一张表。
要换成别的取法，走 Config 的自定义四化表：整表替换某个天干的四化，
见 [Config 详解](/zh/docs/guide/guides/config#自定义四化表与亮度表)。
## 本命四化 [#本命四化]
排盘时用**出生年干**查上表，把四化标记打在对应的星上。
一张盘上的本命四化恰好四个 —— 被化的星里除了十四主星，还有文昌、文曲、左辅、右弼，
这四颗辅星一定在盘上，所以总数不会少。
## 运限四化 [#运限四化]
除了本命，每个运限层级还有自己的四化：大限用大限宫干、流年用流年干，
依次类推。它们叠加在同一张盘上，是运限解读的主要抓手。
返回的四颗星顺序固定为**禄、权、科、忌**。
## 飞星 [#飞星]
宫位也有天干（宫干）。用宫干查四化表，就得到这个宫「飞出去」的四颗星，
再看这四颗星落在哪个宫 —— 这就是**飞星**，用来描述宫与宫之间的作用关系。
## 自化 [#自化]
如果一个宫的宫干飞出的化星，正好就落在这个宫自己里面，称为**自化**。
自化在解读上意味着力量在本宫内部消耗或外泄，与飞入他宫的性质不同。
## 在代码里怎么取 [#在代码里怎么取]
### 读本命四化 [#读本命四化]
```python
for p in chart.palaces:
for s in p.major_stars + p.minor_stars:
if s.mutagen:
print(f"{p.name} 的 {s.name} 化{s.mutagen}")
```
```text
财帛 的 武曲 化权
子女 的 太阳 化禄
仆役 的 太阴 化科
疾厄 的 天同 化忌
```
### 读运限四化 [#读运限四化]
```python
h = chart.horoscope("2024-10-1", 0)
print(h.decadal.mutagen) # 大限四化的四颗星
print(h.yearly.mutagen) # 流年四化的四颗星
```
```text
['太阳', '武曲', '太阴', '天同']
['廉贞', '破军', '武曲', '太阳']
```
判断用标识形态 `h.yearly.mutagen_star_keys`——被化四星的星耀标识，与译文无关。
### 判断某宫有没有某个四化 [#判断某宫有没有某个四化]
```python
soul.has_mutagen(Mutagen.LU)
soul.not_have_mutagen(Mutagen.JI)
```
### 飞星判断 [#飞星判断]
```rust
let wealth = astrolabe.palace(Palace::Wealth).unwrap();
// 财帛宫的宫干化忌，是否落在命宫
wealth.flies_to(Palace::Soul, &[Mutagen::Ji]);
```
```python
soul.flies_one_of_to(PalaceName.WEALTH, [Mutagen.LU, Mutagen.QUAN])
soul.not_fly_to(0, Mutagen.JI)
places = soul.mutaged_places() # 禄权科忌各自飞入了哪个宫，长度为 4
```
### 自化判断 [#自化判断]
```rust
soul.self_mutaged(&[Mutagen::Lu]); // 命宫是否自化禄
soul.self_mutaged_one_of(&[]); // 是否有任意一种自化
soul.not_self_mutaged(&[]); // 四种自化都没有
```
`self_mutaged_one_of` 与 `not_self_mutaged` 传空即检查全部四化，
也可以只检查其中几种。
### 完整方法一览 [#完整方法一览]
| 方法 | 作用 |
| ----------------------------- | ----------------- |
| `has_mutagen(m)` | 本宫是否有指定四化 |
| `not_have_mutagen(m)` | 本宫是否没有指定四化 |
| `mutagen_stars(ms)` | 本宫宫干在指定四化位上对应的星 |
| `flies_to(target, ms)` | 指定化星是否**全部**落在目标宫 |
| `flies_one_of_to(target, ms)` | 是否有**任一颗**落在目标宫 |
| `not_fly_to(target, ms)` | 是否**一颗都不**落在目标宫 |
| `self_mutaged(ms)` | 本宫是否自化指定四化 |
| `self_mutaged_one_of(ms?)` | 本宫是否有任一自化 |
| `not_self_mutaged(ms?)` | 本宫指定自化全无 |
| `mutaged_places()` | 禄权科忌四星各自所在的宫 |
宫上另有 `mutagen_star_keys` 字段，直接给出本宫宫干化出的四颗星的标识，
顺序为禄、权、科、忌；用了自定义四化表时它也会跟着变。
这是复刻 iztro 的行为，三种编程语言一致：`flies_to` 在四化列表为空时返回 `false`，
而 `flies_one_of_to` 与 `not_fly_to` 在同样情况下返回 `true`。
三方四正范围内的四化判断见[三方四正](/zh/docs/guide/concepts/surrounded)。
# 三方四正 (/zh/docs/guide/concepts/surrounded)
为什么一个宫不能单独看，三方四正由哪四个宫组成，夹宫与它有什么不同，以及在三种编程语言里怎么取。
*适合：所有人。代码与判断方法表在页尾*
## 为什么需要它 [#为什么需要它]
单看一个宫会漏掉一半信息。紫微斗数的惯例是：解读任何一宫，都要连着它的
**对宫**与两个**三合宫**一起看。这四个宫合称**三方四正**。
最直观的理由是空宫 —— 一个宫里没有主星时，传统上要「借对宫的星来看」。
即便不是空宫，三方四正里的煞星与四化同样会影响本宫的判断。
## 由哪四个宫组成 [#由哪四个宫组成]
以本宫在盘上的位置为基准，另外三宫的位置是固定的：
| 成员 | 位置 | 说明 |
| --- | ------- | --------- |
| 本宫 | `i` | 要看的那个宫 |
| 对宫 | `i + 6` | 正对面，影响最直接 |
| 官禄位 | `i + 4` | 三合之一 |
| 财帛位 | `i + 8` | 三合之一 |
位置对 12 取模。这四个位置在盘上构成一个三角加一条对角线，
「三方」指三合的三个宫，「四正」指加上对宫共四个。
```
i+4 (官禄位)
／ ＼
／ ＼
i ──────── i+6 (对宫)
＼ ／
＼ ／
i+8 (财帛位)
```
「官禄位」与「财帛位」是**相对本宫**的称呼，不是盘上的官禄宫与财帛宫。
以命宫为本宫时它们才恰好是官禄宫和财帛宫；以其他宫为本宫时只是位置关系相同。
## 在代码里怎么取 [#在代码里怎么取]
三种编程语言都既接受宫位索引，也接受宫名：
```rust
let sp = astrolabe.surrounded_palaces(Palace::Soul).unwrap();
println!("{:?}", sp.opposite.name);
```
```python
sp = chart.surrounded_palaces(PalaceName.SOUL)
sp = chart.surrounded_palaces(soul.index)
```
```go
sp := chart.SurroundedPalaces(iztro.PalaceSoul) // 按宫名
sp = chart.SurroundedPalacesByIndex(soul.Index) // 按索引
```
四个成员分别是 `target`（本宫）、`opposite`（对宫）、`career`（官禄位）、
`wealth`（财帛位）。
### 判断方法 [#判断方法]
三方四正的判断方法与单宫同名，但检查范围是四个宫的并集，三种编程语言一致：
| 方法 | 作用 |
| --------------------- | ------------------- |
| `have(stars)` | 四宫合起来是否包含**全部**指定星耀 |
| `have_one_of(stars)` | 是否包含**任意一颗** |
| `not_have(stars)` | 是否**一颗都不包含** |
| `have_mutagen(m)` | 四宫中是否有任一宫带指定四化 |
| `not_have_mutagen(m)` | 四宫都没有指定四化 |
```go
sp := chart.SurroundedPalaces(iztro.PalaceSoul)
sp.Have(iztro.StarTianfuMaj) // 三方四正有天府
sp.HaveOneOf(iztro.StarQingyangMin, iztro.StarTuoluoMin) // 是否见羊陀
sp.NotHaveMutagen(iztro.MutagenJi) // 是否不见化忌
```
星盘上还有三个直接判断的快捷方法，省去先取三方四正这一步：
```python
chart.is_surrounded(PalaceName.SOUL, [MajorStar.TIANFU])
chart.is_surrounded_one_of(PalaceName.SOUL, [MinorStar.QINGYANG, MinorStar.TUOLUO])
chart.not_surrounded(PalaceName.SOUL, [MinorStar.HUOXING])
```
`have` 要求列表里的星**全部**出现，`have_one_of` 只要求出现一个。
判断「见煞」这类需求几乎总是用 `have_one_of`。
### 一个实际例子 [#一个实际例子]
判断命宫格局是否「吉星拱照且不见煞」：
```python
from x_iztro.enums import PalaceName, MinorStar
sp = chart.surrounded_palaces(PalaceName.SOUL)
lucky = sp.have_one_of([MinorStar.ZUOFU, MinorStar.YOUBI,
MinorStar.WENCHANG, MinorStar.WENQU])
clean = sp.not_have([MinorStar.QINGYANG, MinorStar.TUOLUO,
MinorStar.HUOXING, MinorStar.LINGXING])
print(lucky, clean, lucky and clean)
```
```text
True False False
```
这张盘的三方四正里有文昌文曲，但也见了羊陀火铃中的某几颗，所以不成立。
## 夹宫 [#夹宫]
**夹宫**是目标宫**前后相邻**的两宫：索引 `i - 1` 与 `i + 1`。十二宫在盘上首尾相连，
索引对 12 回绕 —— 第 0 宫的前一宫是第 11 宫。
```
… ── i-1 (前宫) ── i (被夹的宫) ── i+1 (后宫) ── …
```
夹宫与三方四正是两套**不重叠**的取象：`i±1` 与 `i+4` / `i+6` / `i+8` 没有一个位置相同。
| | 关系 | 成员 | 位置 |
| ---- | -- | ------------- | --------------------- |
| 三方四正 | 会照 | 本宫、对宫、官禄位、财帛位 | `i` `i+6` `i+4` `i+8` |
| 夹宫 | 相夹 | 前宫、后宫 | `i-1` `i+1` |
「会照」是隔着盘面遥相呼应，问的是同一组能量彼此照应；「相夹」是贴身左右挤住，
问的是这一宫被什么样的力量围住。取象不同，所以两条线索要分开读。
夹宫**不含本宫**：三方四正把本宫算作四个成员之一，夹宫只有前后两宫。
### 判定在两宫合计上做 [#判定在两宫合计上做]
判断方法与三方四正同名同义，检查范围换成**两个夹宫的并集**：
| 方法 | 作用 |
| --------------------- | ------------------- |
| `have(stars)` | 两宫合起来是否包含**全部**指定星耀 |
| `have_one_of(stars)` | 是否包含**任意一颗** |
| `not_have(stars)` | 是否**一颗都不包含** |
| `have_mutagen(m)` | 两宫中是否有任一宫带指定四化 |
| `not_have_mutagen(m)` | 两宫都没有指定四化 |
「夹」本来就是一边一颗。`have([天机, 天钺])` 在天机落前宫、天钺落后宫时为真 ——
判定看的是两宫合计的集合，不看它们分在哪一宫。
```rust
let f = chart.flanking_palaces(Palace::Soul).unwrap();
println!("{} / {}", translate_palace(f.previous.name, Language::ZhCN),
translate_palace(f.next.name, Language::ZhCN));
println!("{}", f.have(&[StarKey::TianjiMaj, StarKey::TianyueMin]));
println!("{}", f.have_one_of(&[StarKey::QingyangMin, StarKey::TuoluoMin]));
```
```text
兄弟 / 父母
true
true
```
```python
f = chart.flanking_palaces(PalaceName.SOUL)
print(f.previous.name, f.next.name)
print(f.have([MajorStar.TIANJI, MinorStar.TIANYUE]))
print(f.have_one_of([MinorStar.QINGYANG, MinorStar.TUOLUO]))
```
```text
兄弟 父母
True
True
```
```go
f, _ := chart.FlankingPalaces(iztro.PalaceTarget{Key: iztro.PalaceSoul})
fmt.Println(f.Previous.Name, f.Next.Name)
fmt.Println(f.Have(iztro.StarTianjiMaj, iztro.StarTianyueMin))
fmt.Println(f.HaveOneOf(iztro.StarQingyangMin, iztro.StarTuoluoMin))
```
```text
兄弟 父母
true
true
```
这张盘的命宫被兄弟宫（天机）与父母宫（天钺、陀罗）夹住。天机与天钺分居两侧，
`have` 仍为真；羊陀只见陀罗一颗，`have_one_of` 为真而 `have` 为假 ——
所以不成羊陀夹命。
### 命理上的用法 [#命理上的用法]
「XX 夹命」这一类格局用的就是这个几何：两颗星分居命宫前后邻宫。
[格局引擎](/zh/docs/guide/concepts/patterns)里的羊陀夹命、日月夹命、左右夹命、
魁钺夹命、劫空夹命、昌曲夹命、科权禄夹都判在夹宫上，紫府夹命、金舆扶驾亦然。
「夹」与「会照」为什么必须分开算，见格局页的
[几处容易误解的地方](/zh/docs/guide/concepts/patterns#几处容易误解的地方)。
夹宫也有自己的[语义化文本](/zh/docs/guide/guides/to-text)：前后两宫各一段，
与三方四正文本同构，角色标题写「前宫」「后宫」。
星耀的分类与标识见[星耀](/zh/docs/guide/concepts/stars)。
# 运限 (/zh/docs/guide/concepts/horoscope)
六个时间层级各自算什么，同一格子的宫名为什么会变，童限怎么起，流耀与流年十二神从哪来。
*适合：所有人。代码在页尾*
本命盘一生不变，**运限**是把时间叠加到本命盘上得到的动态信息。
给一个目标日期，x-iztro 一次返回六个层级。
## 同一个格子，宫名会变 [#同一个格子宫名会变]
这是运限里最容易绕住人的一点，先说清楚：
运限解读要把运限所在的那一宫当作「这一步的命宫」，其余十一宫跟着重排。
所以**同一个格子，在本命盘上是财帛宫，在某个大限里可能就是命宫**。
每个运限层级都给出一份重排后的十二宫名，按盘上位置排列。
本命盘的宫名不受影响，两套并存 —— 读结果时要分清手上拿的是哪一套。
## 六个层级 [#六个层级]
| 层级 | 周期 | 依据 |
| -- | --- | ----------------------- |
| 大限 | 十年 | 五行局起运虚岁 + 性别与年支阴阳定的行进方向 |
| 小限 | 一年 | 年支三合定起点，性别定方向 |
| 流年 | 一年 | 目标日期所在的农历年 |
| 流月 | 一月 | 目标日期所在的农历月 |
| 流日 | 一日 | 目标日期 |
| 流时 | 一时辰 | 目标时辰索引 |
大限与小限都是「按年龄推进」的，但规则完全不同，各走各的；
流年到流时则是「按日历推进」的。两套并行，共同构成一次查询的结果。
## 每个层级有什么 [#每个层级有什么]
除小限与流年外，每个层级的结构相同：
| 字段 | 含义 |
| ---------------------------------- | ------------------------- |
| `index` | 该运限落在哪一个盘上位置（0–11，第一格是寅宫） |
| `name` | 层级名，按盘面语言翻译（「大限」「流年」……） |
| `heavenly_stem` / `earthly_branch` | 该运限的干支 |
| `palace_names` | 以该运限位置为命宫重排的十二宫名 |
| `mutagen` | 该运限干引发的四化星，顺序为禄、权、科、忌 |
| `stars` | 流耀在十二宫的分布，没有流耀的层级为空 |
小限额外带**虚岁**（`nominal_age`）。
流年额外带**流年十二神**：按流年支重起的岁前十二神与将前十二神。
这两组与本命盘上宫位自带的那两组是两回事 ——
本命的按出生年支起，流年的按目标年支起。
## 童限 [#童限]
大限从五行局决定的虚岁才开始（水二局 2 岁、火六局 6 岁）。
在此之前的年份不属于任何大限，这段时间用**童限**推算。
童限按虚岁取宫，口诀是「一命二财三疾厄，四妻五福六官禄」：
| 虚岁 | 1 | 2 | 3 | 4 | 5 |
| --- | -- | -- | -- | -- | -- |
| 童限宫 | 命宫 | 财帛 | 疾厄 | 夫妻 | 福德 |
表到虚岁 5 为止：起运最晚的是火六局，6 岁即入第一个大限，
所以虚岁 6 及以后不会再是童限——口诀里的「六官禄」用不上，也不存在循环。
当目标日期落在起运之前，大限字段返回的就是童限，层级名显示为「童限」。
字段结构不变，所以调用方不需要特殊处理，只在需要区分时看层级名。
## 流耀 [#流耀]
流年、流月等层级会带一批只在该层级存在的星，称为**流耀**
（运昌、运曲、运魁、运钺、运鸾、运喜、运禄、运羊、运陀、运马，
以及流年层的流昌、流曲……）。它们按十二宫分组存放。
星的所属层级字段标明它属于哪一层：本命星是 `origin`，大限流耀是 `decadal`，
流年流耀是 `yearly`。
## 分界点会改变结果 [#分界点会改变结果]
运限的干支与虚岁受两个配置开关影响：
* `horoscope_divide` 决定运限年按正月初一还是立春换年，以及流月按初一还是节气分界
* `age_divide` 决定虚岁按农历年跨年加一，还是过了生日才加一
在年初或生日前后查询时，这两个开关会直接改变返回的干支与虚岁。
详见 [Config 详解](/zh/docs/guide/guides/config)。
## 在代码里怎么取 [#在代码里怎么取]
运限从已排好的盘发起，出生参数、盘面语言与配置都从盘上取，只需给目标日期与时辰：
```python
h = chart.horoscope("2024-10-1", 0)
```
```rust
let h = astrolabe.horoscope("2024-10-1", 0)?;
```
```go
h, err := astrolabe.Horoscope("2024-10-1", 0)
```
读六个层级：
```python
h = chart.horoscope("2024-10-1", 0)
print(h.decadal.name, h.decadal.heavenly_stem + h.decadal.earthly_branch, h.decadal.mutagen)
print(h.age.name, "虚岁", h.age.nominal_age)
print(h.yearly.name, h.yearly.heavenly_stem + h.yearly.earthly_branch)
print("流年重排宫名:", h.yearly.palace_names)
print("流年岁前十二神:", h.yearly.yearly_dec_star.suiqian12)
```
```text
大限 庚辰 ['太阳', '武曲', '太阴', '天同']
小限 虚岁 25
流年 甲辰
流年重排宫名: ['夫妻', '兄弟', '命宫', '父母', '福德', '田宅', '官禄', '仆役', '迁移', '疾厄', '财帛', '子女']
流年岁前十二神: ['吊客', '病符', '岁建', '晦气', '丧门', '贯索', '官符', '小耗', '大耗', '龙德', '白虎', '天德']
```
遍历流耀：
```python
for palace_index, stars in enumerate(h.yearly.stars or []):
for s in stars:
print(palace_index, s.name, s.scope)
```
小限与流年各自多带一项专属数据（虚岁、流年十二神），Rust 里通用字段收在 `.base` 下，
但两个类型都实现了 `Deref`，`h.yearly.heavenly_stem` 直接可读；序列化到 Python / Go 时
这一层被展平，同样写 `h.yearly.heavenly_stem`。
# 格局 (/zh/docs/guide/concepts/patterns)
什么是格局，x-iztro 按什么原则判定，本命与运限视角有何不同，以及 64 条格局的完整总表。
*适合：所有人。64 条格局总表在页尾*
## 什么是格局 [#什么是格局]
一张盘上，某几颗星按特定方式凑在一起，传统上会给这个组合起一个名字——
「紫府同宫」「杀破狼」「阳梁昌禄」都是这样的名字。这类有名字的星耀组合就是**格局**。
格局不是另一套算法，它只是在已经排好的盘上做**模式识别**：
看某几颗星是不是落在了某几个宫，亮度够不够，带没带四化。
盘一旦排完，格局就已经确定了。
格局在传统上还附带吉凶断语（「主贵」「主孤」之类）。
x-iztro **只判定组合是否成立，不给任何评价**——断语属于解读，
不同流派说法不一，交给你自己或你的模型。
## x-iztro 怎么判 [#x-iztro-怎么判]
格局这件事在古籍与各家资料里口径并不统一，同一个名字常有宽严两种说法。
这套引擎的取舍原则是：
1. **只做事实判定**。输出是「这个组合成立，证据是这几颗星落在这几个宫」，
不含吉凶、强弱、评分。
2. **每条规则注明来源**。规则实现里逐条写了古籍引文与所采口径，
以及为什么在两种说法之间选了这一种。
3. **多口径不设开关，用 `variant` 报出**。同一个格局有几种成立形式时，
引擎把命中的那一种记在 `variant` 字段上，由你决定认不认。
比如「机巨同临」在酉宫成立的那种，`variant` 是 `"you"`，
因为另有资料称酉宫不算此格——引擎照报，标注清楚。
4. **「破格」只标记不否决**。资料里说的「加杀平常」「破格」这类条件触发时，
格局照样报出来，只把 `broken` 置为真。成立与否是事实，好坏是解读。
5. **「身命」类格局命中哪宫记哪宫**。古籍常写「身命居子午」，
意思是命宫或身宫任一成立即可。这类格局命宫、身宫各判一次，
`palace_index` 记的是实际成格的那一宫，两宫都成立就报两次。
6. **空宫借对宫**。宫内没有主星时，按传统借对宫主星参与判定。
证据里记的仍是那颗星**真正待的宫**，不是借到的宫。
7. **没有金标，自己造证据**。iztro 本身没有格局 API，
所以这部分不像排盘那样有逐字段对照的金标数据。代之以四层测试：
每条规则的正反例单测（约 80 个）、来源页 32 张示例盘的真实盘复现、
tier1 那 1,560 张盘上的批量合理性与不变量检查（含每个格局的命中盘数统计），
以及 4 张盘 × 6 种语言的输出快照——快照由 Rust 写基线，Python 与 Go 读同一批文件比对，
三侧结果必须逐字节一致。
## 一次命中长什么样 [#一次命中长什么样]
一次命中就是一个 `PatternHit`，字段在三种编程语言里同名（大小写随语言习惯；
唯 Rust 结构体把 `palace_index` 叫 `palace`，序列化 DTO 的键统一是 `palaceIndex`）：
| 字段 | 说明 |
| --------------------------------- | ---------------------------------------------------- |
| `key` | 语言无关的格局标识，如 `zi_fu_tong_gong`。判断逻辑用它 |
| `name` | 格局名称，按排盘语言翻译 |
| `scope` | 判定视角：本命为 `origin`，运限为该层（`decadal`、`yearly`…） |
| `palace_index` | 成格所在的宫位索引（0-11，寅宫为 0） |
| `palace_name` / `palace_name_key` | 该宫在这个视角下的宫名与标识 |
| `variant` | 命中的是哪种口径；单口径格局没有这个值 |
| `broken` | 「破格」条件是否触发。成格照报，这里只作标记 |
| `stars` | 参与成格的星与各自落宫，每颗带 `key`、`name`、`palace_index`，有则带亮度与四化 |
拿一张盘列出它的全部格局：
```rust
let zh = Language::ZhCN;
let chart = by_solar("1985-5-3", 9, Gender::Male, true, zh, Config::default())?;
for hit in chart.patterns() {
println!("{} {}",
translate_pattern(hit.key, zh),
translate_palace(chart.palaces[hit.palace].name, zh));
}
```
```python
from x_iztro import Astro
chart = Astro().by_solar("1985-5-3", 9, "male")
for hit in chart.patterns():
print(hit.name, hit.palace_name)
```
```go
chart, _ := iztro.BySolar("1985-5-3", 9, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
hits, _ := chart.Patterns(nil)
for _, h := range hits {
fmt.Println(h.Name, h.PalaceName)
}
```
**输出**
```text
武贪同行 迁移
府相朝垣 命宫
杀破狼 迁移
禄马交驰 命宫
左右夹命 命宫
文贵文华 迁移
文星朝命 命宫
文星暗拱 命宫
文星暗拱 命宫
```
这张盘的身宫落在迁移宫，所以三条「身命」类格局（武贪同行、杀破狼、文贵文华）
记的是迁移宫而不是命宫。
`variant` 与 `broken` 也在同一批命中里：
```python
for hit in chart.patterns():
if hit.variant or hit.broken:
print(f"{hit.name}: variant={hit.variant} broken={hit.broken}")
```
```text
府相朝垣: variant=soul_empty broken=False
禄马交驰: variant=surround broken=False
文星朝命: variant=None broken=True
文星暗拱: variant=opposite broken=False
文星暗拱: variant=surround broken=False
```
府相朝垣的 `soul_empty` 表示这张盘的命宫确为空宫（古书「命无主星」那一支，
x-iztro 不把它当成格条件，只标注）；文星朝命的 `broken` 表示命宫三方四正见了煞忌；
禄马交驰的 `surround` 与文星暗拱的 `opposite` / `surround` 各是那条格局的一种成立口径，
逐条含义见页尾总表。
## 本命与运限是同一套规则 [#本命与运限是同一套规则]
引擎内部把「本命十二宫」和「某个运限层的合成十二宫」抽象成同一种视图，
规则只面对视图。所谓运限视角，就是把这三件事换掉之后再跑一遍全部规则：
* **命宫换成该层的命宫**。大限走到哪一宫，那一宫就是这一层的命宫，
十二宫名以它为起点重排。
* **合并该层的流曜**。运禄、流禄、运昌、流昌这些流曜，在判定时**等同于对应的本命辅星**：
运限盘上见到流禄，规则就当见到禄存。
* **四化换成该层的四化**。本命视角读生年四化，大限视角读大限干引发的四化，以此类推。
因此资料里说的「本命有此组合，大限又走到即享其益」自然成立——
在大限视角下重跑本命规则即可。运限视角**没有身宫**，
「身命」类格局在运限层只判该层命宫。
```rust
let h = chart.horoscope("2025-6-1", 0)?;
for hit in h.patterns(Scope::Decadal) {
println!("{} {:?}", translate_pattern(hit.key, zh), hit.variant);
}
```
```python
h = chart.horoscope("2025-6-1", 0)
for hit in h.patterns(Scope.DECADAL):
print(hit.name, hit.scope, hit.variant)
```
```go
h, _ := chart.Horoscope("2025-6-1", 0)
hits, _ := h.Patterns(iztro.ScopeDecadal, nil)
for _, x := range hits {
fmt.Printf("%s %s %q\n", x.Name, x.Scope, x.Variant)
}
```
用 2000-8-16 寅时的女命盘，大限视角（Python 版）：
```text
杀破狼 decadal None
风云际会 decadal None
风云际会 decadal yearly
```
同一张盘的本命视角只有一条「府相朝垣」——大限走到之后，
命宫换了位置，杀破狼才在这一层成立。
运限对象上传 `origin` 层，结果与直接在星盘上调 `patterns()` 完全一致。
### 两条只在运限出现的格局 [#两条只在运限出现的格局]
64 条里有两条是**行运格**：只在运限视角判定，本命盘上永远不报。
| 格局 | 何时判 | 说明 |
| ---------------------- | ------ | ----------------------------- |
| 禄衰马困 `lu_shuai_ma_kun` | 任一运限层 | 判定层级即当前视图那一层：大限视角判大限，流年视角判流年 |
| 风云际会 `feng_yun_ji_hui` | 只在大限视角 | 它比较的是「两限同时逢禄马」，跨层，所以只在大限视角报一次 |
风云际会的 `variant` 同时记二限组合与「逢」的松紧：无 variant 或 `same_palace`
取「大限 + 小限」，`yearly` 或 `yearly_same_palace` 取「大限 + 流年」（另有流派取这一种）；
带 `same_palace` 的是两限命宫皆本宫坐禄马的严口径，不带的是三方四正会照。
两种组合各报一条，最多两条，上面那张盘正是两种组合都成立。
## 日月的明暗按哪张表 [#日月的明暗按哪张表]
「日月并明」「日月反背」「丹墀桂墀」这几条要看太阳、太阴的明暗，
而明暗的判法有两种传统，结论会不一样：
| 口径 | 依据 | 标识 |
| ------- | --------------------------- | ------------ |
| 亮度表（默认） | 星盘自带的亮度，庙旺为明，陷与「不」为暗 | `table` |
| 传统位置 | 太阳寅至午为明、酉至丑为暗；太阴酉至丑为明、卯至未为暗 | `positional` |
x-iztro 的亮度表与 iztro **逐值一致**，这是整个库的红线。它与传统位置法的差集只有两格：
* **太阳在酉**：表判「平」，既不算明也不算暗；位置法算暗
* **太阴在寅**：表判「旺」即明；位置法算中性
所以分歧只可能出现在\*\*「皆暗」**一类格局（日月反背、日月藏辉）上。
「皆明」一类（日月并明、丹墀桂墀）两个口径**不可能\*\*有分歧——安星几何决定了
太阴在寅时太阳必在子（表判陷），两边都不成格。
```python
from x_iztro import Astro, PatternConfig, BrightnessSource
chart = Astro().by_solar("1985-6-10", 8, "female")
print([h.name for h in chart.patterns()])
print([h.name for h in chart.patterns(
PatternConfig(brightness_source=BrightnessSource.POSITIONAL))])
```
```text
[]
['日月反背']
```
## 三个口径开关 [#三个口径开关]
`PatternConfig` 只有三个字段。凡是「多口径」的格局一律走 `variant`，
不在这里加开关；这里只放会改变**事实判定本身**的数据口径。
| 字段 | 默认 | 作用 |
| ------------------- | ------- | ----------------- |
| `brightness_source` | `table` | 日月明暗的依据，见上一节 |
| `borrow` | `true` | 空宫是否借对宫主星参与判定 |
| `flow_stars` | `true` | 运限视角下流曜是否等同对应本命辅星 |
关掉 `borrow`，空宫就是空宫，靠借宫成立的格局不再报；
关掉 `flow_stars`，运限视角只认本命辅星，流禄流马不参与。
两者都只影响格局判定，不影响排盘结果。
## 64 条格局总表 [#64-条格局总表]
按来源页的条目顺序。「类别」一列里，**行运**表示只在运限视角判定，
其余在本命与运限两种视角下都会判。
判定条件一列写的是形式化条件的要点；每条规则的完整口径、古籍引文
与在两种说法间取舍的理由，写在实现的文档注释里（`src/pattern/rules/`）。
| # | 名称 | key | 判定条件 | variant | broken | 类别 |
| -- | ---- | ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------------- |
| 1 | 君臣庆会 | `jun_chen_qing_hui` | 紫微或天府与辅佐诸星成四种会合之一（见 variant） | `zi_po_zuo_you_jia` 紫微破军守命、左辅右弼分夹；`zi_xiang_chang_qu_axis` 紫微天相守命、昌曲分居命迁；`tian_fu_ji_yin_tong_liang_jia` 天府守命、机阴同梁四星俱全分布于命宫前后两宫（空侧借对宫主星补足）；`zi_zuo_you_tong_gong` 紫微与左辅右弼同守命宫 | 有（仅第四形式：三方四正见煞忌时标记；前三形式以无煞忌为成格前提） | 通用 |
| 2 | 紫府同宫 | `zi_fu_tong_gong` | 紫微、天府同守命宫（只可能在寅、申） | — | — | 通用 |
| 3 | 金舆扶驾 | `jin_yu_fu_jia` | 天府守命于丑或未，太阳、太阴分夹命宫 | — | — | 通用 |
| 4 | 紫府夹命 | `zi_fu_jia_ming` | 天机、太阴同守命宫，紫微、天府分夹（只可能在寅、申） | — | — | 通用 |
| 5 | 极向离明 | `ji_xiang_li_ming` | 紫微守命于午，且命宫三方四正无煞忌 | — | — | 通用 |
| 6 | 极居卯酉 | `ji_ju_mao_you` | 紫微、贪狼同守命宫于卯或酉 | — | — | 通用 |
| 7 | 机月同梁 | `ji_yue_tong_liang` | 命宫在寅或申，宫内为天同天梁或天机太阴（空宫借对宫主星） | `surround` 机月同梁四星齐见命宫三方四正（含借宫）的宽口径 | — | 通用 |
| 8 | 善荫朝纲 | `shan_yin_chao_gang` | 天机、天梁同守命宫或身宫（只可能在辰、戌） | — | — | 通用 |
| 9 | 机巨同临 | `ji_ju_tong_lin` | 天机、巨门同守命宫（只可能在卯、酉） | `you` 命宫在酉（另有资料称酉宫不算此格） | — | 通用 |
| 10 | 机巨居卯 | `ji_ju_ju_mao` | 天机、巨门同守命宫于卯 | — | — | 通用 |
| 11 | 日月同宫 | `ri_yue_tong_gong` | 太阳、太阴同守命宫（只可能在丑、未） | — | — | 通用 |
| 12 | 巨日同宫 | `ju_ri_tong_gong` | 太阳、巨门同守命宫（寅、申皆算） | — | — | 通用 |
| 13 | 日照雷门 | `ri_zhao_lei_men` | 太阳、天梁同守卯宫，且该宫是命宫或官禄宫 | `career` 落官禄宫（古书「守官禄宫亦然」；无 variant 为命宫） | — | 通用 |
| 14 | 日月并明 | `ri_yue_bing_ming` | 命宫三方四正内太阳、太阴皆明 | — | — | 通用 |
| 15 | 日月反背 | `ri_yue_fan_bei` | 命宫三方四正内太阳、太阴皆暗 | — | — | 通用 |
| 16 | 日月照璧 | `ri_yue_zhao_bi` | 太阳、太阴同守田宅宫 | — | — | 通用 |
| 17 | 金灿光辉 | `jin_can_guang_hui` | 太阳独坐命宫且命宫在午 | — | 有（三方四正见煞忌） | 通用 |
| 18 | 日月藏辉 | `ri_yue_cang_hui` | 日月反背，且命宫三方四正又见巨门 | — | — | 通用 |
| 19 | 丹墀桂墀 | `dan_chi_gui_chi` | 日月并明，且命宫本身坐着明的太阳或明的太阴 | — | — | 通用 |
| 20 | 日月夹命 | `ri_yue_jia_ming` | 太阳、太阴分居命宫前后邻宫，命宫不坐空亡星且宫内有吉星 | — | — | 通用 |
| 21 | 日月夹财 | `ri_yue_jia_cai` | 条件同日月夹命，把命宫换成财帛宫 | — | — | 通用 |
| 22 | 月朗天门 | `yue_lang_tian_men` | 太阴守命宫且命宫在亥 | — | — | 通用 |
| 23 | 月生沧海 | `yue_sheng_cang_hai` | 天同、太阴同坐子宫，且该宫是命宫或田宅宫 | `soul` 落命宫（页面别称「水澄桂萼」）；`property` 落田宅宫（全书原文） | — | 通用 |
| 24 | 明珠出海 | `ming_zhu_chu_hai` | 命宫为空宫且在未，对宫（迁移丑）坐天同、巨门 | — | — | 通用 |
| 25 | 武贪同行 | `wu_tan_tong_xing` | 武曲、贪狼同守命宫或身宫（只可能在丑、未） | — | — | 通用 |
| 26 | 铃昌陀武 | `ling_chang_tuo_wu` | 铃星、文昌、陀罗、武曲四星齐会命宫三方四正 | — | — | 通用 |
| 27 | 刑囚夹印 | `xing_qiu_jia_yin` | 廉贞、天相与刑星（天刑或擎羊）同守命宫或身宫 | — | — | 通用 |
| 28 | 生不逢时 | `sheng_bu_feng_shi` | 命宫的空亡星与廉贞同宫 | `pojun` 与之同宫的是破军（另有资料所立的形态） | — | 通用 |
| 29 | 雄宿朝元 | `xiong_su_chao_yuan` | 廉贞独坐寅或申守命 | — | 有（三方四正见火铃羊陀空劫） | 通用 |
| 30 | 府相朝垣 | `fu_xiang_chao_yuan` | 天府居官禄宫、天相居财帛宫，二宫朝拱命宫 | `soul_empty` 命宫确为空宫 | — | 通用 |
| 31 | 火贪 | `huo_tan` | 贪狼守命，火星同宫 | `surround` 火星只在三方四正会照 | — | 通用 |
| 32 | 铃贪 | `ling_tan` | 贪狼守命，铃星同宫 | `surround` 铃星只在三方四正会照 | — | 通用 |
| 33 | 石中隐玉 | `shi_zhong_yin_yu` | 巨门守命宫或身宫，且该宫在子或午 | — | — | 通用 |
| 34 | 梁马飘荡 | `liang_ma_piao_dang` | 天梁与天马同守命宫或身宫 | — | — | 通用 |
| 35 | 阳梁昌禄 | `yang_liang_chang_lu` | 太阳、天梁、文昌、禄存四星齐会命宫三方四正 | — | — | 通用 |
| 36 | 杀破狼 | `sha_po_lang` | 七杀、破军、贪狼三星之一坐命宫或身宫（三星恒成三合） | — | — | 通用 |
| 37 | 七杀朝斗 | `qi_sha_chao_dou` | 七杀守命，且命宫在子、午、寅、申 | `yang_dou` 命宫在寅或子（仰斗）；`chao_dou` 命宫在午或申（朝斗） | — | 通用 |
| 38 | 禄衰马困 | `lu_shuai_ma_kun` | 运限命宫三方四正内，禄存与空曜或耗曜同宫，同时天马与煞忌同宫 | `qisha` 限命宫三方四正又见七杀（古书「限逢七杀」严口径同时满足） | — | **行运** |
| 39 | 英星入庙 | `ying_xing_ru_miao` | 破军守命，且命宫在子或午 | — | — | 通用 |
| 40 | 众水朝东 | `zhong_shui_chao_dong` | 破军与文曲同守命宫，且命宫在寅或卯 | — | — | 通用 |
| 41 | 三奇加会 | `san_qi_jia_hui` | 化禄、化权、化科齐聚命宫三方四正 | `ke_soul_lu_wealth_quan_career` 化科在命宫、化禄在财帛、化权在官禄 | — | 通用 |
| 42 | 禄马交驰 | `lu_ma_jiao_chi` | 禄存与天马同宫（任一宫成立即报，可有多个命中） | `surround` 命宫三方四正内禄存、天马俱见而不必同宫（成格宫记命宫） | — | 通用 |
| 43 | 禄合鸳鸯 | `lu_he_yuan_yang` | 命宫的禄存与化禄成双：同宫，或一在命宫一在迁移宫对拱 | `opposite` 命迁对拱（无 variant 为同宫） | — | 通用 |
| 44 | 明禄暗禄 | `ming_lu_an_lu` | 命宫有禄存（或化禄），暗合宫有化禄（或禄存） | — | — | 通用 |
| 45 | 禄马佩印 | `lu_ma_pei_yin` | 禄存、天马、天相三星同宫（任一宫成立即报，成格宫记该宫） | — | 有（该宫见空亡星） | 通用 |
| 46 | 两重华盖 | `liang_chong_hua_gai` | 命宫禄存与化禄双禄坐守，又见空曜 | `kong_yao` 空曜取天空、截空、旬空的宽口径（无 variant 为原文的地空、地劫） | — | 通用 |
| 47 | 风云际会 | `feng_yun_ji_hui` | 大限与另一限的命宫三方四正各自见禄存、天马或化禄 | `yearly` / `yearly_same_palace` 取大限 + 流年（无 variant / `same_palace` 为大限 + 小限）；带 `same_palace` 为两限命宫皆本宫坐禄马的严口径 | — | **行运**（只在大限视角） |
| 48 | 羊陀夹命 | `yang_tuo_jia_ming` | 陀罗、擎羊分居命宫前后邻宫；被夹的命宫必坐禄存，一并记入证据 | — | — | 通用 |
| 49 | 马头带箭 | `ma_tou_dai_jian` | 命宫在午，擎羊同宫，且天同、太阴同守命宫（空宫借对宫） | `tanlang_lu` 午宫贪狼化禄与擎羊同宫（旁格） | — | 通用 |
| 50 | 左右同宫 | `zuo_you_tong_gong` | 左辅、右弼同守命宫或身宫（仅三方会照不算） | — | — | 通用 |
| 51 | 左右夹命 | `zuo_you_jia_ming` | 左辅、右弼分居命宫前后两宫 | — | — | 通用 |
| 52 | 辅弼拱主 | `fu_bi_gong_zhu` | 紫微守命，左辅、右弼来拱或来夹 | `surround` 两星皆在三方四正；`jia` 两星分居命宫前后 | — | 通用 |
| 53 | 魁钺夹命 | `kui_yue_jia_ming` | 天魁、天钺分居命宫前后两宫（同宫或会照不算） | — | — | 通用 |
| 54 | 坐贵向贵 | `zuo_gui_xiang_gui` | 天魁、天钺分坐命宫与迁移宫 | — | — | 通用 |
| 55 | 劫空夹命 | `jie_kong_jia_ming` | 地劫、地空分居命宫前后两宫 | — | — | 通用 |
| 56 | 禄逢两杀 | `lu_feng_liang_sha` | 禄存与空亡星同守命宫，且命宫三方四正见地空或地劫 | — | — | 通用 |
| 57 | 文贵文华 | `wen_gui_wen_hua` | 文昌、文曲同守命宫、身宫或命宫三方四正之一宫 | — | — | 通用 |
| 58 | 文星朝命 | `wen_xing_chao_ming` | 文昌、文曲皆见于命宫三方四正（含与命宫同宫） | — | 有（三方四正见煞忌） | 通用 |
| 59 | 昌曲夹命 | `chang_qu_jia_ming` | 文昌、文曲分居命宫前后两宫 | — | 有（三方四正见煞忌） | 通用 |
| 60 | 文星暗拱 | `wen_xing_an_gong` | 文昌、文曲以夹、迁移正照或三方会照之一拱照命宫（三种口径独立判定、命中即报） | `jia` 两星分居命宫前后两宫；`opposite` 两星同坐迁移宫正照；`surround` 两星皆见于命宫三方四正 | — | 通用 |
| 61 | 权禄生逢 | `quan_lu_sheng_feng` | 化权星与化禄星同守命宫，且两星皆庙旺 | — | — | 通用 |
| 62 | 科明暗禄 | `ke_ming_an_lu` | 化科守命宫，命宫的暗合宫有禄存或化禄 | `hua_lu` 暗合宫为化禄（部分流派口径；无 variant 为禄存） | — | 通用 |
| 63 | 科权禄夹 | `ke_quan_lu_jia` | 化禄、化权、化科中的两化分居命宫前后两宫 | — | — | 通用 |
| 64 | 甲第登庸 | `jia_di_deng_yong` | 化科守命宫，化权在迁移宫或两三合宫朝拱命宫 | `complete` 再会化禄或禄存 | — | 通用 |
来源页把「火贪、铃贪」并作一个条目讲，x-iztro 拆成两个独立标识，
所以条目是 63 条、格局标识是 64 个。
### 几处容易误解的地方 [#几处容易误解的地方]
「夹」指两颗星分别落在目标宫的**前后邻宫**（索引 -1 与 +1），与三方四正毫无重叠。
昌曲夹命与文星朝命各取其一：夹归夹命，会照（含同宫）归朝命。
文星暗拱则把夹（`jia`）、迁移正照（`opposite`）、三方会照（`surround`）三种口径并报——
来源页作者自己说明此格「名称和口径并不完全一致」，取舍留给调用方，
所以同一张盘上它可与昌曲夹命或文星朝命同时命中。
暗合宫按地支六合取：子丑、寅亥、卯戌、辰酉、巳申、午未。
明禄暗禄与科明暗禄用的是它，不是对宫。
判定里说的「空亡星」指旬空、空亡、截路、截空四颗杂耀；
「空劫」指地空、地劫两颗辅星。两重华盖、禄逢两杀里的「遇空劫」取后者，
生不逢时、禄马佩印里的「坐空亡」取前者。
它是「某一宫里禄存与天马同宫」，任一宫成立即报，`palace_index` 记那一宫，
一张盘上可能有不止一个命中。天马只落寅申巳亥，所以成格宫必是四生地。
## API 参考 [#api-参考]
* [Rust — patterns](/zh/docs/rust/patterns)
* [Python — patterns](/zh/docs/python/patterns)
* [Go — Patterns](/zh/docs/go/patterns)
## 格局释义在知识包里 [#格局释义在知识包里]
这一页与三个 API 参考页讲的是**判定**：哪几颗星怎么凑在一起才算成格。
成格之后「这条格局意味着什么」是解读，属于门派观点，
放在[知识包](/zh/docs/guide/guides/knowledge-pack)里——
内嵌的默认包给了 64 条格局各自的古籍引文、成立条件的文字描述与解读正文。
命中的 `key` 就是知识包 `patterns` 段的键，直接对上：
```python
pack = KnowledgePack.builtin()
for hit in chart.patterns():
print(hit.name, "|", pack.pattern(hit.key).quotes[0])
```
不认同其中的说法，写一份覆盖包换掉那几条，判定结果不变。
## 来源与署名 [#来源与署名]
格局规则的条目、示例盘与古籍引文取自
[iztro-docs](https://github.com/SylarLong/iztro-docs)《格局》页（MIT License，作者 Sylar Long），
引文本身出自《紫微斗数全书》。格局判定引擎、六语言格局名、
以及在多种说法之间的取舍与形式化，是 x-iztro 的实现——
iztro 本身没有对应的 API。
# 排盘是怎么算的 (/zh/docs/guide/concepts/how-it-works)
从出生数据到一张完整命盘的九个步骤，每一步在做什么、依据是什么。
*适合：所有人。想按步骤调 API 的看[排盘九步对应的 API](/zh/docs/guide/guides/step-api)*
排盘不是玄学，是一串确定的推算。给定同样的出生数据与同样的流派取舍，
任何人算出来的盘都该一模一样。这一页把这串推算拆成九步。
日常排盘不需要自己走这些步骤——直接用排盘入口即可。
读这一页是为了知道结果从哪来，以及某个字段为什么长这样。
## 全流程 [#全流程]
**公历转农历**
—— 得到农历年月日与四柱干支
**定月索引**
—— 处理闰月归属
**定命宫身宫**
—— 由月索引与时辰推出
**定五行局**
—— 由命宫干支推出
**起紫微天府**
—— 由五行局与农历日推出
**安十四主星**
—— 依紫微天府的位置铺开
**安辅星与杂耀**
—— 各按年干、年支、月、日、时起
**安四组十二神**
—— 长生、博士、岁前、将前
**推大限小限**
—— 由五行局、性别、年支决定
***
## 逐步说明 [#逐步说明]
### 1. 公历转农历 [#1-公历转农历]
斗数以农历为基础，但输入通常是公历。这一步同时得到年、月、日、时四柱干支。
年干支的换算时点受配置影响：正月初一与立春之间出生的人，两种配置得到不同的年干支。
年系杂耀另按一个独立的开关取年支——两个开关可以分别设，
因此年系杂耀与主星可能基于不同的年支。这是 iztro 的实际行为，x-iztro 原样复刻。
### 2. 定月索引 [#2-定月索引]
闰月十五日之后按下月算（可以关掉），晚子时不参与这项修正。
### 3. 定命宫身宫 [#3-定命宫身宫]
从寅宫起正月，顺数到生月，再从生月逆数到生时——落点即**命宫**。
**身宫**用同样的起点但顺数生时。命宫的天干由五虎遁从年干推得。
### 4. 定五行局 [#4-定五行局]
由**命宫干支**查表得出，五种取值：水二局、木三局、金四局、土五局、火六局。
局数（2/3/4/5/6）后面要用两次：起紫微时做除数，推大限时做起运岁数。
地盘改用身宫干支起局，人盘改用福德宫干支。起局干支一变，
后面第 5、6、8、9 步全部重算——这就是排盘视角配置做的事。
### 5. 起紫微天府 [#5-起紫微天府]
用农历日除以局数，按「起紫微星诀」定出紫微的落宫。
天府与紫微关于寅申一线互为镜像：天府位 = 12 − 紫微位（对 12 取模）。
### 6. 安十四主星 [#6-安十四主星]
紫微系六颗按固定间隔**逆时针**从紫微位铺开，天府系八颗**顺时针**从天府位铺开。
间隔不是连续的，中间有空位：
| 紫微系（逆行，从紫微位起） | 退几位 |
| ------------- | --- |
| 紫微 | 0 |
| 天机 | 1 |
| 太阳 | 3 |
| 武曲 | 4 |
| 天同 | 5 |
| 廉贞 | 8 |
| 天府系（顺行，从天府位起） | 进几位 |
| ------------- | --- |
| 天府 | 0 |
| 太阴 | 1 |
| 贪狼 | 2 |
| 巨门 | 3 |
| 天相 | 4 |
| 天梁 | 5 |
| 七杀 | 6 |
| 破军 | 10 |
两系铺完，十四主星的位置就全定了。生年干的四化标记也在这一步打上。
### 7. 安辅星与杂耀 [#7-安辅星与杂耀]
各组的起法依据不同：
| 组 | 依据 | 例 |
| ----------- | ------- | ------------- |
| 禄存、擎羊、陀罗 | 年干 | 「甲禄到寅宫」，禄前羊后陀 |
| 天马 | 年支 | 只落四马地（寅申巳亥） |
| 天魁、天钺 | 年干 | |
| 左辅、右弼 | 农历月 | 「辰上顺正寻左辅」 |
| 文昌、文曲 | 时支 | 「戌上逆时觅文昌」 |
| 火星、铃星 | 年支 + 时支 | |
| 地空、地劫 | 时支 | 亥宫起子时，地空逆、地劫顺 |
| 三台、八座、恩光、天贵 | 农历日 | 由辅星位置起初一数 |
| 年系杂耀 | 年干或年支 | 数量最多 |
四颗共用同一个农历日数，但起点与方向各不相同：
三台从左辅位**顺**数、八座从右弼位**逆**数、恩光从文昌位顺数、天贵从文曲位顺数
（恩光天贵再各退一位）。这是 iztro 的实际算法，x-iztro 原样复刻。
### 8. 安四组十二神 [#8-安四组十二神]
每组十二个标记排满十二宫，每宫恰好一个：
| 组 | 起点 | 顺逆 |
| ----- | ------------ | ------- |
| 长生十二神 | 五行局定（水二局在申…） | 性别与年支阴阳 |
| 博士十二神 | 禄存所在宫 | 同上 |
| 岁前十二神 | 年支所在宫 | 恒顺行 |
| 将前十二神 | 年支三合组定 | 恒顺行 |
### 9. 推大限小限 [#9-推大限小限]
大限从命宫起，每宫十年，起运岁数即局数（水二局 2 岁起，木三局 3 岁起…）；
顺逆由性别阴阳与年支阴阳决定。
小限另起一套：从年支所属三合组定的宫起，按虚岁逐年走一宫，
方向只看性别（男顺女逆）。
***
## 运限是另一条线 [#运限是另一条线]
以上九步排出的是**本命盘**，一次算完就固定了。运限是把本命盘投影到某个时间点：
按目标日期算出该层级的干支，据此重排十二宫名、算出该层级的四化与流耀。
本命盘不变，变的是「此刻站在哪一宫看」。见[运限](/zh/docs/guide/concepts/horoscope)。
## 想按步骤调 API [#想按步骤调-api]
九步在 x-iztro 里每一步都有对应的公开函数，可以只取中间某一步的结果。
对照表与「哪些步骤会被配置改变」见
[排盘九步对应的 API](/zh/docs/guide/guides/step-api)。
# 概览 (/zh/docs/guide/guides)
AI 解盘、配置与流派、跨语言判断、多种盘面语言输出、错误处理与扩展的使用指南。
*适合：所有人。每张卡片标了适合的读者*
装好之后会遇到的实际问题都在这一章。
## 最容易踩的三个坑 [#最容易踩的三个坑]
1. **用星名做判断**。换一种盘面语言，所有分支静默失效。
用[语言无关标识](/zh/docs/guide/guides/keys)。
2. **忽略晚子时**。23:00–24:00 出生要用时辰索引 `12` 而不是 `0`，
两者排出的盘不同。见 [Config](/zh/docs/guide/guides/config#晚子时归属-day_divide)。
3. **宫位位置当成宫名顺序**。十二宫数组的第一格是寅宫，不是命宫。
见[十二宫](/zh/docs/guide/concepts/palaces)。
# 不写代码怎么用它 (/zh/docs/guide/guides/for-non-developers)
x-iztro 能做什么、典型用在哪、要跟工程师交代哪几件事，以及它准不准。
*适合：命理爱好者 · 产品与决策者。全页无需读代码*
## 这是什么 [#这是什么]
x-iztro 是一个**排盘引擎**：给它出生日期、时辰、性别，它算出一张完整的紫微斗数命盘，
并能把这张盘转成一段大模型读得懂的文字。
它不是一个 App，也不是一个网站 —— 它是给程序用的一段代码，
需要由工程师装进你们自己的产品里。
## 它能做什么 [#它能做什么]
* **排一张完整的本命盘**：十二宫的位置与干支、每个宫里落了哪些星、
星的亮度与四化、四组十二神、大限与小限
* **算任意时间点的运限**：大限、小限、流年、流月、流日、流时六个层级
* **一键转成 AI 能读的文字**：不必自己描述盘面，
生成的文本直接贴给大模型就能开始问
* **六种盘面语言**：简体中文、繁体中文、英文、日文、韩文、越南文
* **流派可切换**：年分界点、晚子时归属、中州派、天地人三盘，都是配置项
它**不做**解读。星耀落宫算得出来，「这个人事业如何」不在库的职责里 ——
那一步交给 AI 或人。
## 典型用在哪 [#典型用在哪]
### AI 解盘机器人 [#ai-解盘机器人]
最常见的一种。用户在对话里报生日，后台调 x-iztro 排盘，
把生成的盘面文字连同用户的问题一起发给大模型，模型给出解读。
盘由库算准，话由模型来说 —— 两件事分开，各自可靠。
### 命理 App 的后端 [#命理-app-的后端]
App 前端负责画盘、做交互，排盘计算放在服务端。
同一份计算逻辑可以同时服务 iOS、Android、Web 和小程序。
### 批量数据分析 [#批量数据分析]
比如「这十万条出生数据里，命宫有紫微的占多少」「某个格局与某个字段的相关性」。
x-iztro 排一张盘是毫秒级的，几十万条数据在单机上跑得完。
## 需要找工程师吗 [#需要找工程师吗]
需要。x-iztro 是一个代码库，不是可以直接打开的软件。
但工作量很小：装上它、写三行调用、把结果接到你们已有的流程里。
一个熟练的后端工程师，做出一个能跑的原型通常在半天以内。
## 要跟工程师说什么 [#要跟工程师说什么]
把下面这几条转给他们就够了：
| 事项 | 内容 |
| ----- | ----------------------------------------------------------------------------- |
| 仓库 | [github.com/x-haose/x-iztro](https://github.com/x-haose/x-iztro) |
| 编程语言 | Rust、Python、Go 三选一，结果完全一致 |
| 安装 | Python 用 `pip install x-iztro`；Go 用 `go get`；Rust 用 `cargo add` |
| 环境要求 | Python 3.10 及以上 / Go 1.22 及以上 / Rust edition 2024 |
| 输入 | 出生日期、时辰索引（0–12）、性别，三样 |
| AI 用法 | 调 `chart.to_text()` 拿到盘面文字，直接喂大模型 |
| 文档 | [快速开始](/zh/docs/guide/getting-started)、[语义化文本](/zh/docs/guide/guides/to-text) |
不是小时数，是 0–12 的十三个值：0 是早子时（00:00–01:00），
1 丑时、2 寅时……11 亥时，12 是晚子时（23:00–24:00）。
对照表见[你需要准备的输入](/zh/docs/guide/getting-started#时辰索引)。
**23 点以后出生的要填 12，不是 0** —— 这两个值排出的盘不一样。
## 它准不准 [#它准不准]
「准」在这里有一个很具体的定义：**与 JS 版的
[iztro](https://github.com/SylarLong/iztro) 逐字段完全一致**。
iztro 是开源社区里最完整、维护时间最长的紫微斗数排盘实现之一，
不少前端项目在用。x-iztro 把它当作对照基准，
用 716,314 个测试用例逐字段核对 —— 任何一处不一致都当作 bug 修掉。
这句话的**边界**也要说清楚：与 iztro 一致不等于「命理界唯一正解」。
斗数流派众多，不同流派的安星与四化取法本来就不同。
x-iztro 保证的是「在同一套流派取舍下，算得和权威实现一模一样」，
而不是「这套流派取舍就是对的」。
详见[准确性保证](/zh/docs/guide/about/accuracy)。
## MIT 是什么意思 [#mit-是什么意思]
x-iztro 用 MIT 许可证开源。对使用方来说这意味着：
* **可以商用**，不需要付费，也不需要跟作者报备
* **可以闭源使用**：把它装进你们的商业产品里，产品本身不必开源
* **可以修改**
* 唯一的义务是**保留版权声明**（通常放在产品的「开源许可」页面里）
* 作者**不承担任何担保责任**：用出问题是你们自己的事
在开源许可证里，MIT 是限制最少的那一类，法务通常不会有意见。
# 语义化文本（to_text） (/zh/docs/guide/guides/to-text)
把一张盘、一段运限或一个宫位投影成 Markdown 文本，喂大模型或直接给人读。
*适合：所有人。这是这个库最直接的用法*
一张盘在 x-iztro 里有三种投影：`to_json` / DTO 是给机器的结构化形态，
译文字段是给界面的展示形态，**to\_text 是给语言和人的自然语言形态** ——
盘面事实的完整文字描述，喂给大模型是它最常见的用途之一，但它本身不是提示词，
不含任何指令。手工拼接这段描述既繁琐又容易漏字段，所以每个可解读的对象都自带 to\_text。
输出是 **Markdown 子集**：只用 `#`/`##`/`###` 三级标题、`- 标签: 值` 列表、`**粗体**`
与一张窄表。渲染成页面是文档，不渲染时源码同样可读，直接贴进对话框也不损失结构。
| 入口 | 内容 |
| ------------------ | ---------------------------------- |
| 星盘 `to_text` | 本命盘：基本信息、十二宫总览表、格局命中、从命宫起的十二宫详解 |
| 运限 `to_text` | 运限：大限、小限、流年、流月、流日、流时各一节，各层四化、流耀与格局 |
| 宫位 `to_text` | 单个宫位，与本命盘详解里该宫的段落逐字一致 |
| 三方四正 `to_text` | 本宫、对宫、财帛位、官禄位四宫各一段 |
| 夹宫 `to_text` | 目标宫前后相邻的两宫各一段 |
| 大限一览 `to_text` | 十二个大限一张表：本命宫、虚岁、年份、干支、四化 |
| `patterns_to_text` | 格局命中列表单独成文，本命与运限视角皆可 |
全部按**盘面语言**生成：中文盘出中文，英文盘出英文。带[知识包](#带释义的文本)时，
释义内联在对应事实旁，不另起附录（四化释义除外）。
## 用法 [#用法]
```python
chart = astro.by_solar("2000-8-16", 2, "female")
h = chart.horoscope("2025-1-1", 0)
text = f"{chart.to_text()}\n{h.to_text()}" # str(chart) / str(h) 等价
```
```rust
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let h = chart.horoscope("2025-1-1", 0)?;
let text = format!("{}\n{}", chart.to_text(), h.to_text());
```
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
h, _ := chart.Horoscope("2025-1-1", 0)
natal, _ := chart.ToText()
fortune, _ := h.ToText()
```
更细粒度的入口：
```python
chart.palace("命宫").to_text() # 单宫
chart.surrounded_palaces("命宫").to_text() # 三方四正
chart.flanking_palaces("命宫").to_text() # 夹宫
chart.decadal_list_to_text() # 大限一览
chart.patterns_to_text() # 本命格局
h.patterns_to_text("yearly") # 流年视角格局
```
```go
chart.PalaceToText(iztro.PalaceTarget{Key: iztro.PalaceSoul})
chart.SurroundedPalacesToText(iztro.PalaceTarget{Key: iztro.PalaceSoul})
chart.FlankingPalacesToText(iztro.PalaceTarget{Key: iztro.PalaceSoul})
chart.DecadalListToText()
chart.PatternsToText(nil)
h.PatternsToText(iztro.ScopeYearly, nil)
```
Rust 侧对应 `PalaceRef::to_text()`、`SurroundedPalaces::to_text()`、
`FlankingPalaces::to_text()`、`Astrolabe::decadal_list_to_text()` 与
`text` 模块的自由函数（`astrolabe_to_text` / `horoscope_to_text` /
`palace_to_text` / `surrounded_palaces_to_text` / `flanking_palaces_to_text` /
`decadal_list_to_text` / `patterns_to_text`），
便捷方法按排盘语言输出，自由函数可指定语言，见 [Rust — TextOptions](/zh/docs/rust/astro#textoptions)。
三语言输出逐字节一致。
## 结构总览 [#结构总览]
本命盘文本的骨架，从上到下：
```text
# 命盘 <阳历> <时辰> <性别>
## 基本信息 四行合并字段 + 生年四化（带落宫）
## 十二宫总览 宫位 | 主星 | 辅星 | 大限 的窄表，命宫起
## 格局 命中列表；无命中时整节省略
## 十二宫 从命宫起顺排：命兄夫子财疾迁仆官田福父
### 命宫 (壬午) · 大限 3-12 每宫一段：主星、辅星、杂耀、三方四正、宫干飞化、十二神、小限虚岁
### 兄弟 (辛巳) · 大限 13-22
…
```
运限文本：
```text
# 运限 <阳历> (<农历>)
## 大限 · 命宫: 本命X (干支) 四化、格局 + 十二宫表（大限宫 | 本命 | 主星 | 辅星 | 流耀）；未起运写「童限」
## 小限 · 命宫: 本命X · 虚岁 N 宫名、四化、该宫三组星
## 流年 · 命宫: 本命X (干支) 四化、格局 + 十二宫表（另加十二神列）
## 流月 · 命宫: 本命X (干支) 宫名、四化、流耀（带落宫）、格局
## 流日 · … 同流月
## 流时 · … 同流月
```
## 本命盘文本长什么样 [#本命盘文本长什么样]
下面是 2000-8-16 寅时 女这张盘的完整开头（基本信息、总览表、格局）与前两宫，
其余十宫同款列全：
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座
- 五行局: 木三局 · 命主: 破军 · 身主: 文昌
- 命宫: 午 · 身宫: 戌 (官禄) · 来因宫: 辰 (夫妻)
- 生年四化: 太阳化禄→子女, 武曲化权→财帛, 太阴化科→仆役, 天同化忌→疾厄
## 十二宫总览
| 宫位 | 主星 | 辅星 | 大限 |
|---|---|---|---|
| **命宫** 午 | 紫微(庙) | 文曲(陷) | 3-12 |
| 兄弟 巳 | 天机(平) | — | 13-22 |
| 夫妻 辰 [来因宫] | 七杀(庙) | 右弼, 火星(陷) | 23-32 |
| 子女 卯 | 太阳(庙)化禄, 天梁(庙) | — | 33-42 |
| 财帛 寅 | 武曲(得)化权, 天相(庙) | 天马 | 43-52 |
| 疾厄 丑 | 天同(不)化忌, 巨门(不) | 天魁, 地劫 | 53-62 |
| 迁移 子 | 贪狼(旺) | 铃星(陷) | 63-72 |
| 仆役 亥 | 太阴(庙)化科 | — | 73-82 |
| 官禄 戌 [身宫] | 廉贞(利), 天府(庙) | 左辅 | 83-92 |
| 田宅 酉 | — | 地空, 擎羊(陷) | 93-102 |
| 福德 申 | 破军(得) | 文昌(得), 禄存 | 103-112 |
| 父母 未 | — | 天钺, 陀罗(庙) | 113-122 |
## 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
## 十二宫
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
### 兄弟 (辛巳) · 大限 13-22
- 主星: 天机(平)
- 杂耀: 天喜, 天空, 孤辰
- 三方四正: 对宫 仆役 · 三合 疾厄, 田宅
- 宫干辛飞化: 巨门化禄→疾厄, 太阳化权→子女, 文曲化科→命宫, 文昌化忌→福德
- 十二神: 长生·病, 博士·小耗, 岁前·晦气, 将前·劫煞
- 小限虚岁: 6, 18, 30, 42, 54, 66, 78, 90, 102, 114
（其余十宫同款）
```
总览表与详解都从命宫起、按宫位索引递减排列（命、兄、夫、子、财、疾、迁、仆、官、田、福、父），
不是按盘上格子位置。「格局」节列出[格局引擎](/zh/docs/guide/concepts/patterns)在本命盘上的全部命中，
每条一行：格局名、命中宫、构成星耀；无命中时整节省略。
## 运限文本长什么样 [#运限文本长什么样]
目标日期 2025-1-1 早子时。大限与流年展开十二宫表，小限只写落宫与该宫星，
流月及以下只写落宫、重排宫名、四化、流耀与格局：
```text
# 运限 2025-1-1 (二〇二四年腊月初二)
## 大限 · 命宫: 本命夫妻 (庚辰)
- 四化: 太阳化禄→本命子女, 武曲化权→本命财帛, 太阴化科→本命仆役, 天同化忌→本命疾厄
- 格局: 杀破狼 (命宫), 风云际会 (命宫)
| 大限 | 本命 | 主星 | 辅星 | 流耀 |
|---|---|---|---|---|
| 命宫 | 夫妻 | 七杀(庙) | 右弼, 火星(陷) | — |
| 兄弟 | 子女 | 太阳(庙)化禄, 天梁(庙) | — | 运曲 |
| 夫妻 | 财帛 | 武曲(得)化权, 天相(庙) | 天马 | 运马 |
| 子女 | 疾厄 | 天同(不)化忌, 巨门(不) | 天魁, 地劫 | 运魁 |
| 财帛 | 迁移 | 贪狼(旺) | 铃星(陷) | — |
| 疾厄 | 仆役 | 太阴(庙)化科 | — | 运昌, 运鸾 |
| 迁移 | 官禄 | 廉贞(利), 天府(庙) | 左辅 | — |
| 仆役 | 田宅 | — | 地空, 擎羊(陷) | 运羊 |
| 官禄 | 福德 | 破军(得) | 文昌(得), 禄存 | 运禄 |
| 田宅 | 父母 | — | 天钺, 陀罗(庙) | 运钺, 运陀 |
| 福德 | 命宫 | 紫微(庙) | 文曲(陷) | — |
| 父母 | 兄弟 | 天机(平) | — | 运喜 |
## 小限 · 命宫: 本命官禄 · 虚岁 25
- 宫名: 命宫→本命官禄, 兄弟→本命田宅, 夫妻→本命福德, 子女→本命父母, 财帛→本命命宫, 疾厄→本命兄弟, 迁移→本命夫妻, 仆役→本命子女, 官禄→本命财帛, 田宅→本命疾厄, 福德→本命迁移, 父母→本命仆役
- 四化: 天同化禄→本命疾厄, 天机化权→本命兄弟, 文昌化科→本命福德, 廉贞化忌→本命官禄
- 主星: 廉贞(利), 天府(庙)
- 辅星: 左辅
- 杂耀: 天才, 天虚
## 流年 · 命宫: 本命夫妻 (甲辰)
- 四化: 廉贞化禄→本命官禄, 破军化权→本命福德, 武曲化科→本命财帛, 太阳化忌→本命子女
- 格局: 杀破狼 (命宫), 禄马交驰 (夫妻), 禄马佩印 (夫妻), 昌曲夹命 (命宫, 破格), 文星暗拱 (命宫)
| 流年 | 本命 | 主星 | 辅星 | 流耀 | 十二神 |
|---|---|---|---|---|---|
| 命宫 | 夫妻 | 七杀(庙) | 右弼, 火星(陷) | — | 岁前·岁建, 将前·华盖 |
| 兄弟 | 子女 | 太阳(庙)化禄, 天梁(庙) | — | 流羊 | 岁前·病符, 将前·息神 |
| 夫妻 | 财帛 | 武曲(得)化权, 天相(庙) | 天马 | 流禄, 流马 | 岁前·吊客, 将前·岁驿 |
（其余九行同款）
## 流月 · 命宫: 本命仆役 (丁丑)
- 宫名: 命宫→本命仆役, 兄弟→本命官禄, 夫妻→本命田宅, 子女→本命福德, 财帛→本命父母, 疾厄→本命命宫, 迁移→本命兄弟, 仆役→本命夫妻, 官禄→本命子女, 田宅→本命财帛, 福德→本命疾厄, 父母→本命迁移
- 四化: 太阴化禄→本命仆役, 天同化权→本命疾厄, 天机化科→本命兄弟, 巨门化忌→本命疾厄
- 流耀: 月鸾→田宅, 月曲→迁移, 月陀→迁移, 月禄→疾厄, 月羊→财帛, 月喜→子女, 月钺→夫妻, 月昌→夫妻, 月魁→命宫, 月马→命宫
- 格局: 机月同梁 (命宫), 日照雷门 (官禄), 日月并明 (命宫), 丹墀桂墀 (命宫), 月朗天门 (命宫), 禄马交驰 (田宅), 明禄暗禄 (命宫), 禄马佩印 (田宅), 文星朝命 (命宫, 破格), 文星暗拱 (命宫)
## 流日 · 命宫: 本命迁移 (庚午)
- 宫名: 命宫→本命迁移, 兄弟→本命仆役, 夫妻→本命官禄, 子女→本命田宅, 财帛→本命福德, 疾厄→本命父母, 迁移→本命命宫, 仆役→本命兄弟, 官禄→本命夫妻, 田宅→本命子女, 福德→本命财帛, 父母→本命疾厄
- 四化: 太阳化禄→本命子女, 武曲化权→本命财帛, 太阴化科→本命仆役, 天同化忌→本命疾厄
- 流耀: 日曲→田宅, 日喜→田宅, 日钺→疾厄, 日陀→疾厄, 日禄→财帛, 日马→财帛, 日羊→子女, 日鸾→子女, 日昌→兄弟, 日魁→父母
- 格局: 火贪 (命宫), 铃贪 (命宫), 杀破狼 (命宫), 禄马交驰 (福德), 禄马佩印 (福德), 文星朝命 (命宫, 破格), 文星暗拱 (命宫)
## 流时 · 命宫: 本命迁移 (丙子)
（同流日的写法）
```
大限与流年及以下各层都带该层视角的格局行，格局后括号里的宫名按该层重排后的宫名书写；
小限不设格局视角。各层的「四化」行箭头指向的是**本命盘**的宫（四化星安在本命盘上，不随层级重排），
所以落宫写作「本命仆役」；流耀行与十二宫表用的才是该层重排后的宫名。
命主尚未起运时，大限节的标题与表头写「童限」而非「大限」——童限与大限是不同的解盘语义。
## 格式约定 [#格式约定]
| 记号 | 含义 |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `# 命盘 2000-8-16 寅时 女`、`# 运限 2025-1-1 (…)` | 文档标题：本命盘带阳历、时辰、性别；运限带目标日期的阳历与农历 |
| `## 基本信息`、`## 十二宫总览`、`## 格局`、`## 十二宫`、`## 四化释义` | 本命盘的节；`## 大限`、`## 小限`、`## 流年`、`## 流月`、`## 流日`、`## 流时` 是运限的节 |
| `### 命宫 (壬午) · 大限 3-12` | 一宫一段：宫名、宫干支、这一宫作大限时的虚岁区间 |
| `### 官禄 (丙戌) · 大限 83-92 [身宫]` | 方括号标记该宫同时是身宫；`[来因宫]` 标记[来因宫](/zh/docs/guide/concepts/palaces#来因宫)。总览表的宫位列同样标记 |
| `- 标签: 值` | 事实行；同一行多个字段用 `·` 分隔，列表项用 `, ` 分隔 |
| `\| 宫位 \| 主星 \| 辅星 \| 大限 \|` | 十二宫总览的窄表，命宫加粗；空单元格写 `—` |
| `紫微(庙)` | 括号内是[亮度](/zh/docs/guide/concepts/stars#亮度)，无亮度的星不带括号 |
| `太阳(庙)化禄` | [四化](/zh/docs/guide/concepts/mutagen)写全称「化禄 / 化权 / 化科 / 化忌」，紧跟在星名（与亮度）之后；英文盘写 `[A]`/`[B]`/`[C]`/`[D]` |
| `太阴化禄→疾厄` | 箭头指向该四化星在**本命盘**上落的宫。生年四化与宫干飞化这样写；星不在盘上时不写箭头 |
| `- 四化: 太阴化禄→本命仆役, …` | 运限各层的四化行：落宫同样是本命盘的宫，但该层段落里的宫名默认指该层重排宫名，故加「本命」前缀标明参照系 |
| `月鸾→田宅` | 流月及以下层级的流耀行：箭头指向该流耀落在**这一层重排后**的哪个宫 |
| `- 主星: 空宫` | 无主星的宫写「空宫」；辅星、杂耀为空时整行省略 |
| `- 三方四正: 对宫 迁移 · 三合 财帛, 官禄` | 本宫的对宫，与三合的另外两宫，固定按财帛位、官禄位的顺序（[三方四正](/zh/docs/guide/concepts/surrounded)） |
| `### 本宫 · 命宫 (壬午) · 大限 3-12` | 三方四正文本的宫段标题：宫名前多一个角色——`本宫`、`对宫`、`财帛位`、`官禄位` |
| `### 前宫 · 兄弟 (辛巳) · 大限 13-22` | 夹宫文本的宫段标题：角色是 `前宫`、`后宫`，事实行与三方四正逐字同构 |
| `\| 序 \| 本命宫 \| 虚岁 \| 年份 \| 干支 \| 四化 \|` | 大限一览的表头：十二行一行一限，按起运先后排；四化列的箭头指向本命宫 |
| `- 宫干壬飞化: 天梁化禄→子女, …` | 以本宫宫干起的[飞星四化](/zh/docs/guide/concepts/mutagen#飞星)：四化星与各自落宫 |
| `- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞` | 四组各一位，写「组名·神名」，固定顺序长生 12、博士 12、岁前 12、将前 12；流年表的十二神列只有岁前、将前两组 |
| `- 小限虚岁: 5, 17, 29, …` | 小限落在本宫的虚岁 |
| `- **府相朝垣** (命宫): 天府(庙), 天相(庙)` | 格局行：格局名加粗，括号内是命中宫，冒号后是构成星耀 |
| `昌曲夹命 (命宫, 破格)` | 括号里追加「破格」：格局构成但被冲破 |
| `## 大限 · 命宫: 本命夫妻 (庚辰)` | 这一层的命宫落在本命的哪个宫，括号内是该层干支 |
| `## 小限 · 命宫: 本命官禄 · 虚岁 25` | 小限落宫与虚岁 |
| `\| 大限 \| 本命 \| 主星 \| 辅星 \| 流耀 \|` | 运限层十二宫表：第一列是**这一层重排后的宫名**，第二列是本命宫名，主星辅星是本命盘的，流耀是这一层的 |
| `- 宫名: 命宫→本命官禄, …` | 小限、流月及以下层级不展开十二宫表，改用这一行给出对应：从该层命宫起顺排，箭头左边是该层重排宫名、右边是本命宫名 |
| `**紫微(庙)**: 正文` | 释义条目（[带知识包](#带释义的文本)时才有）：标题是星、格局或四化的写法，正文是知识包原文 |
| `**紫微 × 天府 (同宫)**: 正文` | 同宫主星的组合解读 |
| `成立条件: …` | 格局释义正文末尾的成格条件 |
`| 夫妻 | 财帛 | …` 说的是「这一格在本大限里叫夫妻宫，它在本命盘上是财帛宫」。
运限解读要以第一列为准，第二列是为了让你能对回本命盘。
见[运限](/zh/docs/guide/concepts/horoscope#同一个格子宫名会变)。
日期字段原样回显入参，不补零：传 `"2000-8-16"` 输出就是 `阳历: 2000-8-16`。
## 七个入口 [#七个入口]
| 入口 | 输出 |
| ------------------ | --------------------------------------------------------------------------------------- |
| 星盘 | 上面的完整本命盘文本 |
| 运限 | 上面的完整运限文本；本命信息不重复，两段拼起来就是一份完整上下文 |
| 宫位 | 本命详解里该宫的那一段（`### 宫名 …` 起的一段），逐字一致，可从本命文本里 `contains` 到 |
| 三方四正 | `## 命宫 三方四正` 标题 + 本宫、对宫、财帛位、官禄位四宫各一段；每段标题带角色前缀（`### 本宫 · 命宫 …`），事实行与单宫文本逐字一致 |
| 夹宫 | `## 夹宫` 标题 + [前后两宫](/zh/docs/guide/concepts/surrounded#夹宫)各一段，与三方四正同构，角色前缀是 `前宫` / `后宫` |
| 大限一览 | `# 大限一览` 标题 + 十二行的表，一行一限 |
| `patterns_to_text` | 只有格局行，每条一行；本命视角与运限各层视角皆可 |
八个 bridge kind 与之对应：`patterns_to_text` 的本命视角与运限视角是两个 kind
（`patternsToText` / `horoscopePatternsToText`），其余六个入口一个入口一个 kind。
单宫与三方四正：
```text
## 命宫 三方四正
### 本宫 · 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
### 对宫 · 迁移 (戊子) · 大限 63-72
- 主星: 贪狼(旺)
- 辅星: 铃星(陷)
- 杂耀: 八座
- 三方四正: 对宫 命宫 · 三合 福德, 夫妻
- 宫干戊飞化: 贪狼化禄→迁移, 太阴化权→仆役, 右弼化科→夫妻, 天机化忌→兄弟
- 十二神: 长生·养, 博士·病符, 岁前·白虎, 将前·将星
- 小限虚岁: 11, 23, 35, 47, 59, 71, 83, 95, 107, 119
### 财帛位 · 财帛 (戊寅) · 大限 43-52
（事实行同单宫）
### 官禄位 · 官禄 (丙戌) · 大限 83-92 [身宫]
（事实行同单宫）
```
单宫文本就是去掉角色前缀的其中一段（`### 命宫 (壬午) · 大限 3-12` 起）。
命宫的夹宫 —— 兄弟宫与父母宫，事实行与单宫文本同款：
```text
## 夹宫
### 前宫 · 兄弟 (辛巳) · 大限 13-22
- 主星: 天机(平)
- 杂耀: 天喜, 天空, 孤辰
- 三方四正: 对宫 仆役 · 三合 疾厄, 田宅
- 宫干辛飞化: 巨门化禄→疾厄, 太阳化权→子女, 文曲化科→命宫, 文昌化忌→福德
- 十二神: 长生·病, 博士·小耗, 岁前·晦气, 将前·劫煞
- 小限虚岁: 6, 18, 30, 42, 54, 66, 78, 90, 102, 114
### 后宫 · 父母 (癸未) · 大限 113-122
- 主星: 空宫
- 辅星: 天钺, 陀罗(庙)
- 杂耀: 天姚, 空亡
- 三方四正: 对宫 疾厄 · 三合 子女, 仆役
- 宫干癸飞化: 破军化禄→福德, 巨门化权→疾厄, 太阴化科→仆役, 贪狼化忌→迁移
- 十二神: 长生·帝旺, 博士·力士, 岁前·贯索, 将前·天煞
- 小限虚岁: 4, 16, 28, 40, 52, 64, 76, 88, 100, 112
```
大限一览是一张十二行的表，一行一限（截前三行，其余九行同款）：
```text
# 大限一览
| 序 | 本命宫 | 虚岁 | 年份 | 干支 | 四化 |
|---|---|---|---|---|---|
| 1 | 命宫 | 3-12 | 2002-2011 | 壬午 | 天梁化禄→本命子女, 紫微化权→本命命宫, 左辅化科→本命官禄, 武曲化忌→本命财帛 |
| 2 | 兄弟 | 13-22 | 2012-2021 | 辛巳 | 巨门化禄→本命疾厄, 太阳化权→本命子女, 文曲化科→本命命宫, 文昌化忌→本命福德 |
| 3 | 夫妻 | 23-32 | 2022-2031 | 庚辰 | 太阳化禄→本命子女, 武曲化权→本命财帛, 太阴化科→本命仆役, 天同化忌→本命疾厄 |
```
这张表**不展开每限的流年** —— 十二限各十年会撑到一百二十行，它要做的是一眼看完一生的
十二个十年。某一限的流年用 `yearly_list` 单取。
格局文本：
```text
# 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
```
## 带释义的文本 [#带释义的文本]
上面的文本只有事实。每个 to\_text 都有一个带[知识包](/zh/docs/guide/guides/knowledge-pack)参数的形态：
释义**内联**在对应的事实旁——每宫事实之后紧跟该宫星耀的释义，格局列表之后紧跟格局释义，
文末附四化释义。材料按盘从知识包里取，原文照录。内核只做「按盘取材 + 装配」，
不内置任何解读观点：传内嵌默认包就是 iztro-docs 的说法，传合并覆盖包之后的自定义包就是你的说法。
`by_solar` 与 DTO 输出不变。
```python
chart.to_text(knowledge=True) # True 取盘语言的内嵌默认包
chart.to_text(knowledge=my_pack) # 或任意 KnowledgePack
h.to_text(knowledge=True)
chart.palace("命宫").to_text(knowledge=True)
chart.surrounded_palaces("命宫").to_text(knowledge=True)
chart.flanking_palaces("命宫").to_text(knowledge=True)
chart.decadal_list_to_text(knowledge=True)
chart.patterns_to_text(knowledge=True)
h.patterns_to_text("yearly", knowledge=True)
chart.to_text(knowledge=True, config=PatternConfig(borrow=False)) # 五处 to_text 都收 config
```
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let opts = TextOptions::new().knowledge(&pack);
chart.to_text_with(&opts);
h.to_text_with(&opts);
chart.palace(Palace::Soul).unwrap().to_text_with(&opts);
chart.surrounded_palaces(Palace::Soul).unwrap().to_text_with(&opts);
chart.flanking_palaces(Palace::Soul).unwrap().to_text_with(&opts);
chart.decadal_list_to_text_with(&opts);
text::patterns_to_text_with(&hits, &names, &opts, chart.language);
let cfg = PatternConfig { borrow: false, ..PatternConfig::default() };
chart.to_text_with(&TextOptions::new().knowledge(&pack).pattern_config(&cfg));
```
```go
opts := iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()} // 或 iztro.KnowledgeFrom(pack)
chart.ToTextWith(opts)
h.ToTextWith(opts)
chart.PalaceToTextWith(iztro.PalaceTarget{Key: iztro.PalaceSoul}, opts)
chart.SurroundedPalacesToTextWith(iztro.PalaceTarget{Key: iztro.PalaceSoul}, opts)
chart.FlankingPalacesToTextWith(iztro.PalaceTarget{Key: iztro.PalaceSoul}, opts)
chart.DecadalListToTextWith(opts)
chart.PatternsToTextWith(opts)
h.PatternsToTextWith(iztro.ScopeYearly, opts)
cfg := iztro.PatternConfig{Borrow: iztro.Bool(false)}
chart.ToTextWith(iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge(), PatternConfig: &cfg})
```
格局判定口径（`config` / `pattern_config` / `PatternConfig`）与 `patterns(config)` 同一入参，
同时作用于文本里的格局节与格局释义：口径变了，命中的格局与紧跟其后的释义一起变。
不传取默认口径。大限一览没有格局节，故不收这个入参。
### 插入位置与去重 [#插入位置与去重]
| 入口 | 释义放在哪 |
| ------------------ | -------------------------------------------------------------------- |
| 星盘 | `## 格局` 的命中列表之后：每个格局一条；每宫 `### ` 段的事实行之后：该宫每颗星一条；文末 `## 四化释义`：禄权科忌四条 |
| 运限 | 大限与流年的十二宫表之后、流月及以下各层的事实行之后：该层流耀各一条、该层命中格局各一条 |
| 宫位 | 该宫事实行之后：该宫每颗星一条 |
| 三方四正 | 四宫各自的事实行之后 |
| 夹宫 | 前后两宫各自的事实行之后 |
| 大限一览 | 表之后 `## 星耀释义`：各限四化星每颗一条，同一颗星在多限重复出现时只出一次 |
| `patterns_to_text` | 格局列表之后 |
* 释义条目写作 `**标题**: 正文`，标题就是事实行里那颗星的写法（`**紫微(庙)**`、`**太阳(庙)化禄**`），
正文是知识包里的 `intro` 原文（Markdown，一字不裁），条目之间空一行。
* 同宫主星之间的组合解读（知识包 `combinations`）写作 `**紫微 × 天府 (同宫)**: …`，
放在该宫释义的最前面；两个方向都查，组合解读只写在其中一方名下同样会出，每对只出一次。
* 每宫按主星、辅星、杂耀的顺序逐星释义；**十二神不释义**。
* 格局释义是 `intro` 正文，末尾另起一段 `成立条件: …`。
* 运限文本里只释义流耀与各层格局，本命星耀不重复（本命盘的释义在本命盘文本里）；
同一颗流耀、同一个格局在多层出现时只在第一次出现的层释义（跨层去重）。
* 知识包里没有条目的星或格局，不写条目也不留占位。
下面是 2000-8-16 寅时 女这张盘命宫段带释义的样子（正文截断）：
```text
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
**紫微(庙)**: 紫微星号称 `帝王星`，并非指紫微坐命者能成帝王，而是指其个性带有“王者”特质……
**文曲(陷)**: 文曲星是紫微斗数里第一文艺之星，代表艺术修养与浪漫……
**凤阁**: 凤阁星会增加比较柔和的技能天赋，比如音乐、舞蹈……
（天福、截路、蜚廉、年解各一条）
```
格局节带释义：
```text
# 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
**府相朝垣**: “食禄千锺”的断语使此格备受欢迎，但成格并不必然富足。……
成立条件: 此格指 天府星 在官禄宫、天相星 在财帛宫会照命宫。……
```
节标题与条目标题按盘面语言翻译：英文盘上是 `## Mutagen Notes` 与 `**emperor([+3])**`，
正文仍是包里的语言。
### 篇幅 [#篇幅]
释义给全文，裁剪归应用层。同一张盘的实测字符数（中文盘，默认包）：
| 入口 | 只有事实 | 带释义 |
| -------- | ----- | ------ |
| 本命盘 | 3,389 | 20,765 |
| 运限 | 2,697 | 8,698 |
| 单宫（命宫） | 222 | 1,141 |
| 三方四正（命宫） | 924 | 6,312 |
| 夹宫（命宫） | 436 | 1,874 |
| 大限一览 | 1,045 | 6,447 |
| 格局 | 36 | 328 |
英文盘更长（星名是单词而非两字，且多一套结构标签）：本命 6,757、运限 6,378、单宫 464、
三方四正 1,911、夹宫 895、大限一览 1,893、格局 95。
任何主流模型的上下文窗口都装得下，通常不必裁剪。本命盘的释义占大头是因为盘上每颗主星、辅星、杂耀都有条目。
只要某几个宫的释义，用宫位或三方四正的入口；要自己排版，用
[`for_astrolabe`](/zh/docs/guide/guides/knowledge-pack#按盘取材) 取出这张盘的子包自己拼。
### 自定义包 [#自定义包]
包是参数，合并覆盖包之后的结果照样传：
```python
pack = KnowledgePack.builtin().merged(KnowledgePack.from_json(open("my-school.json").read()))
chart.to_text(knowledge=pack)
```
同一张盘传不同的包，事实部分逐字节相同，只有释义条目随包变。
内嵌默认包只有 zh-CN。英文（及其他四种语言）盘上 `knowledge=True` / `BuiltinKnowledge()` /
`KnowledgePack::builtin(Language::EnUS)` 报 `invalid_argument`，不会静默退回到无释义。
显式传一份包即可——包的语言不受盘语言限制，英文盘配中文包得到英文标题、中文正文。
## 六种语言 [#六种语言]
结构标签（「基本信息」「主星」「三方四正」「大限」……）有 zh-CN、zh-TW、en-US、ja-JP、ko-KR、vi-VN
六套；星名、宫名、干支、亮度、四化、格局名按盘面语言现翻。同一张盘六种语言的骨架逐行对应，
只有词不同。农历日期在任何语言下都是汉字数字（`二〇〇〇年七月十七`）。
四化标记随语言：中文写 `化禄`、日文 `化祿`，英文写 `[A]`（`[A]`/`[B]`/`[C]`/`[D]` 依次是禄权科忌），
韩文 `화록`，越南文 `hóa Lộc`。分词也随语言：拉丁字母语言里星名与四化标记之间、干支之间以空格分开
（英文 `sun [A]`、`### soul (ren woo)`，越南文 `Thái Dương hóa Lộc`、`(Nhâm Ngọ)`），
复合标签同理（`Natal spouse`）；中文与日文直接相连（`太阳化禄`、`(壬午)`、`本命夫妻`）。
Rust 自由函数收显式语言：中文盘按 en-US 渲染，与原生英文盘的渲染逐字节一致——
星名按 key 现翻，不是拿盘上固化的译名，所以不会出现混排。
优先用中文盘。英文盘的星名走 iztro 的意译词表（紫微是 `emperor`、七杀是 `marshal`），
亮度退化成 `[+3]` 这类记号，四化写成 `[A]`/`[B]`/`[C]`/`[D]`，
流耀的英文名自带层级后缀（运曲是 `artist(D)`、流禄是 `money(Y)`），
年解的英文名 `considery(Y)` 里的 `(Y)` 也是星名的一部分——
这套写法与英文命理界的通行译法不同，模型未必认得。
主流模型的中文命理术语能力都不差，直接喂中文文本效果更好。
确实需要英文时，建议附上一份[星名对照表](/zh/docs/guide/concepts/stars#星名对照表)。
## 接入大模型 [#接入大模型]
生成的文本是纯描述，不含指令。实际使用时在前面加上你的分析要求：
```python
system = "你是紫微斗数分析师。基于给定命盘作答，不要编造盘上没有的信息。"
user = f"""{chart.to_text()}
{chart.horoscope("2025-1-1", 0).to_text()}
请分析这个人 2025 年的事业运势。"""
```
要让模型按某一家的说法解读而不是自由发挥，把 `chart.to_text()` 换成
`chart.to_text(knowledge=True)`（或传你的包），释义随盘一起进上下文。
文本是 Markdown，模型能直接把「十二宫总览」当表读、把 `### ` 当宫段边界，
要求它「引用宫段」时也有稳定的锚点。
更完整的接法（工具调用、别让模型自己排盘）见[让 AI 解读命盘](/zh/docs/guide/guides/llm)。
## 需要更细的控制 [#需要更细的控制]
to\_text 覆盖的是通用场景。如果要自定义文本结构（比如只描述特定几个宫、
或者输出 JSON 而非文本），直接遍历星盘数据自己拼即可 ——
所有字段都是公开的，见[数据结构字典](/zh/docs/guide/data-model)。
# 让 AI 解读命盘 (/zh/docs/guide/guides/llm)
排盘交给库、解读交给模型：怎么把 x-iztro 接进 AI 应用，以及几条踩过的坑。
*适合：开发者 · 产品与决策者*
这是最重要的一条。大模型算不准干支与安星 —— 它会给出**看起来合理但错误**的结果，
而且错得毫无规律，你没法从输出上看出来。
排盘是确定性计算，交给库；模型只负责解读。
这条分工是把斗数接进 AI 应用的整个前提。
## 最小接法 [#最小接法]
把盘转成文本，前面加上你的分析要求，一起发给模型：
```python
from x_iztro import Astro
astro = Astro()
chart = astro.by_solar("2000-8-16", 2, "female")
system = "你是紫微斗数分析师。基于给定命盘作答，不要编造盘上没有的信息。"
user = f"""{chart.to_text()}
{chart.horoscope("2025-1-1", 0).to_text()}
请分析这个人 2025 年的事业运势。"""
```
生成的文本长什么样、格式怎么读，见[语义化文本](/zh/docs/guide/guides/to-text)。
## 做成工具调用 [#做成工具调用]
让模型自己决定什么时候排盘，比在应用里写死流程更灵活：
模型负责理解需求与解读，x-iztro 负责算准。一个最小的工具定义：
```python
{
"name": "cast_chart",
"description": "紫微斗数排盘。给定阳历生日、时辰索引与性别，返回完整命盘的结构化描述。",
"input_schema": {
"type": "object",
"properties": {
"solar_date": {"type": "string", "description": "阳历生日，格式 YYYY-M-D"},
"time_index": {"type": "integer", "minimum": 0, "maximum": 12,
"description": "时辰索引，0=早子时(00-01)，12=晚子时(23-24)"},
"gender": {"type": "string", "enum": ["male", "female"]},
},
"required": ["solar_date", "time_index", "gender"],
},
}
```
实现里调 `chart.to_text()` 返回文本即可。
运限单独做一个工具（多收一个目标日期），让模型按需要取。
用户说的「晚上 11 点」对应索引 `12` 而不是 `0`，模型不会自己知道。
把 0–12 的含义写进参数描述，或者干脆让工具收「出生时间 HH:MM」再由你换算。
## 用中文盘喂模型 [#用中文盘喂模型]
排盘结果本身与盘面语言无关，但 to\_text 生成的文本会跟着变。默认的中文盘就是最好的选择：
主流模型的中文命理术语能力都不差；而英文盘的星名走 iztro 的意译词表
（紫微 `emperor`、七杀 `marshal`），亮度退化成 `[+3]` 这类记号，四化写成 `A`/`B`/`C`/`D`，
这套写法与英文命理界的通行译法不同，模型未必认得。
确实需要英文输出时，做法是**用中文盘喂模型、让模型用英文作答**，
而不是换成英文盘。
## 判断逻辑用标识 [#判断逻辑用标识]
如果你的应用要基于盘的内容做分支（例如「命宫有化忌时走另一套话术」），
用[语言无关标识](/zh/docs/guide/guides/keys)判断，不要匹配文本 ——
否则换一种盘面语言，所有分支都会静默失效。
```python
soul = chart.palace("soulPalace")
if soul.has_mutagen("sihuaJi"):
prompt_style = "谨慎"
```
## 别把模型的解读当计算结果 [#别把模型的解读当计算结果]
模型可能在解读里顺手「补」一些盘上没有的信息 ——
多出一颗星、把大限区间说错、把宫名记混。
如果解读要落进产品（写库、发推送、做决策），
凡是可以从盘上直接取的事实，都从盘上取，不要从模型的自然语言里回抽。
模型输出只当文字用。
## 让 AI 读这份文档 [#让-ai-读这份文档]
本站另有专供模型抓取的纯文本端点（`llms.txt`、单页 Markdown），
见[给 AI 读的文档端点](/zh/docs/guide/guides/llms-txt)。
# 知识包 (/zh/docs/guide/guides/knowledge-pack)
解读文本与门派属性怎么与内核分开、内嵌默认包里有什么、怎么写覆盖包、三语言怎么读。
*适合：要在排盘结果之上给出文字解读的人*
排完盘拿到的是事实：命宫在午、武曲在财帛且化权、这张盘成了府相朝垣。
接下来要回答的「武曲是什么意思」「府相朝垣好在哪里」不是事实，是**观点**——
不同门派、不同书、不同老师给的答案不一样。
x-iztro 把这两件事分开：内核只做事实判定（排盘、运限、格局），
解读文本与星耀的门派属性放在**知识包**里。知识包是一份 JSON，
协议是「语言无关标识 → 文本与属性」。库里内嵌一份默认包，开箱即用；
不认同其中的说法，写一份覆盖包逐条改掉。包是 to\_text 家族的参数：传给
[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)，释义就按盘取材内联在事实旁——
每宫事实后跟该宫星耀释义，格局列表后跟格局释义，文末附四化释义。
## 内核与知识包的分工 [#内核与知识包的分工]
| | 内核 | 知识包 |
| ----- | ---------------------- | ---------------------------- |
| 内容 | 十二宫、星耀落宫、亮度、四化、运限、格局命中 | 星耀解读、格局解读、宫位与四化含义、术语、星耀的门派属性 |
| 性质 | 事实，可与 iztro 逐字段对照 | 观点，换一家说法就换一份 |
| 出错的样子 | 盘排错了 | 解读你不认同 |
| 怎么改 | 不能改（改了就不是这套算法） | 换包或写覆盖包 |
两边的接缝就是**语言无关标识**：星耀用 `ziweiMaj`、格局用 `zi_fu_tong_gong`、
宫位用 `soulPalace`、四化用 `sihuaLu`。内核输出的每个字段都带这些标识
（见[标识体系](/zh/docs/guide/guides/keys)），拿它去知识包里取文本即可，
不必匹配译名，也不受盘面语言影响。
## 内嵌的默认包里有什么 [#内嵌的默认包里有什么]
| 段 | 条目数 | 内容 |
| ---------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stars` | 162 | 主星 14、辅星 14、杂耀 38、神煞 46、流耀 50——全部 `StarKey` 都有条目。主辅杂神各带卡片属性（阴阳、五行、斗分、化气、职业、职务、别号、五行色、能量色）与特性正文；14 颗主星另有与其他主星的双星组合解读；流耀条目（`category: "flow"`）是指向对应本命辅星的对照性条目，机器可读对照表由 `flow_star_counterparts`（Go `FlowStarCounterparts`）提供 |
| `patterns` | 64 | 每条带古籍引文、成立条件的文字描述与解读正文 |
| `palaces` | 12 | 十二宫各自的含义 |
| `mutagens` | 4 | 禄权科忌各自的含义 |
| `concepts` | 49 | 术语与基础概念（同宫、本宫、身宫、地支六合、三方四正、飞星四化…） |
内容取自 [iztro-docs](https://github.com/SylarLong/iztro-docs) 的《学习》各页
（MIT License，作者 Sylar Long），锁定来源 commit（`source.commit`），文本经 x-iztro 整理改写为第三人称释义口吻（`source.adapted` 注明），
包的 `source` 段完整记录来源、commit、许可与作者。文本字段是 Markdown。
其他五种语言没有内嵌默认包：Rust 的 `KnowledgePack::builtin` 返回 `None`，
Python 与 Go 报 `invalid_argument`。要别的语言，自己写一份包，
或者把中文条目连同盘一起交给大模型，让它边译边解读。
默认包让 Go 侧内嵌的 wasm 增大了约 380 KB。Rust 与 Python 侧同样内嵌这份数据。
## 包长什么样 [#包长什么样]
权威格式规范（字段表、标识值域、合并算法、校验与版本兼容、覆盖包完整示例）见仓库的 [`knowledge/SCHEMA.md`](https://github.com/x-haose/x-iztro/blob/main/knowledge/SCHEMA.md)。
所有条目与字段都可选——缺什么就是没写：
```json
{
"schema": 1,
"id": "iztro-docs",
"version": "2026-08-19+ec2d58b",
"language": "zh-CN",
"extends": null,
"source": {
"name": "iztro-docs",
"url": "https://github.com/SylarLong/iztro-docs",
"commit": "ec2d58bb8b2a0d243d91212a1e3c87ab866858ee",
"license": "MIT",
"author": "Sylar Long",
"retrievedAt": "2026-08-19",
"adapted": "文本由 x-iztro 在 iztro-docs 原文基础上整理改写为第三人称释义口吻……"
},
"stars": {
"ziweiMaj": {
"name": "紫微",
"category": "major",
"group": null,
"attributes": {
"yinYang": "yin",
"fiveElements": "earth",
"stem": "ji",
"dipper": "中天星系",
"chemistry": "尊贵",
"career": "官禄主",
"duty": "众星枢纽，长五行，孕万物",
"aliases": ["帝王星", "老板星", "俸禄星"],
"elementColor": "黄色",
"energyColor": "紫光"
},
"intro": "紫微星号称 `帝王星`，并非指紫微坐命者能成帝王……",
"combinations": { "tianfuMaj": "紫微星和 `天府星` 都是帝星……" }
}
},
"patterns": {
"zi_fu_tong_gong": {
"name": "紫府同宫",
"quotes": ["紫府同宫终身福厚。"],
"conditions": "指紫微星和天府星同宫，这两颗星只会在寅宫和申宫同宫；其组合特质与紫微天府星曜组合一致。",
"intro": "“终身福厚”并非定数，但紫府同宫格的人一定无法接受平凡的人生……"
}
},
"palaces": { "soulPalace": { "name": "命宫", "intro": "命宫是决定星盘主人属性的宫位……" } },
"mutagens": { "sihuaLu": { "name": "化禄", "intro": "**五行**：土；**意象**：开心、忙碌、增加、包容、多\n\n化禄星简称 `禄`，是一种 `增加` 的力量……" } },
"concepts": { "tong-gong": { "title": "遇、加、逢、同宫、同度", "intro": "指星曜在同一个宫位里面……" } }
}
```
## 读一份包 [#读一份包]
```rust
use x_iztro::{KnowledgePack, Language, StarKey};
let pack = KnowledgePack::builtin(Language::ZhCN).expect("zh-CN 有默认包");
let ziwei = pack.star(StarKey::ZiweiMaj).unwrap();
println!("{:?} {:?}", ziwei.name, ziwei.attributes.aliases);
let head: String = pack.star_intro(StarKey::ZiweiMaj).unwrap().chars().take(12).collect();
println!("{head}");
```
```text
Some("紫微") Some(["帝王星", "老板星", "俸禄星"])
紫微星号称 `帝王星`，
```
```python
from x_iztro import KnowledgePack
from x_iztro.enums import MajorStar
pack = KnowledgePack.builtin()
ziwei = pack.star(MajorStar.ZIWEI)
print(ziwei.name, ziwei.attributes.aliases)
print(pack.star_intro(MajorStar.ZIWEI)[:12])
```
```text
紫微 ['帝王星', '老板星', '俸禄星']
紫微星号称 `帝王星`，
```
```go
pack, err := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
if err != nil {
log.Fatal(err)
}
ziwei := pack.Star(iztro.StarZiweiMaj)
fmt.Println(ziwei.Name, ziwei.Attributes.Aliases)
fmt.Println(string([]rune(pack.StarIntro(iztro.StarZiweiMaj))[:12]))
```
```text
紫微 [帝王星 老板星 俸禄星]
紫微星号称 `帝王星`，
```
查不到的键统一返回空：Rust / Python 是 `None`，Go 是 `nil`（`StarIntro` 为空串）。
## 和格局结果搭配 [#和格局结果搭配]
格局命中的 `key` 就是知识包 `patterns` 段的键，一一对上：
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
for hit in chart.patterns() {
let entry = pack.pattern(hit.key).unwrap();
let quote = entry.quotes.as_ref().and_then(|q| q.first());
println!("{} | {:?}", translate_pattern(hit.key, Language::ZhCN), quote);
}
```
```text
府相朝垣 | Some("府相朝垣命必荣")
```
```python
pack = KnowledgePack.builtin()
chart = Astro().by_solar("2000-8-16", 2, "female")
for hit in chart.patterns():
entry = pack.pattern(hit.key)
print(hit.name, "|", entry.quotes[0])
```
```text
府相朝垣 | 府相朝垣命必荣
```
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
hits, _ := chart.Patterns(nil)
for _, hit := range hits {
entry := pack.Pattern(hit.Key)
fmt.Println(hit.Name, "|", entry.Quotes[0])
}
```
```text
府相朝垣 | 府相朝垣命必荣
```
星耀同理：盘上每颗星的 `key` 直接拿去 `pack.star(key)`，宫位用 `palaceNameKey`，
四化用四化标识。
## 按盘取材 [#按盘取材]
整包 162 颗星、64 条格局，一张盘用不到这么多。`for_astrolabe` 从包里裁出只含这张盘的子包，
`for_horoscope` 在此之上再加运限层的材料：
| 段 | `for_astrolabe` | `for_horoscope` 另加 |
| ---------------------- | ------------------------------------------------------------ | ------------------ |
| `stars` | 十二宫上出现的星：主星、辅星、杂耀与四组十二神；14 主星的 `combinations` 只保留对方主星确在同宫的那些 | 各层流耀 |
| `patterns` | 按格局口径命中的格局 | 大限到流时各层视角命中的格局 |
| `mutagens` | 禄权科忌四条，与盘无关 | — |
| `palaces` / `concepts` | 空——宫位与术语与盘无关，按需从整包直接查 | — |
格局口径可选传：Rust 走 `for_astrolabe_with(&chart, &PatternConfig)` /
`for_horoscope_with(&chart, &h, &PatternConfig)`（不带 `_with` 的两个即默认口径），
Python 是 `config=` 关键字，Go 是第二个参数 `*PatternConfig`（`nil` 即默认）。
子包要和 `patterns` / `patterns_to_text` 配同一口径：口径不同，命中集合不同，释义就会缺项或多项。
Go 另有 `BuiltinKnowledge().ForAstrolabe(chart, nil)` 这条路，让内核直接读内嵌包，不必先取整包再送回。
返回的仍是标准知识包（元信息沿用本包），可以继续合并、序列化、按 key 查，
或者反过来作为 to\_text 的释义参数。2000-8-16 寅时 女这张盘从默认包取出的子包：
本命 108 星 / 1 格局 / 4 四化，序列化约 75 KB（整包约 219 KB）；
2025-1-1 的运限再加流耀与各层格局，158 星 / 16 格局。
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let sub = pack.for_astrolabe(&chart);
println!("{} {} {} {}", sub.stars.len(), sub.patterns.len(), sub.mutagens.len(), sub.palaces.len());
let h = chart.horoscope("2025-1-1", 0)?;
let sub = pack.for_horoscope(&chart, h.data());
println!("{} {}", sub.stars.len(), sub.patterns.len());
```
```python
pack = KnowledgePack.builtin()
sub = pack.for_astrolabe(chart)
print(len(sub.stars()), len(sub.patterns()), sub.mutagen("sihuaLu") is not None, sub.palace("soulPalace"))
sub = pack.for_horoscope(chart.horoscope("2025-1-1", 0))
print(len(sub.stars()), len(sub.patterns()))
```
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
sub, _ := pack.ForAstrolabe(chart, nil)
fmt.Println(len(sub.Stars), len(sub.Patterns), len(sub.Mutagens), len(sub.Palaces))
h, _ := chart.Horoscope("2025-1-1", 0)
sub, _ = pack.ForHoroscope(h, nil)
fmt.Println(len(sub.Stars), len(sub.Patterns))
```
三侧输出一致：`108 1 4 0` 与 `158 16`（Python 第一行的后两项是 `True None`）。
带释义的 to\_text 按同一套规则取材：子包里有的星与格局，文本里就有对应的释义条目
（十二神除外——子包收录它们，to\_text 不为它们写释义）。
## 写一份覆盖包 [#写一份覆盖包]
覆盖包是同样格式的 JSON，只写要改的条目与字段，`extends` 记被覆盖包的 `id`。
下面这份改掉紫微的解读与别号、换掉紫府同宫的解读，其余原样保留：
```json
{
"schema": 1,
"id": "my-school",
"version": "2026-08-19",
"language": "zh-CN",
"extends": "iztro-docs",
"stars": {
"ziweiMaj": {
"intro": "紫微在我这一派看来先看格局高低，再论性情。",
"attributes": { "aliases": ["帝座"] }
}
},
"patterns": {
"zi_fu_tong_gong": { "intro": "紫府同宫，我只把它当作起点高，不当作福厚。" }
}
}
```
合并出一份新包：
```rust
let base = KnowledgePack::builtin(Language::ZhCN).unwrap();
let overlay = KnowledgePack::from_json(&std::fs::read_to_string("my-school.json")?)?;
let pack = base.merged(&[&overlay]);
let ziwei = pack.star(StarKey::ZiweiMaj).unwrap();
println!("{:?} {:?} {:?}", ziwei.name, ziwei.attributes.aliases, ziwei.attributes.chemistry);
println!("{:?}", pack.pattern_intro(PatternKey::ZiFuTongGong));
```
```python
base = KnowledgePack.builtin()
overlay = KnowledgePack.from_json(open("my-school.json", encoding="utf-8").read())
pack = base.merged(overlay)
ziwei = pack.star(MajorStar.ZIWEI)
print(ziwei.name, ziwei.attributes.aliases, ziwei.attributes.chemistry)
print(pack.pattern_intro(PatternKey.ZI_FU_TONG_GONG))
```
```go
base, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
data, _ := os.ReadFile("my-school.json")
overlay, err := iztro.ParseKnowledgePack(data)
if err != nil {
log.Fatal(err)
}
pack, err := base.Merged(overlay)
if err != nil {
log.Fatal(err)
}
ziwei := pack.Star(iztro.StarZiweiMaj)
fmt.Println(ziwei.Name, ziwei.Attributes.Aliases, ziwei.Attributes.Chemistry)
fmt.Println(pack.PatternIntro(iztro.PatternZiFuTongGong))
```
三侧输出一致：紫微的 `name`（紫微）与 `chemistry`（尊贵）保留，`intro` 与 `aliases` 换成覆盖包的；
紫府同宫的 `intro` 换掉，`quotes` 与 `conditions` 保留。
合并只在 Rust 内核实现了一处，Python 与 Go 的 `merged` / `Merged` 都是调进内核算的，
所以三侧的合并结果逐字节一致，不会各写各的规则。
## 合并规则 [#合并规则]
以底包为底，逐段（`stars` / `patterns` / `palaces` / `mutagens` / `concepts`）按键合并：
* 覆盖包里出现的条目，其**非 null 字段**覆盖底包同键条目的对应字段，未出现的字段保留
* `attributes` 与 `combinations` 同样按字段 / 子键合并
* 数组字段（`aliases`、`quotes`）整体替换，不做逐项合并
* 底包没有的键直接新增
* 把某字段显式写成 `null` **不会删除**底包内容（缺省与 null 同义）；要删除请整包替换
* 合并后的 `id` / `version` / `language` / `source` 取覆盖包的（若非空），`extends` 保留底包的
`schema` 高于本库支持的版本直接报错，不做降级解析。
## 为什么星耀的阴阳五行放在这里 [#为什么星耀的阴阳五行放在这里]
星耀的五行看起来像事实，其实也是观点。iztro 自带的 `starsInfo` 表与
iztro-docs 星耀卡片本身就对不上：
| 星 | iztro 的 `starsInfo` | iztro-docs 卡片 |
| -- | ------------------- | ------------- |
| 贪狼 | 水 | 甲木（气为水） |
| 巨门 | 阴土 | 癸水、己土（藏金、木） |
同一位作者的两处数据都不一致，说明这类属性是门派说法而非唯一答案。
所以 x-iztro 的核心 `StarInfo` 保持与 iztro 逐值一致（迁移过来的代码不会变行为），
卡片上那套属性放进知识包，想换就换。
## 之后 [#之后]
同一套协议之上还能做覆盖包的加载与分发——这属于应用层的事，不在库里。
## API 参考 [#api-参考]
* [Rust — knowledge](/zh/docs/rust/knowledge)
* [Python — knowledge](/zh/docs/python/knowledge)
* [Go — KnowledgePack](/zh/docs/go/knowledge)
## 来源与署名 [#来源与署名]
默认包的全部文本取自 [iztro-docs](https://github.com/SylarLong/iztro-docs) 的《学习》各页，
MIT License，作者 Sylar Long。知识包协议、默认包文本的整理改写与三语言 API 是 x-iztro 的实现。
# 反推 (/zh/docs/guide/guides/reverse)
由八字四柱或星盘特征反查候选生辰：两个入口各自的语义、四柱口径与 Config 的关系、多解与 60 年周期、截断语义。
*适合：只记得盘、不记得生日的人；要把八字转成紫微盘的人*
正排是「生辰 → 盘」。但常有反着来的需求：
* 手里有一张旧盘或一组八字，生日却记不清了；
* 对方只报八字不报公历生日，而排紫微盘需要公历日期与时辰；
* 只记得「命宫在午、木三局、紫微坐命」这类盘面特征，想找回是哪天生的。
x-iztro 给了两个反推入口，都返回**候选生辰**（公历日期 + 时辰索引），
拿去正排即可复现目标：
| 入口 | 输入 | 语义 |
| --------------------- | -------------------- | ------------------ |
| `solar_dates_by_bazi` | 八字四柱干支 | 找出范围内四柱恰好如此的全部生辰 |
| `reverse_chart` | 命宫身宫地支、五行局、星耀落宫、生年四化 | 找出范围内排出的盘满足全部条件的生辰 |
两者的实现都是「剪枝枚举 + 正排终验」：先用便宜的查表把明显不可能的日子整批剪掉，
幸存者再用与正排完全相同的代码验证。因此**反推结果与正向排盘零分歧**——
每个候选正排出来必然真的满足条件，目标生辰也必然在候选里。
## 由八字反查生辰 [#由八字反查生辰]
```rust
use x_iztro::*;
// 庚辰 甲申 丙午 庚寅
let cands = solar_dates_by_bazi(
(HeavenlyStem::Geng, EarthlyBranch::Chen),
(HeavenlyStem::Jia, EarthlyBranch::Shen),
(HeavenlyStem::Bing, EarthlyBranch::Wu),
(HeavenlyStem::Geng, EarthlyBranch::Yin),
(1900, 2100),
&Config::default(),
)?;
for c in &cands {
println!("{} {}", c.solar_date, c.time_index);
}
```
```python
from x_iztro import solar_dates_by_bazi
from x_iztro.enums import EarthlyBranch as B, HeavenlyStem as S
# 庚辰 甲申 丙午 庚寅
cands = solar_dates_by_bazi(
(S.GENG, B.CHEN), (S.JIA, B.SHEN), (S.BING, B.WU), (S.GENG, B.YIN),
year_range=(1900, 2100),
)
for c in cands:
print(c.solar_date, c.time_index)
```
```go
cands, err := iztro.SolarDatesByBazi(
iztro.Pillar{iztro.StemGeng, iztro.BranchChen}, // 庚辰
iztro.Pillar{iztro.StemJia, iztro.BranchShen}, // 甲申
iztro.Pillar{iztro.StemBing, iztro.BranchWu}, // 丙午
iztro.Pillar{iztro.StemGeng, iztro.BranchYin}, // 庚寅
1900, 2100, nil)
if err != nil {
log.Fatal(err)
}
for _, c := range cands {
fmt.Println(c.SolarDate, c.TimeIndex)
}
```
**输出**（三种语言相同）
```text
1940-8-31 2
2000-8-16 2
2060-8-1 2
```
### 多解与 60 年周期 [#多解与-60-年周期]
干支纪年 60 年一轮回，同一组四柱在相隔约 60 年的位置重复出现，
因此一组四柱在大范围内**注定多解**——上例 1900–2100 里出现三次。
年份范围收窄到一个甲子（60 年）内通常只剩一个解；
范围给宽时，靠年龄常识从候选里挑出正确的那个。
### 子时的双候选 [#子时的双候选]
子时跨午夜，拆成早子时（索引 0，当日 0:00–1:00）与晚子时（索引 12，当日 23:00–24:00），
而晚子时的日柱按 `day_divide` 的默认口径归**次日**。
所以时柱为子的一组四柱可能给出相邻两天的两个候选：某日的早子时、其前一日的晚子时——
这不是误差，两个候选正排出来的四柱确实完全相同，八字本身分不出它们。
## 四柱按哪套口径解释——随 Config [#四柱按哪套口径解释随-config]
四柱不是绝对的：年柱几时换（春节还是立春）、月柱几时换（初一还是节气）、
晚子时的日柱归谁，不同流派口径不同。这些口径都在
[`Config`](/zh/docs/guide/guides/config) 上：`year_divide` 管年柱、
`horoscope_divide` 管月柱、`day_divide` 管晚子归属。
`solar_dates_by_bazi` 按**传入的 config** 解释四柱，
与正排输出的 `raw_dates.chinese_date` 是同一套语义。
同一个生辰，两种口径下的四柱可能不同——以 2001-2-1 卯时为例，
它落在春节（1 月 24 日）之后、立春（2 月 4 日）之前：
| 口径 | 四柱 |
| ------------------ | ----------- |
| 默认（春节换年、初一换月） | 辛巳 庚寅 乙未 己卯 |
| `Exact`（立春换年、节气换月） | 庚辰 己丑 乙未 己卯 |
所以拿到一组八字，先弄清它是按哪套口径排的，再传对应的 config。
用哪套 config 排的盘，就用哪套 config 反查，往返必然闭环：
```rust
let cfg = Config {
year_divide: YearDivide::Exact,
horoscope_divide: HoroscopeDivide::Exact,
..Config::default()
};
let chart = by_solar("2001-2-1", 3, Gender::Female, true, Language::ZhCN, cfg.clone())?;
let p = chart.raw_dates.chinese_date;
let cands = solar_dates_by_bazi(p.yearly, p.monthly, p.daily, p.hourly, (1980, 2020), &cfg)?;
assert!(cands.iter().any(|c| c.solar_date == "2001-2-1" && c.time_index == 3));
```
## 由星盘特征反查生辰 [#由星盘特征反查生辰]
只记得盘面、给不出完整八字时用 `reverse_chart`。条件全部可选，
但至少要给一个；给了的条件须**同时满足**：
| 条件 | 说明 |
| ----------------------------- | ------------------------------------------------ |
| `soul_branch` / `body_branch` | 命宫、身宫地支 |
| `five_elements_class` | 五行局 |
| `stars` | 星耀落宫（星 + 地支），可给多条 |
| `mutagens` | 生年四化 \[禄, 权, 科, 忌] 各自是哪颗星，可只给其中几个 |
| `year_range` | 公历年闭区间（含两端），默认 1900–2100 |
| `fix_leap` | 闰月修正，与排盘入参同义；缺省取 `true`（Go 侧为 `*bool`，`nil` 即缺省） |
| `limit` | 候选数上限，0 取默认值 512 |
```rust
use x_iztro::*;
let r = reverse_chart(
&ReverseCriteria {
soul_branch: Some(EarthlyBranch::Wu),
five_elements_class: Some(FiveElementsClass::Wood3rd),
stars: vec![StarPosition { star: StarKey::ZiweiMaj, branch: EarthlyBranch::Wu }],
mutagens: [Some(StarKey::TaiyangMaj), None, None, None], // 太阳化禄
year_range: (1998, 2002),
..Default::default()
},
&Config::default(),
)?;
println!("{} 个候选, truncated = {}", r.candidates.len(), r.truncated);
```
```python
from x_iztro import ReverseCriteria, StarPosition, reverse_chart
from x_iztro.enums import EarthlyBranch, FiveElementsClass, MajorStar
r = reverse_chart(ReverseCriteria(
soul_branch=EarthlyBranch.WU,
five_elements_class=FiveElementsClass.WOOD_3,
stars=[StarPosition(star=MajorStar.ZIWEI, branch=EarthlyBranch.WU)],
mutagens=(MajorStar.TAIYANG, None, None, None), # 太阳化禄
year_range=(1998, 2002),
))
print(len(r.candidates), "个候选, truncated =", r.truncated)
```
```go
r, err := iztro.ReverseChart(&iztro.ReverseCriteria{
SoulBranch: iztro.BranchWu,
FiveElementsClass: iztro.ClassWood3rd,
Stars: []iztro.StarPosition{{Star: iztro.StarZiweiMaj, Branch: iztro.BranchWu}},
Mutagens: [4]string{iztro.StarTaiyangMaj, "", "", ""}, // 太阳化禄
YearRange: [2]int{1998, 2002},
}, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(len(r.Candidates), "个候选, truncated =", r.Truncated)
```
**输出**
```text
39 个候选, truncated = false
```
39 个候选全部落在庚辰年（2000-2-11 至 2001-1-11），其中就有真实生辰 2000-8-16 时辰 2。
每个候选拿去正排都满足全部条件——命宫都在午、都是木三局、紫微都坐午宫、太阳都化禄。
`reverse_chart` 的判定同样贯穿 config：四化表、算法派别、各分界口径都按传入的 config 算，
候选用同一 config 排盘必满足条件。
星盘布局（星耀落宫、亮度、四化）与性别无关——性别只影响大限的行进方向。
反推的目标是生辰，因此条件里没有性别；反查出生辰后自行配上性别正排。
条件只能是**本命盘**特征：运限流曜（运魁流昌之类）不出现在本命盘上，传入直接报错。
## 性能与截断 [#性能与截断]
代价主要取决于条件的「筛选力」：命宫地支、五行局、主星落宫、生年四化
都能整年整月地剪掉搜索空间，**条件越具体越快，年份范围越窄越快**。
量级参考（Apple Silicon，release 构建，进程内首次调用）：上面 5 年范围的特征反查约 30 毫秒
（含一次性表初始化，同进程再查约 1–2 毫秒）；同样条件放宽到 1900–2100，
约 0.4 秒后即达到默认候选上限 512 而截断（调高上限扫完全部 843 个解约 0.7 秒）；
八字反查 200 年约 0.1 秒。
宽条件的解非常多（只给一个命宫地支，全范围有上万个解）。
`limit`（默认 512）达到即停止搜索，结果的 `truncated` 置 `true`，
**更晚的解未被搜索**——这是截断，不是抽样。看到 `truncated = true` 时，
正确的做法是收窄 `year_range` 或补条件后重查，而不是调大 `limit` 硬扫。
## 出错的情况 [#出错的情况]
以下情形返回 `invalid_argument` 错误（Rust 为 `IztroError::InvalidArgument`）：
* 四柱干支阴阳不配：如「甲丑」——甲是阳干、丑是阴支，六十甲子里不存在这一柱；
* 反推条件为空，或条件里含运限流曜；
* 年份范围颠倒，或超出支持范围（公历 1583–9999）。
错误分类与各语言的错误类型见[错误处理](/zh/docs/guide/guides/errors)。
## API 参考 [#api-参考]
* Rust：[反推](/zh/docs/rust/reverse)
* Python：[反推](/zh/docs/python/reverse)
* Go：[反推](/zh/docs/go/reverse)
# Config 详解 (/zh/docs/guide/guides/config)
六个开关分别改变什么、自定义四化表与亮度表怎么传、什么时候会看出差别。
*适合：开发者 · 命理爱好者（前半页的流派差异不需要会写代码）*
排盘中真正有分歧的地方都收在 `Config` 里：六个开关，外加两张可整表替换的数据表。
默认值与 JS iztro 完全一致，所以**不传配置就能得到与 iztro 相同的盘**。
| 开关 | 取值 | 默认 | 管什么 |
| ------------------ | ---------------------------- | --------- | -------------- |
| `year_divide` | `normal` / `exact` | `normal` | 排盘年干支按哪天换年 |
| `horoscope_divide` | `normal` / `exact` | `normal` | 运限干支与月柱按哪天分界 |
| `age_divide` | `normal` / `birthday` | `normal` | 虚岁什么时候加一 |
| `day_divide` | `forward` / `current` | `forward` | 晚子时算今天还是明天 |
| `algorithm` | `default` / `zhongzhou` | `default` | 算法派别 |
| `astro_type` | `heaven` / `earth` / `human` | `heaven` | 排盘视角（天盘/地盘/人盘） |
另有两张覆盖表：`mutagens`（自定义四化表）与 `brightness`（自定义亮度表），
见[自定义四化表与亮度表](#自定义四化表与亮度表)。
## 怎么传 [#怎么传]
```rust
use x_iztro::data::types::*;
let config = Config {
algorithm: Algorithm::Zhongzhou,
year_divide: YearDivide::Exact,
..Config::default()
};
by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, config)?;
```
```python
from x_iztro import ChartConfig
from x_iztro.enums import Algorithm, YearDivide
config = ChartConfig(
algorithm=Algorithm.ZHONGZHOU,
year_divide=YearDivide.EXACT,
)
astro.by_solar("2000-8-16", 2, "female", config=config)
```
```go
cfg := &iztro.Config{
Algorithm: "zhongzhou",
YearDivide: "exact",
}
iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, cfg)
```
Python 与 Go 都只需填要改的键，其余取默认；Rust 用 `..Config::default()` 达到同样效果。
***
## 年分界点 `year_divide` [#年分界点-year_divide]
决定**排盘用的年干支**在哪一天换年。
| 取值 | 换年时点 |
| ------------ | ------ |
| `normal`（默认） | 农历正月初一 |
| `exact` | 立春 |
年干支是一连串东西的源头：本命四化、命主与身主、十二宫宫干。
所以这个开关一旦改变，整张盘可能大幅不同。
**什么时候会看出差别**：出生在农历正月初一与立春之间的人。
这两个日期通常相差几天到半个月，落在这个窗口里的生日，两种配置排出的年干支相差一位。
八字体系一律以立春换年，所以要与八字盘对齐时选 `exact`。
紫微斗数的通行做法是以正月初一换年，`normal` 也是 iztro 的默认。
拿不准就别动 —— 改了就不再与 iztro 的默认输出一致。
x-iztro 复刻了 iztro 内部的一处细节：依赖年支的东西并非全走同一个开关。
分工是固定的三条：
1. **跟 `year_divide` 的年干支**：生年四化、命主与身主、十二宫宫干、
禄存、擎羊、陀罗、天魁、天钺、天马、红鸾、天喜、长生十二神、博士十二神
2. **跟 `horoscope_divide` 的年干支**：其余全部年系杂耀，
以及本命盘上的岁前十二神与将前十二神
3. **跟 `horoscope_divide` 的月分界**：本命四柱里的**月柱**
两个开关可以分别设，所以「主星按一个年支、部分杂耀按另一个年支」是可能出现的。
这看起来不对称，但它就是 iztro 的实际行为，为保证零差异必须原样保留。
## 运限分界点 `horoscope_divide` [#运限分界点-horoscope_divide]
决定**运限干支**、**本命月柱**与**干支纪月**在哪一天分界。
| 取值 | 年分界 | 月分界 |
| ------------ | ---- | ---------- |
| `normal`（默认） | 正月初一 | 初一，以五虎遁推月干 |
| `exact` | 立春 | 节气 |
**什么时候会看出差别**：查询日期落在年初（正月初一到立春之间）或每个节气交接的前后，
流年与流月的干支会差一位，进而改变运限四化。
这个开关还会改**本命盘的月柱**——不只是运限。
例如 2000-8-5 寅时：`normal` 下四柱是 `庚辰 甲申 乙未 戊寅`，
`exact` 下是 `庚辰 癸未 乙未 戊寅`，月柱由甲申变癸未。
## 虚岁分界点 `age_divide` [#虚岁分界点-age_divide]
决定**虚岁**什么时候加一，直接影响小限落在哪个宫。
| 取值 | 加岁时点 |
| ------------ | ---------- |
| `normal`（默认） | 跨农历年即加一岁 |
| `birthday` | 过了农历生日才加一岁 |
**什么时候会看出差别**：查询日期落在农历新年与本人农历生日之间。
这段时间两种配置的虚岁相差一岁，小限也就落在相邻的两个宫。
## 晚子时归属 `day_divide` [#晚子时归属-day_divide]
决定 23:00–24:00 出生（时辰索引 `12`）的人，日柱按哪一天算。
| 取值 | 行为 |
| ------------- | ------------------- |
| `forward`（默认） | 晚子时归**次日**，按次日的日柱排盘 |
| `current` | 晚子时归**当天**，按当日早子时排盘 |
**什么时候会看出差别**：只影响时辰索引为 `12` 的盘，其余时辰完全无差异。
`forward` 会把日柱与**起紫微用的农历日**一起推到次日，
但星盘上的农历日期展示串仍显示**出生当日**。
例如 2000-8-16 晚子时：农历日期照旧显示「二〇〇〇年七月十七」，
四柱却是 `庚辰 甲申 丁未 庚子` —— 日柱丁未已是 8 月 17 日的。
读结果时别拿农历展示串去反推日柱。
无论选哪种，时辰索引字段都保留原始传入值 `12`，
不会因为归到次日就变成 `0` —— 这样调用方始终能知道出生的真实时辰。
## 算法派别 `algorithm` [#算法派别-algorithm]
| 取值 | 说明 |
| ------------- | ----------------------- |
| `default`（默认） | 通行的安星规则，与 JS iztro 默认一致 |
| `zhongzhou` | 中州派 |
中州派与默认派的差别集中在四处，**四化表不在其中**：
| 改动 | `default` | `zhongzhou` |
| ----- | ------------------------ | -------------------------------------------------- |
| 命主怎么查 | 按**命宫地支** | 按**生年地支**（因此换命宫重排时命主不再变） |
| 岁前十二神 | 大耗 `dahao` | 岁破 `suipo` |
| 杂耀 | 截路 `jielu`、空亡 `kongwang` | 截空 `jiekong`、劫杀 `jieshaAdj`、大耗 `dahao`、龙德 `longde` |
| 天伤天使 | 天伤在仆役、天使在疾厄 | 阴阳男女互换，两星位置对调 |
庚干化科在两派下都是太阴 —— 要换四化取法请用下面的自定义四化表，
不要指望 `algorithm`。
```python
astro.by_solar("1990-11-5", 4, "male", config=ChartConfig(algorithm=Algorithm.ZHONGZHOU))
```
## 排盘视角 `astro_type` [#排盘视角-astro_type]
中州派把同一组出生数据看作三张盘，差别只在**用哪一宫的干支起五行局**：
| 视角 | 起五行局的宫 | 新盘的命宫 |
| ----------- | ------ | ----------- |
| `heaven` 天盘 | 命宫 | 命宫（即常规排盘结果） |
| `earth` 地盘 | 身宫 | 身宫 |
| `human` 人盘 | 福德宫 | 福德宫 |
五行局一变，紫微天府的落点、十二宫名、身宫地支、长生十二神、大限小限全部跟着变；
辅星、杂耀（天伤天使天才随命宫走，会重新落位）、博士十二神、
岁前将前十二神沿用天盘。
```python
earth = astro.by_solar("2000-8-16", 2, "female",
config=ChartConfig(astro_type=AstroType.EARTH))
```
```go
earth, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN,
&iztro.Config{AstroType: iztro.AstroEarth})
```
```rust
let earth = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN,
Config::default().with_astro_type(AstroType::Earth))?;
```
JS iztro 把 `astroType` 放在 `withOptions` 的选项对象上，因为它的 `config()`
是全局单例、装不下按盘变化的值。x-iztro 的配置本来就随盘传入，
所以直接收进 `Config`，两个排盘入口都能用。
### 从任意干支起盘 [#从任意干支起盘]
天盘、地盘、人盘之外，也可以指定任意干支为命宫重排：
```python
body = chart.palace(PalaceName.BODY)
earth = chart.rearranged(body.heavenly_stem_key, body.earthly_branch_key)
```
```go
earth, _ := chart.Rearranged(body.HeavenlyStemKey, body.EarthlyBranchKey)
```
```rust
let earth = chart.rearranged(body.heavenly_stem, body.earthly_branch)?;
```
以身宫干支重排，结果与 `astro_type = earth` 一致。
## 自定义四化表与亮度表 [#自定义四化表与亮度表]
四化与亮度是流派分歧最集中的两处。`Config` 允许**按标识整表替换**：
给出某个天干的四化就只改那个天干，未给出的天干仍用默认表；亮度同理。
### 四化表 [#四化表]
一个天干配四颗星，顺序固定为**禄、权、科、忌**，必须给满四项。
```rust
let config = Config::default().with_mutagens(
HeavenlyStem::Geng,
[StarKey::TaiyangMaj, StarKey::WuquMaj, StarKey::TiantongMaj, StarKey::TianfuMaj],
);
by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, config)?;
```
```python
cfg = ChartConfig(mutagens={
"gengHeavenly": ["taiyangMaj", "wuquMaj", "tiantongMaj", "tianfuMaj"],
})
chart = astro.by_solar("2000-8-16", 2, "female", config=cfg)
```
```go
cfg := &iztro.Config{Mutagens: map[string][]string{
"gengHeavenly": {"taiyangMaj", "wuquMaj", "tiantongMaj", "tianfuMaj"},
}}
```
把庚干换成「天同化科、天府化忌」之后，这张庚年盘的四化变成：
```text
财帛 武曲 权
子女 太阳 禄
官禄 天府 忌
疾厄 天同 科
```
自定义四化表同时改变**全部飞星判断** —— 宫干化出哪四颗星走的是同一张表。
### 亮度表 [#亮度表]
一颗星配十二个亮度，按盘上位置排列（第一项是寅宫），必须给满十二项；
该位置无亮度时用空值（Python / Go 传空串）。
```python
cfg = ChartConfig(brightness={
"ziweiMaj": ["miao", "wang", "de", "li", "ping", "bu",
"xian", "miao", "wang", "de", "li", "ping"],
})
```
1. **只收标识，不收译名**：`"ziweiMaj"` 可以，`"紫微"` 不行。
2. **长度严格校验**：四化表必须 4 项、亮度表必须 12 项，多一项少一项都会报错。
3. **不回显在输出里**：覆盖表是排盘的输入，不属于排盘结果，
星盘上回显的 `config` 只有六个开关，两张表读回来是空的。
自己要留档就自己存那份配置。
## 配置会跟着星盘走 [#配置会跟着星盘走]
排盘用的配置存在星盘上，运限从那里取，
所以**运限一定与排盘用同一套配置**，不会出现本命盘用中州派、运限用默认派的错配。
```python
chart = astro.by_solar("2000-8-16", 2, "female", config=ChartConfig(age_divide="birthday"))
h = chart.horoscope("2024-10-1", 0) # 自动沿用 age_divide=birthday
```
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN,
&iztro.Config{AgeDivide: "birthday"})
h, _ := chart.Horoscope("2024-10-1", 0) // 同上
```
## 测试覆盖 [#测试覆盖]
四个分界开关的非默认取值有 9,696 例专门的金标测试（含排盘层与运限层的组合），
中州派盘型另有 12,488 例，覆盖立春窗口逐日、晚子时、生日前后等所有会产生分歧的边界。
自定义四化表与亮度表另有一组专门的测试。见[准确性保证](/zh/docs/guide/about/accuracy)。
# 语言无关的 key 契约 (/zh/docs/guide/guides/keys)
为什么星名不能拿来做判断，key 字段是什么，三种编程语言各自怎么用。
*适合：开发者*
## 问题 [#问题]
排盘结果的文本会跟着盘面语言变。同一颗星，中文盘上是「紫微」，英文盘上是 `emperor`，
韩文盘上是 `자미`。如果判断逻辑写成：
```python
# 反面例子
if any(s.name == "紫微" for s in soul.major_stars):
...
```
那么这段代码只在 `language="zh-CN"` 时正确。换成任何其他盘面语言就静默失效 ——
不会报错，只是永远返回 `False`。这类 bug 很难发现。
## 解法 [#解法]
每个会被翻译的字段，x-iztro 都额外提供一个**语言无关标识**（key）。
key 的取值是 iztro 的 i18n 键名，与盘面语言无关，永远不变。
```json
{
"name": "紫微",
"key": "ziweiMaj",
"brightness": "庙",
"brightnessKey": "miao",
"mutagen": "禄",
"mutagenKey": "sihuaLu"
}
```
`name` 给人看，`key` 给代码用。
## 有哪些 key 字段 [#有哪些-key-字段]
| 数据 | 翻译字段 | 标识字段 | 取值示例 |
| ------- | --------------------- | ---------------------- | ------------------- |
| 星耀 | `name` | `key` | `ziweiMaj` |
| 亮度 | `brightness` | `brightnessKey` | `miao` |
| 四化 | `mutagen` | `mutagenKey` | `sihuaLu` |
| 宫位名 | `name` | `nameKey` | `soulPalace` |
| 天干 | `heavenly_stem` | `heavenlyStemKey` | `jiaHeavenly` |
| 地支 | `earthly_branch` | `earthlyBranchKey` | `ziEarthly` |
| 五行局 | `five_elements_class` | `fiveElementsClassKey` | `water2nd` |
| 命主 / 身主 | `soul` / `body` | `soulKey` / `bodyKey` | `ziweiMaj` |
| 性别 | `gender` | `genderKey` | `male` |
| 长生十二神 | `changsheng12` | `changsheng12Key` | `changsheng` |
| 博士十二神 | `boshi12` | `boshi12Key` | `boshi` |
| 将前十二神 | `jiangqian12` | `jiangqian12Key` | `jiangxing` |
| 岁前十二神 | `suiqian12` | `suiqian12Key` | `suijian` |
| 宫干四化星 | — | `mutagenStarKeys` | `["taiyangMaj", …]` |
## 三种编程语言的用法 [#三种编程语言的用法]
### Python：枚举 [#python枚举]
`x_iztro.enums` 里所有枚举都是 `StrEnum`，**成员的值就是 key**。
```python
from x_iztro.enums import MajorStar, Mutagen, PalaceName, Brightness
MajorStar.ZIWEI # "ziweiMaj"
Mutagen.LU # "sihuaLu"
PalaceName.SOUL # "soulPalace"
Brightness.MIAO # "miao"
```
判断方法接受枚举：
```python
soul = chart.palace(PalaceName.SOUL)
soul.has([MajorStar.ZIWEI])
soul.has_mutagen(Mutagen.LU)
```
因为是 `StrEnum`，它同时也是字符串，可以直接和 key 字段比较：
```python
star.key == MajorStar.ZIWEI # True
```
### Go：常量 [#go常量]
`keys.go` 里的常量值就是 key：
```go
iztro.PalaceSoul // "soulPalace"
iztro.StarZiweiMaj // "ziweiMaj"
iztro.MutagenLu // "sihuaLu"
iztro.BrightnessMiao // "miao"
soul := chart.Palace(iztro.PalaceSoul)
soul.Has(iztro.StarZiweiMaj)
star.WithMutagen(iztro.MutagenQuan)
star.WithBrightness(iztro.BrightnessMiao)
```
### Rust：枚举本身 [#rust枚举本身]
Rust 侧不需要 key 字段 —— 结构体里存的本来就是枚举，翻译是显示时才做的事。
```rust
if soul.has(&[StarKey::ZiweiMaj]) { }
```
需要 key 字符串时（例如自己做序列化）调 `as_key()`：
```rust
Palace::Soul.as_key(); // "soulPalace"
Mutagen::Lu.as_key(); // "sihuaLu"
Brightness::Miao.as_key(); // "miao"
```
## 验证方式 [#验证方式]
同一个生日分别用六种盘面语言排盘，所有 key 字段必须逐一相等 ——
这条由绑定契约测试（`golden_contract`）与 Go / Python 的端到端金标测试守着。
所以下面这段代码在任何盘面语言下结果都相同：
```python
for lang in ["zh-CN", "zh-TW", "en-US", "ja-JP", "ko-KR", "vi-VN"]:
chart = astro.by_solar("2000-8-16", 2, "female", language=lang)
soul = chart.palace(PalaceName.SOUL)
assert soul.has_mutagen(Mutagen.LU) == expected
```
## 什么时候可以用文本 [#什么时候可以用文本]
展示。只有展示。任何进入 `if` 的比较都应该用 key。
# 多语言输出 (/zh/docs/guide/guides/i18n)
六种盘面语言、哪些字段会被翻译、换盘面语言对结果的影响，以及标识与译名的双向换算。
*适合：开发者*
## 支持的盘面语言 [#支持的盘面语言]
「盘面语言」指排盘结果里那些人读的文本用哪种语言写，与你用哪种**编程语言**调用无关。
| 取值 | 语言 | Rust 枚举 |
| ------- | -------- | ---------------- |
| `zh-CN` | 简体中文（默认） | `Language::ZhCN` |
| `zh-TW` | 繁体中文 | `Language::ZhTW` |
| `en-US` | 英文 | `Language::EnUS` |
| `ja-JP` | 日文 | `Language::JaJP` |
| `ko-KR` | 韩文 | `Language::KoKR` |
| `vi-VN` | 越南文 | `Language::ViVN` |
```python
chart = astro.by_solar("2000-8-16", 2, "female", language="en-US")
```
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageJaJP, nil)
```
```rust
by_solar("2000-8-16", 2, Gender::Female, true, Language::KoKR, Config::default())?;
```
## 哪些内容会翻译 [#哪些内容会翻译]
会翻译的是所有面向人阅读的文本：
* 星耀名、宫位名、四化名、亮度名
* 天干、地支、五行局
* 时辰名与时间段、星座、生肖、性别
* 农历日期的中文表示、干支纪日展示串
* 运限层级名（大限 / 流年 / …）
**不翻译**的是所有标识字段与数值字段：星耀的 `key`、宫位的 `nameKey`、
宫位索引、大限区间、虚岁等。见 [key 契约](/zh/docs/guide/guides/keys)。
1. **英文与韩文没有亮度译名**，输出的是记号：`[+3]`（庙）、`[+2]`（旺）、
`[+1]`（得）、`[0]`（利）、`[-1]`（平）、`[-2]`（不）、`[-3]`（陷）。
繁体、日文、越南文有真译名。
2. **英文四化输出 `A`/`B`/`C`/`D`**，依次是禄、权、科、忌。
3. **非中文译名沿用 iztro 的词表，不保证是该语言命理界的通行译法**，
个别条目并非真词 —— 例如英文的 `considery`、`disastery`。
译名只做展示，判断一律用标识字段。
## 换盘面语言不改变排盘结果 [#换盘面语言不改变排盘结果]
盘面语言只影响翻译层。同一个生日在六种盘面语言下：
* 十二宫的位置与宫名顺序完全相同
* 每个宫里的星耀完全相同
* 四化、亮度、大限小限、运限干支完全相同
变的只是这些东西被写成什么字。所以下面两张盘除文本外逐字段相等：
```python
zh = astro.by_solar("2000-8-16", 2, "female", language="zh-CN")
en = astro.by_solar("2000-8-16", 2, "female", language="en-US")
assert zh.palace(PalaceName.SOUL).index == en.palace(PalaceName.SOUL).index
assert zh.soul_key == en.soul_key
```
六种盘面语言的一致性由变体金标测试覆盖，零容忍差异。
## 标识与译名的换算 [#标识与译名的换算]
手上只有标识（或只有某种语言的译名）时，用双向查找函数换算，不必重新排盘：
```rust
translate_key("ziweiMaj", Language::EnUS); // Some("emperor")
key_of("emperor"); // Some("ziweiMaj")
key_of("자미"); // Some("ziweiMaj")
```
类别已知时用强类型版本更直接，也免去 `Option`：
```rust
use x_iztro::{translate_palace, translate_star};
translate_star(StarKey::ZiweiMaj, Language::ViVN); // Tử Vi
translate_palace(Palace::Soul, Language::KoKR); // 명궁
```
```python
i18n.translate("ziweiMaj", "en-US") # emperor
i18n.key_of("emperor") # ziweiMaj
i18n.key_of("자미") # ziweiMaj
```
```go
name, _ := iztro.Translate(iztro.StarZiweiMaj, iztro.LanguageEnUS) // emperor
key, _ := iztro.KeyOf("emperor") // ziweiMaj
key, _ = iztro.KeyOf("자미") // ziweiMaj
```
Go 侧两个函数都返回 `(string, error)`：标识未知或反查不到时返回空串与
`*iztro.Error`（分类 `invalid_argument`）。
覆盖十二类共 260 个标识：星耀、宫位（含身宫、来因宫）、天干、地支、亮度、四化、
五行局、性别、生肖、时辰、星座、运限层级。完整清单与逐条说明见
[Rust](/zh/docs/rust/i18n)、[Python](/zh/docs/python/i18n)、[Go](/zh/docs/go/i18n) 三页。
`key_of("不存在的名字")` 返回 `None` / 空串，而不是把入参吐回来。
另有同形译名的问题：不同标识在某些语言下译名相同（`horse`、`dragon`、`유시` 等）。
反查按固定的扫描顺序取第一个命中，与 iztro 的 `kot` 逐例一致。
要指定类别就用 `key_of_in`（Rust）/ `key_of(text, key_filter)`（Python）/
`KeyOfIn`（Go），传标识名的共同后缀消歧：
`"Maj"` 只看十四主星、`"Min"` 只看辅星、`"Palace"` 只看宫位、`"Hour"` 只看时辰。
## 三种编程语言的取值形态不同 [#三种编程语言的取值形态不同]
| | 排盘结果里存什么 | 换盘面语言的代价 |
| ------ | ------------------------------------------ | ------------------- |
| Rust | 枚举（`StarKey`、`Palace`…），只有少数展示字段是 `String` | 调翻译函数，同一张盘可同时输出多种语言 |
| Python | 译名与标识两组字段都已经是字符串 | 重新排盘 |
| Go | 同上 | 重新排盘 |
排盘本身是毫秒级，多排几次不是问题。判断逻辑请始终用标识字段，
这样换盘面语言不需要改任何代码。
## 没有全局语言开关 [#没有全局语言开关]
x-iztro 不设「当前语言」这样的全局状态：排盘时语言随参数传入，
翻译函数每次调用都显式指定目标语言。
全局语言开关会让同一段代码在不同调用顺序下产出不同结果，并发环境尤其危险。
显式传参使每次调用的结果只由入参决定。
## 新增一种语言要改哪些地方 [#新增一种语言要改哪些地方]
词表不是一个可以外挂的资源文件，是编译进库的静态表。加一种语言要动四处：
`src/data/types.rs`
的
`Language`
枚举加一个变体，并在
`as_code`
/
`from_code`
里补上语言代码
`src/i18n/`
下新增一个词表文件，实现与既有文件相同的一组函数（星名、宫名、干支名、亮度、四化……）
`src/i18n/mod.rs`
里每个翻译函数的
`match`
各加一条分派 —— 这里是逐个函数的，不是一处
`src/i18n/lookup.rs`
的
`lang_index`
与反查扫描顺序表加一项；反查顺序会影响同形译名落到哪个标识，须与金标对照
绑定层不需要改：语言代码是字符串传入的，加了枚举变体三侧自动可用。
# 错误处理 (/zh/docs/guide/guides/errors)
校验了什么、在哪一层校验、四个错误分类各是什么，以及为什么核心层坚持不 panic。
*适合：开发者*
x-iztro 把外部输入的校验放在尽量靠内的一层，三种编程语言共用同一道防线。
各语言只把错误翻译成自己的惯例类型，不重复校验、也不各自解释。
## 错误分类 [#错误分类]
每个错误都带一个机器可读的分类，跨语言取值相同 —— **判断用它，不要解析文案**。
| 分类 | 含义 |
| -------------------- | --------------------------------------------------------------- |
| `invalid_date` | 日期格式非法、该日期不存在，或超出支持范围（公历 1583–9999） |
| `invalid_time_index` | 时辰索引越界（合法值 0–12） |
| `invalid_argument` | 其余入参或配置非法：未知的性别、盘面语言、星耀标识、开关取值、覆盖表长度错；反推的干支阴阳不配、条件为空或含流耀、年份范围非法 |
| `internal` | 库内部缺陷或运行时故障，不是调用方的错，请上报 |
## 各语言的错误类型 [#各语言的错误类型]
`IztroError` 枚举，`code()` 给出分类：
```rust
match by_solar(date, ti, Gender::Female, true, Language::ZhCN, Config::default()) {
Ok(chart) => { /* ... */ }
Err(e) => println!("{:20} {}", e.code(), e),
}
```
```text
invalid_date invalid solar date '2000-2-30': day is out of range for that month
invalid_date invalid solar date '1000-1-1': year must be within 1583-9999
invalid_time_index time_index must be 0-12, got 13
```
变体有四个：`InvalidDate`、`InvalidTimeIndex`、`InvalidArgument`、`Internal`。
枚举标了 `#[non_exhaustive]`，`match` 时请留 `_` 分支。
`IztroError`，继承 `ValueError`，所以既有的 `except ValueError` 依然能捕获：
```python
from x_iztro import Astro, IztroError
try:
Astro().by_solar("2000-2-30", 2, "female")
except IztroError as e:
print(e.code, e)
```
```text
invalid_date invalid solar date '2000-2-30': day is out of range for that month
```
`*iztro.Error`，带 `Code` 与 `Message`；四个哨兵变量配合 `errors.Is` 按类别匹配：
```go
_, err := iztro.BySolar("2000-13-1", 2, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
if errors.Is(err, iztro.ErrInvalidDate) {
var e *iztro.Error
errors.As(err, &e)
fmt.Println(e.Code, e.Message)
}
```
```text
invalid_date invalid solar date '2000-13-1': month must be within 1-12
```
| 哨兵 | 对应分类 |
| --------------------- | ---------------------- |
| `ErrInvalidDate` | `CodeInvalidDate` |
| `ErrInvalidTimeIndex` | `CodeInvalidTimeIndex` |
| `ErrInvalidArgument` | `CodeInvalidArgument` |
| `ErrInternal` | `CodeInternal` |
`Error()` 输出带 `iztro: ` 前缀；`Message` 是不带前缀的原文。
C FFI 与 wasm 出口把同一个错误落成 `{"error":"","code":""}`，
由 serde 生成以保证转义完备。
## 校验范围与消息样例 [#校验范围与消息样例]
消息一律小写起首、以冒号引出细节，并带上原始输入 ——
批量处理时能直接定位是哪一条数据出的问题。
| 输入 | 消息样例 |
| -------- | ------------------------------------------------------------------------------------ |
| 公历日期格式 | `invalid solar date 'not-a-date': year is not a number` |
| 公历日期不存在 | `invalid solar date '2000-2-30': day is out of range for that month` |
| 公历年份范围 | `invalid solar date '1000-1-1': year must be within 1583-9999` |
| 农历月份 | `invalid lunar date '2000-13-1': month must be within 1-12` |
| 农历该月天数 | `invalid lunar date '2000-2-31': day is out of range for that lunar month` |
| 时辰索引 | `time_index must be 0-12, got 13` |
| 性别 | `invalid gender 'x': expected 'male' or 'female'` |
| 盘面语言 | `invalid language 'fr-FR': expected one of zh-CN, zh-TW, en-US, ja-JP, ko-KR, vi-VN` |
| 自定义四化表长度 | `invalid mutagens for 'gengHeavenly': expected 4 stars (lu, quan, ke, ji), got 3` |
| 自定义表收到译名 | `invalid mutagens for 'gengHeavenly': unknown star '太阳'` |
日期与时辰在**核心层**校验，三种编程语言完全一致。
性别、盘面语言、配置开关、星耀标识这些以字符串传入的东西，
在**绑定层**解析时校验 —— Rust 侧它们本来就是枚举，不存在非法取值。
## 查不到不是错误 [#查不到不是错误]
需要计算的入口返回错误；**查询**方法查不到时返回空值而非错误——
「这张盘上没有这颗星」是正常结果，不是异常。
| 场景 | 返回 |
| ---------- | -------------- |
| 某颗星不在这张盘上 | `None` / `nil` |
| 宫位索引越界 | `None` / `nil` |
| 该星没有亮度表 | `None` / 空串 |
| 反查一个不存在的译名 | `None` / 空串 |
`chart.palace("soulPalce")` 不会报错，只会返回空；`has(["ziweiMj"])` 恒返回 `False`。
判断用枚举或常量（Python 的 `PalaceName.SOUL`、Go 的 `iztro.PalaceSoul`）——
拼错时是编译期或构造期报错，不是运行期静默。
要校验一个外来的字符串，把它喂给枚举构造：`PalaceName("x")` 会抛 `ValueError`。
## 为什么核心层不 panic [#为什么核心层不-panic]
这不是风格偏好，是 wasm 目标带来的硬约束。
wasm 上 panic 会变成
**trap**
，直接中止调用
`catch_unwind`
在 wasm 上
**无效**
——绑定层兜不住
每次 trap 都会
**永久损耗**
模块实例的栈空间，累积之后连合法调用都会失败
因此防线必须设在更靠内的一层：所有外部输入在进入算法前校验完毕，入口返回 `Result`。
绑定层的 `catch_unwind` 只负责兜底库内部的缺陷，不承担参数校验职责。
排盘入口不会因非法**外部输入**而 panic。若真的遇到，那是库内部缺陷，
会以 `internal` 分类返回，应作为 bug 上报——而不是调用方需要防御的情况。
## 批量处理的写法 [#批量处理的写法]
坏数据跳过、好数据继续，而不是整批失败：
```rust
let (charts, failed): (Vec<_>, Vec<_>) = rows
.iter()
.map(|r| by_solar(&r.date, r.ti, r.gender, true, Language::ZhCN, Config::default()))
.partition(Result::is_ok);
```
```python
charts, failed = [], []
for row in rows:
try:
charts.append(Astro().by_solar(row["date"], row["ti"], row["gender"]))
except IztroError as e:
failed.append((row, e.code, str(e)))
```
```go
for _, row := range rows {
chart, err := iztro.BySolar(row.Date, row.TimeIndex, row.Gender, true, iztro.LanguageZhCN, nil)
if err != nil {
var e *iztro.Error
errors.As(err, &e)
failed = append(failed, failure{row, e.Code, e.Message})
continue
}
charts = append(charts, chart)
}
```
逐条 API 的错误行为见
[Rust](/zh/docs/rust/errors)、[Python](/zh/docs/python/errors)、[Go](/zh/docs/go/errors) 三页。
# 扩展星盘 (/zh/docs/guide/guides/plugins)
把自己的分析规则挂到星盘上——三种编程语言各自的扩展点。
*适合：开发者*
排盘结果是数据，怎么解读是各家的事。斗数流派众多、判断规则千人千面，
把它们全塞进核心既不可能也不该做。x-iztro 的做法是让你把自己的规则
以方法的形式挂到星盘上，调用语法与内置方法一致。
## 三种编程语言的扩展点 [#三种编程语言的扩展点]
每种编程语言用它自己最自然的机制，不强行统一成一套：
| 编程语言 | 机制 | 检查时机 | 作用范围 |
| -------------------------------- | -------- | ---- | ---------- |
| [Rust](/zh/docs/rust/extend) | 扩展 trait | 编译期 | `use` 了才可见 |
| [Python](/zh/docs/python/extend) | 往类上挂方法 | 运行期 | 进程内全局 |
| [Go](/zh/docs/go/extend) | 结构体嵌入 | 编译期 | 只影响自己的类型 |
三者都做同一件事：`chart.my_method()` 这样调用，且能用上星盘的全部内置能力。
具体写法与可运行示例见各自的页面。
## 共同的约定 [#共同的约定]
`star.key == "ziweiMaj"` 在任何盘面语言下都成立；
`star.name == "紫微"` 只在中文盘上成立。
扩展方法里做判断请用 `*_key` / `*Key` 字段或内置判断方法，
展示时才取译名。这样同一条规则在六种盘面语言的盘上结果一致。
详见[语言无关标识](/zh/docs/guide/guides/keys)。
`WealthAnalysis`、`CareerAnalysis`、`HealthAnalysis` 各自成一组，
使用方按需引入。堆成一个大集合会让所有调用点都被迫带上全部方法。
同一套规则要在三种编程语言上都可用时，当前的做法是三侧各写一遍，
再用一组断言同一张盘上同一组取值的测试守住。
因为判断基于语言无关标识，三份实现只要逻辑相同，结果必然相同——
测试负责证明「逻辑确实相同」。
## 一个例子 [#一个例子]
三种编程语言实现同一个插件：取命宫主星（空宫借对宫），并读出五行局的局数。
```rust
trait MyAnalysis {
fn major_star(&self) -> String;
}
impl MyAnalysis for Astrolabe {
fn major_star(&self) -> String {
let soul = self.palace(Palace::Soul).expect("命宫必然存在");
let source = if soul.is_empty() { soul.opposite_palace() } else { soul };
source.major_stars.iter()
.filter(|s| s.star_type == StarType::Major)
.map(|s| translate_star(s.key, self.language))
.collect::>().join(",")
}
}
chart.major_star() // 紫微
```
```python
def my_analysis(cls: type[Astrolabe]) -> None:
def major_star(self) -> str:
soul = self.palace(PalaceName.SOUL)
source = soul.opposite_palace() if soul.is_empty() else soul
return ",".join(s.name for s in source.major_stars)
cls.major_star = major_star
load_plugin(my_analysis)
chart.major_star() # 紫微
```
```go
type MyChart struct{ *iztro.Astrolabe }
func (c MyChart) MajorStar() string {
soul := c.Palace(iztro.PalaceSoul)
source := soul
if soul.IsEmpty() {
source = soul.OppositePalace()
}
names := []string{}
for _, s := range source.MajorStars {
if s.Type == iztro.StarTypeMajor {
names = append(names, s.Name)
}
}
return strings.Join(names, ",")
}
MyChart{chart}.MajorStar() // 紫微
```
三段代码在同一张盘上都返回 `紫微`，换成英文盘则都返回 `emperor`。
# 排盘九步对应的 API (/zh/docs/guide/guides/step-api)
排盘的九个步骤各自对应哪个公开函数，以及哪些步骤会被配置开关改变。
*适合：开发者*
排盘的[九个步骤](/zh/docs/guide/concepts/how-it-works)在 x-iztro 里**每一步都有对应的公开函数**。
日常排盘用不到它们——直接调排盘入口即可；
这一页面向两类需求：想核对某一步的推算，或想复用其中一段自建流程。
下面的示例用的是 2000-8-16 寅时 女这张盘，与
[排盘是怎么算的](/zh/docs/guide/concepts/how-it-works)一页同一个例子。
## 步骤与 API 对照 [#步骤与-api-对照]
### 2. 定月索引 [#2-定月索引]
```python
utils.fix_lunar_month_index(7, 17, False, 2, True) # 农历七月十七、非闰月、寅时、修正闰月
```
```text
6
```
[Rust](/zh/docs/rust/util#fix_lunar_month_index--fix_lunar_day_index) ·
[Python](/zh/docs/python/util#fix_lunar_month_index--fix_lunar_day_index) ·
[Go](/zh/docs/go/util#fixlunarmonthindex--fixlunardayindex)
### 3. 定命宫身宫 [#3-定命宫身宫]
```python
utils.get_soul_and_body(6, 2, "gengHeavenly") # 月索引、时辰索引、年干
```
```text
SoulAndBody(soul_index=4, body_index=8, heavenly_stem_of_soul='renHeavenly', earthly_branch_of_soul='wuEarthly')
```
[Rust](/zh/docs/rust/util#get_soul_and_body) ·
[Python](/zh/docs/python/util#get_soul_and_body) ·
[Go](/zh/docs/go/util#getsoulandbody)
### 4. 定五行局 [#4-定五行局]
```python
utils.get_five_elements_class("renHeavenly", "wuEarthly") # 命宫干、命宫支
```
```text
wood3rd
```
[Rust](/zh/docs/rust/util#get_five_elements_class) ·
[Python](/zh/docs/python/util#get_five_elements_class) ·
[Go](/zh/docs/go/util#getfiveelementsclass)
### 5. 起紫微天府 [#5-起紫微天府]
```python
star.get_start_index("2000-8-16", 2, "female")
```
```text
StartIndex(ziwei_index=4, tianfu_index=8)
```
[Rust](/zh/docs/rust/star#get_start_index) ·
[Python](/zh/docs/python/star#get_start_index) ·
[Go](/zh/docs/go/star#getstartindex)
### 6 与 7. 安主星、辅星与杂耀 [#6-与-7-安主星辅星与杂耀]
三组各有一个入口，返回十二宫的星耀分布；
另有各组的落宫索引函数（`get_lu_yang_tuo_ma_index`、`get_chang_qu_index` 等），
清单见各语言的安星模块页。
[Rust](/zh/docs/rust/star) · [Python](/zh/docs/python/star) · [Go](/zh/docs/go/star)
### 8. 安四组十二神 [#8-安四组十二神]
`get_changsheng12`、`get_boshi12`、`get_yearly12`，
以及两个起点函数 `get_changsheng12_start_index`、`get_jiangqian12_start_index`。
### 9. 推大限小限 [#9-推大限小限]
```python
r = utils.get_decadals_and_ages(4, "wood3rd", "female", "gengHeavenly", "chenEarthly")
print(r.decadals[0], r.ages[0])
```
```text
Decadal(range=(43, 52), heavenly_stem='戊', heavenly_stem_key='wuHeavenly', earthly_branch='寅', earthly_branch_key='yinEarthly') [9, 21, 33, 45, 57, 69, 81, 93, 105, 117]
```
这个函数直接收命宫索引与五行局，不必先凑出一份完整的出生数据，
能力是 iztro 对应函数的超集。见[从 iztro 迁移：API 对照](/zh/docs/guide/about/iztro-parity#大限小限)。
[Rust](/zh/docs/rust/util#get_decadals_and_ages) ·
[Python](/zh/docs/python/util#get_decadals_and_ages) ·
[Go](/zh/docs/go/util#getdecadalsandages)
## 哪些步骤会被配置改变 [#哪些步骤会被配置改变]
| 配置 | 影响的步骤 |
| ------------------ | ------------------------ |
| `year_divide` | 1（年干支）→ 连带 6、7、8、9 |
| `horoscope_divide` | 1（月柱与年系杂耀所用年支）→ 连带 7 |
| `day_divide` | 1、2（晚子时归属）→ 连带 3、5 |
| `age_divide` | 9（虚岁进位时点） |
| `algorithm` | 4（中州派命主按年支）、7、8（部分星耀的取法） |
| `astro_type` | 4 起（换宫起局）→ 连带 5、6、8、9 |
| 自定义四化表 | 6（四化标记）与全部飞星判断 |
| 自定义亮度表 | 6、7（星耀亮度） |
逐项说明见 [Config 详解](/zh/docs/guide/guides/config)。
# 给 AI 读的文档端点 (/zh/docs/guide/guides/llms-txt)
本站提供的 llms.txt、llms-full.txt、单页 Markdown 与 Accept 头协商。
*适合：开发者 · 运维*
这一页讲的是**怎么让 AI 读懂这份文档**——不是怎么用这个库。
想把 x-iztro 接进 AI 应用，看[让 AI 解读命盘](/zh/docs/guide/guides/llm)。
## `/llms.txt` [#llmstxt]
站点结构索引，列出该语言所有页面的标题、描述与链接。适合让模型先定位再抓取。
## `/llms-full.txt` [#llms-fulltxt]
该语言全站文档的 Markdown 全文，一次抓取即可作为完整上下文。
## 两个端点都分语言 [#两个端点都分语言]
索引与全文各语言一份，互不混杂——全文本来就是整份塞进上下文用的，
掺入用不上的语言只会挤占窗口。
| 端点 | 内容 |
| ----------------------------------------- | ------------------------------ |
| `/zh/llms.txt` · `/en/llms.txt` | 该语言的结构索引，末尾列出其余语言与全文端点 |
| `/zh/llms-full.txt` · `/en/llms-full.txt` | 该语言的全文 |
| `/llms.txt` · `/llms-full.txt` | llms.txt 约定的根路径，内容同 `/zh/` 那两个 |
## 单页 Markdown [#单页-markdown]
任意文档页 URL 追加 `.md` 就得到该页的 Markdown 原文：
`.md` 与 `.mdx` 两种后缀都可以，返回内容相同。
页面标题下方的「复制 Markdown」按钮取的就是这个端点，「打开」下拉里还能
直接送进 ChatGPT 或 Claude。
## 不知道后缀约定也能拿到 [#不知道后缀约定也能拿到]
AI 代理在请求任意文档页时，只要 `Accept` 头里表明更想要 Markdown，
就会拿到 Markdown 原文而不是整页 HTML：
```bash
curl -H "Accept: text/markdown" <本站地址>/zh/docs/rust/palace
```
同一个页面，HTML 约 400 KB，Markdown 约 14 KB。
这三种取法返回的都是纯文本，没有导航、样式与脚本，
比让模型抓 HTML 省 token 也更准确。
## 建议的用法 [#建议的用法]
问 AI 关于 x-iztro 的问题时，把 `/zh/llms-full.txt` 作为上下文一起给它。
单一语言的全文约 500 KB，在常见模型的上下文窗口内绰绰有余。
如果只关心某个主题，抓对应的单页 `.md` 更省：
| 主题 | 页面 |
| ------------- | ----------------------------------- |
| 参数与安装 | `/zh/docs/guide/getting-started.md` |
| 领域概念 | `/zh/docs/guide/concepts.md` 及其子页 |
| 分界点与流派 | `/zh/docs/guide/guides/config.md` |
| 字段字典 | `/zh/docs/guide/data-model.md` |
| to\_text 文本格式 | `/zh/docs/guide/guides/to-text.md` |
# 数据结构字典 (/zh/docs/guide/data-model)
Astrolabe、Palace、Star、Horoscope 每一个字段的类型与含义。
*适合：开发者*
这一页以序列化后的 JSON 字段名（camelCase）为准，它是三套绑定共用的契约。
各编程语言的命名换算：
| 层 | 命名 | 示例 |
| ----------- | ---------------- | ---------------- |
| JSON / 绑定契约 | camelCase | `isBodyPalace` |
| Python | snake\_case | `is_body_palace` |
| Go | PascalCase | `IsBodyPalace` |
| Rust | snake\_case，值为枚举 | `is_body_palace` |
## Astrolabe 星盘 [#astrolabe-星盘]
排盘入口的返回值。
| 字段 | 类型 | 含义 |
| ------------------------------ | --------------------------- | ------------------------- |
| `gender` | string | 性别，翻译文本 |
| `genderKey` | string | `"male"` / `"female"` |
| `solarDate` | string | 阳历生日，与入参一致 |
| `lunarDate` | string | 农历生日的文字表示 |
| `chineseDate` | string | 四柱干支展示串 |
| `rawDates` | [RawDates](#rawdates-结构化日期) | 结构化的农历生日与四柱 |
| `time` | string | 时辰名，如「寅时」 |
| `timeRange` | string | 时辰时间段，如「03:00\~05:00」 |
| `sign` | string | 星座 |
| `signKey` | string | 星座 key，`aries` … `pisces` |
| `zodiac` | string | 生肖，按年支 |
| `zodiacKey` | string | 生肖 key，`rat` … `pig` |
| `earthlyBranchOfSoulPalace` | string | 命宫地支 |
| `earthlyBranchOfSoulPalaceKey` | string | 命宫地支 key |
| `earthlyBranchOfBodyPalace` | string | 身宫地支 |
| `earthlyBranchOfBodyPalaceKey` | string | 身宫地支 key |
| `soul` | string | 命主星 |
| `soulKey` | string | 命主星 key |
| `body` | string | 身主星 |
| `bodyKey` | string | 身主星 key |
| `fiveElementsClass` | string | 五行局 |
| `fiveElementsClassKey` | string | 五行局 key，如 `water2nd` |
| `palaces` | [Palace](#palace-宫位)\[12] | 十二宫，索引 0 是寅宫 |
| `timeIndex` | int | 出生时辰索引 0–12，保留原始传入值 |
| `fixLeap` | bool | 是否修正闰月 |
| `language` | string | 盘面语言 |
| `config` | [Config](#config-配置) | 排盘配置 |
## Palace 宫位 [#palace-宫位]
| 字段 | 类型 | 含义 |
| ---------------------------------- | ---------------------- | ---------------------------------------------------------------------------- |
| `index` | int | 宫位在盘上的位置，0–11，0 是寅宫 |
| `name` | string | 宫名 |
| `nameKey` | string | 宫名 key，如 `soulPalace` |
| `isBodyPalace` | bool | 是否身宫 |
| `isOriginalPalace` | bool | 是否来因宫 |
| `heavenlyStem` | string | 宫干 |
| `heavenlyStemKey` | string | 宫干 key |
| `earthlyBranch` | string | 宫支 |
| `earthlyBranchKey` | string | 宫支 key |
| `majorStars` | [Star](#star-星耀)\[] | 主星 |
| `minorStars` | [Star](#star-星耀)\[] | 辅星 |
| `adjectiveStars` | [Star](#star-星耀)\[] | 杂耀 |
| `changsheng12` / `changsheng12Key` | string | 长生十二神 |
| `boshi12` / `boshi12Key` | string | 博士十二神 |
| `jiangqian12` / `jiangqian12Key` | string | 将前十二神 |
| `suiqian12` / `suiqian12Key` | string | 岁前十二神 |
| `mutagenStarKeys` | string\[4] | 本宫宫干化出的四颗星标识，顺序为禄、权、科、忌；受[自定义四化表](/zh/docs/guide/guides/config#自定义四化表与亮度表)影响 |
| `decadal` | [Decadal](#decadal-大限) | 该宫掌管的大限 |
| `ages` | int\[] | 小限经过该宫的虚岁列表 |
## Star 星耀 [#star-星耀]
| 字段 | 类型 | 含义 |
| --------------- | ------- | ----------------------------------------------------------------------------------- |
| `key` | string | 星耀 key，如 `ziweiMaj` |
| `name` | string | 星名 |
| `type` | string | `major` / `soft` / `tough` / `adjective` / `flower` / `helper` / `lucun` / `tianma` |
| `scope` | string | `origin` / `decadal` / `yearly` / `monthly` / `daily` / `hourly` |
| `brightness` | string | 亮度显示文本。**主星与辅星恒有这个键**，无亮度时为空串；杂耀与流耀整个键缺省 |
| `brightnessKey` | string? | 亮度标识。无亮度时**缺省**（不是空串） |
| `mutagen` | string | 四化显示文本。**十四主星与左辅右弼文昌文曲这 18 颗四化候选星恒有这个键**，无四化时为空串；其余星整个键缺省 |
| `mutagenKey` | string? | 四化标识。无四化时**缺省** |
`brightness` / `mutagen` 这两个**翻译字段**按星耀类别决定键在不在，
在的时候可能是空串；`brightnessKey` / `mutagenKey` 这两个**标识字段**
则是没值就整个键不出现。
所以「有没有亮度」要判断 `brightnessKey` 存在与否，
而不是判断 `brightness` 这个键在不在 —— 后者对所有主辅星都为真。
## Decadal 大限 [#decadal-大限]
| 字段 | 类型 | 含义 |
| ------------------------------------ | ----------- | -------- |
| `range` | \[int, int] | 起止虚岁，含两端 |
| `heavenlyStem` / `heavenlyStemKey` | string | 大限天干 |
| `earthlyBranch` / `earthlyBranchKey` | string | 大限地支 |
## RawDates 结构化日期 [#rawdates-结构化日期]
| 字段 | 类型 | 含义 |
| ------------------------- | ----------------- | ----------------------------------------- |
| `lunarDate.lunarYear` | int | 农历年 |
| `lunarDate.lunarMonth` | int | 农历月 1–12 |
| `lunarDate.lunarDay` | int | 农历日 1–30 |
| `lunarDate.isLeap` | bool | 是否闰月 |
| `chineseDate.yearly` | \[string, string] | 年柱 \[天干, 地支] |
| `chineseDate.monthly` | \[string, string] | 月柱 |
| `chineseDate.daily` | \[string, string] | 日柱 |
| `chineseDate.hourly` | \[string, string] | 时柱 |
| `chineseDate.yearlyKeys` | \[string, string] | 年柱的[语言无关 key](/zh/docs/guide/guides/keys) |
| `chineseDate.monthlyKeys` | \[string, string] | 月柱的语言无关 key |
| `chineseDate.dailyKeys` | \[string, string] | 日柱的语言无关 key |
| `chineseDate.hourlyKeys` | \[string, string] | 时柱的语言无关 key |
四柱里的干支是未本地化的原文（任何盘面语言下都是中文），做判断请用 `*Keys`。
把 `*Keys` 交给 `translate_chinese_date` 即可得到按语言翻译的展示串，
与顶层 `chineseDate` 字段逐字一致。
## Config 配置 [#config-配置]
| 字段 | 取值 | 默认 |
| ----------------- | ---------------------------- | --------- |
| `yearDivide` | `normal` / `exact` | `normal` |
| `horoscopeDivide` | `normal` / `exact` | `normal` |
| `ageDivide` | `normal` / `birthday` | `normal` |
| `dayDivide` | `forward` / `current` | `forward` |
| `algorithm` | `default` / `zhongzhou` | `default` |
| `astroType` | `heaven` / `earth` / `human` | `heaven` |
另有两个**只进不出**的输入键，用于替换内置数据表：
| 输入键 | 取值 |
| ------------ | ---------------------------------------- |
| `mutagens` | `{天干标识: [四个星耀标识]}`，顺序为禄权科忌，必须四项 |
| `brightness` | `{星耀标识: [十二个亮度标识]}`，第一项是寅宫，必须十二项，无亮度处传空串 |
这两个键**不会回显在星盘的 `config` 里** —— 它们是排盘的输入配置，
不属于排盘结果，加进 DTO 会破坏与 JS iztro 的字段契约。
要留档就自己存那份配置。
含义见 [Config 详解](/zh/docs/guide/guides/config)。
## Horoscope 运限 [#horoscope-运限]
| 字段 | 类型 | 含义 |
| ----------- | -------------------------------------- | -------------------- |
| `solarDate` | string | 目标阳历日期 |
| `lunarDate` | string | 目标农历日期 |
| `decadal` | [HoroscopeScope](#horoscopescope-运限层级) | 大限，未起运时为童限 |
| `age` | HoroscopeScope | 小限，带 `nominalAge` |
| `yearly` | HoroscopeScope | 流年，带 `yearlyDecStar` |
| `monthly` | HoroscopeScope | 流月 |
| `daily` | HoroscopeScope | 流日 |
| `hourly` | HoroscopeScope | 流时 |
### HoroscopeScope 运限层级 [#horoscopescope-运限层级]
| 字段 | 类型 | 含义 |
| ------------------------------------ | -------------------------------------- | -------------------------------------------------------------------------------------- |
| `index` | int | 该运限所在盘上位置 0–11 |
| `name` | string | 层级名，翻译文本 |
| `nameKey` | string | 层级 key：`decadal` / `childhood` / `turn`（小限）/ `yearly` / `monthly` / `daily` / `hourly` |
| `heavenlyStem` / `heavenlyStemKey` | string | 该运限天干 |
| `earthlyBranch` / `earthlyBranchKey` | string | 该运限地支 |
| `palaceNames` | string\[12] | 以该运限位置为命宫重排的宫名，按盘上位置排列 |
| `palaceNameKeys` | string\[12] | 同上的 key 形式 |
| `mutagen` | string\[4] | 四化星名，顺序为禄、权、科、忌 |
| `mutagenStarKeys` | string\[4] | 同上的 key 形式，与宫位的同名字段同义——被化的四颗星的星耀标识；单数 `mutagenKey` 才是四化类型（`sihuaLu` 等） |
| `stars` | [Star](#star-星耀)\[]\[12]? | 流耀在十二宫的分布（外层十二项对应宫位，内层是该宫的流耀列表），无流耀的层级缺省 |
| `nominalAge` | int? | 虚岁，仅小限有 |
| `yearlyDecStar` | [YearlyDecStar](#yearlydecstar-流年十二神)? | 仅流年有 |
命主尚未起运时，`decadal` 这一层的 `nameKey` 为 `childhood`（童限）而非 `decadal`——
童限与大限是不同的解盘语义。程序判断该层是不是童限请用 `nameKey`，
不要比对 `name` 的译文。
### YearlyDecStar 流年十二神 [#yearlydecstar-流年十二神]
| 字段 | 类型 | 含义 |
| --------------------------------- | ----------- | ------------------- |
| `suiqian12` / `suiqian12Keys` | string\[12] | 按流年支起的岁前十二神，索引即宫位索引 |
| `jiangqian12` / `jiangqian12Keys` | string\[12] | 按流年支起的将前十二神 |
Rust 里 `age` 与 `yearly` 的通用字段收在 `.base` 下（`AgeItem { base, nominal_age }`），
序列化时用 `#[serde(flatten)]` 展平，所以 JSON 与 Python / Go 侧看到的是平铺结构。
## 完整 JSON 样例 [#完整-json-样例]
`by_solar("2000-8-16", 2, female)` 的真实输出（顶层，省略 `palaces` 的十二项）：
```json
{
"gender": "女",
"genderKey": "female",
"solarDate": "2000-8-16",
"lunarDate": "二〇〇〇年七月十七",
"chineseDate": "庚辰 甲申 丙午 庚寅",
"rawDates": {
"lunarDate": { "lunarYear": 2000, "lunarMonth": 7, "lunarDay": 17, "isLeap": false },
"chineseDate": {
"yearly": ["庚", "辰"], "monthly": ["甲", "申"],
"daily": ["丙", "午"], "hourly": ["庚", "寅"],
"yearlyKeys": ["gengHeavenly", "chenEarthly"],
"monthlyKeys": ["jiaHeavenly", "shenEarthly"],
"dailyKeys": ["bingHeavenly", "wuEarthly"],
"hourlyKeys": ["gengHeavenly", "yinEarthly"]
}
},
"time": "寅时",
"timeRange": "03:00~05:00",
"sign": "狮子座", "signKey": "leo",
"zodiac": "龙", "zodiacKey": "dragon",
"earthlyBranchOfSoulPalace": "午", "earthlyBranchOfSoulPalaceKey": "wuEarthly",
"earthlyBranchOfBodyPalace": "戌", "earthlyBranchOfBodyPalaceKey": "xuEarthly",
"soul": "破军", "soulKey": "pojunMaj",
"body": "文昌", "bodyKey": "wenchangMin",
"fiveElementsClass": "木三局", "fiveElementsClassKey": "wood3rd",
"palaces": [ /* 12 项 */ ],
"timeIndex": 2,
"fixLeap": true,
"language": "zh-CN",
"config": {
"yearDivide": "normal", "horoscopeDivide": "normal",
"ageDivide": "normal", "dayDivide": "forward",
"algorithm": "default", "astroType": "heaven"
}
}
```
### 一个宫的样例 [#一个宫的样例]
同一张盘的命宫（`palaces` 里 `index` 为 4 的那一项）：
```json
{
"index": 4,
"name": "命宫", "nameKey": "soulPalace",
"isBodyPalace": false, "isOriginalPalace": false,
"heavenlyStem": "壬", "heavenlyStemKey": "renHeavenly",
"earthlyBranch": "午", "earthlyBranchKey": "wuEarthly",
"majorStars": [
{ "key": "ziweiMaj", "name": "紫微", "type": "major", "scope": "origin",
"brightness": "庙", "brightnessKey": "miao", "mutagen": "" }
],
"minorStars": [
{ "key": "wenquMin", "name": "文曲", "type": "soft", "scope": "origin",
"brightness": "陷", "brightnessKey": "xian", "mutagen": "" }
],
"adjectiveStars": [
{ "key": "fengge", "name": "凤阁", "type": "adjective", "scope": "origin" },
{ "key": "tianfu", "name": "天福", "type": "adjective", "scope": "origin" },
{ "key": "jielu", "name": "截路", "type": "adjective", "scope": "origin" },
{ "key": "feilian", "name": "蜚廉", "type": "adjective", "scope": "origin" },
{ "key": "nianjie", "name": "年解", "type": "helper", "scope": "origin" }
],
"changsheng12": "衰", "changsheng12Key": "shuai",
"boshi12": "青龙", "boshi12Key": "qinglong",
"jiangqian12": "灾煞", "jiangqian12Key": "zhaisha",
"suiqian12": "丧门", "suiqian12Key": "sangmen",
"mutagenStarKeys": ["tianliangMaj", "ziweiMaj", "zuofuMin", "wuquMaj"],
"decadal": {
"range": [3, 12],
"heavenlyStem": "壬", "heavenlyStemKey": "renHeavenly",
"earthlyBranch": "午", "earthlyBranchKey": "wuEarthly"
},
"ages": [5, 17, 29, 41, 53, 65, 77, 89, 101, 113]
}
```
紫微与文曲都有 `mutagen: ""` —— 它们是四化候选星，这一盘上没被化到，
所以键在但值为空，`mutagenKey` 则整个缺省。五颗杂耀连 `brightness` 键都没有。
## `*Key` 字段是什么 [#key-字段是什么]
每个会被翻译的字段旁边都有一个同名加 `Key` 后缀的伴生字段，
取值是 iztro 的 i18n 键名，与盘面语言无关：
```json
{ "name": "紫微", "key": "ziweiMaj", "brightness": "庙", "brightnessKey": "miao" }
```
翻译字段给人看，标识字段给代码用。契约就两条：
1. **凡有译文的属性 `x`，必有配套的 `xKey`**；数组形式的用复数 `Keys`
（`palaceNameKeys`、`yearlyKeys`）。
2. **实体自身的标识直接叫 `key`**——星耀的标识字段是 `key` 而非 `nameKey`。
唯一的命名分叉在四化：单数 `mutagenKey` 是四化类型（`sihuaLu` 等），
复数 `mutagenStarKeys` 是被化的四颗星的星耀标识。
这份契约由 `semantic_contract` 测试强制——DTO 每个翻译字段都必须有对应的标识字段。
`*Key` / `key` 系列、`genderKey`、`timeIndex`、`fixLeap`、`language`、`config`
是 x-iztro 相对 JS iztro 的扩展；其余字段与 iztro 的 `JSON.stringify`
输出逐键逐值一致，由绑定契约测试守着。判断逻辑请用标识字段，见
[key 契约](/zh/docs/guide/guides/keys)。
## 导出 JSON [#导出-json]
Python 侧有现成的导出方法，输出即上面这份契约：
```python
chart.to_dict() # dict
chart.to_json(indent=2) # str
```
`Astrolabe`、`Palace`、`Star` 之间有回指引用（宫位持有所属星盘），
`asdict()` 会递归进去直到 `RecursionError`。要 JSON 就用 `to_json()`。
# 概览 (/zh/docs/guide/about)
准确性保证、给 AI 读的文档端点，以及移植与架构说明。
*适合：所有人*
## 项目信息 [#项目信息]
| 项目 | 值 |
| --------- | ---------------------------------------------------------------- |
| 对照的 iztro | v2.6.1（版本锁定） |
| 许可 | MIT |
| 仓库 | [github.com/x-haose/x-iztro](https://github.com/x-haose/x-iztro) |
| crates.io | [x-iztro](https://crates.io/crates/x-iztro) |
| PyPI | [x-iztro](https://pypi.org/project/x-iztro/) |
当前版本号以 crates.io 与 PyPI 上的发布为准。
# 准确性保证 (/zh/docs/guide/about/accuracy)
716,314 例金标测试如何保证 x-iztro 与 JS iztro 零差异，以及这个「准」的边界在哪。
*适合：所有人。「哈希比对怎么做」一节给开发者*
排盘库最重要的属性是**结果正确**。而「正确」在紫微斗数里没有权威裁判 ——
不同实现之间的差异往往来自流派取舍，很难说谁对谁错。
x-iztro 因此把目标定得很具体：**与 JS
[iztro](https://github.com/SylarLong/iztro) v2.6.1 逐字段一致**。
把它当作金标准，差异就从「见仁见智」变成了可以自动检测的 bug。
## iztro 是什么，为什么拿它当金标准 [#iztro-是什么为什么拿它当金标准]
iztro 是一个 TypeScript 写的开源紫微斗数排盘库，
是这个领域里最完整、维护时间最长的开源实现之一，
不少前端项目与小程序在用。
选它做基准的理由不是「它一定对」，而是三条工程上的性质：
1. **完整**：本命盘、六层运限、四组十二神、年系杂耀、中州派、六种盘面语言，
一个不缺 —— 有得可对，才对得下去。
2. **确定**：同样的输入永远给同样的输出，没有随机与外部依赖，
所以差异一定是逻辑差异，不是噪声。
3. **可锁版本**：把版本钉在 v2.6.1，基准就是稳定的；
iztro 升级时重新生成基准数据，失败的用例清单就是版本间的行为差异清单。
## 这个「准」指什么、不指什么 [#这个准指什么不指什么]
x-iztro 保证的是：**在同一套流派取舍下，算得与一个成熟实现完全一样**。
它**不保证**这套流派取舍本身是「对的」。
庚干化科取太阴还是天府、年干支按正月初一还是立春换、晚子时归今天还是明天 ——
这些历来就有分歧，iztro 选了一套，x-iztro 原样跟随，并把有分歧的地方
做成[配置开关](/zh/docs/guide/guides/config)让你自己决定。
如果你的流派与默认不同，改配置或用自定义四化表，别期待默认输出符合你的师承。
基准数据由 JS 侧生成，用例集中在 JS 实现能稳定生成的年份区间内，
边界年代（1583–1983 与 2044–2100）另有按十年抽样的一层。
x-iztro 本身支持公历 1583–9999 年，区间之外的年份能排出盘，
但**没有金标数据逐例对照过** —— 用在极端年份上时请自行验证。
## 覆盖矩阵 [#覆盖矩阵]
全部基准数据由锁定版本的 JS iztro 生成，共 716,314 例：
| 层级 | 用例数 | 覆盖范围 | 数据格式 |
| --------- | ----------- | ------------------------------------------------------------- | ----------- |
| Tier 1 | 1,560 | 60 年 × 13 时辰 × 男女，**全字段逐一比对**（含展示字段、来因宫与结构化日期） | 完整 JSON |
| Tier 2 | 37,440 | 60 年 × 每月 1/15 号 × 13 时辰 × 男女 | 压缩 JSON |
| Tier 3 | 586,430 | 60 年**每一天** × 13 时辰 × 男女 × fix\_leap（闰月双份） | SHA-256 CSV |
| 边界年代 | 46,228 | 1583–1983 与 2044–2100 每 10 年抽样，补 Tier 1/2/3 只覆盖 1984–2043 的盲区 | SHA-256 CSV |
| Horoscope | 5,760 | 360 命盘 × 16 目标日期，六层级运限全字段 | 紧凑 JSON |
| Variants | 14,268 | by\_lunar 闰月逐日、中州派、六种盘面语言 | CSV / JSON |
| Config | 9,696 | 四个分界开关的非默认取值，含排盘层与运限层的组合 | CSV / JSON |
| 中州派盘型 | 12,488 | 天盘 / 地盘 / 人盘 | SHA-256 CSV |
| 1602 窗口 | 2,444 | 1602-2-20 至 4-25 逐日 × 13 时辰 × 男女（闰月日期含 fix\_leap 双份），锁定闰二月修正层 | SHA-256 CSV |
| **合计** | **716,314** | | |
以下不计入上表：
* **翻译反查 1,559 例**：逐条对照 iztro `kot` 的实际取值，守的是同形译名的消歧顺序
* **绑定契约 13 例**：把 DTO 与 iztro 的 `JSON.stringify` 输出逐键逐值对照
* **Python 端到端 209 例**（含自定义四化表与亮度表、全时辰覆盖、格局与知识包）
* **Go 端到端测试**：金标对照、星耀落宫、并发正确性、覆盖表、非法输入轰炸
* **C FFI 边界安全测试**：任何非法输入都必须返回错误 JSON 而非崩溃
* **Prompt 快照测试**：中英两种语言的本命与运限 prompt 逐字节比对
## 每一层在防什么 [#每一层在防什么]
**Tier 1** 抓字段级差异。它比对包括展示串、来因宫标记在内的每一个字段，
一旦某个字段的翻译或格式与 iztro 不同，立刻暴露。
**Tier 2 与 Tier 3** 抓边界日期。紫微斗数的错误常常只在特定日期出现 ——
闰月、月末、年初、节气交接。Tier 3 覆盖 60 年里的每一天，一天都不漏。
**边界年代**抓年份两端。Tier 1/2/3 集中在 1984–2043，
这一层按十年抽样把范围拉到 1583 与 2100，
防的是历法算法在远端年份上悄悄走样。
**Horoscope** 抓运限。16 个目标日期专门选在会出问题的位置：
12 个流年支各一、童限、高龄、闰月、晚子时。
**Variants** 抓流派与盘面语言。中州派与六种盘面语言各自完整比对，
确保切换算法派别或语言不引入偏差。
**Config** 与**中州派盘型**抓分界点与盘型。立春窗口逐日、晚子时、生日前后 ——
每个开关都在它会产生分歧的窗口里逐日验证。
**1602 窗口**抓农历依赖本身的缺陷。Rust 侧农历库的月表在 1602 年自相矛盾
（二月 31 天），x-iztro 在月表唯一读取入口按真值修正——真值经 lunar-typescript、
寿星天文历（sxtwl）与韩国天文研究院历表三个独立来源交叉确认——这一层把修正窗口
逐日锁死；另有 1583–9999 全域逐日扫描（约 614 万盘，标 `#[ignore]`）未发现
第二个同类窗口。
## 哈希比对怎么做的 [#哈希比对怎么做的]
给开发者
Tier 3 有 58 万例，存完整 JSON 会有几十 GB。所以这几层比对的是**规范化串的 SHA-256**：
JS 侧的 `tests/golden/canonical.mjs` 与 Rust 侧的 `tests/common/mod.rs`
实现同一套序列化规则，**逐字节同构**。两边各自把排盘结果压成同一个规范化串，
比对哈希即可 —— 存的是 SHA-256 的前 32 个十六进制字符，而不是几十 KB 的 JSON。
哈希不一致时，用生成器的 `--inspect` 系列参数重放该例的 JS 输出，
与 Rust 的规范化串做 diff，直接定位到出错字段。
## 跑测试 [#跑测试]
```bash
# 常规层：单元 + Tier 1/2 + 运限 + 变体 + 配置 + 契约 + 1602 窗口，约 1 分钟
cargo test
# Tier 3 全量：586,430 例，约 70 秒
cargo test --release --test golden_tier3 -- --ignored
# 绑定端到端
cd python && pytest tests/ # 需先 maturin develop
cd go/iztro && go test ./...
```
## 重新生成基准数据 [#重新生成基准数据]
需要 Node.js 环境：
```bash
cd tests/golden
npm ci
npm run gen:all # 全部层级；逐个生成器见 package.json 的 gen:* 脚本
```
tier3 与边界年代层按年跳过已存在的文件，便于断点续跑；tier3 另支持
`node generate_tier3.mjs --range <起> <止>` 分段，多进程并行可跑满 CPU（全量约 30 分钟）。
## 跟进 iztro 新版本 [#跟进-iztro-新版本]
流程是固定的：
1. 升级 `tests/golden/package.json` 里锁定的 iztro 版本
2. 重新生成全部基准数据
3. 跑 `cargo test`
失败的用例清单就是两个版本之间的行为差异清单 —— 不需要读 changelog，
测试直接告诉你哪些字段变了。
这条流程覆盖的是**数值**差异。iztro 新增或删除 API 时测试不会报，
那部分要按[从 iztro 迁移：API 对照](/zh/docs/guide/about/iztro-parity)一页逐条自查。
## 零容忍的含义 [#零容忍的含义]
任何一例不一致都当作 bug 处理，不接受「差异很小」「这个字段不重要」这类理由。
凡是 iztro 有的功能与数据，x-iztro 必须给出相同结果；
在此之上再谈扩展功能（语言无关标识、Prompt 生成、Config 开关的语义化）。
# 架构 (/zh/docs/guide/about/architecture)
核心层与三套绑定的分层、各自的实现取舍，以及不 panic 的设计约束。
*适合：开发者*
x-iztro 是一份 Rust 核心加三套绑定。算法只实现一次，
Python、Go 与 C 调用方拿到的是同一份计算结果。
## 分层 [#分层]
```
┌──────────────────────────────┐
│ Rust 核心库 │
│ astro/ 排盘、运限、宫位推算 │
│ star/ 安星 │
│ data/ 枚举、常量、数据表 │
│ i18n/ 六语言词表与双向查找 │
└──────────────┬───────────────┘
│
bridge.rs（编组与分派）
dto.rs（序列化契约）
│
┌────────────────────┼────────────────────┐
│ │ │
python.rs wasm.rs ffi.rs
PyO3 扩展 wasm32-wasip1 C ABI
│ │ │
Python 包 Go 包（wazero） C / C++ / 其他
```
两个共用层各司其职：
| 层 | 职责 |
| ----------- | --------------------------------------------------------------------- |
| `bridge.rs` | 入参解析、按名分派、结果编组。Python 与 Go 走同一个函数，行为没有分叉的余地。它是 crate 内部模块，不在公开 API 面上 |
| `dto.rs` | 序列化契约：camelCase 键、按盘面语言翻译的值，外加 `*Key` 标识与排盘上下文 |
绑定文件因此很薄——只剩语言特有的部分：wasm 的内存协定、PyO3 的异常类型。
## 三套绑定的取舍 [#三套绑定的取舍]
### Python：PyO3 原生扩展 [#pythonpyo3-原生扩展]
Rust 侧用 pythonize 在 Python 对象与 Rust 结构体之间直转，
Python 侧用 dataclass 包装成类型化 API。
* 编译为 abi3 wheel（`abi3-py310`），一个 wheel 覆盖 Python 3.10 及以上
* 零运行期依赖，纯 stdlib（dataclasses + StrEnum）
* 没有 JSON 序列化往返，开销最小
### Go：内嵌 WebAssembly [#go内嵌-webassembly]
编译为 `wasm32-wasip1`，用纯 Go 的 wazero 运行时执行。
选它而不是 cgo 的理由是**保留 Go 的交叉编译能力**：cgo 会让 `GOOS`/`GOARCH`
交叉编译变得极其麻烦，还要求使用者本机有 C 工具链。wasm 方案下 `go get` 即用，
静态链接与容器构建都不受影响。
单个 wasm 实例不能并发使用，包内维护一个**实例池**（上限 `GOMAXPROCS`）：
每个调用取一个空闲实例，用完归还，多 goroutine 之间不串行化。
wasm 模块只编译一次，编译产物落盘缓存在 `os.UserCacheDir()` 下，
所以只有机器上第一次是 \~200ms，之后每个进程的首次调用 \~30ms。
`iztro.Warmup(ctx)` 可以把这段冷启动提前到服务启动阶段，
`iztro.Close(ctx)` 归还全部实例内存。
wazero 的编译器后端只支持 amd64 与 arm64，其余架构走解释器，速度慢但结果相同。
每次调用另有一次 JSON 编解码与 wasm 内存拷贝，热路径上单次排盘在 0.5ms 量级。
### C FFI [#c-ffi]
标准 C ABI，收 C 字符串、返回 JSON 字符串。
错误以 `{"error":"..."}` 返回，由 serde 生成以保证转义完备。
外层有 `catch_unwind` 兜底。
## 核心层不 panic [#核心层不-panic]
日期格式与存在性、公历年份范围、时辰索引在**核心层**校验，入口返回 `Result`；
性别、盘面语言、配置开关、标识这些以字符串传入的东西在绑定层解析时校验
（Rust 侧它们本来就是枚举）。两处都不 panic。
绑定层的 `catch_unwind` 只负责兜底库内部的缺陷，不承担参数校验职责。
wasm 上 panic 会变成 trap，而 `catch_unwind` 在 wasm 上无效——兜不住。
更糟的是每次 trap 都会永久损耗模块实例的栈空间，累积之后连合法调用都会失败。
校验因此必须在更靠内的一层，三种编程语言共用同一道防线。
各语言的错误类型见 [Rust](/zh/docs/rust/errors)、[Python](/zh/docs/python/errors)、[Go](/zh/docs/go/errors) 三页。
## 一致性怎么保证 [#一致性怎么保证]
三种编程语言的行为一致不靠纪律，靠三层结构约束：
**算法只有一份**
—— 全部计算在 Rust 核心完成，绑定层不含任何斗数逻辑
**编组只有一份**
—— Python 与 Go 调用同一个
`bridge::query`
，入参解析与结果形状不可能分叉
**断言成对**
—— 每组对外能力在 Python 与 Go 两侧各有一组 parity 测试，断言同一张盘上的同一组取值
判断方法一律基于语言无关标识，因此同一条分析规则在三种编程语言上写出来、结果也相同。
标识约定见[语言无关标识](/zh/docs/guide/guides/keys)。
## 版本 [#版本]
| 项目 | 版本 |
| ------------ | ------------ |
| 对照的 iztro | v2.6.1（版本锁定） |
| Rust edition | 2024 |
| Python 要求 | 3.10 及以上 |
| Go 要求 | 1.22 及以上 |
当前版本号见 [crates.io](https://crates.io/crates/x-iztro) 与 [PyPI](https://pypi.org/project/x-iztro/)。
## 许可 [#许可]
MIT。
# 从 iztro 迁移：API 对照 (/zh/docs/guide/about/iztro-parity)
iztro 每个公开 API 在 x-iztro 三侧的落点，换了形状的几处及其原因，以及不提供的那些。
*适合：开发者，尤其是从 JS iztro 迁移过来的*
x-iztro 是 [iztro](https://github.com/SylarLong/iztro) v2.6.1 的移植。
iztro 的每个公开 API 在 Rust、Python、Go 三侧都有等价物，
三侧能力完全一致，形式各随语言习惯。
这一页写给从 iztro 迁移过来的人：名字对不上时来这里查。
逐个 API 的用法见各语言的 API 参考。
## 名字直接对得上的 [#名字直接对得上的]
| iztro | Rust | Python | Go |
| ------------------------- | ------------------------------ | -------------------------- | ----------------------------------- |
| `astro.bySolar` | `by_solar` | `astro.by_solar` | `BySolar` |
| `astro.byLunar` | `by_lunar` | `astro.by_lunar` | `ByLunar` |
| `chart.horoscope` | `chart.horoscope` | `chart.horoscope` | `Horoscope` |
| `chart.palace` | `chart.palace` | `chart.palace` | `Palace` / `PalaceByIndex` |
| `chart.surroundedPalaces` | `chart.surrounded_palaces` | `chart.surrounded_palaces` | `SurroundedPalaces` |
| `chart.flankingPalaces` | `chart.flanking_palaces` | `chart.flanking_palaces` | `FlankingPalaces` |
| `chart.decadalList` | `chart.decadal_list` | `chart.decadal_list` | `DecadalList` |
| `chart.yearlyList` | `chart.yearly_list` | `chart.yearly_list` | `YearlyList` / `YearlyListByPalace` |
| `chart.monthlyList` | `chart.monthly_list` | `chart.monthly_list` | `MonthlyList` |
| `palace.fliesTo` | `flies_to` | `flies_to` | `FliesTo` |
| `util.fixIndex` | `utils::fix_index` | `utils.fix_index` | `FixIndex` |
| `star.getMajorStar` | `star::query::get_major_stars` | `star.get_major_star` | `GetMajorStar` |
| `i18n.t` | `translate_key` | `i18n.translate` | `Translate` |
| `i18n.kot` | `key_of` | `i18n.key_of` | `KeyOf` |
其余同理：JS 的 camelCase 在 Rust / Python 下是 snake\_case，在 Go 下是 PascalCase。
## 换了形状的 [#换了形状的]
这几处不是照抄，因为照抄会把 JS 的限制一起搬过来。
### 排盘视角（天盘 / 地盘 / 人盘） [#排盘视角天盘--地盘--人盘]
iztro 把 `astroType` 放在 `astro.withOptions` 的选项对象上，
是因为它的 `astro.config()` 是全局单例、装不下按盘变化的值。
x-iztro 的配置本来就随每次排盘传入，因此 `astroType` 直接收进 `Config`，
两个排盘入口都能用，不必再记一个入口：
```python
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 缺少其他扩展手段的产物。三侧各按语言给出的答案实现同一能力，
都是编译期或加载期完成，不牺牲类型检查：
| | 做法 |
| ------ | -------------------------------------------------------------------- |
| Rust | 扩展 trait |
| Python | `x_iztro.plugin` 的 `load_plugin` / `load_plugins`，往 `Astrolabe` 类挂方法 |
| Go | 嵌入 `*Astrolabe`（Go 不允许给外部包的类型加方法，嵌入是语言给出的答案） |
写法见[扩展星盘](/zh/docs/guide/guides/plugins)。
### 反查译名时的消歧 [#反查译名时的消歧]
`kot(value, k)` 的第二个参数在三侧是独立入口：
`key_of_in`（Rust）、`key_of(text, key_filter)`（Python）、`KeyOfIn`（Go）。
取值与 iztro 逐例一致，包括 `horse`、`dragon`、`유시`（韩语的酉时）这类同形译名落到哪个标识。
iztro 的 `kot` 查不到会把入参吐回来；x-iztro 返回
`None`（Rust / Python）或空串（Go）。
迁移时如果依赖过「查不到就当作原值继续用」这个行为，这里要改。
## 不提供的 [#不提供的]
| iztro | 为什么不做 |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `astro.astrolabeBySolarDate` / `astrolabeByLunarDate` | iztro v2.0.5 起废弃的别名，与 `bySolar` / `byLunar` 同参同行为 |
| `star.initStars` | JS 里是返回 12 个空数组的工厂；三侧的类型系统本身就给出定长 12 的数组 |
| `util.fixEarthlyBranchIndex` | 与 `earthlyBranchIndexToPalaceIndex` 同义 |
| `palace.setAstrolabe` / `star.setPalace` / `star.setAstrolabe` | 建立对象间引用是内部行为，三侧在解析后自动完成 |
| `astro/analyzer` 模块 | 里面 11 个函数是宫位与三方四正方法的自由函数版（`hasStars` 即 `palace.has`），能力已由对象方法覆盖 |
| `calendar` 模块 | 在 iztro v2.5.8 里已是死代码——活的代码路径全部改走 `lunar-lite` 依赖，该模块也不在包的根导出里；v2.6.1 已把它从包中删除 |
| `i18n` 默认导出的 i18next 实例 | 不转手第三方库实例；翻译与反查由 `translate` / `key_of` 覆盖 |
| `Astrolabe.copyright` | iztro 自身的版权声明字符串 |
## 行为上要注意的几处 [#行为上要注意的几处]
### 自定义四化表与亮度表只收标识 [#自定义四化表与亮度表只收标识]
`Config` 的 `mutagens` / `brightness` 两张覆盖表**只接受语言无关标识**：
`"ziweiMaj"` 可以，`"紫微"` 不行 —— 收译名会让配置绑死在某种盘面语言上。
### 覆盖表长度严格校验 [#覆盖表长度严格校验]
四化表必须给满 4 项（禄权科忌），亮度表必须给满 12 项（第一项是寅宫），
多一项少一项都直接报 `invalid_argument`，不做补齐也不做截断。
见 [Config 详解](/zh/docs/guide/guides/config#自定义四化表与亮度表)。
### 覆盖表不回显在输出的 config 里 [#覆盖表不回显在输出的-config-里]
星盘上回显的 `config` 只有六个开关。覆盖表是排盘的输入，
放进 DTO 会破坏与 iztro 的字段契约，所以读回来是空的 —— 要留档自己存。
## 比 iztro 多的 [#比-iztro-多的]
### 格局判定（iztro 无对应 API） [#格局判定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 条总表见[格局](/zh/docs/guide/concepts/patterns)。
因为 iztro 没有对应实现，这部分没有金标数据，正确性由四层测试守着：
每条规则的单测、来源页 32 张示例盘的真实盘复现、tier1 那 1,560 张盘上的批量不变量检查，
以及三侧共读的输出快照。
### 知识包（iztro 无对应 API） [#知识包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 逐值一致，属性是门派说法。
见[知识包](/zh/docs/guide/guides/knowledge-pack)。
### 反推（iztro 无对应 API） [#反推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 变体）。
见[反推](/zh/docs/guide/guides/reverse)。
### 其余增补 [#其余增补]
* **语言无关标识**：星盘每个字段在译名之外同时给出 `*key` / `*Key`，
取值是 iztro 的 i18n key。判断逻辑因此不受盘面语言影响，
不必再反查译名。详见[标识体系](/zh/docs/guide/guides/keys)
* **语义化文本投影（to\_text）**：把星盘、运限、宫位或三方四正投影成自然语言文本，
喂大模型或直接给人读，见[语义化文本](/zh/docs/guide/guides/to-text)
* **入口前置校验**：非法日期、越界时辰等在入口返回错误而非 panic，
且带机器可读的分类码，见[错误处理](/zh/docs/guide/guides/errors)
* **自定义四化表与亮度表**：按标识整表替换内置数据，
见 [Config 详解](/zh/docs/guide/guides/config#自定义四化表与亮度表)
* **`all_keys`**：一次取全部 260 个可翻译标识
## 数值一致性 [#数值一致性]
功能对齐之外，排盘结果与 iztro **逐字段零差异**，由 716,314 例金标数据守着。
覆盖矩阵与验证方式见[准确性保证](/zh/docs/guide/about/accuracy)。
# 概览 (/zh/docs/rust)
crate 结构、类型体系与阅读本参考的方式。
x-iztro 的 Rust crate 是整个项目的核心，Python 与 Go 绑定都调用它。
这一栏是 Rust 侧的完整 API 参考——每个公开函数、类型与方法都有独立条目。
## 安装 [#安装]
```toml title="Cargo.toml"
[dependencies]
x-iztro = "0.3"
```
crate 无默认 feature，直接可用。`python` feature 仅供构建 PyO3 扩展时启用，普通依赖方不需要。
## 第一张盘 [#第一张盘]
```rust
use x_iztro::*;
fn main() -> Result<(), IztroError> {
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
println!("{} {}", chart.solar_date, chart.lunar_date);
// 2000-8-16 二〇〇〇年七月十七
let soul = chart.palace(Palace::Soul).unwrap();
println!("{}", soul.data().major_stars.iter().map(|s| s.name.as_str()).collect::>().join(" "));
// 紫微
Ok(())
}
```
## crate 结构 [#crate-结构]
| 模块 | 内容 | 本参考对应页 |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `x_iztro::astro` | 排盘、运限、宫位推算、轻量查询 | [排盘入口](/zh/docs/rust/astro)、[运限对象](/zh/docs/rust/horoscope)、[轻量查询](/zh/docs/rust/query) |
| `x_iztro::models` | `Astrolabe`、`PalaceData`、`Star`、`HoroscopeData` 与三个视图类型 | [星盘对象](/zh/docs/rust/astrolabe) 起的四页 |
| `x_iztro::star` | 安星：低层构件与按出生数据的入口 | [安星模块](/zh/docs/rust/star) |
| `x_iztro::data` | 枚举、常量、星耀与干支数据表 | [数据表](/zh/docs/rust/data) |
| `x_iztro::utils` | 索引换算、亮度与四化查表等工具函数 | [工具函数](/zh/docs/rust/util) |
| `x_iztro::i18n` | 六语言词表、`translate_*` 与双向查找 | [翻译](/zh/docs/rust/i18n) |
| `x_iztro::error` | `IztroError`、`BridgeError` | [错误处理](/zh/docs/rust/errors) |
| `x_iztro::text` | `astrolabe_to_text`、`horoscope_to_text`、`palace_to_text`、`surrounded_palaces_to_text`、`patterns_to_text` 及各自的 `_with` 形态，`TextOptions` | [排盘入口](/zh/docs/rust/astro#astrolabe_to_text--horoscope_to_text)、[TextOptions](/zh/docs/rust/astro#textoptions) |
| `x_iztro::dto` | 跨语言绑定共用的序列化 DTO | [数据结构](/zh/docs/guide/data-model) |
| `x_iztro::ffi` | C ABI 导出，供 Go/C 调用 | Rust 调用方不需要 |
绑定层共用的编组与分派（原 `x_iztro::bridge`）已收为 crate 内部，不在公开 API 面上。
`use x_iztro::*;` 拿到全部入口函数、数据结构、枚举与十二个 `translate_*`——
本参考里所有不带模块前缀的名字都在其中。带模块前缀的（`utils::fix_index`、
`star::query::get_major_stars`、`data::stars::get_star_info`、
`astro::palace::get_decadals_and_ages`）是低层构件，按路径调用。
## 两层 API [#两层-api]
同一件事在 crate 里往往有两个层次，选哪个取决于你手上有什么。
`by_solar` · `star::query::*` · `astro::query::*`
`star::location::*` · `star::decorative::*` · `astro::palace::*`
从出生数据到安星中间量（生效时辰、农历年月日、两套年干支、月索引、命身宫、五行局）
的推算收在 `astro::context`，收出生数据的那层调它一次，把结果喂给低层构件。
因此两层的结果永远一致，自己拼安星流程时也不必从日期重推一遍。
## 视图类型 [#视图类型]
Rust 的数据结构本身不持有星盘，因此 `PalaceData` 无法直接回答「我的对宫是谁」。
crate 用三个视图类型在查询入口处把数据与星盘绑在一起：
| 视图 | 由谁返回 | 解引用得到 | 额外能力 |
| ------------------ | ---------------------- | ---------------- | --------------- |
| `PalaceRef<'a>` | `chart.palace(...)` | `&PalaceData` | 对宫、三方四正、飞星、四化宫位 |
| `StarRef<'a>` | `chart.star(...)` | `&Star` | 所在宫、对宫、三方四正 |
| `HoroscopeRef<'a>` | `chart.horoscope(...)` | `&HoroscopeData` | 运限宫位查询不必再传星盘 |
```rust
let soul = chart.palace(Palace::Soul).unwrap();
soul.data().name; // 通过 data() 取底层字段
soul.opposite_palace(); // 视图独有：对宫
soul.flies_to(Palace::Wealth, &[Mutagen::Lu]);
```
三个视图都实现了 `Deref`，`soul.name` 与 `soul.data().name` 等价。
## 条目怎么读 [#条目怎么读]
每个 API 条目按固定八段组织：
**用途**
—— 一句话说清它做什么
**斗数含义**
—— 它在紫微斗数里对应什么概念（纯工程性的函数省略此段）
**签名**
—— 从源码原样摘出
**参数**
—— 名、类型、是否必填、默认值、说明
**返回值**
—— 类型与结构
**示例**
—— 可直接运行的片段
**输出**
—— 该示例的真实运行结果
**边界与陷阱**
—— 空值、越界、配置影响、与其他 API 的相互作用
示例统一用同一张盘：**2000 年 8 月 16 日寅时女命**（`("2000-8-16", 2, Gender::Female)`），
方便跨页对照。这张盘的完整数据见[数据结构](/zh/docs/guide/data-model)。
# 排盘入口 (/zh/docs/rust/astro)
by_solar、by_lunar、rearranged 与 JSON 便捷版本。
排盘是一切的起点：给出生日期、时辰、性别，得到一张 `Astrolabe`。
本页是四个排盘入口的完整参考。
收外部输入的入口（`by_solar`、`by_lunar`、两个 JSON 版本、`get_horoscope`）都返回
`Result`：日期格式与存在性、公历年份范围、时辰索引在核心层前置校验，非法输入返回
`IztroError` 而不是 panic。`rearranged` 同样返回 `Result`（守护反序列化来的非法
`raw_dates`）；入参全是枚举、无非法值的函数（`astrolabe_to_text` 等）直接返回结果。
错误类型见[错误处理](/zh/docs/rust/errors)。
***
## by\_solar [#by_solar]
**用途** 由公历日期排出本命盘。
**斗数含义** 紫微斗数以农历为算法基础，但绝大多数人只记得公历生日。
本函数先把公历转农历（含年干支、月干支、日干支、时干支四柱），再据此安星。
换年的时点受 `year_divide` 影响——正月初一与立春之间出生的人，两种配置会得到不同的年干支，
进而影响四化、命主身主与全部年系星。
**签名**
```rust
pub fn by_solar(
solar_date: &str,
time_index: u8,
gender: Gender,
fix_leap: bool,
language: Language,
config: Config,
) -> Result
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ---------- | -- | -- | ------------------------------------------------------ |
| `solar_date` | `&str` | 是 | — | 公历日期，格式 `YYYY-M-D`，月日不必补零。支持 1583–9999 年 |
| `time_index` | `u8` | 是 | — | 时辰索引 0–12。0 为早子时（00:00–01:00），12 为晚子时（23:00–24:00） |
| `gender` | `Gender` | 是 | — | `Gender::Male` 或 `Gender::Female`。决定大限顺逆与长生、博士十二神的排列方向 |
| `fix_leap` | `bool` | 是 | — | 是否调整农历闰月。为 `true` 时闰月十六日起按下月算（晚子时除外，见下） |
| `language` | `Language` | 是 | — | 输出语言，影响 DTO 中所有译名字段；`*_key` 标识字段不受影响 |
| `config` | `Config` | 是 | — | 排盘配置，六个开关加自定义表。取默认值用 `Config::default()` |
**返回值** `Astrolabe`——十二宫、四柱、命主身主、五行局俱全的完整星盘。字段清单见[数据结构](/zh/docs/guide/data-model)。
**示例**
```rust
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_*` 转成当前语言的文本。
**输出**
```text
2000-8-16 | 二〇〇〇年七月十七 | 庚辰 甲申 丙午 庚寅
狮子座 龙 木三局
命主 破军 身主 文昌
```
**边界与陷阱**
子时横跨午夜，分早子时（00:00–01:00，属当日）与晚子时（23:00–24:00，属次日）。
两者的日柱不同，紫微起宫也可能差一天，因此必须区分，索引才有 13 个。
`day_divide` 配置可以把晚子时改判为当日，见 [Config 详解](/zh/docs/guide/guides/config)。
进位要同时满足四个条件：该农历月确实是闰月、`fix_leap` 为 `true`、
农历日大于 15、且时辰索引不是 12（晚子时）。四者缺一，月索引就按本月算。
因此只有农历闰月下半月出生的人，`true` 与 `false` 会得到不同的月索引，
进而影响左辅右弼与全部月系星。
1582 年格里历改革留下了不存在的日期空洞，底层历法库在这些日期上会 panic。
crate 因此把公历支持范围收在 1583–9999，超出范围返回 `IztroError::InvalidDate`。
星盘上所有判断方法（`has`、`flies_to`、`with_mutagen` 等）都基于语言无关标识，
换语言排盘不会改变任何判断结果，只改变 `name` 一类展示字段。
***
## by\_lunar [#by_lunar]
**用途** 由农历日期排出本命盘。
**斗数含义** 农历日期是斗数的原生输入，跳过公历转换这一步。
知道自己农历生日的人直接用它，结果与用对应公历日期调 `by_solar` 完全一致。
**签名**
```rust
pub fn by_lunar(
lunar_date: &str,
time_index: u8,
gender: Gender,
leap: LeapMonth,
language: Language,
config: Config,
) -> Result
```
**参数**
除以下两项外，其余与 `by_solar` 相同；`by_solar` 的 `fix_leap` 在这里并入 `leap`。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ----------- | -- | -- | -------------------------------------------------------------------------------------------- |
| `lunar_date` | `&str` | 是 | — | 农历日期，格式 `YYYY-M-D`，月份写正数（闰月由下一参数标记） |
| `leap` | `LeapMonth` | 是 | — | `NotLeap` 非闰月；`Leap` 闰月、按闰月本身排；`LeapFixed` 闰月且十五之后视作次月（iztro `fixLeap`）。标为闰月但那年那月没有闰月时按普通月处理 |
**返回值** 同 `by_solar`。
**示例**
```rust
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);
```
**输出**
```text
2000-8-16
```
**边界与陷阱**
`leap` 标为闰月但那个月并非闰月时，按普通月排盘，不报错（与 iztro 一致）。
如果需要严格校验，调用前先自行确认该年该月确实有闰月。
`LeapMonth::from_flags(is_leap_month, fix_leap)` 可从 iztro 风格的两个布尔换算。
***
## rearranged [#rearranged]
**用途** 以指定干支为命宫重排本盘，返回新盘；原盘不变。
**斗数含义** 中州派把同一组出生数据看作三张盘：天盘以命宫干支起五行局，
地盘以身宫干支起，人盘以福德宫干支起。起局的干支一变，五行局就变，
紫微天府落点、十二宫名、长生十二神、大限小限随之全部重算。
本方法把这个能力放开到**任意干支**，不限于那三种。
**签名**
```rust
pub fn rearranged(
&self,
from_stem: HeavenlyStem,
from_branch: EarthlyBranch,
) -> Result
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | --------------- | -- | -- | ------ |
| `from_stem` | `HeavenlyStem` | 是 | — | 新命宫的天干 |
| `from_branch` | `EarthlyBranch` | 是 | — | 新命宫的地支 |
**返回值** `Result`。重算：命宫身宫、五行局、十四主星、十二宫名、
长生十二神、大限小限，以及随命宫挪位的天伤、天使、天才。沿用原盘：辅星、其余杂耀、
博士十二神、岁前与将前十二神。排盘入口产出的盘重排必成功；仅当 `raw_dates` 被
反序列化或手工构造成月表中不存在的农历月时返回 `IztroError::Internal`。
重排返回的盘上，`patterns() / patterns_with()`、运限查询与 to\_text 文本投影都按**重排后的布局**
计算——五行局、命宫与大限随重排起点变化；出生数据（日期与四柱）保持不变。
**示例**
```rust
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));
```
**输出**
```text
天盘 木三局 → 地盘 土五局
```
**边界与陷阱**
天盘、地盘、人盘用 `Config::default().with_astro_type(AstroType::Earth)` 直接排即可，
两个排盘入口都支持。`rearranged` 是为「从任意干支起盘」准备的。
跟着走：命宫地支、身宫地支、五行局、命主星。命主星按命宫地支查表，
命宫既已挪位，取值随之更新。
不动：身主星。它按**出生年支**查表，与命宫位置无关，重排不改变出生年。
`algorithm` 设为中州派时命主星也改按年支取，此时它同样不随重排变化。
`rearranged` 返回新盘，`&self` 只读。同一张原盘可以连续重排出多个视角，
互不干扰。
***
## by\_solar\_json / by\_lunar\_json [#by_solar_json--by_lunar_json]
**用途** 排盘并直接返回 DTO 的 JSON 字符串，省掉调用方自己序列化。
**签名**
```rust
pub fn by_solar_json(
solar_date: &str,
time_index: u8,
gender: Gender,
fix_leap: bool,
language: Language,
config: Config,
) -> Result
pub fn by_lunar_json(
lunar_date: &str,
time_index: u8,
gender: Gender,
leap: LeapMonth,
language: Language,
config: Config,
) -> Result
```
**参数** 与对应的排盘函数完全相同。
**返回值** `String`——[DTO](/zh/docs/guide/data-model) 的 JSON 序列化结果，
camelCase 键、值按 `language` 翻译，另带 `*Key` 语言无关标识。
**示例**
```rust
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"]);
```
**输出**
```text
"2000-8-16" "wealthPalace"
```
**边界与陷阱**
这两个函数只是 `by_solar(...)?.to_dto()` 加序列化的快捷方式。
Rust 侧要做进一步分析时用 `by_solar` 拿 `Astrolabe`，能用上全部查询方法；
只是要把结果丢给别的进程或前端时才用 JSON 版本。
***
## get\_horoscope [#get_horoscope]
**用途** 以某张本命盘为起点计算目标日期的运限。
**斗数含义** 运限是把大限、小限、流年、流月、流日、流时六个层级叠在本命盘上，
每一层各有自己的宫位起点、干支与流耀。
**签名**
```rust
pub fn get_horoscope(
astrolabe: &Astrolabe,
solar_date: &str,
time_index: u8,
language: Language,
) -> Result
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------------ | -- | -- | ----------------------------------- |
| `astrolabe` | `&Astrolabe` | 是 | — | 本命盘 |
| `solar_date` | `&str` | 是 | — | 目标公历日期，格式 `YYYY-M-D`，支持 1583–9999 年 |
| `time_index` | `u8` | 是 | — | 目标时辰索引 0–12 |
| `language` | `Language` | 是 | — | 输出语言 |
**返回值** `Result`。详见[运限对象](/zh/docs/rust/horoscope)。
**示例**
```rust
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);
```
**输出**
```text
大限宫位索引 2，流年干支 JiaChen
```
**边界与陷阱**
要连着做运限查询（取某层级的宫位、判断流耀）时，用星盘方法
`chart.horoscope(...)` 拿 `HoroscopeRef`——它同时持有本命盘，
查询不必再把星盘传进去。这里的自由函数只返回数据本身。
***
## astrolabe\_to\_text / horoscope\_to\_text [#astrolabe_to_text--horoscope_to_text]
**用途** 把星盘或运限投影成语义化文本——盘面事实的自然语言形态，
喂给大模型或直接给人读。与 `serde_json`（机器结构）、译文字段（展示）
是同一对象的三种投影。输出是 Markdown 子集（`#` 标题、`- 标签: 值` 列表、
`**粗体**` 与十二宫总览窄表），不渲染时源码同样可读。
**签名**（`x_iztro::text` 模块，全部从 crate 根 re-export；同模块另有
`palace_to_text` / `surrounded_palaces_to_text` / `patterns_to_text` 与各自的 `_with` 形态）
```rust
pub fn astrolabe_to_text(astrolabe: &Astrolabe, lang: Language) -> String
pub fn astrolabe_to_text_with(astrolabe: &Astrolabe, opts: &TextOptions, lang: Language) -> String
pub fn horoscope_to_text(
astrolabe: &Astrolabe,
horoscope: &HoroscopeData,
lang: Language,
) -> String
pub fn horoscope_to_text_with(
astrolabe: &Astrolabe,
horoscope: &HoroscopeData,
opts: &TextOptions,
lang: Language,
) -> String
```
按排盘语言输出的便捷方法：`Astrolabe::to_text()`、`HoroscopeRef::to_text()`、
`PalaceRef::to_text()`、`SurroundedPalaces::to_text()`，各自另有收 `&TextOptions` 的 `to_text_with`。
自由函数的 `lang` 可以与排盘语言不同：结构标签、星名、时辰、星座、干支、流耀全部按标识
以目标语言重翻，输出与用该语言排的盘逐字一致。
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ---------------- | ---------- | -- | -------------------------------------------------------------------------------- |
| `astrolabe` | `&Astrolabe` | 是 | — | 本命盘 |
| `horoscope` | `&HoroscopeData` | 是 | — | `get_horoscope` 的结果 |
| `opts` | `&TextOptions` | `_with` 必填 | — | 输出选项；无 `_with` 的两个即 `TextOptions::default()`，只输出事实。见 [TextOptions](#textoptions) |
| `lang` | `Language` | 是 | — | 输出语言，随之切换结构标签与星耀译名 |
**返回值** `String`，Markdown 文本。本命文本：标题、基本信息、十二宫总览表、格局、
从命宫起的十二宫详解；运限文本：大限（未起运为童限）、小限、流年、流月、流日、流时各一节，
各层带四化、格局与流耀，大限与流年展开十二宫表。带知识包时释义紧跟对应事实之后。
**示例**
```rust
use x_iztro::*;
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
print!("{}", chart.to_text());
```
**输出**
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座
- 五行局: 木三局 · 命主: 破军 · 身主: 文昌
- 命宫: 午 · 身宫: 戌 (官禄) · 来因宫: 辰 (夫妻)
- 生年四化: 太阳化禄→子女, 武曲化权→财帛, 太阴化科→仆役, 天同化忌→疾厄
## 十二宫总览
| 宫位 | 主星 | 辅星 | 大限 |
|---|---|---|---|
| **命宫** 午 | 紫微(庙) | 文曲(陷) | 3-12 |
| 兄弟 巳 | 天机(平) | — | 13-22 |
| 夫妻 辰 [来因宫] | 七杀(庙) | 右弼, 火星(陷) | 23-32 |
| 子女 卯 | 太阳(庙)化禄, 天梁(庙) | — | 33-42 |
| 财帛 寅 | 武曲(得)化权, 天相(庙) | 天马 | 43-52 |
| 疾厄 丑 | 天同(不)化忌, 巨门(不) | 天魁, 地劫 | 53-62 |
| 迁移 子 | 贪狼(旺) | 铃星(陷) | 63-72 |
| 仆役 亥 | 太阴(庙)化科 | — | 73-82 |
| 官禄 戌 [身宫] | 廉贞(利), 天府(庙) | 左辅 | 83-92 |
| 田宅 酉 | — | 地空, 擎羊(陷) | 93-102 |
| 福德 申 | 破军(得) | 文昌(得), 禄存 | 103-112 |
| 父母 未 | — | 天钺, 陀罗(庙) | 113-122 |
## 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
## 十二宫
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
（其余十一宫格式相同，此处从略）
```
完整输出与逐字段说明见[语义化文本](/zh/docs/guide/guides/to-text)。
这是 x-iztro 在 iztro 之外自加的功能，三语言均可用。
接入大模型的写法见[让 AI 解读命盘](/zh/docs/guide/guides/llm)。
***
## TextOptions [#textoptions]
**用途** to\_text 家族的输出选项：释义材料来源与格局判定口径。默认只输出盘面事实、按默认口径判格局；
给知识包后，每宫事实之后紧跟该宫星耀的释义
（同宫主星组合 `**A × B (同宫)**: ` 在前），格局列表之后紧跟格局释义（含 `成立条件: ` 段），
本命文本末尾附 `## 四化释义`，运限文本各层附该层流耀与格局的释义（跨层去重）。十二神不释义。
**签名**（`x_iztro::text`，从 crate 根 re-export）
```rust
#[derive(Debug, Clone, Copy, Default)]
pub struct TextOptions<'a> { /* 字段私有 */ }
impl<'a> TextOptions<'a> {
pub fn new() -> Self
pub fn knowledge(self, pack: &'a KnowledgePack) -> Self
pub fn pattern_config(self, config: &'a PatternConfig) -> Self
pub fn knowledge_pack(&self) -> Option<&'a KnowledgePack>
}
```
**方法**
| 方法 | 说明 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `new()` / `default()` | 只输出事实、默认格局口径的选项 |
| `knowledge(&pack)` | 按盘从 `pack` 取释义；`pack` 是内嵌默认包或合并覆盖包之后的自定义包，借用期须覆盖选项本身 |
| `pattern_config(&config)` | 格局按 `config` 口径判定，与 [`patterns_with`](/zh/docs/rust/patterns#patterns_with) 同一入参；同时作用于文本的格局节与格局释义。不设即 `PatternConfig::default()` |
| `knowledge_pack()` | 当前的释义材料来源；`None` 即只输出事实 |
`Copy`，同一份选项可传给任意多个 `to_text_with`。释义正文是包里的 Markdown 原文，
条目标题（星名、格局名、四化名）按输出语言翻译。取材规则与
[`KnowledgePack::for_astrolabe`](/zh/docs/rust/knowledge#for_astrolabe--for_horoscope) 相同，
插入位置与去重规则见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let opts = TextOptions::new().knowledge(pack);
let plain = chart.to_text();
let noted = chart.to_text_with(&opts);
println!("{} {}", plain.chars().count(), noted.chars().count());
assert!(plain.lines().all(|l| noted.contains(l)));
let positional = PatternConfig { brightness_source: BrightnessSource::Positional, ..PatternConfig::default() };
let by_position = chart.to_text_with(&opts.pattern_config(&positional)); // 格局节与格局释义都按该口径
```
**输出**
```text
3389 20767
```
内嵌默认包只有 zh-CN，其他语言 `KnowledgePack::builtin` 返回 `None`；英文盘要带释义须显式传一份包，
包的语言不受盘语言限制——英文盘配中文包得到英文标题、中文正文。
# 星盘对象 (/zh/docs/rust/astrolabe)
Astrolabe 的字段、定位方法，以及三方四正与夹宫。
`Astrolabe` 是排盘的产物，也是一切查询的入口。它持有十二宫的全部数据，
以及四柱、命主身主、五行局这些盘级信息。
```rust
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
```
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
换成别的语言只改这些展示串，`*_key` 标识与所有判断方法的结果不变。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| -------------- | -------- | ------------------------- |
| `gender` | `Gender` | 性别 |
| `solar_date` | `String` | 公历日期，与入参一致 |
| `lunar_date` | `String` | 农历日期的中文写法，如「二〇〇〇年七月十七」 |
| `chinese_date` | `String` | 四柱展示串，如「庚辰 甲申 丙午 庚寅」 |
| `time` | `String` | 时辰名，如「寅时」 |
| `time_range` | `String` | 时辰对应的钟点区间，如「03:00\~05:00」 |
| `sign` | `String` | 星座，按公历日期 |
| `zodiac` | `String` | 生肖，按年支 |
展示字段随 `language` 翻译。要做判断请用下一组的标识字段。
| 字段 | 类型 | 说明 |
| ------------------------------- | ------------------- | ----------------------- |
| `sign_key` | `String` | 星座标识，`aries` … `pisces` |
| `zodiac_key` | `String` | 生肖标识，`rat` … `pig` |
| `earthly_branch_of_soul_palace` | `EarthlyBranch` | 命宫地支 |
| `earthly_branch_of_body_palace` | `EarthlyBranch` | 身宫地支 |
| `soul` | `StarKey` | 命主星 |
| `body` | `StarKey` | 身主星 |
| `five_elements_class` | `FiveElementsClass` | 五行局，决定大限起运岁数与紫微起宫 |
这些是强类型枚举，与语言无关，可直接比较。
| 字段 | 类型 | 说明 |
| ----------- | ------------------ | ------------------------ |
| `palaces` | `[PalaceData; 12]` | 十二宫，定长数组，索引 0 为寅宫、11 为丑宫 |
| `raw_dates` | `RawDates` | 结构化的农历生日与四柱干支枚举 |
`palaces` 的索引是**宫位索引**而非宫名顺序：`palaces[0]` 永远是寅宫，
命宫可能落在其中任何一格。取命宫用 `chart.palace(Palace::Soul)`。
`raw_dates` 是 `lunar_date` / `chinese_date` 两个展示串的数据形式，
要做日期运算或按干支查表时用它，不必解析中文串：
```rust
pub struct RawDates {
pub lunar_date: RawLunarDate,
pub chinese_date: RawChineseDate,
}
pub struct RawLunarDate {
pub lunar_year: i64, // 农历年
pub lunar_month: u32, // 农历月 1–12，是否闰月看 is_leap
pub lunar_day: u32, // 农历日 1–30
pub is_leap: bool, // 是否闰月
}
pub struct RawChineseDate {
pub yearly: (HeavenlyStem, EarthlyBranch), // 年柱
pub monthly: (HeavenlyStem, EarthlyBranch), // 月柱
pub daily: (HeavenlyStem, EarthlyBranch), // 日柱
pub hourly: (HeavenlyStem, EarthlyBranch), // 时柱
}
```
三个类型都在 crate 根重导出，`use x_iztro::*;` 即可用。
| 字段 | 类型 | 说明 |
| ------------ | ---------- | ------------------------------------ |
| `time_index` | `u8` | 出生时辰索引，即使 `day_divide` 把晚子时改判当日也保留原值 |
| `fix_leap` | `bool` | 排盘时是否修正闰月 |
| `language` | `Language` | 输出语言 |
| `config` | `Config` | 排盘配置 |
运限与 Prompt 从这四项重新发起计算，因此不必再传一遍排盘参数。
***
## palace [#palace]
**用途** 按索引、宫名、身宫或来因宫取一宫。
**斗数含义** 十二宫是斗数的骨架。命宫定下后，其余十一宫按固定顺序逆时针排开。
「身宫」是十二宫之一同时被标记的那一宫，代表后天着力处；
「来因宫」是宫干与生年干相同的那一宫，代表事情的起因。
**签名**
```rust
pub fn palace(&self, target: impl Into) -> Option>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ------------------------- | -- | -- | ------- |
| `target` | `impl Into` | 是 | — | 四种写法见下表 |
`PalaceTarget` 的四个变体都有 `From` 实现，调用时直接写值即可：
| 写法 | 例子 | 含义 |
| --- | -------------------------------------- | --------------- |
| 索引 | `chart.palace(0)` | 宫位索引 0–11，0 为寅宫 |
| 宫名 | `chart.palace(Palace::Soul)` | 十二宫名之一 |
| 身宫 | `chart.palace(PalaceTarget::Body)` | 带身宫标记的那一宫 |
| 来因宫 | `chart.palace(PalaceTarget::Original)` | 宫干与生年干相同的那一宫 |
**返回值** `Option>`。索引越界返回 `None`；宫名、身宫、来因宫三种写法在任何一张盘上都能定位到，不会是 `None`。
**示例**
```rust
let zh = Language::ZhCN;
let soul = chart.palace(Palace::Soul).unwrap();
println!("{} {}{}", translate_palace(soul.name, zh),
translate_heavenly_stem(soul.heavenly_stem, zh),
translate_earthly_branch(soul.earthly_branch, zh));
let body = chart.palace(PalaceTarget::Body).unwrap();
println!("身宫落在 {}", translate_palace(body.name, zh));
let original = chart.palace(PalaceTarget::Original).unwrap();
println!("来因宫是 {}", translate_palace(original.name, zh));
println!("寅宫是 {}", translate_palace(chart.palace(0).unwrap().name, zh));
```
`PalaceData::name` 的类型是 `Palace` 枚举而非字符串，不能直接用 `{}` 打印——
枚举是语言无关标识，展示时经 `translate_palace` 转成当前语言的文本。
`heavenly_stem`、`earthly_branch`、`five_elements_class` 等字段同理。
**输出**
```text
命宫 壬午
身宫落在 官禄
来因宫是 夫妻
寅宫是 财帛
```
**边界与陷阱**
来因宫要求宫干与生年干相同，且该宫不在子、丑二宫。
十二宫的天干由五虎遁从寅宫起排，寅到酉这十宫刚好把十天干各走一遍，
子、丑两宫是第十一、十二格，重复了寅、卯的天干——正因为重复才被排除在外。
于是生年干在寅到酉之间必然命中且只命中一次：任何一张盘上来因宫都存在，且唯一。
十二宫名在一张盘上各出现一次，因此按宫名查找必然唯一。
身宫是**标记**不是宫名——身宫同时也是十二宫中的某一宫（例中的官禄宫）。
来因宫同理，例中落在夫妻宫。
***
## star [#star]
**用途** 按标识找到一颗星，得到能回溯所在宫的视图。
**签名**
```rust
pub fn star(&self, key: StarKey) -> Option>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----- | --------- | -- | -- | -------------------------- |
| `key` | `StarKey` | 是 | — | 星耀标识，如 `StarKey::ZiweiMaj` |
**返回值** `Option>`。该星不在这张盘上时返回 `None`。
**示例**
```rust
let zh = Language::ZhCN;
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
println!("{} 在 {}", ziwei.name, translate_palace(ziwei.palace().name, zh));
println!("对宫是 {}", translate_palace(ziwei.opposite_palace().name, zh));
println!("亮度 {:?} 四化 {:?}", ziwei.brightness, ziwei.mutagen);
```
`Star::name` 是 `String`（排盘时已按语言翻译好），可以直接打印；
宫名 `PalaceData::name` 是枚举，要经 `translate_palace`。
**输出**
```text
紫微 在 命宫
对宫是 迁移
亮度 Some(Miao) 四化 None
```
**边界与陷阱**
只在主星、辅星、杂耀三组里查找。长生十二神、博士十二神、岁前与将前十二神
是每宫一个的标记而非星耀列表，用 `palace.changsheng12` 一类字段直接取。
***
## surrounded\_palaces [#surrounded_palaces]
**用途** 取目标宫的三方四正。
**斗数含义** 三方四正是斗数最常用的取象范围：本宫、对宫（本宫 +6）、
官禄位（本宫 +4）、财帛位（本宫 +8）。四个宫合起来看，而不只看本宫，
是因为对宫与三合宫的星耀同样作用于本宫的事。
**签名**
```rust
pub fn surrounded_palaces(&self, target: impl Into) -> Option>
```
**参数** 同 `palace`，四种定位写法都支持。
**返回值** `Option>`，含 `target` / `opposite` / `wealth` / `career`
四个 `&PalaceData`（不是 `PalaceRef`，字段可直接读，但没有对宫、飞星那些需要星盘上下文的方法）。
判断方法见[三方四正](/zh/docs/rust/surpalaces)。
**示例**
```rust
let zh = Language::ZhCN;
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();
println!("{} / {} / {} / {}",
translate_palace(sp.target.name, zh), translate_palace(sp.opposite.name, zh),
translate_palace(sp.wealth.name, zh), translate_palace(sp.career.name, zh));
println!("三方四正见紫微: {}", sp.have(&[StarKey::ZiweiMaj]));
```
**输出**
```text
命宫 / 迁移 / 财帛 / 官禄
三方四正见紫微: true
```
***
## is\_surrounded / is\_surrounded\_one\_of / not\_surrounded [#is_surrounded--is_surrounded_one_of--not_surrounded]
**用途** 直接在星盘上判断某宫的三方四正里有没有指定星耀，省去先取三方四正的一步。
**签名**
```rust
pub fn is_surrounded(&self, target: impl Into, stars: &[StarKey]) -> bool
pub fn is_surrounded_one_of(&self, target: impl Into, stars: &[StarKey]) -> bool
pub fn not_surrounded(&self, target: impl Into, stars: &[StarKey]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ------------------------- | -- | -- | -------------- |
| `target` | `impl Into` | 是 | — | 定位方式同 `palace` |
| `stars` | `&[StarKey]` | 是 | — | 星耀标识列表 |
**返回值**
| 方法 | 语义 |
| ---------------------- | ----------------- |
| `is_surrounded` | 列表中**每一颗**都在三方四正里 |
| `is_surrounded_one_of` | 列表中**至少一颗**在三方四正里 |
| `not_surrounded` | 列表中**一颗都不在**三方四正里 |
**示例**
```rust
use x_iztro::StarKey::*;
println!("{}", chart.is_surrounded(Palace::Soul, &[ZiweiMaj, TianxiangMaj]));
println!("{}", chart.is_surrounded_one_of(Palace::Soul, &[QishaMaj, PojunMaj]));
println!("{}", chart.not_surrounded(Palace::Soul, &[HuoxingMin]));
```
**输出**
```text
true
false
true
```
命宫只坐紫微，天相在三方之一的财帛宫，因此第一行为 `true`；
七杀与破军都不在这四宫内，第二行为 `false`。
**边界与陷阱**
`stars` 传空切片时，`is_surrounded` 与 `not_surrounded` 返回 `true`
（「所有元素都满足」与「没有元素不满足」对空集都成立），
`is_surrounded_one_of` 返回 `false`。调用前先确认列表非空。
***
## flanking\_palaces [#flanking_palaces]
**用途** 取目标宫的夹宫：盘上紧邻它前后的两宫。
**斗数含义** 「羊陀夹忌」「日月夹命」这类说法看的就是夹宫。
夹宫与三方四正是两条不重叠的线索：三方四正问的是同一组能量彼此呼应，
夹宫问的是这一宫左右两侧的处境。
**签名**
```rust
pub fn flanking_palaces(&self, target: impl Into) -> Option>
```
**参数** 同 `palace`，四种定位写法都支持。
**返回值** `Option>`，两个字段：
| 字段 | 相对目标宫 | 类型 | 说明 |
| ---------- | ----- | ------------- | --- |
| `previous` | -1 | `&PalaceData` | 前一宫 |
| `next` | +1 | `&PalaceData` | 后一宫 |
十二宫首尾相连，索引对 12 回绕：第 0 宫的前一宫是第 11 宫。
另有 `astrolabe()` 取回两宫所属的星盘。
五个判断方法与[三方四正](/zh/docs/rust/surpalaces)同名同义，只是作用范围换成这两宫：
| 方法 | 语义 |
| ----------------------------------- | ------------- |
| `have(&[StarKey]) -> bool` | 两宫合起来含列表中每一颗 |
| `not_have(&[StarKey]) -> bool` | 两宫一颗都不含 |
| `have_one_of(&[StarKey]) -> bool` | 两宫合起来至少含一颗 |
| `have_mutagen(Mutagen) -> bool` | 两宫中有任一宫带该生年四化 |
| `not_have_mutagen(Mutagen) -> bool` | 两宫都不带 |
**示例**
```rust
let zh = Language::ZhCN;
let f = chart.flanking_palaces(Palace::Soul).unwrap();
println!("{} / {}", translate_palace(f.previous.name, zh), translate_palace(f.next.name, zh));
println!("{}", f.have(&[StarKey::TianjiMaj, StarKey::TuoluoMin]));
println!("{}", f.have_one_of(&[StarKey::HuoxingMin]));
let w = chart.flanking_palaces(Palace::Wealth).unwrap();
println!("{} / {}", translate_palace(w.previous.name, zh), translate_palace(w.next.name, zh));
println!("{} {}", w.have_mutagen(Mutagen::Lu), w.have_mutagen(Mutagen::Ji));
```
**输出**
```text
兄弟 / 父母
true
false
疾厄 / 子女
true true
```
命宫在午，夹它的是兄弟（巳）与父母（未）。天机坐兄弟、陀罗坐父母，分处两宫，
`have` 仍然成立；火星坐夫妻，不在这两宫之内，因此 `have_one_of` 为 `false`。
财帛在寅，夹它的疾厄坐天同、子女坐太阳，这张盘生年干庚使太阳化禄、天同化忌，
于是禄与忌两问都为 `true`。
**边界与陷阱**
`have(&[A, B])` 问的是「A 和 B 都出现在这两宫里」，不要求它们同在其中一宫。
要单看某一侧，直接对 `f.previous` / `f.next` 调宫位的
[`has`](/zh/docs/rust/palace#has--not_have--has_one_of)。
索引对 12 回绕，十二宫每一宫都有完整的前后两宫。
`have` 与 `not_have` 在空列表下返回 `true`，`have_one_of` 返回 `false`。
***
## horoscope / horoscope\_now [#horoscope--horoscope_now]
**用途** 以本盘为起点计算目标日期的运限。
**签名**
```rust
pub fn horoscope(&self, target_date: &str, target_time_index: u8) -> Result, IztroError>
pub fn horoscope_now(&self) -> Result, IztroError>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------ | -- | -- | -------------------- |
| `target_date` | `&str` | 是 | — | 目标公历日期，格式 `YYYY-M-D` |
| `target_time_index` | `u8` | 是 | — | 目标时辰索引 0–12，决定流时 |
`horoscope_now` 取本地时钟的当前日期与当前时辰，无参数。
**返回值** `HoroscopeRef<'_>`——持有本盘的运限视图，六个层级的宫位查询不必再传星盘。
详见[运限对象](/zh/docs/rust/horoscope)。
**示例**
```rust
let zh = Language::ZhCN;
let h = chart.horoscope("2025-6-1", 0)?;
println!("大限 {}{}",
translate_heavenly_stem(h.decadal.heavenly_stem, zh),
translate_earthly_branch(h.decadal.earthly_branch, zh));
println!("流年 {}{}",
translate_heavenly_stem(h.yearly.heavenly_stem, zh),
translate_earthly_branch(h.yearly.earthly_branch, zh));
```
`decadal` / `monthly` / `daily` / `hourly` 是 `HoroscopeItem`，干支直接读；
`yearly` 与 `age` 各自多带一项自己的数据（通用字段收在 `base` 里），
但两者都实现了 `Deref`，`h.yearly.heavenly_stem` 同样直接可读。
**输出**
```text
大限 庚辰
流年 乙巳
```
***
## to\_text [#to_text]
**用途** 星盘的语义化文本：面向语言模型与人的完整描述，Markdown 子集。
**签名**
```rust
pub fn to_text(&self) -> String
```
按排盘语言输出；要指定语言用自由函数 `text::astrolabe_to_text(astrolabe, lang)`——
`lang` 可以与排盘语言不同，全部字段按标识以目标语言重翻。
单宫与三方四正见 `PalaceRef::to_text()` / `SurroundedPalaces::to_text()`。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
**示例**
```rust
for line in chart.to_text().lines().take(5) {
println!("{line}");
}
```
**输出**
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座
```
***
## to\_text\_with [#to_text_with]
**用途** `to_text` 的同一份文本，按 [`TextOptions`](/zh/docs/rust/astro#textoptions) 附释义：
格局列表之后紧跟格局释义，每宫事实之后紧跟该宫星耀释义（同宫主星组合在前），
文末附 `## 四化释义`。事实部分与 `to_text` 逐行相同。
**签名**
```rust
pub fn to_text_with(&self, opts: &TextOptions) -> String
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | -------------- | -- | -- | ------------------------------------------------------------------------------------- |
| `opts` | `&TextOptions` | 是 | — | 输出选项；`TextOptions::new().knowledge(pack)` 带释义，`TextOptions::default()` 与 `to_text` 等价 |
按排盘语言输出；要指定语言用自由函数 `text::astrolabe_to_text_with(astrolabe, opts, lang)`。
条目标题按 `lang` 翻译，正文是包里的原文。取材规则与
[`KnowledgePack::for_astrolabe`](/zh/docs/rust/knowledge#for_astrolabe--for_horoscope) 相同，
插入位置见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let text = chart.to_text_with(&TextOptions::new().knowledge(pack));
println!("{} {}", chart.to_text().chars().count(), text.chars().count());
println!("{}", text.lines().filter(|l| l.starts_with("## ")).collect::>().join(" "));
```
**输出**
```text
3389 20767
## 基本信息 ## 十二宫总览 ## 格局 ## 十二宫 ## 四化释义
```
***
## to\_dto [#to_dto]
**用途** 把星盘转成与 JS iztro 字段契约一致的序列化结构。
**签名**
```rust
pub fn to_dto(&self) -> AstrolabeDto
```
**返回值** `x_iztro::dto::AstrolabeDto`——camelCase 键、值按**排盘语言**翻译，
另带 `*Key` 语言无关标识与排盘上下文（`genderKey` / `timeIndex` / `fixLeap` / `language` / `config`）。
字段清单见[数据结构](/zh/docs/guide/data-model)。
**示例**
```rust
let dto = chart.to_dto();
let json = serde_json::to_string(&dto)?;
let v: serde_json::Value = serde_json::from_str(&json)?;
println!("{} {}", v["solarDate"], v["palaces"][4]["nameKey"]);
println!("{}", v["config"]["yearDivide"]);
```
**输出**
```text
"2000-8-16" "soulPalace"
"normal"
```
**边界与陷阱**
DTO 是给跨语言绑定与前端用的。Rust 侧做分析请直接用 `Astrolabe`——
它有全部查询方法，DTO 只有数据。想一步拿到 JSON 字符串用
[`by_solar_json`](/zh/docs/rust/astro#by_solar_json--by_lunar_json)。
`Config` 的 `overrides`（自定义四化与亮度表）不进 DTO：它是排盘输入而非结果，
回显会破坏与 JS iztro 的字段契约。
# 宫位对象 (/zh/docs/rust/palace)
PalaceData 的字段，以及星耀判断、空宫判断与飞星族的全部方法。
宫位是斗数分析的主战场。数据本身是 `PalaceData`，`chart.palace(...)` 返回的是
`PalaceRef`——同一份数据外加一个指回星盘的引用。
| | `PalaceData` | `PalaceRef<'a>` |
| ---- | ------------------------------------------------------- | ------------------------------------------------------------------------- |
| 从哪来 | `chart.palaces[i]`、`sp.target` 等字段 | `chart.palace(...)`、`star.palace()`、`sp` 之外的查询入口 |
| 字段 | 全部 | 经 `Deref` 全部可读，`data()` 取到底层 |
| 判断方法 | `has` / `is_empty` / `flies_to` 一族（目标宫要传 `&PalaceData`） | 同名方法，目标宫可直接写索引或宫名 |
| 独有 | — | `opposite_palace` / `surrounded_palaces` / `mutaged_places` / `astrolabe` |
本页条目按 `PalaceRef` 的形式给签名；`PalaceData` 上的同名方法只差在飞星族的
目标宫参数类型（`&PalaceData` 而非 `impl Into`）。
```rust
let soul = chart.palace(Palace::Soul).unwrap();
soul.name; // 经 Deref 直接取字段
soul.opposite_palace(); // 视图独有
```
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
`name` 等枚举字段本身与语言无关，展示时才经 `translate_*` 转成文本。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| -------------------- | ----------------------------- | ----------------------------- |
| `index` | `usize` | 宫位索引 0–11，0 为寅宫 |
| `name` | `Palace` | 宫名 |
| `is_body_palace` | `bool` | 是否身宫 |
| `is_original_palace` | `bool` | 是否来因宫（宫干与年干相同且不在子丑二宫） |
| `heavenly_stem` | `HeavenlyStem` | 宫干，决定本宫飞出的四化 |
| `earthly_branch` | `EarthlyBranch` | 宫支，由索引固定：0 为寅、11 为丑 |
| `major_stars` | `Vec` | 十四主星中落在本宫的，按安放顺序 |
| `minor_stars` | `Vec` | 十四辅星中落在本宫的 |
| `adjective_stars` | `Vec` | 杂耀 |
| `changsheng12` | `StarKey` | 长生十二神，每宫恰好一个 |
| `boshi12` | `StarKey` | 博士十二神 |
| `jiangqian12` | `StarKey` | 将前十二神 |
| `suiqian12` | `StarKey` | 岁前十二神 |
| `decadal` | `Decadal` | 大限：岁数区间与宫干支 |
| `ages` | `Vec` | 小限经过本宫的虚岁列表 |
| `overrides` | `Option>` | 排盘时生效的自定义四化与亮度表；未自定义时为 `None` |
主星、辅星、杂耀是**列表**，一宫可以有零到多颗。
长生、博士、将前、岁前十二神是**每宫恰好一个**的标记，十二宫刚好排满一轮，
因此是单值字段而不是列表。
`overrides` 携带的是排盘配置里的自定义表——飞星族方法要按宫干查四化，
自定义表可能改写了某个天干的四化，因此宫位得随身带着它。
它不参与序列化，DTO 与 JSON 输出里都没有这一项。
***
## has / not\_have / has\_one\_of [#has--not_have--has_one_of]
**用途** 判断本宫坐了哪些星。
**斗数含义** 星耀落宫是斗数的基本盘面信息。「命宫坐紫微天相」即
`has(&[ZiweiMaj, TianxiangMaj])`。查找范围覆盖主星、辅星、杂耀三组。
**签名**
```rust
pub fn has(&self, stars: &[StarKey]) -> bool
pub fn not_have(&self, stars: &[StarKey]) -> bool
pub fn has_one_of(&self, stars: &[StarKey]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ------------ | -- | -- | ------ |
| `stars` | `&[StarKey]` | 是 | — | 星耀标识列表 |
**返回值**
| 方法 | 语义 |
| ------------ | ---------- |
| `has` | 列表中每一颗都在本宫 |
| `not_have` | 列表中一颗都不在本宫 |
| `has_one_of` | 列表中至少一颗在本宫 |
**示例**
```rust
use x_iztro::StarKey::*;
let soul = chart.palace(Palace::Soul).unwrap();
println!("{}", soul.has(&[ZiweiMaj, TianxiangMaj]));
println!("{}", soul.has_one_of(&[QishaMaj, ZiweiMaj]));
println!("{}", soul.not_have(&[HuoxingMin, LingxingMin]));
```
**输出**
```text
false
true
true
```
这张盘的命宫只坐紫微，天相落在财帛宫，因此要求两颗都在的 `has` 为 `false`。
**边界与陷阱**
空列表下 `has` 与 `not_have` 返回 `true`，`has_one_of` 返回 `false`。
***
## has\_mutagen / not\_have\_mutagen [#has_mutagen--not_have_mutagen]
**用途** 判断本宫有没有某种四化。
**斗数含义** 本命四化由**生年干**决定，标记打在对应的星上。
一宫「有化禄」意味着这宫里坐着的某颗星被生年干化了禄。
注意这与飞星不同——飞星看的是宫干，本处看的是星上已有的标记。
**签名**
```rust
pub fn has_mutagen(&self, mutagen: Mutagen) -> bool
pub fn not_have_mutagen(&self, mutagen: Mutagen) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | --------- | -- | -- | ------------------------------ |
| `mutagen` | `Mutagen` | 是 | — | `Lu` / `Quan` / `Ke` / `Ji` 之一 |
**返回值** `bool`。只扫描 `major_stars` 与 `minor_stars`，**不看杂耀**。
**示例**
```rust
let children = chart.palace(Palace::Children).unwrap();
println!("子女宫有化禄: {}", children.has_mutagen(Mutagen::Lu));
println!("子女宫无化忌: {}", children.not_have_mutagen(Mutagen::Ji));
```
**输出**
```text
子女宫有化禄: true
子女宫无化忌: true
```
**边界与陷阱**
`has_mutagen` 只看主星与辅星上的四化标记，杂耀即使带标记也不计入
（复刻 iztro 的行为）。要连杂耀一起看，自己遍历 `adjective_stars` 的 `mutagen` 字段。
生年四化只会落在十四主星与部分辅星上，因此实际盘面上两种口径通常没有差别。
***
## is\_empty / is\_empty\_excluding [#is_empty--is_empty_excluding]
**用途** 判断本宫是否空宫。
**斗数含义** 「空宫」指没有十四主星坐守的宫。空宫要借对宫主星来看，
是斗数里一个很常见的判断分支。辅星与杂耀默认不影响空宫的成立。
**签名**
```rust
pub fn is_empty(&self) -> bool
pub fn is_empty_excluding(&self, exclude_stars: &[StarKey]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------------ | -- | -- | ---------------------------------- |
| `exclude_stars` | `&[StarKey]` | 是 | — | 追加计入的星耀：本宫无主星、但坐了其中任一颗时，同样**不算**空宫 |
**返回值** `bool`。判定顺序是：先看有无主星，有则不空；再看 `exclude_stars`，命中则不空；都不满足才是空宫。
**示例**
```rust
let parents = chart.palace(Palace::Parents).unwrap();
println!("父母宫空宫: {}", parents.is_empty());
let friends = chart.palace(Palace::Friends).unwrap();
println!("仆役宫空宫: {}", friends.is_empty());
// 父母宫无主星，但坐了陀罗——把陀罗也计入后就不算空宫
println!("父母宫计入陀罗后: {}", parents.is_empty_excluding(&[StarKey::TuoluoMin]));
```
**输出**
```text
父母宫空宫: true
仆役宫空宫: false
父母宫计入陀罗后: false
```
这张盘只有父母、田宅两宫无主星。仆役宫坐太阴，因此不算空宫。
**边界与陷阱**
`exclude_stars` 不是「判断时忽略这些星」，而是「这些星也算数」。
本宫已有主星时它完全不起作用——有主星就直接不是空宫，不再看这个列表。
`is_empty` 只检查 `major_stars`。一宫辅星杂耀满座但没有主星，仍然是空宫。
要把某些辅星也当作「填实」，把它们传进 `is_empty_excluding`。
***
## flies\_to / flies\_one\_of\_to / not\_fly\_to [#flies_to--flies_one_of_to--not_fly_to]
**用途** 判断本宫宫干的四化是否飞入目标宫。
**斗数含义** 飞星派的核心手法。每个宫位有自己的宫干，宫干按四化表决定
哪四颗星化禄、权、科、忌。若被化的那颗星恰好坐在目标宫，就叫「本宫化 X 入目标宫」。
「命宫化禄入财帛」表达的是命宫这件事的顺遂落在财帛上。
**签名**
```rust
pub fn flies_to(&self, target: impl Into, mutagens: &[Mutagen]) -> bool
pub fn flies_one_of_to(&self, target: impl Into, mutagens: &[Mutagen]) -> bool
pub fn not_fly_to(&self, target: impl Into, mutagens: &[Mutagen]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------------------------- | -- | -- | -------------------------- |
| `target` | `impl Into` | 是 | — | 目标宫，索引 / 宫名 / 身宫 / 来因宫四种写法 |
| `mutagens` | `&[Mutagen]` | 是 | — | 要检查的四化 |
**返回值**
| 方法 | 语义 |
| ----------------- | ------------------ |
| `flies_to` | 列出的四化**全部**飞入目标宫 |
| `flies_one_of_to` | 列出的四化**至少一个**飞入目标宫 |
| `not_fly_to` | 列出的四化**一个都不**飞入目标宫 |
**示例**
```rust
let soul = chart.palace(Palace::Soul).unwrap();
println!("命宫化禄入财帛: {}", soul.flies_to(Palace::Wealth, &[Mutagen::Lu]));
println!("命宫化禄或忌入迁移: {}", soul.flies_one_of_to(Palace::Surface, &[Mutagen::Lu, Mutagen::Ji]));
println!("命宫不化权入子女: {}", soul.not_fly_to(Palace::Children, &[Mutagen::Quan]));
```
**输出**
```text
命宫化禄入财帛: false
命宫化禄或忌入迁移: false
命宫不化权入子女: true
```
**边界与陷阱**
`mutagens` 传空切片时 `flies_to` 返回 `false`，
`flies_one_of_to` 与 `not_fly_to` 返回 `true`。
这与「空集上全称命题为真」的直觉相反，但复刻的是 iztro 的行为：
`flies_to` 先算出要找的星，一颗都没有就直接判假。传空通常是调用方的疏漏，
先确认列表非空。
目标宫写成越界索引之外的无效值时，`PalaceRef` 上的三个方法一律返回 `false`，
包括语义上「否定」的 `not_fly_to`——定位失败不等于「没飞进去」。
索引会先对 12 取模，因此写 `12`、`-1` 这类值不算定位失败。
`Config::with_mutagens` 换掉某个天干的四化表后，宫干落在该天干的宫飞出的星随之改变。
飞星族方法读的是排盘时生效的表，不是内置默认表。
目标宫写成本宫时，语义上是「自化」。此时用 `self_mutaged` 一族更直观。
***
## self\_mutaged / self\_mutaged\_one\_of / not\_self\_mutaged [#self_mutaged--self_mutaged_one_of--not_self_mutaged]
**用途** 判断本宫是否自化。
**斗数含义** 自化指本宫宫干化出的星恰好就坐在本宫。
含义上是「自己把自己的能量释放掉」，与飞入他宫的定向作用不同。
**签名**
```rust
pub fn self_mutaged(&self, mutagens: &[Mutagen]) -> bool
pub fn self_mutaged_one_of(&self, mutagens: &[Mutagen]) -> bool
pub fn not_self_mutaged(&self, mutagens: &[Mutagen]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------------ | -- | -- | ------------------- |
| `mutagens` | `&[Mutagen]` | 是 | — | 要检查的四化；传空切片表示「四化全部」 |
**返回值**
| 方法 | 语义 |
| --------------------- | ----------------------- |
| `self_mutaged` | 列出的四化全部自化 |
| `self_mutaged_one_of` | 列出的四化至少一个自化；列表为空时检查全部四化 |
| `not_self_mutaged` | 列出的四化一个都不自化；列表为空时检查全部四化 |
**示例**
```rust
let career = chart.palace(Palace::Career).unwrap();
println!("官禄宫自化禄: {}", career.self_mutaged(&[Mutagen::Lu]));
println!("官禄宫自化忌: {}", career.self_mutaged(&[Mutagen::Ji]));
println!("官禄宫有任一自化: {}", career.self_mutaged_one_of(&[]));
println!("官禄宫无任何自化: {}", career.not_self_mutaged(&[]));
```
**输出**
```text
官禄宫自化禄: false
官禄宫自化忌: true
官禄宫有任一自化: true
官禄宫无任何自化: false
```
官禄宫宫干为丙，丙干化忌在廉贞，而廉贞正坐官禄宫，故成自化忌。
**边界与陷阱**
`self_mutaged_one_of` 与 `not_self_mutaged` 把空列表解释为「全部四化」，
而不是「空集」。`self_mutaged` 不做这层回退，空列表退化成「本宫是否包含空集」，
恒为 `true`——与 `flies_to` 的空列表判假正好相反，别把两者的直觉混用。
***
## mutaged\_places / mutagen\_stars [#mutaged_places--mutagen_stars]
**用途** 取本宫宫干化出的四颗星分别落在哪些宫，或直接取那四颗星本身。
**斗数含义** 飞星分析的全景版本：不问「有没有飞到某宫」，而是一次拿到禄权科忌四个落点。
**签名**
```rust
pub fn mutaged_places(&self) -> Vec>>
pub fn mutagen_stars(&self, mutagens: &[Mutagen]) -> Vec
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------------ | -- | -- | -------------------- |
| `mutagens` | `&[Mutagen]` | 是 | — | 要取的四化位；同一四化重复传入会重复出现 |
**返回值** `mutaged_places` 返回长度为 4 的 `Vec`，顺序为**禄、权、科、忌**，
某颗被化的星不在这张盘上时对应位置为 `None`。
`mutagen_stars` 返回 `Vec`，顺序与传入的四化一致。
**示例**
```rust
let soul = chart.palace(Palace::Soul).unwrap();
for (m, place) in ["禄", "权", "科", "忌"].iter().zip(soul.mutaged_places()) {
match place {
Some(p) => println!("化{m} → {}", translate_palace(p.name, Language::ZhCN)),
None => println!("化{m} → 不在盘上"),
}
}
println!("{:?}", soul.mutagen_stars(&[Mutagen::Lu, Mutagen::Ji]));
```
**输出**
```text
化禄 → 子女
化权 → 命宫
化科 → 官禄
化忌 → 财帛
[TianliangMaj, WuquMaj]
```
命宫宫干为壬，壬干四化为天梁化禄、紫微化权、左辅化科、武曲化忌，
四颗星分别坐在子女、命宫、官禄、财帛四宫。
`mutagen_stars` 取的是「本宫宫干化出哪几颗星」，与星耀自身的
`mutagen` 字段（生年四化）无关；后者由出生年干决定。
`PalaceRef::mutaged_places` 不收参数，恒按禄、权、科、忌四位返回长度为 4 的结果。
`PalaceData` 上的同名方法要传十二宫切片（`p.mutaged_places(&chart.palaces)`），
返回的是 `Vec>` 宫位索引而不是宫位视图。
***
## opposite\_palace / surrounded\_palaces [#opposite_palace--surrounded_palaces]
**用途** 取本宫的对宫与三方四正。
**斗数含义** 对宫是本宫 +6 的那一宫，两宫永远相对而看。
三方四正在对宫之外再加上 +4（官禄位）与 +8（财帛位）。
**签名**
```rust
pub fn opposite_palace(&self) -> PalaceRef<'a>
pub fn surrounded_palaces(&self) -> SurroundedPalaces<'a>
```
**返回值** `opposite_palace` 必然存在，不返回 `Option`。
`surrounded_palaces` 见[三方四正](/zh/docs/rust/surpalaces)。
**示例**
```rust
let zh = Language::ZhCN;
let soul = chart.palace(Palace::Soul).unwrap();
println!("{} 的对宫是 {}", translate_palace(soul.name, zh),
translate_palace(soul.opposite_palace().name, zh));
println!("三方四正见煞: {}", soul.surrounded_palaces().have_one_of(&[StarKey::HuoxingMin, StarKey::LingxingMin]));
```
**输出**
```text
命宫 的对宫是 迁移
三方四正见煞: true
```
***
## astrolabe [#astrolabe]
**用途** 从宫位回到它所属的星盘。
**签名**
```rust
pub fn astrolabe(&self) -> &'a Astrolabe
```
**返回值** `&Astrolabe`。视图始终持有星盘，因此不返回 `Option`。
**示例**
```rust
let soul = chart.palace(Palace::Soul).unwrap();
println!("{}", translate_five_elements_class(soul.astrolabe().five_elements_class, Language::ZhCN));
```
**输出**
```text
木三局
```
***
## to\_text [#to_text]
**用途** 本宫的语义化文本，与本命盘文本中该宫的段落逐字节一致：标题行带干支、大限与身宫/来因宫标记，
事实行依次是主星（空宫写「空宫」）、辅星、杂耀、三方四正、宫干飞化、十二神、小限虚岁。
**签名**
```rust
pub fn to_text(&self) -> String
```
定义在 `PalaceRef` 上，按星盘排盘语言输出；要指定语言用自由函数
`text::palace_to_text(&palace, lang)`（收 `&PalaceRef`）。
**示例**
```rust
let soul = chart.palace(Palace::Soul).unwrap();
print!("{}", soul.to_text());
```
**输出**
```text
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
```
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
***
## to\_text\_with [#to_text_with]
**用途** 本宫事实之后紧跟该宫每颗星（主星、辅星、杂耀）的释义，写法 `**星名(亮度)化X**: 正文`，
同宫主星的组合解读 `**A × B (同宫)**: ` 排在最前；十二神不释义。
**签名**
```rust
pub fn to_text_with(&self, opts: &TextOptions) -> String
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | -------------- | -- | -- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `opts` | `&TextOptions` | 是 | — | 输出选项；`TextOptions::new().knowledge(pack)` 带释义，`TextOptions::default()` 与 `to_text` 等价。见 [TextOptions](/zh/docs/rust/astro#textoptions) |
定义在 `PalaceRef` 上，按星盘排盘语言输出；要指定语言用自由函数
`text::palace_to_text_with(&palace, opts, lang)`。
插入位置见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let text = chart.palace(Palace::Soul).unwrap().to_text_with(&TextOptions::new().knowledge(pack));
for line in text.lines().filter(|l| l.starts_with("**")) {
println!("{}", line.chars().take(14).collect::());
}
```
**输出**
```text
**紫微(庙)**: 紫微星
**文曲(陷)**: 文曲星
**凤阁**: 凤阁星会增加
**天福**: 天福星可以看
**截路**: 截路星按生年
**蜚廉**: 蜚廉星充满好
**年解**: 年解星按年支
```
# 星耀对象 (/zh/docs/rust/star-object)
Star 的字段与亮度、四化判断，以及 StarRef 的回溯能力。
`Star` 是一颗落在某宫的星，带着它的类型、亮度与四化标记。
`chart.star(...)` 返回 `StarRef`，在 `Star` 之上多出回溯所在宫的能力。
```rust
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
let _name = &ziwei.name; // 经 Deref 直接取字段
let _palace = ziwei.palace(); // 视图独有：回溯所在宫
```
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
`Star` 本身不实现 `Copy`，经 `Deref` 取字段时按引用借用（`&ziwei.name`）
或克隆，不能直接搬走。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| ------------ | -------------------- | ---------------------------- |
| `key` | `StarKey` | 星耀标识，与语言无关，判断时用它 |
| `name` | `String` | 星名，按排盘语言翻译 |
| `star_type` | `StarType` | 星耀类型，见下表 |
| `scope` | `Scope` | 作用范围：本命星为 `Origin`，流耀为对应运限层级 |
| `brightness` | `Option` | 亮度；没有亮度表的星耀为 `None` |
| `mutagen` | `Option` | 生年四化；未被生年干化的星为 `None` |
### StarType 的八个取值 [#startype-的八个取值]
| 取值 | 含义 | 典型成员 |
| ----------- | ---- | ----------------- |
| `Major` | 十四主星 | 紫微、天府、七杀、破军 |
| `Soft` | 吉星 | 左辅、右弼、文昌、文曲、天魁、天钺 |
| `Tough` | 煞星 | 擎羊、陀罗、火星、铃星、地空、地劫 |
| `Adjective` | 杂耀 | 三台、八座、天刑、天姚 |
| `Flower` | 桃花星 | 红鸾、天喜、咸池 |
| `Helper` | 解神 | 解神 |
| `Lucun` | 禄存 | 禄存 |
| `Tianma` | 天马 | 天马 |
禄存与天马各自独占一类，因为它们在传统分法里既非纯吉也非纯煞，判断时常单独拎出来。
只有十四主星与文昌、文曲、火星、铃星、擎羊、陀罗这二十颗有亮度表，
其余星耀本就没有亮度概念，`brightness` 为 `None`。
***
## with\_brightness [#with_brightness]
**用途** 判断这颗星是否处于给定亮度之一。
**斗数含义** 亮度（庙旺得利平不陷）描述星耀在该宫位的强弱。
同一颗星在十二宫各有定值，庙旺则力量充分发挥，落陷则受制。
**签名**
```rust
pub fn with_brightness(&self, brightness: &[Brightness]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | --------------- | -- | -- | ------------ |
| `brightness` | `&[Brightness]` | 是 | — | 亮度列表，命中任一即为真 |
**返回值** `bool`。该星无亮度时恒为 `false`。
**示例**
```rust
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
println!("{}", ziwei.with_brightness(&[Brightness::Miao]));
println!("{}", ziwei.with_brightness(&[Brightness::Wang, Brightness::De]));
```
**输出**
```text
true
false
```
**边界与陷阱**
语义是「命中任一」而非「全部命中」——一颗星只有一个亮度，要求全部命中在列表多于一项时永假。
***
## with\_mutagen [#with_mutagen]
**用途** 判断这颗星是否带指定的生年四化。
**斗数含义** 生年四化由出生年干决定，一年固定四颗星分别化禄、权、科、忌。
这个标记跟着星走，无论那颗星落在哪一宫。
**签名**
```rust
pub fn with_mutagen(&self, mutagens: &[Mutagen]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------------ | -- | -- | ------------ |
| `mutagens` | `&[Mutagen]` | 是 | — | 四化列表，命中任一即为真 |
**返回值** `bool`。该星未被生年干化时恒为 `false`。
**示例**
```rust
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
let taiyang = chart.star(StarKey::TaiyangMaj).unwrap();
println!("紫微化禄: {}", ziwei.with_mutagen(&[Mutagen::Lu]));
println!("太阳化禄: {}", taiyang.with_mutagen(&[Mutagen::Lu]));
```
**输出**
```text
紫微化禄: false
太阳化禄: true
```
这张盘生年干为庚，庚干太阳化禄，因此标记落在太阳而非紫微。
**边界与陷阱**
`with_mutagen` 看的是**生年干**给这颗星打的标记，一张盘上只有四颗星带标记。
宫干飞出的四化不在这里体现，用宫位的 [`flies_to`](/zh/docs/rust/palace#flies_to--flies_one_of_to--not_fly_to) 一族。
***
## palace / opposite\_palace / surrounded\_palaces [#palace--opposite_palace--surrounded_palaces]
**用途** 从星回溯到它所在的宫、该宫的对宫与三方四正。
**签名**
```rust
pub fn palace(&self) -> PalaceRef<'a>
pub fn opposite_palace(&self) -> PalaceRef<'a>
pub fn surrounded_palaces(&self) -> SurroundedPalaces<'a>
```
**返回值** 三者都必然存在，不返回 `Option`——`StarRef` 只能由星盘查询产生，天然持有归属关系。
**示例**
```rust
let zh = Language::ZhCN;
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
println!("{}", translate_palace(ziwei.palace().name, zh));
println!("{}", translate_palace(ziwei.opposite_palace().name, zh));
println!("同宫或三方见天相: {}", ziwei.surrounded_palaces().have(&[StarKey::TianxiangMaj]));
```
**输出**
```text
命宫
迁移
同宫或三方见天相: true
```
**边界与陷阱**
一颗星在一张盘上只出现一次，因此 `chart.star(key)` 的结果唯一。
运限流耀不在本命盘的星耀列表里，要取它们用运限对象的
[`palace`](/zh/docs/rust/horoscope#palace) 配合层级参数。
# 三方四正 (/zh/docs/rust/surpalaces)
SurroundedPalaces 的四个宫位与五个判断方法。
三方四正是斗数最常用的取象范围。看一件事不能只看本宫，
对宫与两个三合宫的星耀同样作用其上，四宫合看才完整。
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
## 四个宫位 [#四个宫位]
| 字段 | 相对本宫 | 传统称呼 | 意义 |
| ---------- | ---- | ---- | -------------- |
| `target` | +0 | 本宫 | 事情本身 |
| `opposite` | +6 | 对宫 | 与本宫相对的一面，影响最直接 |
| `career` | +4 | 官禄位 | 三合之一 |
| `wealth` | +8 | 财帛位 | 三合之一 |
四个字段的类型都是 `&'a PalaceData`（不是 `PalaceRef`）：
字段可以直接读，[宫位对象](/zh/docs/rust/palace)上那些不需要星盘上下文的方法
（`has`、`is_empty`、`has_mutagen`、`mutagen_stars`）也都能调；
要用 `opposite_palace`、`surrounded_palaces` 这类需要回溯星盘的方法，
拿 `sp.target.index` 再走 `chart.palace(...)` 换成 `PalaceRef`。
`SurroundedPalaces` 声明时 `wealth` 写在 `career` 前面，但偏移是
`career = +4`、`wealth = +8`。以命宫起算时 +4 落在官禄宫、+8 落在财帛宫，
名字与偏移是这样对上的。
`wealth` 与 `career` 指的是「相对本宫的三合位置」，不是十二宫里那两个固定的宫名。
以命宫起算时它们恰好落在财帛宫与官禄宫；以别的宫起算则是别的宫。
## 三种取法 [#三种取法]
```rust
// 从星盘取
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();
// 从宫位取
let sp = chart.palace(Palace::Soul).unwrap().surrounded_palaces();
// 从星耀取（该星所在宫的三方四正）
let sp = chart.star(StarKey::ZiweiMaj).unwrap().surrounded_palaces();
```
三者结果相同，选哪个取决于手上已有什么。
***
## have / not\_have / have\_one\_of [#have--not_have--have_one_of]
**用途** 判断四宫合起来有没有指定星耀。
**斗数含义** 「三方四正见紫微」这类说法，问的正是这四宫里出没出现某颗星，
而不问具体落在其中哪一宫。
**签名**
```rust
pub fn have(&self, stars: &[StarKey]) -> bool
pub fn not_have(&self, stars: &[StarKey]) -> bool
pub fn have_one_of(&self, stars: &[StarKey]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ------------ | -- | -- | ------ |
| `stars` | `&[StarKey]` | 是 | — | 星耀标识列表 |
**返回值**
| 方法 | 语义 |
| ------------- | -------------------- |
| `have` | 列表中每一颗都出现在这四宫（不要求同宫） |
| `not_have` | 列表中一颗都没出现 |
| `have_one_of` | 列表中至少一颗出现 |
**示例**
```rust
use x_iztro::StarKey::*;
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();
println!("{}", sp.have(&[ZiweiMaj, TianxiangMaj]));
println!("{}", sp.have_one_of(&[QishaMaj, PojunMaj]));
println!("{}", sp.not_have(&[HuoxingMin]));
```
**输出**
```text
true
false
true
```
紫微在命宫、天相在财帛宫，分处两宫但都在这四宫内，因此 `have` 为 `true`。
**边界与陷阱**
`have(&[A, B])` 的语义是「A 和 B 都出现在这四宫里」，
不要求它们坐在同一宫。要判断同宫，用宫位的 [`has`](/zh/docs/rust/palace#has--not_have--has_one_of)。
`have` 与 `not_have` 在空列表下返回 `true`，`have_one_of` 返回 `false`。
***
## have\_mutagen / not\_have\_mutagen [#have_mutagen--not_have_mutagen]
**用途** 判断四宫里有没有某种生年四化。
**斗数含义** 「三方四正见忌」意味着这组宫位里坐着一颗被生年干化忌的星，
是判断压力来源的常用条件。
**签名**
```rust
pub fn have_mutagen(&self, mutagen: Mutagen) -> bool
pub fn not_have_mutagen(&self, mutagen: Mutagen) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | --------- | -- | -- | ------------------------------ |
| `mutagen` | `Mutagen` | 是 | — | `Lu` / `Quan` / `Ke` / `Ji` 之一 |
**返回值** `bool`。
**示例**
```rust
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();
println!("三方四正见禄: {}", sp.have_mutagen(Mutagen::Lu));
println!("三方四正见忌: {}", sp.have_mutagen(Mutagen::Ji));
println!("三方四正不见科: {}", sp.not_have_mutagen(Mutagen::Ke));
```
**输出**
```text
三方四正见禄: false
三方四正见忌: false
三方四正不见科: true
```
这张盘的生年四化落在四宫：太阳化禄在子女、武曲化权在财帛、太阴化科在仆役、天同化忌在疾厄。
命宫的三方四正是命宫、迁移、财帛、官禄——只有化权那一颗落在里面，
因此查禄、查忌都是 `false`，查权则会是 `true`。
**边界与陷阱**
这里看的是**生年四化**打在星上的标记，与宫干飞出的四化无关。
后者请用宫位的飞星族方法。
***
## to\_text [#to_text]
**用途** 三方四正的语义化文本：`## 本宫名 三方四正` 标题之下，本宫、对宫、财帛位、官禄位各一段，
每段标题带角色前缀（`### 本宫 · 命宫 (壬午) · 大限 3-12`），事实行与本命盘文本中该宫的段落一致。
**签名**
```rust
pub fn to_text(&self) -> String
```
按星盘排盘语言输出；要指定语言用自由函数 `text::surrounded_palaces_to_text(&sp, lang)`。
**示例**
```rust
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();
println!("{}", sp.to_text().lines().next().unwrap());
```
**输出**
```text
## 命宫 三方四正
```
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
***
## to\_text\_with [#to_text_with]
**用途** 四宫每段事实之后紧跟该宫星耀的释义，与单宫的 `to_text_with` 逐段相同。
**签名**
```rust
pub fn to_text_with(&self, opts: &TextOptions) -> String
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | -------------- | -- | -- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `opts` | `&TextOptions` | 是 | — | 输出选项；`TextOptions::new().knowledge(pack)` 带释义，`TextOptions::default()` 与 `to_text` 等价。见 [TextOptions](/zh/docs/rust/astro#textoptions) |
要指定语言用自由函数 `text::surrounded_palaces_to_text_with(&sp, opts, lang)`。
插入位置见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();
let text = sp.to_text_with(&TextOptions::new().knowledge(pack));
println!("{} {}", sp.to_text().chars().count(), text.chars().count());
```
**输出**
```text
924 6312
```
# 运限对象 (/zh/docs/rust/horoscope)
六个运限层级的数据结构、整层取回的三个列表，以及不必再传星盘的宫位查询方法。
运限把本命盘投影到某个时间点上。同一张盘，不同年份看到的宫位分布不同——
这正是「大限走到哪一宫」的意思。
```rust
let h = chart.horoscope("2025-6-1", 0)?;
```
`HoroscopeRef` 持有发起它的那张本命盘，因此所有查询方法都不必再把星盘传进去。
本页示例统一用 `Language::ZhCN` 的本命盘，因此输出里的展示值都是中文。
## HoroscopeData [#horoscopedata]
`HoroscopeRef` 经 `Deref` 得到 `HoroscopeData`，它有八个字段：两个日期串与六个层级。
| 字段 | 类型 | 说明 |
| ------------ | --------------- | ------------ |
| `solar_date` | `String` | 目标公历日期，与入参一致 |
| `lunar_date` | `String` | 目标日期的农历中文写法 |
| `decadal` | `HoroscopeItem` | 大限 |
| `age` | `AgeItem` | 小限 |
| `yearly` | `YearlyItem` | 流年 |
| `monthly` | `HoroscopeItem` | 流月 |
| `daily` | `HoroscopeItem` | 流日 |
| `hourly` | `HoroscopeItem` | 流时 |
`solar_date` 是**目标日期**不是出生日期；出生日期在本命盘上，用 `h.astrolabe().solar_date` 取。
## 六个层级 [#六个层级]
| 字段 | 类型 | 跨度 | 说明 |
| --------- | --------------- | --- | ------------- |
| `decadal` | `HoroscopeItem` | 十年 | 大限。未起运的幼年期为童限 |
| `age` | `AgeItem` | 一年 | 小限。按虚岁逐年走一宫 |
| `yearly` | `YearlyItem` | 一年 | 流年。按流年干支定宫 |
| `monthly` | `HoroscopeItem` | 一月 | 流月 |
| `daily` | `HoroscopeItem` | 一日 | 流日 |
| `hourly` | `HoroscopeItem` | 一时辰 | 流时 |
两者都是一年一走，但起法不同：小限从生年地支起、按虚岁顺推，
流年直接看那一年的干支落在哪一宫。两条线互相独立，斗数里通常并看。
### HoroscopeItem [#horoscopeitem]
| 字段 | 类型 | 说明 |
| ---------------- | ------------------------ | ---------------------------------------------------------------- |
| `index` | `usize` | 该层级落在哪一宫（宫位索引） |
| `name` | `String` | 层级显示名，按输出语言翻译 |
| `name_key` | `HoroscopeName` | 层级标识；大限层未起运时为 `Childhood`（童限），与 `Decadal` 是不同的解盘语义，判断层级用它、不要比对译文 |
| `heavenly_stem` | `HeavenlyStem` | 该层级的天干，决定它飞出的四化 |
| `earthly_branch` | `EarthlyBranch` | 该层级的地支 |
| `palace_names` | `Vec` | 以该层级所在宫为命宫重推的十二宫名，按宫位索引排列 |
| `mutagen` | `Vec` | 该层级天干引发的四化星，顺序为禄权科忌 |
| `stars` | `Option>>` | 该层级的流耀分布；无流耀的层级为 `None` |
`age` 与 `yearly` 不是 `HoroscopeItem` 本身，而是各自多带一项数据的包装：
```rust
pub struct AgeItem {
pub base: HoroscopeItem,
pub nominal_age: u32, // 该日期对应的虚岁
}
pub struct YearlyItem {
pub base: HoroscopeItem,
pub yearly_dec_star: YearlyDecStar,
}
pub struct YearlyDecStar {
pub jiangqian12: Vec, // 流年将前十二神，按宫位索引排列
pub suiqian12: Vec, // 流年岁前十二神，按宫位索引排列
}
```
`AgeItem` 与 `YearlyItem` 都实现 `Deref`，通用字段直接读：
`h.yearly.heavenly_stem`、`h.age.index`；需要整个 `HoroscopeItem` 时取 `.base`。
四个类型都在 crate 根重导出。
**示例**
```rust
let h = chart.horoscope("2025-6-1", 0)?;
for item in [&h.decadal, &h.monthly, &h.daily, &h.hourly] {
println!("{} 落在宫位 {} 干支 {}{}", item.name, item.index,
translate_heavenly_stem(item.heavenly_stem, Language::ZhCN),
translate_earthly_branch(item.earthly_branch, Language::ZhCN));
}
println!("小限虚岁 {}", h.age.nominal_age);
```
**输出**
```text
大限 落在宫位 2 干支 庚辰
流月 落在宫位 3 干支 壬午
流日 落在宫位 8 干支 辛丑
流时 落在宫位 8 干支 戊子
小限虚岁 26
```
***
## 三个列表 [#三个列表]
`decadal_list` / `yearly_list` / `monthly_list` 是 `Astrolabe` 上的方法，不在运限对象上：
它们一次取回整层的运限项，省去按日期逐个调 `horoscope` 再自己拼。
每项都在通用的 `HoroscopeItem` 之外多带该层的时间坐标：
```rust
pub struct DecadalHoroscope {
pub base: HoroscopeItem,
pub palace_name: Palace, // 该大限所在的本命宫名
pub age_range: (u32, u32), // 起止虚岁，含两端
pub year_range: (i64, i64), // 起止农历年份，含两端
}
pub struct YearlyHoroscope {
pub base: HoroscopeItem,
pub age: u32, // 该流年对应的虚岁
pub year: i64, // 农历年份
}
pub struct MonthlyHoroscope {
pub base: HoroscopeItem,
pub age: u32, // 该流月对应的虚岁
pub year: i64, // 农历年份
pub month: u32, // 农历月份，正月为 1；闰月与同号常规月的 month 相同
pub is_leap_month: bool, // 该项是否闰月
pub part: MonthPart, // Normal 整月 / First 闰月前半 / Second 闰月后半
pub day_range: (u32, u32), // 该段覆盖的农历日，含两端
}
```
三者都实现 `Deref`，通用字段直接读（`d.heavenly_stem`、`d.palace_names`），
需要整个 `HoroscopeItem` 时取 `.base`。四个类型与 `MonthPart` 都在 crate 根重导出。
三个列表的每一项都以**时柱地支**对应的时辰计算，而不是排盘时传入的 `time_index`。
两者只在晚子时不同：入参 12 的盘，时柱地支是子，列表按时辰 0 起运限。
***
## decadal\_list [#decadal_list]
**用途** 一次取回本盘十二个大限，按起运先后排列。
**斗数含义** 大限十年一步，从命宫或其他起限宫顺逆行走十二宫。
把整条线摊平看，才知道某一段人生落在哪一宫、对应哪十年。
**签名**
```rust
pub fn decadal_list(&self) -> Vec
```
**返回值** 定长 12 项，第 0 项是第一个大限。顺序按起运虚岁排，
与宫位索引顺序无关（大限顺行逆行取决于阴阳男女）。
**示例**
```rust
let zh = Language::ZhCN;
for d in chart.decadal_list().iter().take(3) {
println!("{} {}{} {}-{} {}-{}",
translate_palace(d.palace_name, zh),
translate_heavenly_stem(d.heavenly_stem, zh),
translate_earthly_branch(d.earthly_branch, zh),
d.age_range.0, d.age_range.1, d.year_range.0, d.year_range.1);
}
println!("{}", chart.decadal_list().len());
```
**输出**
```text
命宫 壬午 3-12 2002-2011
兄弟 辛巳 13-22 2012-2021
夫妻 庚辰 23-32 2022-2031
12
```
这张盘三岁起运，第一个大限落在命宫。
**边界与陷阱**
起运之前的那几年是童限，只有按具体日期查 `horoscope` 才会出现（`name_key` 为 `Childhood`）。
`decadal_list` 列的是十二个大限本身，每项的 `name_key` 恒为 `Decadal`。
***
## yearly\_list [#yearly_list]
**用途** 取一个大限内的全部流年。
**斗数含义** 定了大限再逐年细看，是斗数常规的推运顺序。
一个大限十年，对应的就是这十个流年。
**签名**
```rust
pub fn yearly_list(&self, target: impl Into) -> Result, IztroError>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | -------------------------- | -- | -- | ------------------------------------------ |
| `target` | `impl Into` | 是 | — | 大限序号（`usize`，0 为第一个大限）或该限所在的本命宫名（`Palace`） |
```rust
pub enum DecadalTarget {
Ordinal(usize), // 起运先后序号
Name(Palace), // 该大限所在的本命宫名
}
```
两种写法定位到同一个大限时结果完全相同，选哪个取决于手上已有什么。
**返回值** `Result, IztroError>`，10 项，按虚岁先后排列。
序号越界或宫名定位不到时返回 `Err`。
**示例**
```rust
let zh = Language::ZhCN;
let list = chart.yearly_list(2usize)?;
for y in list.iter().take(3) {
println!("{} {} {}{} -> {}", y.age, y.year,
translate_heavenly_stem(y.heavenly_stem, zh),
translate_earthly_branch(y.earthly_branch, zh), y.index);
}
println!("{} {}", list.len(), chart.yearly_list(Palace::Spouse)?.len());
```
**输出**
```text
23 2022 壬寅 -> 0
24 2023 癸卯 -> 1
25 2024 甲辰 -> 2
10 10
```
第 2 个大限落在夫妻宫，因此 `yearly_list(2)` 与 `yearly_list(Palace::Spouse)` 是同一个大限。
**边界与陷阱**
两种定位必须给一个，没有「不传就取当前大限」的行为——静默取一个默认值会把漏传
变成看起来成功的错答案。
***
## monthly\_list [#monthly_list]
**用途** 取一个农历年的全部流月。
**斗数含义** 流月是流年之下的一层，逐月推移。闰月怎么算是一个流派分歧点，
因此拆不拆由调用方定。
**签名**
```rust
pub fn monthly_list(&self, year: i64, fix_leap: bool) -> Result, IztroError>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------ | -- | -- | ------------ |
| `year` | `i64` | 是 | — | 农历年份 |
| `fix_leap` | `bool` | 是 | — | 闰月是否拆成前后半月两项 |
**返回值** `Result, IztroError>`，长度取决于该年有无闰月与 `fix_leap`：
| 该农历年 | `fix_leap` | 项数 | 闰月怎么排 |
| ---- | ---------- | -- | -------------------------------------- |
| 无闰月 | 任意 | 12 | — |
| 有闰月 | `true` | 14 | 闰月拆成 `First`（初一至十五）与 `Second`（十六至月末）两项 |
| 有闰月 | `false` | 13 | 闰月整月一项，`part` 为 `Normal` |
闰月排在同月号的常规月之后。每项按该段首日算出（后半段取十六）。
**示例**
```rust
let zh = Language::ZhCN;
let list = chart.monthly_list(2020, true)?;
println!("{}", list.len());
for m in list.iter().skip(3).take(4) {
println!("{} {} {} {}-{} {}{}", m.month, m.is_leap_month, m.part.as_key(),
m.day_range.0, m.day_range.1,
translate_heavenly_stem(m.heavenly_stem, zh),
translate_earthly_branch(m.earthly_branch, zh));
}
println!("{} {}", chart.monthly_list(2020, false)?.len(), chart.monthly_list(2021, true)?.len());
```
**输出**
```text
14
4 false normal 1-30 辛巳
4 true first 1-15 辛巳
4 true second 16-29 壬午
5 false normal 1-30 壬午
13 12
```
农历 2020 年有闰四月。拆开之后，闰四月前半与四月同干支（辛巳），后半跟五月同干支（壬午）
——这正是「闰月下半月算下一个月」的意思。农历 2021 年无闰月，恒为 12 项。
**边界与陷阱**
排盘入口那个 `fix_leap` 决定闰月出生的人下半月按下个月安星，改的是本命盘布局；
这里这个只决定本列表拆不拆闰月。两者可以取不同的值，互不影响。
闰四月的 `month` 也是 `4`，靠 `is_leap_month` 区分。按 `month` 去重会把闰月弄丢。
***
## age\_palace [#age_palace]
**用途** 取小限当年所在的宫。
**斗数含义** 小限是逐年推移的一条线，落在哪一宫就以那宫为该年重点。
**签名**
```rust
pub fn age_palace(&self) -> PalaceRef<'a>
```
**返回值** `PalaceRef`——本命盘上的宫位，必然存在。
**示例**
```rust
let h = chart.horoscope("2025-6-1", 0)?;
println!("{}", translate_palace(h.age_palace().name, Language::ZhCN));
```
**输出**
```text
田宅
```
***
## palace [#palace]
**用途** 取某个运限层级下、按该层级重推的十二宫中的某一宫。
**斗数含义** 大限走到某宫后，以那一宫为「大限命宫」重排十二宫。
「大限的夫妻宫」问的就是这套重排后的宫位，与本命夫妻宫通常不是同一宫。
**签名**
```rust
pub fn palace(&self, name: Palace, scope: Scope) -> Option>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | -------- | -- | -- | ----------- |
| `name` | `Palace` | 是 | — | 要取的宫名 |
| `scope` | `Scope` | 是 | — | 在哪个层级的十二宫里找 |
**返回值** `Option>`——本命盘上的宫位（同一格宫位在不同层级有不同宫名）。
层级为 `Origin` 时即本命十二宫。
**示例**
```rust
let zh = Language::ZhCN;
let h = chart.horoscope("2025-6-1", 0)?;
println!("大限命宫落在本命的 {}",
translate_palace(h.palace(Palace::Soul, Scope::Decadal).unwrap().name, zh));
println!("本命命宫是 {}",
translate_palace(h.palace(Palace::Soul, Scope::Origin).unwrap().name, zh));
```
**输出**
```text
大限命宫落在本命的 夫妻
本命命宫是 命宫
```
**边界与陷阱**
`palace(Soul, Decadal)` 返回的宫位对象上，`name` 仍是**本命宫名**（例中的夫妻），
因为它就是本命盘上的那一格。要看该格在大限层级叫什么，查 `h.decadal.palace_names[index]`。
***
## surround\_palaces [#surround_palaces]
**用途** 取某个运限层级下某宫的三方四正。
**签名**
```rust
pub fn surround_palaces(&self, name: Palace, scope: Scope) -> Option>
```
**参数** 同 `palace`。
**返回值** `Option>`，判断方法见[三方四正](/zh/docs/rust/surpalaces)。
**示例**
```rust
let h = chart.horoscope("2025-6-1", 0)?;
let sp = h.surround_palaces(Palace::Wealth, Scope::Yearly).unwrap();
println!("流年财帛的三方四正以本命 {} 为本宫", translate_palace(sp.target.name, Language::ZhCN));
```
**输出**
```text
流年财帛的三方四正以本命 疾厄 为本宫
```
***
## has\_horoscope\_stars / has\_one\_of\_horoscope\_stars / not\_have\_horoscope\_stars [#has_horoscope_stars--has_one_of_horoscope_stars--not_have_horoscope_stars]
**用途** 判断某层级某宫里有没有指定的流耀。
**斗数含义** 流耀是随运限层级产生的一组星：魁钺昌曲禄羊陀马鸾喜。
它们在不同层级有不同名字——大限层级叫运魁、运钺，流年层级叫流魁、流钺，
含义相同但作用于各自的时间跨度。
**签名**
```rust
pub fn has_horoscope_stars(&self, name: Palace, scope: Scope, stars: &[StarKey]) -> bool
pub fn has_one_of_horoscope_stars(&self, name: Palace, scope: Scope, stars: &[StarKey]) -> bool
pub fn not_have_horoscope_stars(&self, name: Palace, scope: Scope, stars: &[StarKey]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ------------ | -- | -- | ------------- |
| `name` | `Palace` | 是 | — | 该层级下的宫名 |
| `scope` | `Scope` | 是 | — | 运限层级 |
| `stars` | `&[StarKey]` | 是 | — | 流耀标识，须用该层级的名字 |
**返回值**
| 方法 | 语义 |
| ---------------------------- | ----- |
| `has_horoscope_stars` | 每一颗都在 |
| `has_one_of_horoscope_stars` | 至少一颗在 |
| `not_have_horoscope_stars` | 一颗都不在 |
**示例**
```rust
use x_iztro::StarKey::*;
let h = chart.horoscope("2025-6-1", 0)?;
println!("{}", h.has_horoscope_stars(Palace::Soul, Scope::Decadal, &[Yunlu]));
println!("{}", h.has_one_of_horoscope_stars(Palace::Soul, Scope::Decadal, &[Yunlu, Yunyang]));
println!("{}", h.not_have_horoscope_stars(Palace::Soul, Scope::Decadal, &[Yuntuo]));
```
**输出**
```text
false
false
true
```
**边界与陷阱**
三个方法用 `scope` + `name` 定位到本命盘上的某一格，
但要比对的星耀集合恒为**大限流耀与流年流耀的并集**，与 `scope` 无关。
因此 `scope` 传 `Monthly` 时，查的是「流月某宫这一格里有没有大限或流年的流耀」，
而不是流月自己的流耀——流月、流日、流时三层的流耀不参与这里的比对。
要按层级取流耀分布，用 `h.monthly.stars` 一类字段，或
[`get_horoscope_stars`](/zh/docs/rust/star#get_horoscope_stars)。
大限流耀叫 `Yunlu`（运禄）、`Yunyang`（运羊）……，流年流耀叫 `Liulu`（流禄）、
`Liuyang`（流羊）……，两组标识不同名。由于比对集合恒是这两组的并集，
`Yunlu` 与 `Liulu` 在任何 `scope` 下都查得到，只是落宫不同。
各层级的标识对照见[安星模块](/zh/docs/rust/star#get_horoscope_stars)。
`Origin` 走的是本命十二宫，因此仍能定位到宫位；
只是本命盘上没有流耀，比对的仍是大限与流年的流耀落在那一格的部分。
***
## has\_horoscope\_mutagen [#has_horoscope_mutagen]
**用途** 判断某层级某宫里有没有该层级天干引发的四化。
**斗数含义** 每个运限层级有自己的天干，会像生年干一样化出四颗星。
「大限化禄落在大限财帛」这类判断问的就是这个。
**签名**
```rust
pub fn has_horoscope_mutagen(&self, name: Palace, scope: Scope, mutagen: Mutagen) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | --------- | -- | -- | ------- |
| `name` | `Palace` | 是 | — | 该层级下的宫名 |
| `scope` | `Scope` | 是 | — | 运限层级 |
| `mutagen` | `Mutagen` | 是 | — | 四化之一 |
**返回值** `bool`。检查该层级天干化出的那颗星是否落在目标宫的主星或辅星里（不看杂耀）。
**示例**
```rust
let h = chart.horoscope("2025-6-1", 0)?;
println!("{}", h.has_horoscope_mutagen(Palace::Soul, Scope::Decadal, Mutagen::Lu));
// 该层级化出的四颗星本身可直接读
println!("{:?}", h.decadal.mutagen.iter()
.map(|s| translate_star(*s, Language::ZhCN)).collect::>());
```
**输出**
```text
false
["太阳", "武曲", "太阴", "天同"]
```
大限干为庚，庚干四化为太阳化禄、武曲化权、太阴化科、天同化忌。
**边界与陷阱**
本命层级没有「层级天干」这回事——生年四化已经打在星耀自身的 `mutagen` 字段上。
`has_horoscope_mutagen(name, Scope::Origin, m)` 因此直接返回 `false`，
不代表本命盘上没有这个四化。要查本命四化，用宫位的
[`has_mutagen`](/zh/docs/rust/palace#has_mutagen--not_have_mutagen)。
***
## astrolabe / data / into\_data [#astrolabe--data--into_data]
**用途** 回到本命盘，或取出运限的纯数据。
**签名**
```rust
pub fn astrolabe(&self) -> &'a Astrolabe
pub fn data(&self) -> &HoroscopeData
pub fn into_data(self) -> HoroscopeData
```
**返回值**
| 方法 | 用途 |
| ----------- | ----------------------------------------- |
| `astrolabe` | 回到发起这次运限的本命盘 |
| `data` | 借用底层数据；视图已实现 `Deref`，通常直接写 `h.decadal` 即可 |
| `into_data` | 取走数据、丢掉对星盘的借用，用于需要 `'static` 生命周期的场合 |
**示例**
```rust
let h = chart.horoscope("2025-6-1", 0)?;
println!("{}", h.astrolabe().solar_date);
let data: HoroscopeData = h.into_data(); // 不再借用 chart
println!("{}", data.solar_date);
```
**输出**
```text
2000-8-16
2025-6-1
```
***
## to\_text [#to_text]
**用途** 运限的语义化文本：面向语言模型与人的完整描述，Markdown 子集。
**签名**
```rust
pub fn to_text(&self) -> String
```
定义在 `HoroscopeRef` 上，按星盘排盘语言输出；要指定语言用自由函数
`text::horoscope_to_text(astrolabe, horoscope, lang)`。
**返回值** `String`——大限（未起运为童限）、小限、流年、流月、流日、流时各一节，
各层带四化、该层视角的格局与流耀，大限与流年展开十二宫表。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
**示例**
```rust
let h = chart.horoscope("2025-1-1", 0)?;
for line in h.to_text().lines().take(5) {
println!("{line}");
}
```
**输出**
```text
# 运限 2025-1-1 (二〇二四年腊月初二)
## 大限 · 命宫: 本命夫妻 (庚辰)
- 四化: 太阳化禄→本命子女, 武曲化权→本命财帛, 太阴化科→本命仆役, 天同化忌→本命疾厄
- 格局: 杀破狼 (命宫), 风云际会 (命宫)
```
***
## to\_text\_with [#to_text_with]
**用途** `to_text` 的同一份文本，按 [`TextOptions`](/zh/docs/rust/astro#textoptions) 附释义：
每层的表或事实之后紧跟该层流耀的释义与该层视角命中格局的释义，跨层去重。
本命星耀的释义不在这里重复，在本命盘的 `to_text_with` 里。
**签名**
```rust
pub fn to_text_with(&self, opts: &TextOptions) -> String
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | -------------- | -- | -- | ------------------------------------------------------------------------------------- |
| `opts` | `&TextOptions` | 是 | — | 输出选项；`TextOptions::new().knowledge(pack)` 带释义，`TextOptions::default()` 与 `to_text` 等价 |
定义在 `HoroscopeRef` 上，按星盘排盘语言输出；要指定语言用自由函数
`text::horoscope_to_text_with(astrolabe, horoscope, opts, lang)`。
插入位置见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let h = chart.horoscope("2025-1-1", 0)?;
let text = h.to_text_with(&TextOptions::new().knowledge(pack));
println!("{} {}", h.to_text().chars().count(), text.chars().count());
for line in text.lines().filter(|l| l.starts_with("## ")) {
println!("{line}");
}
```
**输出**
```text
2457 8458
## 大限 · 命宫: 本命夫妻 (庚辰)
## 小限 · 命宫: 本命官禄 · 虚岁 25
## 流年 · 命宫: 本命夫妻 (甲辰)
## 流月 · 命宫: 本命仆役 (丁丑)
## 流日 · 命宫: 本命迁移 (庚午)
## 流时 · 命宫: 本命迁移 (丙子)
```
***
## to\_dto [#to_dto]
**用途** 把运限数据转成与 JS iztro 字段契约一致的序列化结构。
**签名**
```rust
pub fn to_dto(&self, lang: Language) -> HoroscopeDto
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | ---------- | -- | -- | --------- |
| `lang` | `Language` | 是 | — | 译名字段用哪种语言 |
定义在 `HoroscopeData` 上（不是 `HoroscopeRef`）。运限数据本身不记语言，
因此这里要显式传——通常传 `chart.language` 与本命盘保持一致。
**返回值** `x_iztro::dto::HoroscopeDto`，camelCase 键 + `*Key` 标识。
**示例**
```rust
let h = chart.horoscope("2025-6-1", 0)?;
let json = serde_json::to_string(&h.to_dto(chart.language))?;
let v: serde_json::Value = serde_json::from_str(&json)?;
println!("{} {}", v["solarDate"], v["decadal"]["heavenlyStem"]);
println!("{}", v["age"]["nominalAge"]);
```
**输出**
```text
"2025-6-1" "庚"
26
```
# 格局判定 (/zh/docs/rust/patterns)
本命与运限的格局命中、口径开关、格局标识与序列化 DTO。
格局是「盘上某几颗星按特定方式凑在一起」的模式识别。判定在本命盘与运限盘上共用同一套规则，
共 64 条。什么是格局、每条规则的条件与来源，见[概念页](/zh/docs/guide/concepts/patterns)。
```rust
let chart = by_solar("1985-5-3", 9, Gender::Male, true, Language::ZhCN, Config::default())?;
let hits = chart.patterns();
```
本页示例统一用 `Language::ZhCN` 的本命盘，因此输出里的展示值都是中文。
## 类型 [#类型]
五个类型都在 crate 根重导出：`PatternHit`、`StarAt`、`PatternConfig`、`BrightnessSource`、
`PatternKey`，另有常量 `ALL_PATTERNS` 与模块函数 `patterns_at`。
### PatternHit [#patternhit]
一次命中。
| 字段 | 类型 | 说明 |
| --------- | ---------------------- | ------------------------------ |
| `key` | `PatternKey` | 格局 |
| `scope` | `Scope` | 判定视角：本命为 `Scope::Origin`，运限为该层 |
| `palace` | `usize` | 成格所在的宫位索引（0-11，寅宫为 0） |
| `variant` | `Option<&'static str>` | 多口径格局命中的是哪个口径；单口径为 `None` |
| `broken` | `bool` | 「破格 / 加杀平常」条件是否触发。成格照报，这里只作标记 |
| `stars` | `Vec` | 参与成格的星与落宫 |
`PatternHit` 实现 `Clone`、`PartialEq`、`Eq`、`Serialize`、`Deserialize`。
### StarAt [#starat]
一颗参与成格的星。
| 字段 | 类型 | 说明 |
| ------------ | -------------------- | --------------------------- |
| `star` | `StarKey` | 星耀 |
| `palace` | `usize` | 该星**真正待的**宫位索引（借宫时不是借到的那一宫） |
| `brightness` | `Option` | 亮度；无亮度表的星为 `None` |
| `mutagen` | `Option` | 判定视角下的四化：本命读生年四化，运限读该层四化 |
### PatternConfig [#patternconfig]
判定口径。凡是「同一格局的多种成立形式」都走 `PatternHit::variant`，这里只放会改变
**事实判定本身**的数据口径，因此只有三个字段。
```rust
pub struct PatternConfig {
pub brightness_source: BrightnessSource, // 默认 Table
pub borrow: bool, // 默认 true
pub flow_stars: bool, // 默认 true
}
```
| 字段 | 默认 | 作用 |
| ------------------- | ------------------------- | ------------------------------- |
| `brightness_source` | `BrightnessSource::Table` | 日月明暗的依据 |
| `borrow` | `true` | 空宫是否借对宫主星参与判定 |
| `flow_stars` | `true` | 运限视角下流曜（运禄/流禄、运昌/流昌…）是否等同对应本命辅星 |
`BrightnessSource` 两个变体：`Table` 按星盘亮度表（庙旺为明，陷与「不」为暗，与 iztro 逐值一致），
`Positional` 按传统位置（太阳寅至午明、酉至丑暗；太阴酉至丑明、卯至未暗）。
两者的取舍见[概念页的说明](/zh/docs/guide/concepts/patterns#日月的明暗按哪张表)。
`PatternConfig` 实现 `Default`，改单项用结构体更新语法：
```rust
let cfg = PatternConfig {
brightness_source: BrightnessSource::Positional,
..Default::default()
};
```
### PatternKey [#patternkey]
64 个格局的语言无关标识，`Copy` + `Hash`，可直接做 `HashMap` 的键。
| 方法 | 签名 | 说明 |
| ------------------- | ---------------------------------------- | -------------------------------- |
| `as_key` | `fn as_key(self) -> &'static str` | snake\_case 标识，如 `"sha_po_lang"` |
| `from_key` | `fn from_key(key: &str) -> Option` | 由标识反查；未知字符串返回 `None` |
| `is_horoscope_only` | `fn is_horoscope_only(self) -> bool` | 是否行运格（只在运限视角判定） |
常量 `ALL_PATTERNS: [PatternKey; 64]` 按来源页条目顺序列出全部格局。
译名用 `translate_pattern(key, lang)`，六种语言都有。
**示例**
```rust
println!("{}", ALL_PATTERNS.len());
println!("{}", PatternKey::ShaPoLang.as_key());
println!("{:?}", PatternKey::from_key("sha_po_lang"));
println!("{:?}", PatternKey::from_key("nope"));
println!("{}", PatternKey::FengYunJiHui.is_horoscope_only());
```
**输出**
```text
64
sha_po_lang
Some(ShaPoLang)
None
true
```
***
## patterns [#patterns]
**用途** 取本命盘的全部格局命中，默认口径。
**斗数含义** 把这张盘上成立的所有有名字的星耀组合列出来，附上成格的宫位与证据星。
**签名**
```rust
impl Astrolabe {
pub fn patterns(&self) -> Vec
}
```
**返回值** `Vec`——按来源页条目顺序排列；一条格局也不成立时为空 `Vec`。
本命盘上两条行运格（禄衰马困、风云际会）永远不出现。
**示例**
```rust
let zh = Language::ZhCN;
let chart = by_solar("1985-5-3", 9, Gender::Male, true, zh, Config::default())?;
for hit in chart.patterns() {
println!("{} {} broken={}", translate_pattern(hit.key, zh), hit.palace, hit.broken);
}
```
**输出**
```text
武贪同行 11 broken=false
府相朝垣 5 broken=false
杀破狼 11 broken=false
禄马交驰 5 broken=false
左右夹命 5 broken=false
文贵文华 11 broken=false
文星朝命 5 broken=true
文星暗拱 5 broken=false
文星暗拱 5 broken=false
```
取一条命中的证据星：
```rust
let hit = chart.patterns().into_iter()
.find(|h| h.key == PatternKey::FuXiangChaoYuan)
.unwrap();
println!("{} variant={:?}", translate_pattern(hit.key, zh), hit.variant);
for s in &hit.stars {
println!(" {} 宫位 {} 亮度 {:?}", translate_star(s.star, zh), s.palace, s.brightness);
}
```
```text
府相朝垣 variant=Some("soul_empty")
天府 宫位 9 亮度 Some(De)
天相 宫位 1 亮度 Some(Xian)
```
**边界与陷阱**
多数格局成于命宫，但「身命」类格局（武贪同行、杀破狼、石中隐玉…）命宫身宫各判一次，
`palace` 记实际成格的那一宫，两宫都成立就返回两条命中。
禄马交驰更是任一宫成立即报，一张盘上可能有多条。
空宫借对宫主星时，`StarAt::palace` 记的是那颗星实际落的宫（对宫），
不是借进来的宫。要知道格局成在哪一宫看 `PatternHit::palace`。
判定在已经排好的盘上做，没有外部输入需要校验，因此不会失败。
错误只可能来自排盘入口（`by_solar` / `by_lunar`）。
***
## patterns\_with [#patterns_with]
**用途** 同 `patterns`，指定判定口径。
**签名**
```rust
impl Astrolabe {
pub fn patterns_with(&self, config: &PatternConfig) -> Vec
}
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ---------------- | -- | -- | -------------------------------------------------- |
| `config` | `&PatternConfig` | 是 | — | 判定口径，`PatternConfig::default()` 即 `patterns()` 的行为 |
**返回值** 同 `patterns`。
**示例** 同一张盘按两种日月明暗口径判：
```rust
let chart = by_solar("1985-6-10", 8, Gender::Female, true, zh, Config::default())?;
let cfg = PatternConfig {
brightness_source: BrightnessSource::Positional,
..Default::default()
};
println!("{:?}", chart.patterns().iter()
.map(|h| translate_pattern(h.key, zh)).collect::>());
println!("{:?}", chart.patterns_with(&cfg).iter()
.map(|h| translate_pattern(h.key, zh)).collect::>());
```
**输出**
```text
[]
["日月反背"]
```
***
## HoroscopeRef::patterns [#horoscoperefpatterns]
**用途** 取某个运限层级视角下的格局命中。
**斗数含义** 以该层的命宫为命宫、合并该层的流曜与四化之后重跑全部规则。
「本命有此组合，大限又走到即享其益」就是这么算出来的。
**签名**
```rust
impl<'a> HoroscopeRef<'a> {
pub fn patterns(&self, scope: Scope) -> Vec
pub fn patterns_with(&self, scope: Scope, config: &PatternConfig) -> Vec
}
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ---------------- | ------------------ | -- | --------- |
| `scope` | `Scope` | 是 | — | 判定视角所在的层级 |
| `config` | `&PatternConfig` | `patterns_with` 必填 | — | 判定口径 |
**返回值** `Vec`，每条的 `scope` 即传入的层级。
传 `Scope::Origin` 时结果与本命盘上直接调 `patterns()` 完全一致。
**示例**
```rust
let chart = by_solar("2000-8-16", 2, Gender::Female, true, zh, Config::default())?;
let h = chart.horoscope("2025-6-1", 0)?;
for hit in h.patterns(Scope::Decadal) {
println!("{} {:?} {:?}", translate_pattern(hit.key, zh), hit.scope, hit.variant);
}
```
**输出**
```text
杀破狼 Decadal None
风云际会 Decadal None
风云际会 Decadal Some("yearly")
```
同一张盘的本命视角只有一条「府相朝垣」——大限换了命宫，杀破狼才在这一层成立。
**边界与陷阱**
身宫是本命概念。运限视角下「身命」类格局只判该层命宫。
禄衰马困按当前视角那一层判（大限视角判大限，流年视角判流年），
限命宫三方四正又见七杀（古书严口径同时满足）时 `variant` 为 `Some("qisha")`；
风云际会跨层比较「两限同时逢禄马」，只在 `Scope::Decadal` 视角判一次，
`variant` 同时记二限组合与「逢」的松紧：大限 + 小限命中为 `None`（三方四正会照）或
`Some("same_palace")`（两限命宫皆本宫坐禄马的严口径），大限 + 流年命中为
`Some("yearly")` 或 `Some("yearly_same_palace")`。两种组合各报一条，最多两条。
默认口径下运禄/流禄当禄存看、运昌/流昌当文昌看，其余同理。
不想要这个行为，用 `patterns_with` 传 `flow_stars: false`。
***
## patterns\_at [#patterns_at]
**用途** 在某运限层视角上判定格局的自由函数版，收 `HoroscopeData` 而非 `HoroscopeRef`。
**签名**
```rust
pub fn patterns_at(
astrolabe: &Astrolabe,
horoscope: &HoroscopeData,
scope: Scope,
config: &PatternConfig,
) -> Vec
```
**返回值** 同 `HoroscopeRef::patterns_with`。
手里只有 `HoroscopeData`（例如从别处反序列化得到）时用它；
有 `HoroscopeRef` 的场合用方法版更短。
***
## patterns\_dto [#patterns_dto]
**用途** 取序列化用的命中列表：键为 camelCase，值按排盘语言翻译，同时给出语言无关标识。
三语言绑定与 FFI 都走这一层。
**签名**
```rust
impl Astrolabe {
pub fn patterns_dto(&self, config: &PatternConfig) -> Vec
}
impl HoroscopeData {
pub fn patterns_dto(
&self,
astrolabe: &Astrolabe,
scope: Scope,
config: &PatternConfig,
) -> Vec
}
```
**返回值** `Vec`。相对 `PatternHit` 多出四项：
每条带 `name`（译名）与 `palaceName` / `palaceNameKey`（成格宫在该视角下的宫名），
每颗证据星带 `name` 与 `brightnessKey` / `mutagenKey`。
无值的可选键在序列化时省略。
**示例**
```rust
let chart = by_solar("2000-8-16", 2, Gender::Female, true, zh, Config::default())?;
let dto = chart.patterns_dto(&PatternConfig::default());
println!("{}", serde_json::to_string_pretty(&dto[0]).unwrap());
```
**输出**
```json
{
"key": "fu_xiang_chao_yuan",
"name": "府相朝垣",
"scope": "origin",
"palaceIndex": 4,
"palaceName": "命宫",
"palaceNameKey": "soulPalace",
"broken": false,
"stars": [
{
"key": "tianfuMaj",
"name": "天府",
"palaceIndex": 8,
"brightness": "庙",
"brightnessKey": "miao"
},
{
"key": "tianxiangMaj",
"name": "天相",
"palaceIndex": 0,
"brightness": "庙",
"brightnessKey": "miao"
}
]
}
```
`PatternHitDto` 里的字段叫 `palaceIndex`，Rust 结构体里叫 `palace`——
DTO 的键名与 JS 侧的命名习惯对齐，Rust 侧用更短的名字。
***
## 语义化文本 [#语义化文本]
格局命中列表可以经 `text::patterns_to_text` 投影成文本，每条一行：
`- **格局名** (命中宫, 破格): 构成星耀`，未破格时括号里只有宫名。
```rust
pub fn patterns_to_text(hits: &[PatternHit], palace_names: &[Palace], lang: Language) -> String
```
`palace_names` 是判定视角下按宫位索引排列的十二宫名——本命视角传
`chart.palaces` 各宫的 `name`，运限视角传该层的 `palace_names`。
```rust
use x_iztro::text::patterns_to_text;
let hits = chart.patterns();
let names: Vec = chart.palaces.iter().map(|p| p.name).collect();
print!("{}", patterns_to_text(&hits, &names, chart.language));
```
**输出**
```text
# 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
```
本命盘的 `to_text` 已自带这一节；单独调用适合只要格局摘要的场景。
带释义的形态在命中列表之后紧跟每条命中格局的释义（`intro` 加 `成立条件: ` 段，同一格局只出一次），
选项见 [TextOptions](/zh/docs/rust/astro#textoptions)：
```rust
pub fn patterns_to_text_with(
hits: &[PatternHit],
palace_names: &[Palace],
opts: &TextOptions,
lang: Language,
) -> String
```
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let opts = TextOptions::new().knowledge(pack);
let text = text::patterns_to_text_with(&hits, &names, &opts, chart.language);
for line in text.lines().skip(2).take(3) {
println!("{}", line.chars().take(30).collect::());
}
```
**输出**
```text
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
**府相朝垣**: “食禄千锺”的断语使此格备受欢迎，但成格
```
# 轻量查询 (/zh/docs/rust/query)
不排整盘就能拿到的生肖、星座与命宫主星。
有些问题不需要整张星盘。这五个函数各自只跑到必要的那一步就返回，
结果与完整排盘的对应字段永远一致——它们走的是同一套核心逻辑。
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
***
## get\_zodiac\_by\_solar\_date [#get_zodiac_by_solar_date]
**用途** 由公历日期取生肖。
**斗数含义** 生肖由**年支**决定，而年支的换算时点受 `year_divide` 影响。
正月初一与立春之间出生的人，两种配置会得到不同的生肖——这不是 bug，是流派差异。
**签名**
```rust
pub fn get_zodiac_by_solar_date(
solar_date: &str,
language: Language,
config: Config,
) -> Result
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ---------- | -- | -- | -------------------- |
| `solar_date` | `&str` | 是 | — | 公历日期，格式 `YYYY-M-D` |
| `language` | `Language` | 是 | — | 输出语言 |
| `config` | `Config` | 是 | — | 仅 `year_divide` 影响结果 |
**返回值** `String`——按语言翻译的生肖名。
**示例**
```rust
println!("{}", get_zodiac_by_solar_date("2000-8-16", Language::ZhCN, Config::default())?);
```
**输出**
```text
龙
```
**边界与陷阱**
默认按正月初一换年。改成 `YearDivide::Exact` 后按立春换年，
1 月下旬到 2 月上旬出生的人可能拿到不同生肖。
***
## get\_sign\_by\_solar\_date / get\_sign\_by\_lunar\_date [#get_sign_by_solar_date--get_sign_by_lunar_date]
**用途** 取星座。
**斗数含义** 星座是西洋占星概念，只由公历日期决定，与斗数算法无关。
农历版本先把农历转成公历再判定，因此两者对同一天的结果相同。
**签名**
```rust
pub fn get_sign_by_solar_date(solar_date: &str, language: Language) -> Result
pub fn get_sign_by_lunar_date(
lunar_date: &str,
is_leap_month: bool,
language: Language,
) -> Result
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------------- | ---------- | -- | -- | ---------------- |
| `solar_date` / `lunar_date` | `&str` | 是 | — | 日期，格式 `YYYY-M-D` |
| `is_leap_month` | `bool` | 是 | — | 仅农历版本：该月是否闰月 |
| `language` | `Language` | 是 | — | 输出语言 |
无 `config` 参数——星座不受任何配置影响。
**返回值** `String`。
**示例**
```rust
println!("{}", get_sign_by_solar_date("2000-8-16", Language::ZhCN)?);
println!("{}", get_sign_by_lunar_date("2000-7-17", false, Language::ZhCN)?);
```
**输出**
```text
狮子座
狮子座
```
***
## get\_major\_star\_by\_solar\_date / get\_major\_star\_by\_lunar\_date [#get_major_star_by_solar_date--get_major_star_by_lunar_date]
**用途** 只取命宫主星，不排整盘。
**斗数含义** 命宫主星是斗数最常被单独问起的一项。
命宫为空宫时按惯例借对宫主星来看，本函数已经处理了这一步。
**签名**
```rust
pub fn get_major_star_by_solar_date(
solar_date: &str,
time_index: u8,
fix_leap: bool,
language: Language,
config: Config,
) -> Result
pub fn get_major_star_by_lunar_date(
lunar_date: &str,
time_index: u8,
leap: LeapMonth,
language: Language,
config: Config,
) -> Result
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------------- | ----------- | -- | -- | ----------------------------------------------------------------------------------- |
| `solar_date` / `lunar_date` | `&str` | 是 | — | 日期 |
| `time_index` | `u8` | 是 | — | 时辰索引 0–12，命宫由月份与时辰共同决定 |
| `fix_leap` | `bool` | 是 | — | 仅阳历版本：阳历日期落在闰月十五之后时是否视作次月 |
| `leap` | `LeapMonth` | 是 | — | 仅农历版本：`NotLeap` / `Leap` / `LeapFixed`，见 [`by_lunar`](/zh/docs/rust/astro#by_lunar) |
| `language` | `Language` | 是 | — | 输出语言 |
| `config` | `Config` | 是 | — | 排盘配置 |
**返回值** `String`——多颗主星以逗号分隔；空宫时返回对宫主星。
**示例**
```rust
let cfg = Config::default();
println!("{}", get_major_star_by_solar_date("2000-8-16", 2, true, Language::ZhCN, cfg.clone())?);
println!("{}", get_major_star_by_solar_date("2000-8-16", 2, true, Language::EnUS, cfg.clone())?);
```
**输出**
```text
紫微
emperor
```
**边界与陷阱**
命宫由农历月份与出生时辰共同定位，因此 `time_index` 是必填的。
只知道日期不知道时辰时，斗数无法给出确定的命宫。
返回值是翻译后的字符串，换语言就会变。要做程序判断用下面的
`major_star_keys_of_soul_palace`，或排整盘后比较 `major_stars` 里的 `key`。
***
## major\_star\_keys\_of\_soul\_palace [#major_star_keys_of_soul_palace]
**用途** 命宫主星的语言无关标识列表——上面两个函数的 key 形态，供程序判断。
**签名**
```rust
pub fn major_star_keys_of_soul_palace(astrolabe: &Astrolabe) -> Vec
```
收已排好的盘（配合 `by_solar` / `by_lunar` 使用），借宫规则与译文形态共享同一实现：
命宫为空宫时借对宫主星，对宫也无主星时返回空列表。标识与盘面语言无关。
**示例**
```rust
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
println!("{:?}", major_star_keys_of_soul_palace(&chart));
```
**输出**
```text
["ziweiMaj"]
```
# 工具函数 (/zh/docs/rust/util)
索引换算、亮度与四化查表、命身宫推算、四柱展示串。
这些函数是排盘算法的零件。自己实现斗数逻辑、或要复核某一步推算时用得上；
日常排盘不必直接调用。
参数与返回值中的枚举都与语言无关，可直接与星盘上的字段互操作。
***
## fix\_index [#fix_index]
**用途** 把任意整数约束到 `0..max` 的循环区间（含 0，不含 `max`）。
**斗数含义** 十二宫首尾相接，从丑宫（索引 11）再走一格回到寅宫（索引 0）。
所有「顺数几格、逆数几格」的推算都靠这个回绕。
**签名**
```rust
pub fn fix_index(index: i32, max: i32) -> usize
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----- | -- | -- | ------------------ |
| `index` | `i32` | 是 | — | 待修正的索引，可为负 |
| `max` | `i32` | 是 | — | 循环长度，宫位用 12、天干用 10 |
**返回值** `usize`，落在 `0..max`（`max` 本身不会出现）。`max` 传 0 会触发除零 panic，
调用方自己保证它是正数——盘上的用法固定为 12 或 10。
**示例**
```rust
println!("{} {}", utils::fix_index(-1, 12), utils::fix_index(13, 12));
```
**输出**
```text
11 1
```
**边界与陷阱**
负数按数学取模回绕（-1 → 11），不是截断到 0。
***
## earthly\_branch\_to\_palace\_index [#earthly_branch_to_palace_index]
**用途** 地支转宫位索引。
**斗数含义** 十二宫的排列从**寅宫**起，而地支的自然顺序从**子**起，两者差两格。
这个函数负责这层换算：寅 → 0，卯 → 1，⋯，子 → 10，丑 → 11。
**签名**
```rust
pub fn earthly_branch_to_palace_index(branch: EarthlyBranch) -> usize
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | --------------- | -- | -- | -- |
| `branch` | `EarthlyBranch` | 是 | — | 地支 |
**返回值** `usize`，0–11。
**示例**
```rust
println!("寅={} 子={}",
utils::earthly_branch_to_palace_index(EarthlyBranch::Yin),
utils::earthly_branch_to_palace_index(EarthlyBranch::Zi));
```
**输出**
```text
寅=0 子=10
```
***
## time\_to\_index [#time_to_index]
**用途** 小时数转时辰索引。
**斗数含义** 一天十二时辰，每时辰两小时，但子时横跨午夜被拆成早子时（0）与晚子时（12），
因此索引有 13 个值。
**签名**
```rust
pub fn time_to_index(hour: u8) -> u8
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | ---- | -- | -- | -------- |
| `hour` | `u8` | 是 | — | 小时数 0–23 |
**返回值** `u8`，0–12。
**示例**
```rust
println!("{} {} {}", utils::time_to_index(0), utils::time_to_index(4), utils::time_to_index(23));
```
**输出**
```text
0 2 12
```
0 点为早子时，4 点为寅时，23 点为晚子时。
***
## get\_age\_index [#get_age_index]
**用途** 由生年地支取小限起始宫位索引。
**斗数含义** 小限从固定的宫起，按虚岁逐年推移。起宫由生年地支所属的三合组决定：
寅午戌年起辰宫、申子辰年起戌宫、巳酉丑年起未宫、亥卯未年起丑宫。
**签名**
```rust
pub fn get_age_index(branch: EarthlyBranch) -> usize
```
**返回值** `usize`，0–11。
**示例**
```rust
println!("{}", utils::get_age_index(EarthlyBranch::Chen));
```
**输出**
```text
8
```
辰年属申子辰组，小限从戌宫起，戌宫的索引是 8。
***
## get\_brightness [#get_brightness]
**用途** 查某颗星落在某宫时的亮度。
**签名**
```rust
pub fn get_brightness(star: StarKey, palace_index: i32, config: &Config) -> Option
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------- | -- | -- | --------------- |
| `star` | `StarKey` | 是 | — | 星耀标识 |
| `palace_index` | `i32` | 是 | — | 宫位索引，越界会对 12 取模 |
| `config` | `&Config` | 是 | — | 自定义亮度表会改变结果 |
**返回值** `Option`。该星没有亮度表时为 `None`。
**示例**
```rust
let cfg = Config::default();
println!("{:?}", utils::get_brightness(StarKey::ZiweiMaj, 4, &cfg));
println!("{:?}", utils::get_brightness(StarKey::LucunMin, 0, &cfg));
```
**输出**
```text
Some(Miao)
None
```
紫微在午宫（索引 4）庙；禄存没有亮度表。
***
## get\_mutagen / get\_mutagens\_by\_heavenly\_stem [#get_mutagen--get_mutagens_by_heavenly_stem]
**用途** 查天干四化。
**斗数含义** 十天干各自固定指派四颗星化禄、权、科、忌。
`get_mutagen` 问「这颗星在这个天干下化什么」，
`get_mutagens_by_heavenly_stem` 问「这个天干化哪四颗星」。
**签名**
```rust
pub fn get_mutagen(star: StarKey, stem: HeavenlyStem, config: &Config) -> Option
pub fn get_mutagens_by_heavenly_stem(stem: HeavenlyStem, config: &Config) -> [StarKey; 4]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | -------------- | -- | -- | ----------- |
| `star` | `StarKey` | 是 | — | 星耀标识 |
| `stem` | `HeavenlyStem` | 是 | — | 天干 |
| `config` | `&Config` | 是 | — | 自定义四化表会改变结果 |
**返回值** `get_mutagen` 返回 `Option`，该星不在此天干的四化表内时为 `None`。
`get_mutagens_by_heavenly_stem` 返回定长四项数组，顺序为**禄、权、科、忌**。
**示例**
```rust
let cfg = Config::default();
println!("{:?}", utils::get_mutagen(StarKey::TaiyangMaj, HeavenlyStem::Geng, &cfg));
println!("{:?}", utils::get_mutagen(StarKey::ZiweiMaj, HeavenlyStem::Geng, &cfg));
println!("{:?}", utils::get_mutagens_by_heavenly_stem(HeavenlyStem::Geng, &cfg)
.iter().map(|s| translate_star(*s, Language::ZhCN)).collect::>());
```
**输出**
```text
Some(Lu)
None
["太阳", "武曲", "太阴", "天同"]
```
***
## get\_soul\_and\_body [#get_soul_and_body]
**用途** 由农历月索引、时辰与年干推命宫、身宫。
**斗数含义** 命宫是整张盘的起点：从寅宫起正月，顺数到生月，再从生月逆数到生时。
身宫用同样的起点但顺数生时。命宫的天干由五虎遁从年干推得。
**签名**
```rust
pub fn get_soul_and_body(month_index: usize, time_index: u8, yearly_stem: HeavenlyStem) -> SoulAndBody
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | -------------- | -- | -- | ---------------------------------------- |
| `month_index` | `usize` | 是 | — | 农历月索引，正月为 0；由 `fix_lunar_month_index` 求得 |
| `time_index` | `u8` | 是 | — | 时辰索引 0–12 |
| `yearly_stem` | `HeavenlyStem` | 是 | — | 生年天干 |
**返回值** `SoulAndBody`，含 `soul_index`、`body_index`、`heavenly_stem_of_soul`、`earthly_branch_of_soul`。
**示例**
```rust
let sb = get_soul_and_body(6, 2, HeavenlyStem::Geng);
println!("命宫索引 {} 身宫索引 {} 命宫支 {}", sb.soul_index, sb.body_index,
translate_earthly_branch(sb.earthly_branch_of_soul, Language::ZhCN));
```
**输出**
```text
命宫索引 4 身宫索引 8 命宫支 午
```
***
## get\_five\_elements\_class [#get_five_elements_class]
**用途** 由命宫干支推五行局。
**斗数含义** 五行局（水二、木三、金四、土五、火六）决定两件大事：
紫微星的起宫位置，以及大限的起运岁数。
**签名**
```rust
pub fn get_five_elements_class(stem: HeavenlyStem, branch: EarthlyBranch) -> FiveElementsClass
```
**返回值** `FiveElementsClass`。
**示例**
```rust
let c = get_five_elements_class(HeavenlyStem::Ren, EarthlyBranch::Wu);
println!("{}", translate_five_elements_class(c, Language::ZhCN));
```
**输出**
```text
木三局
```
***
## get\_palace\_names [#get_palace_names]
**用途** 由命宫索引推十二宫名。
**斗数含义** 命宫定下后，其余十一宫按固定顺序逆时针排开：
命、兄弟、夫妻、子女、财帛、疾厄、迁移、仆役、官禄、田宅、福德、父母。
**签名**
```rust
pub fn get_palace_names(soul_index: usize) -> [Palace; 12]
```
**返回值** 定长十二项数组，**按宫位索引排列**——第 `i` 项就是 `chart.palaces[i]` 的宫名。
**示例**
```rust
let names = get_palace_names(4);
println!("{:?}", names.iter().take(4).map(|p| translate_palace(*p, Language::ZhCN)).collect::>());
```
**输出**
```text
["财帛", "子女", "夫妻", "兄弟"]
```
命宫在索引 4，因此索引 0（寅宫）是财帛。
***
## get\_decadals\_and\_ages [#get_decadals_and_ages]
**用途** 由命宫索引与五行局推十二宫的大限与小限。
**斗数含义** 大限从命宫起、每宫十年，起运岁数即五行局的局数
（水二局 2 岁起、木三局 3 岁起，依此类推），顺逆由性别阴阳与年支阴阳决定；
小限从年支所属三合组定的宫起，按虚岁逐年走一宫。
**签名**
```rust
pub fn get_decadals_and_ages(
soul_index: usize,
five_elements_class: FiveElementsClass,
gender: Gender,
yearly_stem: HeavenlyStem,
yearly_branch: EarthlyBranch,
) -> ([Decadal; 12], [Vec; 12])
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------- | ------------------- | -- | -- | ---------------- |
| `soul_index` | `usize` | 是 | — | 命宫宫位索引 |
| `five_elements_class` | `FiveElementsClass` | 是 | — | 五行局，决定起运岁数与紫微起宫 |
| `gender` | `Gender` | 是 | — | 性别，与年支阴阳共同决定大限顺逆 |
| `yearly_stem` | `HeavenlyStem` | 是 | — | 年干 |
| `yearly_branch` | `EarthlyBranch` | 是 | — | 年支，决定小限起宫 |
**返回值** `([Decadal; 12], [Vec; 12])`——两个定长十二项数组，均按宫位索引排列。
`Decadal` 的字段：
| 字段 | 类型 | 说明 |
| ---------------- | --------------- | ---------- |
| `range` | `(u32, u32)` | 大限起止虚岁，含两端 |
| `heavenly_stem` | `HeavenlyStem` | 该大限的天干 |
| `earthly_branch` | `EarthlyBranch` | 该大限的地支 |
第二项是每宫的小限虚岁列表。
**示例**
```rust
let (decadals, ages) = astro::palace::get_decadals_and_ages(
4,
FiveElementsClass::Wood3rd,
Gender::Female,
HeavenlyStem::Geng,
EarthlyBranch::Chen,
);
let d = &decadals[0];
println!("寅宫 {:?} 岁 {}{}", d.range,
translate_heavenly_stem(d.heavenly_stem, Language::ZhCN),
translate_earthly_branch(d.earthly_branch, Language::ZhCN));
println!("{:?}", &ages[0][..3]);
```
**输出**
```text
寅宫 (43, 52) 岁 戊寅
[9, 21, 33]
```
**边界与陷阱**
整盘排出的每个宫位上已有 `decadal` 与 `ages` 字段，内容与本函数一致。
这个函数用于不排整盘、只推大限小限的场合。
***
## fix\_lunar\_month\_index / fix\_lunar\_day\_index [#fix_lunar_month_index--fix_lunar_day_index]
**用途** 求修正后的农历月索引与日索引。
**斗数含义** 闰月归属与晚子时归属是斗数两个长期有争议的边界，这两个函数把规则落定：
闰月十六日起按下月算（可关，且晚子时不进位），晚子时的日索引属次日。
**签名**
```rust
pub fn fix_lunar_month_index(
lunar_month: u32,
lunar_day: u32,
is_leap: bool,
time_index: u8,
fix_leap: bool,
) -> usize
pub fn fix_lunar_day_index(lunar_day: u32, time_index: u8) -> u32
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ------ | -- | -- | --------- |
| `lunar_month` | `u32` | 是 | — | 农历月份 1–12 |
| `lunar_day` | `u32` | 是 | — | 农历日 |
| `is_leap` | `bool` | 是 | — | 该月是否闰月 |
| `time_index` | `u8` | 是 | — | 时辰索引 |
| `fix_leap` | `bool` | 是 | — | 是否启用闰月修正 |
**返回值** 月索引为 0-based（正月为 0）；日索引在晚子时不减一。
`fix_lunar_month_index` 进位要同时满足四个条件：`is_leap` 为真、`fix_leap` 为真、
`lunar_day` 大于 15、且 `time_index` 不是 12。四者缺一，就按本月算。
**示例**
```rust
println!("{}", astro::builder::fix_lunar_month_index(7, 17, false, 2, true));
println!("{} {}", astro::builder::fix_lunar_day_index(17, 2), astro::builder::fix_lunar_day_index(17, 12));
```
**输出**
```text
6
16 17
```
七月非闰月，索引为 6；十七日在寅时减一得 16，在晚子时属次日故保持 17。
***
## translate\_chinese\_date [#translate_chinese_date]
**用途** 把四柱干支拼成展示串。
**签名**
```rust
pub fn translate_chinese_date(
pillars: [(HeavenlyStem, EarthlyBranch); 4],
lang: Language,
) -> String
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | ------------------------------------ | -- | -- | ------------- |
| `pillars` | `[(HeavenlyStem, EarthlyBranch); 4]` | 是 | — | 四柱，顺序为年、月、日、时 |
| `lang` | `Language` | 是 | — | 输出语言 |
**返回值** `String`。词条均为单字符时柱内紧凑相连、柱间空格；
任一词条为多字符时柱内空格、柱间 `-`。
**示例**
```rust
let pillars = [
(HeavenlyStem::Geng, EarthlyBranch::Chen),
(HeavenlyStem::Jia, EarthlyBranch::Shen),
(HeavenlyStem::Bing, EarthlyBranch::Wu),
(HeavenlyStem::Geng, EarthlyBranch::Yin),
];
println!("{}", utils::translate_chinese_date(pillars, Language::ZhCN));
println!("{}", utils::translate_chinese_date(pillars, Language::EnUS));
```
**输出**
```text
庚辰 甲申 丙午 庚寅
geng chen - jia shen - bing woo - geng yin
```
星盘的 `chinese_date` 字段即由此生成，四柱枚举可从 `chart.raw_dates.chinese_date` 取。
## merge\_stars [#merge_stars]
**用途** 把多组「十二宫星耀」按宫位合并成一组。
**斗数含义** 安星是分批进行的：主星、辅星、杂耀各出一组十二宫列表。
要把它们并成一张完整盘面时用这个函数。
**签名**
```rust
pub fn merge_stars(groups: &[[Vec; 12]]) -> [Vec; 12]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | -------------------- | -- | -- | ---------- |
| `groups` | `&[[Vec; 12]]` | 是 | — | 若干组十二宫星耀列表 |
**返回值** 合并后的十二宫列表，同宫内按传入顺序首尾相接。
**示例**
```rust
use x_iztro::{star::query::{self, StarParam}, utils, Config, Gender, Language};
let param = StarParam {
solar_date: "2000-8-16",
time_index: 2,
gender: Gender::Female,
fix_leap: true,
from: None,
language: Language::ZhCN,
config: &Config::default(),
};
let major = query::get_major_stars(¶m)?;
let minor = query::get_minor_stars(¶m)?;
let merged = utils::merge_stars(&[major, minor]);
println!("{:?}", merged[0].iter().map(|s| s.name.as_str()).collect::>());
```
**输出**
```text
["武曲", "天相", "天马"]
```
数组长度由类型系统保证为 12，因此不会出现 Python / Go 侧那种长度校验失败。
***
## parse\_heavenly\_stem / parse\_earthly\_branch [#parse_heavenly_stem--parse_earthly_branch]
**用途** 把中文单字的干支还原成枚举。
**斗数含义** 外部系统（八字排盘、老命书录入）常以中文单字给干支。
这两个函数是把那种输入接进来的入口。
**签名**
```rust
pub fn parse_heavenly_stem(s: &str) -> Option
pub fn parse_earthly_branch(s: &str) -> Option
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --- | ------ | -- | -- | ------------------ |
| `s` | `&str` | 是 | — | 中文单字，如 `"甲"`、`"子"` |
**返回值** `Option<...>`。只认中文单字，不认拼音、不认其他语言的译名，也不做去空白——
不匹配返回 `None`。
**示例**
```rust
use x_iztro::astro::builder::{parse_earthly_branch, parse_heavenly_stem};
println!("{:?} {:?}", parse_heavenly_stem("庚"), parse_earthly_branch("辰"));
println!("{:?} {:?}", parse_heavenly_stem("geng"), parse_heavenly_stem("庚 "));
```
**输出**
```text
Some(Geng) Some(Chen)
None None
```
**边界与陷阱**
这两个函数只处理中文单字。收任意语言的译名请走
[`key_of`](/zh/docs/rust/i18n#key_of)，它返回 i18n key，
再用 `HeavenlyStem::from_key` / `EarthlyBranch::from_key` 转成枚举。
它们在 `x_iztro::astro::builder` 下，未在 crate 根重导出，需要写全路径。
# 安星模块 (/zh/docs/rust/star)
按出生数据取某一组星耀的落宫，以及排盘流水线的低层构件。
不排整盘、只想知道「禄存落在哪一宫」或「这张盘的杂耀怎么分布」时用这一层。
模块分两层：
| 层 | 收什么 | 用途 |
| ----------------------------------------------------------------- | ------ | ---------------- |
| `star::query` | 出生数据 | 对外的安星入口，本页主体 |
| `star::location` / `decorative` / `major` / `minor` / `adjective` | 已算好的索引 | 排盘流水线的构件，自建流程时复用 |
所有索引都是**宫位索引**：0 为寅宫，11 为丑宫。
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
## StarParam [#starparam]
`star::query` 的全部入口共用这一个参数结构。
```rust
pub struct StarParam<'a> {
pub solar_date: &'a str,
pub time_index: u8,
pub gender: Gender,
pub fix_leap: bool,
pub from: Option<(HeavenlyStem, EarthlyBranch)>,
pub language: Language,
pub config: &'a Config,
}
```
| 字段 | 类型 | 说明 |
| ------------ | --------------------------------------- | ---------------------- |
| `solar_date` | `&str` | 公历日期，格式 `YYYY-M-D` |
| `time_index` | `u8` | 时辰索引 0–12 |
| `gender` | `Gender` | 性别，决定长生与博士十二神的顺逆 |
| `fix_leap` | `bool` | 是否修正闰月 |
| `from` | `Option<(HeavenlyStem, EarthlyBranch)>` | 起五行局的干支；`None` 时由命宫干支起 |
| `language` | `Language` | 星耀名称的输出语言 |
| `config` | `&Config` | 排盘配置 |
```rust
use x_iztro::star::query::StarParam;
let cfg = Config::default();
let param = StarParam {
solar_date: "2000-8-16",
time_index: 2,
gender: Gender::Female,
fix_leap: true,
from: None,
language: Language::ZhCN,
config: &cfg,
};
```
`from` 给出后，五行局改由该干支推算，进而改变紫微天府落点与长生十二神。
其余各组星的起法不受影响。用它可以取到中州派地盘、人盘的安星结果。
***
## get\_start\_index [#get_start_index]
**用途** 求紫微、天府的起始宫位。
**斗数含义** 紫微是全盘的锚点：由五行局与农历生日按「起紫微星诀」定位，
其余十三颗主星再依紫微与天府的位置铺开。天府与紫微的位置互为镜像。
**签名**
```rust
pub fn get_start_index(param: &StarParam) -> Result
```
**返回值** `StartIndex { ziwei: usize, tianfu: usize }`。
**示例**
```rust
let s = star::query::get_start_index(¶m)?;
println!("紫微 {} 天府 {}", s.ziwei, s.tianfu);
```
**输出**
```text
紫微 4 天府 8
```
**边界与陷阱**
`from` 给出不同干支时结果随之改变——这正是中州派三张盘差异的来源。
***
## 各组落宫索引 [#各组落宫索引]
以下六个入口形状一致：收 `&StarParam`，返回一个字段全是宫位索引的结构体。
| 函数 | 返回类型 | 字段 | 起法依据 |
| -------------------------- | ------------- | ---------------------- | ----------------- |
| `get_lu_yang_tuo_ma_index` | `LuYangTuoMa` | `lu` `yang` `tuo` `ma` | 年干定禄存，禄前羊后陀；天马按年支 |
| `get_kui_yue_index` | `KuiYue` | `kui` `yue` | 年干 |
| `get_chang_qu_index` | `ChangQu` | `chang` `qu` | 时支 |
| `get_kong_jie_index` | `KongJie` | `kong` `jie` | 时支 |
| `get_timely_star_index` | `TimelyStars` | `taifu` `fenggao` | 时支 |
| `get_luan_xi_index` | `LuanXi` | `hongluan` `tianxi` | 年支 |
**示例**
```rust
use x_iztro::star::query as sq;
let l = sq::get_lu_yang_tuo_ma_index(¶m)?;
println!("禄存 {} 擎羊 {} 陀罗 {} 天马 {}", l.lu, l.yang, l.tuo, l.ma);
let c = sq::get_chang_qu_index(¶m)?;
println!("文昌 {} 文曲 {}", c.chang, c.qu);
let lx = sq::get_luan_xi_index(¶m)?;
println!("红鸾 {} 天喜 {}", lx.hongluan, lx.tianxi);
```
**输出**
```text
禄存 6 擎羊 7 陀罗 5 天马 0
文昌 6 文曲 4
红鸾 9 天喜 3
```
擎羊在禄存前一格、陀罗在后一格，这是「禄前羊刃当，禄后陀罗府」的直接体现。
***
## get\_daily\_star\_index / get\_monthly\_star\_index / get\_yearly\_star\_index [#get_daily_star_index--get_monthly_star_index--get_yearly_star_index]
**用途** 取按日、按月、按年起的杂耀落宫。
**斗数含义** 杂耀按起法分组：日系星从辅星位置起初一顺数到生日；
月系星按农历月份定位；年系星最多，按年干或年支起。
**签名**
```rust
pub fn get_daily_star_index(param: &StarParam) -> Result
pub fn get_monthly_star_index(param: &StarParam) -> Result
pub fn get_yearly_star_index(param: &StarParam) -> Result
```
**返回值**
| 类型 | 字段 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DailyStar` | `santai` `bazuo` `enguang` `tiangui` |
| `MonthlyStar` | `jieshen` `tianyao` `tianxing` `yinsha` `tianyue` `tianwu` |
| `YearlyStars` | 29 项：`tiancai` `tianshou` `tianchu` `posui` `feilian` `longchi` `fengge` `tianku` `tianxu` `tianguan` `tianfu` `tiande` `yuede` `tiankong` `jielu` `kongwang` `xunkong` `jiekong` `tianshang` `tianshi` `huagai` `xianchi` `guchen` `guasu` `jiesha` `nianjie` `dahao` `hongluan` `tianxi` |
**示例**
```rust
let d = sq::get_daily_star_index(¶m)?;
println!("三台 {} 八座 {} 恩光 {} 天贵 {}", d.santai, d.bazuo, d.enguang, d.tiangui);
let m = sq::get_monthly_star_index(¶m)?;
println!("解神 {} 天姚 {} 天刑 {}", m.jieshen, m.tianyao, m.tianxing);
let y = sq::get_yearly_star_index(¶m)?;
println!("咸池 {} 华盖 {} 天伤 {} 天使 {}", y.xianchi, y.huagai, y.tianshang, y.tianshi);
```
**输出**
```text
三台 0 八座 10 恩光 9 天贵 7
解神 0 天姚 5 天刑 1
咸池 7 华盖 2 天伤 9 天使 11
```
**边界与陷阱**
年系杂耀属流年神煞，取年支时用的是 `horoscope_divide` 而非 `year_divide`。
两个配置不同时，年系星与主星、辅星可能基于不同的年支——这是刻意的流派区分。
`YearlyStars` 里带 `hongluan` / `tianxi` 两项，`get_luan_xi_index` 也单独给这两颗。
两者取值一致，区别只在 `get_luan_xi_index` 不必算其余二十七颗。
这三项只在 `algorithm` 为中州派时进入盘面，替换掉截路、空亡与大耗的默认取法；
默认派别下它们仍会被算出来，只是不安进宫位。
***
## get\_major\_stars / get\_minor\_stars / get\_adjective\_stars [#get_major_stars--get_minor_stars--get_adjective_stars]
**用途** 取主星、辅星、杂耀在十二宫的完整分布。
**签名**
```rust
pub fn get_major_stars(param: &StarParam) -> Result<[Vec; 12], IztroError>
pub fn get_minor_stars(param: &StarParam) -> Result<[Vec; 12], IztroError>
pub fn get_adjective_stars(param: &StarParam) -> Result<[Vec; 12], IztroError>
```
**返回值** 定长十二项数组，按宫位索引排列。每项是该宫的星耀列表（可能为空）。
**示例**
```rust
let major = sq::get_major_stars(¶m)?;
for (i, stars) in major.iter().take(5).enumerate() {
println!("[{i}] {:?}", stars.iter().map(|s| s.name.as_str()).collect::>());
}
```
**输出**
```text
[0] ["武曲", "天相"]
[1] ["太阳", "天梁"]
[2] ["七杀"]
[3] ["天机"]
[4] ["紫微"]
```
**边界与陷阱**
返回的 `Star` 带亮度与生年四化标记，与整盘排出的完全一致——
它们走的是同一段代码。要取整盘的话直接用 `by_solar` 更省事。
***
## get\_changsheng12 / get\_boshi12 / get\_yearly12 [#get_changsheng12--get_boshi12--get_yearly12]
**用途** 取四组十二神在十二宫的排列。
**斗数含义** 这四组各是十二个标记排满十二宫，每宫恰好一个：
长生十二神按五行局起、随性别与年支阴阳定顺逆；
博士十二神从禄存起、同样定顺逆；
岁前十二神从年支起顺行；将前十二神按年支三合组起。
**签名**
```rust
pub fn get_changsheng12(param: &StarParam) -> Result<[StarKey; 12], IztroError>
pub fn get_boshi12(param: &StarParam) -> Result<[StarKey; 12], IztroError>
pub fn get_yearly12(param: &StarParam) -> Result<([StarKey; 12], [StarKey; 12]), IztroError>
```
**返回值** 定长十二项数组，按宫位索引排列。
`get_yearly12` 一次返回两组，顺序为 `(岁前十二神, 将前十二神)`。
**示例**
```rust
let cs = sq::get_changsheng12(¶m)?;
println!("{:?}", cs.iter().take(4).map(|s| translate_star(*s, Language::ZhCN)).collect::>());
let (suiqian, jiangqian) = sq::get_yearly12(¶m)?;
println!("{:?}", suiqian.iter().take(4).map(|s| translate_star(*s, Language::ZhCN)).collect::>());
println!("{:?}", jiangqian.iter().take(4).map(|s| translate_star(*s, Language::ZhCN)).collect::>());
```
**输出**
```text
["绝", "墓", "死", "病"]
["吊客", "病符", "岁建", "晦气"]
["岁驿", "息神", "华盖", "劫煞"]
```
***
## get\_changsheng12\_start\_index / get\_jiangqian12\_start\_index [#get_changsheng12_start_index--get_jiangqian12_start_index]
**用途** 只取两组十二神的起始宫位，不排整组。
**斗数含义** 长生起点由五行局定：水二局长生在申、木三局在亥、金四局在巳、
土五局在申、火六局在寅。将星起点由年支三合组定：寅午戌年在午、申子辰年在子、
巳酉丑年在酉、亥卯未年在卯。
**签名**
```rust
pub fn get_changsheng12_start_index(five_elements_class: FiveElementsClass) -> usize
pub fn get_jiangqian12_start_index(yearly_branch: EarthlyBranch) -> usize
```
**返回值** `usize`，0–11。这两个函数不需要出生数据，也不会失败。
**示例**
```rust
use x_iztro::star::decorative::{get_changsheng12_start_index, get_jiangqian12_start_index};
println!("{} {}",
get_changsheng12_start_index(FiveElementsClass::Water2nd),
get_changsheng12_start_index(FiveElementsClass::Fire6th));
println!("{} {}",
get_jiangqian12_start_index(EarthlyBranch::Zi),
get_jiangqian12_start_index(EarthlyBranch::Wu));
```
**输出**
```text
6 0
10 4
```
水二局长生在申（索引 6），火六局在寅（索引 0）。
***
## get\_horoscope\_stars [#get_horoscope_stars]
**用途** 取某个运限层级的流耀分布。
**斗数含义** 流耀是随运限产生的十颗星：魁钺昌曲禄羊陀马鸾喜。
它们的落宫由该层级的干支决定，名字随层级变化。流年层级额外多一颗年解。
**签名**
```rust
pub fn get_horoscope_stars(
stem: HeavenlyStem,
branch: EarthlyBranch,
scope: Scope,
lang: Language,
) -> [Vec; 12]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | --------------- | -- | -- | --------- |
| `stem` | `HeavenlyStem` | 是 | — | 该层级的天干 |
| `branch` | `EarthlyBranch` | 是 | — | 该层级的地支 |
| `scope` | `Scope` | 是 | — | 运限层级，决定星名 |
| `lang` | `Language` | 是 | — | 输出语言 |
**返回值** 定长十二项数组，按宫位索引排列。不会失败——入参是枚举，无非法值。
**各层级的星名对照**
| 本命 | 大限 | 流年 | 流月 | 流日 | 流时 |
| -- | -- | -- | -- | -- | -- |
| 天魁 | 运魁 | 流魁 | 月魁 | 日魁 | 时魁 |
| 天钺 | 运钺 | 流钺 | 月钺 | 日钺 | 时钺 |
| 文昌 | 运昌 | 流昌 | 月昌 | 日昌 | 时昌 |
| 文曲 | 运曲 | 流曲 | 月曲 | 日曲 | 时曲 |
| 禄存 | 运禄 | 流禄 | 月禄 | 日禄 | 时禄 |
| 擎羊 | 运羊 | 流羊 | 月羊 | 日羊 | 时羊 |
| 陀罗 | 运陀 | 流陀 | 月陀 | 日陀 | 时陀 |
| 天马 | 运马 | 流马 | 月马 | 日马 | 时马 |
| 红鸾 | 运鸾 | 流鸾 | 月鸾 | 日鸾 | 时鸾 |
| 天喜 | 运喜 | 流喜 | 月喜 | 日喜 | 时喜 |
**示例**
```rust
use x_iztro::astro::horoscope::get_horoscope_stars;
let decadal = get_horoscope_stars(HeavenlyStem::Jia, EarthlyBranch::Zi, Scope::Decadal, Language::ZhCN);
println!("{:?}", decadal.iter().take(4)
.map(|g| g.iter().map(|s| s.name.as_str()).collect::>()).collect::>());
let origin = get_horoscope_stars(HeavenlyStem::Jia, EarthlyBranch::Zi, Scope::Origin, Language::ZhCN);
println!("{:?}", origin.iter().take(2)
.map(|g| g.iter().map(|s| s.name.as_str()).collect::>()).collect::>());
```
**输出**
```text
[["运禄", "运马"], ["运羊", "运鸾"], [], ["运昌"]]
[["禄存", "天马"], ["擎羊", "红鸾"]]
```
**边界与陷阱**
`Scope::Yearly` 的结果里额外含年解，按流年地支定位，安放在十颗流耀之前。
其余层级没有这一颗。
***
## 低层构件 [#低层构件]
`star::location` 与 `star::decorative` 下的函数收已算好的索引而非出生数据。
排盘流水线内部用它们，自建流程时也可复用。
### star::location [#starlocation]
| 函数 | 收 | 返回 |
| ----------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `get_start_index` | `lunar_day, time_index, month_day_count, five_elements_value` | `StartIndex { ziwei, tianfu }` |
| `get_lu_yang_tuo_ma_index` | `stem, branch` | `LuYangTuoMa { lu, yang, tuo, ma }` |
| `get_kui_yue_index` | `stem` | `KuiYue { kui, yue }` |
| `get_zuo_you_index` | `lunar_month` | `ZuoYou { zuo, you }` |
| `get_chang_qu_index` | `time_index` | `ChangQu { chang, qu }` |
| `get_chang_qu_index_by_stem` | `stem` | `ChangQu { chang, qu }`（运限层级用） |
| `get_daily_star_index` | `lunar_day, time_index, zuo_index, you_index, chang_index, qu_index` | `DailyStar { santai, bazuo, enguang, tiangui }` |
| `get_timely_star_index` | `time_index` | `TimelyStars { taifu, fenggao }` |
| `get_kong_jie_index` | `time_index` | `KongJie { kong, jie }` |
| `get_huo_ling_index` | `branch, time_index` | `HuoLing { huo, ling }` |
| `get_luan_xi_index` | `branch` | `LuanXi { hongluan, tianxi }` |
| `get_huagai_xianchi_index` | `branch` | `HuagaiXianchi { huagai, xianchi }` |
| `get_gu_gua_index` | `branch` | `GuGua { guchen, guasu }` |
| `get_jiesha_adj_index` | `branch` | `usize` |
| `get_dahao_index` | `branch` | `usize` |
| `get_nianjie_index` | `branch` | `usize` |
| `get_tianshang_tianshi_index` | `gender, yearly_branch, soul_index, algorithm` | `(usize, usize)`，依次为天伤、天使 |
| `get_tiancai_index` | `yearly_branch, soul_index` | `usize` |
| `get_monthly_star_index` | `month_index` | `MonthlyStar { jieshen, tianyao, tianxing, yinsha, tianyue, tianwu }` |
| `get_yearly_star_index` | `soul_index, body_index, yearly_stem, yearly_branch, gender, algorithm` | `YearlyStars`（上面那 29 项） |
所有结构体的字段都是 `usize` 宫位索引（0 为寅宫），
`get_tianshang_tianshi_index` 返回的是裸元组而非具名结构体。
### star::decorative [#stardecorative]
| 函数 | 收 | 返回 |
| ------------------------------ | --------------------------------- | ----------------------------------------- |
| `get_changsheng12_start_index` | `five_elements_class` | `usize` |
| `get_jiangqian12_start_index` | `yearly_branch` | `usize` |
| `get_changsheng12` | 五行局、性别、年支等 | `[StarKey; 12]` |
| `get_boshi12` | `lu_index, gender, yearly_branch` | `[StarKey; 12]` |
| `get_yearly12` | 年支等 | `([StarKey; 12], [StarKey; 12])`，依次为岁前、将前 |
### star::major / minor / adjective [#starmajor--minor--adjective]
`get_major_stars`、`get_minor_stars`、`get_adjective_stars`——
与 `star::query` 下的同名函数同名不同参：这一层收已算好的索引，那一层收出生数据。
两层有若干同名函数（如两个 `get_start_index`），靠模块路径区分：
`star::query::get_start_index` 收 `&StarParam`，
`star::location::get_start_index` 收农历日、时辰、当月天数与五行局局数。
同时 `use` 两个模块时请用限定路径。
从出生数据到这些构件所需中间量的推算收在 `astro::context::derive`，
自建流程时先调它拿到上下文，再喂给构件即可，不必自己重推年干支与命宫。
# 数据表 (/zh/docs/rust/data)
枚举与它们的方法、排盘配置、星耀基础信息、天干地支信息与顺序常量。
`x_iztro::data` 收着两类东西：贯穿全库的**枚举**（星盘字段与几乎所有函数参数的类型），
以及排盘算法的**输入表**。两者都与输出语言无关——它们是算法的输入而非结果。
常用枚举都在 crate 根重导出，`use x_iztro::*;` 即可用。
***
## 枚举 [#枚举]
十九个枚举 + `StarKey`。所有枚举都实现 `Debug`、`Clone`、`Copy`、`PartialEq`、`Eq`
与 serde 的 `Serialize` / `Deserialize`，可以直接比较、直接放进集合。
### 语言无关标识：as\_key / from\_key [#语言无关标识as_key--from_key]
绝大多数枚举带一对互逆的方法，把变体与 iztro i18n key 字符串来回换。
这套 key 就是 DTO 里 `*Key` 字段的取值，也是 Python 枚举与 Go 常量的值——
三侧写同一个字符串，判断结果一致。
| 枚举 | 变体数 | 取标识 | 由标识还原 | key 举例 |
| ------------------- | --- | ---------- | ---------------- | -------------------------------- |
| `StarKey` | 162 | `as_key()` | `from_key(&str)` | `ziweiMaj`、`yunlu` |
| `Palace` | 12 | `as_key()` | `from_key(&str)` | `soulPalace`、`wealthPalace` |
| `HeavenlyStem` | 10 | `as_key()` | `from_key(&str)` | `jiaHeavenly` |
| `EarthlyBranch` | 12 | `as_key()` | `from_key(&str)` | `ziEarthly` |
| `Mutagen` | 4 | `as_key()` | `from_key(&str)` | `sihuaLu` |
| `Brightness` | 7 | `as_key()` | `from_key(&str)` | `miao` |
| `FiveElementsClass` | 5 | `as_key()` | `from_key(&str)` | `water2nd` |
| `StarType` | 8 | `as_key()` | — | `major`、`lucun` |
| `Scope` | 6 | `as_key()` | `from_key(&str)` | `origin`、`decadal` |
| `YearDivide` | 2 | `as_key()` | `from_key(&str)` | `normal` / `exact` |
| `HoroscopeDivide` | 2 | `as_key()` | `from_key(&str)` | `normal` / `exact` |
| `AgeDivide` | 2 | `as_key()` | `from_key(&str)` | `normal` / `birthday` |
| `DayDivide` | 2 | `as_key()` | `from_key(&str)` | `forward` / `current` |
| `Algorithm` | 2 | `as_key()` | `from_key(&str)` | `default` / `zhongzhou` |
| `AstroType` | 3 | `as_key()` | `from_key(&str)` | `heaven` / `earth` / `human` |
| `LeapMonth` | 3 | `as_key()` | `from_key(&str)` | `notLeap` / `leap` / `leapFixed` |
`from_key` 一律返回 `Option`，未知标识给 `None`——绑定层据此拒绝非法入参。
```rust
println!("{}", StarKey::ZiweiMaj.as_key());
println!("{:?}", StarKey::from_key("taiyinMaj"));
println!("{:?}", StarKey::from_key("nosuch"));
println!("{} {}", Palace::Soul.as_key(), AstroType::Earth.as_key());
println!("{:?}", DayDivide::from_key("current"));
```
**输出**
```text
ziweiMaj
Some(TaiyinMaj)
None
soulPalace earth
Some(Current)
```
### 其余方法 [#其余方法]
| 枚举 | 方法 | 说明 |
| ------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `HeavenlyStem` | `index() -> usize` / `from_index(usize)` | 天干序号，甲 = 0 … 癸 = 9 |
| `EarthlyBranch` | `index() -> usize` / `from_index(usize)` | 地支序号，子 = 0 … 亥 = 11。**不是宫位索引**，换算用 [`earthly_branch_to_palace_index`](/zh/docs/rust/util#earthly_branch_to_palace_index) |
| `Palace` | `index() -> usize` / `from_index(usize)` | 宫名在 `PALACES` 里的序号，命宫 = 0、父母 = 1 …… 兄弟 = 11。**不是盘上位置**；`from_index` 对 12 取模、不返回 `Option` |
| `FiveElementsClass` | `value() -> usize` | 局数：水二局 2、木三局 3、金四局 4、土五局 5、火六局 6 |
| `Gender` | `yin_yang() -> YinYang` | 男为阳、女为阴，决定大限与长生十二神的顺逆 |
| `Language` | `as_code() -> &'static str` / `from_code(&str)` | 语言代码 `zh-CN` 等；`from_code` 大小写不敏感，连字符与下划线等价（`zh_cn` 也接受） |
| `YinYang` | `as_str() -> &'static str` | 「阳」/「阴」，不参与国际化 |
| `FiveElements` | `as_str() -> &'static str` | 「木」「金」「水」「火」「土」，不参与国际化 |
```rust
println!("{} {}", HeavenlyStem::Gui.index(), EarthlyBranch::Hai.index());
println!("{:?}", Palace::from_index(4));
println!("{}", FiveElementsClass::Wood3rd.value());
println!("{:?} {}", Gender::Female.yin_yang(), Gender::Female.yin_yang().as_str());
println!("{} {:?}", Language::JaJP.as_code(), Language::from_code("ZH-cn"));
```
**输出**
```text
9 11
Career
3
Yin 阴
ja-JP Some(ZhCN)
```
### 变体清单 [#变体清单]
只列非「一眼可推」的几个；干支、宫名、星耀的变体名与它们的 key 一一对应。
| 枚举 | 变体 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `YinYang` | `Yang` `Yin` |
| `FiveElements` | `Wood` `Metal` `Water` `Fire` `Earth` |
| `FiveElementsClass` | `Water2nd` `Wood3rd` `Metal4th` `Earth5th` `Fire6th` |
| `Mutagen` | `Lu` `Quan` `Ke` `Ji` |
| `Brightness` | `Miao` `Wang` `De` `Li` `Ping` `Bu` `Xian` |
| `StarType` | `Major` `Soft` `Tough` `Adjective` `Flower` `Helper` `Lucun` `Tianma` |
| `Scope` | `Origin` `Decadal` `Yearly` `Monthly` `Daily` `Hourly` |
| `HoroscopeName` | `Decadal` `Childhood` `Age` `Yearly` `Monthly` `Daily` `Hourly` |
| `Gender` | `Male` `Female` |
| `Language` | `ZhCN` `ZhTW` `EnUS` `JaJP` `KoKR` `ViVN` |
| `LeapMonth` | `NotLeap` `Leap` `LeapFixed`——`by_lunar` 的闰月处理方式；另有 `from_flags(is_leap_month, fix_leap)`、`is_leap_month()`、`fix_leap()` 与 iztro 风格的两个布尔互换 |
| `Palace` | 按 `index()` 序：`Soul` `Parents` `Spirit` `Property` `Career` `Friends` `Surface` `Health` `Wealth` `Children` `Spouse` `Siblings` |
| `PalaceTarget` | `Index(usize)` `Name(Palace)` `Body` `Original` |
`IztroError`、`StarType`、`Scope`、`Algorithm`、`AstroType` 标了 `#[non_exhaustive]`，
crate 外的 `match` 必须带兜底分支。将来新增变体因此不是破坏性变更。
`Scope` 比 `HoroscopeName` 少一个 `Childhood`：童限不是独立的查询层级，
它只是大限的显示名——未起运时 `h.decadal.name` 显示「童限」，`Scope::Decadal` 照常用。
`TimeIndex` 是 `u8` 的类型别名，仅作可读性标注，没有额外校验。
***
## Config [#config]
排盘配置：六个开关加两张可选的自定义表。`Config::default()` 与 JS iztro 的默认配置一致。
| 字段 | 类型 | 默认值 | 说明 |
| ------------------ | ----------------------------- | --------- | ----------------- |
| `year_divide` | `YearDivide` | `Normal` | 年干支按正月初一还是立春换年 |
| `horoscope_divide` | `HoroscopeDivide` | `Normal` | 运限干支与月柱按初一还是节气推 |
| `age_divide` | `AgeDivide` | `Normal` | 虚岁按自然农历年还是生日进位 |
| `day_divide` | `DayDivide` | `Forward` | 晚子时归次日还是归当天 |
| `algorithm` | `Algorithm` | `Default` | 派别：默认或中州派 |
| `astro_type` | `AstroType` | `Heaven` | 排盘视角：天盘 / 地盘 / 人盘 |
| `overrides` | `Option>` | `None` | 自定义四化与亮度表 |
六个开关的取值语义与流派背景见 [Config 详解](/zh/docs/guide/guides/config)。
`overrides` 标了 `#[serde(skip)]`：它是排盘的**输入**而不是结果，
放进 DTO 会破坏与 JS iztro 的字段契约。因此 JSON 输出里的 `config` 对象只有六个开关，
自定义表不会回显。
### 构造方法 [#构造方法]
字段都是 `pub`，可以直接改；链式写法更省事：
| 方法 | 说明 |
| -------------------------------------------------------------- | --------------------- |
| `with_astro_type(AstroType) -> Config` | 指定排盘视角 |
| `with_mutagens(HeavenlyStem, [StarKey; 4]) -> Config` | 覆盖某个天干的四化表，顺序为禄、权、科、忌 |
| `with_brightness(StarKey, [Option; 12]) -> Config` | 覆盖某颗星的十二宫亮度表，索引 0 为寅宫 |
### 查表方法 [#查表方法]
| 方法 | 说明 |
| ----------------------------------------------------- | ----------------------------- |
| `mutagens_of(HeavenlyStem) -> [StarKey; 4]` | 该天干**实际生效**的四化表：有覆盖用覆盖，否则用默认表 |
| `brightness_of(StarKey, usize) -> Option` | 该星在该宫实际生效的亮度；宫位索引越界对 12 取模 |
**示例**
```rust
let cfg = Config::default()
.with_astro_type(AstroType::Earth)
.with_mutagens(HeavenlyStem::Geng, [
StarKey::TaiyangMaj, StarKey::WuquMaj, StarKey::TianfuMaj, StarKey::TiantongMaj,
]);
println!("{:?}", cfg.astro_type);
println!("{:?}", cfg.mutagens_of(HeavenlyStem::Geng)
.iter().map(|s| translate_star(*s, Language::ZhCN)).collect::>());
println!("{:?}", cfg.mutagens_of(HeavenlyStem::Jia)
.iter().map(|s| translate_star(*s, Language::ZhCN)).collect::>());
println!("{:?}", cfg.brightness_of(StarKey::ZiweiMaj, 4));
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, cfg)?;
println!("{}", translate_five_elements_class(chart.five_elements_class, Language::ZhCN));
```
**输出**
```text
Earth
["太阳", "武曲", "天府", "天同"]
["廉贞", "破军", "武曲", "太阳"]
Some(Miao)
土五局
```
庚干的四化被换成「太阳禄、武曲权、天府科、天同忌」（默认表是太阴化科），
甲干未被覆盖，仍走默认表。
**边界与陷阱**
`with_mutagens` 一次替换某个天干的**全部四位**，不能只换其中一位；
`with_brightness` 一次替换某颗星的**全部十二宫**。未提到的天干与星仍用默认表。
`Config` 含 `Option>`，只实现 `Clone`。要在循环里复用同一份配置，
写 `cfg.clone()`——`Arc` 的克隆是引用计数加一，不复制表本身。
四化表影响：生年四化标记、宫干飞星族方法、运限各层级的四化、
`get_mutagen` / `get_mutagens_by_heavenly_stem`。
亮度表影响：星耀的 `brightness` 字段与 `with_brightness` 判断、`get_brightness`。
两者都不改变星耀落宫。
### TableOverrides [#tableoverrides]
`Config` 里那两张表的载体，一般不必直接构造——用上面两个 `with_*` 即可。
需要一次塞多条时可以自己建：
| 方法 | 说明 |
| ------------------------------------------------------------- | -------------------- |
| `set_mutagens(HeavenlyStem, [StarKey; 4])` | 写入某天干的四化表 |
| `set_brightness(StarKey, [Option; 12])` | 写入某星的亮度表 |
| `mutagens_of(HeavenlyStem) -> Option<&[StarKey; 4]>` | 取被覆盖的四化表，未覆盖为 `None` |
| `brightness_of(StarKey) -> Option<&[Option; 12]>` | 取被覆盖的亮度表 |
| `is_empty() -> bool` | 是否一条覆盖都没有 |
注意与 `Config` 上同名方法的区别：`TableOverrides::mutagens_of` 只报告**有没有被覆盖**，
`Config::mutagens_of` 报告**实际生效**的表（未覆盖时回落到默认表）。
***
## flow\_star\_counterparts [#flow_star_counterparts]
**用途** 流耀 → 对应本命辅星的全量对照表（50 条）。
**签名**
```rust
pub fn flow_star_counterparts() -> Vec<(StarKey, StarKey)>
pub fn natal_counterpart_of_flow_star(key: StarKey) -> Option
```
两者都从 crate 根导出（`use x_iztro::*` 即得）。全量表每项为（流耀，对应本命辅星），
如 `(StarKey::Liuchang, StarKey::WenchangMin)`；单查版本非流耀返回 `None`。
流耀没有独立的知识包条目，释义按对应的本命辅星查，这张表就是官方对照。
***
## get\_star\_info [#get_star_info]
**用途** 取一颗星的亮度表、五行与阴阳。
**签名**
```rust
pub fn get_star_info(key: StarKey) -> Option
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----- | --------- | -- | -- | ---- |
| `key` | `StarKey` | 是 | — | 星耀标识 |
**返回值** `Option`。只有二十颗星有记录，其余返回 `None`。
`StarInfo` 的字段：
| 字段 | 类型 | 说明 |
| --------------- | -------------------------- | ----------------------------- |
| `brightness` | `[Option; 12]` | 十二宫亮度，索引 0 为寅宫；该宫无亮度则为 `None` |
| `five_elements` | `Option` | 五行 |
| `yin_yang` | `Option` | 阴阳 |
有记录的二十颗是**十四主星**加文昌、文曲、火星、铃星、擎羊、陀罗，
即 `STARS_WITH_INFO` 常量列出的那些。
**示例**
```rust
let info = data::stars::get_star_info(StarKey::ZiweiMaj).unwrap();
println!("五行 {:?} 阴阳 {:?}", info.five_elements, info.yin_yang);
println!("寅宫亮度 {:?}", info.brightness[0]);
println!("禄存有记录: {}", data::stars::get_star_info(StarKey::LucunMin).is_some());
```
**输出**
```text
五行 Some(Earth) 阴阳 Some(Yin)
寅宫亮度 Some(Wang)
禄存有记录: false
```
**边界与陷阱**
表中部分星耀的五行或阴阳未填：太阳与七杀两项皆空，
贪狼、天相、天梁、破军的阴阳空，六颗辅星两项皆空。
读到 `None` 表示表里没有这项数据，不是算法产生的中间态。
***
## get\_heavenly\_stem\_info [#get_heavenly_stem_info]
**用途** 取天干的阴阳、五行、对冲天干与四化四星。
**斗数含义** 天干的四化表是四化系统的根：生年干决定生年四化，
宫干决定该宫飞出的四化，运限干决定该层级的四化。
**签名**
```rust
pub fn get_heavenly_stem_info(stem: HeavenlyStem) -> HeavenlyStemInfo
```
**返回值** `HeavenlyStemInfo`，字段：
| 字段 | 类型 | 说明 |
| --------------- | ---------------------- | -------------------- |
| `yin_yang` | `YinYang` | 阴阳 |
| `five_elements` | `FiveElements` | 五行 |
| `crash` | `Option` | 对冲天干；戊、己无对冲，为 `None` |
| `mutagen` | `[StarKey; 4]` | 四化四星，顺序为禄、权、科、忌 |
**示例**
```rust
let jia = data::heavenly_stems::get_heavenly_stem_info(HeavenlyStem::Jia);
println!("{:?} {:?} 对冲 {:?}", jia.yin_yang, jia.five_elements, jia.crash);
println!("{:?}", jia.mutagen.iter().map(|s| translate_star(*s, Language::ZhCN)).collect::>());
println!("戊干对冲 {:?}", data::heavenly_stems::get_heavenly_stem_info(HeavenlyStem::Wu).crash);
```
**输出**
```text
Yang Wood 对冲 Some(Geng)
["廉贞", "破军", "武曲", "太阳"]
戊干对冲 None
```
***
## get\_earthly\_branch\_info [#get_earthly_branch_info]
**用途** 取地支的阴阳、五行、对冲地支、命主身主与身体对应。
**签名**
```rust
pub fn get_earthly_branch_info(branch: EarthlyBranch) -> EarthlyBranchInfo
```
**返回值** `EarthlyBranchInfo`，字段：
| 字段 | 类型 | 说明 |
| --------------- | --------------- | ---------------- |
| `yin_yang` | `YinYang` | 阴阳，决定大限与长生十二神的顺逆 |
| `five_elements` | `FiveElements` | 五行 |
| `crash` | `EarthlyBranch` | 对冲地支 |
| `soul` | `StarKey` | 命主星（按命宫地支查） |
| `body` | `StarKey` | 身主星（按生年地支查） |
| `inside` | `&'static str` | 对应脏腑 |
| `outside` | `&'static str` | 对应身体部位 |
| `health_tip` | `&'static str` | 健康提示 |
`inside` / `outside` / `health_tip` 三项只有中文一种写法，不参与国际化。
**示例**
```rust
let zi = data::earthly_branches::get_earthly_branch_info(EarthlyBranch::Zi);
println!("{:?} {:?} 对冲 {:?}", zi.yin_yang, zi.five_elements, zi.crash);
println!("命主 {} 身主 {}", translate_star(zi.soul, Language::ZhCN), translate_star(zi.body, Language::ZhCN));
println!("{} / {}", zi.inside, zi.outside);
```
**输出**
```text
Yang Water 对冲 Wu
命主 贪狼 身主 火星
胆 / 下体
```
***
## 顺序常量 [#顺序常量]
| 常量 | 类型 | 内容 |
| ------------------ | --------------------- | ---------------------------------------------------- |
| `HEAVENLY_STEMS` | `[HeavenlyStem; 10]` | 天干顺序：甲乙丙丁戊己庚辛壬癸 |
| `EARTHLY_BRANCHES` | `[EarthlyBranch; 12]` | 地支顺序：子丑寅卯辰巳午未申酉戌亥 |
| `PALACES` | `[Palace; 12]` | 十二宫名，从命宫起**逆时针**排：命、父母、福德、田宅、官禄、仆役、迁移、疾厄、财帛、子女、夫妻、兄弟 |
| `LANGUAGES` | `[&str; 6]` | 支持的语言代码 |
| `ZODIAC` | `[&str; 12]` | 生肖标识，按地支顺序 |
| `SIGNS` | `[&str; 12]` | 星座标识，按黄道顺序 |
| `CHINESE_TIME` | `[&str; 13]` | 时辰标识，早子时起、晚子时止 |
| `TIME_RANGES` | `[&str; 13]` | 时辰对应的钟点区间 |
| `TIGER_RULE` | `[HeavenlyStem; 10]` | 五虎遁：年干推正月天干 |
| `RAT_RULE` | `[HeavenlyStem; 10]` | 五鼠遁：日干推子时天干 |
| `MUTAGEN` | `[Mutagen; 4]` | 四化顺序：禄、权、科、忌（在 `data::stars` 下） |
`TIGER_RULE` 与 `RAT_RULE` 按天干序号索引：`TIGER_RULE[0]` 是甲年的正月天干。
**示例**
```rust
use x_iztro::data::constants::*;
println!("{} {} {}", LANGUAGES[0], ZODIAC[0], CHINESE_TIME[12]);
println!("{}", TIME_RANGES[2]);
println!("甲年正月干 {}", translate_heavenly_stem(TIGER_RULE[0], Language::ZhCN));
println!("甲日子时干 {}", translate_heavenly_stem(RAT_RULE[0], Language::ZhCN));
```
**输出**
```text
en-US rat lateRatHour
03:00~05:00
甲年正月干 丙
甲日子时干 甲
```
***
## 星耀枚举清单 [#星耀枚举清单]
| 常量 | 长度 | 内容 |
| ----------------- | --- | ------------------------- |
| `ALL_STARS` | 162 | 全部星耀标识，顺序与 `StarKey` 声明一致 |
| `STARS_WITH_INFO` | 20 | 有 `StarInfo` 记录的那二十颗 |
**示例**
```rust
println!("{} {}", data::stars::ALL_STARS.len(), data::stars::STARS_WITH_INFO.len());
// 列出所有有亮度表的星
for star in data::stars::STARS_WITH_INFO {
print!("{} ", translate_star(star, Language::ZhCN));
}
```
**输出**
```text
162 20
紫微 天机 太阳 武曲 天同 廉贞 天府 太阴 贪狼 巨门 天相 天梁 七杀 破军 文昌 文曲 火星 铃星 擎羊 陀罗
```
***
## get\_brightness\_table [#get_brightness_table]
**用途** 取一颗星的十二宫亮度表原文。
**签名**
```rust
pub fn get_brightness_table(key: StarKey) -> Option<[Option; 12]>
```
**返回值** 定长十二项数组，索引 0 为寅宫；该宫无亮度的位置为 `None`。
没有亮度表的星耀返回外层 `None`。
**示例**
```rust
let t = data::stars::get_brightness_table(StarKey::ZiweiMaj).unwrap();
println!("{:?}", &t[..4]);
println!("{:?}", data::stars::get_brightness_table(StarKey::LucunMin).is_none());
```
**输出**
```text
[Some(Wang), Some(Wang), Some(De), Some(Wang)]
true
```
**边界与陷阱**
`get_brightness_table` 给的是**内置默认表**，不看配置；
[`utils::get_brightness`](/zh/docs/rust/util#get_brightness) 收 `&Config`，
自定义亮度表会改变它的结果。要复核「这张盘上实际用了什么亮度」，用后者。
`get_star_info(key).brightness` 与本函数取值相同，只是顺带给出五行与阴阳。
# 翻译 (/zh/docs/rust/i18n)
标识与译名的双向查找，以及按类目的翻译函数。
星盘上每个字段都同时给出译名与 `*_key` 标识，通常不必手工翻译。
这些函数用于手上只有标识（或只有某种语言的译名）、需要换算的场合。
支持六种语言：`zh-CN`、`zh-TW`、`en-US`、`ja-JP`、`ko-KR`、`vi-VN`。
***
## translate\_key [#translate_key]
**用途** 把任意标识译成指定语言。
**签名**
```rust
pub fn translate_key(key: &str, lang: Language) -> Option<&'static str>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | ---------- | -- | -- | ------ |
| `key` | `&str` | 是 | — | 语言无关标识 |
| `lang` | `Language` | 是 | — | 目标语言 |
覆盖十二类共 260 个标识：
| 类目 | 数量 | 例 |
| ----------- | --- | --------------------------------------------------------- |
| 星耀 | 162 | `ziweiMaj`、`changsheng`、`yunlu` |
| 宫位（含身宫、来因宫） | 14 | `soulPalace`、`wealthPalace`、`bodyPalace`、`originalPalace` |
| 天干 | 10 | `jiaHeavenly` |
| 地支 | 12 | `ziEarthly` |
| 亮度 | 7 | `miao`、`wang` |
| 四化 | 4 | `sihuaLu` |
| 五行局 | 5 | `water2nd` |
| 性别 | 2 | `male`、`female` |
| 生肖 | 12 | `rat`、`ox` |
| 时辰 | 13 | `earlyRatHour` |
| 星座 | 12 | `aries` |
| 运限层级 | 7 | `decadal`、`turn` |
**返回值** `Option<&'static str>`。未知标识返回 `None`。
**示例**
```rust
println!("{:?}", translate_key("ziweiMaj", Language::EnUS));
println!("{:?}", translate_key("soulPalace", Language::JaJP));
println!("{:?}", translate_key("nosuch", Language::ZhCN));
```
**输出**
```text
Some("emperor")
Some("命宮")
None
```
***
## key\_of [#key_of]
**用途** 由任意语言的译名反查标识。
**签名**
```rust
pub fn key_of(text: &str) -> Option<&'static str>
pub fn key_of_in(text: &str, key_filter: &str) -> Option<&'static str>
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------ | -- | -- | ------------------- |
| `text` | `&str` | 是 | — | 任一支持语言下的译名 |
| `key_filter` | `&str` | 是 | — | 限定标识名须含的子串，用于消歧同形译名 |
**返回值** `Option<&'static str>`。查不到返回 `None`。
**示例**
```rust
println!("{:?}", key_of("紫微"));
println!("{:?}", key_of("emperor"));
println!("{:?}", key_of("자미"));
println!("{:?}", key_of("查无此名"));
```
**输出**
```text
Some("ziweiMaj")
Some("ziweiMaj")
Some("ziweiMaj")
None
```
三种语言的译名都落到同一个标识。
**边界与陷阱**
少数译名在多个类目下同形：en-US 的 `horse` 既是生肖马也是天马，
`dragon` 既是生肖龙也是青龙，ko-KR 的 `사` 既是地支巳也是长生12神的死。
`key_of` 逐语言、每种语言内逐标识取先命中者，顺序与 iztro 的 `kot` 完全一致
（有金标测试逐例守着）。要指定类目就用 `key_of_in`——标识名含该子串才纳入比对：
```rust
println!("{:?}", key_of("horse")); // Some("horse")（生肖马）
println!("{:?}", key_of_in("horse", "Min")); // Some("tianmaMin")（天马）
println!("{:?}", key_of("유시")); // Some("hourly")（流时）
println!("{:?}", key_of_in("유시", "Hour")); // Some("roosterHour")（酉时）
println!("{:?}", key_of_in("horse", "Palace")); // None
```
常用子串：`Maj` 十四主星、`Min` 辅星、`Heavenly` / `Earthly` 干支、
`Palace` 宫位、`Hour` 时辰。限定后无匹配返回 `None`，不退回未限定的结果。
`key_of` 会遍历 260 个标识 × 6 种语言。单次调用开销可忽略，
但不要放在每宫每星的内层循环里——那种场合直接用数据自带的 `*_key` 字段。
***
## all\_keys [#all_keys]
**用途** 取全部 260 个可翻译标识。
**签名**
```rust
pub fn all_keys() -> Vec<&'static str>
```
**返回值** `Vec<&'static str>`，顺序即 `key_of` 的反查次序：
运限层级、生肖、时辰、星座、五行局、天干、地支、亮度、四化、星耀、宫位、性别，
与 iztro 各语言翻译文件的合并次序一致。
**示例**
```rust
use x_iztro::i18n::lookup::{all_keys, translate_key};
let keys = all_keys();
println!("{} 个标识", keys.len());
println!("{:?}", &keys[..4]);
println!("{:?}", translate_key(keys[0], Language::ZhCN));
```
**输出**
```text
260 个标识
["decadal", "childhood", "yearly", "monthly"]
Some("大限")
```
要遍历某一类目自己的标识时，直接用 `data` 模块的对应常量
（`ALL_STARS`、`PALACES`、`HEAVENLY_STEMS`、`MUTAGEN` 等）更省事。
***
## 按类目的翻译函数 [#按类目的翻译函数]
标识的类别已知时，用对应的强类型函数更直接，也免去 `Option`。
| 函数 | 入参 |
| ------------------------------- | ---------------------- |
| `translate_star` | `StarKey` |
| `translate_palace` | `Palace` |
| `translate_heavenly_stem` | `HeavenlyStem` |
| `translate_earthly_branch` | `EarthlyBranch` |
| `translate_brightness` | `Brightness` |
| `translate_mutagen` | `Mutagen` |
| `translate_five_elements_class` | `FiveElementsClass` |
| `translate_gender` | `Gender` |
| `translate_zodiac` | `EarthlyBranch` |
| `translate_time` | `u8`（时辰索引 0–12） |
| `translate_sign` | `usize`（星座索引 0–11，白羊起） |
| `translate_horoscope_name` | `HoroscopeName` |
全部形如 `fn(值, Language) -> &'static str`，返回静态字符串不分配内存。
**示例**
```rust
use x_iztro::i18n::{translate_palace, translate_star};
println!("{}", translate_star(StarKey::ZiweiMaj, Language::ViVN));
println!("{}", translate_palace(Palace::Soul, Language::KoKR));
```
**输出**
```text
Tử Vi
명궁
```
***
## 没有全局语言开关 [#没有全局语言开关]
x-iztro 不设「当前语言」这样的全局状态：排盘时语言随参数传入，
翻译函数每次调用都显式指定目标语言。
全局语言开关会让同一段代码在不同调用顺序下产出不同结果，
多线程环境尤其危险。显式传参使每次调用的结果只由入参决定。
要在一个进程里同时输出多种语言，直接排多张盘或多次调用翻译函数即可，互不干扰：
```rust
let zh = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let en = by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS, Config::default())?;
println!("{} / {}", zh.palace(Palace::Soul).unwrap().major_stars[0].name,
en.palace(Palace::Soul).unwrap().major_stars[0].name);
```
**输出**
```text
紫微 / emperor
```
# 知识包 (/zh/docs/rust/knowledge)
KnowledgePack 与各条目类型、内嵌默认包、JSON 解析与序列化、覆盖包合并。
知识包是「语言无关标识 → 解读文本与门派属性」的 JSON。内核只判事实，
解读文本与星耀的门派属性放在这里。概念、格式与写覆盖包的方法见
[知识包指南](/zh/docs/guide/guides/knowledge-pack)，完整字段表见仓库的
[`knowledge/SCHEMA.md`](https://github.com/x-haose/x-iztro/blob/main/knowledge/SCHEMA.md)。
```rust
use x_iztro::{KnowledgePack, Language, StarKey};
let pack = KnowledgePack::builtin(Language::ZhCN).expect("zh-CN 有内嵌默认包");
let intro = pack.star_intro(StarKey::ZiweiMaj);
```
`KnowledgePack` 在 crate 根重导出；其余类型在 `x_iztro::knowledge` 下。
## 类型 [#类型]
### KnowledgePack [#knowledgepack]
字段全部公开，可直接读写；映射类字段是 `BTreeMap`，因此迭代顺序按键稳定。
| 字段 | 类型 | 说明 |
| ---------- | -------------------------------- | ---------------------------- |
| `schema` | `u32` | 格式版本，当前为 `SCHEMA_VERSION`（1） |
| `id` | `String` | 包标识，默认包为 `"iztro-docs"` |
| `version` | `String` | 包版本，默认包为「抓取日期+来源 commit 短号」 |
| `language` | `String` | 文本语言的语言码，如 `"zh-CN"` |
| `extends` | `Option` | 覆盖包所覆盖的包标识；独立包为 `None` |
| `source` | `Source` | 来源与许可 |
| `stars` | `BTreeMap` | 星耀条目，键为 `StarKey::as_key` |
| `patterns` | `BTreeMap` | 格局条目，键为 `PatternKey::as_key` |
| `palaces` | `BTreeMap` | 宫位条目，键为 `Palace::as_key` |
| `mutagens` | `BTreeMap` | 四化条目，键为 `Mutagen::as_key` |
| `concepts` | `BTreeMap` | 术语条目，键为 slug |
实现 `Clone`、`Default`、`PartialEq`、`Eq`、`Debug`、`Serialize`、`Deserialize`。
### Source [#source]
| 字段 | 类型 | 说明 |
| -------------- | ---------------- | ------------------- |
| `name` | `Option` | 来源名称 |
| `url` | `Option` | 来源地址 |
| `commit` | `Option` | 来源版本（git commit） |
| `license` | `Option` | 许可证 |
| `author` | `Option` | 作者 |
| `retrieved_at` | `Option` | 取得日期 |
| `adapted` | `Option` | 改编说明：文本相对来源做了何种整理改写 |
### StarEntry [#starentry]
| 字段 | 类型 | 说明 |
| -------------- | -------------------------- | -------------------------------------------------------------------------------- |
| `name` | `Option` | 该语言的显示名 |
| `category` | `Option` | 类别：`"major"` / `"minor"` / `"adjective"` / `"dec"` / `"flow"`（流耀，指向对应本命辅星的对照性条目） |
| `group` | `Option` | 分组：杂耀的分类、神煞的组别 |
| `attributes` | `StarAttributes` | 门派属性，缺省为全 `None` |
| `intro` | `Option` | 解读正文（Markdown） |
| `combinations` | `BTreeMap` | 与另一颗主星同宫的组合解读，键为对方星耀标识 |
### StarAttributes [#starattributes]
全部字段为 `Option`，`aliases` 为 `Option>`：
`yin_yang`（`yin` / `yang`）、`five_elements`（`wood` / `fire` / `earth` / `metal` / `water`）、
`stem`（`jia`…`gui`）、`five_elements_note`、`dipper`、`chemistry`、`career`、`duty`、
`aliases`、`element_color`、`energy_color`。
这里的 `five_elements` 与 `yin_yang` 是知识包来源的说法，与核心
[`StarInfo`](/zh/docs/rust/data) 的取值可能不同——核心那份与 iztro 逐值一致。
原因见[指南](/zh/docs/guide/guides/knowledge-pack#为什么星耀的阴阳五行放在这里)。
### PatternEntry [#patternentry]
| 字段 | 类型 | 说明 |
| ------------ | --------------------- | ------------ |
| `name` | `Option` | 该语言的显示名 |
| `quotes` | `Option>` | 古籍引文 |
| `conditions` | `Option` | 来源对成立条件的文字描述 |
| `intro` | `Option` | 解读正文 |
### TextEntry / ConceptEntry [#textentry--conceptentry]
`TextEntry`（宫位、四化）有 `name` 与 `intro`；`ConceptEntry`（术语）有 `title` 与 `intro`，
都是 `Option`。
### SCHEMA\_VERSION [#schema_version]
```rust
pub const SCHEMA_VERSION: u32 = 1;
```
本库支持的最高格式版本。解析到更高的 `schema` 会报错。
***
## builtin [#builtin]
**用途** 取内嵌的默认知识包。
**签名**
```rust
impl KnowledgePack {
pub fn builtin(language: Language) -> Option<&'static KnowledgePack>
}
```
**参数**
| 参数 | 类型 | 说明 |
| ---------- | ---------- | ---- |
| `language` | `Language` | 文本语言 |
**返回值** `Option<&'static KnowledgePack>`——该语言没有默认包时为 `None`。
目前只有 `Language::ZhCN` 有。首次调用时解析并缓存，之后是零成本的静态引用。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
println!("{} {} {}", pack.id, pack.version, pack.stars.len());
println!("{:?}", pack.source.license);
println!("{}", KnowledgePack::builtin(Language::EnUS).is_some());
```
**输出**
```text
iztro-docs 2026-08-19+ec2d58b 162
Some("MIT")
false
```
***
## builtin\_json [#builtin_json]
**用途** 取内嵌默认包的 JSON 原文，不做解析。
**签名**
```rust
impl KnowledgePack {
pub fn builtin_json(language: Language) -> Option<&'static str>
}
```
**返回值** `Option<&'static str>`，与 `builtin` 同样只有 zh-CN 有。
要把包原样透传给别的进程或写盘时用它，省一次解析加序列化。绑定层走的就是这条路。
***
## from\_json / from\_value [#from_json--from_value]
**用途** 由 JSON 文本或已解析的 `serde_json::Value` 解析一份包。
**签名**
```rust
impl KnowledgePack {
pub fn from_json(json: &str) -> Result
pub fn from_value(value: &serde_json::Value) -> Result
}
```
`from_value` 只借用值树、不复制，手上已有 `Value` 时省一次序列化往返；校验与 `from_json` 相同。
**返回值** `Result`。错误是给人看的字符串，三种情况：
JSON 语法或类型不合格式（`invalid knowledge pack: ...`）、
`schema` 缺失或为 0（包必须声明格式版本）、
以及 `schema` 高于 `SCHEMA_VERSION`（不做降级解析）。
这里返回 `String` 而不是 [`IztroError`](/zh/docs/rust/errors)：知识包是调用方自带的数据，
不属于排盘入口的输入校验。绑定层会把它包成各语言的 `invalid_argument` 错误。
**示例**
```rust
let pack = KnowledgePack::from_json(r#"{
"schema": 1, "id": "mine", "version": "1", "language": "zh-CN",
"stars": {"ziweiMaj": {"intro": "我的紫微"}}
}"#)?;
println!("{:?}", pack.star_intro(StarKey::ZiweiMaj));
println!("{:?}", KnowledgePack::from_json(r#"{"schema": 99}"#));
println!("{:?}", KnowledgePack::from_json(r#"{"id": "x"}"#));
```
**输出**
```text
Some("我的紫微")
Err("knowledge pack schema 99 is newer than supported 1")
Err("knowledge pack must declare \"schema\" (currently 1)")
```
**边界与陷阱**
所有条目与字段都可选。映射类字段（`source`、`stars`、`combinations`…）写成 `null`
等同于缺省——Go 等语言序列化 nil map 就是 `null`，这样三侧的默认序列化产物可以互相解析。
`stars` 里出现不是星耀标识的键、`patterns` 里出现未知格局标识，都会照原样留在包里。
校验键的有效性是写包者与测试的事，解析器只管格式（未知键被保留但查询不到）。
***
## to\_json [#to_json]
**用途** 序列化为 JSON（紧凑，无缩进）。
**签名**
```rust
impl KnowledgePack {
pub fn to_json(&self) -> String
}
```
**返回值** `String`。为 `None` 的可选字段与空映射在输出里省略，
因此 `from_json(&pack.to_json())` 与原包相等。要缩进输出用
`serde_json::to_string_pretty(&pack)`。
***
## merged [#merged]
**用途** 把若干覆盖包依次叠加到本包上，返回新包。
**签名**
```rust
impl KnowledgePack {
pub fn merged(&self, overlays: &[&KnowledgePack]) -> KnowledgePack
}
```
**参数**
| 参数 | 类型 | 说明 |
| ---------- | ------------------- | ---------------------- |
| `overlays` | `&[&KnowledgePack]` | 覆盖包，按数组顺序依次叠加，后面的覆盖前面的 |
**返回值** `KnowledgePack`，本包与覆盖包都不变。
合并规则见[指南](/zh/docs/guide/guides/knowledge-pack#合并规则)：
逐段按键合并，覆盖包的非 `None` 字段覆盖同键条目的对应字段，
`attributes` 与 `combinations` 逐字段合并，数组字段整体替换。
**示例**
```rust
let base = KnowledgePack::builtin(Language::ZhCN).unwrap();
let overlay = KnowledgePack::from_json(r#"{
"schema": 1, "id": "my-school", "version": "1", "language": "zh-CN", "extends": "iztro-docs",
"stars": {"ziweiMaj": {"intro": "我的紫微", "attributes": {"aliases": ["帝座"]}}},
"patterns": {"zi_fu_tong_gong": {"intro": "我的紫府同宫"}}
}"#)?;
let pack = base.merged(&[&overlay]);
let ziwei = pack.star(StarKey::ZiweiMaj).unwrap();
println!("{:?} {:?} {:?}", ziwei.name, ziwei.attributes.aliases, ziwei.attributes.chemistry);
println!("{:?}", pack.pattern_intro(PatternKey::ZiFuTongGong));
println!("{:?}", pack.pattern(PatternKey::ZiFuTongGong).unwrap().quotes);
println!("{} {:?}", pack.id, base.star_intro(StarKey::ZiweiMaj).map(|s| s.chars().take(5).collect::()));
```
**输出**
```text
Some("紫微") Some(["帝座"]) Some("尊贵")
Some("我的紫府同宫")
Some(["紫府同宫终身福厚。"])
my-school Some("紫微星号称")
```
***
## merge [#merge]
**用途** 把一份覆盖包就地合并进本包。
**签名**
```rust
impl KnowledgePack {
pub fn merge(&mut self, overlay: &KnowledgePack)
}
```
`merged` 是它的不可变版本（克隆本包后逐个 `merge`）。
手里已经有一份可变的包、又要叠很多层时用 `merge` 省掉克隆。
***
## star / pattern / palace / mutagen [#star--pattern--palace--mutagen]
**用途** 按语言无关标识取条目。
**签名**
```rust
impl KnowledgePack {
pub fn star(&self, key: StarKey) -> Option<&StarEntry>
pub fn pattern(&self, key: PatternKey) -> Option<&PatternEntry>
pub fn palace(&self, palace: Palace) -> Option<&TextEntry>
pub fn mutagen(&self, mutagen: Mutagen) -> Option<&TextEntry>
}
```
**返回值** 包里没有该条目时为 `None`。四个方法都是在对应 `BTreeMap` 上按
`as_key()` 取值，等价于自己写 `pack.stars.get(key.as_key())`；
术语没有专门的方法，直接 `pack.concepts.get(slug)`。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let ziwei = pack.star(StarKey::ZiweiMaj).unwrap();
println!("{:?} {:?} {:?}", ziwei.name, ziwei.category, ziwei.attributes.dipper);
println!("{:?}", ziwei.combinations.keys().collect::>());
println!("{:?}", pack.palace(Palace::Soul).and_then(|e| e.name.clone()));
println!("{:?}", pack.mutagen(Mutagen::Lu).and_then(|e| e.name.clone()));
println!("{:?}", pack.concepts.get("tong-gong").and_then(|e| e.title.clone()));
```
**输出**
```text
Some("紫微") Some("major") Some("中天星系")
["pojunMaj", "qishaMaj", "tanlangMaj", "tianfuMaj", "tianxiangMaj"]
Some("命宫")
Some("化禄")
Some("遇、加、逢、同宫、同度")
```
***
## star\_intro / pattern\_intro [#star_intro--pattern_intro]
**用途** 直接取解读正文，省掉一层 `Option` 展开。
**签名**
```rust
impl KnowledgePack {
pub fn star_intro(&self, key: StarKey) -> Option<&str>
pub fn pattern_intro(&self, key: PatternKey) -> Option<&str>
}
```
**返回值** 条目不存在、或条目存在但没写正文，都是 `None`。
**示例** 把本命格局连同解读列出来：
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
for hit in chart.patterns() {
let intro = pack.pattern_intro(hit.key).unwrap_or("（这份包里没写）");
let head: String = intro.chars().take(10).collect();
println!("{} {}", translate_pattern(hit.key, Language::ZhCN), head);
}
```
**输出**
```text
府相朝垣 “食禄千锺”的断语使
```
***
## for\_astrolabe / for\_horoscope [#for_astrolabe--for_horoscope]
**用途** 按盘取材：裁出只含这张盘相关条目的子包。
**签名**
```rust
impl KnowledgePack {
pub fn for_astrolabe(&self, chart: &Astrolabe) -> KnowledgePack
pub fn for_astrolabe_with(&self, chart: &Astrolabe, config: &PatternConfig) -> KnowledgePack
pub fn for_horoscope(&self, chart: &Astrolabe, horoscope: &HoroscopeData) -> KnowledgePack
pub fn for_horoscope_with(
&self,
chart: &Astrolabe,
horoscope: &HoroscopeData,
config: &PatternConfig,
) -> KnowledgePack
}
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ---------------- | ---------- | -- | ------------------------------------------------ |
| `chart` | `&Astrolabe` | 是 | — | 取材依据的星盘；重排盘按重排后的布局取材 |
| `horoscope` | `&HoroscopeData` | 是 | — | 运限数据，`HoroscopeRef::data()` 可得 |
| `config` | `&PatternConfig` | `_with` 必填 | — | 格局判定口径；无 `_with` 的两个即 `PatternConfig::default()` |
**返回值** 标准 `KnowledgePack`，元信息沿用本包：`stars` 是盘上出现的星
（主辅杂与四组十二神，14 主星的 `combinations` 只留对方主星确在同宫的），
`patterns` 是按 `config` 口径命中的格局，`mutagens` 四条全留，`palaces` 与 `concepts` 为空。
`for_horoscope` 在此之上再加各层流耀与大限到流时各层视角命中的格局。
子包要和[`patterns_with`](/zh/docs/rust/patterns#patterns_with) / `patterns_to_text_with`
配同一口径：口径不同，命中集合不同，释义就会缺项或多项。
取材规则见[按盘取材](/zh/docs/guide/guides/knowledge-pack#按盘取材)。
**示例**
```rust
let pack = KnowledgePack::builtin(Language::ZhCN).unwrap();
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let sub = pack.for_astrolabe(&chart);
println!("{} {} {} {}", sub.stars.len(), sub.patterns.len(), sub.mutagens.len(), sub.palaces.len());
println!("{:?}", sub.star(StarKey::WuquMaj).unwrap().combinations.keys().collect::>());
let h = chart.horoscope("2025-1-1", 0)?;
let sub = pack.for_horoscope(&chart, h.data());
println!("{} {}", sub.stars.len(), sub.patterns.len());
```
**输出**
```text
108 1 4 0
["tianxiangMaj"]
158 16
```
武曲在这张盘上与天相同宫，所以子包里武曲的 `combinations` 只剩天相一条。
# 反推 (/zh/docs/rust/reverse)
solar_dates_by_bazi 与 reverse_chart：由八字四柱或星盘特征反查候选生辰的函数与类型。
由八字四柱或星盘特征反查候选生辰。两个入口都是「剪枝枚举 + 正排终验」，
结果与正向排盘零分歧。概念、四柱口径与 Config 的关系、多解与截断语义见
[反推指南](/zh/docs/guide/guides/reverse)。
```rust
use x_iztro::*;
let cands = solar_dates_by_bazi(
(HeavenlyStem::Geng, EarthlyBranch::Chen),
(HeavenlyStem::Jia, EarthlyBranch::Shen),
(HeavenlyStem::Bing, EarthlyBranch::Wu),
(HeavenlyStem::Geng, EarthlyBranch::Yin),
(1900, 2100),
&Config::default(),
)?;
```
全部函数与类型定义在 `x_iztro::astro::reverse`，并在 crate 根重导出。
## 类型 [#类型]
### BirthCandidate [#birthcandidate]
一个候选生辰，可直接交给 [`by_solar`](/zh/docs/rust/astro) 排盘。
| 字段 | 类型 | 说明 |
| ------------ | -------- | ------------------------- |
| `solar_date` | `String` | 公历日期，`YYYY-M-D` |
| `time_index` | `u8` | 时辰索引 0–12（0 为早子时，12 为晚子时） |
### StarPosition [#starposition]
一颗星与其落宫地支：星盘特征反推的原子条件。
| 字段 | 类型 | 说明 |
| -------- | --------------- | ------------------- |
| `star` | `StarKey` | 星耀（须为本命盘星耀，运限流曜不接受） |
| `branch` | `EarthlyBranch` | 落宫地支 |
### ReverseCriteria [#reversecriteria]
星盘特征反推的条件集。实现 `Default`，惯用写法是给出条件后 `..Default::default()`。
全部条件可选，但至少要给一个。
| 字段 | 类型 | 默认值 | 说明 |
| --------------------- | --------------------------- | -------------- | ----------------------------------- |
| `soul_branch` | `Option` | `None` | 命宫地支 |
| `body_branch` | `Option` | `None` | 身宫地支 |
| `five_elements_class` | `Option` | `None` | 五行局 |
| `stars` | `Vec` | 空 | 星耀落宫条件，全部须同时满足 |
| `mutagens` | `[Option; 4]` | 全 `None` | 生年四化 \[禄, 权, 科, 忌] 各自是哪颗星 |
| `year_range` | `(i64, i64)` | `(1900, 2100)` | 公历年闭区间（含两端），须落在 1583–9999 内 |
| `fix_leap` | `bool` | `true` | 是否修正闰月，与排盘入参同义 |
| `limit` | `usize` | `0` | 候选数上限；`0` 取 `DEFAULT_REVERSE_LIMIT` |
### ReverseResult [#reverseresult]
| 字段 | 类型 | 说明 |
| ------------ | --------------------- | --------------------------- |
| `candidates` | `Vec` | 满足全部条件的候选生辰 |
| `truncated` | `bool` | 是否因达到候选数上限而提前截断；截断时更晚的解未被搜索 |
### DEFAULT\_REVERSE\_LIMIT [#default_reverse_limit]
```rust
pub const DEFAULT_REVERSE_LIMIT: usize = 512;
```
`ReverseCriteria::limit` 为 0 时采用的候选数上限。
***
## solar\_dates\_by\_bazi [#solar_dates_by_bazi]
由八字四柱反查公历生辰。
```rust
pub fn solar_dates_by_bazi(
yearly: (HeavenlyStem, EarthlyBranch),
monthly: (HeavenlyStem, EarthlyBranch),
daily: (HeavenlyStem, EarthlyBranch),
hourly: (HeavenlyStem, EarthlyBranch),
year_range: (i64, i64),
config: &Config,
) -> Result, IztroError>
```
四柱按 `config` 的分界口径解释（`year_divide` 年柱、`horoscope_divide` 月柱、
`day_divide` 晚子归属），与排盘输出的 `raw_dates.chinese_date` 同一套语义，
因此任何盘的四柱反查结果必包含该盘的生辰。一组四柱在范围内通常每约 60 年
出现一次；时柱为子时因早晚子之分可能给出相邻两天的两个候选。
**示例**
```rust
let a = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
let p = a.raw_dates.chinese_date;
let cands = solar_dates_by_bazi(p.yearly, p.monthly, p.daily, p.hourly, (1900, 2100), &Config::default())?;
for c in &cands {
println!("{} {}", c.solar_date, c.time_index);
}
```
**输出**
```text
1940-8-31 2
2000-8-16 2
2060-8-1 2
```
**错误** 干支阴阳不配（如甲丑）、年份范围颠倒或超出 1583–9999 时返回
[`IztroError::InvalidArgument`](/zh/docs/rust/errors#invalidargument)。
***
## reverse\_chart [#reverse_chart]
由星盘特征反查候选生辰。
```rust
pub fn reverse_chart(
criteria: &ReverseCriteria,
config: &Config,
) -> Result
```
判定贯穿 `config`：四化表、算法派别、各分界口径都按它算，
候选用同一 `config` 排盘必满足全部条件。星盘布局与性别无关
（性别只影响大限行进方向），因此条件不含性别。
**示例**
```rust
let r = reverse_chart(
&ReverseCriteria {
soul_branch: Some(EarthlyBranch::Wu),
five_elements_class: Some(FiveElementsClass::Wood3rd),
stars: vec![StarPosition { star: StarKey::ZiweiMaj, branch: EarthlyBranch::Wu }],
mutagens: [Some(StarKey::TaiyangMaj), None, None, None],
year_range: (1998, 2002),
..Default::default()
},
&Config::default(),
)?;
println!("{} {}", r.candidates.len(), r.truncated);
```
**输出**
```text
39 false
```
**错误** 条件为空、`stars` 含运限流曜、年份范围非法时返回
[`IztroError::InvalidArgument`](/zh/docs/rust/errors#invalidargument)。
达到 `limit` 即停止搜索，更晚的解不会出现在结果里。
`truncated` 为 `true` 时应收窄 `year_range` 或补条件后重查。
# 扩展星盘 (/zh/docs/rust/extend)
用扩展 trait 给 Astrolabe、PalaceRef 补自定义分析方法。
斗数的分析规则千人千面，库不可能穷举。x-iztro 的做法是让你把自己的规则
以方法的形式挂到星盘上——调用语法与内置方法一致，且在编译期完成，类型受检、零运行期开销。
## 配方 [#配方]
定义一个 trait，声明你要补的方法
为
`Astrolabe`
（或
`PalaceRef`
、
`StarRef`
）实现它
使用处
`use`
这个 trait，方法即可用
```rust
use x_iztro::i18n::translate_star;
use x_iztro::*;
/// 给星盘补两个自定义分析方法。
trait MyAnalysis {
/// 命宫主星名（空宫借对宫），多颗以逗号分隔
fn major_star(&self) -> String;
/// 五行局的局数
fn five_elements_value(&self) -> usize;
}
impl MyAnalysis for Astrolabe {
fn major_star(&self) -> String {
let soul = self.palace(Palace::Soul).expect("命宫必然存在");
let source = if soul.is_empty() { soul.opposite_palace() } else { soul };
source
.major_stars
.iter()
.filter(|s| s.star_type == StarType::Major)
.map(|s| translate_star(s.key, self.language))
.collect::>()
.join(",")
}
fn five_elements_value(&self) -> usize {
self.five_elements_class.value()
}
}
```
**用法**
```rust
let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;
println!("{}", chart.major_star());
println!("{}", chart.five_elements_value());
// 扩展方法随排盘语言输出
let en = by_solar("2000-8-16", 2, Gender::Female, true, Language::EnUS, Config::default())?;
println!("{}", en.major_star());
```
**输出**
```text
紫微
3
emperor
```
***
## 扩展别的类型 [#扩展别的类型]
同一套写法适用于宫位与星耀。为视图类型实现时注意生命周期参数：
```rust
trait PalaceAnalysis {
/// 本宫是否「煞忌交冲」：坐煞星且带化忌
fn is_afflicted(&self) -> bool;
}
impl PalaceAnalysis for PalaceRef<'_> {
fn is_afflicted(&self) -> bool {
use x_iztro::StarKey::*;
self.has_one_of(&[QingyangMin, TuoluoMin, HuoxingMin, LingxingMin, DikongMin, DijieMin])
&& self.has_mutagen(Mutagen::Ji)
}
}
```
```rust
for palace in &chart.palaces {
let p = chart.palace(palace.index).unwrap();
if p.is_afflicted() {
println!("{} 煞忌交冲", translate_palace(p.name, Language::ZhCN));
}
}
```
**输出**
```text
疾厄 煞忌交冲
```
***
## 组织建议 [#组织建议]
`WealthAnalysis`、`CareerAnalysis`、`HealthAnalysis` 各自成 trait，
使用方按需 `use`。堆成一个大 trait 会让所有调用点都被迫引入全部方法。
`s.key == StarKey::ZiweiMaj` 在任何输出语言下都成立；
`s.name == "紫微"` 只在中文盘上成立。展示时才翻译。
同一套分析规则要在 Python 与 Go 上都能用时，写成 Rust 扩展没有意义——
三侧各写一遍才是当前的做法，两侧的扩展方式见各自的「扩展星盘」页。
判断逻辑基于语言无关标识，三份实现断言同一组取值即可保证一致。
***
## 与运行期注入的区别 [#与运行期注入的区别]
有些库让你在运行期把函数挂到对象上。Rust 的扩展 trait 在编译期完成同一件事，
差别在于：
| | 扩展 trait | 运行期注入 |
| ------ | ---------- | ------- |
| 方法是否存在 | 编译期确定 | 运行期才知道 |
| 类型检查 | 有 | 无 |
| 调用开销 | 与内置方法相同 | 多一次动态查找 |
| 出错时机 | 编译失败 | 运行时报错 |
| 作用范围 | `use` 了才可见 | 全局或按实例 |
代价是扩展方法必须在编译期就写好，不能由配置文件或用户输入动态决定。
需要那种灵活度时，用一张 `HashMap bool>` 自行分派。
# 错误处理 (/zh/docs/rust/errors)
IztroError 的四个变体、code() 分类标识、BridgeError 与排查方式。
所有收外部输入的入口都返回 `Result`。日期格式、日期存在性、年份范围、
时辰索引与反推入参都在核心层前置校验，非法输入得到错误值而不是 panic。
```rust
#[non_exhaustive]
pub enum IztroError {
/// 日期串格式错、日期不存在，或超出公历 1583–9999
InvalidDate(String),
/// 时辰索引超出 0–12
InvalidTimeIndex(u8),
/// 反推入参不合法：干支阴阳不配、条件为空或含流耀、年份范围非法
InvalidArgument(String),
/// 依赖的历法库没给出本应存在的干支或星座取值
Internal(String),
}
impl IztroError {
/// 机器可读的错误分类标识
pub fn code(&self) -> &'static str
}
```
`IztroError` 实现了 `Display` 与 `std::error::Error`，可直接用 `?` 传播、用 `{}` 打印。
## code() [#code]
`Display` 给的是面向人的文案，会随版本调整；要在程序里分支请用 `code()`：
| 变体 | `code()` | 含义 |
| ------------------ | -------------------- | ----------- |
| `InvalidDate` | `invalid_date` | 日期非法 |
| `InvalidTimeIndex` | `invalid_time_index` | 时辰索引越界 |
| `InvalidArgument` | `invalid_argument` | 反推等入口的入参不合法 |
| `Internal` | `internal` | 库内部缺陷 |
这四个取值与 Python 的 `IztroError.code`、Go 的 `iztro.Error.Code` 是同一套，
跨语言分支逻辑可以照抄。
```rust
let e = by_solar("2000-2-30", 2, Gender::Female, true, Language::ZhCN, Config::default())
.unwrap_err();
println!("{} / {}", e.code(), e);
```
**输出**
```text
invalid_date / invalid solar date '2000-2-30': day is out of range for that month
```
`IztroError` 标了 `#[non_exhaustive]`，crate 外无法穷尽匹配——`match` 必须带兜底分支。
将来新增错误分类因此不构成破坏性变更；按 `code()` 分支的代码则完全不受影响。
***
## InvalidDate [#invaliddate]
**触发条件**
| 情形 | 例 | 消息 |
| --------------- | ------------- | ------------------------------------ |
| 格式不是 `YYYY-M-D` | `"2000/8/16"` | `expected 'YYYY-M-D'` |
| 年、月、日不是数字 | `"abc-8-16"` | `year is not a number` |
| 月份越界 | `"2000-13-1"` | `month must be within 1-12` |
| 该月没有这一天 | `"2000-2-30"` | `day is out of range for that month` |
| 年份超出支持范围 | `"1500-1-1"` | `year must be within 1583-9999` |
农历专有（只有 `by_lunar` 与 `get_sign_by_lunar_date`、`get_major_star_by_lunar_date` 会碰到）：
| 情形 | 例 | 消息 |
| --------- | ---------------------------------- | ------------------------------------------ |
| 该农历年没有这个月 | `by_lunar("2000-13-1", …)` 之外的表内缺月 | `month does not exist in that lunar year` |
| 该农历月没有这一天 | `"2000-7-30"`（七月是小月） | `day is out of range for that lunar month` |
农历消息的前缀是 `invalid lunar date '<原串>': `，公历是 `invalid solar date '<原串>': `，
从消息就能看出走的是哪个入口。
**示例**
```rust
let cfg = Config::default();
for date in ["2000-13-1", "2000-2-30", "1500-1-1"] {
match by_solar(date, 2, Gender::Female, true, Language::ZhCN, cfg.clone()) {
Ok(_) => println!("{date}: ok"),
Err(e) => println!("{e}"),
}
}
```
**输出**
```text
invalid solar date '2000-13-1': month must be within 1-12
invalid solar date '2000-2-30': day is out of range for that month
invalid solar date '1500-1-1': year must be within 1583-9999
```
消息里带上了原始输入，便于在批量处理时定位是哪一条数据出的问题。
**边界与陷阱**
1582 年格里历改革当年有一段不存在的日期。底层历法库在这些日期上没有定义，
因此支持范围从改革完成后的 1583 年起算。上限 9999 是农历数据表的覆盖终点。
`"2000-8-16"` 与 `"2000-08-16"` 都接受。分隔符必须是 `-`。
`by_lunar` 会检查该农历年该月是否真的存在，以及该月有多少天（大月 30、小月 29）。
`leap` 标为闰月但那年那月无闰月时不报错，按普通月处理。
***
## InvalidTimeIndex [#invalidtimeindex]
**触发条件** 时辰索引大于 12。
**示例**
```rust
let err = by_solar("2000-8-16", 13, Gender::Female, true, Language::ZhCN, Config::default())
.unwrap_err();
println!("{err}");
```
**输出**
```text
time_index must be 0-12, got 13
```
**边界与陷阱**
子时跨午夜，拆成早子时（索引 0）与晚子时（索引 12），因此合法值有 13 个。
从小时数换算用 [`time_to_index`](/zh/docs/rust/util#time_to_index)，它保证结果落在合法范围。
***
## InvalidArgument [#invalidargument]
**触发条件** 反推入口的调用方错误：
| 情形 | 例 | 消息 |
| -------- | ---------------------------- | ----------------------------------------------------------------------------- |
| 四柱干支阴阳不配 | 甲丑（阳干配阴支） | `invalid yearly pillar: stem and branch must have the same polarity` |
| 反推条件为空 | `ReverseCriteria::default()` | `reverse criteria must contain at least one condition` |
| 条件含运限流曜 | 流禄 | `star 'liulu' is a horoscope-scope star and never appears on the natal chart` |
| 年份范围非法 | `(2100, 1900)` | `invalid year range 2100-1900: expected 1583-9999 with start <= end` |
**示例**
```rust
let jia_zi = (HeavenlyStem::Jia, EarthlyBranch::Zi);
let err = solar_dates_by_bazi(
(HeavenlyStem::Jia, EarthlyBranch::Chou), // 甲丑：阴阳不配
jia_zi, jia_zi, jia_zi,
(1900, 2100),
&Config::default(),
)
.unwrap_err();
println!("{} / {}", err.code(), err);
```
**输出**
```text
invalid_argument / invalid yearly pillar: stem and branch must have the same polarity
```
反推入口的语义见[反推](/zh/docs/rust/reverse)。
***
## Internal [#internal]
**触发条件** 依赖的历法库 `lunar_rust` 没有交回本应存在的干支或星座取值。
这是库内部缺陷而非调用方过错。
**为什么不 panic** wasm 目标下 panic 即 trap，而且每次 trap 都会永久损耗模块实例的
栈空间。把这类情况落成错误值，非法调用就不会累积损坏 Go 侧的 wasm 实例。
**消息形状** `internal error: <细节>`，`code()` 为 `internal`。
在金标覆盖的全部日期上都没有触发过这个变体。真的碰到请当作 bug 上报，
并附上完整的排盘入参。
***
## BridgeError [#bridgeerror]
绑定层（C FFI / wasm / PyO3）对外报错的统一形状。Rust 调用方一般用不到它——
它是 Python 与 Go 侧错误对象的来源。
```rust
pub struct BridgeError {
/// invalid_date / invalid_time_index / invalid_argument / internal
pub code: &'static str,
/// 面向人的错误描述
pub message: String,
}
impl BridgeError {
pub fn invalid_argument(message: impl Into) -> Self
pub fn internal(message: impl Into) -> Self
}
impl From for BridgeError { /* code 与 message 直接沿用 */ }
```
四个分类与 `IztroError` 相同。绑定层收的是字符串而非枚举，
性别、语言、宫名、四化、配置 JSON 这些取值的合法性只能在那一层校验，
同样落在 `invalid_argument` 分类下。
三条出口都把它序列化成同一段 JSON：
```json
{ "error": "invalid solar date '2000-2-30': day is out of range for that month",
"code": "invalid_date" }
```
Python 侧变成 `IztroError`（继承 `ValueError`，带 `.code`），
Go 侧变成 `*iztro.Error`（带 `Code`、可用 `errors.Is` 比对哨兵）。
## C FFI [#c-ffi]
`x_iztro::ffi` 导出的 C ABI 里，统一查询入口是 `iztro_query`：
```c
// include/x_iztro.h
char *iztro_query(const char *query_json);
void iztro_free_string(char *s);
```
收一段以 `kind` 选择具体查询的 JSON（如 `{"kind":"getPalaceNames","soulIndex":0}`），
成功返回 `{"value": <结果>}`，失败返回上面那段带 `code` 的错误 JSON。
它把轻量查询、宫位推算、工具函数、安星、数据表、翻译与 Prompt 生成收进一个符号，
不必为每个函数导出一个 C 符号。键名 camelCase，星耀、干支、宫位等标识按
iztro i18n key 传入与返回。
返回的字符串都由调用方用 `iztro_free_string` 归还；这些函数永不返回 `NULL`。
`ffi` 模块标了 `#[doc(hidden)]`，不是给 Rust 调用方用的——
Rust 里直接调 `by_solar` 一族即可。
***
## 处理方式 [#处理方式]
**用 `?` 传播**
```rust
fn analyze(date: &str) -> Result {
let chart = by_solar(date, 2, Gender::Female, true, Language::ZhCN, Config::default())?;
Ok(chart.palace(Palace::Soul).unwrap().major_stars
.iter().map(|s| s.name.clone()).collect::>().join(","))
}
```
**分变体处理**
```rust
fn describe(date: &str, ti: u8) -> String {
match by_solar(date, ti, Gender::Female, true, Language::ZhCN, Config::default()) {
Ok(chart) => format!("排盘成功: {}", chart.solar_date),
Err(IztroError::InvalidDate(msg)) => format!("日期有误: {msg}"),
Err(IztroError::InvalidTimeIndex(t)) => format!("时辰索引 {t} 越界"),
Err(e) => format!("其他错误 [{}]: {e}", e.code()),
}
}
println!("{}", describe("2000-8-16", 2));
println!("{}", describe("2000-2-30", 2));
println!("{}", describe("2000-8-16", 13));
```
**输出**
```text
排盘成功: 2000-8-16
日期有误: invalid solar date '2000-2-30': day is out of range for that month
时辰索引 13 越界
```
`IztroError` 标了 `#[non_exhaustive]`，crate 外的 `match` 必须带一个
`_` 或 `Err(e)` 兜底分支，否则编译不过。这样将来新增变体不会成为破坏性变更。
**转成自己的错误类型**
`IztroError` 实现了 `std::error::Error`，可直接被 `Box`、`anyhow::Error`
或 `thiserror` 的 `#[from]` 接住。
```rust
#[derive(Debug, thiserror::Error)]
enum AppError {
#[error("排盘失败: {0}")]
Chart(#[from] x_iztro::IztroError),
}
```
***
## 关于 panic [#关于-panic]
排盘入口不会因非法**外部输入**而 panic：日期、时辰这些都落成 `IztroError`，
连历法库交不出取值这种内部情形也走 `IztroError::Internal` 而不是 panic。
仍可能 panic 的只有库自身的逻辑缺陷（如断言失败），这类情况应视为 bug 上报。
wasm 上 panic 即 trap，而且每次 trap 都会永久损耗模块实例的栈空间。
因此校验放在核心层而非绑定层——三种语言共用同一道防线。
# 概览 (/zh/docs/python)
包结构、类型体系与阅读本参考的方式。
Python 包是 Rust 核心的类型化封装：计算在 Rust 里完成，
Python 侧提供 dataclass 与 StrEnum 构成的强类型 API，零外部依赖。
这一栏是 Python 侧的完整 API 参考——每个函数、类与方法都有独立条目。
## 安装 [#安装]
```bash
pip install x-iztro
```
要求 Python 3.10 及以上。发行版内含预编译的原生扩展（abi3-py310 轮子），
安装时不需要 Rust 工具链。
`enum.StrEnum` 是 3.11 才进标准库的。`x_iztro.enums` 在 3.10 上自动回退到等价的
`class StrEnum(str, Enum)` 实现——枚举成员照样既是字符串又能补全，两个版本行为一致。
## 第一张盘 [#第一张盘]
```python
from x_iztro import Astro
chart = Astro().by_solar("2000-8-16", 2, "female") # 2 = 寅时（03:00–05:00）
print(chart.solar_date, chart.lunar_date)
# 2000-8-16 二〇〇〇年七月十七
soul = chart.palace("soulPalace")
print(" ".join(s.name for s in soul.major_stars))
# 紫微
```
## 包结构 [#包结构]
| 模块 | 内容 | 本参考对应页 |
| ---------------- | ---------------------------------------------------------------------- | -------------------------------------- |
| `x_iztro.Astro` | 排盘主类 | [排盘入口](/zh/docs/python/astro) |
| `x_iztro.models` | `Astrolabe`、`Palace`、`Star`、`Horoscope`、`ChartConfig` 等 dataclass | [星盘对象](/zh/docs/python/astrolabe) 起的四页 |
| `x_iztro.enums` | 全部语言无关标识的 StrEnum，以及 `GenderType`、`LanguageType`、`TimeIndexType` 等类型别名 | [数据表](/zh/docs/python/data)、本页下方 |
| `x_iztro.query` | 生肖、星座、命宫主星的轻量查询 | [轻量查询](/zh/docs/python/query) |
| `x_iztro.utils` | 索引换算、亮度与四化查表 | [工具函数](/zh/docs/python/util) |
| `x_iztro.star` | 按出生数据安星 | [安星模块](/zh/docs/python/star) |
| `x_iztro.data` | 星耀与干支数据表、顺序常量 | [数据表](/zh/docs/python/data) |
| `x_iztro.i18n` | 标识与译名的双向查找 | [翻译](/zh/docs/python/i18n) |
| `x_iztro.plugin` | 给星盘类挂自定义方法 | [扩展星盘](/zh/docs/python/extend) |
`models` 是聚合层：`Astrolabe` 实际定义在 `x_iztro.astrolabe`，`Palace` 在 `x_iztro.palace`，
`Star` 在 `x_iztro.star_object`，`Horoscope` 在 `x_iztro.horoscope`，
`ChartConfig` 在 `x_iztro.config`，`SurroundedPalaces` 在 `x_iztro.surpalaces`。
从 `x_iztro` 顶层或 `x_iztro.models` 导入都拿得到，按哪个都行。
## 类型别名 [#类型别名]
`x_iztro.enums` 里几个 `Literal` 别名，作用是让编辑器在参数写错时立刻标红：
| 别名 | 定义 |
| ----------------- | --------------------------------------------------------------------------------------- |
| `GenderType` | `Literal["male", "female"]` |
| `LanguageType` | `Literal["zh-CN", "zh-TW", "en-US", "ja-JP", "ko-KR", "vi-VN"]` |
| `TimeIndexType` | `Literal[0, 1, …, 12]` |
| `StarTypeLiteral` | `Literal["major", "soft", "tough", "adjective", "flower", "helper", "lucun", "tianma"]` |
| `ScopeLiteral` | `Literal["origin", "decadal", "yearly", "monthly", "daily", "hourly"]` |
它们只是类型标注，运行期不做校验——真正的取值校验在核心层，非法值抛 `IztroError`。
## 枚举即标识 [#枚举即标识]
`x_iztro.enums` 里的每个枚举都是 `StrEnum`，其**取值就是语言无关标识**，
可以直接与数据对象上的 `*_key` 字段比较：
```python
from x_iztro import MajorStar, PalaceName
soul = chart.palace(PalaceName.SOUL)
print(soul.major_stars[0].key == MajorStar.ZIWEI)
# True
```
因为是 `StrEnum`，字符串字面量同样有效——`chart.palace("soulPalace")` 与
`chart.palace(PalaceName.SOUL)` 等价。枚举的价值在于 IDE 补全与拼写检查。
`star.name` 随排盘语言变化（中文盘是「紫微」，英文盘是 `emperor`）；
`star.key` 在任何语言下都是 `ziweiMaj`。所有判断都应基于 `*_key` 字段或内置判断方法。
## 数据对象是不可变的 [#数据对象是不可变的]
星盘、宫位、星耀都是 `frozen=True` 的 dataclass，构造后不能修改字段。
需要变体时用返回新对象的方法，如 `chart.rearranged(...)`。
```python
try:
chart.solar_date = "2001-1-1"
except Exception as e:
print(type(e).__name__, e)
```
**输出**
```text
FrozenInstanceError cannot assign to field 'solar_date'
```
不可变让星盘可以安全地在多个分析函数之间传递、放进缓存、跨线程共享，
不必担心某一处的修改影响到别处。
## 条目怎么读 [#条目怎么读]
每个 API 条目按固定八段组织：
**用途**
—— 一句话说清它做什么
**斗数含义**
—— 它在紫微斗数里对应什么概念（纯工程性的函数省略此段）
**签名**
—— 从源码原样摘出
**参数**
—— 名、类型、是否必填、默认值、说明
**返回值**
—— 类型与结构
**示例**
—— 可直接运行的片段
**输出**
—— 该示例的真实运行结果
**边界与陷阱**
—— 空值、越界、配置影响、与其他 API 的相互作用
示例统一用同一张盘：**2000 年 8 月 16 日寅时女命**（`by_solar("2000-8-16", 2, "female")`），
方便跨页对照。这张盘的完整数据见[数据结构](/zh/docs/guide/data-model)。
排盘语言不传时默认 `zh-CN`，因此本参考所有输出块里的展示值都是中文。
换语言只改这些展示串，`*_key` 标识与全部判断方法的结果不变。
# 排盘入口 (/zh/docs/python/astro)
Astro 类的排盘方法、重排与语义化文本投影。
排盘是一切的起点：给出生日期、时辰、性别，得到一个 `Astrolabe`。
```python
from x_iztro import Astro
astro = Astro()
```
`Astro` 无内部状态，实例化一次到处用；也可以每次调用时临时构造。
所有入口在入参非法时抛 `IztroError`（继承自 `ValueError`，因此 `except ValueError`
也接得住）。日期格式与存在性、公历年份范围、时辰索引在核心层前置校验；
性别、语言、宫名这类字符串取值在绑定层校验。
异常带 `.code` 给出机器可读分类，详见[错误处理](/zh/docs/python/errors)。
***
## ChartConfig [#chartconfig]
排盘配置：六个开关加两张可选的自定义表。冻结的 dataclass，全部字段都有默认值，
默认值与 JS iztro 一致——`ChartConfig()` 与不传 `config` 等价。
| 字段 | 类型 | 默认 | 取值（对应枚举） |
| ------------------ | ------------------------------ | ----------- | -------------------------------------------------- |
| `year_divide` | `str` | `"normal"` | `normal` 正月初一 / `exact` 立春（`YearDivide`） |
| `horoscope_divide` | `str` | `"normal"` | `normal` 初一 / `exact` 节气（`HoroscopeDivide`） |
| `age_divide` | `str` | `"normal"` | `normal` 跨年即加 / `birthday` 过生日才加（`AgeDivide`） |
| `day_divide` | `str` | `"forward"` | `forward` 晚子时归次日 / `current` 归当天（`DayDivide`） |
| `algorithm` | `str` | `"default"` | `default` / `zhongzhou`（`Algorithm`） |
| `astro_type` | `str` | `"heaven"` | `heaven` 天盘 / `earth` 地盘 / `human` 人盘（`AstroType`） |
| `mutagens` | `dict[str, list[str]] \| None` | `None` | 天干标识 → 四颗星标识（禄、权、科、忌） |
| `brightness` | `dict[str, list[str]] \| None` | `None` | 星耀标识 → 十二项亮度标识，索引 0 为寅宫，空串表示该宫无亮度 |
六个开关的取值语义与流派背景见 [Config 详解](/zh/docs/guide/guides/config)。
**方法**
| 方法 | 说明 |
| ------------------- | -------------------------------------------- |
| `to_dict() -> dict` | 转成绑定层接受的 camelCase 配置对象；两张表为 `None` 时不出现在结果里 |
**示例**
```python
from x_iztro import Astro, ChartConfig, AstroType, HeavenlyStem, MajorStar
cfg = ChartConfig(
astro_type="earth",
mutagens={HeavenlyStem.GENG: [MajorStar.TAIYANG, MajorStar.WUQU,
MajorStar.TIANFU, MajorStar.TIANTONG]},
)
print(cfg.to_dict())
chart = Astro().by_solar("2000-8-16", 2, "female", config=cfg)
print(chart.five_elements_class, chart.config.astro_type)
print(chart.palace("soulPalace").mutagen_star_keys)
```
**输出**
```text
{'yearDivide': 'normal', 'horoscopeDivide': 'normal', 'ageDivide': 'normal', 'dayDivide': 'forward', 'algorithm': 'default', 'astroType': 'earth', 'mutagens': {'gengHeavenly': ['taiyangMaj', 'wuquMaj', 'tianfuMaj', 'tiantongMaj']}}
土五局 earth
['tiantongMaj', 'tianjiMaj', 'wenchangMin', 'lianzhenMaj']
```
地盘的命宫落在原盘身宫（官禄，丙戌），因此宫干四化按丙干取。
**边界与陷阱**
`mutagens` 一次替换某个天干的**全部四位**，`brightness` 一次替换某颗星的**全部十二宫**。
长度是严格校验：四化必须正好四项、亮度必须正好十二项，多一项少一项都抛 `IztroError`。
未列出的天干与星仍用默认表。
两张表的键与值都必须是语言无关标识（`"gengHeavenly"`、`"taiyangMaj"`）。
传 `"庚"`、`"太阳"` 会报 `invalid mutagens key` 一类错误。
枚举成员是 `StrEnum`，直接当键用即可，`to_dict` 会把它们转成字符串。
`to_dict` 只对两张表里的键值做 `str()`，六个开关字段原样带出。
写 `ChartConfig(astro_type=AstroType.EARTH)` 排盘完全正常（`StrEnum` 与字符串等价），
只是 `to_dict()` 的结果里那一项会印成 ``。
要把配置落成干净的 JSON，开关传字符串字面量，或自己 `str()` 一遍。
`chart.config` 由输出 DTO 还原，只含六个开关——两张自定义表是排盘**输入**而非结果，
不进 DTO（这一点与 JS iztro 的字段契约一致）。
但星盘内部保留了你传进来的原件，因此 `chart.rearranged(...)`、`chart.horoscope(...)`、
to\_text 文本投影这些二次计算仍然用得上那两张表，不会静默丢失。
要把配置记录下来，请在自己的调用侧保存 `ChartConfig` 对象。
***
## by\_solar [#by_solar]
**用途** 由公历日期排出本命盘。
**斗数含义** 紫微斗数以农历为算法基础，但绝大多数人只记得公历生日。
本方法先把公历转农历（含年、月、日、时四柱），再据此安星。
换年的时点受 `year_divide` 影响——正月初一与立春之间出生的人，
两种配置会得到不同的年干支，进而影响四化、命主身主与全部年系星。
**签名**
```python
def by_solar(
self,
solar_date: str,
time_index: TimeIndexType,
gender: GenderType,
*,
fix_leap: bool = True,
language: LanguageType = "zh-CN",
config: ChartConfig | None = None,
) -> Astrolabe
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | --------------------- | -- | --------- | -------------------------------------------------- |
| `solar_date` | `str` | 是 | — | 公历日期，格式 `YYYY-M-D`，月日不必补零。支持 1583–9999 年 |
| `time_index` | `int` | 是 | — | 时辰索引 0–12。0 为早子时（00:00–01:00），12 为晚子时（23:00–24:00） |
| `gender` | `str` | 是 | — | `"male"` 或 `"female"`。决定大限顺逆与长生、博士十二神的排列方向 |
| `fix_leap` | `bool` | 否 | `True` | 仅限关键字。是否调整农历闰月。为真时闰月十六日起按下月算（晚子时除外，见下） |
| `language` | `str` | 否 | `"zh-CN"` | 输出语言，影响所有译名字段；`*_key` 标识字段不受影响 |
| `config` | `ChartConfig \| None` | 否 | `None` | 排盘配置，`None` 取默认 |
**返回值** `Astrolabe`——十二宫、四柱、命主身主、五行局俱全的完整星盘。
**示例**
```python
from x_iztro import Astro
chart = Astro().by_solar("2000-8-16", 2, "female")
print(chart.solar_date, "|", chart.lunar_date, "|", chart.chinese_date)
print(chart.sign, chart.zodiac, chart.five_elements_class)
print("命主", chart.soul, "身主", chart.body)
```
**输出**
```text
2000-8-16 | 二〇〇〇年七月十七 | 庚辰 甲申 丙午 庚寅
狮子座 龙 木三局
命主 破军 身主 文昌
```
**边界与陷阱**
子时横跨午夜，分早子时（00:00–01:00，属当日）与晚子时（23:00–24:00，属次日）。
两者的日柱不同，紫微起宫也可能差一天，因此必须区分，索引才有 13 个。
不确定时辰索引时用 `utils.time_to_index(hour)` 换算。
进位要同时满足四个条件：该农历月确实是闰月、`fix_leap` 为真、农历日大于 15、
且时辰索引不是 12（晚子时）。四者缺一，月索引就按本月算。
因此只有农历闰月下半月出生的人，`True` 与 `False` 会得到不同的月索引，
进而影响左辅右弼与全部月系星。
星盘上所有判断方法（`has`、`flies_to`、`with_mutagen` 等）都基于语言无关标识，
换语言排盘不会改变任何判断结果，只改变 `name` 一类展示字段。
***
## by\_lunar [#by_lunar]
**用途** 由农历日期排出本命盘。
**斗数含义** 农历日期是斗数的原生输入，跳过公历转换这一步。
知道自己农历生日的人直接用它，结果与用对应公历日期调 `by_solar` 完全一致。
**签名**
```python
def by_lunar(
self,
lunar_date: str,
time_index: TimeIndexType,
gender: GenderType,
*,
is_leap_month: bool = False,
fix_leap: bool = True,
language: LanguageType = "zh-CN",
config: ChartConfig | None = None,
) -> Astrolabe
```
**参数** 除以下一项外，其余与 `by_solar` 相同。`gender` 之后的参数只能按关键字传入——
`is_leap_month` 与 `fix_leap` 相邻，位置传参写反了不报错、盘会静默错一个月。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------ | -- | ------- | ------------------------------------- |
| `lunar_date` | `str` | 是 | — | 农历日期，格式 `YYYY-M-D`，月份写正数（闰月由下一参数标记） |
| `is_leap_month` | `bool` | 否 | `False` | 仅限关键字。该农历月是否为闰月。若那一年那个月本来就没有闰月，此参数不生效 |
**返回值** 同 `by_solar`。
**示例**
```python
a = Astro().by_lunar("2000-7-17", 2, "female")
b = Astro().by_solar("2000-8-16", 2, "female")
print(a.solar_date, a.solar_date == b.solar_date)
```
**输出**
```text
2000-8-16 True
```
**边界与陷阱**
传 `True` 但那个月并非闰月时，参数被静默忽略，不报错。
如果需要严格校验，调用前先自行确认该年该月确实有闰月。
***
## get\_horoscope [#get_horoscope]
**用途** 以某张本命盘为起点计算目标日期的运限。
**签名**
```python
def get_horoscope(
self,
astrolabe: Astrolabe,
target_date: str | None = None,
target_time_index: TimeIndexType | None = None,
) -> Horoscope
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------------- | -- | ------ | ---------------- |
| `astrolabe` | `Astrolabe` | 是 | — | 本命盘 |
| `target_date` | `str \| None` | 否 | `None` | 目标公历日期；不传取今天 |
| `target_time_index` | `int \| None` | 否 | `None` | 目标时辰索引；不传取此刻所属时辰 |
**返回值** `Horoscope`，持有传入的星盘。详见[运限对象](/zh/docs/python/horoscope)。
**示例**
```python
chart = Astro().by_solar("2000-8-16", 2, "female")
h = Astro().get_horoscope(chart, "2025-6-1", 0)
print(h.decadal.heavenly_stem + h.decadal.earthly_branch)
print(h.yearly.heavenly_stem + h.yearly.earthly_branch)
```
**输出**
```text
庚辰
乙巳
```
**边界与陷阱**
`chart.horoscope("2025-6-1", 0)` 与本方法完全等价，且不必再持有 `Astro` 实例。
`Astro.get_horoscope` 存在是为了让「所有入口都在一个类上」这种用法也成立。
***
## rearranged [#rearranged]
**用途** 以指定干支为命宫重排本盘，返回新盘；原盘不变。
**斗数含义** 中州派把同一组出生数据看作三张盘：天盘以命宫干支起五行局，
地盘以身宫干支起，人盘以福德宫干支起。起局的干支一变，五行局就变，
紫微天府落点、十二宫名、长生十二神、大限小限随之全部重算。
本方法把这个能力放开到**任意干支**。
**签名**
```python
def rearranged(self, from_stem: str, from_branch: str) -> Astrolabe
```
这是 `Astrolabe` 上的方法，不在 `Astro` 类上。
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ----- | -- | -- | ----------------------------- |
| `from_stem` | `str` | 是 | — | 新命宫的天干标识，`HeavenlyStem` 枚举值域 |
| `from_branch` | `str` | 是 | — | 新命宫的地支标识，`EarthlyBranch` 枚举值域 |
**返回值** 新的 `Astrolabe`。重算：命宫身宫、五行局、十四主星、十二宫名、
长生十二神、大限小限、命主星，以及随命宫挪位的天伤、天使、天才。
沿用原盘：辅星、其余杂耀、博士十二神、岁前与将前十二神、身主星。
重排返回的盘上，`patterns()`、运限查询与 to\_text 文本投影都按**重排后的布局**
计算——五行局、命宫与大限随重排起点变化；出生数据（日期与四柱）保持不变。
**示例**
```python
chart = Astro().by_solar("2000-8-16", 2, "female")
# 从原盘身宫的干支起盘，等价于地盘
body = next(p for p in chart.palaces if p.is_body_palace)
earth = chart.rearranged(body.heavenly_stem_key, body.earthly_branch_key)
print("天盘", chart.five_elements_class, "→ 地盘", earth.five_elements_class)
```
**输出**
```text
天盘 木三局 → 地盘 土五局
```
**边界与陷阱**
天盘、地盘、人盘用 `ChartConfig(astro_type="earth")` 直接排即可，
两个排盘入口都支持。`rearranged` 是为「从任意干支起盘」准备的。
身主星按**出生年支**查表，与命宫位置无关，重排不改变出生年。
命主星按命宫地支查表，因此会跟着更新。
***
## 语义化文本（to\_text） [#语义化文本to_text]
**用途** 把星盘或运限投影成语义化文本——盘面事实的自然语言形态，
喂给大模型或直接给人读。与 `to_dict`/`to_json`（机器结构）、译文字段（展示）
是同一对象的三种投影。
**签名** 文本投影是对象自己的方法，不在 `Astro` 上：
```python
chart.to_text() # 本命盘；str(chart) 等价
chart.horoscope("2025-1-1", 0).to_text() # 运限；str(h) 等价
chart.palace("命宫").to_text() # 单宫
chart.surrounded_palaces("命宫").to_text() # 三方四正
chart.patterns_to_text() # 本命格局
```
**返回值** `str`——按星盘的排盘语言输出的 Markdown 子集（`#` 标题、`- 标签: 值` 列表、
十二宫总览窄表）；本命文本带格局节与从命宫起的十二宫详解，运限文本各层带该层视角的
四化、流耀与格局行。每个 `to_text` 都收 `knowledge=`（`True` 或 `KnowledgePack`），
给出时释义按盘取材内联在事实之后；也都收 `config=`（`PatternConfig`），给格局节与格局释义的判定口径。
格式见[语义化文本](/zh/docs/guide/guides/to-text)。
**示例**
```python
astro = Astro()
chart = astro.by_solar("2000-8-16", 2, "female")
print("\n".join(chart.to_text().splitlines()[:5]))
```
**输出**
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座
```
**边界与陷阱**
输出语言跟随星盘的 `language`，不单独设置。要英文文本就用英文排盘。
# 星盘对象 (/zh/docs/python/astrolabe)
Astrolabe 的字段、定位方法，以及三方四正与夹宫。
`Astrolabe` 是排盘的产物，也是一切查询的入口。它是 `frozen=True` 的 dataclass，
持有十二宫的全部数据，以及四柱、命主身主、五行局这些盘级信息。
```python
chart = Astro().by_solar("2000-8-16", 2, "female")
```
本页示例统一用默认的 `zh-CN` 排盘，因此输出里的展示值都是中文。
换语言只改这些展示串，`*_key` 标识与所有判断方法的结果不变。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| ------------------------------- | ----- | ---------- |
| `gender` | `str` | 性别译名 |
| `solar_date` | `str` | 公历日期，与入参一致 |
| `lunar_date` | `str` | 农历日期的中文写法 |
| `chinese_date` | `str` | 四柱展示串 |
| `time` | `str` | 时辰名 |
| `time_range` | `str` | 时辰对应的钟点区间 |
| `sign` | `str` | 星座 |
| `zodiac` | `str` | 生肖 |
| `soul` | `str` | 命主星译名 |
| `body` | `str` | 身主星译名 |
| `five_elements_class` | `str` | 五行局译名 |
| `earthly_branch_of_soul_palace` | `str` | 命宫地支译名 |
| `earthly_branch_of_body_palace` | `str` | 身宫地支译名 |
展示字段随 `language` 翻译。要做判断请用下一组的 `*_key` 字段。
| 字段 | 类型 | 说明 |
| ----------------------------------- | ----- | ----------------------- |
| `gender_key` | `str` | `"male"` / `"female"` |
| `sign_key` | `str` | 星座标识，`aries` … `pisces` |
| `zodiac_key` | `str` | 生肖标识，`rat` … `pig` |
| `soul_key` | `str` | 命主星标识 |
| `body_key` | `str` | 身主星标识 |
| `five_elements_class_key` | `str` | 五行局标识 |
| `earthly_branch_of_soul_palace_key` | `str` | 命宫地支标识 |
| `earthly_branch_of_body_palace_key` | `str` | 身宫地支标识 |
取值与 `x_iztro.enums` 的枚举一一对应，可直接用 `==` 比较。
| 字段 | 类型 | 说明 |
| ----------- | -------------- | ------------------- |
| `palaces` | `list[Palace]` | 十二宫，索引 0 为寅宫、11 为丑宫 |
| `raw_dates` | `RawDates` | 结构化的农历生日与四柱干支标识 |
`palaces` 的索引是**宫位索引**而非宫名顺序：`palaces[0]` 永远是寅宫，
命宫可能落在其中任何一格。取命宫用 `chart.palace("soulPalace")`。
十二宫在**首次访问** `chart.palaces` 时才从底层 DTO 构建并回填反向引用。
只读日期、命主身主这些盘级字段的调用不必为此付出转换开销；
构建后缓存在实例上，之后每次访问都是同一批对象。
`raw_dates` 是 `lunar_date` / `chinese_date` 两个展示串的数据形式，
要做日期运算或按干支查表时用它，不必解析中文串：
| 类型 | 字段 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RawDates` | `lunar_date: RawLunarDate`、`chinese_date: RawChineseDate` |
| `RawLunarDate` | `lunar_year: int`、`lunar_month: int`（1–12）、`lunar_day: int`、`is_leap: bool` |
| `RawChineseDate` | 四柱的原始干支中文字（不随盘面语言翻译）`yearly` / `monthly` / `daily` / `hourly`（各是 `tuple[str, str]`），以及对应的标识 `yearly_keys` / `monthly_keys` / `daily_keys` / `hourly_keys` |
`RawChineseDate` 另有一个方法 `pillar_keys() -> list[tuple[str, str]]`，
按年、月、日、时的顺序一次给出四柱标识，正好是
[`utils.translate_chinese_date`](/zh/docs/python/util#translate_chinese_date) 的入参形状。
```python
rd = chart.raw_dates
print(rd.lunar_date.lunar_year, rd.lunar_date.lunar_month,
rd.lunar_date.lunar_day, rd.lunar_date.is_leap)
print(rd.chinese_date.yearly, rd.chinese_date.yearly_keys)
print(rd.chinese_date.pillar_keys())
```
**输出**
```text
2000 7 17 False
('庚', '辰') ('gengHeavenly', 'chenEarthly')
[('gengHeavenly', 'chenEarthly'), ('jiaHeavenly', 'shenEarthly'), ('bingHeavenly', 'wuEarthly'), ('gengHeavenly', 'yinEarthly')]
```
| 字段 | 类型 | 说明 |
| ------------ | ------------- | ------------------ |
| `time_index` | `int` | 出生时辰索引 |
| `fix_leap` | `bool` | 排盘时是否修正闰月 |
| `language` | `str` | 输出语言 |
| `config` | `ChartConfig` | 排盘配置，由 DTO 还原的六个开关 |
运限、重排与 Prompt 从这四项重新发起计算，因此不必再传一遍排盘参数。
`chart.config` 是从输出 DTO 还原的，只含六个开关；
排盘时传进来的自定义四化 / 亮度表不在里面。
但星盘内部保留了调用方给的原件，因此 `rearranged`、`horoscope`、
Prompt 这些二次计算仍然用得上那两张表——不会静默丢失。
***
## palace [#palace]
**用途** 按索引、宫名、身宫或来因宫取一宫。
**斗数含义** 十二宫是斗数的骨架。命宫定下后，其余十一宫按固定顺序逆时针排开。
「身宫」是十二宫之一同时被标记的那一宫，代表后天着力处；
「来因宫」是宫干与生年干相同的那一宫，代表事情的起因。
**签名**
```python
def palace(self, index_or_name: int | PalaceName | str) -> Palace | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------------ | -- | -- | ------- |
| `index_or_name` | `int \| str` | 是 | — | 四种写法见下表 |
| 写法 | 例子 | 含义 |
| ------ | -------------------------------- | --------------------------- |
| 索引 | `chart.palace(0)` | 宫位索引 0–11，0 为寅宫 |
| 宫名标识 | `chart.palace("soulPalace")` | 十二宫名标识之一，即 `PalaceName` 的值域 |
| 当前语言宫名 | `chart.palace("命宫")` | 与排盘语言一致的宫名文本 |
| 身宫 | `chart.palace("bodyPalace")` | 带身宫标记的那一宫 |
| 来因宫 | `chart.palace("originalPalace")` | 宫干与生年干相同的那一宫 |
**返回值** `Palace | None`。索引越界、宫名拼错时返回 `None`；
宫名、身宫、来因宫三种写法只要拼对，在任何一张盘上都能定位到。
**示例**
```python
soul = chart.palace("soulPalace")
print(soul.name, soul.heavenly_stem + soul.earthly_branch)
print("身宫落在", chart.palace("bodyPalace").name)
print("来因宫是", chart.palace("originalPalace").name)
print("寅宫是", chart.palace(0).name)
```
**输出**
```text
命宫 壬午
身宫落在 官禄
来因宫是 夫妻
寅宫是 财帛
```
**边界与陷阱**
来因宫要求宫干与生年干相同，且该宫不在子、丑二宫。
十二宫的天干由五虎遁从寅宫起排，寅到酉这十宫刚好把十天干各走一遍，
子、丑两宫重复了寅、卯的天干——正因为重复才被排除。
于是生年干在寅到酉之间必然命中且只命中一次：任何一张盘上来因宫都存在，且唯一。
身宫同理恒存在。因此 `None` 只可能来自索引越界或名字拼错。
`chart.palace("soulPalce")`（少一个 a）不会报错，只会返回 `None`——
`palace` 用的是逐宫比对而不是查表，比不中就是没有。
下一步再 `.name` 就变成 `AttributeError: 'NoneType' object has no attribute 'name'`，
错误现场离真正的笔误已经隔了一段。
要在写错的当场就发现，用枚举：`PalaceName.SOUL` 有 IDE 补全；
名字来自外部输入时先过一遍构造函数，非法值直接抛 `ValueError`：
```python
from x_iztro import PalaceName
print(PalaceName("soulPalace")) # StrEnum，打印出来就是它的值
try:
PalaceName("soulPalce")
except ValueError as e:
print("ValueError:", e)
```
**输出**
```text
soulPalace
ValueError: 'soulPalce' is not a valid PalaceName
```
同一条规律适用于 `star()`（星名拼错返回 `None`）与 `has()`
（星名拼错返回 `False`，因为「集合里没有这个标识」）。
枚举清单见[数据表](/zh/docs/python/data#枚举清单)。
***
## star / star\_in\_palace [#star--star_in_palace]
**用途** 按标识找到一颗星，或同时取回它所在的宫。
**签名**
```python
def star(self, star: str) -> Star | None
def star_in_palace(self, star: str) -> tuple[Star, Palace] | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | ----- | -- | -- | ---------------------------------------------- |
| `star` | `str` | 是 | — | 星耀标识（如 `"ziweiMaj"`），或**当前排盘语言**下的星名（如 `"紫微"`） |
**返回值** 该星不在这张盘上时返回 `None`。
`star_in_palace` 返回 `(星, 宫)` 二元组，省去再调 `star.palace()`。
**示例**
```python
ziwei = chart.star("ziweiMaj")
print(ziwei.name, "在", ziwei.palace().name)
print("对宫是", ziwei.opposite_palace().name)
print("亮度", ziwei.brightness, "四化", ziwei.mutagen)
star, palace = chart.star_in_palace("ziweiMaj")
print(star.key, palace.name_key)
```
**输出**
```text
紫微 在 命宫
对宫是 迁移
亮度 庙 四化 None
ziweiMaj soulPalace
```
**边界与陷阱**
只在主星、辅星、杂耀三组里查找。长生十二神、博士十二神、岁前与将前十二神
是每宫一个的标记而非星耀列表，用 `palace.changsheng12_key` 一类字段直接取。
***
## surrounded\_palaces [#surrounded_palaces]
**用途** 取目标宫的三方四正。
**斗数含义** 三方四正是斗数最常用的取象范围：本宫、对宫（本宫 +6）、
官禄位（本宫 +4）、财帛位（本宫 +8）。四个宫合起来看，而不只看本宫，
是因为对宫与三合宫的星耀同样作用于本宫的事。
**签名**
```python
def surrounded_palaces(self, index_or_name: int | PalaceName | str) -> SurroundedPalaces | None
```
**参数** 同 `palace`，四种定位写法都支持。
**返回值** `SurroundedPalaces | None`，含 `target` / `opposite` / `wealth` / `career` 四个 `Palace`。
定位不到（索引越界或宫名拼错）时返回 `None`。判断方法见[三方四正](/zh/docs/python/surpalaces)。
**示例**
```python
sp = chart.surrounded_palaces("soulPalace")
print(sp.target.name, sp.opposite.name, sp.wealth.name, sp.career.name)
print("三方四正见紫微:", sp.have(["ziweiMaj"]))
```
**输出**
```text
命宫 迁移 财帛 官禄
三方四正见紫微: True
```
***
## is\_surrounded / is\_surrounded\_one\_of / not\_surrounded [#is_surrounded--is_surrounded_one_of--not_surrounded]
**用途** 直接在星盘上判断某宫的三方四正里有没有指定星耀，省去先取三方四正的一步。
**签名**
```python
def is_surrounded(self, index_or_name: int | PalaceName | str, stars: list[str]) -> bool
def is_surrounded_one_of(self, index_or_name: int | PalaceName | str, stars: list[str]) -> bool
def not_surrounded(self, index_or_name: int | PalaceName | str, stars: list[str]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------------ | -- | -- | -------------- |
| `index_or_name` | `int \| str` | 是 | — | 定位方式同 `palace` |
| `stars` | `list[str]` | 是 | — | 星耀标识列表 |
**返回值**
| 方法 | 语义 |
| ---------------------- | ----------------- |
| `is_surrounded` | 列表中**每一颗**都在三方四正里 |
| `is_surrounded_one_of` | 列表中**至少一颗**在三方四正里 |
| `not_surrounded` | 列表中**一颗都不在**三方四正里 |
**示例**
```python
print(chart.is_surrounded("soulPalace", ["ziweiMaj", "tianxiangMaj"]))
print(chart.is_surrounded_one_of("soulPalace", ["qishaMaj", "pojunMaj"]))
print(chart.not_surrounded("soulPalace", ["huoxingMin"]))
```
**输出**
```text
True
False
True
```
命宫只坐紫微，天相在三方之一的财帛宫，因此第一行为真；
七杀与破军都不在这四宫内，第二行为假。
**边界与陷阱**
`stars` 传空列表时，`is_surrounded` 与 `not_surrounded` 返回 `True`
（「所有元素都满足」与「没有元素不满足」对空集都成立），
`is_surrounded_one_of` 返回 `False`。调用前先确认列表非空。
***
## flanking\_palaces [#flanking_palaces]
**用途** 取目标宫的夹宫：盘上紧邻它前后的两宫。
**斗数含义** 「羊陀夹忌」「日月夹命」这类说法看的就是夹宫。
夹宫与三方四正是两条不重叠的线索：三方四正问的是同一组能量彼此呼应，
夹宫问的是这一宫左右两侧的处境。
**签名**
```python
def flanking_palaces(self, index_or_name: int | PalaceName | str) -> FlankingPalaces | None
```
**参数** 同 `palace`，四种定位写法都支持。
**返回值** `FlankingPalaces | None`，两个 `Palace` 字段。定位不到时返回 `None`。
| 字段 | 相对目标宫 | 说明 |
| ---------- | ----- | --- |
| `previous` | -1 | 前一宫 |
| `next` | +1 | 后一宫 |
十二宫首尾相连，索引对 12 回绕：第 0 宫的前一宫是第 11 宫。
另有 `astrolabe()` 取回两宫所属的星盘。
五个判断方法与[三方四正](/zh/docs/python/surpalaces)同名同义，只是作用范围换成这两宫：
| 方法 | 语义 |
| -------------------------------------------- | ------------- |
| `have(stars: list[str]) -> bool` | 两宫合起来含列表中每一颗 |
| `not_have(stars: list[str]) -> bool` | 两宫一颗都不含 |
| `have_one_of(stars: list[str]) -> bool` | 两宫合起来至少含一颗 |
| `have_mutagen(mutagen: Mutagen) -> bool` | 两宫中有任一宫带该生年四化 |
| `not_have_mutagen(mutagen: Mutagen) -> bool` | 两宫都不带 |
星耀既可以写 `MajorStar` / `MinorStar` 这些枚举，也可以写当前语言的星名。
**示例**
```python
f = chart.flanking_palaces("soulPalace")
print(f.previous.name, "/", f.next.name)
print(f.have(["tianjiMaj", "tuoluoMin"]))
print(f.have_one_of(["huoxingMin"]))
w = chart.flanking_palaces("wealthPalace")
print(w.previous.name, "/", w.next.name)
print(w.have_mutagen("sihuaLu"), w.have_mutagen("sihuaJi"))
```
**输出**
```text
兄弟 / 父母
True
False
疾厄 / 子女
True True
```
命宫在午，夹它的是兄弟（巳）与父母（未）。天机坐兄弟、陀罗坐父母，分处两宫，
`have` 仍然成立；火星坐夫妻，不在这两宫之内，因此 `have_one_of` 为 `False`。
财帛在寅，夹它的疾厄坐天同、子女坐太阳，这张盘生年干庚使太阳化禄、天同化忌，
于是禄与忌两问都为 `True`。
**边界与陷阱**
`have(["A", "B"])` 问的是「A 和 B 都出现在这两宫里」，不要求它们同在其中一宫。
要单看某一侧，直接对 `f.previous` / `f.next` 调宫位的
[`has`](/zh/docs/python/palace#has--not_have--has_one_of)。
索引对 12 回绕，十二宫每一宫都有完整的前后两宫。
`have` 与 `not_have` 在空列表下返回 `True`，`have_one_of` 返回 `False`。
***
## horoscope [#horoscope]
**用途** 以本盘为起点计算目标日期的运限。
**签名**
```python
def horoscope(
self,
target_date: str | None = None,
target_time_index: int | None = None,
) -> Horoscope
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | ------------- | -- | ------ | ---------------- |
| `target_date` | `str \| None` | 否 | `None` | 目标公历日期；不传取今天 |
| `target_time_index` | `int \| None` | 否 | `None` | 目标时辰索引；不传取此刻所属时辰 |
**返回值** `Horoscope`——持有本盘的运限对象，六个层级的宫位查询不必再传星盘。
详见[运限对象](/zh/docs/python/horoscope)。
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
print("大限", h.decadal.heavenly_stem + h.decadal.earthly_branch)
print("流年", h.yearly.heavenly_stem + h.yearly.earthly_branch)
# 两个参数都可省略，取当下
now = chart.horoscope()
```
**输出**
```text
大限 庚辰
流年 乙巳
```
***
## to\_text [#to_text]
**用途** 星盘的语义化文本：面向语言模型与人的完整描述，`str(chart)` 等价。
**签名**
```python
def to_text(
self,
*,
knowledge: bool | KnowledgePack | None = None,
config: PatternConfig | None = None,
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------------------- | -- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `knowledge` | `bool \| KnowledgePack \| None` | 否 | `None` | 释义材料：`True` 取排盘语言的内嵌默认包，`KnowledgePack` 用该包（自定义或合并后的包）；给出时释义内联在事实之后——格局列表后跟格局释义（含成立条件），每宫事实后跟该宫星耀释义（同宫主星组合在前），文末附 `## 四化释义` |
| `config` | `PatternConfig \| None` | 否 | `None` | 格局判定口径，与 `patterns(config)` 同一入参；同时作用于文本的格局节与格局释义。`None` 取默认口径 |
**返回值** `str`——按排盘语言输出的 Markdown 子集：`# 命盘 …` 标题、`## 基本信息`、
`## 十二宫总览`（表）、`## 格局`、`## 十二宫`（从命宫起每宫一段 `### `）。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text#格式约定)，释义的插入位置见
[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```python
print(chart.to_text().splitlines()[0])
text = chart.to_text(knowledge=True)
print(len(chart.to_text()), len(text))
print(" ".join(l for l in text.splitlines() if l.startswith("## ")))
```
**输出**
```text
# 命盘 2000-8-16 寅时 女
3389 20767
## 基本信息 ## 十二宫总览 ## 格局 ## 十二宫 ## 四化释义
```
**边界与陷阱**
`knowledge=True` 而排盘语言没有内嵌包（目前只有 zh-CN 有）抛 `IztroError`（`invalid_argument`），
不会静默退回无释义；英文盘显式传一份 `KnowledgePack` 即可。
单宫与三方四正的文本见 `palace(...).to_text()` 与 `surrounded_palaces(...).to_text()`，
格局文本见 `patterns_to_text`（[格局判定](/zh/docs/python/patterns)）。
***
## to\_dict / to\_json [#to_dict--to_json]
**用途** 把星盘导出成与 JS iztro 字段契约一致的 JSON。
**签名**
```python
def to_dict(self) -> dict[str, Any]
def to_json(self, **kwargs: Any) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | -- | -- | -- | ---------------------------------------------------------- |
| `kwargs` | — | 否 | — | 仅 `to_json`：透传给 `json.dumps`，如 `indent=2`、`sort_keys=True` |
`to_json` 默认 `ensure_ascii=False`，中文直接落在输出里而不是 `\uXXXX`。
**返回值** `to_dict` 返回底层 DTO 的**深拷贝**——camelCase 键、值按排盘语言翻译，
另带 `*Key` 语言无关标识与排盘上下文。改它不会影响星盘。
`to_json` 返回同一份数据的 JSON 字符串，内容与 iztro 的
`JSON.stringify(astrolabe)` 逐键逐值对应。
**示例**
```python
d = chart.to_dict()
print(d["solarDate"], d["palaces"][4]["nameKey"])
print(d["config"]["yearDivide"], d["genderKey"], d["timeIndex"])
import json
print(json.dumps({k: d[k] for k in ("gender", "solarDate", "lunarDate")},
ensure_ascii=False))
print(len(chart.to_json()) > 10000, chart.to_json()[:1])
```
**输出**
```text
2000-8-16 soulPalace
normal female 2
{"gender": "女", "solarDate": "2000-8-16", "lunarDate": "二〇〇〇年七月十七"}
True {
```
底层 DTO 经原生扩展转成 Python `dict` 时按键名排序，
因此 `to_dict()` / `to_json()` 的顶层键是 `body`、`bodyKey`、`chineseDate`…… 这个次序，
不是 iztro 声明字段的次序。键名与取值逐个对应，只是排列不同；
要固定次序请自己按需要挑键输出。
**边界与陷阱**
`Astrolabe`、`Palace`、`Star` 都是 dataclass，但宫位与星耀各自持有一个指回本盘的
引用（`_astrolabe` / `_palace`）。`dataclasses.asdict(chart)` 会顺着这条回指
无限递归，最终 `RecursionError`。
导出一律走 `to_dict()` / `to_json()`——它们直接拿底层 DTO，既不递归也不丢字段。
`config` 只回显六个开关。排盘时传的自定义四化 / 亮度表是**输入**而非结果，
不进 DTO——这一点与 JS iztro 的字段契约一致。要记录用了哪张表，
请在自己的调用侧保存 `ChartConfig`。
`Horoscope` 上有同名的一对方法，形状一致，见[运限对象](/zh/docs/python/horoscope#to_dict--to_json)。
# 宫位对象 (/zh/docs/python/palace)
Palace 的字段，以及星耀判断、空宫判断与飞星族的全部方法。
宫位是斗数分析的主战场。`chart.palace(...)` 返回 `Palace`，
它既持有本宫数据，也能回溯所属星盘、对宫与三方四正。
```python
soul = chart.palace("soulPalace")
```
本页示例统一用默认的 `zh-CN` 排盘，因此输出里的展示值都是中文。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| --------------------------------------- | ------------ | --------------------------- |
| `index` | `int` | 宫位索引 0–11，0 为寅宫 |
| `name` / `name_key` | `str` | 宫名译名 / 标识 |
| `is_body_palace` | `bool` | 是否身宫 |
| `is_original_palace` | `bool` | 是否来因宫（宫干与年干相同且不在子丑二宫） |
| `heavenly_stem` / `heavenly_stem_key` | `str` | 宫干，决定本宫飞出的四化 |
| `earthly_branch` / `earthly_branch_key` | `str` | 宫支，由索引固定：0 为寅、11 为丑 |
| `major_stars` | `list[Star]` | 十四主星中落在本宫的，按安放顺序 |
| `minor_stars` | `list[Star]` | 十四辅星中落在本宫的 |
| `adjective_stars` | `list[Star]` | 杂耀 |
| `changsheng12` / `changsheng12_key` | `str` | 长生十二神，每宫恰好一个 |
| `boshi12` / `boshi12_key` | `str` | 博士十二神 |
| `jiangqian12` / `jiangqian12_key` | `str` | 将前十二神 |
| `suiqian12` / `suiqian12_key` | `str` | 岁前十二神 |
| `decadal` | `Decadal` | 大限：岁数区间与宫干支 |
| `ages` | `list[int]` | 小限经过本宫的虚岁列表 |
| `mutagen_star_keys` | `list[str]` | 本宫**宫干**化出的四颗星标识，顺序为禄、权、科、忌 |
主星、辅星、杂耀是**列表**，一宫可以有零到多颗。
长生、博士、将前、岁前十二神是**每宫恰好一个**的标记，十二宫刚好排满一轮，
因此是单值字段而不是列表。
它由**排盘时生效的**四化表算得——自定义四化表（`ChartConfig(mutagens=...)`）
会反映在这里，飞星族方法读的正是它。
生年四化是打在星耀自身 `mutagen_key` 字段上的标记，两者不是一回事。
***
## has / not\_have / has\_one\_of [#has--not_have--has_one_of]
**用途** 判断本宫坐了哪些星。
**斗数含义** 星耀落宫是斗数的基本盘面信息。「命宫坐紫微天相」即
`has(["ziweiMaj", "tianxiangMaj"])`。查找范围覆盖主星、辅星、杂耀三组。
**签名**
```python
def has(self, stars: list[str]) -> bool
def not_have(self, stars: list[str]) -> bool
def has_one_of(self, stars: list[str]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----------- | -- | -- | ------------------------ |
| `stars` | `list[str]` | 是 | — | 星耀标识列表；也接受**当前排盘语言**下的星名 |
**返回值**
| 方法 | 语义 |
| ------------ | ---------- |
| `has` | 列表中每一颗都在本宫 |
| `not_have` | 列表中一颗都不在本宫 |
| `has_one_of` | 列表中至少一颗在本宫 |
**示例**
```python
from x_iztro import MajorStar, MinorStar
soul = chart.palace("soulPalace")
print(soul.has([MajorStar.ZIWEI, MajorStar.TIANXIANG]))
print(soul.has_one_of([MajorStar.QISHA, MajorStar.ZIWEI]))
print(soul.not_have([MinorStar.HUOXING, MinorStar.LINGXING]))
```
**输出**
```text
False
True
True
```
这张盘的命宫只坐紫微，天相落在财帛宫，因此要求两颗都在的 `has` 为假。
**边界与陷阱**
空列表下 `has` 与 `not_have` 返回 `True`，`has_one_of` 返回 `False`。
比对的是「本宫全部星耀的标识与译名」这个集合，比不中就是没有——
`soul.has(["ziweiMj"])` 返回 `False` 而不报错，看起来跟「命宫没有紫微」一模一样。
外部输入的星名先过一遍枚举构造函数就能当场发现：
`MajorStar("ziweiMj")` 抛 `ValueError`。写死在代码里的用枚举成员，靠 IDE 补全。
***
## has\_mutagen / not\_have\_mutagen [#has_mutagen--not_have_mutagen]
**用途** 判断本宫有没有某种四化。
**斗数含义** 本命四化由**生年干**决定，标记打在对应的星上。
一宫「有化禄」意味着这宫里坐着的某颗星被生年干化了禄。
注意这与飞星不同——飞星看的是宫干，本处看的是星上已有的标记。
**签名**
```python
def has_mutagen(self, mutagen: Mutagen) -> bool
def not_have_mutagen(self, mutagen: Mutagen) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | ----- | -- | -- | ------------------------------------------------------- |
| `mutagen` | `str` | 是 | — | `"sihuaLu"` / `"sihuaQuan"` / `"sihuaKe"` / `"sihuaJi"` |
**返回值** `bool`。只扫描 `major_stars` 与 `minor_stars`，**不看杂耀**。
**示例**
```python
from x_iztro import Mutagen
children = chart.palace("childrenPalace")
print("子女宫有化禄:", children.has_mutagen(Mutagen.LU))
print("子女宫无化忌:", children.not_have_mutagen(Mutagen.JI))
```
**输出**
```text
子女宫有化禄: True
子女宫无化忌: True
```
**边界与陷阱**
`has_mutagen` 只看主星与辅星上的四化标记，杂耀即使带标记也不计入（复刻 iztro 的行为）。
生年四化只会落在十四主星与部分辅星上，因此实际盘面上两种口径通常没有差别。
***
## is\_empty [#is_empty]
**用途** 判断本宫是否空宫。
**斗数含义** 「空宫」指没有十四主星坐守的宫。空宫要借对宫主星来看，
是斗数里一个很常见的判断分支。辅星与杂耀默认不影响空宫的成立。
**签名**
```python
def is_empty(self, exclude_stars: list[str] | None = None) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ------------------- | -- | ------ | ---------------------------------- |
| `exclude_stars` | `list[str] \| None` | 否 | `None` | 追加计入的星耀：本宫无主星、但坐了其中任一颗时，同样**不算**空宫 |
**返回值** `bool`。判定顺序是：先看有无主星，有则不空；再看 `exclude_stars`，命中则不空；都不满足才是空宫。
**示例**
```python
parents = chart.palace("parentsPalace")
print("父母宫空宫:", parents.is_empty())
print("仆役宫空宫:", chart.palace("friendsPalace").is_empty())
# 父母宫无主星，但坐了陀罗——把陀罗也计入后就不算空宫
print("父母宫计入陀罗:", parents.is_empty(["tuoluoMin"]))
```
**输出**
```text
父母宫空宫: True
仆役宫空宫: False
父母宫计入陀罗: False
```
这张盘只有父母、田宅两宫无主星。仆役宫坐太阴，因此不算空宫。
**边界与陷阱**
`exclude_stars` 不是「判断时忽略这些星」，而是「这些星也算数」。
本宫已有主星时它完全不起作用——有主星就直接不是空宫，不再看这个列表。
不传 `exclude_stars` 时只检查 `major_stars`。一宫辅星杂耀满座但没有主星，仍然是空宫。
***
## flies\_to / flies\_one\_of\_to / not\_fly\_to [#flies_to--flies_one_of_to--not_fly_to]
**用途** 判断本宫宫干的四化是否飞入目标宫。
**斗数含义** 飞星派的核心手法。每个宫位有自己的宫干，宫干按四化表决定
哪四颗星化禄、权、科、忌。若被化的那颗星恰好坐在目标宫，就叫「本宫化 X 入目标宫」。
「命宫化禄入财帛」表达的是命宫这件事的顺遂落在财帛上。
**签名**
```python
def flies_to(self, target: Palace | int | str, mutagens: Mutagen | list[Mutagen]) -> bool
def flies_one_of_to(self, target: Palace | int | str, mutagens: Mutagen | list[Mutagen]) -> bool
def not_fly_to(self, target: Palace | int | str, mutagens: Mutagen | list[Mutagen]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ---------------------- | -- | -- | -------------------------------------------------- |
| `target` | `Palace \| int \| str` | 是 | — | 目标宫：宫位对象、索引、宫名、`"bodyPalace"` 或 `"originalPalace"` |
| `mutagens` | `str \| list[str]` | 是 | — | 要检查的四化，单个或列表 |
**返回值**
| 方法 | 语义 |
| ----------------- | ------------------ |
| `flies_to` | 列出的四化**全部**飞入目标宫 |
| `flies_one_of_to` | 列出的四化**至少一个**飞入目标宫 |
| `not_fly_to` | 列出的四化**一个都不**飞入目标宫 |
**示例**
```python
from x_iztro import Mutagen, PalaceName
soul = chart.palace("soulPalace")
print("命宫化禄入财帛:", soul.flies_to(PalaceName.WEALTH, Mutagen.LU))
print("命宫化禄或忌入迁移:", soul.flies_one_of_to(PalaceName.SURFACE, [Mutagen.LU, Mutagen.JI]))
print("命宫不化权入子女:", soul.not_fly_to(PalaceName.CHILDREN, Mutagen.QUAN))
```
**输出**
```text
命宫化禄入财帛: False
命宫化禄或忌入迁移: False
命宫不化权入子女: True
```
**边界与陷阱**
`mutagens` 传空列表时 `flies_to` 返回 `False`，
`flies_one_of_to` 与 `not_fly_to` 返回 `True`。
这与「空集上全称命题为真」的直觉相反，但复刻的是 iztro 的行为：
`flies_to` 先算出要找的星，一颗都没有就直接判假。传空通常是调用方的疏漏。
`target` 写成越界索引或拼错的宫名时，三个方法一律返回 `False`，
包括语义上「否定」的 `not_fly_to`——定位失败不等于「没飞进去」。
`ChartConfig(mutagens=...)` 换掉某个天干的四化表后，宫干落在该天干的宫飞出的星随之改变。
飞星族方法读的是排盘时生效的表，不是内置默认表。
目标宫写成本宫时，语义上是「自化」。此时用 `self_mutaged` 一族更直观。
***
## self\_mutaged / self\_mutaged\_one\_of / not\_self\_mutaged [#self_mutaged--self_mutaged_one_of--not_self_mutaged]
**用途** 判断本宫是否自化。
**斗数含义** 自化指本宫宫干化出的星恰好就坐在本宫。
含义上是「自己把自己的能量释放掉」，与飞入他宫的定向作用不同。
**签名**
```python
def self_mutaged(self, mutagens: Mutagen | list[Mutagen]) -> bool
def self_mutaged_one_of(self, mutagens: Mutagen | list[Mutagen] | None = None) -> bool
def not_self_mutaged(self, mutagens: Mutagen | list[Mutagen] | None = None) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | -------------------------- | --- | ------ | ----------------------- |
| `mutagens` | `str \| list[str] \| None` | 视方法 | `None` | 要检查的四化；后两个方法省略时表示「四化全部」 |
**返回值**
| 方法 | 语义 |
| --------------------- | ----------------------- |
| `self_mutaged` | 列出的四化全部自化 |
| `self_mutaged_one_of` | 列出的四化至少一个自化；省略参数时检查全部四化 |
| `not_self_mutaged` | 列出的四化一个都不自化；省略参数时检查全部四化 |
**示例**
```python
career = chart.palace("careerPalace")
print("官禄宫自化禄:", career.self_mutaged(Mutagen.LU))
print("官禄宫自化忌:", career.self_mutaged(Mutagen.JI))
print("官禄宫有任一自化:", career.self_mutaged_one_of())
print("官禄宫无任何自化:", career.not_self_mutaged())
```
**输出**
```text
官禄宫自化禄: False
官禄宫自化忌: True
官禄宫有任一自化: True
官禄宫无任何自化: False
```
官禄宫宫干为丙，丙干化忌在廉贞，而廉贞正坐官禄宫，故成自化忌。
**边界与陷阱**
`self_mutaged_one_of` 与 `not_self_mutaged` 把不传参数（或空列表）解释为「全部四化」。
`self_mutaged` 不做这层回退，空列表退化成「本宫是否包含空集」，恒为 `True`——
与 `flies_to` 的空列表判假正好相反，别把两者的直觉混用。
***
## mutaged\_places / mutagen\_stars [#mutaged_places--mutagen_stars]
**用途** 取本宫宫干化出的四颗星分别落在哪些宫，或直接取那四颗星本身。
**斗数含义** 飞星分析的全景版本：不问「有没有飞到某宫」，而是一次拿到禄权科忌的落点。
**签名**
```python
def mutaged_places(self, all_palaces: list[Palace] | None = None) -> list[Palace | None]
def mutagen_stars(self, mutagens: Mutagen | list[Mutagen]) -> list[str]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ---------------------- | -- | ------ | ------------ |
| `all_palaces` | `list[Palace] \| None` | 否 | `None` | 通常不传，宫位已持有星盘 |
| `mutagens` | `str \| list[str]` | 是 | — | 要取的四化位 |
**返回值** `mutaged_places` 返回长度为 4 的列表，顺序为**禄、权、科、忌**，
某颗被化的星不在盘上时对应位置为 `None`。
`mutagen_stars` 返回星耀标识列表，顺序与传入的四化一致。
**示例**
```python
soul = chart.palace("soulPalace")
for m, place in zip(["禄", "权", "科", "忌"], soul.mutaged_places()):
print(f"化{m} →", place.name if place else "不在盘上")
print(soul.mutagen_stars([Mutagen.LU, Mutagen.JI]))
```
**输出**
```text
化禄 → 子女
化权 → 命宫
化科 → 官禄
化忌 → 财帛
['tianliangMaj', 'wuquMaj']
```
命宫宫干为壬，壬干四化为天梁化禄、紫微化权、左辅化科、武曲化忌，
四颗星分别坐在子女、命宫、官禄、财帛四宫。
不传 `all_palaces` 时检索范围是本宫所属星盘的十二宫。
脱离星盘单独构造的宫位既没有星盘也没传范围，此时返回**空列表**而不是四个 `None`。
`mutaged_places` 恒按禄、权、科、忌四位取，不受参数影响；
要挑其中几位用 `mutagen_stars`。
***
## opposite\_palace / surrounded\_palaces / astrolabe [#opposite_palace--surrounded_palaces--astrolabe]
**用途** 从宫位回溯到对宫、三方四正与所属星盘。
**签名**
```python
def opposite_palace(self) -> Palace | None
def surrounded_palaces(self) -> SurroundedPalaces | None
def astrolabe(self) -> Astrolabe | None
```
**返回值** 脱离星盘单独构造的宫位返回 `None`；由星盘查询得到的宫位必然非空。
**示例**
```python
soul = chart.palace("soulPalace")
print(soul.name, "的对宫是", soul.opposite_palace().name)
print("三方四正见煞:", soul.surrounded_palaces().have_one_of(["huoxingMin", "lingxingMin"]))
print(soul.astrolabe().five_elements_class)
```
**输出**
```text
命宫 的对宫是 迁移
三方四正见煞: True
木三局
```
***
## to\_text [#to_text]
**用途** 本宫的语义化文本，与本命盘文本中该宫的段落一致。
**签名**
```python
def to_text(
self,
*,
knowledge: bool | KnowledgePack | None = None,
config: PatternConfig | None = None,
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------------------- | -- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledge` | `bool \| KnowledgePack \| None` | 否 | `None` | 释义材料：`True` 取排盘语言的内嵌默认包，`KnowledgePack` 用该包；给出时该宫事实行之后紧跟该宫每颗星的释义（`**星名(亮度)化X**: 正文`，同宫主星组合在前，十二神不释义），见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本) |
| `config` | `PatternConfig \| None` | 否 | `None` | 格局判定口径，与 `patterns(config)` 同一入参；同时作用于文本的格局节与格局释义。`None` 取默认口径 |
**示例**
```python
print(chart.palace("命宫").to_text(), end="")
print(chart.palace("命宫").to_text(knowledge=True).splitlines()[9][:15])
```
**输出**
```text
### 命宫 (壬午) · 大限 3-12
- 主星: 紫微(庙)
- 辅星: 文曲(陷)
- 杂耀: 凤阁, 天福, 截路, 蜚廉, 年解
- 三方四正: 对宫 迁移 · 三合 财帛, 官禄
- 宫干壬飞化: 天梁化禄→子女, 紫微化权→命宫, 左辅化科→官禄, 武曲化忌→财帛
- 十二神: 长生·衰, 博士·青龙, 岁前·丧门, 将前·灾煞
- 小限虚岁: 5, 17, 29, 41, 53, 65, 77, 89, 101, 113
**紫微(庙)**: 紫微星号
```
脱离星盘单独构造的宫位没有排盘上下文，调用抛 `ValueError`；
`knowledge=True` 而排盘语言没有内嵌包（目前只有 zh-CN 有）抛 `IztroError`。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
# 星耀对象 (/zh/docs/python/star-object)
Star 的字段与亮度、四化判断，以及回溯所在宫的能力。
`Star` 是一颗落在某宫的星，带着它的类型、亮度与四化标记，并能回溯所在宫。
```python
ziwei = chart.star("ziweiMaj")
```
本页示例统一用默认的 `zh-CN` 排盘，因此输出里的展示值都是中文。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| ---------------- | ------------- | ------------------------------ |
| `key` | `str` | 星耀标识，与语言无关，判断时用它 |
| `name` | `str` | 星名，按排盘语言翻译 |
| `type` | `str` | 星耀类型，见下表 |
| `scope` | `str` | 作用范围：本命星为 `"origin"`，流耀为对应运限层级 |
| `brightness` | `str \| None` | 亮度译名；没有亮度表的星耀为 `None` |
| `brightness_key` | `str \| None` | 亮度标识 |
| `mutagen` | `str \| None` | 生年四化译名；未被生年干化的星为 `None` |
| `mutagen_key` | `str \| None` | 四化标识 |
### 星耀类型的八个取值 [#星耀类型的八个取值]
| 取值 | 含义 | 典型成员 |
| ----------- | ---- | ----------------- |
| `major` | 十四主星 | 紫微、天府、七杀、破军 |
| `soft` | 吉星 | 左辅、右弼、文昌、文曲、天魁、天钺 |
| `tough` | 煞星 | 擎羊、陀罗、火星、铃星、地空、地劫 |
| `adjective` | 杂耀 | 三台、八座、天刑、天姚 |
| `flower` | 桃花星 | 红鸾、天喜、咸池 |
| `helper` | 解神 | 解神 |
| `lucun` | 禄存 | 禄存 |
| `tianma` | 天马 | 天马 |
禄存与天马各自独占一类，因为它们在传统分法里既非纯吉也非纯煞，判断时常单独拎出来。
只有十四主星与文昌、文曲、火星、铃星、擎羊、陀罗这二十颗有亮度表，
其余星耀本就没有亮度概念，`brightness` 为 `None`。
***
## with\_brightness [#with_brightness]
**用途** 判断这颗星是否处于给定亮度之一。
**斗数含义** 亮度（庙旺得利平不陷）描述星耀在该宫位的强弱。
同一颗星在十二宫各有定值，庙旺则力量充分发挥，落陷则受制。
**签名**
```python
def with_brightness(self, brightness: Brightness | list[Brightness]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------------------ | -- | -- | --------------------- |
| `brightness` | `str \| list[str]` | 是 | — | 亮度标识，单个或列表；列表时命中任一即为真 |
**返回值** `bool`。该星无亮度时恒为假。
**示例**
```python
from x_iztro import Brightness
ziwei = chart.star("ziweiMaj")
print(ziwei.with_brightness(Brightness.MIAO))
print(ziwei.with_brightness([Brightness.WANG, Brightness.DE]))
```
**输出**
```text
True
False
```
**边界与陷阱**
列表的语义是「命中任一」而非「全部命中」——一颗星只有一个亮度，
要求全部命中在列表多于一项时永假。
***
## with\_mutagen [#with_mutagen]
**用途** 判断这颗星是否带指定的生年四化。
**斗数含义** 生年四化由出生年干决定，一年固定四颗星分别化禄、权、科、忌。
这个标记跟着星走，无论那颗星落在哪一宫。
**签名**
```python
def with_mutagen(self, mutagen: Mutagen | list[Mutagen]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | ------------------ | -- | -- | --------------------- |
| `mutagen` | `str \| list[str]` | 是 | — | 四化标识，单个或列表；列表时命中任一即为真 |
**返回值** `bool`。该星未被生年干化时恒为假。
**示例**
```python
from x_iztro import Mutagen
print("紫微化禄:", chart.star("ziweiMaj").with_mutagen(Mutagen.LU))
print("太阳化禄:", chart.star("taiyangMaj").with_mutagen(Mutagen.LU))
```
**输出**
```text
紫微化禄: False
太阳化禄: True
```
这张盘生年干为庚，庚干太阳化禄，因此标记落在太阳而非紫微。
**边界与陷阱**
`with_mutagen` 看的是**生年干**给这颗星打的标记，一张盘上只有四颗星带标记。
宫干飞出的四化不在这里体现，用宫位的 [`flies_to`](/zh/docs/python/palace#flies_to--flies_one_of_to--not_fly_to) 一族。
***
## palace / opposite\_palace / surrounded\_palaces [#palace--opposite_palace--surrounded_palaces]
**用途** 从星回溯到它所在的宫、该宫的对宫与三方四正。
**签名**
```python
def palace(self) -> Palace | None
def opposite_palace(self) -> Palace | None
def surrounded_palaces(self) -> SurroundedPalaces | None
```
**返回值** 脱离星盘单独构造的星耀返回 `None`；由星盘查询得到的星耀必然非空。
**示例**
```python
ziwei = chart.star("ziweiMaj")
print(ziwei.palace().name)
print(ziwei.opposite_palace().name)
print("同宫或三方见天相:", ziwei.surrounded_palaces().have(["tianxiangMaj"]))
```
**输出**
```text
命宫
迁移
同宫或三方见天相: True
```
**边界与陷阱**
一颗星在一张盘上只出现一次，因此 `chart.star(key)` 的结果唯一。
运限流耀不在本命盘的星耀列表里，要取它们用运限对象的
[`palace`](/zh/docs/python/horoscope#palace) 配合层级参数。
# 三方四正 (/zh/docs/python/surpalaces)
SurroundedPalaces 的四个宫位与五个判断方法。
三方四正是斗数最常用的取象范围。看一件事不能只看本宫，
对宫与两个三合宫的星耀同样作用其上，四宫合看才完整。
本页示例统一用默认的 `zh-CN` 排盘，因此输出里的展示值都是中文。
## 四个宫位 [#四个宫位]
| 字段 | 相对本宫 | 传统称呼 | 意义 |
| ---------- | ---- | ---- | -------------- |
| `target` | +0 | 本宫 | 事情本身 |
| `opposite` | +6 | 对宫 | 与本宫相对的一面，影响最直接 |
| `career` | +4 | 官禄位 | 三合之一 |
| `wealth` | +8 | 财帛位 | 三合之一 |
四个字段都是 `Palace`，[宫位对象](/zh/docs/python/palace)的全部方法都能用。
`wealth` 与 `career` 指的是「相对本宫的三合位置」，不是十二宫里那两个固定的宫名。
以命宫起算时它们恰好落在财帛宫与官禄宫（+8 与 +4），名字就是这么对上的；
以别的宫起算则是别的宫。
## 三种取法 [#三种取法]
```python
# 从星盘取
sp = chart.surrounded_palaces("soulPalace")
# 从宫位取
sp = chart.palace("soulPalace").surrounded_palaces()
# 从星耀取（该星所在宫的三方四正）
sp = chart.star("ziweiMaj").surrounded_palaces()
```
三者结果相同，选哪个取决于手上已有什么。
***
## have / not\_have / have\_one\_of [#have--not_have--have_one_of]
**用途** 判断四宫合起来有没有指定星耀。
**斗数含义** 「三方四正见紫微」这类说法，问的正是这四宫里出没出现某颗星，
而不问具体落在其中哪一宫。
**签名**
```python
def have(self, stars: list[str]) -> bool
def not_have(self, stars: list[str]) -> bool
def have_one_of(self, stars: list[str]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----------- | -- | -- | ------------------------ |
| `stars` | `list[str]` | 是 | — | 星耀标识列表；也接受**当前排盘语言**下的星名 |
**返回值**
| 方法 | 语义 |
| ------------- | -------------------- |
| `have` | 列表中每一颗都出现在这四宫（不要求同宫） |
| `not_have` | 列表中一颗都没出现 |
| `have_one_of` | 列表中至少一颗出现 |
**示例**
```python
from x_iztro import MajorStar, MinorStar
sp = chart.surrounded_palaces("soulPalace")
print(sp.have([MajorStar.ZIWEI, MajorStar.TIANXIANG]))
print(sp.have_one_of([MajorStar.QISHA, MajorStar.POJUN]))
print(sp.not_have([MinorStar.HUOXING]))
```
**输出**
```text
True
False
True
```
紫微在命宫、天相在财帛宫，分处两宫但都在这四宫内，因此 `have` 为真。
**边界与陷阱**
`have([A, B])` 的语义是「A 和 B 都出现在这四宫里」，
不要求它们坐在同一宫。要判断同宫，用宫位的 [`has`](/zh/docs/python/palace#has--not_have--has_one_of)。
`have` 与 `not_have` 在空列表下返回 `True`，`have_one_of` 返回 `False`。
***
## have\_mutagen / not\_have\_mutagen [#have_mutagen--not_have_mutagen]
**用途** 判断四宫里有没有某种生年四化。
**斗数含义** 「三方四正见忌」意味着这组宫位里坐着一颗被生年干化忌的星，
是判断压力来源的常用条件。
**签名**
```python
def have_mutagen(self, mutagen: Mutagen) -> bool
def not_have_mutagen(self, mutagen: Mutagen) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | ----- | -- | -- | ------ |
| `mutagen` | `str` | 是 | — | 四化标识之一 |
**返回值** `bool`。
**示例**
```python
from x_iztro import Mutagen
sp = chart.surrounded_palaces("soulPalace")
print("三方四正见禄:", sp.have_mutagen(Mutagen.LU))
print("三方四正见忌:", sp.have_mutagen(Mutagen.JI))
print("三方四正不见科:", sp.not_have_mutagen(Mutagen.KE))
```
**输出**
```text
三方四正见禄: False
三方四正见忌: False
三方四正不见科: True
```
这张盘的生年四化落在四宫：太阳化禄在子女、武曲化权在财帛、太阴化科在仆役、天同化忌在疾厄。
命宫的三方四正是命宫、迁移、财帛、官禄——只有化权那一颗落在里面，
因此查禄、查忌都是 `False`，查权则会是 `True`。
**边界与陷阱**
这里看的是**生年四化**打在星上的标记，与宫干飞出的四化无关。
后者请用宫位的飞星族方法。
***
## to\_text [#to_text]
**用途** 三方四正的语义化文本：本宫、对宫、财帛位、官禄位各一段。
**签名**
```python
def to_text(
self,
*,
knowledge: bool | KnowledgePack | None = None,
config: PatternConfig | None = None,
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------------------- | -- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `knowledge` | `bool \| KnowledgePack \| None` | 否 | `None` | 释义材料：`True` 取排盘语言的内嵌默认包，`KnowledgePack` 用该包；给出时四宫各自的事实行之后紧跟该宫星耀的释义，见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本) |
| `config` | `PatternConfig \| None` | 否 | `None` | 格局判定口径，与 `patterns(config)` 同一入参；同时作用于文本的格局节与格局释义。`None` 取默认口径 |
**返回值** `str`——`## 命宫 三方四正` 标题之下四宫各一段 `### `，标题带角色前缀（本宫、对宫、财帛位、官禄位），
事实行与单宫 `to_text` 一致。
**示例**
```python
sp = chart.surrounded_palaces("命宫")
print("\n".join(l for l in sp.to_text().splitlines() if l.startswith("#")))
print(len(sp.to_text()), len(sp.to_text(knowledge=True)))
```
**输出**
```text
## 命宫 三方四正
### 本宫 · 命宫 (壬午) · 大限 3-12
### 对宫 · 迁移 (戊子) · 大限 63-72
### 财帛位 · 财帛 (戊寅) · 大限 43-52
### 官禄位 · 官禄 (丙戌) · 大限 83-92 [身宫]
924 6312
```
本宫脱离星盘单独构造时没有排盘上下文，调用抛 `ValueError`；
`knowledge=True` 而排盘语言没有内嵌包（目前只有 zh-CN 有）抛 `IztroError`。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
# 运限对象 (/zh/docs/python/horoscope)
六个运限层级的数据结构、整层取回的三个列表，以及不必再传星盘的宫位查询方法。
运限把本命盘投影到某个时间点上。同一张盘，不同年份看到的宫位分布不同——
这正是「大限走到哪一宫」的意思。
```python
h = chart.horoscope("2025-6-1", 0)
```
`Horoscope` 持有发起它的那张本命盘，因此所有查询方法都不必再把星盘传进去。
每个查询方法末尾那个 `astrolabe=None` 参数是为「手里只有运限数据、星盘另存」的场合留的，
日常用不着传。
本页示例统一用默认的 `zh-CN` 本命盘，因此输出里的展示值都是中文。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| --------------------------------------------------- | ----- | ---------------- |
| `solar_date` | `str` | **目标**公历日期，与入参一致 |
| `lunar_date` | `str` | 目标日期的农历中文写法 |
| `decadal` `age` `yearly` `monthly` `daily` `hourly` | 见下 | 六个运限层级 |
`solar_date` 是目标日期不是出生日期；出生日期在本命盘上，用 `h.astrolabe().solar_date` 取。
## 六个层级 [#六个层级]
| 字段 | 类型 | 跨度 | 说明 |
| --------- | ----------------- | --- | ------------- |
| `decadal` | `HoroscopeItem` | 十年 | 大限。未起运的幼年期为童限 |
| `age` | `AgeItem` | 一年 | 小限。按虚岁逐年走一宫 |
| `yearly` | `HoroscopeYearly` | 一年 | 流年。按流年干支定宫 |
| `monthly` | `HoroscopeItem` | 一月 | 流月 |
| `daily` | `HoroscopeItem` | 一日 | 流日 |
| `hourly` | `HoroscopeItem` | 一时辰 | 流时 |
两者都是一年一走，但起法不同：小限从生年地支起、按虚岁顺推，
流年直接看那一年的干支落在哪一宫。两条线互相独立，斗数里通常并看。
### HoroscopeItem [#horoscopeitem]
| 字段 | 类型 | 说明 |
| --------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
| `index` | `int` | 该层级落在哪一宫（宫位索引） |
| `name` | `str` | 层级显示名，按输出语言翻译 |
| `name_key` | `str` | 层级标识：`decadal` / `childhood`（童限，未起运）/ `turn`（小限）/ `yearly` / `monthly` / `daily` / `hourly`。判断层级用它，不要比对译文 |
| `heavenly_stem` / `heavenly_stem_key` | `str` | 该层级的天干，决定它飞出的四化 |
| `earthly_branch` / `earthly_branch_key` | `str` | 该层级的地支 |
| `palace_names` / `palace_name_keys` | `list[str]` | 以该层级所在宫为命宫重推的十二宫名，按宫位索引排列 |
| `mutagen` / `mutagen_star_keys` | `list[str]` | 该层级天干引发的四化星，顺序为禄权科忌；`mutagen_star_keys` 是被化四星的星耀标识，与宫位的同名字段同义 |
| `stars` | `list[list[Star]] \| None` | 该层级的流耀分布；无流耀的层级为 `None` |
`AgeItem` 与 `HoroscopeYearly` 继承 `HoroscopeItem`，各自多一个字段：
| 类型 | 多出的字段 | 说明 |
| ----------------- | -------------------------------- | ----------- |
| `AgeItem` | `nominal_age: int` | 该日期对应的虚岁 |
| `HoroscopeYearly` | `yearly_dec_star: YearlyDecStar` | 流年的岁前与将前十二神 |
```python
class YearlyDecStar:
jiangqian12: list[str] # 流年将前十二神译名，按宫位索引排列
jiangqian12_keys: list[str] # 对应标识
suiqian12: list[str] # 流年岁前十二神译名
suiqian12_keys: list[str] # 对应标识
```
因为是继承而不是包装，通用字段直接访问就行：写 `h.yearly.heavenly_stem`，
没有 Rust 侧那层 `.base`。
```python
h = chart.horoscope("2025-6-1", 0)
print(h.yearly.heavenly_stem, h.yearly.earthly_branch, h.age.nominal_age)
print(h.yearly.yearly_dec_star.suiqian12[:3])
print(h.yearly.yearly_dec_star.jiangqian12_keys[:3])
```
**输出**
```text
乙 巳 26
['天德', '吊客', '病符']
['jiesha', 'zhaisha', 'tiansha']
```
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
for item in (h.decadal, h.monthly, h.daily, h.hourly):
print(f"{item.name} 落在宫位 {item.index} 干支 {item.heavenly_stem}{item.earthly_branch}")
print("小限虚岁", h.age.nominal_age)
print("大限四化", h.decadal.mutagen)
```
**输出**
```text
大限 落在宫位 2 干支 庚辰
流月 落在宫位 3 干支 壬午
流日 落在宫位 8 干支 辛丑
流时 落在宫位 8 干支 戊子
小限虚岁 26
大限四化 ['太阳', '武曲', '太阴', '天同']
```
***
## 三个列表 [#三个列表]
`decadal_list` / `yearly_list` / `monthly_list` 是 `Astrolabe` 上的方法，不在运限对象上：
它们一次取回整层的运限项，省去按日期逐个调 `horoscope` 再自己拼。
三种列表项都继承 `HoroscopeItem`，通用字段直接访问，各自多带该层的时间坐标：
| 类型 | 多出的字段 | 说明 |
| ----------------- | ---------------------------------------- | ------------------------------- |
| `DecadalListItem` | `palace_name` / `palace_name_key`: `str` | 该大限所在的本命宫名 |
| | `age_range`: `tuple[int, int]` | 起止虚岁，含两端 |
| | `year_range`: `tuple[int, int]` | 起止农历年份，含两端 |
| `YearlyListItem` | `age`: `int` | 该流年对应的虚岁 |
| | `year`: `int` | 农历年份 |
| `MonthlyListItem` | `age`: `int` | 该流月对应的虚岁 |
| | `year`: `int` | 农历年份 |
| | `month`: `int` | 农历月份，正月为 1；闰月与同号常规月的 `month` 相同 |
| | `is_leap_month`: `bool` | 该项是否闰月 |
| | `part`: `str` | 分段标识，取值见 `MonthPart` 枚举 |
| | `day_range`: `tuple[int, int]` | 该段覆盖的农历日，含两端 |
`MonthPart` 三个取值：`NORMAL` 整月一段、`FIRST` 闰月前半、`SECOND` 闰月后半。
三个列表的每一项都以**时柱地支**对应的时辰计算，而不是排盘时传入的 `time_index`。
两者只在晚子时不同：入参 12 的盘，时柱地支是子，列表按时辰 0 起运限。
***
## decadal\_list [#decadal_list]
**用途** 一次取回本盘十二个大限，按起运先后排列。
**斗数含义** 大限十年一步，从起限宫顺逆行走十二宫。
把整条线摊平看，才知道某一段人生落在哪一宫、对应哪十年。
**签名**
```python
def decadal_list(self) -> list[DecadalListItem]
```
**返回值** 定长 12 项，第 0 项是第一个大限。顺序按起运虚岁排，
与宫位索引顺序无关（大限顺行逆行取决于阴阳男女）。
**示例**
```python
for d in chart.decadal_list()[:3]:
print(d.palace_name, d.heavenly_stem, d.earthly_branch, d.age_range, d.year_range)
print(len(chart.decadal_list()))
```
**输出**
```text
命宫 壬 午 (3, 12) (2002, 2011)
兄弟 辛 巳 (13, 22) (2012, 2021)
夫妻 庚 辰 (23, 32) (2022, 2031)
12
```
这张盘三岁起运，第一个大限落在命宫。
**边界与陷阱**
起运之前的那几年是童限，只有按具体日期查 `horoscope` 才会出现（`name_key` 为 `childhood`）。
`decadal_list` 列的是十二个大限本身，每项的 `name_key` 恒为 `decadal`。
***
## yearly\_list [#yearly_list]
**用途** 取一个大限内的全部流年。
**斗数含义** 定了大限再逐年细看，是斗数常规的推运顺序。
一个大限十年，对应的就是这十个流年。
**签名**
```python
def yearly_list(self, decadal: int | PalaceName | str | None = None) -> list[YearlyListItem]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | ---------------------------------- | -- | ------ | -------------------------------- |
| `decadal` | `int \| PalaceName \| str \| None` | 是 | `None` | 大限序号（`int`，0 为第一个大限）或该限所在的本命宫名标识 |
两种写法定位到同一个大限时结果完全相同，选哪个取决于手上已有什么。
**返回值** 10 项，按虚岁先后排列。
**异常** 未给出定位、大限序号越界、宫名定位不到时抛 `IztroError`。
**示例**
```python
years = chart.yearly_list(2)
for y in years[:3]:
print(y.age, y.year, y.heavenly_stem, y.earthly_branch, "->", y.index)
print(len(years), len(chart.yearly_list("spousePalace")))
```
**输出**
```text
23 2022 壬 寅 -> 0
24 2023 癸 卯 -> 1
25 2024 甲 辰 -> 2
10 10
```
第 2 个大限落在夫妻宫，因此 `yearly_list(2)` 与 `yearly_list("spousePalace")` 是同一个大限。
**边界与陷阱**
`decadal=None` 不是「取当前大限」，而是抛 `IztroError`——静默取一个默认值会把漏传
变成看起来成功的错答案。
***
## monthly\_list [#monthly_list]
**用途** 取一个农历年的全部流月。
**斗数含义** 流月是流年之下的一层，逐月推移。闰月怎么算是一个流派分歧点，
因此拆不拆由调用方定。
**签名**
```python
def monthly_list(self, year: int, fix_leap: bool = True) -> list[MonthlyListItem]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------ | -- | ------ | ------------ |
| `year` | `int` | 是 | — | 农历年份 |
| `fix_leap` | `bool` | 否 | `True` | 闰月是否拆成前后半月两项 |
**返回值** 长度取决于该年有无闰月与 `fix_leap`：
| 该农历年 | `fix_leap` | 项数 | 闰月怎么排 |
| ---- | ---------- | -- | -------------------------------------- |
| 无闰月 | 任意 | 12 | — |
| 有闰月 | `True` | 14 | 闰月拆成 `first`（初一至十五）与 `second`（十六至月末）两项 |
| 有闰月 | `False` | 13 | 闰月整月一项，`part` 为 `normal` |
闰月排在同月号的常规月之后。每项按该段首日算出（后半段取十六）。
**异常** 该农历年不存在，或某一段的目标日期落在支持范围外时抛 `IztroError`。
**示例**
```python
months = chart.monthly_list(2020)
print(len(months))
for m in months[3:7]:
print(m.month, m.is_leap_month, m.part, m.day_range, m.heavenly_stem, m.earthly_branch)
print(len(chart.monthly_list(2020, fix_leap=False)), len(chart.monthly_list(2021)))
```
**输出**
```text
14
4 False normal (1, 30) 辛 巳
4 True first (1, 15) 辛 巳
4 True second (16, 29) 壬 午
5 False normal (1, 30) 壬 午
13 12
```
农历 2020 年有闰四月。拆开之后，闰四月前半与四月同干支（辛巳），后半跟五月同干支（壬午）
——这正是「闰月下半月算下一个月」的意思。农历 2021 年无闰月，恒为 12 项。
**边界与陷阱**
排盘入口那个 `fix_leap` 决定闰月出生的人下半月按下个月安星，改的是本命盘布局；
这里这个只决定本列表拆不拆闰月。两者可以取不同的值，互不影响。
闰四月的 `month` 也是 `4`，靠 `is_leap_month` 区分。按 `month` 去重会把闰月弄丢。
***
## age\_palace [#age_palace]
**用途** 取小限当年所在的宫。
**斗数含义** 小限是逐年推移的一条线，落在哪一宫就以那宫为该年重点。
**签名**
```python
def age_palace(self, astrolabe: Astrolabe | None = None) -> Palace | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------- | -- | ------ | ------------- |
| `astrolabe` | `Astrolabe \| None` | 否 | `None` | 通常不传，运限已持有本命盘 |
**返回值** `Palace | None`——本命盘上的宫位。
运限已持有本命盘，因此实际不会是 `None`；只有手工构造、既没绑星盘也没传
`astrolabe` 的运限对象才拿不到。
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
print(h.age_palace().name)
```
**输出**
```text
田宅
```
***
## palace [#palace]
**用途** 取某个运限层级下、按该层级重推的十二宫中的某一宫。
**斗数含义** 大限走到某宫后，以那一宫为「大限命宫」重排十二宫。
「大限的夫妻宫」问的就是这套重排后的宫位，与本命夫妻宫通常不是同一宫。
**签名**
```python
def palace(
self,
name: PalaceName | str,
scope: Scope | ScopeLiteral,
astrolabe: Astrolabe | None = None,
) -> Palace | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------- | -- | ------ | ----------- |
| `name` | `str` | 是 | — | 要取的宫名标识 |
| `scope` | `str` | 是 | — | 在哪个层级的十二宫里找 |
| `astrolabe` | `Astrolabe \| None` | 否 | `None` | 通常不传 |
**返回值** `Palace | None`——本命盘上的宫位（同一格宫位在不同层级有不同宫名）。
层级为 `"origin"` 时即本命十二宫。宫名或层级标识拼错时返回 `None`，不报错。
**示例**
```python
from x_iztro import PalaceName, Scope
h = chart.horoscope("2025-6-1", 0)
print("大限命宫落在本命的", h.palace(PalaceName.SOUL, Scope.DECADAL).name)
print("本命命宫是", h.palace(PalaceName.SOUL, Scope.ORIGIN).name)
```
**输出**
```text
大限命宫落在本命的 夫妻
本命命宫是 命宫
```
**边界与陷阱**
`palace("soulPalace", "decadal")` 返回的宫位对象上，`name` 仍是**本命宫名**（例中的夫妻），
因为它就是本命盘上的那一格。要看该格在大限层级叫什么，查 `h.decadal.palace_names[index]`。
***
## surround\_palaces [#surround_palaces]
**用途** 取某个运限层级下某宫的三方四正。
**签名**
```python
def surround_palaces(
self,
name: PalaceName | str,
scope: Scope | ScopeLiteral,
astrolabe: Astrolabe | None = None,
) -> SurroundedPalaces | None
```
**参数** 同 `palace`。
**返回值** `SurroundedPalaces | None`，判断方法见[三方四正](/zh/docs/python/surpalaces)。
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
sp = h.surround_palaces(PalaceName.WEALTH, Scope.YEARLY)
print("流年财帛的三方四正以本命", sp.target.name, "为本宫")
```
**输出**
```text
流年财帛的三方四正以本命 疾厄 为本宫
```
***
## has\_horoscope\_stars / has\_one\_of\_horoscope\_stars / not\_have\_horoscope\_stars [#has_horoscope_stars--has_one_of_horoscope_stars--not_have_horoscope_stars]
**用途** 判断某层级某宫里有没有指定的流耀。
**斗数含义** 流耀是随运限层级产生的一组星：魁钺昌曲禄羊陀马鸾喜。
它们在不同层级有不同名字——大限层级叫运魁、运钺，流年层级叫流魁、流钺，
含义相同但作用于各自的时间跨度。
**签名**
```python
def has_horoscope_stars(self, name, scope, stars: list[str], astrolabe=None) -> bool
def has_one_of_horoscope_stars(self, name, scope, stars: list[str], astrolabe=None) -> bool
def not_have_horoscope_stars(self, name, scope, stars: list[str], astrolabe=None) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------- | -- | ------ | ------------- |
| `name` | `str` | 是 | — | 该层级下的宫名标识 |
| `scope` | `str` | 是 | — | 运限层级 |
| `stars` | `list[str]` | 是 | — | 流耀标识，须用该层级的名字 |
| `astrolabe` | `Astrolabe \| None` | 否 | `None` | 通常不传 |
**返回值**
| 方法 | 语义 |
| ---------------------------- | ----- |
| `has_horoscope_stars` | 每一颗都在 |
| `has_one_of_horoscope_stars` | 至少一颗在 |
| `not_have_horoscope_stars` | 一颗都不在 |
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
print(h.has_horoscope_stars(PalaceName.SOUL, Scope.DECADAL, ["yunlu"]))
print(h.has_one_of_horoscope_stars(PalaceName.SOUL, Scope.DECADAL, ["yunlu", "yunyang"]))
print(h.not_have_horoscope_stars(PalaceName.SOUL, Scope.DECADAL, ["yuntuo"]))
```
**输出**
```text
False
False
True
```
**边界与陷阱**
三个方法用 `scope` + `name` 定位到本命盘上的某一格，
但要比对的星耀集合恒为**大限流耀与流年流耀的并集**，与 `scope` 无关。
因此 `scope` 传 `"monthly"` 时，查的是「流月某宫这一格里有没有大限或流年的流耀」，
而不是流月自己的流耀——流月、流日、流时三层的流耀不参与这里的比对。
要按层级取流耀分布，用 `h.monthly.stars` 一类字段，或
[`star.get_horoscope_star`](/zh/docs/python/star#get_horoscope_star)。
大限流耀叫 `yunlu`（运禄）、`yunyang`（运羊）……，流年流耀叫 `liulu`（流禄）、
`liuyang`（流羊）……，两组标识不同名。由于比对集合恒是这两组的并集，
`yunlu` 与 `liulu` 在任何 `scope` 下都查得到，只是落宫不同。
各层级的标识对照见[安星模块](/zh/docs/python/star#get_horoscope_star)，
枚举形式见 `HoroscopeStar`。
***
## has\_horoscope\_mutagen [#has_horoscope_mutagen]
**用途** 判断某层级某宫里有没有该层级天干引发的四化。
**斗数含义** 每个运限层级有自己的天干，会像生年干一样化出四颗星。
「大限化禄落在大限财帛」这类判断问的就是这个。
**签名**
```python
def has_horoscope_mutagen(self, name, scope, mutagen: Mutagen, astrolabe=None) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------- | -- | ------ | --------- |
| `name` | `str` | 是 | — | 该层级下的宫名标识 |
| `scope` | `str` | 是 | — | 运限层级 |
| `mutagen` | `str` | 是 | — | 四化标识 |
| `astrolabe` | `Astrolabe \| None` | 否 | `None` | 通常不传 |
**返回值** `bool`。
**示例**
```python
from x_iztro import Mutagen
h = chart.horoscope("2025-6-1", 0)
print(h.has_horoscope_mutagen(PalaceName.SOUL, Scope.DECADAL, Mutagen.LU))
print(h.decadal.mutagen)
```
**输出**
```text
False
['太阳', '武曲', '太阴', '天同']
```
大限干为庚，庚干四化为太阳化禄、武曲化权、太阴化科、天同化忌。
**边界与陷阱**
本命层级没有「层级天干」这回事——生年四化已经打在星耀自身的 `mutagen_key` 上。
`has_horoscope_mutagen(name, "origin", m)` 因此直接返回 `False`，
不代表本命盘上没有这个四化。要查本命四化，用宫位的
[`has_mutagen`](/zh/docs/python/palace#has_mutagen--not_have_mutagen)。
只检查目标宫的**主星与辅星**，不看杂耀。
***
## scope\_item / astrolabe [#scope_item--astrolabe]
**用途** 按层级标识取对应的 `HoroscopeItem`，或回到本命盘。
**签名**
```python
def scope_item(self, scope: Scope | ScopeLiteral) -> HoroscopeItem | None
def astrolabe(self) -> Astrolabe | None
```
**返回值** `scope_item` 在层级为 `"origin"` 时返回 `None`——本命不是运限层级。
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
print(h.scope_item(Scope.DECADAL).name)
print(h.scope_item(Scope.ORIGIN))
print(h.astrolabe().solar_date)
```
**输出**
```text
大限
None
2000-8-16
```
**边界与陷阱**
`scope_item` 用于写按层级参数化的通用逻辑，比一串 `if scope == ...` 简洁。
`HoroscopeItem` 上另有 `palace_index_by_name(name)`，
把宫名在该层级的十二宫里换成宫位索引，查不到返回 `None`：
```python
h = chart.horoscope("2025-6-1", 0)
item = h.scope_item(Scope.DECADAL)
print(item.palace_index_by_name(PalaceName.SOUL))
print(item.palace_index_by_name(PalaceName.WEALTH))
print(item.palace_index_by_name("nosuch"))
```
**输出**
```text
2
10
None
```
***
## to\_text [#to_text]
**用途** 运限的语义化文本：面向语言模型与人的完整描述，`str(h)` 等价。
**签名**
```python
def to_text(
self,
*,
knowledge: bool | KnowledgePack | None = None,
config: PatternConfig | None = None,
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------------------------------- | -- | ------ | --------------------------------------------------------------------------------------- |
| `knowledge` | `bool \| KnowledgePack \| None` | 否 | `None` | 释义材料：`True` 取排盘语言的内嵌默认包，`KnowledgePack` 用该包；给出时每层事实之后紧跟该层流耀释义与该层视角命中格局的释义（跨层去重），本命星耀不重复 |
| `config` | `PatternConfig \| None` | 否 | `None` | 格局判定口径，与 `patterns(config)` 同一入参；同时作用于文本的格局节与格局释义。`None` 取默认口径 |
**返回值** `str`——按星盘排盘语言输出的 Markdown 子集：`# 运限 <日期> (<农历>)` 标题，
大限（未起运写童限）、小限、流年、流月、流日、流时各一节 `## `，大限与流年展开十二宫表，
各层带该层视角的四化、流耀与格局行。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text#格式约定)，释义的插入位置见
[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```python
h = chart.horoscope("2025-1-1", 0)
text = h.to_text(knowledge=True)
print(len(h.to_text()), len(text))
print("\n".join(l for l in text.splitlines() if l.startswith("#")))
```
**输出**
```text
2457 8458
# 运限 2025-1-1 (二〇二四年腊月初二)
## 大限 · 命宫: 本命夫妻 (庚辰)
## 小限 · 命宫: 本命官禄 · 虚岁 25
## 流年 · 命宫: 本命夫妻 (甲辰)
## 流月 · 命宫: 本命仆役 (丁丑)
## 流日 · 命宫: 本命迁移 (庚午)
## 流时 · 命宫: 本命迁移 (丙子)
```
**边界与陷阱**
脱离星盘单独构造的运限（`horoscope()` 之外的途径）没有排盘上下文，调用抛 `ValueError`。
格局命中的文本另见 `patterns_to_text`（[格局判定](/zh/docs/python/patterns)）。
`knowledge=True` 而排盘语言没有内嵌包（目前只有 zh-CN 有）抛 `IztroError`（`invalid_argument`）。
***
## to\_dict / to\_json [#to_dict--to_json]
**用途** 把运限导出成与 JS iztro 字段契约一致的 JSON。
**签名**
```python
def to_dict(self) -> dict[str, Any]
def to_json(self, **kwargs: Any) -> str
```
形状与用法同[星盘的同名方法](/zh/docs/python/astrolabe#to_dict--to_json)：
`to_dict` 给底层 DTO 的深拷贝，`to_json` 给 JSON 字符串且默认 `ensure_ascii=False`。
同样不要用 `dataclasses.asdict`——运限持有本命盘的引用，会无限递归。
**示例**
```python
h = chart.horoscope("2025-6-1", 0)
d = h.to_dict()
print(d["solarDate"], d["decadal"]["heavenlyStem"], d["age"]["nominalAge"])
print(sorted(d.keys()))
```
**输出**
```text
2025-6-1 庚 26
['age', 'daily', 'decadal', 'hourly', 'lunarDate', 'monthly', 'solarDate', 'yearly']
```
# 格局判定 (/zh/docs/python/patterns)
本命与运限的格局命中、PatternConfig 口径、PatternKey 枚举与判断方法。
格局是「盘上某几颗星按特定方式凑在一起」的模式识别。判定在本命盘与运限盘上共用同一套规则，
共 64 条。什么是格局、每条规则的条件与来源，见[概念页](/zh/docs/guide/concepts/patterns)。
```python
from x_iztro import Astro
chart = Astro().by_solar("1985-5-3", 9, "male")
hits = chart.patterns()
```
本页示例统一用默认的 `zh-CN` 本命盘，因此输出里的展示值都是中文。
## 类型 [#类型]
`PatternHit`、`PatternStar`、`PatternConfig` 是 frozen dataclass，
`PatternKey`、`BrightnessSource` 是 `StrEnum`，全部从 `x_iztro` 顶层导出。
### PatternHit [#patternhit]
| 字段 | 类型 | 说明 |
| ----------------- | ------------------- | ----------------------------- |
| `key` | `str` | 语言无关格局标识，取值域即 `PatternKey` |
| `name` | `str` | 格局名称，按排盘语言翻译 |
| `scope` | `str` | 判定视角：本命为 `"origin"`，运限为该层 |
| `palace_index` | `int` | 成格所在的宫位索引（0-11，寅宫为 0） |
| `palace_name` | `str` | 该宫在这个视角下的宫名 |
| `palace_name_key` | `str` | 宫名标识，取值域即 `PalaceName` |
| `variant` | `str \| None` | 多口径格局命中的口径；单口径为 `None` |
| `broken` | `bool` | 「破格 / 加杀平常」条件是否触发。成格照报，这里只作标记 |
| `stars` | `list[PatternStar]` | 参与成格的星与落宫 |
三个方法：
| 方法 | 说明 |
| ----------------- | ------------------------------------------- |
| `is_(key)` | 是否为指定格局，收 `PatternKey` 或字符串 |
| `in_palace(name)` | 成格宫位在该视角下是否为指定宫名，收 `PalaceName`、宫名标识或当前语言宫名 |
| `to_dict()` | 绑定层返回的原始 DTO（camelCase 键） |
### PatternStar [#patternstar]
| 字段 | 类型 | 说明 |
| ------------------------------- | ------------- | --------------------------- |
| `key` | `str` | 语言无关星耀标识 |
| `name` | `str` | 星耀名称，按排盘语言翻译 |
| `palace_index` | `int` | 该星**真正待的**宫位索引（借宫时不是借到的那一宫） |
| `brightness` / `brightness_key` | `str \| None` | 亮度显示文本与标识；无亮度为 `None` |
| `mutagen` / `mutagen_key` | `str \| None` | 判定视角下的四化与标识；无四化为 `None` |
两个方法：`has_brightness(b)`、`has_mutagen(m)`，都比标识，与排盘语言无关。
### PatternConfig [#patternconfig]
判定口径。凡是「同一格局的多种成立形式」都走 `PatternHit.variant`，这里只放会改变
**事实判定本身**的数据口径，因此只有三个字段。
```python
from x_iztro import PatternConfig, BrightnessSource
PatternConfig(
brightness_source=BrightnessSource.TABLE, # 默认
borrow=True, # 默认
flow_stars=True, # 默认
)
```
| 字段 | 默认 | 作用 |
| ------------------- | ------------------------ | ------------------------------- |
| `brightness_source` | `BrightnessSource.TABLE` | 日月明暗的依据 |
| `borrow` | `True` | 空宫是否借对宫主星参与判定 |
| `flow_stars` | `True` | 运限视角下流曜（运禄/流禄、运昌/流昌…）是否等同对应本命辅星 |
`BrightnessSource` 两个成员：`TABLE` 按星盘亮度表（庙旺为明，陷与「不」为暗，与 iztro 逐值一致），
`POSITIONAL` 按传统位置（太阳寅至午明、酉至丑暗；太阴酉至丑明、卯至未暗）。
两者的取舍见[概念页的说明](/zh/docs/guide/concepts/patterns#日月的明暗按哪张表)。
`PatternConfig` 是 frozen dataclass，改一项用 `dataclasses.replace`，
或直接构造一个新的——三个字段都有默认值，只写要改的那个即可。
### PatternKey [#patternkey]
64 个格局的语言无关标识，`StrEnum`，可直接与 `PatternHit.key` 比较：
```python
from x_iztro import PatternKey
print(len(list(PatternKey)))
print(PatternKey.SHA_PO_LANG)
print(PatternKey("sha_po_lang").name)
```
```text
64
sha_po_lang
SHA_PO_LANG
```
***
## patterns [#patterns]
**用途** 取本命盘的全部格局命中。
**斗数含义** 把这张盘上成立的所有有名字的星耀组合列出来，附上成格的宫位与证据星。
**签名**
```python
def patterns(self, config: PatternConfig | None = None) -> list[PatternHit]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ----------------------- | -- | ------ | ------------ |
| `config` | `PatternConfig \| None` | 否 | `None` | 判定口径；不传即默认口径 |
**返回值** `list[PatternHit]`——按来源页条目顺序排列；一条格局也不成立时为空列表。
本命盘上两条行运格（禄衰马困、风云际会）永远不出现。
**示例**
```python
chart = Astro().by_solar("1985-5-3", 9, "male")
for hit in chart.patterns():
print(f"{hit.name} {hit.palace_index} {hit.palace_name} broken={hit.broken}")
```
**输出**
```text
武贪同行 11 迁移 broken=False
府相朝垣 5 命宫 broken=False
杀破狼 11 迁移 broken=False
禄马交驰 5 命宫 broken=False
左右夹命 5 命宫 broken=False
文贵文华 11 迁移 broken=False
文星朝命 5 命宫 broken=True
文星暗拱 5 命宫 broken=False
文星暗拱 5 命宫 broken=False
```
取一条命中并读它的证据星：
```python
from x_iztro import PatternKey, PalaceName
hit = next(h for h in chart.patterns() if h.is_(PatternKey.FU_XIANG_CHAO_YUAN))
print(hit.name, hit.variant, hit.in_palace(PalaceName.SOUL))
for s in hit.stars:
print(" ", s.name, s.palace_index, s.brightness, s.brightness_key)
```
```text
府相朝垣 soul_empty True
天府 9 得 de
天相 1 陷 xian
```
按口径判：
```python
from x_iztro import PatternConfig, BrightnessSource
chart = Astro().by_solar("1985-6-10", 8, "female")
print([h.name for h in chart.patterns()])
print([h.name for h in chart.patterns(
PatternConfig(brightness_source=BrightnessSource.POSITIONAL))])
```
```text
[]
['日月反背']
```
**边界与陷阱**
多数格局成于命宫，但「身命」类格局（武贪同行、杀破狼、石中隐玉…）命宫身宫各判一次，
`palace_index` 记实际成格的那一宫，两宫都成立就返回两条命中。
禄马交驰更是任一宫成立即报，一张盘上可能有多条。
上面那张盘的身宫落在迁移宫，所以三条记的是迁移宫。
空宫借对宫主星时，`PatternStar.palace_index` 记的是那颗星实际落的宫（对宫），
不是借进来的宫。要知道格局成在哪一宫看 `PatternHit.palace_index`。
`hit.is_(PatternKey.SHA_PO_LANG)` 在任何排盘语言下结果一致；
比 `hit.name == "杀破狼"` 只在中文盘上成立。星耀与宫位同理，
用 `key` / `palace_name_key` 而不是 `name` / `palace_name`。
***
## Horoscope.patterns [#horoscopepatterns]
**用途** 取某个运限层级视角下的格局命中。
**斗数含义** 以该层的命宫为命宫、合并该层的流曜与四化之后重跑全部规则。
「本命有此组合，大限又走到即享其益」就是这么算出来的。
**签名**
```python
def patterns(
self,
scope: Scope | ScopeLiteral,
config: PatternConfig | None = None,
astrolabe: Astrolabe | None = None,
) -> list[PatternHit]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ----------------------- | -- | ------ | ------------------- |
| `scope` | `Scope \| str` | 是 | — | 判定视角所在的层级 |
| `config` | `PatternConfig \| None` | 否 | `None` | 判定口径 |
| `astrolabe` | `Astrolabe \| None` | 否 | `None` | 星盘；省略时取发起本次运限查询的那张盘 |
**返回值** `list[PatternHit]`，每条的 `scope` 即传入的层级。
传 `Scope.ORIGIN` 时结果与本命盘上直接调 `patterns()` 完全一致。
**异常** `ValueError`——既没传 `astrolabe`、本运限也不是由星盘发起时抛出。
用 `chart.horoscope(...)` 拿到的运限对象不会遇到这种情况。
**示例**
```python
from x_iztro import Scope
chart = Astro().by_solar("2000-8-16", 2, "female")
h = chart.horoscope("2025-6-1", 0)
for hit in h.patterns(Scope.DECADAL):
print(hit.name, hit.scope, hit.variant)
print(h.patterns("origin") == chart.patterns())
```
**输出**
```text
杀破狼 decadal None
风云际会 decadal None
风云际会 decadal yearly
True
```
同一张盘的本命视角只有一条「府相朝垣」——大限换了命宫，杀破狼才在这一层成立。
**边界与陷阱**
身宫是本命概念。运限视角下「身命」类格局只判该层命宫。
禄衰马困按当前视角那一层判（大限视角判大限，流年视角判流年），
限命宫三方四正又见七杀（古书严口径同时满足）时 `variant` 为 `"qisha"`；
风云际会跨层比较「两限同时逢禄马」，只在 `Scope.DECADAL` 视角判一次，
`variant` 同时记二限组合与「逢」的松紧：大限 + 小限命中为 `None`（三方四正会照）或
`"same_palace"`（两限命宫皆本宫坐禄马的严口径），大限 + 流年命中为
`"yearly"` 或 `"yearly_same_palace"`。两种组合各报一条，最多两条。
默认口径下运禄/流禄当禄存看、运昌/流昌当文昌看，其余同理。
不想要这个行为，传 `PatternConfig(flow_stars=False)`。
`patterns()` 不是在已有的星盘对象上做增量计算，而是把排盘上下文（生日、时辰、性别、
语言、config）送回内核重新发起一次判定。因此它不修改星盘，也不缓存结果——
在循环里反复调用时自己存一下返回值。
***
## to\_dict [#to_dict]
**用途** 取绑定层返回的原始 DTO：camelCase 键，值按排盘语言翻译，同时带语言无关标识。
需要把命中原样落库、发给前端或喂给模型时用它。
**签名**
```python
def to_dict(self) -> dict[str, Any]
```
**示例**
```python
import json
chart = Astro().by_solar("1985-5-3", 9, "male")
hit = next(h for h in chart.patterns() if h.is_(PatternKey.FU_XIANG_CHAO_YUAN))
print(json.dumps(hit.to_dict(), ensure_ascii=False, indent=2))
```
**输出**
```json
{
"broken": false,
"key": "fu_xiang_chao_yuan",
"name": "府相朝垣",
"palaceIndex": 5,
"palaceName": "命宫",
"palaceNameKey": "soulPalace",
"scope": "origin",
"stars": [
{
"brightness": "得",
"brightnessKey": "de",
"key": "tianfuMaj",
"name": "天府",
"palaceIndex": 9
},
{
"brightness": "陷",
"brightnessKey": "xian",
"key": "tianxiangMaj",
"name": "天相",
"palaceIndex": 1
}
],
"variant": "soul_empty"
}
```
无值的可选键（`variant`、亮度、四化）在 DTO 里直接省略，不会出现 `null`。
***
## patterns\_to\_text [#patterns_to_text]
**用途** 格局命中的语义化文本，每条一行 `- **格局名** (宫名, 破格): 构成星耀`，
破格在括号里与宫名并列。
**签名**
```python
def patterns_to_text(self, config: PatternConfig | None = None, *, knowledge=None) -> str # Astrolabe
def patterns_to_text(self, scope, config=None, astrolabe=None, *, knowledge=None) -> str # Horoscope
```
与 `patterns` 同一套判定（含重排上下文与判定口径）；运限版本的宫名
按该层重排后的宫名书写。`knowledge`（`bool | KnowledgePack | None`）：`True` 取排盘语言的
内嵌默认包，`KnowledgePack` 用该包；给出时命中列表之后紧跟每条命中格局的释义
（`**格局名**: ` 正文加 `成立条件: ` 段，同一格局只出一次），见
[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```python
print(chart.patterns_to_text(), end="")
print(chart.patterns_to_text(knowledge=True).splitlines()[4][:20])
```
**输出**
```text
# 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
**府相朝垣**: “食禄千锺”的断语使
```
运限视角同形：`chart.horoscope("2025-1-1", 0).patterns_to_text("yearly", knowledge=True)`，
宫名按流年重排后的宫名书写。
本命盘与运限的 `to_text` 已各自带格局节；单独调用适合只要格局摘要的场景。
# 轻量查询 (/zh/docs/python/query)
不排整盘就能拿到的生肖、星座与命宫主星。
有些问题不需要整张星盘。这五个函数各自只跑到必要的那一步就返回，
结果与完整排盘的对应字段永远一致——它们走的是同一套核心逻辑。
本页示例统一用默认的 `zh-CN` 排盘，因此输出里的展示值都是中文。
```python
from x_iztro import query
```
***
## get\_zodiac\_by\_solar\_date [#get_zodiac_by_solar_date]
**用途** 由公历日期取生肖。
**斗数含义** 生肖由**年支**决定，而年支的换算时点受 `year_divide` 影响。
正月初一与立春之间出生的人，两种配置会得到不同的生肖——这不是缺陷，是流派差异。
**签名**
```python
def get_zodiac_by_solar_date(
solar_date: str,
language: LanguageType = "zh-CN",
config: ChartConfig | None = None,
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | --------------------- | -- | --------- | -------------------- |
| `solar_date` | `str` | 是 | — | 公历日期，格式 `YYYY-M-D` |
| `language` | `str` | 否 | `"zh-CN"` | 输出语言 |
| `config` | `ChartConfig \| None` | 否 | `None` | 仅 `year_divide` 影响结果 |
**返回值** `str`——按语言翻译的生肖名。
**示例**
```python
print(query.get_zodiac_by_solar_date("2000-8-16"))
```
**输出**
```text
龙
```
**边界与陷阱**
默认按正月初一换年。改成 `ChartConfig(year_divide="exact")` 后按立春换年，
1 月下旬到 2 月上旬出生的人可能拿到不同生肖。
***
## get\_sign\_by\_solar\_date / get\_sign\_by\_lunar\_date [#get_sign_by_solar_date--get_sign_by_lunar_date]
**用途** 取星座。
**斗数含义** 星座是西洋占星概念，只由公历日期决定，与斗数算法无关。
农历版本先把农历转成公历再判定，因此两者对同一天的结果相同。
**签名**
```python
def get_sign_by_solar_date(solar_date: str, language: LanguageType = "zh-CN") -> str
def get_sign_by_lunar_date(
lunar_date: str,
is_leap_month: bool = False,
language: LanguageType = "zh-CN",
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------------- | ------ | -- | --------- | ---------------- |
| `solar_date` / `lunar_date` | `str` | 是 | — | 日期，格式 `YYYY-M-D` |
| `is_leap_month` | `bool` | 否 | `False` | 仅农历版本：该月是否闰月 |
| `language` | `str` | 否 | `"zh-CN"` | 输出语言 |
无 `config` 参数——星座不受任何配置影响。
**返回值** `str`。
**示例**
```python
print(query.get_sign_by_solar_date("2000-8-16"))
print(query.get_sign_by_lunar_date("2000-7-17"))
```
**输出**
```text
狮子座
狮子座
```
***
## get\_major\_star\_by\_solar\_date / get\_major\_star\_by\_lunar\_date [#get_major_star_by_solar_date--get_major_star_by_lunar_date]
**用途** 只取命宫主星，不排整盘。
**斗数含义** 命宫主星是斗数最常被单独问起的一项。
命宫为空宫时按惯例借对宫主星来看，本函数已经处理了这一步。
**签名**
```python
def get_major_star_by_solar_date(
solar_date: str,
time_index: TimeIndexType,
*,
fix_leap: bool = True,
language: LanguageType = "zh-CN",
config: ChartConfig | None = None,
) -> str
def get_major_star_by_lunar_date(
lunar_date: str,
time_index: TimeIndexType,
*,
is_leap_month: bool = False,
fix_leap: bool = True,
language: LanguageType = "zh-CN",
config: ChartConfig | None = None,
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------------- | --------------------- | -- | --------- | ------------------------------------ |
| `solar_date` / `lunar_date` | `str` | 是 | — | 日期 |
| `time_index` | `int` | 是 | — | 时辰索引 0–12，命宫由月份与时辰共同决定。之后的参数只能按关键字传入 |
| `is_leap_month` | `bool` | 否 | `False` | 仅农历版本 |
| `fix_leap` | `bool` | 否 | `True` | 是否修正闰月 |
| `language` | `str` | 否 | `"zh-CN"` | 输出语言 |
| `config` | `ChartConfig \| None` | 否 | `None` | 排盘配置 |
**返回值** `str`——多颗主星以逗号分隔；空宫时返回对宫主星。
**示例**
```python
print(query.get_major_star_by_solar_date("2000-8-16", 2))
print(query.get_major_star_by_solar_date("2000-8-16", 2, language="en-US"))
```
**输出**
```text
紫微
emperor
```
**边界与陷阱**
命宫由农历月份与出生时辰共同定位，因此 `time_index` 是必填的。
只知道日期不知道时辰时，斗数无法给出确定的命宫。
返回值是翻译后的字符串，换语言就会变。要做程序判断用下面的
`get_major_star_keys_by_solar_date` / `get_major_star_keys_by_lunar_date`，
或排整盘后比较 `major_stars` 里的 `key`。
***
## get\_major\_star\_keys\_by\_solar\_date / get\_major\_star\_keys\_by\_lunar\_date [#get_major_star_keys_by_solar_date--get_major_star_keys_by_lunar_date]
**用途** 命宫主星的语言无关标识列表——上面两个函数的 key 形态，供程序判断。
**签名**
```python
def get_major_star_keys_by_solar_date(
solar_date: str,
time_index: TimeIndexType,
*,
fix_leap: bool = True,
config: ChartConfig | None = None,
) -> list[str]
def get_major_star_keys_by_lunar_date(
lunar_date: str,
time_index: TimeIndexType,
*,
is_leap_month: bool = False,
fix_leap: bool = True,
config: ChartConfig | None = None,
) -> list[str]
```
**返回值** `list[str]`——`MajorStar` 枚举值域的标识（如 `"ziweiMaj"`）；
命宫为空宫时同样借对宫主星。标识与输出语言无关，因此**不收 `language`**。
**示例**
```python
print(query.get_major_star_keys_by_solar_date("2000-8-16", 2))
```
**输出**
```text
['ziweiMaj']
```
# 工具函数 (/zh/docs/python/util)
索引换算、亮度与四化查表、命身宫推算、大限小限、四柱展示串。
这些函数是排盘算法的零件。自己实现斗数逻辑、或要复核某一步推算时用得上；
日常排盘不必直接调用。
```python
from x_iztro import utils
```
参数与返回值中的标识都与语言无关，可直接与星盘上的 `*_key` 字段互操作。
返回结构体的函数给的是**具名 dataclass**，字段用属性访问；
返回单个标识的函数给的是枚举成员（`StrEnum`，与等值字符串可直接比较）。
***
## fix\_index [#fix_index]
**用途** 把任意整数约束到 `0..max` 的循环区间。
**斗数含义** 十二宫首尾相接，从丑宫（索引 11）再走一格回到寅宫（索引 0）。
所有「顺数几格、逆数几格」的推算都靠这个回绕。
**签名**
```python
def fix_index(index: int, max: int = 12) -> int
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----- | -- | ---- | ----------- |
| `index` | `int` | 是 | — | 待修正的索引，可为负 |
| `max` | `int` | 否 | `12` | 循环长度，天干用 10 |
**返回值** `int`，落在 `0..max`——含 0，**不含 `max`** 本身。
**示例**
```python
print(utils.fix_index(-1), utils.fix_index(13))
```
**输出**
```text
11 1
```
**边界与陷阱**
负数按数学取模回绕（-1 → 11），不是截断到 0。`max` 传 0 会抛
`ZeroDivisionError`，调用方自己保证它是正数——盘上的用法固定为 12 或 10。
***
## earthly\_branch\_to\_palace\_index [#earthly_branch_to_palace_index]
**用途** 地支转宫位索引。
**斗数含义** 十二宫的排列从**寅宫**起，而地支的自然顺序从**子**起，两者差两格。
这个函数负责这层换算：寅 → 0，卯 → 1，⋯，子 → 10，丑 → 11。
**签名**
```python
def earthly_branch_to_palace_index(branch: EarthlyBranch | str) -> int
```
**返回值** `int`，0–11。
**示例**
```python
from x_iztro import EarthlyBranch
print(utils.earthly_branch_to_palace_index(EarthlyBranch.YIN))
print(utils.earthly_branch_to_palace_index(EarthlyBranch.ZI))
```
**输出**
```text
0
10
```
***
## time\_to\_index [#time_to_index]
**用途** 小时数转时辰索引。
**斗数含义** 一天十二时辰，每时辰两小时，但子时横跨午夜被拆成早子时（0）与晚子时（12），
因此索引有 13 个值。
**签名**
```python
def time_to_index(hour: int) -> int
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | ----- | -- | -- | -------- |
| `hour` | `int` | 是 | — | 小时数 0–23 |
**返回值** `int`，0–12。
**示例**
```python
print(utils.time_to_index(0), utils.time_to_index(4), utils.time_to_index(23))
```
**输出**
```text
0 2 12
```
0 点为早子时，4 点为寅时，23 点为晚子时。排盘时不确定时辰索引，用这个函数换算。
***
## get\_age\_index [#get_age_index]
**用途** 由生年地支取小限起始宫位索引。
**斗数含义** 小限从固定的宫起，按虚岁逐年推移。起宫由生年地支所属的三合组决定：
寅午戌年起辰宫、申子辰年起戌宫、巳酉丑年起未宫、亥卯未年起丑宫。
**签名**
```python
def get_age_index(branch: EarthlyBranch | str) -> int
```
**返回值** `int`，0–11。
**示例**
```python
print(utils.get_age_index("chenEarthly"))
```
**输出**
```text
8
```
辰年属申子辰组，小限从戌宫起，戌宫的索引是 8。
***
## get\_brightness [#get_brightness]
**用途** 查某颗星落在某宫时的亮度。
**签名**
```python
def get_brightness(
star: str,
palace_index: int,
config: ChartConfig | None = None,
) -> Brightness | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | --------------------- | -- | ------ | --------------- |
| `star` | `str` | 是 | — | 星耀标识 |
| `palace_index` | `int` | 是 | — | 宫位索引，越界会对 12 取模 |
| `config` | `ChartConfig \| None` | 否 | `None` | 自定义亮度表会改变结果 |
**返回值** `Brightness` 枚举成员；该星没有亮度表时返回 `None`。
它是 `StrEnum`，`utils.get_brightness("ziweiMaj", 4) == "miao"` 成立。
星耀标识未知时抛 `IztroError`（`code` 为 `invalid_argument`）。
**示例**
```python
print(utils.get_brightness("ziweiMaj", 4))
print(utils.get_brightness("lucunMin", 0))
```
**输出**
```text
miao
None
```
紫微在午宫（索引 4）庙；禄存没有亮度表。
***
## get\_mutagen / get\_mutagens\_by\_heavenly\_stem [#get_mutagen--get_mutagens_by_heavenly_stem]
**用途** 查天干四化。
**斗数含义** 十天干各自固定指派四颗星化禄、权、科、忌。
`get_mutagen` 问「这颗星在这个天干下化什么」，
`get_mutagens_by_heavenly_stem` 问「这个天干化哪四颗星」。
**签名**
```python
def get_mutagen(star: str, stem: HeavenlyStem | str, config: ChartConfig | None = None) -> Mutagen | None
def get_mutagens_by_heavenly_stem(stem: HeavenlyStem | str, config: ChartConfig | None = None) -> list[str]
```
**返回值** `get_mutagen` 返回 `Mutagen` 枚举成员，该星不在此天干的四化表内时为 `None`。
`get_mutagens_by_heavenly_stem` 返回四项星耀标识列表（`list[str]`），顺序为**禄、权、科、忌**。
两者都受 `config` 里的自定义四化表影响。
**示例**
```python
print(utils.get_mutagen("taiyangMaj", "gengHeavenly"))
print(utils.get_mutagen("ziweiMaj", "gengHeavenly"))
print(utils.get_mutagens_by_heavenly_stem("gengHeavenly"))
```
**输出**
```text
sihuaLu
None
['taiyangMaj', 'wuquMaj', 'taiyinMaj', 'tiantongMaj']
```
***
## get\_soul\_and\_body [#get_soul_and_body]
**用途** 由农历月索引、时辰与年干推命宫、身宫。
**斗数含义** 命宫是整张盘的起点：从寅宫起正月，顺数到生月，再从生月逆数到生时。
身宫用同样的起点但顺数生时。命宫的天干由五虎遁从年干推得。
**签名**
```python
def get_soul_and_body(
month_index: int,
time_index: int,
yearly_stem: HeavenlyStem | str,
) -> SoulAndBody
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ----- | -- | -- | ---------------------------------------- |
| `month_index` | `int` | 是 | — | 农历月索引，正月为 0；由 `fix_lunar_month_index` 求得 |
| `time_index` | `int` | 是 | — | 时辰索引 0–12 |
| `yearly_stem` | `str` | 是 | — | 生年天干标识 |
**返回值** `SoulAndBody`：
| 字段 | 类型 | 说明 |
| ------------------------ | ----- | ------ |
| `soul_index` | `int` | 命宫宫位索引 |
| `body_index` | `int` | 身宫宫位索引 |
| `heavenly_stem_of_soul` | `str` | 命宫天干标识 |
| `earthly_branch_of_soul` | `str` | 命宫地支标识 |
**示例**
```python
sb = utils.get_soul_and_body(6, 2, "gengHeavenly")
print(sb)
print(sb.soul_index, sb.body_index, sb.earthly_branch_of_soul)
```
**输出**
```text
SoulAndBody(soul_index=4, body_index=8, heavenly_stem_of_soul='renHeavenly', earthly_branch_of_soul='wuEarthly')
4 8 wuEarthly
```
***
## get\_five\_elements\_class [#get_five_elements_class]
**用途** 由命宫干支推五行局。
**斗数含义** 五行局（水二、木三、金四、土五、火六）决定两件大事：
紫微星的起宫位置，以及大限的起运岁数。
**签名**
```python
def get_five_elements_class(stem: HeavenlyStem | str, branch: EarthlyBranch | str) -> str
```
**返回值** 五行局标识字符串（`FiveElementsClass` 的值域）。
**示例**
```python
print(utils.get_five_elements_class("renHeavenly", "wuEarthly"))
```
**输出**
```text
wood3rd
```
***
## get\_palace\_names [#get_palace_names]
**用途** 由命宫索引推十二宫名。
**斗数含义** 命宫定下后，其余十一宫按固定顺序逆时针排开：
命、兄弟、夫妻、子女、财帛、疾厄、迁移、仆役、官禄、田宅、福德、父母。
**签名**
```python
def get_palace_names(soul_index: int) -> list[PalaceName]
```
**返回值** 十二项 `PalaceName` 列表，**按宫位索引排列**——第 `i` 项就是 `chart.palaces[i]` 的宫名。
**示例**
```python
names = utils.get_palace_names(4)
print(names[:4])
print([str(n) for n in names[:4]])
print(names[0] == "wealthPalace")
```
**输出**
```text
[, , , ]
['wealthPalace', 'childrenPalace', 'spousePalace', 'siblingsPalace']
True
```
列表元素是 `PalaceName` 枚举成员，`repr` 带枚举名、`str` 给标识本身；
因为是 `StrEnum`，与字符串直接比较也成立。
命宫在索引 4，因此索引 0（寅宫）是财帛。
***
## get\_decadals\_and\_ages [#get_decadals_and_ages]
**用途** 由命宫索引与五行局推十二宫的大限与小限。
**斗数含义** 大限起运岁数由五行局决定（水二局 2 岁起、木三局 3 岁起，依此类推），
顺逆由性别阴阳与年支阴阳决定；小限起宫由年支决定，按虚岁逐年推移。
**签名**
```python
def get_decadals_and_ages(
soul_index: int,
five_elements_class: str,
gender: str,
yearly_stem: HeavenlyStem | str,
yearly_branch: EarthlyBranch | str,
) -> DecadalsAndAges
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------- | ----- | -- | -- | --------------------- |
| `soul_index` | `int` | 是 | — | 命宫宫位索引 |
| `five_elements_class` | `str` | 是 | — | 五行局标识 |
| `gender` | `str` | 是 | — | `"male"` 或 `"female"` |
| `yearly_stem` | `str` | 是 | — | 年干标识 |
| `yearly_branch` | `str` | 是 | — | 年支标识 |
**返回值** `DecadalsAndAges`，两个字段都按宫位索引排列：
| 字段 | 类型 | 说明 |
| ---------- | ----------------- | ------------ |
| `decadals` | `list[Decadal]` | 十二宫各自的大限 |
| `ages` | `list[list[int]]` | 十二宫各自的小限虚岁列表 |
`Decadal` 与宫位上的 `palace.decadal` 是同一个类型：
| 字段 | 类型 | 说明 |
| --------------------------------------- | ----------------- | ------------ |
| `range` | `tuple[int, int]` | 大限起止虚岁，含两端 |
| `heavenly_stem` / `heavenly_stem_key` | `str` | 大限天干的译名 / 标识 |
| `earthly_branch` / `earthly_branch_key` | `str` | 大限地支的译名 / 标识 |
**示例**
```python
d = utils.get_decadals_and_ages(4, "wood3rd", "female", "gengHeavenly", "chenEarthly")
print(d.decadals[0])
print(d.decadals[0].range, d.decadals[0].earthly_branch_key)
print(d.ages[0][:3])
```
**输出**
```text
Decadal(range=(43, 52), heavenly_stem='戊', heavenly_stem_key='wuHeavenly', earthly_branch='寅', earthly_branch_key='yinEarthly')
(43, 52) yinEarthly
[9, 21, 33]
```
`Decadal` 的译名字段按 **zh-CN** 生成——这个函数不收 `language` 参数。
要别的语言用 `heavenly_stem_key` 走 [`i18n.translate`](/zh/docs/python/i18n#translate)。
**边界与陷阱**
整盘排出的每个宫位上已有 `decadal` 与 `ages` 字段，内容与本函数一致。
这个函数用于不排整盘、只推大限小限的场合。
***
## fix\_lunar\_month\_index / fix\_lunar\_day\_index [#fix_lunar_month_index--fix_lunar_day_index]
**用途** 求修正后的农历月索引与日索引。
**斗数含义** 闰月归属与晚子时归属是斗数两个长期有争议的边界，这两个函数把规则落定：
闰月十六日起按下月算（可关，且晚子时不进位），晚子时的日索引属次日。
**签名**
```python
def fix_lunar_month_index(
lunar_month: int,
lunar_day: int,
is_leap: bool,
time_index: int,
fix_leap: bool,
) -> int
def fix_lunar_day_index(lunar_day: int, time_index: int) -> int
```
**返回值** 月索引为 0-based（正月为 0）；日索引在晚子时不减一。
`fix_lunar_month_index` 进位要同时满足四个条件：`is_leap` 为真、`fix_leap` 为真、
`lunar_day` 大于 15、且 `time_index` 不是 12。四者缺一，就按本月算。
**示例**
```python
print(utils.fix_lunar_month_index(7, 17, False, 2, True))
print(utils.fix_lunar_day_index(17, 2), utils.fix_lunar_day_index(17, 12))
```
**输出**
```text
6
16 17
```
七月非闰月，索引为 6；十七日在寅时减一得 16，在晚子时属次日故保持 17。
***
## translate\_chinese\_date [#translate_chinese_date]
**用途** 把四柱干支拼成展示串。
**签名**
```python
def translate_chinese_date(
pillars: list[tuple[str, str]],
language: str = "zh-CN",
) -> str
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ----------------------- | -- | --------- | ------------------------------- |
| `pillars` | `list[tuple[str, str]]` | 是 | — | 四柱标识 \[年, 月, 日, 时]，每柱为 (天干, 地支) |
| `language` | `str` | 否 | `"zh-CN"` | 输出语言 |
**返回值** `str`。词条均为单字符时柱内紧凑相连、柱间空格；
任一词条为多字符时柱内空格、柱间 `-`。
**示例**
```python
pillars = [
("gengHeavenly", "chenEarthly"),
("jiaHeavenly", "shenEarthly"),
("bingHeavenly", "wuEarthly"),
("gengHeavenly", "yinEarthly"),
]
print(utils.translate_chinese_date(pillars))
# 星盘上的四柱标识可直接取
print(utils.translate_chinese_date(chart.raw_dates.chinese_date.pillar_keys()))
```
**输出**
```text
庚辰 甲申 丙午 庚寅
庚辰 甲申 丙午 庚寅
```
**边界与陷阱**
柱数不为四、某柱不是两项，或干支标识非法时抛 `IztroError`（`code` 为 `invalid_argument`）。
***
## merge\_stars [#merge_stars]
**用途** 把多组「十二宫星耀」按宫位合并成一组。
**斗数含义** 安星是分批进行的：主星、辅星、杂耀各出一组十二宫列表。
要把它们并成一张完整盘面时用这个函数。
**签名**
```python
def merge_stars(*groups: list[list[Star]]) -> list[list[Star]]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ------------------ | -- | -- | ------------------------------------------------------------------------- |
| `groups` | `list[list[Star]]` | 是 | — | 若干组十二宫星耀列表，每组长度须为 12。注意是**可变参数**：写 `merge_stars(major, minor)`，不是传一个列表的列表 |
**返回值** 合并后的十二宫列表，同宫内按传入顺序首尾相接。
**示例**
```python
from x_iztro import star
major = star.get_major_star("2000-8-16", 2, "female")
minor = star.get_minor_star("2000-8-16", 2, "female")
merged = utils.merge_stars(major, minor)
print([s.name for s in merged[0]])
```
**输出**
```text
['武曲', '天相', '天马']
```
**边界与陷阱**
某一组的长度不是 12 时抛 `ValueError`。这是纯本地实现，不经绑定层。
# 安星模块 (/zh/docs/python/star)
按出生数据取某一组星耀的落宫。
不排整盘、只想知道「禄存落在哪一宫」或「这张盘的杂耀怎么分布」时用这一层。
```python
from x_iztro import star
```
所有索引都是**宫位索引**：0 为寅宫，11 为丑宫。
## 共用参数 [#共用参数]
按出生数据安星的入口共用同一组参数：
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------------------- | --------------------- | -- | --------- | ------------------ |
| `solar_date` | `str` | 是 | — | 公历日期，格式 `YYYY-M-D` |
| `time_index` | `int` | 是 | — | 时辰索引 0–12 |
| `gender` | `str` | 否 | `"male"` | 性别，决定长生与博士十二神的顺逆 |
| `fix_leap` | `bool` | 否 | `True` | 是否修正闰月 |
| `language` | `str` | 否 | `"zh-CN"` | 星耀名称的输出语言 |
| `config` | `ChartConfig \| None` | 否 | `None` | 排盘配置 |
| `from_stem` / `from_branch` | `str \| None` | 否 | `None` | 起五行局的干支；两者须同时给出 |
```python
birth = dict(solar_date="2000-8-16", time_index=2, gender="female")
```
本页示例统一用默认的 `zh-CN`，因此星名输出都是中文。
各入口的返回值都是**具名 dataclass**（不是 dict），字段用属性访问：
`star.get_start_index(**birth).ziwei_index`。
两者同时给出后，五行局改由该干支推算，进而改变紫微天府落点与长生十二神。
其余各组星的起法不受影响。用它可以取到中州派地盘、人盘的安星结果。
支持这两个参数的只有 `get_start_index`、`get_major_star`、`get_changsheng12`。
***
## get\_start\_index [#get_start_index]
**用途** 求紫微、天府的起始宫位。
**斗数含义** 紫微是全盘的锚点：由五行局与农历生日按「起紫微星诀」定位，
其余十三颗主星再依紫微与天府的位置铺开。天府与紫微的位置互为镜像。
**签名**
```python
def get_start_index(solar_date, time_index, gender="male", fix_leap=True,
language="zh-CN", config=None, from_stem=None, from_branch=None) -> dict[str, int]
```
**返回值** `StartIndex`，字段 `ziwei_index`、`tianfu_index`。
**示例**
```python
s = star.get_start_index(**birth)
print(s)
print(s.ziwei_index, s.tianfu_index)
```
**输出**
```text
StartIndex(ziwei_index=4, tianfu_index=8)
4 8
```
***
## 各组落宫索引 [#各组落宫索引]
以下六个入口形状一致：收出生数据，返回一个字段全是宫位索引的 dataclass。
| 函数 | 返回类型 | 字段 | 起法依据 |
| -------------------------- | ------------------ | ---------------------------------------------- | ----------------- |
| `get_lu_yang_tuo_ma_index` | `LuYangTuoMaIndex` | `lu_index` `yang_index` `tuo_index` `ma_index` | 年干定禄存，禄前羊后陀；天马按年支 |
| `get_kui_yue_index` | `KuiYueIndex` | `kui_index` `yue_index` | 年干 |
| `get_chang_qu_index` | `ChangQuIndex` | `chang_index` `qu_index` | 时支 |
| `get_kong_jie_index` | `KongJieIndex` | `kong_index` `jie_index` | 时支 |
| `get_timely_star_index` | `TimelyStarIndex` | `taifu_index` `fenggao_index` | 时支 |
| `get_luan_xi_index` | `LuanXiIndex` | `hongluan_index` `tianxi_index` | 年支 |
**示例**
```python
print(star.get_lu_yang_tuo_ma_index(**birth))
print(star.get_chang_qu_index(**birth))
print(star.get_luan_xi_index(**birth))
```
**输出**
```text
LuYangTuoMaIndex(lu_index=6, yang_index=7, tuo_index=5, ma_index=0)
ChangQuIndex(chang_index=6, qu_index=4)
LuanXiIndex(hongluan_index=9, tianxi_index=3)
```
擎羊在禄存前一格、陀罗在后一格，这是「禄前羊刃当，禄后陀罗府」的直接体现。
***
## get\_daily\_star\_index / get\_monthly\_star\_index / get\_yearly\_star\_index [#get_daily_star_index--get_monthly_star_index--get_yearly_star_index]
**用途** 取按日、按月、按年起的杂耀落宫。
**斗数含义** 杂耀按起法分组：日系星从辅星位置起初一顺数到生日；
月系星按农历月份定位；年系星最多，按年干或年支起。
**返回值**
| 函数 | 返回类型 | 字段 |
| ------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_daily_star_index` | `DailyStarIndex` | `santai_index` `bazuo_index` `enguang_index` `tiangui_index` |
| `get_monthly_star_index` | `MonthlyStarIndex` | `yuejie_index`（解神） `tianyao_index` `tianxing_index` `yinsha_index` `tianyue_index` `tianwu_index` |
| `get_yearly_star_index` | `YearlyStarIndex` | 27 项：`xianchi_index` `huagai_index` `guchen_index` `guasu_index` `tiancai_index` `tianshou_index` `tianchu_index` `posui_index` `feilian_index` `longchi_index` `fengge_index` `tianku_index` `tianxu_index` `tianguan_index` `tianfu_index` `tiande_index` `yuede_index` `tiankong_index` `jielu_index` `kongwang_index` `xunkong_index` `tianshang_index` `tianshi_index` `jiekong_index` `jiesha_adj_index` `nianjie_index` `dahao_adj_index` |
红鸾、天喜也属年系，但不在 `YearlyStarIndex` 里——它们由
`get_luan_xi_index` 单独给出。
**示例**
```python
d = star.get_daily_star_index(**birth)
m = star.get_monthly_star_index(**birth)
y = star.get_yearly_star_index(**birth)
print(d)
print(m.yuejie_index, m.tianyao_index, m.tianxing_index)
print(y.xianchi_index, y.huagai_index, y.tianshang_index, y.tianshi_index)
```
**输出**
```text
DailyStarIndex(santai_index=0, bazuo_index=10, enguang_index=9, tiangui_index=7)
0 5 1
7 2 9 11
```
**边界与陷阱**
年系杂耀属流年神煞，取年支时用的是 `horoscope_divide` 而非 `year_divide`。
两个配置不同时，年系星与主星、辅星可能基于不同的年支——这是刻意的流派区分。
这三项只在 `algorithm` 为中州派时进入盘面，替换掉截路、空亡与大耗的默认取法；
默认派别下它们仍会被算出来，只是不安进宫位。
***
## get\_major\_star / get\_minor\_star / get\_adjective\_star [#get_major_star--get_minor_star--get_adjective_star]
**用途** 取主星、辅星、杂耀在十二宫的完整分布。
**签名**
```python
def get_major_star(...) -> list[list[Star]]
def get_minor_star(...) -> list[list[Star]]
def get_adjective_star(...) -> list[list[Star]]
```
**返回值** 十二项列表，按宫位索引排列。每项是该宫的 `Star` 列表（可能为空）。
**示例**
```python
major = star.get_major_star(**birth)
for i, stars in enumerate(major[:5]):
print(i, [s.name for s in stars])
```
**输出**
```text
0 ['武曲', '天相']
1 ['太阳', '天梁']
2 ['七杀']
3 ['天机']
4 ['紫微']
```
**边界与陷阱**
返回的 `Star` 带亮度与生年四化标记，与整盘排出的完全一致——
它们走的是同一段代码。要取整盘的话直接用 `Astro().by_solar(...)` 更省事。
***
## get\_changsheng12 / get\_boshi12 / get\_yearly12 [#get_changsheng12--get_boshi12--get_yearly12]
**用途** 取四组十二神在十二宫的排列。
**斗数含义** 这四组各是十二个标记排满十二宫，每宫恰好一个：
长生十二神按五行局起、随性别与年支阴阳定顺逆；
博士十二神从禄存起、同样定顺逆；
岁前十二神从年支起顺行；将前十二神按年支三合组起。
**签名**
```python
def get_changsheng12(...) -> list[str]
def get_boshi12(...) -> list[str]
def get_yearly12(...) -> dict[str, list[str]]
```
**返回值** `get_changsheng12` 与 `get_boshi12` 返回十二项标识列表，按宫位索引排列。
`get_yearly12` 返回 `Yearly12`，字段 `suiqian12`、`jiangqian12` 各是一个十二项标识列表。
**示例**
```python
print(star.get_changsheng12(**birth)[:4])
print(star.get_boshi12(**birth)[:4])
y = star.get_yearly12(**birth)
print(y.suiqian12[:4])
print(y.jiangqian12[:4])
```
**输出**
```text
['jue', 'mu', 'si', 'bing']
['faylian', 'zhoushu', 'jiangjun', 'xiaohao']
['diaoke', 'bingfu', 'suijian', 'huiqi']
['suiyi', 'xiishen', 'huagai', 'jiesha']
```
返回的是标识而非译名，要展示用 `i18n.translate(key)`。
***
## get\_changsheng12\_start\_index / get\_jiangqian12\_start\_index [#get_changsheng12_start_index--get_jiangqian12_start_index]
**用途** 只取两组十二神的起始宫位，不排整组。
**斗数含义** 长生起点由五行局定：水二局长生在申、木三局在亥、金四局在巳、
土五局在申、火六局在寅。将星起点由年支三合组定：寅午戌年在午、申子辰年在子、
巳酉丑年在酉、亥卯未年在卯。
**签名**
```python
def get_changsheng12_start_index(five_elements_class: FiveElementsClass | str) -> int
def get_jiangqian12_start_index(branch: EarthlyBranch | str) -> int
```
**返回值** `int`，0–11。这两个函数不需要出生数据。
**示例**
```python
print(star.get_changsheng12_start_index("water2nd"), star.get_changsheng12_start_index("fire6th"))
print(star.get_jiangqian12_start_index("ziEarthly"), star.get_jiangqian12_start_index("wuEarthly"))
```
**输出**
```text
6 0
10 4
```
水二局长生在申（索引 6），火六局在寅（索引 0）。
***
## get\_horoscope\_star [#get_horoscope_star]
**用途** 取某个运限层级的流耀分布。
**斗数含义** 流耀是随运限产生的十颗星：魁钺昌曲禄羊陀马鸾喜。
它们的落宫由该层级的干支决定，名字随层级变化。流年层级额外多一颗年解。
**签名**
```python
def get_horoscope_star(
stem: HeavenlyStem | str,
branch: EarthlyBranch | str,
scope: Scope | str,
language: str = "zh-CN",
) -> list[list[Star]]
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ----- | -- | --------- | --------- |
| `stem` | `str` | 是 | — | 该层级的天干标识 |
| `branch` | `str` | 是 | — | 该层级的地支标识 |
| `scope` | `str` | 是 | — | 运限层级，决定星名 |
| `language` | `str` | 否 | `"zh-CN"` | 输出语言 |
**返回值** 十二项列表，按宫位索引排列。
**各层级的星名对照**
| 本命 | 大限 | 流年 | 流月 | 流日 | 流时 |
| -- | -- | -- | -- | -- | -- |
| 天魁 | 运魁 | 流魁 | 月魁 | 日魁 | 时魁 |
| 天钺 | 运钺 | 流钺 | 月钺 | 日钺 | 时钺 |
| 文昌 | 运昌 | 流昌 | 月昌 | 日昌 | 时昌 |
| 文曲 | 运曲 | 流曲 | 月曲 | 日曲 | 时曲 |
| 禄存 | 运禄 | 流禄 | 月禄 | 日禄 | 时禄 |
| 擎羊 | 运羊 | 流羊 | 月羊 | 日羊 | 时羊 |
| 陀罗 | 运陀 | 流陀 | 月陀 | 日陀 | 时陀 |
| 天马 | 运马 | 流马 | 月马 | 日马 | 时马 |
| 红鸾 | 运鸾 | 流鸾 | 月鸾 | 日鸾 | 时鸾 |
| 天喜 | 运喜 | 流喜 | 月喜 | 日喜 | 时喜 |
标识形如 `yunlu`（运禄）、`liulu`（流禄）、`yuelu`（月禄）、`rilu`（日禄）、`shilu`（时禄）。
**示例**
```python
decadal = star.get_horoscope_star("jiaHeavenly", "ziEarthly", "decadal")
print([[s.name for s in p] for p in decadal[:4]])
origin = star.get_horoscope_star("jiaHeavenly", "ziEarthly", "origin")
print([[s.name for s in p] for p in origin[:2]])
```
**输出**
```text
[['运禄', '运马'], ['运羊', '运鸾'], [], ['运昌']]
[['禄存', '天马'], ['擎羊', '红鸾']]
```
**边界与陷阱**
`"yearly"` 的结果里额外含年解，按流年地支定位，安放在十颗流耀之前。
其余层级没有这一颗。
***
## 低层落宫 [#低层落宫]
上面的函数都从出生数据起算，内部先推出年干支、命宫、修正后的农历月，再落宫。
这一组则直接收那些中间量，自建流程时可以复用。
| 函数 | 收 | 出 |
| ---------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
| `get_zuo_you_index(lunar_month)` | 修正后的农历月 1–12 | `ZuoYouIndex(zuo_index, you_index)` |
| `get_huo_ling_index(branch, time_index)` | 年支、时辰 | `HuoLingIndex(huo_index, ling_index)` |
| `get_huagai_xianchi_index(branch)` | 年支 | `HuagaiXianchiIndex(huagai_index, xianchi_index)` |
| `get_gu_gua_index(branch)` | 年支 | `GuGuaIndex(guchen_index, guasu_index)` |
| `get_jiesha_adj_index(branch)` | 年支 | `int`，劫煞宫位索引 |
| `get_dahao_index(branch)` | 年支 | `int`，大耗宫位索引 |
| `get_nianjie_index(branch)` | 年支 | `int`，年解宫位索引 |
| `get_tianshi_tianshang_index(gender, branch, soul_index, config=None)` | 性别、年支、命宫索引 | `TianshiTianshangIndex(tianshang_index, tianshi_index)` |
| `get_chang_qu_index_by_heavenly_stem(stem)` | 天干 | `ChangQuIndex(chang_index, qu_index)` |
**示例**
```python
from x_iztro import star
chart = Astro().by_solar("2000-8-16", 2, "female")
year_branch = chart.raw_dates.chinese_date.yearly_keys[1]
print(star.get_huo_ling_index(year_branch, 2))
print(star.get_gu_gua_index(year_branch))
print(star.get_chang_qu_index_by_heavenly_stem("jiaHeavenly"))
```
**输出**
```text
HuoLingIndex(huo_index=2, ling_index=10)
GuGuaIndex(guchen_index=3, guasu_index=11)
ChangQuIndex(chang_index=3, qu_index=7)
```
**边界与陷阱**
`get_zuo_you_index` 收的是修正闰月之后的月份，即 `fix_lunar_month_index(...) + 1`，
不是农历原始月份。闰月盘直接传原始月份会落错宫。
`get_tianshi_tianshang_index` 的结果随 `config.algorithm` 变：中州派在阴男阳女
（生年地支阴阳与性别阴阳不同）时天伤天使对调，通行派不对调。
`get_chang_qu_index_by_heavenly_stem` 按天干起昌曲，用于运限层级的流昌流曲；
本命盘的文昌文曲按时支走 `get_chang_qu_index`。
# 数据表 (/zh/docs/python/data)
星耀基础信息、天干地支信息、顺序常量与全部枚举。
排盘算法的输入表与语言无关标识的枚举清单。
```python
from x_iztro import data
```
四个入口返回的都是**具名 dataclass**（外层容器仍是 `dict` / `list`），
字段用属性访问而不是下标。字段名是 snake\_case，与底层 JSON 的 camelCase 键不同。
***
## stars\_info [#stars_info]
**用途** 取星耀基础信息表。
**签名**
```python
def stars_info() -> dict[str, StarInfo]
```
**返回值** 星耀标识 → `StarInfo`。
只有二十颗星有记录：**十四主星**加文昌、文曲、火星、铃星、擎羊、陀罗。
| 字段 | 类型 | 说明 |
| --------------- | ------------- | -------------------------- |
| `brightness` | `list[str]` | 十二宫亮度标识，索引 0 为寅宫；该宫无亮度则为空串 |
| `five_elements` | `str \| None` | 五行 |
| `yin_yang` | `str \| None` | 阴阳 |
**示例**
```python
info = data.stars_info()
print(len(info))
print(info["ziweiMaj"])
print(info["taiyangMaj"].five_elements)
```
**输出**
```text
20
StarInfo(brightness=['wang', 'wang', 'de', 'wang', 'miao', 'miao', 'wang', 'wang', 'de', 'wang', 'ping', 'miao'], five_elements='土', yin_yang='阴')
None
```
**边界与陷阱**
表中部分星耀的五行或阴阳未填：太阳与七杀两项皆为 `None`，
贪狼、天相、天梁、破军的阴阳为 `None`，六颗辅星两项皆为 `None`。
***
## flow\_star\_counterparts [#flow_star_counterparts]
**用途** 流耀 → 对应本命辅星的全量对照表（50 条）。
**签名**
```python
def flow_star_counterparts() -> dict[str, str]
```
**返回值** 键为流耀标识（`HoroscopeStar` 枚举值域），值为本命辅星标识
（`MinorStar` 枚举值域）。流耀没有独立的知识包条目，释义按对应的本命辅星查，
这张表就是官方对照。
**示例**
```python
from x_iztro import data
print(data.flow_star_counterparts()["liuchang"])
```
**输出**
```text
wenchangMin
```
***
## heavenly\_stems [#heavenly_stems]
**用途** 取天干信息表。
**斗数含义** 天干的四化表是四化系统的根：生年干决定生年四化，
宫干决定该宫飞出的四化，运限干决定该层级的四化。
**签名**
```python
def heavenly_stems() -> dict[str, HeavenlyStemInfo]
```
**返回值** 天干标识 → `HeavenlyStemInfo`：
| 字段 | 类型 | 说明 |
| --------------- | ------------- | ----------------- |
| `yin_yang` | `str` | 阴阳 |
| `five_elements` | `str` | 五行 |
| `crash` | `str \| None` | 对冲天干标识；戊、己无对冲 |
| `mutagen` | `list[str]` | 四化四星标识，顺序为禄、权、科、忌 |
**示例**
```python
stems = data.heavenly_stems()
print(stems["jiaHeavenly"])
print(stems["wuHeavenly"].crash)
```
**输出**
```text
HeavenlyStemInfo(yin_yang='阳', five_elements='木', crash='gengHeavenly', mutagen=['lianzhenMaj', 'pojunMaj', 'wuquMaj', 'taiyangMaj'])
None
```
这是**内置默认表**。自定义四化表（`ChartConfig(mutagens=...)`）不会反映在这里；
要看某张盘上实际生效的四化，用
[`utils.get_mutagens_by_heavenly_stem(stem, config)`](/zh/docs/python/util#get_mutagen--get_mutagens_by_heavenly_stem)
或宫位的 `mutagen_star_keys`。
***
## earthly\_branches [#earthly_branches]
**用途** 取地支信息表。
**签名**
```python
def earthly_branches() -> dict[str, EarthlyBranchInfo]
```
**返回值** 地支标识 → `EarthlyBranchInfo`：
| 字段 | 类型 | 说明 |
| --------------- | ----- | ---------------- |
| `yin_yang` | `str` | 阴阳，决定大限与长生十二神的顺逆 |
| `five_elements` | `str` | 五行 |
| `crash` | `str` | 对冲地支标识 |
| `soul` | `str` | 命主星标识（按命宫地支查） |
| `body` | `str` | 身主星标识（按生年地支查） |
| `inside` | `str` | 对应脏腑 |
| `outside` | `str` | 对应身体部位 |
| `health_tip` | `str` | 健康提示 |
`inside` / `outside` / `health_tip` 三项只有中文一种写法，不参与国际化。
**示例**
```python
zi = data.earthly_branches()["ziEarthly"]
print(zi)
print(zi.soul, zi.body, zi.crash)
```
**输出**
```text
EarthlyBranchInfo(yin_yang='阳', five_elements='水', crash='wuEarthly', soul='tanlangMaj', body='huoxingMin', inside='胆', outside='下体', health_tip='生殖系统、膀胱、尿道之疾病，听觉障碍')
tanlangMaj huoxingMin wuEarthly
```
***
## constants [#constants]
**用途** 取顺序常量与推算规则表。
**签名**
```python
def constants() -> Constants
```
**返回值** `Constants`：
| 字段 | 类型 | 说明 |
| --------------------- | ---------------- | -------------------------- |
| `languages` | `list[str]` | 支持的语言代码 |
| `heavenly_stems` | `list[str]` | 天干顺序 |
| `earthly_branches` | `list[str]` | 地支顺序 |
| `zodiac` | `list[str]` | 生肖标识，按地支顺序 |
| `signs` | `list[str]` | 星座标识，按黄道顺序 |
| `palaces` | `list[str]` | 十二宫名，从命宫起**逆时针**排 |
| `gender` | `dict[str, str]` | 男女各自的阴阳 |
| `chinese_time` | `list[str]` | 时辰标识，早子时起、晚子时止 |
| `time_range` | `list[str]` | 时辰对应的钟点区间 |
| `tiger_rule` | `dict[str, str]` | 五虎遁：年干推正月天干 |
| `rat_rule` | `dict[str, str]` | 五鼠遁：日干推子时天干 |
| `mutagen` | `list[str]` | 四化顺序 |
| `five_elements_class` | `dict[str, int]` | 五行局标识 → 局数（水二局 2 …… 火六局 6） |
**示例**
```python
c = data.constants()
print(c.languages)
print(c.zodiac[:3], c.chinese_time[12], c.time_range[2])
print(c.gender)
print("甲年正月干:", c.tiger_rule["jiaHeavenly"])
print(c.palaces)
print(c.five_elements_class)
```
**输出**
```text
['en-US', 'ja-JP', 'ko-KR', 'zh-CN', 'zh-TW', 'vi-VN']
['rat', 'ox', 'tiger'] lateRatHour 03:00~05:00
{'female': '阴', 'male': '阳'}
甲年正月干: bingHeavenly
['soulPalace', 'parentsPalace', 'spiritPalace', 'propertyPalace', 'careerPalace', 'friendsPalace', 'surfacePalace', 'healthPalace', 'wealthPalace', 'childrenPalace', 'spousePalace', 'siblingsPalace']
{'earth5th': 5, 'fire6th': 6, 'metal4th': 4, 'water2nd': 2, 'wood3rd': 3}
```
**边界与陷阱**
`palaces` 给的是宫名的**排列顺序**：命、父母、福德、田宅、官禄、仆役、迁移、
疾厄、财帛、子女、夫妻、兄弟。这是十二宫从命宫起逆时针铺开的次序，
不是某张盘上第 `i` 格叫什么。要那个用
[`utils.get_palace_names(soul_index)`](/zh/docs/python/util#get_palace_names)。
`languages` 的顺序是 iztro 词表的合并次序（en-US 起），不是 `Language` 枚举的声明次序。
[`i18n.key_of`](/zh/docs/python/i18n#key_of) 的逐语言扫描顺序与它一致。
`five_elements_class`、`gender`、`tiger_rule`、`rat_rule` 四项是 `dict` 而非 `list`，
键的次序是字典序（原生扩展转过来时排过序），不代表五行局或天干的排列顺序。
局数也可以直接从枚举取：`FiveElementsClass.WOOD_3.number`。
***
## 枚举清单 [#枚举清单]
`x_iztro.enums` 里的每个枚举都是 `StrEnum`，取值就是语言无关标识。
从包根直接导入：`from x_iztro import MajorStar, PalaceName`。
| 枚举 | 成员数 | 成员 |
| -------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Gender` | 2 | `MALE` `FEMALE` |
| `Language` | 6 | `ZH_CN` `ZH_TW` `EN_US` `JA_JP` `KO_KR` `VI_VN` |
| `HeavenlyStem` | 10 | `JIA` `YI` `BING` `DING` `WU` `JI` `GENG` `XIN` `REN` `GUI` |
| `EarthlyBranch` | 12 | `ZI` `CHOU` `YIN` `MAO` `CHEN` `SI` `WU` `WEI` `SHEN` `YOU` `XU` `HAI` |
| `PalaceName` | **14** | 十二宫 `SOUL` `SIBLINGS` `SPOUSE` `CHILDREN` `WEALTH` `HEALTH` `SURFACE` `FRIENDS` `CAREER` `PROPERTY` `SPIRIT` `PARENTS`，外加两个定位标记 `BODY`（身宫）`ORIGINAL`（来因宫） |
| `FiveElementsClass` | 5 | `WATER_2` `WOOD_3` `METAL_4` `EARTH_5` `FIRE_6` |
| `Mutagen` | 4 | `LU` `QUAN` `KE` `JI` |
| `Brightness` | 7 | `MIAO` `WANG` `DE` `LI` `PING` `BU` `XIAN` |
| `StarType` | 8 | `MAJOR` `SOFT` `TOUGH` `ADJECTIVE` `FLOWER` `HELPER` `LUCUN` `TIANMA` |
| `Scope` | 6 | `ORIGIN` `DECADAL` `YEARLY` `MONTHLY` `DAILY` `HOURLY` |
| `MajorStar` | 14 | 十四主星，`ZIWEI` `TIANJI` `TAIYANG` `WUQU` `TIANTONG` `LIANZHEN` `TIANFU` `TAIYIN` `TANLANG` `JUMEN` `TIANXIANG` `TIANLIANG` `QISHA` `POJUN` |
| `MinorStar` | 14 | 十四辅星，`ZUOFU` `YOUBI` `WENCHANG` `WENQU` `LUCUN` `TIANMA` `QINGYANG` `TUOLUO` `HUOXING` `LINGXING` `TIANKUI` `TIANYUE` `DIKONG` `DIJIE` |
| `AdjectiveStar` | 43 | 杂耀，含中州派的 `XUNZHONG`（旬中）；成员对照见[星耀](/zh/docs/guide/concepts/stars) |
| `HoroscopeStar` | 50 | 五个运限层级各十颗流耀，`YUNLU` `LIULU` `YUELU` `RILU` `SHILU` 等 |
| `Changsheng12` | 12 | `CHANGSHENG` `MUYU` `GUANDAI` `LINGUAN` `DIWANG` `SHUAI` `BING` `SI` `MU` `JUE` `TAI` `YANG` |
| `Boshi12` | 12 | `BOSHI` `LISHI` `QINGLONG` `XIAOHAO` `JIANGJUN` `ZHOUSHU` `FEILIAN` `XISHEN` `BINGFU` `DAHAO` `FUBING` `GUANFU` |
| `Suiqian12` | 13 | `SUIJIAN` `HUIQI` `SANGMEN` `GUANSUO` `GWANFU` `XIAOHAO` `DAHAO` `SUIPO` `LONGDE` `BAIHU` `TIANDE` `DIAOKE` `BINGFU`（`SUIPO` 为中州派的岁破） |
| `Jiangqian12` | 12 | `JIANGXING` `PANAN` `SUIYI` `XISHEN` `HUAGAI` `JIESHA` `ZHAISHA` `TIANSHA` `ZHIBEI` `XIANCHI` `YUESHA` `WANGSHEN` |
| `Algorithm` | 2 | `DEFAULT` `ZHONGZHOU` |
| `AstroType` | 3 | `HEAVEN` `EARTH` `HUMAN` |
| `YearDivide` / `HoroscopeDivide` | 各 2 | `NORMAL` `EXACT` |
| `AgeDivide` | 2 | `NORMAL` `BIRTHDAY` |
| `DayDivide` | 2 | `FORWARD` `CURRENT` |
成员名与它的取值不总是拼音对应——`Boshi12.FEILIAN` 的值是 `faylian`，
`Jiangqian12.XISHEN` 的值是 `xiishen`，`Suiqian12.GWANFU` 的值是 `gwanfu`。
这些拼写沿用 iztro 的词表，**判断一律用枚举成员**，不要手写字符串。
全部标识与译名的对照见[标识总表](/zh/docs/guide/guides/keys)。
### FiveElementsClass.number [#fiveelementsclassnumber]
五行局枚举多一个属性 `number`，给出局数——大限起运岁数与起紫微都用它：
```python
from x_iztro import FiveElementsClass
for c in FiveElementsClass:
print(c, c.number)
```
**输出**
```text
water2nd 2
wood3rd 3
metal4th 4
earth5th 5
fire6th 6
```
**示例**
```python
from x_iztro import MajorStar, PalaceName, Mutagen
soul = chart.palace(PalaceName.SOUL)
print(soul.major_stars[0].key == MajorStar.ZIWEI)
print(MajorStar.ZIWEI, Mutagen.LU, PalaceName.WEALTH)
```
**输出**
```text
True
ziweiMaj sihuaLu wealthPalace
```
`chart.palace(PalaceName.SOUL)` 与 `chart.palace("soulPalace")` 完全等价。
枚举的价值在于 IDE 补全与拼写检查，而非类型约束。
名字来自外部输入时，用构造函数当校验器：`PalaceName("soulPalce")` 抛
`ValueError: 'soulPalce' is not a valid PalaceName`，
比让查询方法静默返回 `None` 早一步暴露问题。
# 翻译 (/zh/docs/python/i18n)
标识与译名的双向查找。
星盘上每个字段都同时给出译名与 `*_key` 标识，通常不必手工翻译。
这两个函数用于手上只有标识（或只有某种语言的译名）、需要换算的场合。
```python
from x_iztro import i18n
```
支持六种语言：`zh-CN`、`zh-TW`、`en-US`、`ja-JP`、`ko-KR`、`vi-VN`。
***
## translate [#translate]
**用途** 把任意标识译成指定语言。
**签名**
```python
def translate(key: str, language: LanguageType = "zh-CN") -> str | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ----- | -- | --------- | ------ |
| `key` | `str` | 是 | — | 语言无关标识 |
| `language` | `str` | 否 | `"zh-CN"` | 目标语言 |
覆盖十二类共 260 个标识：
| 类目 | 数量 | 例 |
| ----------- | --- | --------------------------------------------------------- |
| 星耀 | 162 | `ziweiMaj`、`changsheng`、`yunlu` |
| 宫位（含身宫、来因宫） | 14 | `soulPalace`、`wealthPalace`、`bodyPalace`、`originalPalace` |
| 天干 | 10 | `jiaHeavenly` |
| 地支 | 12 | `ziEarthly` |
| 亮度 | 7 | `miao`、`wang` |
| 四化 | 4 | `sihuaLu` |
| 五行局 | 5 | `water2nd` |
| 性别 | 2 | `male`、`female` |
| 生肖 | 12 | `rat`、`ox` |
| 时辰 | 13 | `earlyRatHour` |
| 星座 | 12 | `aries` |
| 运限层级 | 7 | `decadal`、`turn` |
**返回值** 译名；未知标识返回 `None`。
**示例**
```python
print(i18n.translate("ziweiMaj", "en-US"))
print(i18n.translate("soulPalace", "ja-JP"))
print(i18n.translate("ziweiMaj", "vi-VN"))
print(i18n.translate("bodyPalace"))
print(i18n.translate("nosuch"))
```
**输出**
```text
emperor
命宮
Tử Vi
身宫
None
```
***
## key\_of [#key_of]
**用途** 由任意语言的译名反查标识。
**签名**
```python
def key_of(text: str, key_filter: str | None = None) -> str | None
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | ------------- | -- | ------ | ------------------- |
| `text` | `str` | 是 | — | 任一支持语言下的译名 |
| `key_filter` | `str \| None` | 否 | `None` | 限定标识名须含的子串，用于消歧同形译名 |
**返回值** 标识；查不到返回 `None`。
**示例**
```python
print(i18n.key_of("紫微"))
print(i18n.key_of("emperor"))
print(i18n.key_of("자미"))
print(i18n.key_of("查无此名"))
```
**输出**
```text
ziweiMaj
ziweiMaj
ziweiMaj
None
```
三种语言的译名都落到同一个标识。
**边界与陷阱**
少数译名在多个类目下同形：en-US 的 `horse` 既是生肖马也是天马，
`dragon` 既是生肖龙也是青龙，ko-KR 的 `사` 既是地支巳也是长生12神的死。
不限定时逐语言、每种语言内逐标识取先命中者，顺序与 iztro 的 `kot` 完全一致
（有金标测试逐例守着）。要指定类目就传 `key_filter`——标识名含该子串才纳入比对：
```python
print(i18n.key_of("horse")) # horse（生肖马）
print(i18n.key_of("horse", "Min")) # tianmaMin（天马）
print(i18n.key_of("유시")) # hourly（流时）
print(i18n.key_of("유시", "Hour")) # roosterHour（酉时）
print(i18n.key_of("horse", "Palace")) # None
```
常用子串：`Maj` 十四主星、`Min` 辅星、`Heavenly` / `Earthly` 干支、
`Palace` 宫位、`Hour` 时辰。限定后无匹配返回 `None`，不退回未限定的结果。
`key_of` 会遍历 260 个标识 × 6 种语言。单次调用开销可忽略，
但不要放在每宫每星的内层循环里——那种场合直接用数据自带的 `*_key` 字段。
***
## all\_keys [#all_keys]
**用途** 取全部 260 个可翻译标识。
**签名**
```python
def all_keys() -> list[str]
```
**返回值** 标识列表，顺序即 `key_of` 的反查次序：
运限层级、生肖、时辰、星座、五行局、天干、地支、亮度、四化、星耀、宫位、性别，
与 iztro 各语言翻译文件的合并次序一致。
**示例**
```python
keys = i18n.all_keys()
print(len(keys))
print(keys[:4])
print(i18n.translate(keys[0]))
```
**输出**
```text
260
['decadal', 'childhood', 'yearly', 'monthly']
大限
```
要遍历某一类目自己的标识时，用 `enums` 里的枚举或 `data.constants()` 更省事。
***
## 没有全局语言开关 [#没有全局语言开关]
x-iztro 不设「当前语言」这样的全局状态：排盘时语言随参数传入，
翻译函数每次调用都显式指定目标语言。
全局语言开关会让同一段代码在不同调用顺序下产出不同结果，
多线程环境尤其危险。显式传参使每次调用的结果只由入参决定。
要在一个进程里同时输出多种语言，直接排多张盘即可，互不干扰：
```python
zh = Astro().by_solar("2000-8-16", 2, "female")
en = Astro().by_solar("2000-8-16", 2, "female", language="en-US")
print(zh.palace("soulPalace").major_stars[0].name,
en.palace("soulPalace").major_stars[0].name)
```
**输出**
```text
紫微 emperor
```
两张盘的 `*_key` 字段完全相同，因此任何基于标识的判断在两张盘上结果一致。
# 知识包 (/zh/docs/python/knowledge)
KnowledgePack 与各条目 dataclass、内嵌默认包、dict/JSON 互转、覆盖包合并。
知识包是「语言无关标识 → 解读文本与门派属性」的 JSON。内核只判事实，
解读文本与星耀的门派属性放在这里。概念、格式与写覆盖包的方法见
[知识包指南](/zh/docs/guide/guides/knowledge-pack)，完整字段表见仓库的
[`knowledge/SCHEMA.md`](https://github.com/x-haose/x-iztro/blob/main/knowledge/SCHEMA.md)。
```python
from x_iztro import KnowledgePack
from x_iztro.enums import MajorStar
pack = KnowledgePack.builtin()
intro = pack.star_intro(MajorStar.ZIWEI)
```
`KnowledgePack` 从 `x_iztro` 顶层导出，条目 dataclass 在 `x_iztro.knowledge` 下。
所有取键的方法都收字符串，枚举（`MajorStar`、`PatternKey`、`PalaceName`、`Mutagen`…）
是 `StrEnum`，可以直接传。
## 类型 [#类型]
### KnowledgePack [#knowledgepack]
持有原始包对象（dict），查询方法返回类型化条目。
**元信息（只读属性）**
| 属性 | 类型 | 说明 |
| ---------- | ------------- | --------------------------- |
| `schema` | `int` | 格式版本，当前为 1 |
| `id` | `str` | 包标识，默认包为 `"iztro-docs"` |
| `version` | `str` | 包版本，默认包为「抓取日期+来源 commit 短号」 |
| `language` | `str` | 文本语言的语言码 |
| `extends` | `str \| None` | 覆盖包所覆盖的包标识；独立包为 `None` |
| `source` | `Source` | 来源与许可 |
**方法**
| 方法 | 说明 |
| ------------------------------------------------------------------------------- | --------------------------------- |
| `KnowledgePack.builtin(language="zh-CN")` | 内嵌默认包 |
| `KnowledgePack.from_dict(d)` | 由包对象构造（保留引用，不复制） |
| `KnowledgePack.from_json(text)` | 由 JSON 文本构造 |
| `to_dict()` | 包对象的深拷贝 |
| `to_json(**kwargs)` | JSON 文本，`kwargs` 透传给 `json.dumps` |
| `merged(*overlays)` | 叠加覆盖包，返回新包 |
| `star(key)` / `pattern(key)` / `palace(key)` / `mutagen(key)` / `concept(slug)` | 取单条条目，没有返回 `None` |
| `stars()` / `patterns()` | 全部星耀 / 格局条目 |
| `star_intro(key)` / `pattern_intro(key)` | 直接取解读正文 |
| `for_astrolabe(chart, config=None)` / `for_horoscope(horoscope, config=None)` | 按盘取材，返回只含该盘相关条目的子包 |
`KnowledgePack` 实例本身也是 to\_text 家族 `knowledge=` 参数的取值（见各对象的 `to_text`）。
### 条目 dataclass [#条目-dataclass]
`StarEntry`、`PatternEntry`、`TextEntry`、`ConceptEntry`、`StarAttributes`、`Source`
都是 `frozen=True, slots=True` 的 dataclass，字段缺省即 `None`。
`StarEntry`
| 字段 | 类型 | 说明 |
| -------------- | ---------------- | -------------------------------------------------------------------------------- |
| `key` | `str` | 星耀标识 |
| `name` | `str \| None` | 该语言的显示名 |
| `category` | `str \| None` | 类别：`"major"` / `"minor"` / `"adjective"` / `"dec"` / `"flow"`（流耀，指向对应本命辅星的对照性条目） |
| `group` | `str \| None` | 分组：杂耀的分类、神煞的组别 |
| `attributes` | `StarAttributes` | 门派属性 |
| `intro` | `str \| None` | 解读正文（Markdown） |
| `combinations` | `dict[str, str]` | 与另一颗主星同宫的组合解读，键为对方星耀标识 |
`StarAttributes`：`yin_yang`（`yin` / `yang`）、
`five_elements`（`wood` / `fire` / `earth` / `metal` / `water`）、`stem`（`jia`…`gui`）、
`five_elements_note`、`dipper`、`chemistry`、`career`、`duty`、`aliases`（`list[str] | None`）、
`element_color`、`energy_color`。
`PatternEntry`：`key`、`name`、`quotes`（`list[str] | None`）、`conditions`、`intro`。
`TextEntry`（宫位、四化）：`key`、`name`、`intro`。
`ConceptEntry`（术语）：`slug`、`title`、`intro`。
`Source`：`name`、`url`、`commit`、`license`、`author`、`retrieved_at`、`adapted`（改编说明）。
`StarAttributes` 的 `five_elements` 与 `yin_yang` 是知识包来源的说法，
与核心星耀数据的取值可能不同——核心那份与 iztro 逐值一致。
原因见[指南](/zh/docs/guide/guides/knowledge-pack#为什么星耀的阴阳五行放在这里)。
***
## builtin [#builtin]
**用途** 取内嵌的默认知识包。
**签名**
```python
@classmethod
def builtin(cls, language: LanguageType = "zh-CN") -> KnowledgePack
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | -------------- | -- | --------- | ---- |
| `language` | `LanguageType` | 否 | `"zh-CN"` | 文本语言 |
**返回值** `KnowledgePack`。
**异常** `IztroError`（`code` 为 `invalid_argument`）——该语言没有内嵌默认包。
目前只有 `zh-CN` 有。
**示例**
```python
from x_iztro import IztroError, KnowledgePack
pack = KnowledgePack.builtin()
print(pack)
print(pack.schema, pack.id, pack.version, pack.language, pack.extends)
print(pack.source.license, pack.source.author)
print(len(pack.stars()), len(pack.patterns()))
try:
KnowledgePack.builtin("en-US")
except IztroError as e:
print(e.code, e)
```
**输出**
```text
KnowledgePack(id='iztro-docs', version='2026-08-19+ec2d58b', language='zh-CN')
1 iztro-docs 2026-08-19+ec2d58b zh-CN None
MIT Sylar Long
162 64
invalid_argument no builtin knowledge pack for language 'en-US'
```
***
## from\_dict / from\_json / to\_dict / to\_json [#from_dict--from_json--to_dict--to_json]
**用途** 自带的包与 x-iztro 之间的互转。
**签名**
```python
@classmethod
def from_dict(cls, d: dict[str, Any]) -> KnowledgePack
@classmethod
def from_json(cls, text: str) -> KnowledgePack
def to_dict(self) -> dict[str, Any]
def to_json(self, **kwargs: Any) -> str
```
**说明**
* `from_dict` 直接持有传入的 dict，不复制：之后改动那个 dict 会影响这份包。
要隔离，先 `copy.deepcopy` 或走 `from_json`。
* `to_dict` 返回深拷贝，怎么改都不影响原包。
* `to_json` 的 `ensure_ascii` 默认为 `False`（中文原样输出），
其余 `kwargs` 原样传给 `json.dumps`，例如 `pack.to_json(indent=2)`。
* 两个构造方法都**校验格式版本**，与 Rust 内核解析同语义：非对象、`schema` 缺失或为 0、
`schema` 高于本库支持的版本都抛 `IztroError`（`invalid_argument`）。
结构不做深校验：字段不认识就是取不到值。
**示例** `my-school.json` 是一份覆盖包，完整样例见
[知识包指南](/zh/docs/guide/guides/knowledge-pack#写一份覆盖包)：
```python
from x_iztro import KnowledgePack
overlay = KnowledgePack.from_json(open("my-school.json", encoding="utf-8").read())
print(overlay.id, overlay.extends)
raw = overlay.to_dict()
raw["stars"]["ziweiMaj"]["intro"] = "再改一次"
print(overlay.star_intro("ziweiMaj")) # to_dict 是深拷贝，原包不受影响
```
***
## merged [#merged]
**用途** 把若干覆盖包依次叠加到本包上，返回新包。
**签名**
```python
def merged(self, *overlays: KnowledgePack | dict[str, Any]) -> KnowledgePack
```
**参数**
| 参数 | 类型 | 说明 |
| ----------- | ----------------------- | ---------------------- |
| `*overlays` | `KnowledgePack \| dict` | 覆盖包，按传入顺序依次叠加，后面的覆盖前面的 |
**返回值** 新的 `KnowledgePack`，本包与覆盖包都不变。
**异常** `IztroError`（`invalid_argument`）——某个包不符合格式，
或 `schema` 高于本库支持的版本。
合并规则见[指南](/zh/docs/guide/guides/knowledge-pack#合并规则)：逐段按键合并，
覆盖包的非空字段覆盖同键条目的对应字段，`attributes` 与 `combinations` 逐字段合并，
数组字段整体替换。合并本身在 Rust 内核里算，三语言结果一致。
**示例**
```python
from x_iztro import IztroError, KnowledgePack, PatternKey
from x_iztro.enums import MajorStar
pack = KnowledgePack.builtin()
overlay = KnowledgePack.from_dict({
"schema": 1, "id": "my-school", "version": "1", "language": "zh-CN", "extends": "iztro-docs",
"stars": {"ziweiMaj": {"intro": "我的紫微", "attributes": {"aliases": ["帝座"]}}},
"patterns": {"zi_fu_tong_gong": {"intro": "我的紫府同宫"}},
})
merged = pack.merged(overlay)
ziwei = merged.star(MajorStar.ZIWEI)
print(merged.id, ziwei.name, ziwei.attributes.aliases, ziwei.attributes.chemistry, ziwei.intro)
print(merged.pattern_intro(PatternKey.ZI_FU_TONG_GONG),
merged.pattern(PatternKey.ZI_FU_TONG_GONG).quotes)
print(pack.star_intro(MajorStar.ZIWEI)[:5])
try:
pack.merged({"schema": 99})
except IztroError as e:
print(e.code, e)
```
**输出**
```text
my-school 紫微 ['帝座'] 尊贵 我的紫微
我的紫府同宫 ['紫府同宫终身福厚。']
紫微星号称
invalid_argument knowledge pack schema 99 is newer than supported 1
```
***
## star / pattern / palace / mutagen / concept [#star--pattern--palace--mutagen--concept]
**用途** 按语言无关标识取条目。
**签名**
```python
def star(self, key: str) -> StarEntry | None
def pattern(self, key: str) -> PatternEntry | None
def palace(self, key: str) -> TextEntry | None
def mutagen(self, key: str) -> TextEntry | None
def concept(self, slug: str) -> ConceptEntry | None
```
**返回值** 包里没有该条目时为 `None`。
**示例**
```python
from x_iztro import KnowledgePack, Mutagen, PalaceName
from x_iztro.enums import MajorStar
pack = KnowledgePack.builtin()
ziwei = pack.star(MajorStar.ZIWEI)
print(ziwei.key, ziwei.name, ziwei.category, ziwei.attributes.dipper)
print(ziwei.attributes.aliases)
print(sorted(ziwei.combinations)[:5])
print(pack.palace(PalaceName.SOUL).name, pack.mutagen(Mutagen.LU).name)
print(pack.concept("tong-gong").title)
print(pack.star("nope"))
```
**输出**
```text
ziweiMaj 紫微 major 中天星系
['帝王星', '老板星', '俸禄星']
['pojunMaj', 'qishaMaj', 'tanlangMaj', 'tianfuMaj', 'tianxiangMaj']
命宫 化禄
遇、加、逢、同宫、同度
None
```
***
## stars / patterns [#stars--patterns]
**用途** 列出包里全部星耀 / 格局条目。
**签名**
```python
def stars(self) -> list[StarEntry]
def patterns(self) -> list[PatternEntry]
```
**返回值** 按键的字典序排列，每条带自己的 `key`。默认包是 162 与 64。
遍历整包（做检索、导出、喂给大模型）时用它，比自己翻 `to_dict()` 省事。
***
## star\_intro / pattern\_intro [#star_intro--pattern_intro]
**用途** 直接取解读正文。
**签名**
```python
def star_intro(self, key: str) -> str | None
def pattern_intro(self, key: str) -> str | None
```
**返回值** 条目不存在、或条目存在但没写正文，都是 `None`。
**示例** 把本命格局连同引文列出来：
```python
from x_iztro import Astro, KnowledgePack
pack = KnowledgePack.builtin()
chart = Astro().by_solar("2000-8-16", 2, "female")
for hit in chart.patterns():
print(hit.name, "|", pack.pattern(hit.key).quotes[0])
print(pack.pattern_intro(hit.key)[:10])
```
**输出**
```text
府相朝垣 | 府相朝垣命必荣
“食禄千锺”的断语使
```
***
## for\_astrolabe / for\_horoscope [#for_astrolabe--for_horoscope]
**用途** 按盘取材：裁出只含这张盘相关条目的子包。
**签名**
```python
def for_astrolabe(self, chart: Astrolabe, config: PatternConfig | None = None) -> KnowledgePack
def for_horoscope(self, horoscope: Horoscope, config: PatternConfig | None = None) -> KnowledgePack
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ----------------------- | -- | ------ | ---------------------------------------------------------------------------------- |
| `chart` | `Astrolabe` | 是 | — | 取材依据的星盘；重排盘按重排后的布局取材 |
| `horoscope` | `Horoscope` | 是 | — | 由 `chart.horoscope(...)` 得到的运限，本命部分随之取材 |
| `config` | `PatternConfig \| None` | 否 | `None` | 格局判定口径，与 [`chart.patterns(config)`](/zh/docs/python/patterns#patterns) 同形态；不传即默认口径 |
**返回值** 标准 `KnowledgePack`，元信息沿用本包：`stars` 是盘上出现的星
（主辅杂与四组十二神，14 主星的 `combinations` 只留对方主星确在同宫的），
`patterns` 是按 `config` 口径命中的格局，`mutagens` 四条全留，`palaces` 与 `concepts` 为空。
`for_horoscope` 在此之上再加各层流耀与大限到流时各层视角命中的格局。
子包要和 `patterns(config)` / `patterns_to_text(config)` 配同一口径：口径不同，命中集合不同，
释义就会缺项或多项。
取材规则见[按盘取材](/zh/docs/guide/guides/knowledge-pack#按盘取材)。
**示例**
```python
pack = KnowledgePack.builtin()
chart = Astro().by_solar("2000-8-16", 2, "female")
sub = pack.for_astrolabe(chart)
print(len(sub.stars()), len(sub.patterns()), sub.palace("soulPalace"))
print(list(sub.star(MajorStar.WUQU).combinations))
sub = pack.for_horoscope(chart.horoscope("2025-1-1", 0))
print(len(sub.stars()), len(sub.patterns()))
```
**输出**
```text
108 1 None
['tianxiangMaj']
158 16
```
武曲在这张盘上与天相同宫，所以子包里武曲的 `combinations` 只剩天相一条。
脱离星盘单独构造的运限没有排盘上下文，`for_horoscope` 抛 `ValueError`。
# 反推 (/zh/docs/python/reverse)
solar_dates_by_bazi 与 reverse_chart：由八字四柱或星盘特征反查候选生辰的函数与 dataclass。
由八字四柱或星盘特征反查候选生辰。计算全部在 Rust 内核完成
（剪枝枚举 + 正排终验，与正向排盘零分歧），Python 侧是类型化封装。
概念、四柱口径与 Config 的关系、多解与截断语义见
[反推指南](/zh/docs/guide/guides/reverse)。
```python
from x_iztro import solar_dates_by_bazi
from x_iztro.enums import EarthlyBranch as B, HeavenlyStem as S
cands = solar_dates_by_bazi(
(S.GENG, B.CHEN), (S.JIA, B.SHEN), (S.BING, B.WU), (S.GENG, B.YIN),
)
```
全部定义在 `x_iztro.reverse`，并在包根重导出。
干支、五行局、星耀都收语言无关标识：`x_iztro.enums` 的枚举成员或等值字符串皆可。
## 类型 [#类型]
### 类型别名 Pillar [#类型别名-pillar]
```python
Pillar = tuple[HeavenlyStem | str, EarthlyBranch | str]
```
一柱干支：(天干标识, 地支标识)，如 `(HeavenlyStem.GENG, EarthlyBranch.CHEN)`。
### BirthCandidate [#birthcandidate]
frozen dataclass。一个候选生辰，可直接交给 [`Astro.by_solar`](/zh/docs/python/astro) 排盘。
| 字段 | 类型 | 说明 |
| ------------ | ----- | ------------------------- |
| `solar_date` | `str` | 公历日期，`YYYY-M-D` |
| `time_index` | `int` | 时辰索引 0–12（0 为早子时，12 为晚子时） |
### StarPosition [#starposition]
frozen dataclass。一颗星与其落宫地支：星盘特征反推的原子条件。
| 字段 | 类型 | 说明 |
| -------- | ---------------------- | --------------------- |
| `star` | `str` | 星耀标识（须为本命盘星耀，运限流曜不接受） |
| `branch` | `EarthlyBranch \| str` | 落宫地支标识 |
### ReverseCriteria [#reversecriteria]
frozen dataclass。星盘特征反推的条件集，全部字段可选，但至少要给一个。
| 字段 | 类型 | 默认值 | 说明 |
| --------------------- | ---------------------------------- | -------------- | --------------------------- |
| `soul_branch` | `EarthlyBranch \| str \| None` | `None` | 命宫地支 |
| `body_branch` | `EarthlyBranch \| str \| None` | `None` | 身宫地支 |
| `five_elements_class` | `FiveElementsClass \| str \| None` | `None` | 五行局 |
| `stars` | `list[StarPosition]` | `[]` | 星耀落宫条件，全部须同时满足 |
| `mutagens` | 四元组，各项 `str \| None` | 全 `None` | 生年四化 \[禄, 权, 科, 忌] 各自是哪颗星 |
| `year_range` | `tuple[int, int]` | `(1900, 2100)` | 公历年闭区间（含两端），须落在 1583–9999 内 |
| `fix_leap` | `bool` | `True` | 是否修正闰月，与排盘入参同义 |
| `limit` | `int` | `0` | 候选数上限；`0` 取内核默认（512） |
### ReverseResult [#reverseresult]
frozen dataclass。
| 字段 | 类型 | 说明 |
| ------------ | ---------------------- | --------------------------- |
| `candidates` | `list[BirthCandidate]` | 满足全部条件的候选生辰 |
| `truncated` | `bool` | 是否因达到候选数上限而提前截断；截断时更晚的解未被搜索 |
***
## solar\_dates\_by\_bazi [#solar_dates_by_bazi]
由八字四柱反查公历生辰。
```python
def solar_dates_by_bazi(
yearly: Pillar,
monthly: Pillar,
daily: Pillar,
hourly: Pillar,
*,
year_range: tuple[int, int] = (1900, 2100),
config: ChartConfig | None = None,
) -> list[BirthCandidate]
```
四柱按 `config` 的分界口径解释（`year_divide` 年柱、`horoscope_divide` 月柱、
`day_divide` 晚子归属），与排盘输出的 `raw_dates.chinese_date` 同一套语义，
因此任何盘的四柱反查结果必包含该盘的生辰。一组四柱在范围内通常每约 60 年
出现一次；时柱为子时因早晚子之分可能给出相邻两天的两个候选。
**示例**
```python
from x_iztro import Astro, solar_dates_by_bazi
a = Astro().by_solar("2000-8-16", 2, "female")
p = a.raw_dates.chinese_date
for c in solar_dates_by_bazi(p.yearly_keys, p.monthly_keys, p.daily_keys, p.hourly_keys):
print(c.solar_date, c.time_index)
```
**输出**
```text
1940-8-31 2
2000-8-16 2
2060-8-1 2
```
注意传的是标识（`yearly_keys` 等）而不是译名（`yearly` 等）——
译名是显示文本，直接传会报 `unknown heavenly stem key '庚'`。
**异常** 干支阴阳不配（如甲丑）、年份范围颠倒或超出 1583–9999 时抛
`IztroError`（`code` 为 `invalid_argument`），见[错误处理](/zh/docs/python/errors)。
***
## reverse\_chart [#reverse_chart]
由星盘特征反查候选生辰。
```python
def reverse_chart(
criteria: ReverseCriteria,
config: ChartConfig | None = None,
) -> ReverseResult
```
判定贯穿 `config`：四化表、算法派别、各分界口径都按它算，
候选用同一 `config` 排盘必满足全部条件。星盘布局与性别无关
（性别只影响大限行进方向），因此条件不含性别。
**示例**
```python
from x_iztro import ReverseCriteria, StarPosition, reverse_chart
from x_iztro.enums import EarthlyBranch, FiveElementsClass, MajorStar
r = reverse_chart(ReverseCriteria(
soul_branch=EarthlyBranch.WU,
five_elements_class=FiveElementsClass.WOOD_3,
stars=[StarPosition(star=MajorStar.ZIWEI, branch=EarthlyBranch.WU)],
mutagens=(MajorStar.TAIYANG, None, None, None),
year_range=(1998, 2002),
))
print(len(r.candidates), r.truncated)
```
**输出**
```text
39 False
```
**异常** 条件为空、`stars` 含运限流曜、年份范围非法时抛
`IztroError`（`code` 为 `invalid_argument`）。
达到 `limit` 即停止搜索，更晚的解不会出现在结果里。
`truncated` 为 `True` 时应收窄 `year_range` 或补条件后重查。
# 扩展星盘 (/zh/docs/python/extend)
用插件给 Astrolabe 类挂自定义分析方法。
斗数的分析规则千人千面，库不可能穷举。x-iztro 让你把自己的规则
以方法的形式挂到星盘类上——调用语法与内置方法一致，所有星盘实例都能用。
## 配方 [#配方]
一个插件就是一个函数，接受 `Astrolabe` 类并往上挂方法。
写一个接受
`type[Astrolabe]`
的函数
在函数体里定义方法，赋值到类上
调
`load_plugin`
加载
```python
from x_iztro import Astro, Astrolabe, PalaceName
from x_iztro.plugin import load_plugin
def my_analysis(cls: type[Astrolabe]) -> None:
"""给星盘补两个自定义分析方法。"""
def major_star(self) -> str:
"""命宫主星名（空宫借对宫），多颗以逗号分隔"""
soul = self.palace(PalaceName.SOUL)
source = soul.opposite_palace() if soul.is_empty() else soul
return ",".join(s.name for s in source.major_stars)
def five_elements_value(self) -> int:
"""五行局的局数"""
return int(self.five_elements_class_key[-3])
cls.major_star = major_star
cls.five_elements_value = five_elements_value
load_plugin(my_analysis)
```
**用法**
```python
chart = Astro().by_solar("2000-8-16", 2, "female")
print(chart.major_star())
# 扩展方法随排盘语言输出
en = Astro().by_solar("2000-8-16", 2, "female", language="en-US")
print(en.major_star())
```
**输出**
```text
紫微
emperor
```
***
## load\_plugin / load\_plugins [#load_plugin--load_plugins]
**签名**
```python
def load_plugin(plugin: Plugin) -> None
def load_plugins(plugins: Iterable[Plugin]) -> None
```
`Plugin` 的类型是 `Callable[[type[Astrolabe]], None]`。
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------- | ------------------ | -- | -- | ------------------- |
| `plugin` | `Plugin` | 是 | — | 接受 `Astrolabe` 类的函数 |
| `plugins` | `Iterable[Plugin]` | 是 | — | 按顺序加载的多个插件 |
**返回值** `None`。方法直接挂到类上。
**边界与陷阱**
方法挂在**类**上而非实例上，因此加载时机不影响已有实例——
先排的盘在插件加载后一样能调用新方法。
`load_plugin` 传入非可调用对象时抛 `TypeError`。
`load_plugins` 逐个加载，遇到第一个不可调用的即报错，后续插件不会加载。
插件改的是 `Astrolabe` 类本身，进程内所有星盘都受影响。
同名方法会被后加载的插件覆盖。
***
## 为什么能挂上去 [#为什么能挂上去]
`Astrolabe` 是 `slots=True` 的 frozen dataclass，实例上挂不了属性：
```python
try:
chart.foo = 1
except Exception as e:
print(type(e).__name__, e)
```
**输出**
```text
FrozenInstanceError cannot assign to field 'foo'
```
但**类**上挂方法不受影响。这正是插件需要的粒度：
插件改的是「所有星盘都有这个方法」，不是「这一张盘多了个字段」。
***
## 扩展别的类型 [#扩展别的类型]
同一套写法适用于宫位与星耀，直接给对应的类挂方法即可：
```python
from x_iztro.models import Palace
def palace_analysis(cls: type[Palace]) -> None:
def is_afflicted(self) -> bool:
"""本宫是否「煞忌交冲」：坐煞星且带化忌"""
sha = ["qingyangMin", "tuoluoMin", "huoxingMin",
"lingxingMin", "dikongMin", "dijieMin"]
return self.has_one_of(sha) and self.has_mutagen("sihuaJi")
cls.is_afflicted = is_afflicted
palace_analysis(Palace)
```
```python
for p in chart.palaces:
if p.is_afflicted():
print(p.name, "煞忌交冲")
```
**输出**
```text
疾厄 煞忌交冲
```
`load_plugin` 只接受作用于 `Astrolabe` 的插件。要挂到别的类上，
像上例那样直接调用函数即可——插件机制本身没有魔法。
***
## 组织建议 [#组织建议]
`wealth_analysis`、`career_analysis`、`health_analysis` 各自成插件，
按需 `load_plugin`。堆成一个大插件会让所有使用方都被迫加载全部方法。
`s.key == MajorStar.ZIWEI` 在任何输出语言下都成立；
`s.name == "紫微"` 只在中文盘上成立。展示时才用 `name`。
挂上去的方法对静态类型检查器不可见，调用处会被标为「未知属性」。
需要类型友好时，为扩展后的星盘声明一个 Protocol 或直接用 `cast`。
# 错误处理 (/zh/docs/python/errors)
IztroError 的 code 分类、触发条件、消息格式与处理模式。
所有收外部输入的入口在入参非法时抛 `IztroError`。日期格式、日期存在性、
年份范围、时辰索引在核心层前置校验；性别、语言、标识、配置这些字符串取值在绑定层校验。
```python
from x_iztro import IztroError
```
`IztroError` 继承自 `ValueError`，因此既有的 `except ValueError` 照样接得住，
不必为升级改代码。
## code [#code]
异常消息面向人，会随版本调整措辞；要在程序里分支请用 `.code`：
| `code` | 含义 | 典型触发 |
| -------------------- | --------- | ---------------------- |
| `invalid_date` | 日期非法 | 格式错、日期不存在、超出 1583–9999 |
| `invalid_time_index` | 时辰索引越界 | 不在 0–12 |
| `invalid_argument` | 其余入参或配置非法 | 性别、语言、星耀标识、宫名、自定义表 |
| `internal` | 库内部缺陷 | 应视为 bug 上报 |
这四个取值与 Rust 的 `IztroError::code()`、Go 的 `iztro.Error.Code` 是同一套，
跨语言分支逻辑可以照抄。
```python
from x_iztro import Astro, IztroError
for args in [("2000-2-30", 2, "female"), ("2000-8-16", 13, "female"), ("2000-8-16", 2, "x")]:
try:
Astro().by_solar(*args)
except IztroError as e:
print(e.code, "|", e)
```
**输出**
```text
invalid_date | invalid solar date '2000-2-30': day is out of range for that month
invalid_time_index | time_index must be 0-12, got 13
invalid_argument | invalid gender 'x': expected 'male' or 'female'
```
库内部缺陷导致的 panic 在绑定层被兜住，转成 `code` 为 `internal` 的 `IztroError`，
不会漏出 `except Exception` 捕获不到的 `pyo3_runtime.PanicException`。
***
## 日期相关 [#日期相关]
| 情形 | 例 | 消息 |
| --------------- | ------------- | ------------------------------------ |
| 格式不是 `YYYY-M-D` | `"2000/8/16"` | `expected 'YYYY-M-D'` |
| 年、月、日不是数字 | `"abc-8-16"` | `year is not a number` |
| 月份越界 | `"2000-13-1"` | `month must be within 1-12` |
| 该月没有这一天 | `"2000-2-30"` | `day is out of range for that month` |
| 年份超出支持范围 | `"1500-1-1"` | `year must be within 1583-9999` |
农历专有（只有 `by_lunar` 与两个 `*_by_lunar_date` 查询会碰到）：
| 情形 | 例 | 消息 |
| --------- | -------------------- | ------------------------------------------ |
| 该农历年没有这个月 | 表内缺月 | `month does not exist in that lunar year` |
| 该农历月没有这一天 | `"2000-7-30"`（七月是小月） | `day is out of range for that lunar month` |
农历消息的前缀是 `invalid lunar date '<原串>': `，公历是 `invalid solar date '<原串>': `，
从消息就能看出走的是哪个入口。
**示例**
```python
from x_iztro import Astro
for date in ["2000-13-1", "2000-2-30", "1500-1-1"]:
try:
Astro().by_solar(date, 2, "female")
except IztroError as e:
print(e)
```
**输出**
```text
invalid solar date '2000-13-1': month must be within 1-12
invalid solar date '2000-2-30': day is out of range for that month
invalid solar date '1500-1-1': year must be within 1583-9999
```
消息里带上了原始输入，便于在批量处理时定位是哪一条数据出的问题。
**边界与陷阱**
1582 年格里历改革当年有一段不存在的日期。底层历法库在这些日期上没有定义，
因此支持范围从改革完成后的 1583 年起算。上限 9999 是农历数据表的覆盖终点。
`"2000-8-16"` 与 `"2000-08-16"` 都接受。分隔符必须是 `-`。
`by_lunar` 会检查该农历年该月是否真的存在，以及该月有多少天（大月 30、小月 29）。
`is_leap_month` 传 `True` 但那年那月无闰月时不报错，参数被静默忽略。
***
## 时辰索引 [#时辰索引]
**触发条件** 时辰索引不在 0–12。
**示例**
```python
try:
Astro().by_solar("2000-8-16", 13, "female")
except IztroError as e:
print(e)
```
**输出**
```text
time_index must be 0-12, got 13
```
**边界与陷阱**
子时跨午夜，拆成早子时（索引 0）与晚子时（索引 12），因此合法值有 13 个。
从小时数换算用 [`utils.time_to_index`](/zh/docs/python/util#time_to_index)，
它保证结果落在合法范围。
***
## 性别与语言 [#性别与语言]
`code` 均为 `invalid_argument`。
| 参数 | 合法值 | 消息 |
| ---------- | --------------------- | --------------------------------------------------------------------------------- |
| `gender` | `"male"` / `"female"` | `invalid gender 'x': expected 'male' or 'female'` |
| `language` | 六个语言代码 | `invalid language 'xx': expected one of zh-CN, zh-TW, en-US, ja-JP, ko-KR, vi-VN` |
语言代码大小写不敏感，`"zh-cn"` 与 `"zh-CN"` 都接受。
用 `Gender` / `Language` 枚举传参可以在写错的当场被 IDE 挡下。
***
## 标识相关 [#标识相关]
工具函数与安星函数收的是语言无关标识，未知标识会报错：
```python
from x_iztro import utils
try:
utils.get_brightness("nosuchstar", 0)
except IztroError as e:
print(e.code, "|", e)
```
**输出**
```text
invalid_argument | unknown star key 'nosuchstar'
```
这些函数只认标识不认译名。传 `"紫微"` 会得到
`unknown star key '紫微'`——先用 [`i18n.key_of`](/zh/docs/python/i18n#key_of) 换算。
星盘上的**查询方法**（`chart.palace`、`chart.star`、`palace.has`）是另一套规则：
它们同时接受标识与当前语言的译名，且查不到时静默返回 `None` / `False` 而不报错。
详见[星盘对象](/zh/docs/python/astrolabe#palace)。
***
## 配置相关 [#配置相关]
`ChartConfig` 的六个开关与两张自定义表都在排盘时校验，`code` 均为 `invalid_argument`：
| 情形 | 消息 |
| ------------ | -------------------------------------------------------------------------------- |
| 开关取值未知 | `invalid yearDivide 'nope': expected 'normal' or 'exact'` |
| 四化表的天干标识未知 | `invalid mutagens key 'nope': unknown heavenly stem` |
| 某个天干的四化不是四项 | `invalid mutagens for 'jiaHeavenly': expected 4 stars (lu, quan, ke, ji), got 1` |
| 某颗星的亮度表不是十二项 | `invalid brightness for 'ziweiMaj': expected 12 entries, got 1` |
长度是**严格**校验：四化必须正好四项、亮度必须正好十二项，多一项少一项都报错。
自定义表只收标识不收译名。
***
## 处理模式 [#处理模式]
**批量处理时跳过坏数据**
```python
rows = [
{"date": "2000-8-16", "ti": 2, "gender": "female"},
{"date": "2000-2-30", "ti": 2, "gender": "female"},
{"date": "1990-3-3", "ti": 13, "gender": "male"},
]
charts, failed = [], []
astro = Astro()
for row in rows:
try:
charts.append(astro.by_solar(row["date"], row["ti"], row["gender"]))
except IztroError as e:
failed.append((row["date"], e.code))
print(len(charts), failed)
```
**输出**
```text
1 [('2000-2-30', 'invalid_date'), ('1990-3-3', 'invalid_time_index')]
```
**转成自己的异常类型**
```python
class ChartError(Exception):
def __init__(self, code: str, message: str):
super().__init__(message)
self.code = code
def build(date: str, ti: int, gender: str):
try:
return Astro().by_solar(date, ti, gender)
except IztroError as e:
raise ChartError(e.code, f"排盘失败: {e}") from e
try:
build("2000-2-30", 2, "female")
except ChartError as e:
print(e.code, "|", e)
```
**输出**
```text
invalid_date | 排盘失败: invalid solar date '2000-2-30': day is out of range for that month
```
`code` 转出去之后，上层就不必再解析文案。
# 概览 (/zh/docs/go)
包结构、类型体系与阅读本参考的方式。
Go 包内嵌一份 WebAssembly 编译的核心，经纯 Go 的 wazero 运行时调用——
**不需要 cgo**，交叉编译与静态链接都不受影响。
这一栏是 Go 侧的完整 API 参考——每个导出函数、类型与方法都有独立条目。
## 安装 [#安装]
```bash
go get github.com/x-haose/x-iztro/go/iztro
```
```go
import "github.com/x-haose/x-iztro/go/iztro"
```
## 第一张盘 [#第一张盘]
```go
chart, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.SolarDate, chart.LunarDate)
// 2000-8-16 二〇〇〇年七月十七
soul := chart.Palace(iztro.PalaceSoul)
if len(soul.MajorStars) > 0 {
fmt.Println(soul.MajorStars[0].Name)
// 紫微
} else {
fmt.Println("命宫是空宫，借对宫看:", soul.OppositePalace().MajorStars[0].Name)
}
```
一张盘上通常有两宫无主星（空宫），命宫也可能是其中之一。
直接写 `soul.MajorStars[0]` 在那种盘上会 panic——先判长度，或用
[`IsEmpty`](/zh/docs/go/palace#isempty) 分支到借对宫的写法。
## 包结构 [#包结构]
包是扁平的，全部导出项都在 `iztro` 下。按主题划分：
| 主题 | 主要导出 | 本参考对应页 |
| ---- | ------------------------------------------------ | ---------------------------------- |
| 排盘 | `BySolar`、`ByLunar`、`Rearranged` | [排盘入口](/zh/docs/go/astro) |
| 数据类型 | `Astrolabe`、`Palace`、`Star`、`Horoscope`、`Config` | [星盘对象](/zh/docs/go/astrolabe) 起的四页 |
| 标识常量 | `PalaceSoul`、`StarZiweiMaj`、`MutagenLu` 等 | [数据表](/zh/docs/go/data) |
| 轻量查询 | `GetZodiacBySolarDate` 等 | [轻量查询](/zh/docs/go/query) |
| 工具函数 | `FixIndex`、`GetBrightness` 等 | [工具函数](/zh/docs/go/util) |
| 安星 | `GetMajorStar`、`GetHoroscopeStar` 等 | [安星模块](/zh/docs/go/star) |
| 数据表 | `StarsInfo`、`HeavenlyStems` 等 | [数据表](/zh/docs/go/data) |
| 翻译 | `Translate`、`KeyOf`、`KeyOfIn` | [翻译](/zh/docs/go/i18n) |
| 错误 | `*Error`、`Err*` 哨兵、`Code*` 常量 | [错误处理](/zh/docs/go/errors) |
| 运行时 | `Warmup`、`Close`、`CompilationCacheDir` | 本页下方 |
## 常量即标识 [#常量即标识]
包里的标识常量取值就是语言无关标识，可直接与数据对象的 `*Key` 字段比较：
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.MajorStars[0].Key == iztro.StarZiweiMaj)
// true
```
它们都是无类型字符串常量，字符串字面量同样有效——
`chart.Palace("soulPalace")` 与 `chart.Palace(iztro.PalaceSoul)` 等价。
常量的价值在于 IDE 补全与拼写检查。
`star.Name` 随排盘语言变化（中文盘是「紫微」，英文盘是 `emperor`）；
`star.Key` 在任何语言下都是 `ziweiMaj`。所有判断都应基于 `*Key` 字段或内置判断方法。
## 可变参数 [#可变参数]
需要传星耀列表或四化列表的方法一律用可变参数，调用处不必构造切片：
```go
soul := chart.Palace(iztro.PalaceSoul)
target := chart.Palace(iztro.PalaceWealth)
fmt.Println(soul.Has(iztro.StarZiweiMaj, iztro.StarTianxiangMaj))
fmt.Println(soul.FliesTo(target, iztro.MutagenLu, iztro.MutagenJi))
```
**输出**
```text
false
false
```
已有切片时用 `...` 展开：
```go
soul := chart.Palace(iztro.PalaceSoul)
stars := []string{iztro.StarZiweiMaj, iztro.StarTianxiangMaj}
fmt.Println(soul.Has(stars...))
```
**输出**
```text
false
```
`HasHoroscopeStars` 一族的星耀参数是 `[]string` 而非可变参数，
因为它前面已有宫名与层级两个字符串参数，可变参数会让调用处产生歧义。
## 错误处理 [#错误处理]
需要计算的入口都返回 `(值, error)`；纯查询方法（`Palace`、`Star`、`Has` 等）不返回错误，
查不到时返回 `nil` 或零值。
```go
_, err := iztro.BySolar("2000-13-1", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
fmt.Println(err)
fmt.Println(errors.Is(err, iztro.ErrInvalidDate))
var e *iztro.Error
if errors.As(err, &e) {
fmt.Println(e.Code)
}
```
**输出**
```text
iztro: invalid solar date '2000-13-1': month must be within 1-12
true
invalid_date
```
错误一律是 `*iztro.Error`，带机器可读的 `Code`，并可用 `errors.Is` 对四个哨兵匹配。
详见[错误处理](/zh/docs/go/errors)。
## 运行时与性能 [#运行时与性能]
wasm 模块**编译一次、实例按需铺开**：实例各持有自己的线性内存，
因此并发调用各占一个实例而不是共享一个加锁，实例数上限为 `GOMAXPROCS`。
排盘的热路径上没有全局互斥锁——取实例走 channel，只有运行时首次初始化与 `Close`
才加锁。多 goroutine 同时排盘因此能真正并行：同一台十核机器上，
8 个 goroutine 跑 800 次排盘比单 goroutine 快四倍出头。
编译产物落盘缓存在用户缓存目录下（`CompilationCacheDir` 可查），
按 wasm 内容哈希分桶，换了 wasm 自然换桶。
实测量级（Apple M 系列，10 核；具体数字随机器与 wasm 体积浮动）：
| 阶段 | 耗时 |
| --------------------------- | ----- |
| 首次调用，编译缓存**未命中**（要现编译 wasm） | 一两百毫秒 |
| 首次调用，编译缓存命中 | 二三十毫秒 |
| 稳态单次排盘 | 半毫秒上下 |
稳态那半毫秒里，大头是 wasm 侧把整张盘序列化成 JSON、Go 侧再反序列化成结构体，
而不是斗数推算本身。只需要个别字段时，用
[轻量查询](/zh/docs/go/query)（`GetMajorStarBySolarDate` 一类）比排整盘划算得多。
### Warmup / Close / CompilationCacheDir [#warmup--close--compilationcachedir]
```go
func Warmup(ctx context.Context) error
func Close(ctx context.Context) error
func CompilationCacheDir(ctx context.Context) (string, error)
```
| 函数 | 说明 |
| --------------------- | ---------------------------------------------------- |
| `Warmup` | 预先完成编译并把实例池铺满，把冷启动开销提前到启动阶段。不调用也能正常工作——编译与实例化本来就是惰性的 |
| `Close` | 关闭运行时、归还全部实例内存。通常不必调用；关闭后再调用本包任何函数会自动重新初始化 |
| `CompilationCacheDir` | 返回编译缓存目录；未启用落盘缓存时返回空串 |
```go
ctx := context.Background()
if err := iztro.Warmup(ctx); err != nil {
log.Fatal(err)
}
dir, err := iztro.CompilationCacheDir(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(dir != "")
chart, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.SolarDate)
```
**输出**
```text
true
2000-8-16
```
服务进程希望第一个请求就走热路径时，在启动阶段调一次 `Warmup` 即可。
### Context 变体 [#context-变体]
排盘、运限、重排、文本投影这些要进 wasm 的入口都有一个 `*Context` 版本，
多收一个 `context.Context`：
| 无 ctx | 带 ctx |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `BySolar` / `ByLunar` | `BySolarContext` / `ByLunarContext` |
| `Astrolabe.Horoscope` / `HoroscopeNow` | `HoroscopeContext` / `HoroscopeNowContext` |
| `Astrolabe.Rearranged` | `RearrangedContext` |
| `Astrolabe.ToText` / `Horoscope.ToText` / `PalaceToText` / `SurroundedPalacesToText` / `PatternsToText` | `ToTextContext` / `PalaceToTextContext` / `SurroundedPalacesToTextContext` / `PatternsToTextContext` |
| 上列各方法的 `With` 形态（`ToTextWith(opts TextOptions)` 等） | `ToTextWithContext` / `PalaceToTextWithContext` / `SurroundedPalacesToTextWithContext` / `PatternsToTextWithContext` |
| — | `Warmup` / `Close` / `CompilationCacheDir` 只有 ctx 版本 |
```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
chart, err := iztro.BySolarContext(ctx, "2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.SolarDate)
```
**输出**
```text
2000-8-16
```
`ctx` 用于取消**等待空闲 wasm 实例**的排队。实例一旦拿到，wasm 侧的计算不可中断——
单次排盘本来就是亚毫秒级，没有需要中途打断的长任务。
这两个架构上 wazero 走优化编译器（编译成机器码）。其余架构回落到解释器，
仍然能跑出正确结果，但速度会低一个量级以上。生产环境请部署在 amd64 或 arm64 上。
## 条目怎么读 [#条目怎么读]
每个 API 条目按固定八段组织：
**用途**
—— 一句话说清它做什么
**斗数含义**
—— 它在紫微斗数里对应什么概念（纯工程性的函数省略此段）
**签名**
—— 从源码原样摘出
**参数**
—— 名、类型、是否必填、默认值、说明
**返回值**
—— 类型与结构
**示例**
—— 可直接运行的片段
**输出**
—— 该示例的真实运行结果
**边界与陷阱**
—— 空值、越界、配置影响、与其他 API 的相互作用
示例统一用同一张盘：**2000 年 8 月 16 日寅时女命**，
方便跨页对照。这张盘的完整数据见[数据结构](/zh/docs/guide/data-model)。
# 排盘入口 (/zh/docs/go/astro)
BySolar、ByLunar、Rearranged 与语义化文本投影。
排盘是一切的起点：给出生日期、时辰、性别，得到一个 `*Astrolabe`。
所有入口都返回 `error`。日期格式与存在性、公历年份范围、时辰索引、性别、
语言、配置都在核心层前置校验。详见[错误处理](/zh/docs/go/errors)。
***
## BySolar [#bysolar]
**用途** 由公历日期排出本命盘。
**斗数含义** 紫微斗数以农历为算法基础，但绝大多数人只记得公历生日。
本函数先把公历转农历（含年、月、日、时四柱），再据此安星。
换年的时点受 `YearDivide` 影响——正月初一与立春之间出生的人，
两种配置会得到不同的年干支，进而影响四化、命主身主与全部年系星。
**签名**
```go
func BySolar(
solarDate string,
timeIndex uint8,
gender Gender,
fixLeap bool,
language Language,
config *Config,
) (*Astrolabe, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ---------- | -- | -- | ------------------------------------------------------------------------------ |
| `solarDate` | `string` | 是 | — | 公历日期，格式 `YYYY-M-D`，月日不必补零。支持 1583–9999 年 |
| `timeIndex` | `uint8` | 是 | — | 时辰索引 0–12。0 为早子时（00:00–01:00），12 为晚子时（23:00–24:00） |
| `gender` | `Gender` | 是 | — | `GenderMale` 或 `GenderFemale`（字面量 `"male"`/`"female"` 也可）。决定大限顺逆与长生、博士十二神的排列方向 |
| `fixLeap` | `bool` | 是 | — | 是否调整农历闰月。为真时闰月十六日起按下月算（晚子时除外，见下） |
| `language` | `Language` | 是 | — | 盘面语言（`LanguageZhCN` 等），影响所有译名字段；`*Key` 标识字段不受影响 |
| `config` | `*Config` | 是 | — | 排盘配置，传 `nil` 取默认 |
**返回值** `*Astrolabe`——十二宫、四柱、命主身主、五行局俱全的完整星盘。
**示例**
```go
chart, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.SolarDate, "|", chart.LunarDate, "|", chart.ChineseDate)
fmt.Println(chart.Sign, chart.Zodiac, chart.FiveElementsClass)
fmt.Println("命主", chart.Soul, "身主", chart.Body)
```
**输出**
```text
2000-8-16 | 二〇〇〇年七月十七 | 庚辰 甲申 丙午 庚寅
狮子座 龙 木三局
命主 破军 身主 文昌
```
**边界与陷阱**
子时横跨午夜，分早子时（00:00–01:00，属当日）与晚子时（23:00–24:00，属次日）。
两者的日柱不同，紫微起宫也可能差一天，因此必须区分，索引才有 13 个。
不确定时辰索引时用 `TimeToIndex(hour)` 换算。
进位要同时满足四个条件：该农历月确实是闰月、`fixLeap` 为 `true`、
农历日大于 15、且时辰索引不是 12（晚子时）。四者缺一，月索引就按本月算。
因此只有农历闰月下半月出生的人，`true` 与 `false` 会得到不同的月索引，
进而影响左辅右弼与全部月系星。
`&Config{}` 与 `nil` 效果相同——所有字段都有 `omitempty`，空值不会覆盖默认。
但显式写 `nil` 更清楚表达「用默认配置」。
***
## ByLunar [#bylunar]
**用途** 由农历日期排出本命盘。
**斗数含义** 农历日期是斗数的原生输入，跳过公历转换这一步。
知道自己农历生日的人直接用它，结果与用对应公历日期调 `BySolar` 完全一致。
**签名**
```go
func ByLunar(
lunarDate string,
timeIndex uint8,
gender Gender,
leap LeapMonth,
language Language,
config *Config,
) (*Astrolabe, error)
```
**参数** 除以下两项外，其余与 `BySolar` 相同；`BySolar` 的 `fixLeap` 在这里并入 `leap`。
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ----------- | -- | -- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `lunarDate` | `string` | 是 | — | 农历日期，格式 `YYYY-M-D`，月份写正数（闰月由下一参数标记） |
| `leap` | `LeapMonth` | 是 | — | `NotLeapMonth` 非闰月；`LeapMonthKeep` 闰月、按闰月本身排；`LeapMonthFixed` 闰月且十五之后视作次月（iztro `fixLeap`）。标为闰月但那年那月没有闰月时按普通月处理；其它取值返回 `ErrInvalidArgument` |
**返回值** 同 `BySolar`。
**示例**
```go
a, _ := iztro.ByLunar("2000-7-17", 2, iztro.GenderFemale, iztro.NotLeapMonth, iztro.LanguageZhCN, nil)
b, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
fmt.Println(a.SolarDate, a.SolarDate == b.SolarDate)
```
**输出**
```text
2000-8-16 true
```
**边界与陷阱**
`leap` 标为闰月但那个月并非闰月时，按普通月排盘，不返回错误（与 iztro 一致）。
如果需要严格校验，调用前先自行确认该年该月确实有闰月。
***
## Config [#config]
排盘配置。所有字段都可省略，省略即取默认。
```go
type Config struct {
YearDivide string
HoroscopeDivide string
AgeDivide string
DayDivide string
Algorithm string
AstroType string
Mutagens map[string][]string
Brightness map[string][]string
}
```
| 字段 | 取值 | 默认 | 说明 |
| ----------------- | ---------------------------------- | ----------- | -------------- |
| `YearDivide` | `"normal"` / `"exact"` | `"normal"` | 年干支按正月初一还是立春换年 |
| `HoroscopeDivide` | `"normal"` / `"exact"` | `"normal"` | 流年神煞按哪个分界取年支 |
| `AgeDivide` | `"normal"` / `"birthday"` | `"normal"` | 虚岁按农历年还是生日增长 |
| `DayDivide` | `"forward"` / `"current"` | `"forward"` | 晚子时归次日还是当日 |
| `Algorithm` | `"default"` / `"zhongzhou"` | `"default"` | 算法派别 |
| `AstroType` | `"heaven"` / `"earth"` / `"human"` | `"heaven"` | 排盘视角 |
| `Mutagens` | 天干标识 → 四星标识 | — | 自定义四化表，按天干整表替换 |
| `Brightness` | 星耀标识 → 十二项亮度标识 | — | 自定义亮度表，按星耀整表替换 |
**示例**
```go
cfg := &iztro.Config{
Algorithm: iztro.AlgorithmZhongzhou,
YearDivide: iztro.YearDivideExact,
}
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, cfg)
fmt.Println(chart.FiveElementsClass)
```
**输出**
```text
木三局
```
每组取值都有对应的常量，不必手写字符串：
`YearDivideNormal` / `YearDivideExact`、`HoroscopeDivideNormal` / `HoroscopeDivideExact`、
`AgeDivideNormal` / `AgeDivideBirthday`、`DayDivideForward` / `DayDivideCurrent`、
`AlgorithmDefault` / `AlgorithmZhongzhou`、`AstroHeaven` / `AstroEarth` / `AstroHuman`。
**边界与陷阱**
`Mutagens["jiaHeavenly"]` 必须给满四项（禄权科忌），
`Brightness["ziweiMaj"]` 必须给满十二项，多一项少一项都排盘报错
（`*Error`，`Code` 为 `invalid_argument`）。未列出的天干与星耀仍用默认表。
两张表的键与值都只收标识，不收译名。
`chart.Config` 由输出 DTO 还原，只含六个开关——两张自定义表是排盘**输入**而非结果，
不进 DTO（这一点与 JS iztro 的字段契约一致）。
但星盘内部保留了你传进来的原件，因此 `Rearranged`、`Horoscope`、ToText
这些二次计算仍然用得上那两张表，不会静默丢失。
要把配置记录下来，请在自己的调用侧保存 `*Config`。
```go
cfg := &iztro.Config{
AstroType: iztro.AstroEarth,
Mutagens: map[string][]string{
iztro.StemGeng: {iztro.StarTaiyangMaj, iztro.StarWuquMaj,
iztro.StarTianfuMaj, iztro.StarTiantongMaj},
},
}
chart, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, cfg)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.FiveElementsClass, chart.Config.AstroType)
fmt.Println(chart.Config.Mutagens == nil)
fmt.Println(chart.Palace(iztro.PalaceSoul).MutagenStarKeys)
```
**输出**
```text
土五局 earth
true
[tiantongMaj tianjiMaj wenchangMin lianzhenMaj]
```
所有字段都带 `omitempty`，空值不进 JSON，因此不会覆盖默认。
只想改一个开关时，构造一个只填那一项的 `&Config{...}` 即可。
***
## Rearranged [#rearranged]
**用途** 以指定干支为命宫重排本盘，返回新盘；原盘不变。
**斗数含义** 中州派把同一组出生数据看作三张盘：天盘以命宫干支起五行局，
地盘以身宫干支起，人盘以福德宫干支起。起局的干支一变，五行局就变，
紫微天府落点、十二宫名、长生十二神、大限小限随之全部重算。
本方法把这个能力放开到**任意干支**。
**签名**
```go
func (a *Astrolabe) Rearranged(fromStemKey string, fromBranchKey string) (*Astrolabe, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | -------- | -- | -- | -------- |
| `fromStemKey` | `string` | 是 | — | 新命宫的天干标识 |
| `fromBranchKey` | `string` | 是 | — | 新命宫的地支标识 |
**返回值** 新的 `*Astrolabe`。重算：命宫身宫、五行局、十四主星、十二宫名、
长生十二神、大限小限、命主星，以及随命宫挪位的天伤、天使、天才。
沿用原盘：辅星、其余杂耀、博士十二神、岁前与将前十二神、身主星。
重排返回的盘上，`Patterns`、运限查询与 ToText 文本投影都按**重排后的布局**
计算——五行局、命宫与大限随重排起点变化；出生数据（日期与四柱）保持不变。
**示例**
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
// 从原盘身宫的干支起盘，等价于地盘
var body *iztro.Palace
for i := range chart.Palaces {
if chart.Palaces[i].IsBodyPalace {
body = &chart.Palaces[i]
}
}
earth, _ := chart.Rearranged(body.HeavenlyStemKey, body.EarthlyBranchKey)
fmt.Println("天盘", chart.FiveElementsClass, "→ 地盘", earth.FiveElementsClass)
```
**输出**
```text
天盘 木三局 → 地盘 土五局
```
**边界与陷阱**
天盘、地盘、人盘用 `&Config{AstroType: iztro.AstroEarth}` 直接排即可，
两个排盘入口都支持。`Rearranged` 是为「从任意干支起盘」准备的。
身主星按**出生年支**查表，与命宫位置无关，重排不改变出生年。
命主星按命宫地支查表，因此会跟着更新。
***
## 语义化文本（ToText） [#语义化文本totext]
**用途** 把星盘或运限投影成语义化文本——盘面事实的自然语言形态，
喂给大模型或直接给人读。与 JSON DTO（机器结构）、译文字段（展示）
是同一对象的三种投影。
**签名**
```go
func (a *Astrolabe) ToText() (string, error)
func (h *Horoscope) ToText() (string, error)
func (a *Astrolabe) PalaceToText(target PalaceTarget) (string, error)
func (a *Astrolabe) SurroundedPalacesToText(target PalaceTarget) (string, error)
```
各有 `Context` 变体（`ToTextContext` 等），ctx 用于取消等待 wasm 实例；
各有 `With` 变体（`ToTextWith(opts TextOptions)` 等），带知识包时释义紧跟在对应事实之后，
见 [ToTextWith](/zh/docs/go/astrolabe#totextwith--palacetotextwith--surroundedpalacestotextwith)。
格局文本另见 `PatternsToText`（[格局判定](/zh/docs/go/patterns)）。
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | -------------- | -- | -- | ----------------------------------------------------------------------------------------------- |
| `target` | `PalaceTarget` | 是 | — | 宫位寻址：`Key` 非空时按宫名标识定位（`PalaceSoul` 等常量，另接受 `PalaceBody` / `PalaceOriginal`），否则按 `Index`（0–11）取宫 |
**返回值** `string`——按星盘的排盘语言输出的 Markdown 子集（`#` 标题、`- 标签: 值` 列表、
一张十二宫总览表）；本命文本带格局节与从命宫起的十二宫详解，
运限文本各层带该层视角的四化、流耀与格局行。全部记号见[格式约定](/zh/docs/guide/guides/to-text#格式约定)。
**示例**
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
text, _ := chart.ToText()
fmt.Println(strings.Join(strings.Split(text, "\n")[:4], "\n"))
```
**输出**
```text
# 命盘 2000-8-16 寅时 女
## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
```
**边界与陷阱**
输出语言跟随星盘的排盘语言，不单独设置。要英文文本就用英文排盘。
# 星盘对象 (/zh/docs/go/astrolabe)
Astrolabe 的字段、定位方法，以及三方四正与夹宫。
`Astrolabe` 是排盘的产物，也是一切查询的入口。它持有十二宫的全部数据，
以及四柱、命主身主、五行局这些盘级信息。
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
```
本页示例统一用 `"zh-CN"` 排盘，因此输出里的展示值都是中文。
换语言只改这些展示串，`*Key` 标识与所有判断方法的结果不变。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| --------------------------- | -------- | ---------- |
| `Gender` | `string` | 性别译名 |
| `SolarDate` | `string` | 公历日期，与入参一致 |
| `LunarDate` | `string` | 农历日期的中文写法 |
| `ChineseDate` | `string` | 四柱展示串 |
| `Time` | `string` | 时辰名 |
| `TimeRange` | `string` | 时辰对应的钟点区间 |
| `Sign` | `string` | 星座 |
| `Zodiac` | `string` | 生肖 |
| `Soul` | `string` | 命主星译名 |
| `Body` | `string` | 身主星译名 |
| `FiveElementsClass` | `string` | 五行局译名 |
| `EarthlyBranchOfSoulPalace` | `string` | 命宫地支译名 |
| `EarthlyBranchOfBodyPalace` | `string` | 身宫地支译名 |
展示字段随排盘语言翻译。要做判断请用下一组的 `*Key` 字段。
| 字段 | 类型 | 说明 |
| ------------------------------ | -------- | ----------------------------- |
| `GenderKey` | `Gender` | `GenderMale` / `GenderFemale` |
| `SignKey` | `string` | 星座标识，`aries` … `pisces` |
| `ZodiacKey` | `string` | 生肖标识，`rat` … `pig` |
| `SoulKey` | `string` | 命主星标识 |
| `BodyKey` | `string` | 身主星标识 |
| `FiveElementsClassKey` | `string` | 五行局标识 |
| `EarthlyBranchOfSoulPalaceKey` | `string` | 命宫地支标识 |
| `EarthlyBranchOfBodyPalaceKey` | `string` | 身宫地支标识 |
取值与包里的标识常量一一对应，可直接用 `==` 比较。
| 字段 | 类型 | 说明 |
| ---------- | ---------- | ------------------- |
| `Palaces` | `[]Palace` | 十二宫，索引 0 为寅宫、11 为丑宫 |
| `RawDates` | `RawDates` | 结构化的农历生日与四柱干支标识 |
`Palaces` 的索引是**宫位索引**而非宫名顺序：`Palaces[0]` 永远是寅宫，
命宫可能落在其中任何一格。取命宫用 `chart.Palace(iztro.PalaceSoul)`。
`RawDates` 是 `LunarDate` / `ChineseDate` 两个展示串的数据形式，
要做日期运算或按干支查表时用它，不必解析中文串：
```go
type RawDates struct {
LunarDate RawLunarDate `json:"lunarDate"`
ChineseDate RawChineseDate `json:"chineseDate"`
}
type RawLunarDate struct {
LunarYear int `json:"lunarYear"` // 农历年
LunarMonth int `json:"lunarMonth"` // 农历月 1–12，是否闰月看 IsLeap
LunarDay int `json:"lunarDay"` // 农历日 1–30
IsLeap bool `json:"isLeap"` // 是否闰月
}
type RawChineseDate struct {
Yearly [2]string `json:"yearly"` // 年柱译名 [天干, 地支]
YearlyKeys [2]string `json:"yearlyKeys"` // 年柱标识
Monthly [2]string `json:"monthly"`
MonthlyKeys [2]string `json:"monthlyKeys"`
Daily [2]string `json:"daily"`
DailyKeys [2]string `json:"dailyKeys"`
Hourly [2]string `json:"hourly"`
HourlyKeys [2]string `json:"hourlyKeys"`
}
```
`RawChineseDate` 另有一个方法 `PillarKeys() [4][2]string`，
按年、月、日、时的顺序一次给出四柱标识，正好是
[`TranslateChineseDate`](/zh/docs/go/util#translatechinesedate) 的入参形状：
```go
rd := chart.RawDates
fmt.Println(rd.LunarDate.LunarYear, rd.LunarDate.LunarMonth,
rd.LunarDate.LunarDay, rd.LunarDate.IsLeap)
fmt.Println(rd.ChineseDate.Yearly, rd.ChineseDate.YearlyKeys)
fmt.Println(rd.ChineseDate.PillarKeys())
```
**输出**
```text
2000 7 17 false
[庚 辰] [gengHeavenly chenEarthly]
[[gengHeavenly chenEarthly] [jiaHeavenly shenEarthly] [bingHeavenly wuEarthly] [gengHeavenly yinEarthly]]
```
| 字段 | 类型 | 说明 |
| ----------- | ---------- | ---------------------- |
| `TimeIndex` | `uint8` | 出生时辰索引 |
| `FixLeap` | `bool` | 排盘时是否修正闰月 |
| `Language` | `Language` | 盘面语言（`LanguageZhCN` 等） |
| `Config` | `Config` | 排盘配置，由 DTO 还原的六个开关 |
运限、重排与 Prompt 从这四项重新发起计算，因此不必再传一遍排盘参数。
`chart.Config` 是从输出 DTO 还原的，只含六个开关；排盘时传进来的自定义四化 / 亮度表
不在里面。但星盘内部保留了调用方给的原件，因此 `Rearranged`、`Horoscope`、
Prompt 这些二次计算仍然用得上那两张表——不会静默丢失。
***
## Palace / PalaceByIndex [#palace--palacebyindex]
**用途** 按宫名、身宫、来因宫或索引取一宫。
**斗数含义** 十二宫是斗数的骨架。命宫定下后，其余十一宫按固定顺序逆时针排开。
「身宫」是十二宫之一同时被标记的那一宫，代表后天着力处；
「来因宫」是宫干与生年干相同的那一宫，代表事情的起因。
**签名**
```go
func (a *Astrolabe) Palace(nameKeyOrName string) *Palace
func (a *Astrolabe) PalaceByIndex(index int) *Palace
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | -------- | -- | -- | -------------------------------------------- |
| `nameKeyOrName` | `string` | 是 | — | 宫名标识、`"bodyPalace"`、`"originalPalace"`，或宫名译名 |
| `index` | `int` | 是 | — | 宫位索引 0–11，0 为寅宫 |
**返回值** `*Palace`。名字拼错或索引越界时返回 `nil`；
`"soulPalace"` 一类宫名、`"bodyPalace"`、`"originalPalace"` 只要拼对，
在任何一张盘上都定位得到。
**示例**
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.Name, soul.HeavenlyStem+soul.EarthlyBranch)
fmt.Println("身宫:", chart.Palace("bodyPalace").Name)
fmt.Println("来因:", chart.Palace("originalPalace").Name)
fmt.Println("寅宫:", chart.PalaceByIndex(0).Name)
```
**输出**
```text
命宫 壬午
身宫: 官禄
来因: 夫妻
寅宫: 财帛
```
**边界与陷阱**
来因宫要求宫干与生年干相同，且该宫不在子、丑二宫。
十二宫的天干由五虎遁从寅宫起排，寅到酉这十宫刚好把十天干各走一遍，
子、丑两宫重复了寅、卯的天干——正因为重复才被排除。
于是生年干在寅到酉之间必然命中且只命中一次：任何一张盘上来因宫都存在，且唯一。
身宫同理恒存在。因此 `nil` 只可能来自索引越界或名字拼错。
`chart.Palace("soulPalce")`（少一个 a）不会报错，只会返回 `nil`，
下一步取字段就 panic，错误现场离真正的笔误已经隔了一段。
用包里的 `Palace*` 常量可以让编译器与 IDE 当场挡下；
名字来自外部输入时先过一遍 [`KeyOf`](/zh/docs/go/i18n#keyof) 校验。
Go 没有联合类型，因此拆成 `Palace`（收字符串）与 `PalaceByIndex`（收整数）两个方法。
三方四正同理，有 `SurroundedPalaces` 与 `SurroundedPalacesByIndex`。
***
## Star [#star]
**用途** 按标识找到一颗星，并同时取回它所在的宫。
**签名**
```go
func (a *Astrolabe) Star(keyOrName string) (*Star, *Palace)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | -------- | -- | -- | ------- |
| `keyOrName` | `string` | 是 | — | 星耀标识或译名 |
**返回值** `(*Star, *Palace)`。该星不在这张盘上时两者都为 `nil`。
**示例**
```go
ziwei, palace := chart.Star(iztro.StarZiweiMaj)
fmt.Println(ziwei.Name, "在", palace.Name)
fmt.Println("对宫是", ziwei.OppositePalace().Name)
fmt.Println("亮度", ziwei.Brightness, "四化", ziwei.Mutagen)
```
**输出**
```text
紫微 在 命宫
对宫是 迁移
亮度 庙 四化
```
四化为空串表示这颗星没有生年四化。
**边界与陷阱**
只在主星、辅星、杂耀三组里查找。长生十二神、博士十二神、岁前与将前十二神
是每宫一个的标记而非星耀列表，用 `palace.Changsheng12Key` 一类字段直接取。
***
## SurroundedPalaces / SurroundedPalacesByIndex [#surroundedpalaces--surroundedpalacesbyindex]
**用途** 取目标宫的三方四正。
**斗数含义** 三方四正是斗数最常用的取象范围：本宫、对宫（本宫 +6）、
官禄位（本宫 +4）、财帛位（本宫 +8）。四个宫合起来看，而不只看本宫，
是因为对宫与三合宫的星耀同样作用于本宫的事。
**签名**
```go
func (a *Astrolabe) SurroundedPalaces(nameKeyOrName string) *SurroundedPalaces
func (a *Astrolabe) SurroundedPalacesByIndex(index int) *SurroundedPalaces
```
**返回值** `*SurroundedPalaces`，含 `Target` / `Opposite` / `Wealth` / `Career` 四个 `*Palace`。
`SurroundedPalaces` 在名字拼错时返回 `nil`；`SurroundedPalacesByIndex` 对索引取模，
因此负数与超过 11 的索引都能正确回绕，只有零值星盘（不足十二宫）才返回 `nil`。
判断方法见[三方四正](/zh/docs/go/surpalaces)。
**示例**
```go
sp := chart.SurroundedPalaces(iztro.PalaceSoul)
fmt.Println(sp.Target.Name, sp.Opposite.Name, sp.Wealth.Name, sp.Career.Name)
fmt.Println("三方四正见紫微:", sp.Have(iztro.StarZiweiMaj))
```
**输出**
```text
命宫 迁移 财帛 官禄
三方四正见紫微: true
```
***
## IsSurrounded / IsSurroundedOneOf / NotSurrounded [#issurrounded--issurroundedoneof--notsurrounded]
**用途** 直接在星盘上判断某宫的三方四正里有没有指定星耀，省去先取三方四正的一步。
**签名**
```go
func (a *Astrolabe) IsSurrounded(nameKeyOrName string, stars ...string) bool
func (a *Astrolabe) IsSurroundedOneOf(nameKeyOrName string, stars ...string) bool
func (a *Astrolabe) NotSurrounded(nameKeyOrName string, stars ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ----------- | -- | -- | --------- |
| `nameKeyOrName` | `string` | 是 | — | 宫名标识或译名 |
| `stars` | `...string` | 是 | — | 星耀标识，可变参数 |
**返回值**
| 方法 | 语义 |
| ------------------- | ----------------- |
| `IsSurrounded` | 列出的**每一颗**都在三方四正里 |
| `IsSurroundedOneOf` | 列出的**至少一颗**在三方四正里 |
| `NotSurrounded` | 列出的**一颗都不在**三方四正里 |
**示例**
```go
fmt.Println(chart.IsSurrounded(iztro.PalaceSoul, iztro.StarZiweiMaj, iztro.StarTianxiangMaj))
fmt.Println(chart.IsSurroundedOneOf(iztro.PalaceSoul, iztro.StarQishaMaj, iztro.StarPojunMaj))
fmt.Println(chart.NotSurrounded(iztro.PalaceSoul, iztro.StarHuoxingMin))
```
**输出**
```text
true
false
true
```
命宫只坐紫微，天相在三方之一的财帛宫，因此第一行为真；
七杀与破军都不在这四宫内，第二行为假。
**边界与陷阱**
一颗星都不传时，`IsSurrounded` 与 `NotSurrounded` 返回 `true`
（「所有元素都满足」与「没有元素不满足」对空集都成立），
`IsSurroundedOneOf` 返回 `false`。
***
## FlankingPalaces [#flankingpalaces]
**用途** 取目标宫的夹宫：盘上紧邻它前后的两宫。
**斗数含义** 「羊陀夹忌」「日月夹命」这类说法看的就是夹宫。
夹宫与三方四正是两条不重叠的线索：三方四正问的是同一组能量彼此呼应，
夹宫问的是这一宫左右两侧的处境。
**签名**
```go
func (a *Astrolabe) FlankingPalaces(target PalaceTarget) (*FlankingPalaces, error)
func (a *Astrolabe) FlankingPalacesContext(ctx context.Context, target PalaceTarget) (*FlankingPalaces, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | -------------- | -- | -- | -------------------------------------------------------------------- |
| `target` | `PalaceTarget` | 是 | — | `Key` 非空时按宫名标识定位（另接受 `PalaceBody` / `PalaceOriginal`），否则按 `Index` 取宫 |
**返回值** `*FlankingPalaces`，两个 `*Palace` 字段：
| 字段 | 相对目标宫 | 说明 |
| ---------- | ----- | --- |
| `Previous` | -1 | 前一宫 |
| `Next` | +1 | 后一宫 |
十二宫首尾相连，索引对 12 回绕：第 0 宫的前一宫是第 11 宫。
两个字段都是本盘上的宫位，`Palace` 的飞化、三方四正等关系查询照常可用。
五个判断方法与[三方四正](/zh/docs/go/surpalaces)同名同义，只是作用范围换成这两宫：
| 方法 | 语义 |
| ---------------------------------------- | ------------- |
| `Have(stars ...string) bool` | 两宫合起来含列表中每一颗 |
| `NotHave(stars ...string) bool` | 两宫一颗都不含 |
| `HaveOneOf(stars ...string) bool` | 两宫合起来至少含一颗 |
| `HaveMutagen(mutagenKey string) bool` | 两宫中有任一宫带该生年四化 |
| `NotHaveMutagen(mutagenKey string) bool` | 两宫都不带 |
星耀是可变参数，既可以写 `StarZiweiMaj` 这些常量，也可以写当前语言的星名。
**示例**
```go
f, _ := chart.FlankingPalaces(iztro.PalaceTarget{Key: iztro.PalaceSoul})
fmt.Println(f.Previous.Name, "/", f.Next.Name)
fmt.Println(f.Have(iztro.StarTianjiMaj, iztro.StarTuoluoMin))
fmt.Println(f.HaveOneOf(iztro.StarHuoxingMin))
w, _ := chart.FlankingPalaces(iztro.PalaceTarget{Key: iztro.PalaceWealth})
fmt.Println(w.Previous.Name, "/", w.Next.Name)
fmt.Println(w.HaveMutagen(iztro.MutagenLu), w.HaveMutagen(iztro.MutagenJi))
```
**输出**
```text
兄弟 / 父母
true
false
疾厄 / 子女
true true
```
命宫在午，夹它的是兄弟（巳）与父母（未）。天机坐兄弟、陀罗坐父母，分处两宫，
`Have` 仍然成立；火星坐夫妻，不在这两宫之内，因此 `HaveOneOf` 为 `false`。
财帛在寅，夹它的疾厄坐天同、子女坐太阳，这张盘生年干庚使太阳化禄、天同化忌，
于是禄与忌两问都为 `true`。
**边界与陷阱**
`Have(A, B)` 问的是「A 和 B 都出现在这两宫里」，不要求它们同在其中一宫。
要单看某一侧，直接对 `f.Previous` / `f.Next` 调宫位的
[`Has`](/zh/docs/go/palace#has--nothave--hasoneof)。
索引对 12 回绕，十二宫每一宫都有完整的前后两宫。
***
## Horoscope / HoroscopeNow [#horoscope--horoscopenow]
**用途** 以本盘为起点计算目标日期的运限。
**签名**
```go
func (a *Astrolabe) Horoscope(targetDate string, targetTimeIndex uint8) (*Horoscope, error)
func (a *Astrolabe) HoroscopeNow() (*Horoscope, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------------- | -------- | -- | -- | -------------------- |
| `targetDate` | `string` | 是 | — | 目标公历日期，格式 `YYYY-M-D` |
| `targetTimeIndex` | `uint8` | 是 | — | 目标时辰索引 0–12，决定流时 |
`HoroscopeNow` 取本地时钟的当前日期与当前时辰，无参数。
**返回值** `*Horoscope`——持有本盘的运限对象，六个层级的宫位查询不必再传星盘。
详见[运限对象](/zh/docs/go/horoscope)。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println("大限", h.Decadal.HeavenlyStem+h.Decadal.EarthlyBranch)
fmt.Println("流年", h.Yearly.HeavenlyStem+h.Yearly.EarthlyBranch)
```
**输出**
```text
大限 庚辰
流年 乙巳
```
***
## ToText / PalaceToText / SurroundedPalacesToText [#totext--palacetotext--surroundedpalacestotext]
**用途** 星盘、单宫或三方四正的语义化文本：面向语言模型与人的完整描述。
**签名**
```go
func (a *Astrolabe) ToText() (string, error)
func (a *Astrolabe) PalaceToText(target PalaceTarget) (string, error)
func (a *Astrolabe) SurroundedPalacesToText(target PalaceTarget) (string, error)
```
各有 `Context` 变体。`PalaceTarget` 的 `Key` 非空时按宫名标识定位
（`PalaceSoul` 等常量，另接受 `PalaceBody` / `PalaceOriginal`），
否则按 `Index`（0–11）取宫。按排盘语言输出，
完整格式见[语义化文本](/zh/docs/guide/guides/to-text)。
**示例**
```go
text, _ := chart.PalaceToText(iztro.PalaceTarget{Key: iztro.PalaceSoul})
fmt.Println(strings.Split(text, "\n")[0])
```
**输出**
```text
### 命宫 (壬午) · 大限 3-12
```
单宫文本就是本命文本「十二宫」节里该宫的段落；三方四正文本以 `## 命宫 三方四正` 起，
下接本宫、对宫、财帛位、官禄位四段，每段标题带角色前缀（`### 本宫 · 命宫 (壬午) · 大限 3-12`），事实行与单宫文本一致。格局文本见 `PatternsToText`（[格局判定](/zh/docs/go/patterns)）。
***
## ToTextWith / PalaceToTextWith / SurroundedPalacesToTextWith [#totextwith--palacetotextwith--surroundedpalacestotextwith]
**用途** 对应 `ToText` 的文本，按 `opts` 带上知识包里的释义：每宫事实行之后紧跟该宫星耀的释义
（`**星名(亮度)化X**: 正文`，同宫主星的组合解读 `**A × B (同宫)**: ` 放最前；十二神不释义），
格局列表之后紧跟格局释义（含 `成立条件: ` 段），本命文本末尾另有 `## 四化释义`。
**签名**
```go
func (a *Astrolabe) ToTextWith(opts TextOptions) (string, error)
func (a *Astrolabe) PalaceToTextWith(target PalaceTarget, opts TextOptions) (string, error)
func (a *Astrolabe) SurroundedPalacesToTextWith(target PalaceTarget, opts TextOptions) (string, error)
```
**参数**
| 参数 | 类型 | 说明 |
| -------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target` | `PalaceTarget` | 同 `PalaceToText` |
| `opts` | [`TextOptions`](/zh/docs/go/knowledge#textoptions) | 输出选项。`Knowledge` 字段给释义材料来源：`BuiltinKnowledge()` 取盘语言的内嵌默认包，`KnowledgeFrom(pack)` 用给定的包；`PatternConfig` 字段给格局判定口径，同时作用于格局节与格局释义；零值 `TextOptions{}` 等同不带 `With` 的方法 |
各有 `Context` 变体。释义的插入位置与去重规则见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```go
plain, _ := chart.ToText()
text, _ := chart.ToTextWith(iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()})
fmt.Println(utf8.RuneCountInString(plain), utf8.RuneCountInString(text))
var heads []string
for _, l := range strings.Split(text, "\n") {
if strings.HasPrefix(l, "## ") {
heads = append(heads, l)
}
}
fmt.Println(strings.Join(heads, " "))
```
**输出**
```text
3389 20767
## 基本信息 ## 十二宫总览 ## 格局 ## 十二宫 ## 四化释义
```
两份文本的 `## ` 节只差末尾的「四化释义」：释义不另起节，而是插在各宫与格局之后。
**边界与陷阱**
`BuiltinKnowledge()` 用在没有内嵌包的语言（目前只有 zh-CN 有）的盘上返回 `ErrInvalidArgument`，
不会静默退回无释义；英文盘用 `KnowledgeFrom(pack)` 显式给包。
***
## 与 JSON 的关系 [#与-json-的关系]
`Astrolabe` 及其下的所有类型都带 `json` 标签，标签名与 JS iztro 的字段契约一致。
因此 `json.Marshal(chart)` 直接就是可以交给前端或别的进程的 DTO：
```go
b, err := json.Marshal(chart)
if err != nil {
log.Fatal(err)
}
var v map[string]any
_ = json.Unmarshal(b, &v)
fmt.Println(v["solarDate"], v["genderKey"], v["timeIndex"])
fmt.Println(v["palaces"].([]any)[4].(map[string]any)["nameKey"])
```
**输出**
```text
2000-8-16 female 2
soulPalace
```
`Config` 里的自定义四化与亮度表不进 JSON——它们是排盘**输入**而非结果，
回显会破坏与 JS iztro 的字段契约。
# 宫位对象 (/zh/docs/go/palace)
Palace 的字段，以及星耀判断、空宫判断与飞星族的全部方法。
宫位是斗数分析的主战场。`chart.Palace(...)` 返回 `*Palace`，
它既持有本宫数据，也能回溯所属星盘、对宫与三方四正。
```go
soul := chart.Palace(iztro.PalaceSoul)
```
本页示例统一用 `"zh-CN"` 排盘，因此输出里的展示值都是中文。
`*Palace` 上的方法都做了 nil 接收者判断，对 `nil` 调用返回零值而不 panic；
但**取字段**仍会 panic，判空还是要做。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| ------------------------------------ | ----------- | --------------------------- |
| `Index` | `int` | 宫位索引 0–11，0 为寅宫 |
| `Name` / `NameKey` | `string` | 宫名译名 / 标识 |
| `IsBodyPalace` | `bool` | 是否身宫 |
| `IsOriginalPalace` | `bool` | 是否来因宫（宫干与年干相同且不在子丑二宫） |
| `HeavenlyStem` / `HeavenlyStemKey` | `string` | 宫干，决定本宫飞出的四化 |
| `EarthlyBranch` / `EarthlyBranchKey` | `string` | 宫支，由索引固定：0 为寅、11 为丑 |
| `MajorStars` | `[]Star` | 十四主星中落在本宫的，按安放顺序 |
| `MinorStars` | `[]Star` | 十四辅星中落在本宫的 |
| `AdjectiveStars` | `[]Star` | 杂耀 |
| `Changsheng12` / `Changsheng12Key` | `string` | 长生十二神，每宫恰好一个 |
| `Boshi12` / `Boshi12Key` | `string` | 博士十二神 |
| `Jiangqian12` / `Jiangqian12Key` | `string` | 将前十二神 |
| `Suiqian12` / `Suiqian12Key` | `string` | 岁前十二神 |
| `Decadal` | `Decadal` | 大限：岁数区间与宫干支 |
| `Ages` | `[]int` | 小限经过本宫的虚岁列表 |
| `MutagenStarKeys` | `[4]string` | 本宫**宫干**化出的四颗星标识，顺序为禄、权、科、忌 |
主星、辅星、杂耀是**切片**，一宫可以有零到多颗。
长生、博士、将前、岁前十二神是**每宫恰好一个**的标记，十二宫刚好排满一轮，
因此是单值字段而不是切片。
它由**排盘时生效的**四化表算得——自定义四化表（`Config.Mutagens`）会反映在这里，
飞星族方法读的正是它。生年四化是打在星耀自身 `MutagenKey` 字段上的标记，
两者不是一回事。
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.HeavenlyStem, soul.MutagenStarKeys)
```
**输出**
```text
壬 [tianliangMaj ziweiMaj zuofuMin wuquMaj]
```
***
## Has / NotHave / HasOneOf [#has--nothave--hasoneof]
**用途** 判断本宫坐了哪些星。
**斗数含义** 星耀落宫是斗数的基本盘面信息。「命宫坐紫微天相」即
`Has(StarZiweiMaj, StarTianxiangMaj)`。查找范围覆盖主星、辅星、杂耀三组。
**签名**
```go
func (p *Palace) Has(stars ...string) bool
func (p *Palace) NotHave(stars ...string) bool
func (p *Palace) HasOneOf(stars ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----------- | -- | -- | --------- |
| `stars` | `...string` | 是 | — | 星耀标识，可变参数 |
**返回值**
| 方法 | 语义 |
| ---------- | ---------- |
| `Has` | 列出的每一颗都在本宫 |
| `NotHave` | 列出的一颗都不在本宫 |
| `HasOneOf` | 列出的至少一颗在本宫 |
**示例**
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.Has(iztro.StarZiweiMaj, iztro.StarTianxiangMaj))
fmt.Println(soul.HasOneOf(iztro.StarQishaMaj, iztro.StarZiweiMaj))
fmt.Println(soul.NotHave(iztro.StarHuoxingMin, iztro.StarLingxingMin))
```
**输出**
```text
false
true
true
```
这张盘的命宫只坐紫微，天相落在财帛宫，因此要求两颗都在的 `Has` 为假。
**边界与陷阱**
`Has` 与 `NotHave` 返回 `true`，`HasOneOf` 返回 `false`。
比对的是「本宫全部星耀的标识与译名」这个集合，比不中就是没有——
`soul.Has("ziweiMj")` 返回 `false` 而不报错，与「命宫没有紫微」无法区分。
用包里的 `Star*` 常量可以让编译器与 IDE 在写错的当场挡下。
`Has` 一族同时比对 `Key` 与 `Name`，因此中文盘上 `soul.Has("紫微")` 也成立。
但这样写换语言就失效——判断请一律用标识。
***
## HasMutagen / NotHaveMutagen [#hasmutagen--nothavemutagen]
**用途** 判断本宫有没有某种四化。
**斗数含义** 本命四化由**生年干**决定，标记打在对应的星上。
一宫「有化禄」意味着这宫里坐着的某颗星被生年干化了禄。
注意这与飞星不同——飞星看的是宫干，本处看的是星上已有的标记。
**签名**
```go
func (p *Palace) HasMutagen(mutagenKey string) bool
func (p *Palace) NotHaveMutagen(mutagenKey string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | -------- | -- | -- | ------------------------------------------------------- |
| `mutagenKey` | `string` | 是 | — | `MutagenLu` / `MutagenQuan` / `MutagenKe` / `MutagenJi` |
**返回值** `bool`。
**示例**
```go
children := chart.Palace(iztro.PalaceChildren)
fmt.Println("子女宫有化禄:", children.HasMutagen(iztro.MutagenLu))
fmt.Println("子女宫无化忌:", children.NotHaveMutagen(iztro.MutagenJi))
```
**输出**
```text
子女宫有化禄: true
子女宫无化忌: true
```
**边界与陷阱**
`HasMutagen` 只看 `MajorStars` 与 `MinorStars` 上的四化标记，杂耀即使带标记也不计入
（复刻 iztro 的行为）。生年四化只会落在十四主星与部分辅星上，
因此实际盘面上两种口径通常没有差别。
***
## IsEmpty [#isempty]
**用途** 判断本宫是否空宫。
**斗数含义** 「空宫」指没有十四主星坐守的宫。空宫要借对宫主星来看，
是斗数里一个很常见的判断分支。辅星与杂耀默认不影响空宫的成立。
**签名**
```go
func (p *Palace) IsEmpty(excludeStars ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------------- | ----------- | -- | -- | ---------------------------------- |
| `excludeStars` | `...string` | 否 | — | 追加计入的星耀：本宫无主星、但坐了其中任一颗时，同样**不算**空宫 |
**返回值** `bool`。判定顺序是：先看有无主星，有则不空；再看 `excludeStars`，命中则不空；都不满足才是空宫。
**示例**
```go
parents := chart.Palace(iztro.PalaceParents)
fmt.Println("父母宫空宫:", parents.IsEmpty())
fmt.Println("仆役宫空宫:", chart.Palace(iztro.PalaceFriends).IsEmpty())
// 父母宫无主星，但坐了陀罗——把陀罗也计入后就不算空宫
fmt.Println("父母宫计入陀罗:", parents.IsEmpty(iztro.StarTuoluoMin))
```
**输出**
```text
父母宫空宫: true
仆役宫空宫: false
父母宫计入陀罗: false
```
这张盘只有父母、田宅两宫无主星。仆役宫坐太阴，因此不算空宫。
**边界与陷阱**
`excludeStars` 不是「判断时忽略这些星」，而是「这些星也算数」。
本宫已有主星时它完全不起作用——有主星就直接不是空宫，不再看这个列表。
不传 `excludeStars` 时只检查 `MajorStars`。一宫辅星杂耀满座但没有主星，仍然是空宫。
***
## FliesTo / FliesOneOfTo / NotFlyTo [#fliesto--fliesoneofto--notflyto]
**用途** 判断本宫宫干的四化是否飞入目标宫。
**斗数含义** 飞星派的核心手法。每个宫位有自己的宫干，宫干按四化表决定
哪四颗星化禄、权、科、忌。若被化的那颗星恰好坐在目标宫，就叫「本宫化 X 入目标宫」。
「命宫化禄入财帛」表达的是命宫这件事的顺遂落在财帛上。
**签名**
```go
func (p *Palace) FliesTo(to *Palace, mutagenKeys ...string) bool
func (p *Palace) FliesOneOfTo(to *Palace, mutagenKeys ...string) bool
func (p *Palace) NotFlyTo(to *Palace, mutagenKeys ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ----------- | -- | -- | ------ |
| `to` | `*Palace` | 是 | — | 目标宫对象 |
| `mutagenKeys` | `...string` | 是 | — | 要检查的四化 |
**返回值**
| 方法 | 语义 |
| -------------- | ------------------ |
| `FliesTo` | 列出的四化**全部**飞入目标宫 |
| `FliesOneOfTo` | 列出的四化**至少一个**飞入目标宫 |
| `NotFlyTo` | 列出的四化**一个都不**飞入目标宫 |
**示例**
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println("命宫化禄入财帛:",
soul.FliesTo(chart.Palace(iztro.PalaceWealth), iztro.MutagenLu))
fmt.Println("命宫化禄或忌入迁移:",
soul.FliesOneOfTo(chart.Palace(iztro.PalaceSurface), iztro.MutagenLu, iztro.MutagenJi))
fmt.Println("命宫不化权入子女:",
soul.NotFlyTo(chart.Palace(iztro.PalaceChildren), iztro.MutagenQuan))
```
**输出**
```text
命宫化禄入财帛: false
命宫化禄或忌入迁移: false
命宫不化权入子女: true
```
**边界与陷阱**
Go 侧目标宫是 `*Palace` 而非字符串——先用 `chart.Palace(...)` 取出来再传。
传 `nil` 时三个方法都返回 `false`。
不传四化（或传空切片）时 `FliesTo` 返回 `false`，
`FliesOneOfTo` 与 `NotFlyTo` 返回 `true`。
这与「空集上全称命题为真」的直觉相反，但复刻的是 iztro 的行为：
`FliesTo` 先算出要找的星，一颗都没有就直接判假。
`Config.Mutagens` 换掉某个天干的四化表后，宫干落在该天干的宫飞出的星随之改变。
飞星族方法读的是排盘时生效的表，不是内置默认表。
***
## SelfMutaged / SelfMutagedOneOf / NotSelfMutaged [#selfmutaged--selfmutagedoneof--notselfmutaged]
**用途** 判断本宫是否自化。
**斗数含义** 自化指本宫宫干化出的星恰好就坐在本宫。
含义上是「自己把自己的能量释放掉」，与飞入他宫的定向作用不同。
**签名**
```go
func (p *Palace) SelfMutaged(mutagenKeys ...string) bool
func (p *Palace) SelfMutagedOneOf(mutagenKeys ...string) bool
func (p *Palace) NotSelfMutaged(mutagenKeys ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ----------- | -- | -- | ----------------------- |
| `mutagenKeys` | `...string` | 否 | — | 要检查的四化；后两个方法不传时表示「四化全部」 |
**返回值**
| 方法 | 语义 |
| ------------------ | --------------------- |
| `SelfMutaged` | 列出的四化全部自化 |
| `SelfMutagedOneOf` | 列出的四化至少一个自化；不传时检查全部四化 |
| `NotSelfMutaged` | 列出的四化一个都不自化；不传时检查全部四化 |
**示例**
```go
career := chart.Palace(iztro.PalaceCareer)
fmt.Println("官禄宫自化禄:", career.SelfMutaged(iztro.MutagenLu))
fmt.Println("官禄宫自化忌:", career.SelfMutaged(iztro.MutagenJi))
fmt.Println("官禄宫有任一自化:", career.SelfMutagedOneOf())
fmt.Println("官禄宫无任何自化:", career.NotSelfMutaged())
```
**输出**
```text
官禄宫自化禄: false
官禄宫自化忌: true
官禄宫有任一自化: true
官禄宫无任何自化: false
```
官禄宫宫干为丙，丙干化忌在廉贞，而廉贞正坐官禄宫，故成自化忌。
***
## MutagedPlaces / MutagenStars [#mutagedplaces--mutagenstars]
**用途** 取本宫宫干化出的四颗星分别落在哪些宫，或直接取那四颗星本身。
**斗数含义** 飞星分析的全景版本：不问「有没有飞到某宫」，而是一次拿到禄权科忌的落点。
**签名**
```go
func (p *Palace) MutagedPlaces() []*Palace
func (p *Palace) MutagenStars(mutagenKeys ...string) []string
```
**返回值** `MutagedPlaces` 返回长度为 4 的切片，顺序为**禄、权、科、忌**，
某颗被化的星不在盘上时对应位置为 `nil`。
`MutagenStars` 返回星耀标识切片，顺序与传入的四化一致。
**示例**
```go
soul := chart.Palace(iztro.PalaceSoul)
for i, m := range []string{"禄", "权", "科", "忌"} {
if place := soul.MutagedPlaces()[i]; place != nil {
fmt.Printf("化%s → %s\n", m, place.Name)
} else {
fmt.Printf("化%s → 不在盘上\n", m)
}
}
fmt.Println(soul.MutagenStars(iztro.MutagenLu, iztro.MutagenJi))
```
**输出**
```text
化禄 → 子女
化权 → 命宫
化科 → 官禄
化忌 → 财帛
[tianliangMaj wuquMaj]
```
命宫宫干为壬，壬干四化为天梁化禄、紫微化权、左辅化科、武曲化忌。
***
## OppositePalace / SurroundedPalaces / Astrolabe [#oppositepalace--surroundedpalaces--astrolabe]
**用途** 从宫位回溯到对宫、三方四正与所属星盘。
**签名**
```go
func (p *Palace) OppositePalace() *Palace
func (p *Palace) SurroundedPalaces() *SurroundedPalaces
func (p *Palace) Astrolabe() *Astrolabe
```
**返回值** 脱离星盘单独构造的宫位返回 `nil`；由星盘查询得到的宫位必然非空。
**示例**
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.Name, "的对宫是", soul.OppositePalace().Name)
fmt.Println("三方四正见煞:",
soul.SurroundedPalaces().HaveOneOf(iztro.StarHuoxingMin, iztro.StarLingxingMin))
fmt.Println(soul.Astrolabe().FiveElementsClass)
```
**输出**
```text
命宫 的对宫是 迁移
三方四正见煞: true
木三局
```
***
## 语义化文本 [#语义化文本]
单宫文本不在 `*Palace` 上，而是星盘方法
[`PalaceToText`](/zh/docs/go/astrolabe#totext--palacetotext--surroundedpalacestotext)：
Go 侧的宫位对象是纯数据，文本投影从星盘的排盘上下文无状态再发起计算。
```go
text, _ := chart.PalaceToText(iztro.PalaceTarget{Index: p.Index})
withNotes, _ := chart.PalaceToTextWith(iztro.PalaceTarget{Index: p.Index},
iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()})
fmt.Println(strings.Split(text, "\n")[0])
fmt.Println(utf8.RuneCountInString(text), utf8.RuneCountInString(withNotes))
```
**输出**（命宫）
```text
### 命宫 (壬午) · 大限 3-12
222 1141
```
单宫文本就是本命文本「十二宫」节里该宫的段落；`PalaceToTextWith` 在事实行之后紧跟该宫每颗星的释义，
`opts` 见 [TextOptions](/zh/docs/go/knowledge#textoptions)。
# 星耀对象 (/zh/docs/go/star-object)
Star 的字段与亮度、四化判断，以及回溯所在宫的能力。
`Star` 是一颗落在某宫的星，带着它的类型、亮度与四化标记，并能回溯所在宫。
```go
ziwei, palace := chart.Star(iztro.StarZiweiMaj)
```
本页示例统一用 `"zh-CN"` 排盘，因此输出里的展示值都是中文。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| --------------- | -------- | ------------------------------ |
| `Key` | `string` | 星耀标识，与语言无关，判断时用它 |
| `Name` | `string` | 星名，按排盘语言翻译 |
| `Type` | `string` | 星耀类型，见下表 |
| `Scope` | `string` | 作用范围：本命星为 `"origin"`，流耀为对应运限层级 |
| `Brightness` | `string` | 亮度译名；没有亮度表的星耀为空串 |
| `BrightnessKey` | `string` | 亮度标识 |
| `Mutagen` | `string` | 生年四化译名；未被生年干化的星为空串 |
| `MutagenKey` | `string` | 四化标识 |
### 星耀类型的八个取值 [#星耀类型的八个取值]
| 取值 | 含义 | 典型成员 |
| ----------- | ---- | ----------------- |
| `major` | 十四主星 | 紫微、天府、七杀、破军 |
| `soft` | 吉星 | 左辅、右弼、文昌、文曲、天魁、天钺 |
| `tough` | 煞星 | 擎羊、陀罗、火星、铃星、地空、地劫 |
| `adjective` | 杂耀 | 三台、八座、天刑、天姚 |
| `flower` | 桃花星 | 红鸾、天喜、咸池 |
| `helper` | 解神 | 解神 |
| `lucun` | 禄存 | 禄存 |
| `tianma` | 天马 | 天马 |
禄存与天马各自独占一类，因为它们在传统分法里既非纯吉也非纯煞，判断时常单独拎出来。
Go 侧用空串表示「没有」——`Brightness` 为空串即该星没有亮度表，
`Mutagen` 为空串即未被生年干化。判空写 `if star.MutagenKey != ""`。
***
## WithBrightness [#withbrightness]
**用途** 判断这颗星是否处于给定亮度之一。
**斗数含义** 亮度（庙旺得利平不陷）描述星耀在该宫位的强弱。
同一颗星在十二宫各有定值，庙旺则力量充分发挥，落陷则受制。
**签名**
```go
func (s *Star) WithBrightness(brightnessKeys ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------------- | ----------- | -- | -- | ------------ |
| `brightnessKeys` | `...string` | 是 | — | 亮度标识，命中任一即为真 |
**返回值** `bool`。该星无亮度时恒为假。
**示例**
```go
ziwei, _ := chart.Star(iztro.StarZiweiMaj)
fmt.Println(ziwei.WithBrightness(iztro.BrightnessMiao))
fmt.Println(ziwei.WithBrightness(iztro.BrightnessWang, iztro.BrightnessDe))
```
**输出**
```text
true
false
```
**边界与陷阱**
语义是「命中任一」而非「全部命中」——一颗星只有一个亮度，
传多个只表示「是其中之一即可」。
***
## WithMutagen [#withmutagen]
**用途** 判断这颗星是否带指定的生年四化。
**斗数含义** 生年四化由出生年干决定，一年固定四颗星分别化禄、权、科、忌。
这个标记跟着星走，无论那颗星落在哪一宫。
**签名**
```go
func (s *Star) WithMutagen(mutagenKeys ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | ----------- | -- | -- | ------------ |
| `mutagenKeys` | `...string` | 是 | — | 四化标识，命中任一即为真 |
**返回值** `bool`。该星未被生年干化时恒为假。
**示例**
```go
ziwei, _ := chart.Star(iztro.StarZiweiMaj)
taiyang, _ := chart.Star(iztro.StarTaiyangMaj)
fmt.Println("紫微化禄:", ziwei.WithMutagen(iztro.MutagenLu))
fmt.Println("太阳化禄:", taiyang.WithMutagen(iztro.MutagenLu))
```
**输出**
```text
紫微化禄: false
太阳化禄: true
```
这张盘生年干为庚，庚干太阳化禄，因此标记落在太阳而非紫微。
**边界与陷阱**
`WithMutagen` 看的是**生年干**给这颗星打的标记，一张盘上只有四颗星带标记。
宫干飞出的四化不在这里体现，用宫位的 [`FliesTo`](/zh/docs/go/palace#fliesto--fliesoneofto--notflyto) 一族。
***
## Palace / OppositePalace / SurroundedPalaces [#palace--oppositepalace--surroundedpalaces]
**用途** 从星回溯到它所在的宫、该宫的对宫与三方四正。
**签名**
```go
func (s *Star) Palace() *Palace
func (s *Star) OppositePalace() *Palace
func (s *Star) SurroundedPalaces() *SurroundedPalaces
```
**返回值** 脱离星盘单独构造的星耀返回 `nil`；由星盘查询得到的星耀必然非空。
**示例**
```go
ziwei, _ := chart.Star(iztro.StarZiweiMaj)
fmt.Println(ziwei.Palace().Name)
fmt.Println(ziwei.OppositePalace().Name)
fmt.Println("同宫或三方见天相:",
ziwei.SurroundedPalaces().Have(iztro.StarTianxiangMaj))
```
**输出**
```text
命宫
迁移
同宫或三方见天相: true
```
**边界与陷阱**
`chart.Star()` 已经把所在宫作为第二个返回值给出，
通常不必再调 `ziwei.Palace()`。
# 三方四正 (/zh/docs/go/surpalaces)
SurroundedPalaces 的四个宫位与五个判断方法。
三方四正是斗数最常用的取象范围。看一件事不能只看本宫，
对宫与两个三合宫的星耀同样作用其上，四宫合看才完整。
本页示例统一用 `"zh-CN"` 排盘，因此输出里的展示值都是中文。
## 四个宫位 [#四个宫位]
| 字段 | 相对本宫 | 传统称呼 | 意义 |
| ---------- | ---- | ---- | -------------- |
| `Target` | +0 | 本宫 | 事情本身 |
| `Opposite` | +6 | 对宫 | 与本宫相对的一面，影响最直接 |
| `Career` | +4 | 官禄位 | 三合之一 |
| `Wealth` | +8 | 财帛位 | 三合之一 |
四个字段都是 `*Palace`，[宫位对象](/zh/docs/go/palace)的全部方法都能用。
`Wealth` 与 `Career` 指的是「相对本宫的三合位置」，不是十二宫里那两个固定的宫名。
以命宫起算时它们恰好落在财帛宫与官禄宫（+8 与 +4），名字就是这么对上的；
以别的宫起算则是别的宫。
## 四种取法 [#四种取法]
```go
// 从星盘按宫名取
byName := chart.SurroundedPalaces(iztro.PalaceSoul)
// 从星盘按索引取
byIndex := chart.SurroundedPalacesByIndex(4)
// 从宫位取
fromPalace := chart.Palace(iztro.PalaceSoul).SurroundedPalaces()
// 从星耀取（该星所在宫的三方四正）
ziwei, _ := chart.Star(iztro.StarZiweiMaj)
fromStar := ziwei.SurroundedPalaces()
fmt.Println(byName.Target.Name, byIndex.Target.Name,
fromPalace.Target.Name, fromStar.Target.Name)
```
**输出**
```text
命宫 命宫 命宫 命宫
```
命宫落在索引 4、紫微又正坐命宫，因此四种取法在这张盘上给出同一组三方四正；
选哪个取决于手上已有什么。
`SurroundedPalacesByIndex` 对索引取模，因此 `-1`、`12` 都能正确回绕；
但**零值星盘**（未经排盘构造出来的 `Astrolabe`）没有十二宫，此时返回 `nil`。
`SurroundedPalaces` 收名字，拼错返回 `nil`。两者都要判空再取字段。
***
## Have / NotHave / HaveOneOf [#have--nothave--haveoneof]
**用途** 判断四宫合起来有没有指定星耀。
**斗数含义** 「三方四正见紫微」这类说法，问的正是这四宫里出没出现某颗星，
而不问具体落在其中哪一宫。
**签名**
```go
func (sp *SurroundedPalaces) Have(stars ...string) bool
func (sp *SurroundedPalaces) NotHave(stars ...string) bool
func (sp *SurroundedPalaces) HaveOneOf(stars ...string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----------- | -- | -- | --------- |
| `stars` | `...string` | 是 | — | 星耀标识，可变参数 |
**返回值**
| 方法 | 语义 |
| ----------- | -------------------- |
| `Have` | 列出的每一颗都出现在这四宫（不要求同宫） |
| `NotHave` | 列出的一颗都没出现 |
| `HaveOneOf` | 列出的至少一颗出现 |
**示例**
```go
sp := chart.SurroundedPalaces(iztro.PalaceSoul)
fmt.Println(sp.Have(iztro.StarZiweiMaj, iztro.StarTianxiangMaj))
fmt.Println(sp.HaveOneOf(iztro.StarQishaMaj, iztro.StarPojunMaj))
fmt.Println(sp.NotHave(iztro.StarHuoxingMin))
```
**输出**
```text
true
false
true
```
紫微在命宫、天相在财帛宫，分处两宫但都在这四宫内，因此 `Have` 为真。
**边界与陷阱**
`Have(A, B)` 的语义是「A 和 B 都出现在这四宫里」，
不要求它们坐在同一宫。要判断同宫，用宫位的 [`Has`](/zh/docs/go/palace#has--nothave--hasoneof)。
`Have` 与 `NotHave` 返回 `true`，`HaveOneOf` 返回 `false`。
***
## HaveMutagen / NotHaveMutagen [#havemutagen--nothavemutagen]
**用途** 判断四宫里有没有某种生年四化。
**斗数含义** 「三方四正见忌」意味着这组宫位里坐着一颗被生年干化忌的星，
是判断压力来源的常用条件。
**签名**
```go
func (sp *SurroundedPalaces) HaveMutagen(mutagenKey string) bool
func (sp *SurroundedPalaces) NotHaveMutagen(mutagenKey string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | -------- | -- | -- | ------ |
| `mutagenKey` | `string` | 是 | — | 四化标识之一 |
**返回值** `bool`。
**示例**
```go
sp := chart.SurroundedPalaces(iztro.PalaceSoul)
fmt.Println("三方四正见禄:", sp.HaveMutagen(iztro.MutagenLu))
fmt.Println("三方四正见忌:", sp.HaveMutagen(iztro.MutagenJi))
fmt.Println("三方四正不见科:", sp.NotHaveMutagen(iztro.MutagenKe))
```
**输出**
```text
三方四正见禄: false
三方四正见忌: false
三方四正不见科: true
```
这张盘的生年四化落在子女、迁移、疾厄三宫，都不在命宫的三方四正内。
**边界与陷阱**
这里看的是**生年四化**打在星上的标记，与宫干飞出的四化无关。
后者请用宫位的飞星族方法。
***
## 语义化文本 [#语义化文本]
三方四正文本不在 `*SurroundedPalaces` 上，而是星盘方法
[`SurroundedPalacesToText`](/zh/docs/go/astrolabe#totext--palacetotext--surroundedpalacestotext)：
```go
text, _ := chart.SurroundedPalacesToText(iztro.PalaceTarget{Key: iztro.PalaceSoul})
withNotes, _ := chart.SurroundedPalacesToTextWith(iztro.PalaceTarget{Key: iztro.PalaceSoul},
iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()})
fmt.Println(strings.Split(text, "\n")[0])
fmt.Println(utf8.RuneCountInString(text), utf8.RuneCountInString(withNotes))
```
**输出**
```text
## 命宫 三方四正
924 6312
```
文本以 `## 命宫 三方四正` 起，下接本宫、对宫、财帛位、官禄位四段，每段标题带角色前缀
（`### 本宫 · 命宫 (壬午) · 大限 3-12`、`### 对宫 · 迁移 (戊子) · 大限 63-72`），事实行与本命文本里该宫的段落一致；
`SurroundedPalacesToTextWith` 在每宫事实行之后紧跟该宫星耀的释义，
`opts` 见 [TextOptions](/zh/docs/go/knowledge#textoptions)。
# 运限对象 (/zh/docs/go/horoscope)
六个运限层级的数据结构、整层取回的三个列表，以及不必再传星盘的宫位查询方法。
运限把本命盘投影到某个时间点上。同一张盘，不同年份看到的宫位分布不同——
这正是「大限走到哪一宫」的意思。
```go
h, _ := chart.Horoscope("2025-6-1", 0)
```
`Horoscope` 持有发起它的那张本命盘，因此所有查询方法都不必再把星盘传进去。
本页示例统一用 `"zh-CN"` 的本命盘，因此输出里的展示值都是中文。
## 字段 [#字段]
| 字段 | 类型 | 跨度 | 说明 |
| ------------------------- | ---------------- | --- | ----------------------------------------------------------- |
| `SolarDate` / `LunarDate` | `string` | — | **目标**日期的公历串与农历中文写法。出生日期在本命盘上，用 `h.Astrolabe().SolarDate` 取 |
| `Decadal` | `HoroscopeScope` | 十年 | 大限。未起运的幼年期为童限 |
| `Age` | `HoroscopeScope` | 一年 | 小限。按虚岁逐年走一宫 |
| `Yearly` | `HoroscopeScope` | 一年 | 流年。按流年干支定宫 |
| `Monthly` | `HoroscopeScope` | 一月 | 流月 |
| `Daily` | `HoroscopeScope` | 一日 | 流日 |
| `Hourly` | `HoroscopeScope` | 一时辰 | 流时 |
两者都是一年一走，但起法不同：小限从生年地支起、按虚岁顺推，
流年直接看那一年的干支落在哪一宫。两条线互相独立，斗数里通常并看。
### HoroscopeScope [#horoscopescope]
| 字段 | 类型 | 说明 |
| ------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- |
| `Index` | `int` | 该层级落在哪一宫（宫位索引） |
| `Name` | `string` | 层级显示名，按输出语言翻译 |
| `NameKey` | `string` | 层级标识：`decadal` / `childhood`（童限，未起运）/ `turn`（小限）/ `yearly` / `monthly` / `daily` / `hourly`。判断层级用它，不要比对译文 |
| `HeavenlyStem` / `HeavenlyStemKey` | `string` | 该层级的天干，决定它飞出的四化 |
| `EarthlyBranch` / `EarthlyBranchKey` | `string` | 该层级的地支 |
| `PalaceNames` / `PalaceNameKeys` | `[]string` | 以该层级所在宫为命宫重推的十二宫名，按宫位索引排列 |
| `Mutagen` / `MutagenStarKeys` | `[]string` | 该层级天干引发的四化星，顺序为禄权科忌；`MutagenStarKeys` 是被化四星的星耀标识，与宫位的同名字段同义 |
| `Stars` | `[][]Star` | 该层级的流耀分布；无流耀的层级为 `nil` |
| `NominalAge` | `int` | 仅小限：虚岁。其余层级为 `0` |
| `YearlyDecStar` | `*YearlyDecStar` | 仅流年：岁前与将前十二神。其余层级为 **`nil`** |
```go
type YearlyDecStar struct {
Suiqian12 []string `json:"suiqian12"` // 岁前十二神译名，按宫位索引排列
Suiqian12Keys []string `json:"suiqian12Keys"` // 对应标识
Jiangqian12 []string `json:"jiangqian12"` // 将前十二神译名
Jiangqian12Keys []string `json:"jiangqian12Keys"` // 对应标识
}
```
Go 侧不为小限与流年各开一个类型，而是把 `NominalAge` 与 `YearlyDecStar`
放进共用的 `HoroscopeScope`——其余层级上这两项为零值。
调用处因此可以写按层级参数化的通用逻辑。
`h.Decadal.YearlyDecStar` 是 `nil`，直接取字段会 panic。
只有 `h.Yearly.YearlyDecStar` 非空——按层级遍历时先判空。
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println(h.Decadal.YearlyDecStar == nil, h.Yearly.YearlyDecStar != nil)
fmt.Println(h.Yearly.YearlyDecStar.Suiqian12[:3])
fmt.Println(h.Yearly.YearlyDecStar.Jiangqian12Keys[:3])
fmt.Println(h.Decadal.NominalAge, h.Age.NominalAge)
```
**输出**
```text
true true
[天德 吊客 病符]
[jiesha zhaisha tiansha]
0 26
```
### PalaceIndexByName [#palaceindexbyname]
```go
func (item *HoroscopeScope) PalaceIndexByName(nameKeyOrName string) int
```
在该层级重排后的十二宫里，按宫名标识或当前语言宫名查宫位索引；**找不到返回 -1**。
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println(h.Decadal.PalaceIndexByName(iztro.PalaceSoul))
fmt.Println(h.Decadal.PalaceIndexByName(iztro.PalaceWealth))
fmt.Println(h.Decadal.PalaceIndexByName("nosuch"))
```
**输出**
```text
2
10
-1
```
返回 `-1` 而不是 `0`——`0` 是合法的宫位索引（寅宫）。
拿它去索引 `chart.Palaces` 前务必判负。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
for _, item := range []iztro.HoroscopeScope{h.Decadal, h.Monthly, h.Daily, h.Hourly} {
fmt.Printf("%s 落在宫位 %d 干支 %s%s\n",
item.Name, item.Index, item.HeavenlyStem, item.EarthlyBranch)
}
fmt.Println("小限虚岁", h.Age.NominalAge)
fmt.Println("大限四化", h.Decadal.Mutagen)
fmt.Println("流年岁前十二神", h.Yearly.YearlyDecStar.Suiqian12[:3])
```
**输出**
```text
大限 落在宫位 2 干支 庚辰
流月 落在宫位 3 干支 壬午
流日 落在宫位 8 干支 辛丑
流时 落在宫位 8 干支 戊子
小限虚岁 26
大限四化 [太阳 武曲 太阴 天同]
流年岁前十二神 [天德 吊客 病符]
```
***
## 三个列表 [#三个列表]
`DecadalList` / `YearlyList` / `MonthlyList` 是 `*Astrolabe` 上的方法，不在运限对象上：
它们一次取回整层的运限项，省去按日期逐个调 `Horoscope` 再自己拼。
三种列表项都内嵌 `HoroscopeScope`，通用字段直接访问，各自多带该层的时间坐标：
| 类型 | 多出的字段 | 说明 |
| ----------------- | ---------------------------------------- | ------------------------------- |
| `DecadalListItem` | `PalaceName` / `PalaceNameKey`: `string` | 该大限所在的本命宫名 |
| | `AgeRange`: `[2]int` | 起止虚岁，含两端 |
| | `YearRange`: `[2]int` | 起止农历年份，含两端 |
| `YearlyListItem` | `Age`: `int` | 该流年对应的虚岁 |
| | `Year`: `int` | 农历年份 |
| `MonthlyListItem` | `Age`: `int` | 该流月对应的虚岁 |
| | `Year`: `int` | 农历年份 |
| | `Month`: `int` | 农历月份，正月为 1；闰月与同号常规月的 `Month` 相同 |
| | `IsLeapMonth`: `bool` | 该项是否闰月 |
| | `Part`: `string` | 分段标识，取 `MonthPart*` 常量 |
| | `DayRange`: `[2]int` | 该段覆盖的农历日，含两端 |
`MonthPart*` 三个常量：`MonthPartNormal` 整月一段、`MonthPartFirst` 闰月前半、
`MonthPartSecond` 闰月后半。
三个方法都各有一个 `*Context` 变体，`ctx` 用于取消等待 wasm 实例。
三个列表的每一项都以**时柱地支**对应的时辰计算，而不是排盘时传入的时辰索引。
两者只在晚子时不同：入参 12 的盘，时柱地支是子，列表按时辰 0 起运限。
***
## DecadalList [#decadallist]
**用途** 一次取回本盘十二个大限，按起运先后排列。
**斗数含义** 大限十年一步，从起限宫顺逆行走十二宫。
把整条线摊平看，才知道某一段人生落在哪一宫、对应哪十年。
**签名**
```go
func (a *Astrolabe) DecadalList() ([]DecadalListItem, error)
func (a *Astrolabe) DecadalListContext(ctx context.Context) ([]DecadalListItem, error)
```
**返回值** 定长 12 项，第 0 项是第一个大限。顺序按起运虚岁排，
与宫位索引顺序无关（大限顺行逆行取决于阴阳男女）。
**示例**
```go
dl, _ := chart.DecadalList()
for _, d := range dl[:3] {
fmt.Println(d.PalaceName, d.HeavenlyStem, d.EarthlyBranch, d.AgeRange, d.YearRange)
}
fmt.Println(len(dl))
```
**输出**
```text
命宫 壬 午 [3 12] [2002 2011]
兄弟 辛 巳 [13 22] [2012 2021]
夫妻 庚 辰 [23 32] [2022 2031]
12
```
这张盘三岁起运，第一个大限落在命宫。
**边界与陷阱**
起运之前的那几年是童限，只有按具体日期查 `Horoscope` 才会出现（`NameKey` 为 `childhood`）。
`DecadalList` 列的是十二个大限本身，每项的 `NameKey` 恒为 `decadal`。
***
## YearlyList / YearlyListByPalace [#yearlylist--yearlylistbypalace]
**用途** 取一个大限内的全部流年。
**斗数含义** 定了大限再逐年细看，是斗数常规的推运顺序。
一个大限十年，对应的就是这十个流年。
**签名**
```go
func (a *Astrolabe) YearlyList(ordinal int) ([]YearlyListItem, error)
func (a *Astrolabe) YearlyListByPalace(nameKey string) ([]YearlyListItem, error)
```
两者各有一个 `*Context` 变体。
**参数**
| 方法 | 参数 | 类型 | 说明 |
| -------------------- | --------- | -------- | ------------------------------------------ |
| `YearlyList` | `ordinal` | `int` | 大限序号，0 为第一个大限；越界返回错误 |
| `YearlyListByPalace` | `nameKey` | `string` | 该大限所在的本命宫名标识（`PalaceSoul` 等常量）；空串或未知标识返回错误 |
两种写法定位到同一个大限时结果完全相同，选哪个取决于手上已有什么。
**返回值** 10 项，按虚岁先后排列。
**示例**
```go
years, _ := chart.YearlyList(2)
for _, y := range years[:3] {
fmt.Println(y.Age, y.Year, y.HeavenlyStem, y.EarthlyBranch, "->", y.Index)
}
byPalace, _ := chart.YearlyListByPalace(iztro.PalaceSpouse)
fmt.Println(len(years), len(byPalace))
```
**输出**
```text
23 2022 壬 寅 -> 0
24 2023 癸 卯 -> 1
25 2024 甲 辰 -> 2
10 10
```
第 2 个大限落在夫妻宫，因此这两次调用问的是同一个大限。
**边界与陷阱**
`YearlyListByPalace("")` 返回错误而不是退回某个默认大限——静默取一个默认值会把漏传
变成看起来成功的错答案。
***
## MonthlyList [#monthlylist]
**用途** 取一个农历年的全部流月。
**斗数含义** 流月是流年之下的一层，逐月推移。闰月怎么算是一个流派分歧点，
因此拆不拆由调用方定。
**签名**
```go
func (a *Astrolabe) MonthlyList(lunarYear int, fixLeap *bool) ([]MonthlyListItem, error)
func (a *Astrolabe) MonthlyListContext(ctx context.Context, lunarYear int, fixLeap *bool) ([]MonthlyListItem, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ------- | -- | -------------- | ------------------------------------- |
| `lunarYear` | `int` | 是 | — | 农历年份 |
| `fixLeap` | `*bool` | 是 | `nil` 即内核默认（真） | 闰月是否拆成前后半月两项；用 `iztro.Bool(false)` 关掉 |
**返回值** 长度取决于该年有无闰月与 `fixLeap`：
| 该农历年 | `fixLeap` | 项数 | 闰月怎么排 |
| ---- | -------------------- | -- | -------------------------------------------------------- |
| 无闰月 | 任意 | 12 | — |
| 有闰月 | `nil` 或 `Bool(true)` | 14 | 闰月拆成 `MonthPartFirst`（初一至十五）与 `MonthPartSecond`（十六至月末）两项 |
| 有闰月 | `Bool(false)` | 13 | 闰月整月一项，`Part` 为 `MonthPartNormal` |
闰月排在同月号的常规月之后。每项按该段首日算出（后半段取十六）。
**示例**
```go
months, _ := chart.MonthlyList(2020, nil)
fmt.Println(len(months))
for _, m := range months[3:7] {
fmt.Println(m.Month, m.IsLeapMonth, m.Part, m.DayRange, m.HeavenlyStem, m.EarthlyBranch)
}
whole, _ := chart.MonthlyList(2020, iztro.Bool(false))
plain, _ := chart.MonthlyList(2021, nil)
fmt.Println(len(whole), len(plain))
```
**输出**
```text
14
4 false normal [1 30] 辛 巳
4 true first [1 15] 辛 巳
4 true second [16 29] 壬 午
5 false normal [1 30] 壬 午
13 12
```
农历 2020 年有闰四月。拆开之后，闰四月前半与四月同干支（辛巳），后半跟五月同干支（壬午）
——这正是「闰月下半月算下一个月」的意思。农历 2021 年无闰月，恒为 12 项。
**边界与陷阱**
排盘入口那个 `fixLeap` 决定闰月出生的人下半月按下个月安星，改的是本命盘布局；
这里这个只决定本列表拆不拆闰月。两者可以取不同的值，互不影响。
闰四月的 `Month` 也是 `4`，靠 `IsLeapMonth` 区分。按 `Month` 去重会把闰月弄丢。
***
## AgePalace [#agepalace]
**用途** 取小限当年所在的宫。
**斗数含义** 小限是逐年推移的一条线，落在哪一宫就以那宫为该年重点。
**签名**
```go
func (h *Horoscope) AgePalace() *Palace
```
**返回值** `*Palace`——本命盘上的宫位。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println(h.AgePalace().Name)
```
**输出**
```text
田宅
```
***
## Palace [#palace]
**用途** 取某个运限层级下、按该层级重推的十二宫中的某一宫。
**斗数含义** 大限走到某宫后，以那一宫为「大限命宫」重排十二宫。
「大限的夫妻宫」问的就是这套重排后的宫位，与本命夫妻宫通常不是同一宫。
**签名**
```go
func (h *Horoscope) Palace(nameKeyOrName string, scope string) *Palace
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | -------- | -- | -- | ----------- |
| `nameKeyOrName` | `string` | 是 | — | 要取的宫名标识或译名 |
| `scope` | `string` | 是 | — | 在哪个层级的十二宫里找 |
**返回值** `*Palace`——本命盘上的宫位（同一格宫位在不同层级有不同宫名）。
层级为 `ScopeOrigin` 时即本命十二宫。查不到返回 `nil`。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println("大限命宫落在本命的", h.Palace(iztro.PalaceSoul, iztro.ScopeDecadal).Name)
fmt.Println("本命命宫是", h.Palace(iztro.PalaceSoul, iztro.ScopeOrigin).Name)
```
**输出**
```text
大限命宫落在本命的 夫妻
本命命宫是 命宫
```
**边界与陷阱**
返回的宫位对象上，`Name` 仍是**本命宫名**（例中的夫妻），因为它就是本命盘上的那一格。
要看该格在大限层级叫什么，查 `h.Decadal.PalaceNames[index]`。
***
## SurroundPalaces [#surroundpalaces]
**用途** 取某个运限层级下某宫的三方四正。
**签名**
```go
func (h *Horoscope) SurroundPalaces(nameKeyOrName string, scope string) *SurroundedPalaces
```
**参数** 同 `Palace`。
**返回值** `*SurroundedPalaces`，判断方法见[三方四正](/zh/docs/go/surpalaces)。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
sp := h.SurroundPalaces(iztro.PalaceWealth, iztro.ScopeYearly)
fmt.Println("流年财帛的三方四正以本命", sp.Target.Name, "为本宫")
```
**输出**
```text
流年财帛的三方四正以本命 疾厄 为本宫
```
***
## HasHoroscopeStars / HasOneOfHoroscopeStars / NotHaveHoroscopeStars [#hashoroscopestars--hasoneofhoroscopestars--nothavehoroscopestars]
**用途** 判断某层级某宫里有没有指定的流耀。
**斗数含义** 流耀是随运限层级产生的一组星：魁钺昌曲禄羊陀马鸾喜。
它们在不同层级有不同名字——大限层级叫运魁、运钺，流年层级叫流魁、流钺，
含义相同但作用于各自的时间跨度。
**签名**
```go
func (h *Horoscope) HasHoroscopeStars(nameKeyOrName string, scope string, stars []string) bool
func (h *Horoscope) HasOneOfHoroscopeStars(nameKeyOrName string, scope string, stars []string) bool
func (h *Horoscope) NotHaveHoroscopeStars(nameKeyOrName string, scope string, stars []string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | ---------- | -- | -- | --------------- |
| `nameKeyOrName` | `string` | 是 | — | 该层级下的宫名 |
| `scope` | `string` | 是 | — | 运限层级 |
| `stars` | `[]string` | 是 | — | 流耀标识切片，须用该层级的名字 |
**返回值**
| 方法 | 语义 |
| ------------------------ | ----- |
| `HasHoroscopeStars` | 每一颗都在 |
| `HasOneOfHoroscopeStars` | 至少一颗在 |
| `NotHaveHoroscopeStars` | 一颗都不在 |
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println(h.HasHoroscopeStars(iztro.PalaceSoul, iztro.ScopeDecadal, []string{"yunlu"}))
fmt.Println(h.HasOneOfHoroscopeStars(iztro.PalaceSoul, iztro.ScopeDecadal, []string{"yunlu", "yunyang"}))
fmt.Println(h.NotHaveHoroscopeStars(iztro.PalaceSoul, iztro.ScopeDecadal, []string{"yuntuo"}))
```
**输出**
```text
false
false
true
```
**边界与陷阱**
这三个方法前面已有宫名与层级两个字符串参数，再用可变参数会让调用处产生歧义，
因此星耀参数取 `[]string`。包里其余带星耀列表的方法都是可变参数。
三个方法用 `scope` + 宫名定位到本命盘上的某一格，
但要比对的星耀集合恒为**大限流耀与流年流耀的并集**，与 `scope` 无关。
因此 `scope` 传 `ScopeMonthly` 时，查的是「流月某宫这一格里有没有大限或流年的流耀」，
而不是流月自己的流耀——流月、流日、流时三层的流耀不参与这里的比对。
要按层级取流耀分布，用 `h.Monthly.Stars`，或
[`GetHoroscopeStar`](/zh/docs/go/star#gethoroscopestar)。
大限流耀叫 `StarYunlu`（运禄）、`StarYunyang`（运羊）……，流年流耀叫
`StarLiulu`（流禄）、`StarLiuyang`（流羊）……，两组标识不同名。
由于比对集合恒是这两组的并集，两组标识在任何 `scope` 下都查得到，只是落宫不同。
各层级的标识对照见[安星模块](/zh/docs/go/star#gethoroscopestar)。
***
## HasHoroscopeMutagen [#hashoroscopemutagen]
**用途** 判断某层级某宫里有没有该层级天干引发的四化。
**斗数含义** 每个运限层级有自己的天干，会像生年干一样化出四颗星。
「大限化禄落在大限财帛」这类判断问的就是这个。
**签名**
```go
func (h *Horoscope) HasHoroscopeMutagen(nameKeyOrName string, scope string, mutagenKey string) bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | -------- | -- | -- | ------- |
| `nameKeyOrName` | `string` | 是 | — | 该层级下的宫名 |
| `scope` | `string` | 是 | — | 运限层级 |
| `mutagenKey` | `string` | 是 | — | 四化标识 |
**返回值** `bool`。检查该层级天干化出的那颗星是否落在目标宫的主星或辅星里（不看杂耀）。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println(h.HasHoroscopeMutagen(iztro.PalaceSoul, iztro.ScopeDecadal, iztro.MutagenLu))
fmt.Println(h.Decadal.Mutagen)
```
**输出**
```text
false
[太阳 武曲 太阴 天同]
```
大限干为庚，庚干四化为太阳化禄、武曲化权、太阴化科、天同化忌。
**边界与陷阱**
本命层级没有「层级天干」这回事——生年四化已经打在星耀自身的 `MutagenKey` 上。
`HasHoroscopeMutagen(name, iztro.ScopeOrigin, m)` 因此直接返回 `false`，
不代表本命盘上没有这个四化。要查本命四化，用宫位的
[`HasMutagen`](/zh/docs/go/palace#hasmutagen--nothavemutagen)。
***
## ScopeItem / Astrolabe [#scopeitem--astrolabe]
**用途** 按层级标识取对应的 `HoroscopeScope`，或回到本命盘。
**签名**
```go
func (h *Horoscope) ScopeItem(scope string) *HoroscopeScope
func (h *Horoscope) Astrolabe() *Astrolabe
```
**返回值** `ScopeItem` 在层级为 `ScopeOrigin` 或未知层级时返回 `nil`——本命不是运限层级。
**示例**
```go
h, _ := chart.Horoscope("2025-6-1", 0)
fmt.Println(h.ScopeItem(iztro.ScopeDecadal).Name)
fmt.Println(h.ScopeItem(iztro.ScopeOrigin))
fmt.Println(h.Astrolabe().SolarDate)
```
**输出**
```text
大限
2000-8-16
```
**边界与陷阱**
`ScopeItem` 用于写按层级参数化的通用逻辑，比一串 `switch scope` 简洁。
返回 `nil` 时记得判空。
***
## ToText [#totext]
**用途** 运限的语义化文本：面向语言模型与人的完整描述。
**签名**
```go
func (h *Horoscope) ToText() (string, error)
func (h *Horoscope) ToTextContext(ctx context.Context) (string, error)
```
**返回值** `string`——按星盘排盘语言输出的 Markdown 子集：`# 运限 <日期> (<农历>)` 标题下，
大限（未起运写童限）、小限、流年、流月、流日、流时各一个 `## ` 节，每节带该层命宫落在本命何宫、
四化（带落宫）、流耀与该层视角的格局行；大限与流年另展开十二宫表。
完整格式见[语义化文本](/zh/docs/guide/guides/to-text#五个入口)。
**示例**
```go
h, _ := chart.Horoscope("2025-1-1", 0)
text, _ := h.ToText()
fmt.Println(strings.Join(strings.Split(text, "\n")[:5], "\n"))
```
**输出**
```text
# 运限 2025-1-1 (二〇二四年腊月初二)
## 大限 · 命宫: 本命夫妻 (庚辰)
- 四化: 太阳化禄→本命子女, 武曲化权→本命财帛, 太阴化科→本命仆役, 天同化忌→本命疾厄
- 格局: 杀破狼 (命宫), 风云际会 (命宫)
```
格局命中的文本另见 `PatternsToText`（[格局判定](/zh/docs/go/patterns)）。
***
## ToTextWith [#totextwith]
**用途** `ToText` 的文本，按 `opts` 带上知识包里的释义：每一层的表或事实行之后紧跟该层流耀的释义
与该层视角命中格局的释义，同一颗流耀、同一个格局跨层只释义一次。
本命星耀的释义不在这里，在星盘的 `ToTextWith` 里。
**签名**
```go
func (h *Horoscope) ToTextWith(opts TextOptions) (string, error)
func (h *Horoscope) ToTextWithContext(ctx context.Context, opts TextOptions) (string, error)
```
**参数**
| 参数 | 类型 | 说明 |
| ------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opts` | [`TextOptions`](/zh/docs/go/knowledge#textoptions) | 输出选项。`Knowledge` 字段给释义材料来源：`BuiltinKnowledge()` 取盘语言的内嵌默认包，`KnowledgeFrom(pack)` 用给定的包；`PatternConfig` 字段给各层格局行与格局释义的判定口径；零值 `TextOptions{}` 等同 `ToText` |
释义的插入位置与去重规则见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本)。
**示例**
```go
h, _ := chart.Horoscope("2025-1-1", 0)
plain, _ := h.ToText()
text, _ := h.ToTextWith(iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()})
fmt.Println(utf8.RuneCountInString(plain), utf8.RuneCountInString(text))
for _, l := range strings.Split(text, "\n") {
if strings.HasPrefix(l, "## ") {
fmt.Println(l)
}
}
```
**输出**
```text
2457 8458
## 大限 · 命宫: 本命夫妻 (庚辰)
## 小限 · 命宫: 本命官禄 · 虚岁 25
## 流年 · 命宫: 本命夫妻 (甲辰)
## 流月 · 命宫: 本命仆役 (丁丑)
## 流日 · 命宫: 本命迁移 (庚午)
## 流时 · 命宫: 本命迁移 (丙子)
```
两份文本的 `## ` 节完全相同：释义不另起节，插在各层之后。
`BuiltinKnowledge()` 用在没有内嵌包的语言（目前只有 zh-CN 有）的盘上返回 `ErrInvalidArgument`。
# 格局判定 (/zh/docs/go/patterns)
本命与运限的格局命中、PatternConfig 口径、Pattern 常量与错误处理。
格局是「盘上某几颗星按特定方式凑在一起」的模式识别。判定在本命盘与运限盘上共用同一套规则，
共 64 条。什么是格局、每条规则的条件与来源，见[概念页](/zh/docs/guide/concepts/patterns)。
```go
chart, err := iztro.BySolar("1985-5-3", 9, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
hits, err := chart.Patterns(nil)
```
本页示例统一用 `"zh-CN"` 的本命盘，因此输出里的展示值都是中文。
## 类型 [#类型]
### PatternHit [#patternhit]
| 字段 | 类型 | 说明 |
| --------------- | --------------- | ----------------------------- |
| `Key` | `string` | 语言无关格局标识，取值即 `PatternXxx` 常量 |
| `Name` | `string` | 格局名称，按排盘语言翻译 |
| `Scope` | `string` | 判定视角：本命为 `ScopeOrigin`，运限为该层 |
| `PalaceIndex` | `int` | 成格所在的宫位索引（0-11，寅宫为 0） |
| `PalaceName` | `string` | 该宫在这个视角下的宫名 |
| `PalaceNameKey` | `string` | 宫名标识，取值即 `PalaceXxx` 常量 |
| `Variant` | `string` | 多口径格局命中的口径；单口径为空串 |
| `Broken` | `bool` | 「破格 / 加杀平常」条件是否触发。成格照报，这里只作标记 |
| `Stars` | `[]PatternStar` | 参与成格的星与落宫 |
三个方法：
| 方法 | 说明 |
| ------------------------------------- | -------------------------------- |
| `Is(patternKey string) bool` | 是否为指定格局，传 `PatternShaPoLang` 等常量 |
| `InPalace(nameKeyOrName string) bool` | 成格宫位是否为指定宫名，传宫位标识或当前语言宫名 |
| `String() string` | `格局名(宫名)` 或 `格局名(宫名,口径)`，便于日志与调试 |
### PatternStar [#patternstar]
| 字段 | 类型 | 说明 |
| ------------------------------ | -------- | --------------------------- |
| `Key` | `string` | 语言无关星耀标识 |
| `Name` | `string` | 星耀名称，按排盘语言翻译 |
| `PalaceIndex` | `int` | 该星**真正待的**宫位索引（借宫时不是借到的那一宫） |
| `Brightness` / `BrightnessKey` | `string` | 亮度显示文本与标识；无亮度为空串 |
| `Mutagen` / `MutagenKey` | `string` | 判定视角下的四化与标识；无四化为空串 |
### PatternConfig [#patternconfig]
判定口径。凡是「同一格局的多种成立形式」都走 `PatternHit.Variant`，这里只放会改变
**事实判定本身**的数据口径，因此只有三个字段。
```go
type PatternConfig struct {
BrightnessSource string // BrightnessSourceTable（默认）或 BrightnessSourcePositional
Borrow *bool // 空宫是否借对宫主星参与判定；nil 取内核默认 true
FlowStars *bool // 运限视角下流曜是否等同对应本命辅星；nil 取内核默认 true
}
func Bool(v bool) *bool // 布尔字面量取地址的便捷构造
func DefaultPatternConfig() *PatternConfig // 三项全显式的默认口径
```
布尔两项是 `*bool`：`nil` 表示「没说」，由内核取默认值 `true`，
显式关掉写 `iztro.Bool(false)`。`DefaultPatternConfig()` 返回
`{BrightnessSourceTable, Bool(true), Bool(true)}`，与传 `nil` 同义。
`BrightnessSourceTable` 按星盘亮度表（庙旺为明，陷与「不」为暗，与 iztro 逐值一致），
`BrightnessSourcePositional` 按传统位置（太阳寅至午明、酉至丑暗；太阴酉至丑明、卯至未暗）。
两者的取舍见[概念页的说明](/zh/docs/guide/concepts/patterns#日月的明暗按哪张表)。
`&iztro.PatternConfig{}` 的三个字段都是零值（空串与 `nil`），语义与传 `nil` 完全一致。
只改一项直接写字面量，没写的仍取内核默认：
```go
cfg := &iztro.PatternConfig{BrightnessSource: iztro.BrightnessSourcePositional}
onlyNatal := &iztro.PatternConfig{FlowStars: iztro.Bool(false)}
```
### Pattern 常量 [#pattern-常量]
64 个格局的语言无关标识都有具名常量，命名为 `Pattern` 加驼峰拼音：
`PatternShaPoLang`、`PatternFuXiangChaoYuan`、`PatternFengYunJiHui` 等，
取值即 `PatternHit.Key`。判断格局一律用常量，不要比 `Name`——
`Name` 随排盘语言变，`Key` 不变。
***
## Patterns [#patterns]
**用途** 取本命盘的全部格局命中。
**斗数含义** 把这张盘上成立的所有有名字的星耀组合列出来，附上成格的宫位与证据星。
**签名**
```go
func (a *Astrolabe) Patterns(config *PatternConfig) ([]PatternHit, error)
func (a *Astrolabe) PatternsContext(ctx context.Context, config *PatternConfig) ([]PatternHit, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ----------------- | ----------- | -- | ---------------- |
| `config` | `*PatternConfig` | 是 | — | 判定口径；传 `nil` 取默认 |
| `ctx` | `context.Context` | Context 版必填 | — | 用于取消等待 wasm 实例 |
**返回值** `[]PatternHit`——按来源页条目顺序排列；一条格局也不成立时为空切片。
本命盘上两条行运格（禄衰马困、风云际会）永远不出现。
**错误**
| 情况 | 错误 |
| ----------------------------- | --------------------------------------------------- |
| 星盘为 `nil` | `iztro: patterns: nil astrolabe` |
| `BrightnessSource` 不是两个合法取值之一 | `iztro: invalid patternConfig: unknown variant ...` |
两者都属于 `ErrInvalidArgument` 类，可用 `errors.Is` 匹配。
**示例**
```go
chart, _ := iztro.BySolar("1985-5-3", 9, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
hits, _ := chart.Patterns(nil)
for _, h := range hits {
fmt.Printf("%s %d %s broken=%v\n", h.Name, h.PalaceIndex, h.PalaceName, h.Broken)
}
```
**输出**
```text
武贪同行 11 迁移 broken=false
府相朝垣 5 命宫 broken=false
杀破狼 11 迁移 broken=false
禄马交驰 5 命宫 broken=false
左右夹命 5 命宫 broken=false
文贵文华 11 迁移 broken=false
文星朝命 5 命宫 broken=true
文星暗拱 5 命宫 broken=false
文星暗拱 5 命宫 broken=false
```
取一条命中并读它的证据星：
```go
for _, h := range hits {
if !h.Is(iztro.PatternFuXiangChaoYuan) {
continue
}
fmt.Println(h, h.Variant, h.InPalace(iztro.PalaceSoul))
for _, s := range h.Stars {
fmt.Printf(" %s %d %s %s\n", s.Name, s.PalaceIndex, s.Brightness, s.BrightnessKey)
}
}
```
```text
府相朝垣(命宫,soul_empty) soul_empty true
天府 9 得 de
天相 1 陷 xian
```
按口径判：
```go
chart, _ := iztro.BySolar("1985-6-10", 8, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
cfg := &iztro.PatternConfig{BrightnessSource: iztro.BrightnessSourcePositional}
a, _ := chart.Patterns(nil)
b, _ := chart.Patterns(cfg)
fmt.Println(names(a)) // names 取每条的 Name
fmt.Println(names(b))
```
```text
[]
[日月反背]
```
**边界与陷阱**
多数格局成于命宫，但「身命」类格局（武贪同行、杀破狼、石中隐玉…）命宫身宫各判一次，
`PalaceIndex` 记实际成格的那一宫，两宫都成立就返回两条命中。
禄马交驰更是任一宫成立即报，一张盘上可能有多条。
上面那张盘的身宫落在迁移宫，所以三条记的是迁移宫。
空宫借对宫主星时，`PatternStar.PalaceIndex` 记的是那颗星实际落的宫（对宫），
不是借进来的宫。要知道格局成在哪一宫看 `PatternHit.PalaceIndex`。
`Variant`、`Brightness`、`Mutagen` 这些在没有值时是空串而不是缺字段——
Go 侧解码自 JSON，可选键在 DTO 里省略，解到结构体上就是零值。
判断有无用 `h.Variant != ""`。
***
## Horoscope.Patterns [#horoscopepatterns]
**用途** 取某个运限层级视角下的格局命中。
**斗数含义** 以该层的命宫为命宫、合并该层的流曜与四化之后重跑全部规则。
「本命有此组合，大限又走到即享其益」就是这么算出来的。
**签名**
```go
func (h *Horoscope) Patterns(scope string, config *PatternConfig) ([]PatternHit, error)
func (h *Horoscope) PatternsContext(ctx context.Context, scope string, config *PatternConfig) ([]PatternHit, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ---------------- | -- | -- | ------------------------------ |
| `scope` | `string` | 是 | — | 判定视角所在的层级，传 `ScopeDecadal` 等常量 |
| `config` | `*PatternConfig` | 是 | — | 判定口径；传 `nil` 取默认 |
**返回值** `[]PatternHit`，每条的 `Scope` 即传入的层级。
传 `ScopeOrigin` 时结果与本命盘上直接调 `Patterns(nil)` 完全一致。
**错误** 运限不是由 `Astrolabe.Horoscope` 发起时返回
`iztro: horoscopePatterns: horoscope must be created by Astrolabe.Horoscope`；
`scope` 不是合法层级标识时返回 `unknown scope`。
**示例**
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
h, _ := chart.Horoscope("2025-6-1", 0)
hits, _ := h.Patterns(iztro.ScopeDecadal, nil)
for _, x := range hits {
fmt.Printf("%s %s %q\n", x.Name, x.Scope, x.Variant)
}
```
**输出**
```text
杀破狼 decadal ""
风云际会 decadal ""
风云际会 decadal "yearly"
```
同一张盘的本命视角只有一条「府相朝垣」——大限换了命宫，杀破狼才在这一层成立。
**边界与陷阱**
身宫是本命概念。运限视角下「身命」类格局只判该层命宫。
禄衰马困按当前视角那一层判（大限视角判大限，流年视角判流年），
限命宫三方四正又见七杀（古书严口径同时满足）时 `Variant` 为 `"qisha"`；
风云际会跨层比较「两限同时逢禄马」，只在 `ScopeDecadal` 视角判一次，
`Variant` 同时记二限组合与「逢」的松紧：大限 + 小限命中为空串（三方四正会照）或
`"same_palace"`（两限命宫皆本宫坐禄马的严口径），大限 + 流年命中为
`"yearly"` 或 `"yearly_same_palace"`。两种组合各报一条，最多两条。
默认口径下运禄/流禄当禄存看、运昌/流昌当文昌看，其余同理。
不想要这个行为，传 `&iztro.PatternConfig{FlowStars: iztro.Bool(false)}`。
`Patterns` 不是在已有的星盘对象上做增量计算，而是把排盘上下文（生日、时辰、性别、
语言、config）送回 wasm 内核重新发起一次判定。因此它不修改星盘，也不缓存结果——
在循环里反复调用时自己存一下返回值。
***
## 序列化 [#序列化]
`PatternHit` 与 `PatternStar` 的 JSON tag 就是绑定层 DTO 的键名，
`encoding/json` 直接序列化即得与 Rust、Python 两侧一致的结构：
```go
chart, _ := iztro.BySolar("1985-5-3", 9, iztro.GenderMale, true, iztro.LanguageZhCN, nil)
hits, _ := chart.Patterns(nil)
for _, hit := range hits {
if !hit.Is(iztro.PatternFuXiangChaoYuan) {
continue
}
b, _ := json.MarshalIndent(hit, "", " ")
fmt.Println(string(b))
}
```
```json
{
"key": "fu_xiang_chao_yuan",
"name": "府相朝垣",
"scope": "origin",
"palaceIndex": 5,
"palaceName": "命宫",
"palaceNameKey": "soulPalace",
"variant": "soul_empty",
"broken": false,
"stars": [
{
"key": "tianfuMaj",
"name": "天府",
"palaceIndex": 9,
"brightness": "得",
"brightnessKey": "de"
},
{
"key": "tianxiangMaj",
"name": "天相",
"palaceIndex": 1,
"brightness": "陷",
"brightnessKey": "xian"
}
]
}
```
***
## PatternsToText / Horoscope.PatternsToText [#patternstotext--horoscopepatternstotext]
**用途** 格局命中的语义化文本，每条一行 `- **格局名** (命中宫, 破格): 构成星耀`，
括号里的「破格」只在被冲破时出现。
**签名**
```go
func (a *Astrolabe) PatternsToText(config *PatternConfig) (string, error)
func (h *Horoscope) PatternsToText(scope string, config *PatternConfig) (string, error)
```
各有 `Context` 变体。与 `Patterns` 同一套判定（含重排上下文与判定口径）；
运限版本的宫名按该层重排后的宫名书写，`config` 传 `nil` 取默认口径。
**示例**
```go
text, _ := chart.PatternsToText(nil)
fmt.Print(text)
```
**输出**
```text
# 格局
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
```
本命盘与运限的 `ToText` 已各自带格局节；单独调用适合只要格局摘要的场景。
带释义的形态在命中列表之后紧跟每条命中格局的释义（`**格局名**: intro`，末段 `成立条件: `），
同一格局只释义一次；`opts` 见 [TextOptions](/zh/docs/go/knowledge#textoptions)：
```go
func (a *Astrolabe) PatternsToTextWith(opts TextOptions) (string, error)
func (h *Horoscope) PatternsToTextWith(scope string, opts TextOptions) (string, error)
```
```go
text, _ := chart.PatternsToTextWith(iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()})
lines := strings.Split(text, "\n")
fmt.Println(lines[2])
fmt.Println(string([]rune(lines[4])[:16]))
```
**输出**
```text
- **府相朝垣** (命宫): 天府(庙), 天相(庙)
**府相朝垣**: “食禄千锺”
```
# 轻量查询 (/zh/docs/go/query)
不排整盘就能拿到的生肖、星座与命宫主星。
有些问题不需要整张星盘。这五个函数各自只跑到必要的那一步就返回，
结果与完整排盘的对应字段永远一致——它们走的是同一套核心逻辑。
本页示例统一用 `"zh-CN"` 排盘，因此输出里的展示值都是中文。
***
## GetZodiacBySolarDate [#getzodiacbysolardate]
**用途** 由公历日期取生肖。
**斗数含义** 生肖由**年支**决定，而年支的换算时点受 `YearDivide` 影响。
正月初一与立春之间出生的人，两种配置会得到不同的生肖——这不是缺陷，是流派差异。
**签名**
```go
func GetZodiacBySolarDate(solarDate string, language Language, config *Config) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ---------- | -- | -- | ------------------------------- |
| `solarDate` | `string` | 是 | — | 公历日期，格式 `YYYY-M-D` |
| `language` | `Language` | 是 | — | 盘面语言 |
| `config` | `*Config` | 是 | — | 传 `nil` 取默认；仅 `YearDivide` 影响结果 |
**返回值** 按语言翻译的生肖名。
**示例**
```go
zodiac, _ := iztro.GetZodiacBySolarDate("2000-8-16", iztro.LanguageZhCN, nil)
fmt.Println(zodiac)
```
**输出**
```text
龙
```
**边界与陷阱**
默认按正月初一换年。改成 `&Config{YearDivide: iztro.YearDivideExact}` 后按立春换年，
1 月下旬到 2 月上旬出生的人可能拿到不同生肖。
***
## GetSignBySolarDate / GetSignByLunarDate [#getsignbysolardate--getsignbylunardate]
**用途** 取星座。
**斗数含义** 星座是西洋占星概念，只由公历日期决定，与斗数算法无关。
农历版本先把农历转成公历再判定，因此两者对同一天的结果相同。
**签名**
```go
func GetSignBySolarDate(solarDate string, language Language) (string, error)
func GetSignByLunarDate(lunarDate string, isLeapMonth bool, language Language) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------- | ---------- | -- | -- | ---------------- |
| `solarDate` / `lunarDate` | `string` | 是 | — | 日期，格式 `YYYY-M-D` |
| `isLeapMonth` | `bool` | 是 | — | 仅农历版本：该月是否闰月 |
| `language` | `Language` | 是 | — | 盘面语言 |
无 `config` 参数——星座不受任何配置影响。
**返回值** 星座名。
**示例**
```go
s1, _ := iztro.GetSignBySolarDate("2000-8-16", iztro.LanguageZhCN)
s2, _ := iztro.GetSignByLunarDate("2000-7-17", false, iztro.LanguageZhCN)
fmt.Println(s1, s2)
```
**输出**
```text
狮子座 狮子座
```
***
## GetMajorStarBySolarDate / GetMajorStarByLunarDate [#getmajorstarbysolardate--getmajorstarbylunardate]
**用途** 只取命宫主星，不排整盘。
**斗数含义** 命宫主星是斗数最常被单独问起的一项。
命宫为空宫时按惯例借对宫主星来看，本函数已经处理了这一步。
**签名**
```go
func GetMajorStarBySolarDate(
solarDate string, timeIndex uint8, fixLeap bool, language Language, config *Config,
) (string, error)
func GetMajorStarByLunarDate(
lunarDate string, timeIndex uint8, leap LeapMonth, language Language, config *Config,
) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------------- | ----------- | -- | -- | -------------------------------------------------------------------------------------------------- |
| `solarDate` / `lunarDate` | `string` | 是 | — | 日期 |
| `timeIndex` | `uint8` | 是 | — | 时辰索引 0–12，命宫由月份与时辰共同决定 |
| `fixLeap` | `bool` | 是 | — | 仅阳历版本：阳历日期落在闰月十五之后时是否视作次月 |
| `leap` | `LeapMonth` | 是 | — | 仅农历版本：`NotLeapMonth` / `LeapMonthKeep` / `LeapMonthFixed`，见 [`ByLunar`](/zh/docs/go/astro#bylunar) |
| `language` | `Language` | 是 | — | 盘面语言 |
| `config` | `*Config` | 是 | — | 传 `nil` 取默认 |
**返回值** 多颗主星以逗号分隔；空宫时返回对宫主星。
**示例**
```go
zh, _ := iztro.GetMajorStarBySolarDate("2000-8-16", 2, true, iztro.LanguageZhCN, nil)
en, _ := iztro.GetMajorStarBySolarDate("2000-8-16", 2, true, iztro.LanguageEnUS, nil)
fmt.Println(zh, en)
```
**输出**
```text
紫微 emperor
```
**边界与陷阱**
命宫由农历月份与出生时辰共同定位，因此 `timeIndex` 是必填的。
只知道日期不知道时辰时，斗数无法给出确定的命宫。
返回值是翻译后的字符串，换语言就会变。要做程序判断用下面的
`MajorStarKeysBySolarDate` / `MajorStarKeysByLunarDate`，
或排整盘后比较 `MajorStars` 里的 `Key`。
***
## MajorStarKeysBySolarDate / MajorStarKeysByLunarDate [#majorstarkeysbysolardate--majorstarkeysbylunardate]
**用途** 命宫主星的语言无关标识列表——上面两个函数的 key 形态，供程序判断。
**签名**
```go
func MajorStarKeysBySolarDate(
solarDate string, timeIndex uint8, fixLeap bool, config *Config,
) ([]string, error)
func MajorStarKeysByLunarDate(
lunarDate string, timeIndex uint8, leap LeapMonth, config *Config,
) ([]string, error)
```
**返回值** `[]string`——星耀标识常量取值（如 `StarZiweiMaj`）；
命宫为空宫时同样借对宫主星。标识与输出语言无关，因此**不收 `language`**。
**示例**
```go
keys, _ := iztro.MajorStarKeysBySolarDate("2000-8-16", 2, true, nil)
fmt.Println(keys)
```
**输出**
```text
[ziweiMaj]
```
# 工具函数 (/zh/docs/go/util)
索引换算、亮度与四化查表、命身宫推算、大限小限、四柱展示串。
这些函数是排盘算法的零件。自己实现斗数逻辑、或要复核某一步推算时用得上；
日常排盘不必直接调用。
参数与返回值中的标识都与语言无关，可直接与星盘上的 `*Key` 字段互操作。
***
## FixIndex / FixIndex12 [#fixindex--fixindex12]
**用途** 把任意整数约束到循环区间。
**斗数含义** 十二宫首尾相接，从丑宫（索引 11）再走一格回到寅宫（索引 0）。
所有「顺数几格、逆数几格」的推算都靠这个回绕。
**签名**
```go
func FixIndex(index int, max int) (int, error)
func FixIndex12(index int) int
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------- | ----- | -- | -- | -------------------------------- |
| `index` | `int` | 是 | — | 待修正的索引，可为负 |
| `max` | `int` | 是 | — | 循环长度；传 `0` 取默认值 12，天干用 10。负数返回错误 |
**返回值** 落在 `0..max` 的索引（含 0，不含 `max`）。
`FixIndex12` 固定模 12、不返回错误——十二宫回绕直接用它。
**示例**
```go
a, _ := iztro.FixIndex(-1, 0)
b, _ := iztro.FixIndex(13, 0)
c, _ := iztro.FixIndex(11, 10)
fmt.Println(a, b, c)
fmt.Println(iztro.FixIndex12(-1), iztro.FixIndex12(13))
_, err := iztro.FixIndex(0, -1)
fmt.Println(err)
```
**输出**
```text
11 1 1
11 1
iztro: invalid max '-1': expected a positive integer
```
**边界与陷阱**
这是复刻 iztro `fixIndex(index, max = 12)` 默认参数的写法，与 Go 的零值直觉相反：
`FixIndex(13, 0)` 得到 1 而不是报错。十二宫回绕请直接用 `FixIndex12`，
省掉这个歧义与那个永远不会发生的 `error`。
负数按数学取模回绕（-1 → 11），不是截断到 0。
这两个函数在 Go 侧直接算，不往返 wasm。
***
## EarthlyBranchToPalaceIndex [#earthlybranchtopalaceindex]
**用途** 地支转宫位索引。
**斗数含义** 十二宫的排列从**寅宫**起，而地支的自然顺序从**子**起，两者差两格。
这个函数负责这层换算：寅 → 0，卯 → 1，⋯，子 → 10，丑 → 11。
**签名**
```go
func EarthlyBranchToPalaceIndex(branchKey string) (int, error)
```
**返回值** `int`，0–11。
**示例**
```go
yin, _ := iztro.EarthlyBranchToPalaceIndex(iztro.BranchYin)
zi, _ := iztro.EarthlyBranchToPalaceIndex(iztro.BranchZi)
fmt.Println(yin, zi)
```
**输出**
```text
0 10
```
***
## TimeToIndex [#timetoindex]
**用途** 小时数转时辰索引。
**斗数含义** 一天十二时辰，每时辰两小时，但子时横跨午夜被拆成早子时（0）与晚子时（12），
因此索引有 13 个值。
**签名**
```go
func TimeToIndex(hour uint8) (uint8, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------ | ------- | -- | -- | --------------- |
| `hour` | `uint8` | 是 | — | 小时数 0–23，越界返回错误 |
**返回值** `uint8`，0–12——正好是排盘入口 `timeIndex` 参数的类型，可以直接传过去。
**示例**
```go
a, _ := iztro.TimeToIndex(0)
b, _ := iztro.TimeToIndex(4)
c, _ := iztro.TimeToIndex(23)
fmt.Println(a, b, c)
_, err := iztro.TimeToIndex(24)
fmt.Println(err)
// 结果可直接喂给排盘入口
chart, err := iztro.BySolar("2000-8-16", b, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(chart.Time)
```
**输出**
```text
0 2 12
iztro: invalid hour '24': expected 0-23
寅时
```
0 点为早子时，4 点为寅时，23 点为晚子时。排盘时不确定时辰索引，用这个函数换算。
***
## GetAgeIndex [#getageindex]
**用途** 由生年地支取小限起始宫位索引。
**斗数含义** 小限从固定的宫起，按虚岁逐年推移。起宫由生年地支所属的三合组决定：
寅午戌年起辰宫、申子辰年起戌宫、巳酉丑年起未宫、亥卯未年起丑宫。
**签名**
```go
func GetAgeIndex(branchKey string) (int, error)
```
**返回值** `int`，0–11。
**示例**
```go
idx, _ := iztro.GetAgeIndex(iztro.BranchChen)
fmt.Println(idx)
```
**输出**
```text
8
```
辰年属申子辰组，小限从戌宫起，戌宫的索引是 8。
***
## GetBrightness [#getbrightness]
**用途** 查某颗星落在某宫时的亮度。
**签名**
```go
func GetBrightness(starKey string, palaceIndex int, config *Config) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------- | --------- | -- | -- | --------------- |
| `starKey` | `string` | 是 | — | 星耀标识 |
| `palaceIndex` | `int` | 是 | — | 宫位索引，越界会对 12 取模 |
| `config` | `*Config` | 是 | — | 自定义亮度表会改变结果 |
**返回值** 亮度标识；该星没有亮度表时返回空串。
**示例**
```go
a, _ := iztro.GetBrightness(iztro.StarZiweiMaj, 4, nil)
b, _ := iztro.GetBrightness(iztro.StarLucunMin, 0, nil)
fmt.Printf("%q %q\n", a, b)
```
**输出**
```text
"miao" ""
```
紫微在午宫（索引 4）庙；禄存没有亮度表。
***
## GetMutagen / GetMutagensByHeavenlyStem [#getmutagen--getmutagensbyheavenlystem]
**用途** 查天干四化。
**斗数含义** 十天干各自固定指派四颗星化禄、权、科、忌。
`GetMutagen` 问「这颗星在这个天干下化什么」，
`GetMutagensByHeavenlyStem` 问「这个天干化哪四颗星」。
**签名**
```go
func GetMutagen(starKey string, stemKey string, config *Config) (string, error)
func GetMutagensByHeavenlyStem(stemKey string, config *Config) ([]string, error)
```
**返回值** `GetMutagen` 返回四化标识，该星不在此天干的四化表内时返回空串。
`GetMutagensByHeavenlyStem` 返回四项切片，顺序为**禄、权、科、忌**。
**示例**
```go
a, _ := iztro.GetMutagen(iztro.StarTaiyangMaj, iztro.StemGeng, nil)
b, _ := iztro.GetMutagen(iztro.StarZiweiMaj, iztro.StemGeng, nil)
c, _ := iztro.GetMutagensByHeavenlyStem(iztro.StemGeng, nil)
fmt.Printf("%q %q\n%v\n", a, b, c)
```
**输出**
```text
"sihuaLu" ""
[taiyangMaj wuquMaj taiyinMaj tiantongMaj]
```
***
## GetSoulAndBody [#getsoulandbody]
**用途** 由农历月索引、时辰与年干推命宫、身宫。
**斗数含义** 命宫是整张盘的起点：从寅宫起正月，顺数到生月，再从生月逆数到生时。
身宫用同样的起点但顺数生时。命宫的天干由五虎遁从年干推得。
**签名**
```go
func GetSoulAndBody(monthIndex int, timeIndex uint8, yearlyStemKey string) (*SoulAndBody, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --------------- | -------- | -- | -- | ------------------------------------- |
| `monthIndex` | `int` | 是 | — | 农历月索引，正月为 0；由 `FixLunarMonthIndex` 求得 |
| `timeIndex` | `uint8` | 是 | — | 时辰索引 0–12 |
| `yearlyStemKey` | `string` | 是 | — | 生年天干标识 |
**返回值** `*SoulAndBody`，含 `SoulIndex`、`BodyIndex`、`HeavenlyStemOfSoul`、`EarthlyBranchOfSoul`。
**示例**
```go
sb, _ := iztro.GetSoulAndBody(6, 2, iztro.StemGeng)
fmt.Printf("%+v\n", *sb)
```
**输出**
```text
{SoulIndex:4 BodyIndex:8 HeavenlyStemOfSoul:renHeavenly EarthlyBranchOfSoul:wuEarthly}
```
***
## GetFiveElementsClass [#getfiveelementsclass]
**用途** 由命宫干支推五行局。
**斗数含义** 五行局（水二、木三、金四、土五、火六）决定两件大事：
紫微星的起宫位置，以及大限的起运岁数。
**签名**
```go
func GetFiveElementsClass(stemKey string, branchKey string) (string, error)
```
**返回值** 五行局标识。
**示例**
```go
fe, _ := iztro.GetFiveElementsClass(iztro.StemRen, iztro.BranchWu)
fmt.Println(fe)
```
**输出**
```text
wood3rd
```
***
## GetPalaceNames [#getpalacenames]
**用途** 由命宫索引推十二宫名。
**斗数含义** 命宫定下后，其余十一宫按固定顺序逆时针排开：
命、兄弟、夫妻、子女、财帛、疾厄、迁移、仆役、官禄、田宅、福德、父母。
**签名**
```go
func GetPalaceNames(soulIndex int) ([]string, error)
```
**返回值** 十二项**标识**切片（不是译名），**按宫位索引排列**——
第 `i` 项就是 `chart.Palaces[i]` 的 `NameKey`。
与 `GetConstants().Palaces` 不同：那个给的是宫名的固定排列顺序，与具体盘无关。
**示例**
```go
names, _ := iztro.GetPalaceNames(4)
fmt.Println(names[:4])
```
**输出**
```text
[wealthPalace childrenPalace spousePalace siblingsPalace]
```
命宫在索引 4，因此索引 0（寅宫）是财帛。
***
## GetDecadalsAndAges [#getdecadalsandages]
**用途** 由命宫索引与五行局推十二宫的大限与小限。
**斗数含义** 大限起运岁数由五行局决定（水二局 2 岁起、木三局 3 岁起，依此类推），
顺逆由性别阴阳与年支阴阳决定；小限起宫由年支决定，按虚岁逐年推移。
**签名**
```go
func GetDecadalsAndAges(
soulIndex int, fiveElementsClass string, gender Gender, yearlyStemKey, yearlyBranchKey string,
) (DecadalsAndAges, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------------- | -------- | -- | -- | ----------------------------- |
| `soulIndex` | `int` | 是 | — | 命宫宫位索引 |
| `fiveElementsClass` | `string` | 是 | — | 五行局标识 |
| `gender` | `Gender` | 是 | — | `GenderMale` 或 `GenderFemale` |
| `yearlyStemKey` | `string` | 是 | — | 年干标识 |
| `yearlyBranchKey` | `string` | 是 | — | 年支标识 |
**返回值** `DecadalsAndAges`，含 `Decadals []Decadal` 与 `Ages [][]int`，均按宫位索引排列。
`Decadal` 与宫位上的 `palace.Decadal` 是同一个类型：
| 字段 | 类型 | 说明 |
| ------------------------------------ | -------- | ------------ |
| `Range` | `[2]int` | 大限起止虚岁，含两端 |
| `HeavenlyStem` / `HeavenlyStemKey` | `string` | 大限天干的译名 / 标识 |
| `EarthlyBranch` / `EarthlyBranchKey` | `string` | 大限地支的译名 / 标识 |
**示例**
```go
da, _ := iztro.GetDecadalsAndAges(4, "wood3rd", iztro.GenderFemale, iztro.StemGeng, iztro.BranchChen)
fmt.Printf("%+v\n", da.Decadals[0])
fmt.Println(da.Ages[0][:3])
```
**输出**
```text
{Range:[43 52] HeavenlyStem:戊 HeavenlyStemKey:wuHeavenly EarthlyBranch:寅 EarthlyBranchKey:yinEarthly}
[9 21 33]
```
**边界与陷阱**
整盘排出的每个宫位上已有 `Decadal` 与 `Ages` 字段，内容与本函数一致，
连译名与标识两组字段的含义都相同。这个函数用于不排整盘、只推大限小限的场合。
这个函数不收 `language` 参数，`Decadal` 的译名字段一律是中文。
要别的语言用 `HeavenlyStemKey` 走 [`Translate`](/zh/docs/go/i18n#translate)。
***
## FixLunarMonthIndex / FixLunarDayIndex [#fixlunarmonthindex--fixlunardayindex]
**用途** 求修正后的农历月索引与日索引。
**斗数含义** 闰月归属与晚子时归属是斗数两个长期有争议的边界，这两个函数把规则落定：
闰月十六日起按下月算（可关，且晚子时不进位），晚子时的日索引属次日。
**签名**
```go
func FixLunarMonthIndex(lunarMonth int, lunarDay int, isLeap bool, timeIndex uint8, fixLeap bool) (int, error)
func FixLunarDayIndex(lunarDay int, timeIndex uint8) (int, error)
```
**返回值** 月索引为 0-based（正月为 0）；日索引在晚子时不减一。
`FixLunarMonthIndex` 进位要同时满足四个条件：`isLeap` 为真、`fixLeap` 为真、
`lunarDay` 大于 15、且 `timeIndex` 不是 12。四者缺一，就按本月算。
**示例**
```go
m, _ := iztro.FixLunarMonthIndex(7, 17, false, 2, true)
d1, _ := iztro.FixLunarDayIndex(17, 2)
d2, _ := iztro.FixLunarDayIndex(17, 12)
fmt.Println(m, d1, d2)
```
**输出**
```text
6 16 17
```
七月非闰月，索引为 6；十七日在寅时减一得 16，在晚子时属次日故保持 17。
***
## TranslateChineseDate [#translatechinesedate]
**用途** 把四柱干支拼成展示串。
**签名**
```go
func TranslateChineseDate(pillars [4][2]string, language Language) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | -------------- | -- | -- | -------------------------------- |
| `pillars` | `[4][2]string` | 是 | — | 四柱标识 \[年, 月, 日, 时]，每柱为 \[天干, 地支] |
| `language` | `Language` | 是 | — | 盘面语言 |
**返回值** 词条均为单字符时柱内紧凑相连、柱间空格；
任一词条为多字符时柱内空格、柱间 `-`。
**示例**
```go
s, _ := iztro.TranslateChineseDate([4][2]string{
{iztro.StemGeng, iztro.BranchChen},
{iztro.StemJia, iztro.BranchShen},
{iztro.StemBing, iztro.BranchWu},
{iztro.StemGeng, iztro.BranchYin},
}, "zh-CN")
fmt.Println(s)
// 星盘上的四柱标识可直接取
s2, _ := iztro.TranslateChineseDate(chart.RawDates.ChineseDate.PillarKeys(), iztro.LanguageZhCN)
fmt.Println(s2)
```
**输出**
```text
庚辰 甲申 丙午 庚寅
庚辰 甲申 丙午 庚寅
```
**边界与陷阱**
干支标识非法时返回错误。定长数组保证了柱数必为四，不必再校验长度。
***
## MergeStars [#mergestars]
**用途** 把多组「十二宫星耀」按宫位合并成一组。
**斗数含义** 安星是分批进行的：主星、辅星、杂耀各出一组十二宫列表。
要把它们并成一张完整盘面时用这个函数。
**签名**
```go
func MergeStars(groups ...[][]Star) ([][]Star, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| -------- | ------------- | -- | -- | ------------------ |
| `groups` | `...[][]Star` | 是 | — | 若干组十二宫星耀，每组长度须为 12 |
**返回值** 合并后的十二宫切片，同宫内按传入顺序首尾相接。
**示例**
```go
birth := iztro.StarBirth{SolarDate: "2000-8-16", TimeIndex: 2, Gender: iztro.GenderFemale, FixLeap: true}
major, _ := iztro.GetMajorStar(birth)
minor, _ := iztro.GetMinorStar(birth)
merged, _ := iztro.MergeStars(major, minor)
names := []string{}
for _, s := range merged[0] {
names = append(names, s.Name)
}
fmt.Println(names)
```
**输出**
```text
[武曲 天相 天马]
```
**边界与陷阱**
某一组的长度不是 12 时返回错误。这是纯本地实现，不经 wasm。
# 安星模块 (/zh/docs/go/star)
按出生数据取某一组星耀的落宫。
不排整盘、只想知道「禄存落在哪一宫」或「这张盘的杂耀怎么分布」时用这一层。
所有索引都是**宫位索引**：0 为寅宫，11 为丑宫。
## StarBirth [#starbirth]
按出生数据安星的入口共用这一个参数结构。
```go
type StarBirth struct {
SolarDate string
TimeIndex uint8
Gender string
FixLeap bool
Language string
Config *Config
FromStem string
FromBranch string
}
```
| 字段 | 类型 | 说明 |
| ------------------------- | --------- | --------------------- |
| `SolarDate` | `string` | 公历日期，格式 `YYYY-M-D` |
| `TimeIndex` | `uint8` | 时辰索引 0–12 |
| `Gender` | `string` | 性别，决定长生与博士十二神的顺逆 |
| `FixLeap` | `bool` | 是否修正闰月 |
| `Language` | `string` | 星耀名称的输出语言，留空取 `zh-CN` |
| `Config` | `*Config` | 排盘配置，`nil` 取默认 |
| `FromStem` / `FromBranch` | `string` | 起五行局的干支；两者须同时给出 |
```go
birth := iztro.StarBirth{
SolarDate: "2000-8-16",
TimeIndex: 2,
Gender: iztro.GenderFemale,
FixLeap: true,
}
```
本页示例统一用默认的 `zh-CN`（`Language` 留空即取它），因此星名输出都是中文。
两者同时给出后，五行局改由该干支推算，进而改变紫微天府落点与长生十二神。
其余各组星的起法不受影响。用它可以取到中州派地盘、人盘的安星结果。
***
## GetStartIndex [#getstartindex]
**用途** 求紫微、天府的起始宫位。
**斗数含义** 紫微是全盘的锚点：由五行局与农历生日按「起紫微星诀」定位，
其余十三颗主星再依紫微与天府的位置铺开。天府与紫微的位置互为镜像。
**签名**
```go
func GetStartIndex(birth StarBirth) (StartIndex, error)
```
**返回值** `StartIndex{ ZiweiIndex, TianfuIndex int }`。
**示例**
```go
s, _ := iztro.GetStartIndex(birth)
fmt.Printf("%+v\n", s)
```
**输出**
```text
{ZiweiIndex:4 TianfuIndex:8}
```
***
## 各组落宫索引 [#各组落宫索引]
以下六个入口形状一致：收 `StarBirth`，返回一个字段全是宫位索引的结构体。
| 函数 | 返回类型 | 字段 | 起法依据 |
| --------------------- | ------------------ | ------------------------------------------ | ----------------- |
| `GetLuYangTuoMaIndex` | `LuYangTuoMaIndex` | `LuIndex` `YangIndex` `TuoIndex` `MaIndex` | 年干定禄存，禄前羊后陀；天马按年支 |
| `GetKuiYueIndex` | `KuiYueIndex` | `KuiIndex` `YueIndex` | 年干 |
| `GetChangQuIndex` | `ChangQuIndex` | `ChangIndex` `QuIndex` | 时支 |
| `GetKongJieIndex` | `KongJieIndex` | `KongIndex` `JieIndex` | 时支 |
| `GetTimelyStarIndex` | `TimelyStarIndex` | `TaifuIndex` `FenggaoIndex` | 时支 |
| `GetLuanXiIndex` | `LuanXiIndex` | `HongluanIndex` `TianxiIndex` | 年支 |
**示例**
```go
l, _ := iztro.GetLuYangTuoMaIndex(birth)
c, _ := iztro.GetChangQuIndex(birth)
lx, _ := iztro.GetLuanXiIndex(birth)
fmt.Printf("%+v\n%+v %+v\n", l, c, lx)
```
**输出**
```text
{LuIndex:6 YangIndex:7 TuoIndex:5 MaIndex:0}
{ChangIndex:6 QuIndex:4} {HongluanIndex:9 TianxiIndex:3}
```
擎羊在禄存前一格、陀罗在后一格，这是「禄前羊刃当，禄后陀罗府」的直接体现。
***
## GetDailyStarIndex / GetMonthlyStarIndex / GetYearlyStarIndex [#getdailystarindex--getmonthlystarindex--getyearlystarindex]
**用途** 取按日、按月、按年起的杂耀落宫。
**斗数含义** 杂耀按起法分组：日系星从辅星位置起初一顺数到生日；
月系星按农历月份定位；年系星最多，按年干或年支起。
**返回值**
| 函数 | 返回类型 | 字段 |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetDailyStarIndex` | `DailyStarIndex` | `SantaiIndex` `BazuoIndex` `EnguangIndex` `TianguiIndex` |
| `GetMonthlyStarIndex` | `MonthlyStarIndex` | `YuejieIndex` `TianyaoIndex` `TianxingIndex` `YinshaIndex` `TianyueIndex` `TianwuIndex` |
| `GetYearlyStarIndex` | `YearlyStarIndex` | 27 项：`XianchiIndex` `HuagaiIndex` `GuchenIndex` `GuasuIndex` `TiancaiIndex` `TianshouIndex` `TianchuIndex` `PosuiIndex` `FeilianIndex` `LongchiIndex` `FenggeIndex` `TiankuIndex` `TianxuIndex` `TianguanIndex` `TianfuIndex` `TiandeIndex` `YuedeIndex` `TiankongIndex` `JieluIndex` `KongwangIndex` `XunkongIndex` `TianshangIndex` `TianshiIndex` `JiekongIndex` `JieshaAdjIndex` `NianjieIndex` `DahaoAdjIndex` |
**示例**
```go
d, _ := iztro.GetDailyStarIndex(birth)
m, _ := iztro.GetMonthlyStarIndex(birth)
fmt.Printf("%+v\n%+v\n", d, m)
```
**输出**
```text
{SantaiIndex:0 BazuoIndex:10 EnguangIndex:9 TianguiIndex:7}
{YuejieIndex:0 TianyaoIndex:5 TianxingIndex:1 YinshaIndex:0 TianyueIndex:9 TianwuIndex:0}
```
**边界与陷阱**
年系杂耀属流年神煞，取年支时用的是 `HoroscopeDivide` 而非 `YearDivide`。
两个配置不同时，年系星与主星、辅星可能基于不同的年支——这是刻意的流派区分。
它们也属年系，但由 `GetLuanXiIndex` 单独给出。
这三项只在 `Algorithm` 为中州派时进入盘面，替换掉截路、空亡与大耗的默认取法；
默认派别下它们仍会被算出来，只是不安进宫位。
***
## GetMajorStar / GetMinorStar / GetAdjectiveStar [#getmajorstar--getminorstar--getadjectivestar]
**用途** 取主星、辅星、杂耀在十二宫的完整分布。
**签名**
```go
func GetMajorStar(birth StarBirth) ([][]Star, error)
func GetMinorStar(birth StarBirth) ([][]Star, error)
func GetAdjectiveStar(birth StarBirth) ([][]Star, error)
```
**返回值** 十二项切片，按宫位索引排列。每项是该宫的 `Star` 切片（可能为空）。
**示例**
```go
major, _ := iztro.GetMajorStar(birth)
for i := 0; i < 5; i++ {
names := []string{}
for _, s := range major[i] {
names = append(names, s.Name)
}
fmt.Println(i, names)
}
```
**输出**
```text
0 [武曲 天相]
1 [太阳 天梁]
2 [七杀]
3 [天机]
4 [紫微]
```
**边界与陷阱**
返回的 `Star` 带亮度与生年四化标记，与整盘排出的完全一致——
它们走的是同一段代码。要取整盘的话直接用 `BySolar` 更省事。
***
## GetChangsheng12 / GetBoShi12 / GetYearly12 [#getchangsheng12--getboshi12--getyearly12]
**用途** 取四组十二神在十二宫的排列。
**斗数含义** 这四组各是十二个标记排满十二宫，每宫恰好一个：
长生十二神按五行局起、随性别与年支阴阳定顺逆；
博士十二神从禄存起、同样定顺逆；
岁前十二神从年支起顺行；将前十二神按年支三合组起。
**签名**
```go
func GetChangsheng12(birth StarBirth) ([]string, error)
func GetBoShi12(birth StarBirth) ([]string, error)
func GetYearly12(birth StarBirth) (Yearly12, error)
```
**返回值** 十二项标识切片，按宫位索引排列。
`GetYearly12` 返回 `Yearly12{ Suiqian12, Jiangqian12 []string }`。
**示例**
```go
cs, _ := iztro.GetChangsheng12(birth)
bs, _ := iztro.GetBoShi12(birth)
y, _ := iztro.GetYearly12(birth)
fmt.Println(cs[:4])
fmt.Println(bs[:4])
fmt.Println(y.Suiqian12[:4])
fmt.Println(y.Jiangqian12[:4])
```
**输出**
```text
[jue mu si bing]
[faylian zhoushu jiangjun xiaohao]
[diaoke bingfu suijian huiqi]
[suiyi xiishen huagai jiesha]
```
返回的是标识而非译名，要展示用 `Translate(key, language)`。
***
## GetChangsheng12StartIndex / GetJiangqian12StartIndex [#getchangsheng12startindex--getjiangqian12startindex]
**用途** 只取两组十二神的起始宫位，不排整组。
**斗数含义** 长生起点由五行局定：水二局长生在申、木三局在亥、金四局在巳、
土五局在申、火六局在寅。将星起点由年支三合组定：寅午戌年在午、申子辰年在子、
巳酉丑年在酉、亥卯未年在卯。
**签名**
```go
func GetChangsheng12StartIndex(fiveElementsClass string) (int, error)
func GetJiangqian12StartIndex(branchKey string) (int, error)
```
**返回值** `int`，0–11。这两个函数不需要出生数据。
**示例**
```go
a, _ := iztro.GetChangsheng12StartIndex(iztro.ClassWater2nd)
b, _ := iztro.GetChangsheng12StartIndex(iztro.ClassFire6th)
c, _ := iztro.GetJiangqian12StartIndex(iztro.BranchZi)
d, _ := iztro.GetJiangqian12StartIndex(iztro.BranchWu)
fmt.Println(a, b, c, d)
```
**输出**
```text
6 0 10 4
```
水二局长生在申（索引 6），火六局在寅（索引 0）。
***
## GetHoroscopeStar [#gethoroscopestar]
**用途** 取某个运限层级的流耀分布。
**斗数含义** 流耀是随运限产生的十颗星：魁钺昌曲禄羊陀马鸾喜。
它们的落宫由该层级的干支决定，名字随层级变化。流年层级额外多一颗年解。
**签名**
```go
func GetHoroscopeStar(stemKey, branchKey, scope string, language Language) ([][]Star, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | ---------- | -- | -- | --------- |
| `stemKey` | `string` | 是 | — | 该层级的天干标识 |
| `branchKey` | `string` | 是 | — | 该层级的地支标识 |
| `scope` | `string` | 是 | — | 运限层级，决定星名 |
| `language` | `Language` | 是 | — | 盘面语言 |
**返回值** 十二项切片，按宫位索引排列。
**各层级的星名对照**
| 本命 | 大限 | 流年 | 流月 | 流日 | 流时 |
| -- | -- | -- | -- | -- | -- |
| 天魁 | 运魁 | 流魁 | 月魁 | 日魁 | 时魁 |
| 天钺 | 运钺 | 流钺 | 月钺 | 日钺 | 时钺 |
| 文昌 | 运昌 | 流昌 | 月昌 | 日昌 | 时昌 |
| 文曲 | 运曲 | 流曲 | 月曲 | 日曲 | 时曲 |
| 禄存 | 运禄 | 流禄 | 月禄 | 日禄 | 时禄 |
| 擎羊 | 运羊 | 流羊 | 月羊 | 日羊 | 时羊 |
| 陀罗 | 运陀 | 流陀 | 月陀 | 日陀 | 时陀 |
| 天马 | 运马 | 流马 | 月马 | 日马 | 时马 |
| 红鸾 | 运鸾 | 流鸾 | 月鸾 | 日鸾 | 时鸾 |
| 天喜 | 运喜 | 流喜 | 月喜 | 日喜 | 时喜 |
标识形如 `yunlu`（运禄）、`liulu`（流禄）、`yuelu`（月禄）、`rilu`（日禄）、`shilu`（时禄）。
**示例**
```go
decadal, _ := iztro.GetHoroscopeStar(iztro.StemJia, iztro.BranchZi, iztro.ScopeDecadal, iztro.LanguageZhCN)
for i := 0; i < 4; i++ {
names := []string{}
for _, s := range decadal[i] {
names = append(names, s.Name)
}
fmt.Println(i, names)
}
```
**输出**
```text
0 [运禄 运马]
1 [运羊 运鸾]
2 []
3 [运昌]
```
**边界与陷阱**
`ScopeYearly` 的结果里额外含年解，按流年地支定位，安放在十颗流耀之前。
其余层级没有这一颗。
***
## 低层落宫 [#低层落宫]
上面的函数都从出生数据起算，内部先推出年干支、命宫、修正后的农历月，再落宫。
这一组则直接收那些中间量，自建流程时可以复用。
| 函数 | 收 | 出（字段全为宫位索引 `int`） |
| ---------------------------------------------------------------- | ------------ | ----------------------------------------------------- |
| `GetZuoYouIndex(lunarMonth)` | 修正后的农历月 1–12 | `ZuoYouIndex{ZuoIndex, YouIndex}` |
| `GetHuoLingIndex(branchKey, timeIndex)` | 年支、时辰 | `HuoLingIndex{HuoIndex, LingIndex}` |
| `GetHuagaiXianchiIndex(branchKey)` | 年支 | `HuagaiXianchiIndex{HuagaiIndex, XianchiIndex}` |
| `GetGuGuaIndex(branchKey)` | 年支 | `GuGuaIndex{GuchenIndex, GuasuIndex}` |
| `GetJieshaAdjIndex(branchKey)` | 年支 | `int`，劫煞宫位索引 |
| `GetDahaoIndex(branchKey)` | 年支 | `int`，大耗宫位索引 |
| `GetNianjieIndex(branchKey)` | 年支 | `int`，年解宫位索引 |
| `GetTianshiTianshangIndex(gender, branchKey, soulIndex, config)` | 性别、年支、命宫索引 | `TianshiTianshangIndex{TianshangIndex, TianshiIndex}` |
| `GetChangQuIndexByHeavenlyStem(stemKey)` | 天干 | `ChangQuIndex{ChangIndex, QuIndex}` |
**示例**
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
yearBranch := chart.RawDates.ChineseDate.YearlyKeys[1]
hl, _ := iztro.GetHuoLingIndex(yearBranch, 2)
gg, _ := iztro.GetGuGuaIndex(yearBranch)
cq, _ := iztro.GetChangQuIndexByHeavenlyStem(iztro.StemJia)
fmt.Println(hl, gg, cq)
```
**输出**
```text
{2 10} {3 11} {3 7}
```
**边界与陷阱**
`GetZuoYouIndex` 收的是修正闰月之后的月份，即 `FixLunarMonthIndex(...) + 1`，
不是农历原始月份。闰月盘直接传原始月份会落错宫。
`GetTianshiTianshangIndex` 的结果随 `config.Algorithm` 变：中州派在阴男阳女
（生年地支阴阳与性别阴阳不同）时天伤天使对调，通行派不对调；`config` 传 `nil` 取默认。
`GetChangQuIndexByHeavenlyStem` 按天干起昌曲，用于运限层级的流昌流曲；
本命盘的文昌文曲按时支走 `GetChangQuIndex`。
# 数据表 (/zh/docs/go/data)
星耀基础信息、天干地支信息、顺序常量与全部标识常量。
排盘算法的输入表与语言无关标识常量。
***
## StarsInfo [#starsinfo]
**用途** 取星耀基础信息表。
**签名**
```go
func StarsInfo() (map[string]StarInfo, error)
```
**返回值** 星耀标识 → `StarInfo`。只有二十颗星有记录：
**十四主星**加文昌、文曲、火星、铃星、擎羊、陀罗。
| 字段 | 类型 | 说明 |
| -------------- | ---------- | -------------------------- |
| `Brightness` | `[]string` | 十二宫亮度标识，索引 0 为寅宫；该宫无亮度则为空串 |
| `FiveElements` | `string` | 五行；原表未填时为空串 |
| `YinYang` | `string` | 阴阳；原表未填时为空串 |
**示例**
```go
info, _ := iztro.StarsInfo()
fmt.Println(len(info))
fmt.Printf("%+v\n", info[iztro.StarZiweiMaj])
fmt.Printf("%q\n", info[iztro.StarTaiyangMaj].FiveElements)
```
**输出**
```text
20
{Brightness:[wang wang de wang miao miao wang wang de wang ping miao] FiveElements:土 YinYang:阴}
""
```
**边界与陷阱**
表中部分星耀的五行或阴阳未填：太阳与七杀两项皆为空串，
贪狼、天相、天梁、破军的阴阳为空串，六颗辅星两项皆为空串。
***
## FlowStarCounterparts [#flowstarcounterparts]
**用途** 流耀 → 对应本命辅星的全量对照表（50 条）。
**签名**
```go
func FlowStarCounterparts() (map[string]string, error)
```
**返回值** 键为流耀标识常量取值（`StarLiuchang` 等），值为本命辅星标识
（`StarWenchangMin` 等）。流耀没有独立的知识包条目，释义按对应的本命辅星查，
这张表就是官方对照。
**示例**
```go
m, _ := iztro.FlowStarCounterparts()
fmt.Println(m["liuchang"])
```
**输出**
```text
wenchangMin
```
***
## HeavenlyStems [#heavenlystems]
**用途** 取天干信息表。
**斗数含义** 天干的四化表是四化系统的根：生年干决定生年四化，
宫干决定该宫飞出的四化，运限干决定该层级的四化。
**签名**
```go
func HeavenlyStems() (map[string]HeavenlyStemInfo, error)
```
**返回值** 天干标识 → `HeavenlyStemInfo`：
| 字段 | 类型 | 说明 |
| -------------- | ---------- | ----------------- |
| `YinYang` | `string` | 阴阳 |
| `FiveElements` | `string` | 五行 |
| `Crash` | `string` | 对冲天干标识；戊、己无对冲，为空串 |
| `Mutagen` | `[]string` | 四化四星标识，顺序为禄、权、科、忌 |
**示例**
```go
stems, _ := iztro.HeavenlyStems()
fmt.Printf("%+v\n", stems[iztro.StemJia])
fmt.Printf("戊干对冲: %q\n", stems[iztro.StemWu].Crash)
```
**输出**
```text
{YinYang:阳 FiveElements:木 Crash:gengHeavenly Mutagen:[lianzhenMaj pojunMaj wuquMaj taiyangMaj]}
戊干对冲: ""
```
***
## EarthlyBranches [#earthlybranches]
**用途** 取地支信息表。
**签名**
```go
func EarthlyBranches() (map[string]EarthlyBranchInfo, error)
```
**返回值** 地支标识 → `EarthlyBranchInfo`：
| 字段 | 类型 | 说明 |
| -------------- | -------- | ---------------- |
| `YinYang` | `string` | 阴阳，决定大限与长生十二神的顺逆 |
| `FiveElements` | `string` | 五行 |
| `Crash` | `string` | 对冲地支标识 |
| `Soul` | `string` | 命主星标识（按命宫地支查） |
| `Body` | `string` | 身主星标识（按生年地支查） |
| `Inside` | `string` | 对应脏腑 |
| `Outside` | `string` | 对应身体部位 |
| `HealthTip` | `string` | 健康提示 |
`Inside` / `Outside` / `HealthTip` 三项只有中文一种写法，不参与国际化。
**示例**
```go
branches, _ := iztro.EarthlyBranches()
fmt.Printf("%+v\n", branches[iztro.BranchZi])
```
**输出**
```text
{YinYang:阳 FiveElements:水 Crash:wuEarthly Soul:tanlangMaj Body:huoxingMin Inside:胆 Outside:下体 HealthTip:生殖系统、膀胱、尿道之疾病，听觉障碍}
```
***
## GetConstants [#getconstants]
**用途** 取顺序常量与推算规则表。
**签名**
```go
func GetConstants() (Constants, error)
```
**返回值** `Constants`：
| 字段 | 类型 | 说明 |
| ------------------- | ------------------- | ---------------------------------------------------- |
| `Languages` | `[]string` | 支持的语言代码 |
| `HeavenlyStems` | `[]string` | 天干顺序 |
| `EarthlyBranches` | `[]string` | 地支顺序 |
| `Zodiac` | `[]string` | 生肖标识，按地支顺序 |
| `Signs` | `[]string` | 星座标识，按黄道顺序 |
| `Palaces` | `[]string` | 十二宫名，从命宫起**逆时针**排：命、父母、福德、田宅、官禄、仆役、迁移、疾厄、财帛、子女、夫妻、兄弟 |
| `Gender` | `map[string]string` | 男女各自的阴阳 |
| `ChineseTime` | `[]string` | 时辰标识，早子时起、晚子时止 |
| `TimeRange` | `[]string` | 时辰对应的钟点区间 |
| `TigerRule` | `map[string]string` | 五虎遁：年干推正月天干 |
| `RatRule` | `map[string]string` | 五鼠遁：日干推子时天干 |
| `Mutagen` | `[]string` | 四化顺序 |
| `FiveElementsClass` | `map[string]int` | 五行局标识 → 局数（水二局 2 …… 火六局 6） |
**示例**
```go
c, _ := iztro.GetConstants()
fmt.Println(c.Languages)
fmt.Println(c.Zodiac[:3], c.ChineseTime[12], c.TimeRange[2])
fmt.Println(c.Gender)
fmt.Println("甲年正月干:", c.TigerRule[iztro.StemJia])
fmt.Println(c.Palaces)
fmt.Println(c.FiveElementsClass[iztro.ClassWood3rd], iztro.FiveElementsClassNumber(iztro.ClassFire6th))
```
**输出**
```text
[en-US ja-JP ko-KR zh-CN zh-TW vi-VN]
[rat ox tiger] lateRatHour 03:00~05:00
map[female:阴 male:阳]
甲年正月干: bingHeavenly
[soulPalace parentsPalace spiritPalace propertyPalace careerPalace friendsPalace surfacePalace healthPalace wealthPalace childrenPalace spousePalace siblingsPalace]
3 6
```
**边界与陷阱**
`Palaces` 给的是宫名的**排列顺序**，不是某张盘上第 `i` 格叫什么。
要那个用 [`GetPalaceNames(soulIndex)`](/zh/docs/go/util#getpalacenames)。
`FiveElementsClassNumber(key)` 不必先取 `Constants`，未知标识返回 0。
`Languages` 的顺序是 iztro 词表的合并次序（en-US 起），不是常量的声明次序。
[`KeyOf`](/zh/docs/go/i18n#keyof) 的逐语言扫描顺序与它一致。
***
## 标识常量 [#标识常量]
包里的标识常量取值就是语言无关标识，可直接与数据对象的 `*Key` 字段比较。
| 前缀 | 数量 | 例 |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `Palace*` | 12 + 2 | `PalaceSoul`、`PalaceWealth`、`PalaceBody`、`PalaceOriginal` |
| `Star*` | 162 | `StarZiweiMaj`、`StarLucunMin`、`StarYunlu` |
| `Stem*` | 10 | `StemJia`、`StemGeng` |
| `Branch*` | 12 | `BranchZi`、`BranchWu` |
| `Mutagen*` | 4 | `MutagenLu`、`MutagenJi` |
| `Brightness*` | 7 | `BrightnessMiao`、`BrightnessWang` |
| `Class*` | 5 | `ClassWater2nd`、`ClassWood3rd`、`ClassMetal4th`、`ClassEarth5th`、`ClassFire6th` |
| `Scope*` | 6 | `ScopeOrigin`、`ScopeDecadal` |
| `StarType*` | 8 | `StarTypeMajor`、`StarTypeTough` |
| `Gender*` | 2 | `GenderMale`、`GenderFemale`（类型 `Gender`） |
| `Language*` | 6 | `LanguageZhCN`、`LanguageZhTW`、`LanguageEnUS`、`LanguageJaJP`、`LanguageKoKR`、`LanguageViVN`（类型 `Language`） |
| `*LeapMonth*` | 3 | `NotLeapMonth`、`LeapMonthKeep`、`LeapMonthFixed`（类型 `LeapMonth`，`ByLunar` 的闰月处理方式） |
`Gender`、`Language`、`LeapMonth` 是具名字符串类型：作为入口参数时编译器会挡住把别的字符串误传进来的错误，
字面量（`"male"`、`"zh-CN"`）仍可直接写；`Astrolabe.GenderKey` 与 `Astrolabe.Language` 字段也是这两个类型。
其余常量是无类型的字符串常量，与 `*Key` 字段直接比较。
配置类另有六组：
| 前缀 | 取值 |
| ------------------ | ------------------------------------------------ |
| `YearDivide*` | `YearDivideNormal` / `YearDivideExact` |
| `HoroscopeDivide*` | `HoroscopeDivideNormal` / `HoroscopeDivideExact` |
| `AgeDivide*` | `AgeDivideNormal` / `AgeDivideBirthday` |
| `DayDivide*` | `DayDivideForward` / `DayDivideCurrent` |
| `Algorithm*` | `AlgorithmDefault` / `AlgorithmZhongzhou` |
| `Astro*` | `AstroHeaven` / `AstroEarth` / `AstroHuman` |
写 `iztro.ClassWood3rd`，不是 `iztro.FiveElementsWood3rd`——
后者不存在，编译不过。取局数用 `iztro.FiveElementsClassNumber(key)`。
**示例**
```go
soul := chart.Palace(iztro.PalaceSoul)
fmt.Println(soul.MajorStars[0].Key == iztro.StarZiweiMaj)
fmt.Println(iztro.StarZiweiMaj, iztro.MutagenLu, iztro.PalaceWealth)
fmt.Println(iztro.ClassWood3rd, iztro.GenderFemale, iztro.LanguageEnUS)
// 排盘入口的 gender 与 language 也用这两组常量
en, err := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageEnUS, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(en.Palace(iztro.PalaceSoul).MajorStars[0].Name)
```
**输出**
```text
true
ziweiMaj sihuaLu wealthPalace
wood3rd female en-US
emperor
```
它们都是无类型字符串常量，`chart.Palace("soulPalace")` 与
`chart.Palace(iztro.PalaceSoul)` 完全等价。
常量的价值在于 IDE 补全与拼写检查，而非类型约束。
# 翻译 (/zh/docs/go/i18n)
标识与译名的双向查找。
星盘上每个字段都同时给出译名与 `*Key` 标识，通常不必手工翻译。
这两个函数用于手上只有标识（或只有某种语言的译名）、需要换算的场合。
支持六种语言：`zh-CN`、`zh-TW`、`en-US`、`ja-JP`、`ko-KR`、`vi-VN`。
***
## Translate [#translate]
**用途** 把任意标识译成指定语言。
**签名**
```go
func Translate(key string, language Language) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ---------- | -- | -- | ------ |
| `key` | `string` | 是 | — | 语言无关标识 |
| `language` | `Language` | 是 | — | 目标语言 |
覆盖十二类共 260 个标识：
| 类目 | 数量 | 例 |
| ----------- | --- | --------------------------------------------------------- |
| 星耀 | 162 | `ziweiMaj`、`changsheng`、`yunlu` |
| 宫位（含身宫、来因宫） | 14 | `soulPalace`、`wealthPalace`、`bodyPalace`、`originalPalace` |
| 天干 | 10 | `jiaHeavenly` |
| 地支 | 12 | `ziEarthly` |
| 亮度 | 7 | `miao`、`wang` |
| 四化 | 4 | `sihuaLu` |
| 五行局 | 5 | `water2nd` |
| 性别 | 2 | `male`、`female` |
| 生肖 | 12 | `rat`、`ox` |
| 时辰 | 13 | `earlyRatHour` |
| 星座 | 12 | `aries` |
| 运限层级 | 7 | `decadal`、`turn` |
**返回值** 译名；未知标识返回空串（不是错误）。
**示例**
```go
a, _ := iztro.Translate(iztro.StarZiweiMaj, iztro.LanguageEnUS)
b, _ := iztro.Translate(iztro.PalaceSoul, iztro.LanguageJaJP)
c, _ := iztro.Translate("nosuch", iztro.LanguageZhCN)
fmt.Printf("%q %q %q\n", a, b, c)
```
**输出**
```text
"emperor" "命宮" ""
```
**边界与陷阱**
标识查不到不算异常，返回空串。要区分「译名恰好是空串」与「标识不存在」时，
先确认标识在上表的类目内。
***
## KeyOf [#keyof]
**用途** 由任意语言的译名反查标识。
**签名**
```go
func KeyOf(text string) (string, error)
func KeyOfIn(text, keyFilter string) (string, error)
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ----------- | -------- | -- | -- | ------------------- |
| `text` | `string` | 是 | — | 任一支持语言下的译名 |
| `keyFilter` | `string` | 是 | — | 限定标识名须含的子串，用于消歧同形译名 |
**返回值** 标识；查不到返回空串。
**示例**
```go
a, _ := iztro.KeyOf("紫微")
b, _ := iztro.KeyOf("emperor")
c, _ := iztro.KeyOf("자미")
d, _ := iztro.KeyOf("查无此名")
fmt.Printf("%q %q %q %q\n", a, b, c, d)
```
**输出**
```text
"ziweiMaj" "ziweiMaj" "ziweiMaj" ""
```
三种语言的译名都落到同一个标识。
**边界与陷阱**
少数译名在多个类目下同形：en-US 的 `horse` 既是生肖马也是天马，
`dragon` 既是生肖龙也是青龙，ko-KR 的 `사` 既是地支巳也是长生12神的死。
`KeyOf` 逐语言、每种语言内逐标识取先命中者，顺序与 iztro 的 `kot` 完全一致
（有金标测试逐例守着）。要指定类目就用 `KeyOfIn`——标识名含该子串才纳入比对：
```go
a, _ := iztro.KeyOf("horse") // "horse"（生肖马）
b, _ := iztro.KeyOfIn("horse", "Min") // "tianmaMin"（天马）
c, _ := iztro.KeyOf("유시") // "hourly"（流时）
d, _ := iztro.KeyOfIn("유시", "Hour") // "roosterHour"（酉时）
e, _ := iztro.KeyOfIn("horse", "Palace") // ""
```
常用子串：`Maj` 十四主星、`Min` 辅星、`Heavenly` / `Earthly` 干支、
`Palace` 宫位、`Hour` 时辰。限定后无匹配返回空串，不退回未限定的结果。
`KeyOf` 会遍历 260 个标识 × 6 种语言，且经一次 wasm 往返。
不要放在每宫每星的内层循环里——那种场合直接用数据自带的 `*Key` 字段。
***
## AllKeys [#allkeys]
**用途** 取全部 260 个可翻译标识。
**签名**
```go
func AllKeys() ([]string, error)
```
**返回值** 标识切片，顺序即 `KeyOf` 的反查次序：
运限层级、生肖、时辰、星座、五行局、天干、地支、亮度、四化、星耀、宫位、性别，
与 iztro 各语言翻译文件的合并次序一致。
**示例**
```go
keys, _ := iztro.AllKeys()
first, _ := iztro.Translate(keys[0], iztro.LanguageZhCN)
fmt.Println(len(keys), keys[:4], first)
```
**输出**
```text
260 [decadal childhood yearly monthly] 大限
```
要遍历某一类目自己的标识时，用 `keys.go` 的常量或 `GetConstants()` 更省事。
***
## 没有全局语言开关 [#没有全局语言开关]
x-iztro 不设「当前语言」这样的全局状态：排盘时语言随参数传入，
翻译函数每次调用都显式指定目标语言。
全局语言开关会让同一段代码在不同调用顺序下产出不同结果，
并发环境尤其危险。显式传参使每次调用的结果只由入参决定。
要在一个进程里同时输出多种语言，直接排多张盘即可，互不干扰：
```go
zh, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
en, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageEnUS, nil)
fmt.Println(zh.Palace(iztro.PalaceSoul).MajorStars[0].Name,
en.Palace(iztro.PalaceSoul).MajorStars[0].Name)
```
**输出**
```text
紫微 emperor
```
两张盘的 `*Key` 字段完全相同，因此任何基于标识的判断在两张盘上结果一致。
# 知识包 (/zh/docs/go/knowledge)
KnowledgePack 与各条目结构体、内嵌默认包、JSON 解析、覆盖包合并与错误处理。
知识包是「语言无关标识 → 解读文本与门派属性」的 JSON。内核只判事实，
解读文本与星耀的门派属性放在这里。概念、格式与写覆盖包的方法见
[知识包指南](/zh/docs/guide/guides/knowledge-pack)，完整字段表见仓库的
[`knowledge/SCHEMA.md`](https://github.com/x-haose/x-iztro/blob/main/knowledge/SCHEMA.md)。
```go
pack, err := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
intro := pack.StarIntro(iztro.StarZiweiMaj)
```
取键的方法都收 `string`，传 `StarXxx` / `PatternXxx` / `PalaceXxx` / `MutagenXxx` 常量即可。
默认包与合并都在内嵌的 wasm 内核里，本包只做 JSON 编解码。
## 类型 [#类型]
### KnowledgePack [#knowledgepack]
字段全部导出，带 `json` 标签，可直接用 `encoding/json` 编解码。
| 字段 | 类型 | 说明 |
| ---------- | ------------------------- | --------------------------- |
| `Schema` | `int` | 格式版本，当前为 1 |
| `ID` | `string` | 包标识，默认包为 `"iztro-docs"` |
| `Version` | `string` | 包版本，默认包为「抓取日期+来源 commit 短号」 |
| `Language` | `string` | 文本语言的语言码，如 `LanguageZhCN` |
| `Extends` | `string` | 覆盖包所覆盖的包标识；独立包为空串 |
| `Source` | `KnowledgeSource` | 来源与许可 |
| `Stars` | `map[string]StarEntry` | 星耀条目，键为星耀标识 |
| `Patterns` | `map[string]PatternEntry` | 格局条目，键为格局标识 |
| `Palaces` | `map[string]TextEntry` | 宫位条目，键为宫位标识 |
| `Mutagens` | `map[string]TextEntry` | 四化条目，键为四化标识 |
| `Concepts` | `map[string]ConceptEntry` | 术语条目，键为 slug |
### KnowledgeSource [#knowledgesource]
`Name`、`URL`、`Commit`、`License`、`Author`、`RetrievedAt`、`Adapted`（改编说明），都是 `string`，缺省为空串。
### StarEntry [#starentry]
| 字段 | 类型 | 说明 |
| -------------- | ------------------- | -------------------------------------------------------------------------------- |
| `Name` | `string` | 该语言的显示名 |
| `Category` | `string` | 类别：`"major"` / `"minor"` / `"adjective"` / `"dec"` / `"flow"`（流耀，指向对应本命辅星的对照性条目） |
| `Group` | `string` | 分组：杂耀的分类、神煞的组别 |
| `Attributes` | `StarAttributes` | 门派属性 |
| `Intro` | `string` | 解读正文（Markdown） |
| `Combinations` | `map[string]string` | 与另一颗主星同宫的组合解读，键为对方星耀标识 |
### StarAttributes [#starattributes]
`YinYang`（`yin` / `yang`）、`FiveElements`（`wood` / `fire` / `earth` / `metal` / `water`）、
`Stem`（`jia`…`gui`）、`FiveElementsNote`、`Dipper`、`Chemistry`、`Career`、`Duty`、
`Aliases`（`[]string`）、`ElementColor`、`EnergyColor`。
`FiveElements` 与 `YinYang` 是知识包来源的说法，与核心星耀数据的取值可能不同——
核心那份与 iztro 逐值一致。
原因见[指南](/zh/docs/guide/guides/knowledge-pack#为什么星耀的阴阳五行放在这里)。
### PatternEntry [#patternentry]
`Name`、`Quotes`（`[]string`）、`Conditions`、`Intro`。
### TextEntry / ConceptEntry [#textentry--conceptentry]
`TextEntry`（宫位、四化）有 `Name` 与 `Intro`；`ConceptEntry`（术语）有 `Title` 与 `Intro`。
Go 侧不用指针区分「没写」与「写了空串」，字段缺省即空串 / nil。
要判断某条到底有没有正文，比空串即可。
***
## BuiltinKnowledgePack [#builtinknowledgepack]
**用途** 取内嵌的默认知识包。
**签名**
```go
func BuiltinKnowledgePack(language Language) (*KnowledgePack, error)
func BuiltinKnowledgePackContext(ctx context.Context, language Language) (*KnowledgePack, error)
```
**参数**
| 参数 | 类型 | 说明 |
| ---------- | ----------------- | --------------------------- |
| `ctx` | `context.Context` | Context 变体专有，用于取消等待 wasm 实例 |
| `language` | `Language` | 文本语言 |
**返回值** `(*KnowledgePack, error)`。该语言没有内嵌默认包时返回错误
（可用 `errors.Is(err, iztro.ErrInvalidArgument)` 匹配）。目前只有 `LanguageZhCN` 有。
**示例**
```go
pack, err := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
if err != nil {
log.Fatal(err)
}
fmt.Println(pack.ID, pack.Version, pack.Language, pack.Source.License)
fmt.Println(len(pack.Stars), len(pack.Patterns), len(pack.Palaces), len(pack.Mutagens), len(pack.Concepts))
_, err = iztro.BuiltinKnowledgePack(iztro.LanguageEnUS)
fmt.Println(err, errors.Is(err, iztro.ErrInvalidArgument))
```
**输出**
```text
iztro-docs 2026-08-19+ec2d58b zh-CN MIT
162 64 12 4 49
iztro: no builtin knowledge pack for language 'en-US' true
```
***
## ParseKnowledgePack [#parseknowledgepack]
**用途** 由 JSON 文本解析一份包。
**签名**
```go
func ParseKnowledgePack(data []byte) (*KnowledgePack, error)
```
**返回值** `(*KnowledgePack, error)`。JSON 不合法、`schema` 缺失或为 0、
`schema` 高于本库支持的版本，都返回 `ErrInvalidArgument` 类的错误——
与 Rust 内核解析（`KnowledgePack::from_json`）同语义。
序列化直接用 `encoding/json`：
```go
data, err := json.Marshal(pack)
```
**示例**
```go
overlay, err := iztro.ParseKnowledgePack([]byte(`{"schema":1,"id":"my-school","version":"1",
"language":"zh-CN","extends":"iztro-docs",
"stars":{"ziweiMaj":{"intro":"我的紫微","attributes":{"aliases":["帝座"]}}},
"patterns":{"zi_fu_tong_gong":{"intro":"我的紫府同宫"}}}`))
if err != nil {
log.Fatal(err)
}
fmt.Println(overlay.ID, overlay.Extends)
_, err = iztro.ParseKnowledgePack([]byte("nope"))
fmt.Println(err)
_, err = iztro.ParseKnowledgePack([]byte(`{"schema":99}`))
fmt.Println(err)
```
**输出**
```text
my-school iztro-docs
iztro: invalid knowledge pack: invalid character 'o' in literal null (expecting 'u')
iztro: knowledge pack schema 99 is newer than supported 1
```
***
## Merged [#merged]
**用途** 把若干覆盖包依次叠加到本包上，返回新包。
**签名**
```go
func (p *KnowledgePack) Merged(overlays ...*KnowledgePack) (*KnowledgePack, error)
func (p *KnowledgePack) MergedContext(ctx context.Context, overlays ...*KnowledgePack) (*KnowledgePack, error)
```
**参数**
| 参数 | 类型 | 说明 |
| ---------- | ------------------- | --------------------------- |
| `ctx` | `context.Context` | Context 变体专有，用于取消等待 wasm 实例 |
| `overlays` | `...*KnowledgePack` | 覆盖包，按传入顺序依次叠加，后面的覆盖前面的 |
**返回值** 新的 `*KnowledgePack`，本包与覆盖包都不变。
接收者为 `nil`、某个覆盖包为 `nil`、或某个包的 `schema` 不合法
（手工构造的结构体也在这里被内核校验），都返回 `ErrInvalidArgument` 类的错误。
合并规则见[指南](/zh/docs/guide/guides/knowledge-pack#合并规则)：逐段按键合并，
覆盖包的非空字段覆盖同键条目的对应字段，`Attributes` 与 `Combinations` 逐字段合并，
数组字段整体替换。合并本身在 wasm 内核里算，三语言结果一致。
**示例**
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
merged, err := pack.Merged(overlay)
if err != nil {
log.Fatal(err)
}
zi := merged.Star(iztro.StarZiweiMaj)
fmt.Println(merged.ID, zi.Name, zi.Attributes.Aliases, zi.Attributes.Chemistry, zi.Intro)
fmt.Println(merged.PatternIntro(iztro.PatternZiFuTongGong),
merged.Pattern(iztro.PatternZiFuTongGong).Quotes)
fmt.Println(string([]rune(pack.StarIntro(iztro.StarZiweiMaj))[:5]))
_, err = pack.Merged(nil)
fmt.Println(err)
```
**输出**
```text
my-school 紫微 [帝座] 尊贵 我的紫微
我的紫府同宫 [紫府同宫终身福厚。]
紫微星号称
iztro: mergeKnowledgePacks: nil overlay pack
```
***
## Star / Pattern / Palace / Mutagen / Concept [#star--pattern--palace--mutagen--concept]
**用途** 按语言无关标识取条目。
**签名**
```go
func (p *KnowledgePack) Star(starKey string) *StarEntry
func (p *KnowledgePack) Pattern(patternKey string) *PatternEntry
func (p *KnowledgePack) Palace(palaceKey string) *TextEntry
func (p *KnowledgePack) Mutagen(mutagenKey string) *TextEntry
func (p *KnowledgePack) Concept(slug string) *ConceptEntry
```
**返回值** 包里没有该条目时返回 `nil`；接收者为 `nil` 时同样返回 `nil`，不会 panic。
返回的是条目的副本地址，改它不影响包本身。
**示例**
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
zi := pack.Star(iztro.StarZiweiMaj)
fmt.Println(zi.Name, zi.Category, zi.Attributes.Dipper, zi.Attributes.Aliases)
fmt.Println(zi.Combinations[iztro.StarTianfuMaj] != "")
fmt.Println(pack.Palace(iztro.PalaceSoul).Name, pack.Mutagen(iztro.MutagenLu).Name)
fmt.Println(pack.Concept("tong-gong").Title)
fmt.Println(pack.Star("nope") == nil)
```
**输出**
```text
紫微 major 中天星系 [帝王星 老板星 俸禄星]
true
命宫 化禄
遇、加、逢、同宫、同度
true
```
***
## StarIntro / PatternIntro [#starintro--patternintro]
**用途** 直接取解读正文。
**签名**
```go
func (p *KnowledgePack) StarIntro(starKey string) string
func (p *KnowledgePack) PatternIntro(patternKey string) string
```
**返回值** 条目不存在、或条目存在但没写正文，都返回空串。
**示例** 把本命格局连同引文列出来：
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
hits, _ := chart.Patterns(nil)
for _, hit := range hits {
fmt.Println(hit.Name, "|", pack.Pattern(hit.Key).Quotes[0])
fmt.Println(string([]rune(pack.PatternIntro(hit.Key))[:10]))
}
```
**输出**
```text
府相朝垣 | 府相朝垣命必荣
“食禄千锺”的断语使
```
***
## TextOptions [#textoptions]
**用途** `ToTextWith` 家族（`ToTextWith` / `PalaceToTextWith` / `SurroundedPalacesToTextWith` /
`PatternsToTextWith` 与 `Horoscope` 上的同名方法）的输出选项：释义材料来源与格局判定口径。
零值只输出盘面事实、按默认口径判格局，与不带 `With` 的方法输出逐字节相同。
**定义**
```go
type TextOptions struct {
Knowledge Knowledge
PatternConfig *PatternConfig
}
```
**字段**
| 字段 | 类型 | 说明 |
| --------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `Knowledge` | [`Knowledge`](#knowledge--builtinknowledge--knowledgefrom) | 释义材料来源；零值不带释义。给出时每宫事实之后紧跟该宫星耀释义、格局列表之后紧跟格局释义、本命文本末尾附 `## 四化释义`，见[带释义的文本](/zh/docs/guide/guides/to-text#带释义的文本) |
| `PatternConfig` | [`*PatternConfig`](/zh/docs/go/patterns#patternconfig) | 格局判定口径，与 `Patterns(config)` 同一入参；同时作用于文本的格局节与格局释义。`nil` 取内核默认 |
**示例**
```go
text, _ := chart.ToTextWith(iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge()})
same, _ := chart.ToTextWith(iztro.TextOptions{})
plain, _ := chart.ToText()
fmt.Println(same == plain, utf8.RuneCountInString(plain), utf8.RuneCountInString(text))
cfg := iztro.PatternConfig{BrightnessSource: iztro.BrightnessSourcePositional}
byPosition, _ := chart.ToTextWith(iztro.TextOptions{Knowledge: iztro.BuiltinKnowledge(), PatternConfig: &cfg})
```
**输出**
```text
true 3389 20767
```
***
## Knowledge / BuiltinKnowledge / KnowledgeFrom [#knowledge--builtinknowledge--knowledgefrom]
**用途** [`TextOptions`](#textoptions) 的 `Knowledge` 字段取值：`ToTextWith` 家族的释义材料来源。
**签名**
```go
type Knowledge struct { /* 不导出 */ }
func BuiltinKnowledge() Knowledge
func KnowledgeFrom(pack *KnowledgePack) Knowledge
```
**取值**
| 取值 | 含义 |
| --------------------- | ----------------------------------------------------------------- |
| `BuiltinKnowledge()` | 用盘语言的内嵌默认包；该语言没有内嵌包（目前只有 zh-CN 有）时方法返回 `ErrInvalidArgument`，不静默回退 |
| `KnowledgeFrom(pack)` | 用给定的包（自定义或 `Merged` 之后的包）；`pack` 为 `nil` 等同零值 |
| `Knowledge{}`（零值） | 不带释义，`TextOptions{}` 的输出与不带 `With` 的方法逐字节相同 |
**示例**
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
data, _ := os.ReadFile("my-school.json")
overlay, _ := iztro.ParseKnowledgePack(data)
mine, _ := pack.Merged(overlay)
text, _ := chart.ToTextWith(iztro.TextOptions{Knowledge: iztro.KnowledgeFrom(mine)})
```
***
## ForAstrolabe / ForHoroscope [#forastrolabe--forhoroscope]
**用途** 按盘取材：裁出只含这张盘相关条目的子包。
**签名**
```go
func (p *KnowledgePack) ForAstrolabe(chart *Astrolabe, config *PatternConfig) (*KnowledgePack, error)
func (p *KnowledgePack) ForAstrolabeContext(ctx context.Context, chart *Astrolabe, config *PatternConfig) (*KnowledgePack, error)
func (p *KnowledgePack) ForHoroscope(horoscope *Horoscope, config *PatternConfig) (*KnowledgePack, error)
func (p *KnowledgePack) ForHoroscopeContext(ctx context.Context, horoscope *Horoscope, config *PatternConfig) (*KnowledgePack, error)
```
**参数**
| 参数 | 类型 | 说明 |
| ----------- | ----------------- | ---------------------------------------------------------------------------------- |
| `ctx` | `context.Context` | Context 变体专有，用于取消等待 wasm 实例 |
| `chart` | `*Astrolabe` | 取材依据的星盘；重排盘按重排后的布局取材 |
| `horoscope` | `*Horoscope` | 由 `chart.Horoscope(...)` 得到的运限，本命部分随之取材 |
| `config` | `*PatternConfig` | 格局判定口径，与 [`Patterns(config)`](/zh/docs/go/patterns#patternconfig) 同一入参；传 `nil` 取默认 |
**返回值** `(*KnowledgePack, error)`。标准知识包，元信息沿用本包：`Stars` 是盘上出现的星
（主辅杂与四组十二神，14 主星的 `Combinations` 只留对方主星确在同宫的），
`Patterns` 是按 `config` 口径命中的格局，`Mutagens` 四条全留，`Palaces` 与 `Concepts` 为空。
`ForHoroscope` 在此之上再加各层流耀与大限到流时各层视角命中的格局。
子包要和 `Patterns(config)` / `PatternsToTextWith` 配同一口径：口径不同，命中集合不同，
释义就会缺项或多项。
取材以本包当前内容为准（整包发给内核），就地改过的条目照样进入子包。
接收者或入参为 `nil`、运限不是由 `Astrolabe.Horoscope` 得到时返回 `ErrInvalidArgument`。
取材规则见[按盘取材](/zh/docs/guide/guides/knowledge-pack#按盘取材)。
**示例**
```go
pack, _ := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
sub, _ := pack.ForAstrolabe(chart, nil)
fmt.Println(len(sub.Stars), len(sub.Patterns), len(sub.Mutagens), len(sub.Palaces))
for k := range sub.Stars[iztro.StarWuquMaj].Combinations {
fmt.Println(k)
}
h, _ := chart.Horoscope("2025-1-1", 0)
sub, _ = pack.ForHoroscope(h, nil)
fmt.Println(len(sub.Stars), len(sub.Patterns))
```
**输出**
```text
108 1 4 0
tianxiangMaj
158 16
```
武曲在这张盘上与天相同宫，所以子包里武曲的 `Combinations` 只剩天相一条。
***
## Knowledge.ForAstrolabe / Knowledge.ForHoroscope [#knowledgeforastrolabe--knowledgeforhoroscope]
**用途** 用 `Knowledge` 哨兵按盘取材。`BuiltinKnowledge()` 时内核直接读内嵌包，
不必先 `BuiltinKnowledgePack` 拿整包再送回去；`KnowledgeFrom(pack)` 时等同 `pack.ForAstrolabe` 系列。
**签名**
```go
func (k Knowledge) ForAstrolabe(chart *Astrolabe, config *PatternConfig) (*KnowledgePack, error)
func (k Knowledge) ForAstrolabeContext(ctx context.Context, chart *Astrolabe, config *PatternConfig) (*KnowledgePack, error)
func (k Knowledge) ForHoroscope(horoscope *Horoscope, config *PatternConfig) (*KnowledgePack, error)
func (k Knowledge) ForHoroscopeContext(ctx context.Context, horoscope *Horoscope, config *PatternConfig) (*KnowledgePack, error)
```
**参数** 与 `(*KnowledgePack).ForAstrolabe` 系列相同。
**返回值** 同上。`Knowledge{}` 零值没有材料来源，返回 `ErrInvalidArgument`；
`BuiltinKnowledge()` 遇到没有内嵌包的盘语言也返回 `ErrInvalidArgument`。
**示例**
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
sub, _ := iztro.BuiltinKnowledge().ForAstrolabe(chart, nil)
fmt.Println(len(sub.Stars), len(sub.Patterns))
```
**输出**
```text
108 1
```
# 反推 (/zh/docs/go/reverse)
SolarDatesByBazi 与 ReverseChart：由八字四柱或星盘特征反查候选生辰的函数与类型。
由八字四柱或星盘特征反查候选生辰。计算全部在 wasm 内核完成
（剪枝枚举 + 正排终验，与正向排盘零分歧），Go 侧是类型化封装。
概念、四柱口径与 Config 的关系、多解与截断语义见
[反推指南](/zh/docs/guide/guides/reverse)。
```go
cands, err := iztro.SolarDatesByBazi(
iztro.Pillar{iztro.StemGeng, iztro.BranchChen},
iztro.Pillar{iztro.StemJia, iztro.BranchShen},
iztro.Pillar{iztro.StemBing, iztro.BranchWu},
iztro.Pillar{iztro.StemGeng, iztro.BranchYin},
1900, 2100, nil)
```
干支、五行局、星耀都收语言无关标识（`StemGeng`、`BranchChen`、`ClassWood3rd`、
`StarZiweiMaj` 等常量）。两个入口都有 `Context` 变体，`ctx` 用于取消等待 wasm 实例。
## 类型 [#类型]
### Pillar [#pillar]
```go
type Pillar [2]string
```
一柱干支：\[天干标识, 地支标识]。星盘上的 `RawDates.ChineseDate.YearlyKeys` 等
字段可直接转换：`iztro.Pillar(cd.YearlyKeys)`。
### BirthCandidate [#birthcandidate]
一个候选生辰，可直接交给 [`BySolar`](/zh/docs/go/astro) 排盘。
| 字段 | 类型 | 说明 |
| ----------- | -------- | ------------------------- |
| `SolarDate` | `string` | 公历日期，`YYYY-M-D` |
| `TimeIndex` | `uint8` | 时辰索引 0–12（0 为早子时，12 为晚子时） |
### StarPosition [#starposition]
一颗星与其落宫地支：星盘特征反推的原子条件。
| 字段 | 类型 | 说明 |
| -------- | -------- | --------------------- |
| `Star` | `string` | 星耀标识（须为本命盘星耀，运限流曜不接受） |
| `Branch` | `string` | 落宫地支标识 |
### ReverseCriteria [#reversecriteria]
星盘特征反推的条件集。字段的零值即「缺省」：空串不设该条件、
`YearRange` 零值取 `[1900, 2100]`、`Limit` 为 0 取内核默认（512）、
`FixLeap` 为 `nil` 取内核默认 `true`（`*bool`，显式关掉写 `iztro.Bool(false)`）。
全部条件可选，但至少要给一个。
| 字段 | 类型 | 说明 |
| ------------------- | ---------------- | ----------------------------------- |
| `SoulBranch` | `string` | 命宫地支标识，空串不限 |
| `BodyBranch` | `string` | 身宫地支标识，空串不限 |
| `FiveElementsClass` | `string` | 五行局标识，空串不限 |
| `Stars` | `[]StarPosition` | 星耀落宫条件，全部须同时满足 |
| `Mutagens` | `[4]string` | 生年四化 \[禄, 权, 科, 忌] 各自的星耀标识，空串表示该位不限 |
| `YearRange` | `[2]int` | 公历年闭区间（含两端），须落在 1583–9999 内 |
| `FixLeap` | `*bool` | 是否修正闰月，与排盘入参同义；`nil` 取内核默认 `true` |
| `Limit` | `int` | 候选数上限 |
### ReverseResult [#reverseresult]
| 字段 | 类型 | 说明 |
| ------------ | ------------------ | --------------------------- |
| `Candidates` | `[]BirthCandidate` | 满足全部条件的候选生辰 |
| `Truncated` | `bool` | 是否因达到候选数上限而提前截断；截断时更晚的解未被搜索 |
***
## SolarDatesByBazi [#solardatesbybazi]
由八字四柱反查公历生辰。
```go
func SolarDatesByBazi(yearly, monthly, daily, hourly Pillar,
startYear, endYear int, config *Config) ([]BirthCandidate, error)
func SolarDatesByBaziContext(ctx context.Context, yearly, monthly, daily, hourly Pillar,
startYear, endYear int, config *Config) ([]BirthCandidate, error)
```
四柱按 `config` 的分界口径解释（`YearDivide` 年柱、`HoroscopeDivide` 月柱、
`DayDivide` 晚子归属），与排盘输出的 `RawDates.ChineseDate` 同一套语义，
因此任何盘的四柱反查结果必包含该盘的生辰。一组四柱在范围内通常每约 60 年
出现一次；时柱为子时因早晚子之分可能给出相邻两天的两个候选。
**示例**
```go
a, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
cd := a.RawDates.ChineseDate
cands, err := iztro.SolarDatesByBazi(
iztro.Pillar(cd.YearlyKeys), iztro.Pillar(cd.MonthlyKeys),
iztro.Pillar(cd.DailyKeys), iztro.Pillar(cd.HourlyKeys),
1900, 2100, nil)
if err != nil {
log.Fatal(err)
}
for _, c := range cands {
fmt.Println(c.SolarDate, c.TimeIndex)
}
```
**输出**
```text
1940-8-31 2
2000-8-16 2
2060-8-1 2
```
**错误** 干支阴阳不配（如甲丑）、年份范围颠倒或超出 1583–9999 时返回
`ErrInvalidArgument` 类错误（`errors.Is` 可匹配），见[错误处理](/zh/docs/go/errors)。
***
## ReverseChart [#reversechart]
由星盘特征反查候选生辰。
```go
func ReverseChart(criteria *ReverseCriteria, config *Config) (*ReverseResult, error)
func ReverseChartContext(ctx context.Context, criteria *ReverseCriteria,
config *Config) (*ReverseResult, error)
```
判定贯穿 `config`：四化表、算法派别、各分界口径都按它算，
候选用同一 `config` 排盘必满足全部条件。星盘布局与性别无关
（性别只影响大限行进方向），因此条件不含性别。
**示例**
```go
r, err := iztro.ReverseChart(&iztro.ReverseCriteria{
SoulBranch: iztro.BranchWu,
FiveElementsClass: iztro.ClassWood3rd,
Stars: []iztro.StarPosition{{Star: iztro.StarZiweiMaj, Branch: iztro.BranchWu}},
Mutagens: [4]string{iztro.StarTaiyangMaj, "", "", ""},
YearRange: [2]int{1998, 2002},
}, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(len(r.Candidates), r.Truncated)
```
**输出**
```text
39 false
```
**错误** `criteria` 为 `nil`、条件为空、`Stars` 含运限流曜、年份范围非法时返回
`ErrInvalidArgument` 类错误。
达到 `Limit` 即停止搜索，更晚的解不会出现在结果里。
`Truncated` 为 `true` 时应收窄 `YearRange` 或补条件后重查。
# 扩展星盘 (/zh/docs/go/extend)
用结构体嵌入给星盘补自定义分析方法。
斗数的分析规则千人千面，库不可能穷举。Go 不允许给其他包的类型加方法，
因此扩展点是**嵌入**：把 `*Astrolabe` 嵌进自己的结构体，
新方法与内置方法一样用点号调用，且是编译期检查的。
## 配方 [#配方]
定义一个结构体，嵌入
`*iztro.Astrolabe`
给这个结构体加方法
用排出的星盘构造它
```go
package main
import (
"strings"
"github.com/x-haose/x-iztro/go/iztro"
)
// MyChart 嵌入星盘，补自己的分析方法。
type MyChart struct {
*iztro.Astrolabe
}
// MajorStar 返回命宫主星名（空宫借对宫），多颗以逗号分隔。
func (c MyChart) MajorStar() string {
soul := c.Palace(iztro.PalaceSoul)
source := soul
if soul.IsEmpty() {
source = soul.OppositePalace()
}
names := make([]string, 0, len(source.MajorStars))
for _, s := range source.MajorStars {
if s.Type == iztro.StarTypeMajor {
names = append(names, s.Name)
}
}
return strings.Join(names, ",")
}
// FiveElementsValue 返回五行局的局数。
func (c MyChart) FiveElementsValue() int {
return map[string]int{
iztro.ClassWater2nd: 2,
iztro.ClassWood3rd: 3,
iztro.ClassMetal4th: 4,
iztro.ClassEarth5th: 5,
iztro.ClassFire6th: 6,
}[c.FiveElementsClassKey]
}
```
**用法**
```go
chart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
my := MyChart{chart}
fmt.Println(my.MajorStar())
fmt.Println(my.FiveElementsValue())
// 内置字段与方法照常可用
fmt.Println(my.SolarDate)
fmt.Println(my.Palace(iztro.PalaceSoul).Name)
// 扩展方法随排盘语言输出
enChart, _ := iztro.BySolar("2000-8-16", 2, iztro.GenderFemale, true, iztro.LanguageEnUS, nil)
fmt.Println(MyChart{enChart}.MajorStar())
```
**输出**
```text
紫微
3
2000-8-16
命宫
emperor
```
写 `*iztro.Astrolabe` 而不是 `Astrolabe *iztro.Astrolabe`——
前者让内置字段与方法直接提升到外层，`my.SolarDate` 就能取到；
后者每次都得写 `my.Astrolabe.SolarDate`。
***
## 扩展别的类型 [#扩展别的类型]
同一套写法适用于宫位与星耀：
```go
type MyPalace struct {
*iztro.Palace
}
// IsAfflicted 判断本宫是否「煞忌交冲」：坐煞星且带化忌。
func (p MyPalace) IsAfflicted() bool {
return p.HasOneOf(
iztro.StarQingyangMin, iztro.StarTuoluoMin,
iztro.StarHuoxingMin, iztro.StarLingxingMin,
iztro.StarDikongMin, iztro.StarDijieMin,
) && p.HasMutagen(iztro.MutagenJi)
}
```
```go
for i := range chart.Palaces {
p := MyPalace{&chart.Palaces[i]}
if p.IsAfflicted() {
fmt.Println(p.Name, "煞忌交冲")
}
}
```
**输出**
```text
疾厄 煞忌交冲
```
***
## 用接口约束扩展 [#用接口约束扩展]
要求多种星盘类型提供同一组分析能力时，用接口：
```go
type WealthAnalyzer interface {
WealthScore() int
HasWealthPattern() bool
}
func report(a WealthAnalyzer) {
fmt.Println(a.WealthScore(), a.HasWealthPattern())
}
```
任何实现了这两个方法的类型都能传进去，编译期检查。
***
## 组织建议 [#组织建议]
`WealthChart`、`CareerChart`、`HealthChart` 各自嵌入星盘，
使用方按需构造。堆成一个大类型会让所有调用点都被迫带上全部方法。
`s.Key == iztro.StarZiweiMaj` 在任何输出语言下都成立；
`s.Name == "紫微"` 只在中文盘上成立。展示时才用 `Name`。
扩展方法通常只读，用值接收器即可——嵌入的是指针，复制外层结构体不会复制星盘。
方法要改外层结构体自己的字段时才需要指针接收器。
***
## 与运行期注入的区别 [#与运行期注入的区别]
嵌入在编译期完成，与运行期往对象上挂函数的做法相比：
| | 嵌入 | 运行期注入 |
| ------ | -------- | ------- |
| 方法是否存在 | 编译期确定 | 运行期才知道 |
| 类型检查 | 有 | 无 |
| 调用开销 | 与内置方法相同 | 多一次动态查找 |
| 出错时机 | 编译失败 | 运行时报错 |
| 作用范围 | 只影响自己的类型 | 全局或按实例 |
代价是扩展方法必须在编译期就写好，不能由配置文件或用户输入动态决定。
需要那种灵活度时，用一张 `map[string]func(*iztro.Astrolabe) bool` 自行分派。
# 错误处理 (/zh/docs/go/errors)
*Error 的 Code 分类、四个哨兵、触发条件与处理模式。
需要计算的入口都返回 `(值, error)`。日期格式、日期存在性、年份范围、
时辰索引在核心层前置校验；性别、语言、标识、配置这些字符串取值在绑定层校验。
纯查询方法（`Palace`、`Star`、`Has` 等）不返回错误，查不到时返回 `nil` 或零值。
## \*Error [#error]
包内所有失败都返回同一个具体类型：
```go
type Error struct {
Code string // 机器可读的类别，Code* 常量之一
Message string // 错误描述原文（英文）
}
func (e *Error) Error() string // 返回 "iztro: " + Message
func (e *Error) Unwrap() error // 返回本类别的哨兵，供 errors.Is 匹配
```
### 四个类别 [#四个类别]
| 哨兵 | `Code` 常量 | 取值 | 含义 |
| --------------------- | ---------------------- | -------------------- | ------------------------------------ |
| `ErrInvalidDate` | `CodeInvalidDate` | `invalid_date` | 日期格式非法、日期不存在，或超出公历 1583–9999 |
| `ErrInvalidTimeIndex` | `CodeInvalidTimeIndex` | `invalid_time_index` | 时辰索引越界（合法值 0–12） |
| `ErrInvalidArgument` | `CodeInvalidArgument` | `invalid_argument` | 其余入参或配置非法：性别、语言、星耀标识、自定义表 |
| `ErrInternal` | `CodeInternal` | `internal` | 库内部缺陷或 Go 侧运行时故障，如 wasm 实例化失败、结果解码失败 |
`Code` 的四个取值与 Rust 的 `IztroError::code()`、Python 的 `IztroError.code`
是同一套，跨语言分支逻辑可以照抄。
### 两种判断姿势 [#两种判断姿势]
```go
_, err := iztro.BySolar("2000-2-30", 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
// 按类别分支：errors.Is 对哨兵匹配
fmt.Println(errors.Is(err, iztro.ErrInvalidDate))
fmt.Println(errors.Is(err, iztro.ErrInvalidTimeIndex))
// 要拿 Code 与原文：errors.As 取出具体类型
var e *iztro.Error
if errors.As(err, &e) {
fmt.Println(e.Code, "|", e.Message)
}
fmt.Println(err)
```
**输出**
```text
true
false
invalid_date | invalid solar date '2000-2-30': day is out of range for that month
iztro: invalid solar date '2000-2-30': day is out of range for that month
```
`Error()` 在 `Message` 前补 `iztro: `，与调用方自己的错误容易区分；
`Message` 字段本身不带前缀。消息主体来自核心层，三种语言绑定完全一致，
但**文案会随版本调整**——要在程序里分支请用 `errors.Is` 或 `Code`，别解析文案。
***
## 日期相关 [#日期相关]
| 情形 | 例 | 消息主体 |
| --------------- | ------------- | ------------------------------------ |
| 格式不是 `YYYY-M-D` | `"2000/8/16"` | `expected 'YYYY-M-D'` |
| 年、月、日不是数字 | `"abc-8-16"` | `year is not a number` |
| 月份越界 | `"2000-13-1"` | `month must be within 1-12` |
| 该月没有这一天 | `"2000-2-30"` | `day is out of range for that month` |
| 年份超出支持范围 | `"1500-1-1"` | `year must be within 1583-9999` |
`Code` 为 `invalid_date`。农历专有（只有 `ByLunar` 与两个 `*ByLunarDate` 查询会碰到）：
| 情形 | 例 | 消息主体 |
| --------- | -------------------- | ------------------------------------------ |
| 该农历年没有这个月 | 表内缺月 | `month does not exist in that lunar year` |
| 该农历月没有这一天 | `"2000-7-30"`（七月是小月） | `day is out of range for that lunar month` |
农历消息的前缀是 `invalid lunar date '<原串>': `，公历是 `invalid solar date '<原串>': `，
从消息就能看出走的是哪个入口。
**示例**
```go
for _, date := range []string{"2000-13-1", "2000-2-30", "1500-1-1"} {
if _, err := iztro.BySolar(date, 2, iztro.GenderFemale, true, iztro.LanguageZhCN, nil); err != nil {
fmt.Println(err)
}
}
```
**输出**
```text
iztro: invalid solar date '2000-13-1': month must be within 1-12
iztro: invalid solar date '2000-2-30': day is out of range for that month
iztro: invalid solar date '1500-1-1': year must be within 1583-9999
```
消息里带上了原始输入，便于在批量处理时定位是哪一条数据出的问题。
**边界与陷阱**
1582 年格里历改革当年有一段不存在的日期。底层历法库在这些日期上没有定义，
因此支持范围从改革完成后的 1583 年起算。上限 9999 是农历数据表的覆盖终点。
`"2000-8-16"` 与 `"2000-08-16"` 都接受。分隔符必须是 `-`。
`ByLunar` 会检查该农历年该月是否真的存在，以及该月有多少天（大月 30、小月 29）。
`leap` 标为闰月但那年那月无闰月时不报错，按普通月处理；`leap` 不是三个 `LeapMonth` 取值之一时返回 `ErrInvalidArgument`。
***
## 时辰索引 [#时辰索引]
**触发条件** 时辰索引大于 12。
**示例**
```go
_, err := iztro.BySolar("2000-8-16", 13, iztro.GenderFemale, true, iztro.LanguageZhCN, nil)
fmt.Println(err)
```
**输出**
```text
iztro: time_index must be 0-12, got 13
```
**边界与陷阱**
子时跨午夜，拆成早子时（索引 0）与晚子时（索引 12），因此合法值有 13 个。
从小时数换算用 [`TimeToIndex`](/zh/docs/go/util#timetoindex)，它保证结果落在合法范围。
***
## 性别与语言 [#性别与语言]
`Code` 均为 `invalid_argument`。
| 参数 | 合法值 | 消息主体 |
| ---------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `gender` | `"male"` / `"female"`（`GenderMale` / `GenderFemale` 常量） | `invalid gender 'x': expected 'male' or 'female'` |
| `language` | 六个语言代码（`Language*` 常量） | `invalid language 'xx': expected one of zh-CN, zh-TW, en-US, ja-JP, ko-KR, vi-VN` |
语言代码大小写不敏感，连字符与下划线等价（`"zh-cn"`、`"zh_cn"` 都接受）。
`gender` 与 `language` 是具名类型 `Gender` / `Language`，把别的字符串变量误传进来会在编译期被挡下；
字面量拼错则在运行期落到这一类错误。
**示例**
```go
_, err := iztro.BySolar("2000-8-16", 2, "x", true, iztro.LanguageZhCN, nil)
fmt.Println(err)
fmt.Println(errors.Is(err, iztro.ErrInvalidArgument))
```
**输出**
```text
iztro: invalid gender 'x': expected 'male' or 'female'
true
```
***
## 标识相关 [#标识相关]
工具函数与安星函数收的是语言无关标识，未知标识会报错：
```go
_, err := iztro.GetBrightness("nosuch", 0, nil)
fmt.Println(err)
```
**输出**
```text
iztro: unknown star key 'nosuch'
```
这些函数只认标识不认译名。传 `"紫微"` 会得到 `unknown star key '紫微'`——
先用 [`KeyOf`](/zh/docs/go/i18n#keyof) 换算。
例外是 `chart.Palace()`、`chart.Star()` 这类**星盘上的查询方法**，
它们同时接受标识与当前排盘语言的译名。
***
## 配置相关 [#配置相关]
`Config` 的六个开关与两张自定义表都在排盘时校验，`Code` 均为 `invalid_argument`：
| 情形 | 消息主体 |
| ------------ | -------------------------------------------------------------------------------- |
| 开关取值未知 | `invalid yearDivide 'nope': expected 'normal' or 'exact'` |
| 四化表的天干标识未知 | `invalid mutagens key 'nope': unknown heavenly stem` |
| 某个天干的四化不是四项 | `invalid mutagens for 'jiaHeavenly': expected 4 stars (lu, quan, ke, ji), got 1` |
| 某颗星的亮度表不是十二项 | `invalid brightness for 'ziweiMaj': expected 12 entries, got 1` |
长度是**严格**校验：四化必须正好四项、亮度必须正好十二项，多一项少一项都报错。
自定义表只收标识不收译名。
***
## 处理模式 [#处理模式]
**批量处理时跳过坏数据**
```go
rows := []struct {
Date string
TimeIndex uint8
Gender iztro.Gender
}{
{"2000-8-16", 2, "female"},
{"2000-2-30", 2, "female"},
{"1990-3-3", 13, "male"},
}
var charts []*iztro.Astrolabe
var failed []string
for _, r := range rows {
chart, err := iztro.BySolar(r.Date, r.TimeIndex, r.Gender, true, iztro.LanguageZhCN, nil)
if err != nil {
var e *iztro.Error
errors.As(err, &e)
failed = append(failed, r.Date+" -> "+e.Code)
continue
}
charts = append(charts, chart)
}
fmt.Println(len(charts), failed)
```
**输出**
```text
1 [2000-2-30 -> invalid_date 1990-3-3 -> invalid_time_index]
```
**包装成自己的错误**
```go
build := func(date string, ti uint8, gender iztro.Gender) (*iztro.Astrolabe, error) {
chart, err := iztro.BySolar(date, ti, gender, true, iztro.LanguageZhCN, nil)
if err != nil {
return nil, fmt.Errorf("排盘失败: %w", err)
}
return chart, nil
}
_, err := build("2000-2-30", 2, "female")
fmt.Println(err)
fmt.Println(errors.Is(err, iztro.ErrInvalidDate))
```
**输出**
```text
排盘失败: iztro: invalid solar date '2000-2-30': day is out of range for that month
true
```
`%w` 保留原错误，调用方可以用 `errors.Is` / `errors.As` 继续判断到具体类别。
***
## 关于 nil [#关于-nil]
查询方法查不到时返回 `nil` 而非错误——查不到是正常结果，不是异常：
```go
p := chart.Palace("nosuchPalace")
fmt.Println(p == nil)
s, sp := chart.Star("nosuchStar")
fmt.Println(s == nil, sp == nil)
fmt.Println(chart.Palace(iztro.PalaceSoul).Has("ziweiMj"))
```
**输出**
```text
true
true true
false
```
`chart.Palace(...)`、`chart.Star(...)`、`h.ScopeItem(...)` 都可能返回 `nil`。
直接取字段会 panic。
上面三行都是「拼错了」而不是「盘上没有」：宫名少写一个字母得到 `nil`，
星名少写一个字母让 `Has` 返回 `false`——与真实的「没有这颗星」无法区分。
用包里的 `Palace*` / `Star*` 常量可以让编译器与 IDE 在写错的当场挡下。
名字来自外部输入时，先用 [`KeyOf`](/zh/docs/go/i18n#keyof) 过一遍：
它对无法识别的文本返回空串，可以据此拒绝非法输入。
`chart.Palace("bodyPalace")` 与 `chart.Palace("originalPalace")` 在任何一张盘上都非 `nil`：
来因宫要求宫干与生年干相同且不在子、丑二宫，而寅到酉这十宫刚好把十天干各走一遍，
因此生年干必然命中且只命中一次。真拿到 `nil`，那就是名字拼错了。