跳到正文

开放代码与数据

API 文档

通过英文 API 调用 Nhat Nguyet 的五个 JavaScript 包与 Python 包:参数按名称传入,使用钟点时间,结果按所选语言输出。代码下方的输出均为真实结果。

安装

# JavaScript, TypeScript
npm install @nhatnguyet/lunar @nhatnguyet/ziwei
npm install @nhatnguyet/bazi @nhatnguyet/numerology @nhatnguyet/festivals
# 同一代码的越南语包名:am-lich、tu-vi、bat-tu、than-so-hoc、le-hoi
# Python
pip install nhatnguyet

每个包都保留原有的越南语命名函数(lapLaSoTuVi、solarToLunar...),并另有一层并行的英文 API,参数按名称传入:

  • 日期可写作 "YYYY-MM-DD"、{ year, month, day } 或一个 Date(按本地时间读取);
  • 钟点写作 "HH:MM"(24 小时制),由程序包自行换算为时辰(子时为 23:00 至 00:59);
  • 性别为 "male" / "female";
  • lang: "en" | "vi" | "zh"(默认 "en")决定结果中所有名称的语言;
  • terms: "pinyin" | "han" | "vi"(仅用于英文,见下文);
  • 原始对象原样保留在 raw 中,不丢失任何内容。

天干、地支与四化:terms

十天干、十二地支、干支组合、四化以及旬空、截空两个空亡标记都没有英文译名。在 lang: "en" 下,由 terms 选项决定其写法:

terms天干、地支干支四化空亡
"pinyin"(默认)Geng, WuGeng WuHua Lu, Hua Quan, Hua Ke, Hua JiXun Kong, Jie Kong
"han"庚, 午庚午化禄, 化权, 化科, 化忌旬空, 截空
"vi"Canh, NgọCanh NgọHóa Lộc, Hóa Quyền, Hóa Khoa, Hóa KỵTuần, Triệt

拼音不标声调,与英文八字、紫微斗数书籍的写法一致,因此 戊 与 午 都是 "Wu",己 与 忌 都是 "Ji";需要区分时请选 "han"。"vi" 给出越南历书所印的汉越名称(即 0.2.0 版的输出)。凡有英文名称者(五行、生肖、节气、宫位、星曜、格局名、十神、长生十二宫)不论 terms 如何都用英文,英文文本中也绝不夹带越南语词(有一项测试会扫描每个测试用例中的越南语字母)。lang: "vi" 始终为越南语,lang: "zh" 始终为汉字。代码不随语言变化:nameVi、code(流年星)、id(节庆)。 枚举值在任何 lang 下也都是英文代码:gender(male、female)、紫微星曜的 kind 与 group、流年星的 toYearPalace、toMinorLimit 与 toDecade(same-palace、opposite、trine 或 "")、八字的 luck.direction(forward、backward)与 symbolicStars[].pillars(year、month、day、hour)、节气的 kind(jie、qi),以及节日的 calendar、group 与 scope。

TypeScript 与 Python 返回相同的键(camelCase),两个命令行工具输出逐字节相同。下文所有输出均由实际运行代码得到。

农历:@nhatnguyet/am-lich

import { toLunar, toSolar, solarTerms, dayPillar, hourBranch } from "@nhatnguyet/am-lich";

toLunar("2027-02-06");
// {"year":2027,"month":1,"day":1,"leap":false,"solarDate":"2027-02-06","country":"VN","timeZone":7,
//  "yearName":"Ding Wei","monthName":"Ren Yin","dayName":"Bing Chen","zodiac":"Goat",
//  "solarTerm":"Start of Spring","lang":"en"}
toLunar("2027-02-06", { terms: "han" }).yearName;   // "丁未"

toLunar("1985-01-21", { country: "CN", lang: "zh" });   // Tết 1985: Vietnam and China differ
// {"year":1984,"month":12,"day":1,"leap":false,"solarDate":"1985-01-21","country":"CN","timeZone":8,
//  "yearName":"甲子","monthName":"丁丑","dayName":"庚申","zodiac":"鼠","solarTerm":"大寒","lang":"zh"}

toSolar({ year: 2023, month: 2, day: 1, leap: true });
// {"day":22,"month":3,"year":2023,"date":"2023-03-22"}
// A lunar date that does not exist (no such leap month, day 30 of a 29-day month) throws RangeError.

solarTerms(2027, { country: "CN" })[2];
// {"index":21,"longitude":315,"name":"Start of Spring","nameVi":"Lập Xuân","kind":"jie",
//  "date":"2027-02-04","time":"09:46","timeZone":8}

dayPillar("1990-09-19");
// {"label":"Ding Hai","stem":"Ding","branch":"Hai","stemIndex":3,"branchIndex":11,"stemElement":"Fire",
//  "branchElement":"Water","naYin":"Earth on the Roof","naYinElement":"Earth"}

hourBranch("23:30");
// {"index":0,"name":"Zi","animal":"Rat","range":"23:00-00:59"}

黄道吉时:auspiciousHours

一日十二时辰,每个时辰标明为黄道(giờ hoàng đạo)或黑道(giờ hắc đạo),并附值时之神,与越南历书的印法相同。每天都有六个黄道吉时,是哪六个只取决于日支。诸神从青龙(Thanh Long)起依次轮转,青龙所起的时辰由日支所在的相冲地支对决定;黄道诸神为轮转中的第 0、1、4、5、7、10 位(AUSPICIOUS_SPIRITS)。钟点范围按越南时间。spirit 与干支一样遵循 terms:默认为拼音,"han" 为汉字,"vi" 为越南语名称(第六位神,即典籍时辰表中的 宝光 Bao Guang,在越南历书中称 Kim Đường)。

import { auspiciousHours } from "@nhatnguyet/am-lich";

auspiciousHours("2027-02-06").day;   // "Bing Chen"
auspiciousHours("2027-02-06").hours[4];
// {"index":4,"branch":"Chen","animal":"Dragon","range":"07:00-08:59","auspicious":true,
//  "spirit":"Qing Long","spiritIndex":0}
auspiciousHours("2027-02-06").hours.filter((h) => h.auspicious).map((h) => h.range);
// ["03:00-04:59","07:00-08:59","09:00-10:59","15:00-16:59","17:00-18:59","21:00-22:59"]
auspiciousHours("2027-02-06", { lang: "zh" }).hours[9].spirit;   // "宝光"

结果已在 1,096 个测试向量(ca-kiem/auspicious-hours.json)上与参考引擎逐一核对。Python 用 auspicious_hours(date, lang=..., terms=...),命令行用 nhatnguyet hours 2027-02-06,MCP 工具为 auspicious_hours。

country 可取 VN(默认,UTC+7)、CN、TW、HK、MO、SG、MY、ID、PH(UTC+8)、KR、JP(UTC+9);规则相同,只是决定日期的当地时间不同。timeZone 可覆盖它。越南第四个生肖是猫,其他地方是兔。另有:solarTermOn(date)、yearPillar(lunarYear)、solarTermNames()、parseDate、parseTime、stemBranchName(label, lang, terms)、termName(vi, lang, terms)。

紫微斗数:@nhatnguyet/tu-vi

import { castZiWei, decadeLuck, yearlyLuck, yearlyStars, findPatterns, ziWeiSvg } from "@nhatnguyet/tu-vi";

const chart = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male", viewYear: 2026 });
chart.hour;     // {"index":10,"name":"Xu","animal":"Dog","range":"19:00-20:59"}
chart.lunar;    // {"year":1990,"month":8,"day":1,"leap":false}
chart.bureau;   // {"number":5,"name":"Earth Five"}
chart.yinYang;  // "Yang Male"
chart.palaces[chart.lifePalace];
// {"index":11,"branch":"Hai","stemBranch":"Ding Hai","name":"Life Palace","nameVi":"Mệnh","isLife":true,
//  "isBody":false,"tuan":true,"triet":false,"stars":[{"name":"Moon","nameVi":"Thái Âm","kind":"major",
//  "brightness":"Exalted","transformation":"Hua Ji"},{"name":"Left Assistant","nameVi":"Tả Phù","kind":"minor",
//  "group":"auspicious"}, ...]}

decadeLuck(chart)[3];
// {"order":4,"palaceIndex":2,"branch":"Yin","palace":"Property","fromAge":35,"toAge":44,
//  "fromYear":2024,"toYear":2033,"majorStars":["Military Song","Celestial Minister"]}
yearlyLuck(chart).decade;       // {"fromAge":35,"toAge":44,"palace":"Property"}
findPatterns(chart)[1];
// {"name":"Left and Right Assistants Meeting","nameVi":"Tả Hữu đồng hội","condition":"Left Assistant and
//  Right Assistant both gather in the triangle and opposite of the Life palace", ...,"nameHan":"左右同會"}
chart.toSvg({ theme: "dark" }); // "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1000 10..."

const han = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male", terms: "han" });
han.palaces[han.lifePalace].stemBranch;                // "丁亥"
han.palaces[han.lifePalace].stars[0].transformation;   // "化忌"
  • 必须提供 time 或 hourBranch(0 = 子 ... 11 = 亥);两者不一致时抛出错误。
  • 23:00 至午夜出生者保留所输入的日期(有的典籍算作次日;如需按此法,请输入次日日期)。命盘在 notes 中注明这一点。
  • 年龄为虚岁(出生即 1 岁);fromYear/toYear 给出对应年份。
  • palaces 按地支编号,0(子)至 11(亥);kind 为 major、minor、growth(长生十二神)、year-ring(太岁十二神)或 scholar(博士十二神)。
  • 辅星带有 group:malefic(六煞星:擎羊、陀罗、地空、地劫、火星、铃星)、auspicious(六吉星,外加禄存与天马)或 miscellaneous(其余所有辅星)。原始命盘在 nhom 中保留核心代码;对应表为 STAR_GROUP_EN。
  • yearlyStars 的代码为 yearly-taisui、yearly-lucun、yearly-qingyang、yearly-tuoluo、yearly-tianma(YEARLY_STAR_CODE_EN;原始的 ma 保留核心代码)。
  • schools 在典籍说法不一之处切换规则(火星与铃星、闰月、庚干四化、天厨、天伤与天使);默认不变。见 schools.md:castZiWei({ ..., schools: { fireBell: "quanshu", leapMonth: "split-at-15" } })。此时命盘带有 schools(仅含非默认选项),并在 notes 中加一行说明。
  • country(与 toLunar 相同:默认 "VN",另有 "CN"、"KR"、"JP"……)或 timeZone(小时数)指定用哪国的农历把出生日期换成排盘所用的农历日期。各国历法在部分日子上不同:1985-01-21 出生,越南历为乙丑年正月初一,country: "CN" 则为甲子年十二月初一,命盘因此不同。不按 UTC+7 排的命盘带有 timeZone,并在 notes 中注明;Python 用 cast_zi_wei(..., country="CN") 或 time_zone=8,命令行用 nhatnguyet ziwei 1985-01-21 10:00 male --country CN。
  • 格局名为据中文原名译出的英文名,典籍原名放在 nameHan 中(terms: "vi" 保留汉越名称);lang: "zh" 给出 命宫、太阴、化忌、土五局。
  • 星曜名称遵循英文紫微斗数的惯用译法;其中三个与 Go 引擎的表不同:陀羅 Spinning Top、天相 Celestial Minister、天鉞 Celestial Halberd(STAR_EN_FIX)。
  • ziWeiSvg(chart, { theme, width, lang }) 与 chart.toSvg() 画出的 SVG 与 renderChartSvg(chart.raw) 相同。toSvg 不可枚举,因此不会出现在 JSON 中。

查询与运限

castZiWei 返回带查询方法的命盘(这些方法不可枚举,因此 JSON 不变);同样的函数也有独立版本,接受来自 castZiWei 或 lapLaSoTuVi 的命盘。宫位可用索引(0 = 子)或英文、越南文、中文名称指定(不区分大小写);星曜可用三种语言中任一名称指定。

import { castZiWei, horoscope, surroundingPalaces, flyingTransformations, fliesTo, selfTransformed, palaceIsEmpty } from "@nhatnguyet/tu-vi";

const chart = castZiWei({ date: "1990-09-19", time: "20:00", gender: "male" });
chart.palace("命宫").name;              // "Life Palace"
chart.star("Purple Star").palace.name;  // "Health"
surroundingPalaces(chart, "Life Palace");
// target "Life Palace", opposite "Travel", wealth "Wealth", career "Career"
flyingTransformations(chart, "Life Palace")[0];
// {"type":"Hua Lu","star":"Moon","palaceIndex":11,"palace":"Life Palace","self":true}
fliesTo(chart, "Life Palace", "Travel", "ji");  // false
selfTransformed(chart, "Life Palace");          // true
palaceIsEmpty(chart, "Spouse");                 // true (no major star)

const h = chart.horoscope({ date: "2026-11-19" });   // same as horoscope(chart, { date })
h.lunar;  // {"year":2026,"month":10,"day":11,"leap":false}
h.age;    // 37
h.decade;
// {"palaceIndex":2,"branch":"Yin","palace":"Property","stemBranch":"Wu Yin","palaceNames":[...],
//  "transformations":[{"type":"Hua Lu","star":"Greedy Wolf","palaceIndex":0,"palace":"Parents"}, ...],
//  "fromAge":35,"toAge":44}
h.minorLimit;  // {"palaceIndex":4,"branch":"Chen","palace":"Friends/Subordinates","stemBranch":"Geng Chen", ...}
h.year;
// {"palaceIndex":6,"branch":"Wu","palace":"Health","stemBranch":"Bing Wu","palaceNames":[...],
//  "transformations":[..., {"type":"Hua Ji","star":"Purity","palaceIndex":10,"palace":"Siblings"}],
//  "year":2026,"stars":[{"code":"yearly-taisui", ...}, {"code":"yearly-lucun","name":"Yearly Prosperity",
//  "byStem":true,"palaceIndex":5,"branch":"Si","palace":"Travel", ...}, ...]}
h.month;  // {"palaceIndex":6,"branch":"Wu","palace":"Health","stemBranch":"Ji Hai","palaceNames":[...],"transformations":[],"month":10}
h.year.palaceNames.slice(4, 8);  // ["Spouse","Siblings","Life Palace","Parents"]: index 6 (Ngọ) is the year's Life palace
h.day;    // null
h.hour;   // null
chart.horoscope({ date: "1991-03-01" }).decade;  // null: before the first ten-year period
  • 所有数值均来自引擎:decade 来自大限(decadeLuck),minorLimit、year 与 month 来自 yearlyLuck(小限、流年宫、当年四化、按斗君法排出的流月宫),year.stars 来自 yearlyStars。
  • 大限与小限的 transformations 是该宫宫干的四化,取自引擎的四化表,与 flyingTransformations、fliesTo、selfTransformed 的飞星路径同用一表。month.transformations 为空:引擎没有流月四化。
  • palaceNames(索引 0 = 子)以该运限的宫位为命宫,按命盘自身的顺序重新命名十二宫。
  • 在第一个大限之前(引擎没有童限规则)及第十二个大限之后,decade 为 null;day 与 hour 为 null(引擎没有流日、流时)。
  • 日期按越南历法(UTC+7)解读,与命盘一致;闰月按其所重复的月份计算。
  • 另有:palaceOf、starOf、flankingPalaces、palaceHas、palaceHasOneOf、palaceNotHave、withZiWeiMethods(chart)(为来自 localizeZiWei 的命盘加上这些方法)。iztro 风格的方法名(astrolabe.horoscope()、palace.fliesTo()...)见 从 iztro 迁移。

八字:@nhatnguyet/bat-tu

import { castBaZi, minorLuck, baZiSvg } from "@nhatnguyet/bat-tu";

const bz = castBaZi({ date: "1990-09-19", time: "20:00", gender: "male" });
bz.pillars.day.label;     // "Ding Hai"
bz.dayMaster;             // {"stem":"Ding","element":"Fire","yinYang":"Yin"}
bz.luck.startAge;         // {"years":6,"months":4}
bz.luck.pillars[0].label; // "Bing Xu"
castBaZi({ date: "1990-09-19", time: "20:00", gender: "male", terms: "han" }).pillars.day.label; // "丁亥"
bz.toSvg({ name: "An" }); // same as renderBaziSvg(bz.raw, { hoTen: "An" })

可省略 time(null):无时柱,起运从正午起算。约定:越南时间(UTC+7);年以立春为界,月以各节为界,日以 23:00 为界(schools: { ziHour: "split-at-midnight" } 使 23:00 至 24:00 仍用所输入日期的日柱,见 schools.md)。每柱含 tenGod、hiddenStems、naYin、stage、selfStage、stars;minorLuck(bz, 2026) 给出某年的小运柱("Ding Hai")。

数字命理:@nhatnguyet/than-so-hoc

import { numerology } from "@nhatnguyet/than-so-hoc";

const n = numerology({ name: "Nguyen Van An", birthDate: "1990-09-19", today: "2026-11-19" });
// lifePath 11, expression 3, soulUrge 1, personalYear 2, karmicDebt 19
n.labels.lifePath;   // "Life Path"  ("生命灵数" with lang: "zh")
n.toSvg();           // same as renderNumerologySvg(...)

保留主数 11、22、33。姓名中的变音符号会被去除,只计 A-Z 字母。另有 grid(出生日期中 1-9 各数字)、pinnacles(含 toAge)、challenges。

节庆:@nhatnguyet/le-hoi

import { festivals, festivalsIcs } from "@nhatnguyet/le-hoi";

festivals(2027)[2];
// {"id":"tet-nguyen-dan","date":"2027-02-06","name":"Lunar New Year (Tết)",...,"calendar":"lunar",
//  "fixedDate":"1/1","level":"major","group":"holiday","scope":"national","publicHoliday":true, ...}
festivals(2027).length;   // 164
festivalsIcs(2027);       // iCalendar (RFC 5545) text of the same list

数据集共收录 206 个节庆。festivals(year) 返回其中农历或公历日期固定的 164 个(1900 至 2100 年间每年都是这 164 个),按日期排序;其余 42 个由主办方逐年定日,列于 DANH_SACH_LE_HOI,已公布的日程见 lich_cong_bo。越南地名、人名在英文中保留变音符号。group 为 holiday、folk-religion 或 other,scope 为 national、regional、local、representative,数据集尚未分类时为 null;各 lang 下均为英文代码(数据集原代码保留在 raw 中)。lang: "zh" 给出 越南春节。

每个节庆还带有以下字段(各语言下键名均为同一套英文):provinces([{ code, name }],依 2025 年 34 个省级单位的区划;代码列于 PROVINCES)、nationwide(布尔值)、ethnicGroups(取自官方 54 个民族名录,仅在描述写明是哪个民族的节庆时才有)、venues([{ name, coordinates: { lat, lon } | null, sourceUrl: string | null }],仅在有来源时才给坐标)以及 daysBefore、daysAfter(围绕 date 的惯常节期)。festivalsIcs(year, { lang })(Python 用 festivals_ics(year, lang=...),命令行用 nhatnguyet festivals 2027 --ics)将同一列表写成 iCalendar:覆盖整个节期的全天事件、稳定的 UID <id>-<year>@nhatnguyet.org,数据集署名写在 X-WR-CALDESC 中。

Python

同样的函数,采用 snake_case 命名与关键字参数,结果键相同:

from nhatnguyet import cast_zi_wei, cast_bazi, to_lunar, numerology, festivals, decade_luck, zi_wei_svg

c = cast_zi_wei(date="1990-09-19", time="20:00", gender="male", lang="zh", view_year=2026)
c["palaces"][c["lifePalace"]]["name"]   # '命宫'
c["bureau"]                             # {'number': 5, 'name': '土五局'}
decade_luck(c)[3]["palace"]             # '田宅宫'
cast_bazi(date="1990-09-19", time="20:00", gender="male")["pillars"]["day"]["label"]   # 'Ding Hai'
cast_bazi(date="1990-09-19", time="20:00", gender="male", terms="vi")["pillars"]["day"]["label"]  # 'Đinh Hợi'
to_lunar("2027-02-06", country="KR")["month"]                                         # 12
numerology("Nguyen Van An", "1990-09-19", today="2026-11-19")["lifePath"]              # 11
festivals(2027, lang="zh")[2]["name"]                                                  # '越南春节'
svg = zi_wei_svg(c, theme="dark")

查询与运限(也可从 nhatnguyet 和 nhatnguyet.ziwei 导入)位于 nhatnguyet.tu_vi_chuc_nang(与 TypeScript 输出的 JSON 逐字节相同):

from nhatnguyet import cast_zi_wei
from nhatnguyet.tu_vi_chuc_nang import horoscope, palace_of, surrounding_palaces, flying_transformations, flies_to

c = cast_zi_wei(date="1990-09-19", time="20:00", gender="male")
horoscope(c, date="2026-11-19")["year"]["palace"]            # 'Health'
surrounding_palaces(c, "Life Palace")["career"]["name"]       # 'Career'
flies_to(c, "Life Palace", "Travel", "ji")                    # False

另有 to_solar(year, month, day, leap=False, country=...)、solar_terms、solar_term_on、day_pillar、year_pillar、hour_branch、auspicious_hours、yearly_luck、yearly_stars、find_patterns、minor_luck、bazi_svg、numerology_svg,均可从 nhatnguyet 导入。日期也接受 datetime.date 与 (year, month, day) 元组。

英文命名的模块与 npm 包一一对应:nhatnguyet.lunar、nhatnguyet.ziwei(含查询方法与 horoscope)、nhatnguyet.bazi、nhatnguyet.numerology 和 nhatnguyet.festivals,每个模块都有英文函数,并包含越南语命名模块的全部内容。后两个模块本身也可调用,因此无论该名称指向函数还是模块,nhatnguyet.festivals(2027) 与 nhatnguyet.numerology(...) 都能正常使用。

>>> from nhatnguyet.lunar import auspicious_hours
>>> [h["branch"] for h in auspicious_hours("2027-02-06")["hours"] if h["auspicious"]]
['Yin', 'Chen', 'Si', 'Shen', 'You', 'Hai']
>>> from nhatnguyet.festivals import festivals
>>> [f["date"] for f in festivals(2027) if f["id"] == "tet-nguyen-dan"]
['2027-02-06']

命令行

以下为摘录:只显示输出的第一部分,即十二宫网格及其图例。

npx @nhatnguyet/cli ziwei 1990-09-19 20:00 male --name "Nguyen Van An" --year 2026
python -m nhatnguyet ziwei 1990-09-19 20:00 male --name "Nguyen Van An" --year 2026
┌────────────────────┬────────────────────┬────────────────────┬────────────────────┐
│ Travel             │ Health             │ Wealth · Body      │ Children           │
│ Xin Si             │ Ren Wu Jie Kong    │ Gui Wei Jie Kong   │ Jia Shen           │
│ Celestial Mechanism│ Purple Star Ex     │ Spinning Top,      │ Army Breaker We    │
│   Pr               │ Celestial Leader,  │ Celestial Void     │ Prosperity,        │
│ Celestial Talent,  │ Celestial Fortune, │ Nurture            │ Celestial Horse,   │
│ Bell Star,         │ Celestial Messen…  │                    │ Celestial Charm,   │
│ Shattering Star    │ Conception         │                    │ Celestial Physic…, │
│ Extinction         │                    │                    │ Solitary Star,     │
│                    │                    │                    │ Flowing Haze       │
│                    │                    │                    │ Growth             │
├────────────────────┼────────────────────┴────────────────────┼────────────────────┤
│ Friends/Subordinat…│                                         │ Spouse             │
│ Geng Chen          │                                         │ Yi You             │
│ Seven Killings We  │                                         │ Sword Ram,         │
│ Phoenix Pavilion,  │                                         │ Earthly Robber,    │
│ Celestial Punish…, │                                         │ Dipper Lord,       │
│ State Seal,        │                                         │ Red Phoenix        │
│ Releasing Spirit,  │                                         │ Bathing            │
│ Terrace Aide,      │                                         │                    │
│ Celestial Injury,  │          ZI WEI DOU SHU CHART           │                    │
│ Celestial Net,     │              Nguyen Van An              │                    │
│ Widow Star         │       Born 1990-09-19 20:00 (Xu)        │                    │
│ Tomb               │       Lunar 1990-08-01 · Geng Wu        │                    │
├────────────────────┤                Yang Male                ├────────────────────┤
│ Career             │           Bureau: Earth Five            │ Siblings           │
│ Ji Mao             │      Na yin: Earth by the Roadside      │ Bing Xu Xun Kong   │
│ Sun Pr Lu          │          Life: Hai · Body: Wei          │ Purity Ex          │
│ Celestial Beam Pr  │                                         │ Celestial Treasury │
│ Right Assistant,   │                                         │   Pr               │
│ Peach Blossom,     │                                         │ Dragon Pool,       │
│ Eight Seats,       │                                         │ Earthly Snare,     │
│ Celestial Nobili…, │                                         │ Canopy             │
│ Celestial Virtue,  │                                         │ Youth              │
│ Celestial Joy,     │                                         │                    │
│ Celestial Release  │                                         │                    │
│ Death              │                                         │                    │
├────────────────────┼────────────────────┬────────────────────┼────────────────────┤
│ Property           │ Fortune/Virtue     │ Parents            │ Life Palace        │
│ Wu Yin             │ Ji Chou            │ Wu Zi              │ Ding Hai Xun Kong  │
│ Military Song      │ Celestial Blessing │ Greedy Wolf We     │ Moon Ex Ji         │
│   Pr Quan          │   We Ke            │ Literary Glory,    │ Left Assistant,    │
│ Celestial Minister │ Giant Gate We      │ Celestial Weeping, │ Three Terraces,    │
│   Ex               │ Earthly Void,      │ Celestial Emptin…, │ Grace Light,       │
│ Celestial Halberd, │ Celestial Longev…, │ Patent of Honour   │ Celestial Offici…, │
│ Literary Melody,   │ Court Tally        │ Peak               │ Fire Star,         │
│ Earthly Release,   │ Decline            │                    │ Monthly Virtue,    │
│ Celestial Kitchen  │                    │                    │ Robbery Sha,       │
│ Illness            │                    │                    │ Annual Literary …  │
│                    │                    │                    │ Prime              │
└────────────────────┴────────────────────┴────────────────────┴────────────────────┘
Brightness: Ex exalted, Pr prosperous, Fa favorable, Ne neutral, We weak. Ages are East
Asian ages (1 at birth).

网格之后(上方摘录已略去)依次输出流年、十二个大运、格局与备注。其他命令:

nhatnguyet bazi 1990-09-19 20:00 male --lang zh
nhatnguyet bazi 1990-09-19 female --terms han  # birth time unknown; stems and branches as 庚午
nhatnguyet lunar 2027-02-06 --country CN
nhatnguyet solar 2023-02-01 --leap             # lunar to Gregorian: 2023-03-22
nhatnguyet terms 2027 --country KR
nhatnguyet hours 2027-02-06                    # auspicious and inauspicious double hours
nhatnguyet numerology "Nguyen Van An" 1990-09-19 --today 2026-11-19
nhatnguyet festivals 2027 --lang vi
nhatnguyet ziwei 1990-09-19 20:00 male --svg chart.svg --theme dark
$ nhatnguyet lunar 2027-02-06 --country CN
┌────────────┬─────────────────┐
│ Gregorian  │ 2027-02-06      │
│ Lunar      │ 2027-01-01      │
│ Year       │ Ding Wei · Goat │
│ Month      │ Ren Yin         │
│ Day        │ Bing Chen       │
│ Solar term │ Start of Spring │
│ Calendar   │ CN (UTC+8)      │
└────────────┴─────────────────┘

$ nhatnguyet solar 2023-02-01 --leap
┌────────────┬───────────────────┐
│ Gregorian  │ 2023-03-22        │
│ Lunar      │ 2023-02 (leap)-01 │
│ Year       │ Gui Mao · Cat     │
│ Month      │ Yi Mao            │
│ Day        │ Ji Mao            │
│ Solar term │ Vernal Equinox    │
│ Calendar   │ VN (UTC+7)        │
└────────────┴───────────────────┘

$ nhatnguyet hours 2027-02-06
AUSPICIOUS HOURS  2027-02-06 · Day Bing Chen
┌───────────────┬─────────────┬──────────────┬───────────┐
│ Zi (Rat)      │ 23:00-00:59 │ inauspicious │ Tian Lao  │
│ Chou (Ox)     │ 01:00-02:59 │ inauspicious │ Yuan Wu   │
│ Yin (Tiger)   │ 03:00-04:59 │ auspicious   │ Si Ming   │
│ Mao (Cat)     │ 05:00-06:59 │ inauspicious │ Gou Chen  │
│ Chen (Dragon) │ 07:00-08:59 │ auspicious   │ Qing Long │
│ Si (Snake)    │ 09:00-10:59 │ auspicious   │ Ming Tang │
│ Wu (Horse)    │ 11:00-12:59 │ inauspicious │ Tian Xing │
│ Wei (Goat)    │ 13:00-14:59 │ inauspicious │ Zhu Que   │
│ Shen (Monkey) │ 15:00-16:59 │ auspicious   │ Jin Kui   │
│ You (Rooster) │ 17:00-18:59 │ auspicious   │ Bao Guang │
│ Xu (Dog)      │ 19:00-20:59 │ inauspicious │ Bai Hu    │
│ Hai (Pig)     │ 21:00-22:59 │ auspicious   │ Yu Tang   │
└───────────────┴─────────────┴──────────────┴───────────┘

--json 输出 JSON(不含 raw),--lang en|vi|zh 选择语言,--terms pinyin|han|vi 决定英文中天干地支的写法,--svg <file> 另将命盘写成 SVG(ziwei、bazi、numerology)。MCP 工具名也可用作命令别名(cast_ziwei、cast_bazi、lunar_convert、solar_terms、auspicious_hours;旧名 cast_zi_wei、zi_wei 亦可)。仅在终端中使用颜色,可用 NO_COLOR 或 --no-color 关闭。