# 语义化文本（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`                      | 小限落宫与虚岁                                                                                               |
| `\| 大限 \| 本命 \| 主星 \| 辅星 \| 流耀 \|`              | 运限层十二宫表：第一列是**这一层重排后的宫名**，第二列是本命宫名，主星辅星是本命盘的，流耀是这一层的                                                  |
| `- 宫名: 命宫→本命官禄, …`                              | 小限、流月及以下层级不展开十二宫表，改用这一行给出对应：从该层命宫起顺排，箭头左边是该层重排宫名、右边是本命宫名                                              |
| `**紫微(庙)**: 正文`                                 | 释义条目（[带知识包](#带释义的文本)时才有）：标题是星、格局或四化的写法，正文是知识包原文                                                       |
| `**紫微 × 天府 (同宫)**: 正文`                          | 同宫主星的组合解读                                                                                             |
| `成立条件: …`                                       | 格局释义正文末尾的成格条件                                                                                         |

<Callout type="warn" title="运限表第一列是这一层的宫名，别读反">
  `| 夫妻 | 财帛 | …` 说的是「这一格在本大限里叫夫妻宫，它在本命盘上是财帛宫」。
  运限解读要以第一列为准，第二列是为了让你能对回本命盘。
  见[运限](/zh/docs/guide/concepts/horoscope#同一个格子宫名会变)。
</Callout>

日期字段原样回显入参，不补零：传 `"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)
```

同一张盘传不同的包，事实部分逐字节相同，只有释义条目随包变。

<Callout type="warn" title="英文盘没有内嵌包">
  内嵌默认包只有 zh-CN。英文（及其他四种语言）盘上 `knowledge=True` / `BuiltinKnowledge()` /
  `KnowledgePack::builtin(Language::EnUS)` 报 `invalid_argument`，不会静默退回到无释义。
  显式传一份包即可——包的语言不受盘语言限制，英文盘配中文包得到英文标题、中文正文。
</Callout>

## 六种语言 [#六种语言]

结构标签（「基本信息」「主星」「三方四正」「大限」……）有 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 现翻，不是拿盘上固化的译名，所以不会出现混排。

<Callout title="用中文盘还是英文盘">
  优先用中文盘。英文盘的星名走 iztro 的意译词表（紫微是 `emperor`、七杀是 `marshal`），
  亮度退化成 `[+3]` 这类记号，四化写成 `[A]`/`[B]`/`[C]`/`[D]`，
  流耀的英文名自带层级后缀（运曲是 `artist(D)`、流禄是 `money(Y)`），
  年解的英文名 `considery(Y)` 里的 `(Y)` 也是星名的一部分——
  这套写法与英文命理界的通行译法不同，模型未必认得。

  主流模型的中文命理术语能力都不差，直接喂中文文本效果更好。
  确实需要英文时，建议附上一份[星名对照表](/zh/docs/guide/concepts/stars#星名对照表)。
</Callout>

## 接入大模型 [#接入大模型]

生成的文本是纯描述，不含指令。实际使用时在前面加上你的分析要求：

```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)。