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

输出

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

翻译

标识与译名的双向查找。

反推

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

本页目录

类型KnowledgePackKnowledgeSourceStarEntryStarAttributesPatternEntryTextEntry / ConceptEntryBuiltinKnowledgePackParseKnowledgePackMergedStar / Pattern / Palace / Mutagen / ConceptStarIntro / PatternIntro