# 介绍 (/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 实现，通过三套绑定暴露给上层编程语言：

<Cards>
  <Card title="Rust" href="/zh/docs/guide/getting-started/rust" description="原生 crate，零拷贝的强类型结构体" />

  <Card title="Python" href="/zh/docs/guide/getting-started/python" description="PyO3 原生扩展，dataclass 类型化 API" />

  <Card title="Go" href="/zh/docs/guide/getting-started/go" description="内嵌 WebAssembly，纯 Go 运行时，无 cgo" />
</Cards>

## 它解决什么问题 [#它解决什么问题]

紫微斗数排盘看似只是查表，实际上牵扯一连串容易出错的历法与流派细节：农历闰月的处理、
晚子时算今天还是明天、年干支按正月初一还是立春换年、虚岁怎么进位、不同流派的四化表差异。
任何一处取舍不同，排出的盘就不是同一张。

社区里最完整的开源实现是 JavaScript 的 [iztro](https://github.com/SylarLong/iztro)，
但它只能在 JS 运行时里用。x-iztro 把这套逻辑完整移植到 Rust，
让服务端、数据分析脚本、命令行工具、移动端也能用上同一套排盘结果。

<Callout title="与 iztro 的关系">
  x-iztro 是 iztro v2.6.1 的移植，不是重新发明。凡是 iztro 有的功能与数据，
  两者结果必须逐字段一致 —— 这条由 716,314 例金标测试守着，
  详见[准确性保证](/zh/docs/guide/about/accuracy)。
</Callout>

## 特性 [#特性]

### 一键转成 AI 能读的文字 [#一键转成-ai-能读的文字]

内置语义化文本投影（to\_text）：把一张盘或一段运限投影成上面那种自然语言文本，
直接交给大模型分析，不必自己拼接命盘描述。见[语义化文本](/zh/docs/guide/guides/to-text)。

### 排盘与运限完整 [#排盘与运限完整]

本命盘、大限、小限、童限、流年、流月、流日、流时，六个层级的宫位、星耀、四化与
三方四正全部可取。年系杂耀、岁前十二神、将前十二神、博士十二神、长生十二神一应俱全。

### 流派与分界点可配置 [#流派与分界点可配置]

`Config` 的六个开关覆盖了实践中会分歧的每一处：年分界点、运限分界点、虚岁分界点、
晚子时归属、算法派别（默认 / 中州派）、排盘视角（天盘 / 地盘 / 人盘），
另可整表替换四化表与亮度表。默认值与 JS iztro 一致，
细节见 [Config 详解](/zh/docs/guide/guides/config)。

### 六种盘面语言 [#六种盘面语言]

简体中文、繁体中文、英文、日文、韩文、越南文。同一张盘换盘面语言只是换一次翻译，
排盘结果不受影响。

### 中文盘、英文盘，判断结果一样 [#中文盘英文盘判断结果一样]

<small>
  给开发者
</small>

星名宫名在不同盘面语言下文本不同，但每个实体都额外带一个稳定的标识（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)。

## 从哪读起 [#从哪读起]

<Cards>
  <Card title="不写代码怎么用它" href="/zh/docs/guide/guides/for-non-developers" description="能做什么、典型场景、要跟工程师交代哪几件事" />

  <Card title="快速开始" href="/zh/docs/guide/getting-started" description="装上它，跑出第一张盘" />

  <Card title="紫微斗数概念" href="/zh/docs/guide/concepts" description="不懂命理也能看懂：一张盘由什么构成，字段各自是什么意思" />

  <Card title="Rust API 参考" href="/zh/docs/rust" description="核心库的函数签名、类型与方法" />

  <Card title="Python API 参考" href="/zh/docs/python" description="dataclass 类型化 API 的完整条目" />

  <Card title="Go API 参考" href="/zh/docs/go" description="导出函数、类型与方法的完整条目" />

  <Card title="数据结构字典" href="/zh/docs/guide/data-model" description="每个字段的类型与含义，三种编程语言共用的契约" />

  <Card title="准确性保证" href="/zh/docs/guide/about/accuracy" description="716,314 例金标测试如何保证与 iztro 零差异" />
</Cards>