x-iztro
x-iztroRustPythonGo

知识包

KnowledgePack 与各条目结构体、内嵌默认包、JSON 解析、覆盖包合并与错误处理。

知识包是「语言无关标识 → 解读文本与门派属性」的 JSON。内核只判事实， 解读文本与星耀的门派属性放在这里。概念、格式与写覆盖包的方法见 知识包指南，完整字段表见仓库的 knowledge/SCHEMA.md。

pack, err := iztro.BuiltinKnowledgePack(iztro.LanguageZhCN)
intro := pack.StarIntro(iztro.StarZiweiMaj)

取键的方法都收 string，传 StarXxx / PatternXxx / PalaceXxx / MutagenXxx 常量即可。 默认包与合并都在内嵌的 wasm 内核里，本包只做 JSON 编解码。

类型

KnowledgePack

字段全部导出，带 json 标签，可直接用 encoding/json 编解码。

字段类型说明
Schemaint格式版本，当前为 1
IDstring包标识，默认包为 "iztro-docs"
Versionstring包版本，默认包为「抓取日期+来源 commit 短号」
Languagestring文本语言的语言码，如 LanguageZhCN
Extendsstring覆盖包所覆盖的包标识；独立包为空串
SourceKnowledgeSource来源与许可
Starsmap[string]StarEntry星耀条目，键为星耀标识
Patternsmap[string]PatternEntry格局条目，键为格局标识
Palacesmap[string]TextEntry宫位条目，键为宫位标识
Mutagensmap[string]TextEntry四化条目，键为四化标识
Conceptsmap[string]ConceptEntry术语条目，键为 slug

KnowledgeSource

Name、URL、Commit、License、Author、RetrievedAt、Adapted（改编说明），都是 string，缺省为空串。

StarEntry

字段类型说明
Namestring该语言的显示名
Categorystring类别："major" / "minor" / "adjective" / "dec" / "flow"（流耀，指向对应本命辅星的对照性条目）
Groupstring分组：杂耀的分类、神煞的组别
AttributesStarAttributes门派属性
Introstring解读正文（Markdown）
Combinationsmap[string]string与另一颗主星同宫的组合解读，键为对方星耀标识

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 逐值一致。 原因见指南。

PatternEntry

Name、Quotes（[]string）、Conditions、Intro。

TextEntry / ConceptEntry

TextEntry（宫位、四化）有 Name 与 Intro；ConceptEntry（术语）有 Title 与 Intro。

缺省一律是零值

Go 侧不用指针区分「没写」与「写了空串」，字段缺省即空串 / nil。 要判断某条到底有没有正文，比空串即可。

BuiltinKnowledgePack

用途　取内嵌的默认知识包。

签名

func BuiltinKnowledgePack(language Language) (*KnowledgePack, error)
func BuiltinKnowledgePackContext(ctx context.Context, language Language) (*KnowledgePack, error)

参数

参数类型说明
ctxcontext.ContextContext 变体专有，用于取消等待 wasm 实例
languageLanguage文本语言

返回值　(*KnowledgePack, error)。该语言没有内嵌默认包时返回错误 （可用 errors.Is(err, iztro.ErrInvalidArgument) 匹配）。目前只有 LanguageZhCN 有。

示例

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

输出

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

用途　由 JSON 文本解析一份包。

签名

func ParseKnowledgePack(data []byte) (*KnowledgePack, error)

返回值　(*KnowledgePack, error)。JSON 不合法、schema 缺失或为 0、 schema 高于本库支持的版本，都返回 ErrInvalidArgument 类的错误—— 与 Rust 内核解析（KnowledgePack::from_json）同语义。

序列化直接用 encoding/json：

data, err := json.Marshal(pack)

示例

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)

输出

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

用途　把若干覆盖包依次叠加到本包上，返回新包。

签名

func (p *KnowledgePack) Merged(overlays ...*KnowledgePack) (*KnowledgePack, error)
func (p *KnowledgePack) MergedContext(ctx context.Context, overlays ...*KnowledgePack) (*KnowledgePack, error)

参数

参数类型说明
ctxcontext.ContextContext 变体专有，用于取消等待 wasm 实例
overlays...*KnowledgePack覆盖包，按传入顺序依次叠加，后面的覆盖前面的

返回值　新的 *KnowledgePack，本包与覆盖包都不变。 接收者为 nil、某个覆盖包为 nil、或某个包的 schema 不合法 （手工构造的结构体也在这里被内核校验），都返回 ErrInvalidArgument 类的错误。

合并规则见指南：逐段按键合并， 覆盖包的非空字段覆盖同键条目的对应字段，Attributes 与 Combinations 逐字段合并， 数组字段整体替换。合并本身在 wasm 内核里算，三语言结果一致。

示例

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)

输出

my-school 紫微 [帝座] 尊贵 我的紫微
我的紫府同宫 [紫府同宫终身福厚。]
紫微星号称
iztro: mergeKnowledgePacks: nil overlay pack

Star / Pattern / Palace / Mutagen / Concept

用途　按语言无关标识取条目。

签名

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。 返回的是条目的副本地址，改它不影响包本身。

示例

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)

输出

紫微 major 中天星系 [帝王星 老板星 俸禄星]
true
命宫 化禄
遇、加、逢、同宫、同度
true

StarIntro / PatternIntro

用途　直接取解读正文。

签名

func (p *KnowledgePack) StarIntro(starKey string) string
func (p *KnowledgePack) PatternIntro(patternKey string) string

返回值　条目不存在、或条目存在但没写正文，都返回空串。

示例　把本命格局连同引文列出来：

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]))
}

输出

府相朝垣 | 府相朝垣命必荣
“食禄千锺”的断语使

TextOptions

用途　ToTextWith 家族（ToTextWith / PalaceToTextWith / SurroundedPalacesToTextWith / PatternsToTextWith 与 Horoscope 上的同名方法）的输出选项：释义材料来源与格局判定口径。 零值只输出盘面事实、按默认口径判格局，与不带 With 的方法输出逐字节相同。

定义

type TextOptions struct {
    Knowledge     Knowledge
    PatternConfig *PatternConfig
}

字段

字段类型说明
KnowledgeKnowledge释义材料来源；零值不带释义。给出时每宫事实之后紧跟该宫星耀释义、格局列表之后紧跟格局释义、本命文本末尾附 ## 四化释义，见带释义的文本
PatternConfig*PatternConfig格局判定口径，与 Patterns(config) 同一入参；同时作用于文本的格局节与格局释义。nil 取内核默认

示例

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})

输出

true 3389 20767

Knowledge / BuiltinKnowledge / KnowledgeFrom

用途　TextOptions 的 Knowledge 字段取值：ToTextWith 家族的释义材料来源。

签名

type Knowledge struct { /* 不导出 */ }

func BuiltinKnowledge() Knowledge
func KnowledgeFrom(pack *KnowledgePack) Knowledge

取值

取值含义
BuiltinKnowledge()用盘语言的内嵌默认包；该语言没有内嵌包（目前只有 zh-CN 有）时方法返回 ErrInvalidArgument，不静默回退
KnowledgeFrom(pack)用给定的包（自定义或 Merged 之后的包）；pack 为 nil 等同零值
Knowledge{}（零值）不带释义，TextOptions{} 的输出与不带 With 的方法逐字节相同

示例

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

用途　按盘取材：裁出只含这张盘相关条目的子包。

签名

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)

参数

参数类型说明
ctxcontext.ContextContext 变体专有，用于取消等待 wasm 实例
chart*Astrolabe取材依据的星盘；重排盘按重排后的布局取材
horoscope*Horoscope由 chart.Horoscope(...) 得到的运限，本命部分随之取材
config*PatternConfig格局判定口径，与 Patterns(config) 同一入参；传 nil 取默认

返回值　(*KnowledgePack, error)。标准知识包，元信息沿用本包：Stars 是盘上出现的星 （主辅杂与四组十二神，14 主星的 Combinations 只留对方主星确在同宫的）， Patterns 是按 config 口径命中的格局，Mutagens 四条全留，Palaces 与 Concepts 为空。 ForHoroscope 在此之上再加各层流耀与大限到流时各层视角命中的格局。 子包要和 Patterns(config) / PatternsToTextWith 配同一口径：口径不同，命中集合不同， 释义就会缺项或多项。 取材以本包当前内容为准（整包发给内核），就地改过的条目照样进入子包。 接收者或入参为 nil、运限不是由 Astrolabe.Horoscope 得到时返回 ErrInvalidArgument。 取材规则见按盘取材。

示例

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

输出

108 1 4 0
tianxiangMaj
158 16

武曲在这张盘上与天相同宫，所以子包里武曲的 Combinations 只剩天相一条。

Knowledge.ForAstrolabe / Knowledge.ForHoroscope

用途　用 Knowledge 哨兵按盘取材。BuiltinKnowledge() 时内核直接读内嵌包， 不必先 BuiltinKnowledgePack 拿整包再送回去；KnowledgeFrom(pack) 时等同 pack.ForAstrolabe 系列。

签名

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。

示例

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

输出

108 1

翻译

标识与译名的双向查找。

反推

SolarDatesByBazi 与 ReverseChart：由八字四柱或星盘特征反查候选生辰的函数与类型。

本页目录

类型KnowledgePackKnowledgeSourceStarEntryStarAttributesPatternEntryTextEntry / ConceptEntryBuiltinKnowledgePackParseKnowledgePackMergedStar / Pattern / Palace / Mutagen / ConceptStarIntro / PatternIntroTextOptionsKnowledge / BuiltinKnowledge / KnowledgeFromForAstrolabe / ForHoroscopeKnowledge.ForAstrolabe / Knowledge.ForHoroscope