SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscantian-bazi

cantian-bazi

General & other

View repository

Updated 10-15 20:10

About this skill

Bazi Chart, Chinese Almanac & Major Luck/Annual Fortune Query (Bazi, Calendar & Fortune Range)

When to Use

  • User wants Four Pillars from Gregorian birth datetime.
  • User wants Four Pillars from lunar birth datetime.
  • User wants Chinese calendar info for a specific date.
  • User wants almanac-style daily auspicious/inauspicious info.
  • User wants decade/annual/monthly/daily/hourly fortune cycles in a time range.

Prerequisites

  • Recommended runtime: Node 24 (can run TypeScript source directly).
  • Fallback: if the Node version is lower, use tsx to execute. / Fallback: use tsx on lower Node versions.
  • Execution directory: run the following commands in the skill root (whereSKILL.md is located). / Run commands in the skill root (where SKILL.md is located).
npm i
Install only when runtime compatibility is needed Install only for fallback mode

npm i -D tsx


## 脚本清单 / Script Index

- `scripts/buildBaziFromSolar.ts`：根据阳历时间生成八字 Markdown。 / Build Bazi from solar datetime.
- `scripts/buildBaziFromLunar.ts`：根据农历时间生成八字 Markdown。 / Build Bazi from lunar datetime.
- `scripts/convertToTrueSolarTime.ts`：将北京时间按经度换算为真太阳时（输出可直接给其它脚本使用）。 / Convert Beijing time to true solar time by longitude.
- `scripts/getChineseCalendar.ts`：查询指定日期（默认今天）的农历与干支信息。 / Get Chinese calendar for a given date (defaults to today).
- `scripts/queryFortuneRange.ts`：按时间区间查询大运与流年/流月/流日/流时（流时按时辰段合并）。 / Query decade fortune and annual/monthly/daily/hourly cycles in a time range.

## 脚本与参数 / Scripts & Parameters

### `scripts/buildBaziFromSolar.ts`

```bash
# 推荐方式
node scripts/buildBaziFromSolar.ts <solarTime> [gender] [sect]

# 兼容方式（fallback）
tsx scripts/buildBaziFromSolar.ts <solarTime> [gender] [sect]

Parameters:

  • solarTime(required)
    • Format: ISO 8601 datetime (without timezone), such as 1990-05-15T14:30:00
    • Default value: none
    • Invalid input: when the format is invalid or empty, the underlying parser fails and reports an error
  • gender(optional)
    • Value range:1(male),0(female)
    • Default value:1
    • Invalid input: throws error 性别参数无效。男性传 1，女性传 0。
  • sect(optional)
    • Value range:1(23:00-23:59 is treated as tomorrow),2(23:00-23:59 is treated as the current day)
    • Default value:2
    • Invalid input: throws error 早晚子时配置参数无效。传 1 表示 23:00-23:59 日干支为明天，传 2 表示 23:00-23:59 日干支为当天。

scripts/buildBaziFromLunar.ts

# 推荐方式
node scripts/buildBaziFromLunar.ts <lunarTime> [gender] [sect]

# 兼容方式（fallback）
tsx scripts/buildBaziFromLunar.ts <lunarTime> [gender] [sect]

Parameters:

  • lunarTime(required)
    • Format: ISO 8601 datetime (without timezone), such as 1990-04-21T14:30:00
    • Default value: none
    • Invalid input: when the format is invalid or empty, the underlying parser fails and reports an error
  • gender(optional)
    • Value range:1(male),0(female)
    • Default value:1
    • Invalid input: throws error 性别参数无效。男性传 1，女性传 0。
  • sect(optional)
    • Value range:1(23:00-23:59 is treated as tomorrow),2(23:00-23:59 is treated as the current day)
    • Default value:2
    • Invalid input: throws error 早晚子时配置参数无效。传 1 表示 23:00-23:59 日干支为明天，传 2 表示 23:00-23:59 日干支为当天。

scripts/convertToTrueSolarTime.ts(True solar time conversion)

# 推荐方式
node scripts/convertToTrueSolarTime.ts <beijingTime> <longitudeOrCity> [standardLongitude]

# 兼容方式（fallback）
tsx scripts/convertToTrueSolarTime.ts <beijingTime> <longitudeOrCity> [standardLongitude]

Parameter definitions / Parameters:

  • beijingTime(required / required)
    • Meaning: Beijing time (UTC+8 standard time) input time
    • Format:YYYY-MM-DDTHH:mm[:ss](without time zone), e.g. 1990-05-15T14:30:00
    • Default value: none
    • Invalid input: throws error 时间格式无效...请使用不带时区的 YYYY-MM-DDTHH:mm[:ss]...
  • longitudeOrCity(required / required)
    • Meaning: can pass longitude directly, or pass a city name and the script will automatically match the longitude
    • Longitude format: decimal degrees, range -180 to 180(e.g. Wuhan 114.17）
    • City format: city name (supports common suffixes, e.g. 武汉、武汉市）
    • Default value: none
    • Invalid input: throws error when the location cannot be recognized 无法识别地点...请传经度或城市名...
  • standardLongitude(optional / optional)
    • Meaning: standard longitude, default 120(Beijing time reference meridian)
    • Value range:-180 to 180
    • Default value:120
    • Invalid input: throws error standardLongitude 无效... or standardLongitude 超出范围...

Output / Output:

  • Standard output returns only 1 line of true solar time string (YYYY-MM-DDTHH:mm:ss), which can be directly used as buildBaziFromSolar.ts and queryFortuneRange.ts of solar time parameter.

scripts/getChineseCalendar.ts(Yellow Calendar/Lunar Calendar query)

# 推荐方式（不传参默认今天）
node scripts/getChineseCalendar.ts [date]

# 兼容方式（fallback）
tsx scripts/getChineseCalendar.ts [date]

Parameter definitions / Parameters:

  • date(optional / optional)
    • Format:YYYY-MM-DD(compatible with YYYY/MM/DD), e.g. 2024-02-10
    • Default value: current date
    • Value range: valid Gregorian date
    • Invalid input:
      • Throws error when the format is incorrect 日期格式无效。请传入 YYYY-MM-DD（也兼容 YYYY/MM/DD）。
      • Throws error when the date does not exist 日期值无效。请确认年月日是实际存在的日期。

scripts/queryFortuneRange.ts(Major Fortune/Annual Fortune/Monthly Fortune/Daily Fortune/Hourly Fortune interval query)

# 推荐方式
node scripts/queryFortuneRange.ts '<json>'

# 兼容方式（fallback）
tsx scripts/queryFortuneRange.ts '<json>'

Parameter definitions / Parameters:

  • json(required / required)
    • Format: JSON string, structure as follows:
      • birth.calendar(required):solar or lunar
      • birth.time(required): birth time (without time zone), e.g. 1990-05-15T14:30:00
      • birth.gender(optional):1 male,0 female, default 1
      • birth.sect(optional):1 or 2, default 2
      • query.startDateTime(required):YYYY-MM-DD or YYYY-MM-DDTHH
      • query.endDateTime(required):YYYY-MM-DD or YYYY-MM-DDTHH
      • query.level(optional):year、month、day、hour, default year
    • Auto-completion rules:
      • startDateTime When YYYY-MM-DD is passed, it is completed to T00
      • endDateTime When YYYY-MM-DD is passed, it is completed to T23
    • Result rules:
      • level Uses hierarchical semantics:year < month < day < hour
      • Automatically completes the parent level: querying day automatically includes year+month; querying hour automatically includes year+month+day
      • level=hour When returning hourly fortune, the output merges consecutive identical hourly fortunes into two-hour time segments (2-hour semantics)
      • When the query level reaches month , it returns monthly fortune intervals segmented by consecutive sexagenary cycle months
      • Annual/Monthly/Daily/Hourly fortune results all include: Heavenly Stems and Earthly Branches, Ten Gods, Deities and Sha, and the clash, punishment, combination, and meeting relationships with the original natal chart
      • Output is fixed as complete Markdown (all fields expanded by hierarchical headings, no code blocks), with no omission or deduplication
    • Invalid input:
      • Throw an error when JSON is invalid 参数 JSON 解析失败。请传入合法 JSON。
      • Throw an error when the time format is incorrect 时间格式无效...请使用 YYYY-MM-DD 或 YYYY-MM-DDTHH...
      • startDateTime later than endDateTime throw an error when 时间范围无效：startDateTime 不能晚于 endDateTime。
      • level=hour and throw an error when the range exceeds 62 days hour 查询区间过大...

Examples

# buildBaziFromSolar.ts 最小可用示例
node scripts/buildBaziFromSolar.ts "1990-05-15T14:30:00"

# buildBaziFromLunar.ts 最小可用示例
node scripts/buildBaziFromLunar.ts "1990-04-21T14:30:00"

# convertToTrueSolarTime.ts 最小可用示例（武汉经度）
node scripts/convertToTrueSolarTime.ts "1990-05-15T14:30:00" 114.17

# convertToTrueSolarTime.ts 城市名示例（无需手查经度）
node scripts/convertToTrueSolarTime.ts "1990-05-15T14:30:00" 武汉

# getChineseCalendar.ts 最小可用示例（默认今天）
node scripts/getChineseCalendar.ts

# getChineseCalendar.ts 指定日期
node scripts/getChineseCalendar.ts 2024-02-10

# queryFortuneRange.ts: 查询 2026-2028 流年
node scripts/queryFortuneRange.ts '{"birth":{"calendar":"solar","time":"1990-05-15T14:30:00","gender":1,"sect":2},"query":{"startDateTime":"2026-01-01","endDateTime":"2028-12-31","level":"year"}}'

# queryFortuneRange.ts: 查询下个月流日（按日）
node scripts/queryFortuneRange.ts '{"birth":{"calendar":"solar","time":"1990-05-15T14:30:00"},"query":{"startDateTime":"2026-05-01","endDateTime":"2026-05-31","level":"day"}}'

# queryFortuneRange.ts: 查询某段流时（按时辰段合并）
node scripts/queryFortuneRange.ts '{"birth":{"calendar":"solar","time":"1990-05-15T14:30:00"},"query":{"startDateTime":"2026-05-01T09","endDateTime":"2026-05-03T18","level":"hour"}}'

# 两步流程示例：先换算真太阳时，再排盘（示例结果需替换为实际换算输出）
node scripts/convertToTrueSolarTime.ts "1990-05-15T14:30:00" 114.17
node scripts/buildBaziFromSolar.ts "1990-05-15T14:10:20" 1 2

Notes

  1. Run all commands in the skill root; do not rely on repo-root paths.
  2. Do not append timezone suffixes (such as Z、+08:00) to the time string, to avoid day-change results inconsistent with expectations. Z or +08:00) to avoid unexpected day shifts.
  3. For true solar time charting, first run convertToTrueSolarTime.ts, then pass the output time to other scripts; the other scripts themselves do not perform true solar time conversion. convertToTrueSolarTime.ts first and pass its output to other scripts.
  4. For births between 23:00-23:59, it is recommended to explicitly set sect, to avoid ambiguity in the attribution of late Zi hour. sect to avoid ambiguity.
  5. queryFortuneRange.ts of startDateTime/endDateTime only supports YYYY-MM-DD or YYYY-MM-DDTHH, and does not support minutes or seconds. / queryFortuneRange.ts supports only YYYY-MM-DD and YYYY-MM-DDTHH for range inputs.
  6. True solar time conversion only depends on longitude and does not require latitude; the script supports directly passing a city name to automatically match the longitude.