八字排盘、黄历与大运流年查询 (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

• 推荐运行环境：Node 24（可直接运行 TypeScript 源码）。 / Recommended runtime: Node 24 (can run TypeScript source directly).
• 兼容方案：若 Node 版本较低，使用 tsx 执行。 / Fallback: use tsx on lower Node versions.
• 执行目录：在 skill 根目录（SKILL.md 所在目录）执行以下命令。 / Run commands in the skill root (where SKILL.md is located).

npm i

# 仅在需要兼容运行时安装
# 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

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

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

参数定义 / Parameters:

• solarTime（必填 / required）
  • 格式：ISO 8601 日期时间（不带时区），如 1990-05-15T14:30:00
  • 默认值：无
  • 非法输入：格式不合法或为空时，由底层解析失败并报错
• gender（可选 / optional）
  • 取值范围：1（男 / male）、0（女 / female）
  • 默认值：1
  • 非法输入：抛错 性别参数无效。男性传 1，女性传 0。
• sect（可选 / optional）
  • 取值范围：1（23:00-23:59 视为明天）、2（23:00-23:59 视为当天）
  • 默认值：2
  • 非法输入：抛错 早晚子时配置参数无效。传 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）
  • 格式：ISO 8601 日期时间（不带时区），如 1990-04-21T14:30:00
  • 默认值：无
  • 非法输入：格式不合法或为空时，由底层解析失败并报错
• gender（可选 / optional）
  • 取值范围：1（男 / male）、0（女 / female）
  • 默认值：1
  • 非法输入：抛错 性别参数无效。男性传 1，女性传 0。
• sect（可选 / optional）
  • 取值范围：1（23:00-23:59 视为明天）、2（23:00-23:59 视为当天）
  • 默认值：2
  • 非法输入：抛错 早晚子时配置参数无效。传 1 表示 23:00-23:59 日干支为明天，传 2 表示 23:00-23:59 日干支为当天。

scripts/convertToTrueSolarTime.ts（真太阳时换算）

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

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

参数定义 / Parameters:

• beijingTime（必填 / required）
  • 含义：北京时间（东八区标准时）输入时间
  • 格式：YYYY-MM-DDTHH:mm[:ss]（不带时区），如 1990-05-15T14:30:00
  • 默认值：无
  • 非法输入：抛错 时间格式无效...请使用不带时区的 YYYY-MM-DDTHH:mm[:ss]...
• longitudeOrCity（必填 / required）
  • 含义：可直接传经度，或传城市名由脚本自动匹配经度
  • 经度格式：十进制度数，范围 -180 到 180（如武汉 114.17）
  • 城市格式：城市名（支持常见后缀，如 武汉、武汉市）
  • 默认值：无
  • 非法输入：地点无法识别时抛错 无法识别地点...请传经度或城市名...
• standardLongitude（可选 / optional）
  • 含义：标准经度，默认 120（北京时间基准经线）
  • 取值范围：-180 到 180
  • 默认值：120
  • 非法输入：抛错 standardLongitude 无效... 或 standardLongitude 超出范围...

输出 / Output:

• 标准输出仅返回 1 行真太阳时时间字符串（YYYY-MM-DDTHH:mm:ss），可直接作为 buildBaziFromSolar.ts 与 queryFortuneRange.ts 的 solar 时间参数。

scripts/getChineseCalendar.ts（黄历/农历查询）

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

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

参数定义 / Parameters:

• date（可选 / optional）
  • 格式：YYYY-MM-DD（兼容 YYYY/MM/DD），如 2024-02-10
  • 默认值：当天日期
  • 取值范围：有效公历日期
  • 非法输入：
    • 格式错误时抛错 日期格式无效。请传入 YYYY-MM-DD（也兼容 YYYY/MM/DD）。
    • 日期不存在时抛错 日期值无效。请确认年月日是实际存在的日期。

scripts/queryFortuneRange.ts（大运/流年/流月/流日/流时区间查询）

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

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

参数定义 / Parameters:

• json（必填 / required）
  • 格式：JSON 字符串，结构如下：
    • birth.calendar（必填）：solar 或 lunar
    • birth.time（必填）：出生时间（不带时区），如 1990-05-15T14:30:00
    • birth.gender（可选）：1 男，0 女，默认 1
    • birth.sect（可选）：1 或 2，默认 2
    • query.startDateTime（必填）：YYYY-MM-DD 或 YYYY-MM-DDTHH
    • query.endDateTime（必填）：YYYY-MM-DD 或 YYYY-MM-DDTHH
    • query.level（可选）：year、month、day、hour，默认 year
  • 自动补全规则：
    • startDateTime 传 YYYY-MM-DD 时补为 T00
    • endDateTime 传 YYYY-MM-DD 时补为 T23
  • 结果规则：
    • level 采用层级语义：year < month < day < hour
    • 自动补父级：查 day 自动包含 year+month；查 hour 自动包含 year+month+day
    • level=hour 时返回流时，输出会将连续相同流时合并为时辰段（2 小时语义）
    • 查询层级达到 month 时返回按连续干支月分段的流月区间
    • 流年/流月/流日/流时结果均包含：干支、十神、神煞、与原命盘的刑冲合会关系
    • 输出固定为完整 Markdown（按层级标题展开全部字段，不使用代码块），不做省略与去重
  • 非法输入：
    • JSON 非法时抛错 参数 JSON 解析失败。请传入合法 JSON。
    • 时间格式错误时抛错 时间格式无效...请使用 YYYY-MM-DD 或 YYYY-MM-DDTHH...
    • startDateTime 晚于 endDateTime 时抛错 时间范围无效：startDateTime 不能晚于 endDateTime。
    • level=hour 且范围超过 62 天时抛错 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. 所有命令均在 skill 根目录执行，不依赖仓库根目录路径。 / Run all commands in the skill root; do not rely on repo-root paths.
2. 时间字符串不要携带时区后缀（如 Z、+08:00），以免产生与预期不一致的换日结果。 / Do not append timezone suffixes (such as Z or +08:00) to avoid unexpected day shifts.
3. 若要按真太阳时排盘，请先运行 convertToTrueSolarTime.ts，再把输出时间传给其它脚本；其它脚本本身不做真太阳时换算。 / For true solar time workflow, run convertToTrueSolarTime.ts first and pass its output to other scripts.
4. 涉及 23:00-23:59 出生时，建议显式传 sect，避免晚子时归属歧义。 / For births between 23:00-23:59, explicitly set sect to avoid ambiguity.
5. queryFortuneRange.ts 的 startDateTime/endDateTime 只支持 YYYY-MM-DD 或 YYYY-MM-DDTHH，不支持分钟秒。 / queryFortuneRange.ts supports only YYYY-MM-DD and YYYY-MM-DDTHH for range inputs.
6. 真太阳时换算只依赖经度，不需要纬度；脚本支持直接传城市名自动匹配经度。 / True solar time conversion uses longitude only; latitude is not required.