排盘

八字排盘引擎，TypeScript 写的，纯计算。npm 包名：paipan。

给出生时间，返回一个 JSON —— 四柱、十神、藏干、大运流年……所有通行的排盘数据都有。

只排盘，不判断。 强弱、格局、用神喜忌、五行比重、评分这些因流派而异的东西，这里一概不碰。你拿到原始数据，怎么解读是你的事。

安装

npm install paipan
# lunar-typescript 会自动装上

用法

import { paipan } from 'paipan'

const chart = paipan({
  calendar: 'solar',     // 'solar'（默认）或 'lunar'
  year: 1990, month: 6, day: 15,
  hour: 14, minute: 30,  // 24 小时制；hour 可省略（出生时间不详）；minute 默认 0
  gender: 'male',
  // 出生地，都可选（详见「出生地与城市表」）
  city: 'cn-shanghai',       // 城市 id，自动填经度 + 时区
  longitude: 121.47,         // 真太阳时校正用
  timeZone: 'Asia/Shanghai', // 默认 'Etc/GMT-8'（东八区）
})

console.log(JSON.stringify(chart, null, 2))

返回示例

1990-06-15 14:30 男，经度 121.47，Asia/Shanghai（数值做了四舍五入）：

{
  "input": { "calendar": "solar", "year": 1990, "month": 6, "day": 15, "hour": 14, "minute": 30,
             "leap": false, "gender": "male", "longitude": 121.47, "timeZone": "Asia/Shanghai" },
  "trueSolar": { "year": 1990, "month": 6, "day": 15, "hour": 13, "minute": 36,
                 "timeZone": "Asia/Shanghai", "timeZoneOffset": 540,
                 "longitudeOffset": -54.12, "eot": -0.32, "totalShift": -54.44 },
  // 阳历 + 农历双向都给数字结构（农历输入时 solarDate 即换算出的阳历）
  "solarDate": { "year": 1990, "month": 6, "day": 15, "hour": 14, "minute": 30 },
  "lunarDate": { "year": 1990, "month": 5, "day": 23, "leap": false, "label": "一九九〇年五月廿三" },
  "lunarLabel": "一九九〇年五月廿三",  // 盘所用农历（TST 校正后）；跨日时可能与 lunarDate.label 不同
  "dayMaster": "辛",
  "pillars": {
    "year":  { "gan": "庚", "zhi": "午", "ganzhi": "庚午",
               "ganWuxing": "金", "zhiWuxing": "火", "ganYinYang": "yang",
               "nayin": { "name": "路旁土", "wuxing": "土" },
               "hiddenStems": [ { "gan": "丁", "wuxing": "火", "shishen": "七杀" },
                                { "gan": "己", "wuxing": "土", "shishen": "偏印" } ],
               "shishen": "劫财",
               "changsheng": "病",
               "selfChangsheng": "沐浴",
               "xunkong": false },
    "month": { ... }, "day": { ... }, "hour": { ... }
  },
  "xunkong": ["寅", "卯"],
  "monthCommand": {
    "monthBranch": "午", "term": "芒种", "daysIntoTerm": 9.28,
    "commandStem": "丙", "phase": "余气", "shishen": "正官", "phaseProgress": 0.93,
    "segments": [ { "gan": "丙", "phase": "余气", "days": 10, "shishen": "正官" }, ... ]
  },
  "transparentStems": [
    { "gan": "壬", "stemPosition": "month", "fromBranch": "亥", "fromBranchPosition": "day",
      "hiddenIndex": 0, "phase": "本气", "shishen": "伤官" }
  ],
  "rooting": [
    { "position": "day", "branch": "亥", "root": null }
  ],
  "sanyuan": {
    "taiyuan":  { "gz": "癸酉", "gan": "癸", "zhi": "酉", "shishen": "食神", "wuxing": "水" },
    "minggong": { "gz": "庚辰", ... }, "shengong": { "gz": "戊寅", ... }
  },
  "gongwei": {
    "palaces": {
      "ancestor": { "palace": "ancestor", "pillar": "year", "name": "祖业宫", "ageRange": [1, 15], "gan": "庚", "zhi": "午" },
      "parent": { ... }, "self": { ... }, "children": { ... }
    },
    "family": [
      { "relation": "妻", "shishen": "正财", "count": 1, "atOwnPalace": true, "ownPalace": "self",
        "locations": [ { "kind": "branch-middle", "pillar": "day" } ] }, ...
    ],
    "ganzhiKin": [
      { "pillar": "year", "slot": "gan", "char": "庚", "relative": "爷爷" },
      { "pillar": "month", "slot": "zhi", "char": "午", "relative": "母亲" },
      { "pillar": "day",  "slot": "zhi", "char": "亥", "relative": "配偶" }, ...
    ]
  },
  "relations": [
    { "type": "六合", "positions": ["year", "hour"], "chars": ["午", "未"], "huaWuxing": "土" },
    { "type": "天干相冲", "positions": ["day", "hour"], "chars": ["辛", "乙"] }
  ],
  "shensha": [
    { "name": "天乙贵人", "position": "year", "char": "午", "anchor": "dayGan" }
  ],
  "dayun": {
    "forward": true,
    "startAge": { "years": 7, "months": 4, "days": 17, "hours": 0 },
    "startSolar": { "year": 1997, "month": 11, "day": 1 },
    "preStart": { "startYear": 1990, "endYear": 1996, "startAge": 1, "endAge": 7 },
    "xiaoYun": [
      { "year": 1990, "age": 1, "gan": "丙", "zhi": "申", "ganzhi": "丙申", "shishen": "正官" },
      { "year": 1991, "age": 2, "gan": "丁", "zhi": "酉", "ganzhi": "丁酉", "shishen": "七杀" }
    ],
    "pillars": [
      { "index": 1, "gan": "癸", "zhi": "未", "ganzhi": "癸未",
        "startYear": 1997, "endYear": 2006, "startAge": 8, "endAge": 17, "shishen": "食神",
        "liunian": [ { "year": 1997, "age": 8, "gan": "丁", "zhi": "丑", "ganzhi": "丁丑", "shishen": "七杀" }, ... ] }
    ]
  }
}

包含哪些数据

| 字段 | 说明 | | --- | --- | | 阳历 / 农历 | solarDate / lunarDate，两个日历都给数字（年月日），无论输入是哪个历 | | 四柱 | 年月日时，真太阳时校正后排出 | | 五行 / 阴阳 | 每个天干、地支的五行和阴阳 | | 纳音 | 六十甲子纳音五行 | | 藏干 | 每个地支的藏干，附十神 | | 十神 | 天干和藏干相对日主的十神 | | 十二长生 | 日主在各支 + 本柱天干自坐 | | 旬空 | 日柱旬空的两个地支 | | 月令司令 | 月支当令的藏干，按节后天数定（《渊海子平》分日法） | | 透干 | 哪些藏干透出为天干，附本/中/余气和十神 | | 通根 | 日主在各支有无根，附气的层级 | | 三元 | 胎元、命宫、身宫 | | 宫位六亲 | 四柱对应的宫位 + 六亲星落位 + 干支位六亲 | | 合冲刑害破 | 六合、半合、三合、三会、六冲、六害、六破、三刑、自刑 + 天干五合/相冲/相克（相冲只含甲庚乙辛丙壬丁癸真四冲，土克水等归相克） | | 神煞 | 标准神煞，只标位置，不判吉凶 | | 大运 | 含精确起运岁（真太阳时精算） | | 小运 | 起运前的童限，每虚岁一柱（在 dayun.xiaoYun 里） | | 流年 | 每步大运里嵌套 10 个流年 |

神煞

只标位置，不判吉凶。起例口径对齐观命（guanming）detectShensha：

• 日干起： 天乙贵人（+年干双锚，带 source 标日/年/双）、文昌、太极贵人、羊刃（含阴干）、飞刃、血刃、禄神、流霞
• 年干起： 福星贵人
• 年支起： 桃花、华盖、将星、驿马、金匮、劫煞、灾煞、亡神、红鸾、天喜、孤辰（排年柱）、寡宿（排年柱）、元辰（+性别）
• 月支起： 天德贵人、月德贵人、天医（月支 +8 位）
• 日柱本身： 魁罡、十恶大败、天罗、地网

串宫押运

calcChuanGong(pillars, year) —— 盲派十二神押四柱。因为要传入具体流年，所以是独立函数，不在 paipan() 的输出里：

import { paipan, calcChuanGong } from 'paipan'

const chart = paipan({ year: 1990, month: 6, day: 15, hour: 14, gender: 'male' })
const cg = calcChuanGong(chart.pillars, 2023)
// cg.taisui = '卯'，cg.godMap = 12支→12神，
// cg.pillars.day.{stemGod, branchGod} = 日柱干/支所落之神

十二神顺序：太岁→青龙→丧门→六合→官符→小耗→大耗→朱雀→白虎→贵神→吊客→病符。天干按建禄支查。

流月 / 流日 / 流时

年以下的流转。和 calcChuanGong 一样要传入具体时间，所以是独立函数，不进 paipan() 输出。三个都要传日主，用来算十神。

import { calcLiuYue, calcLiuRi, calcLiuShi } from 'paipan'

// 流月：某个八字年（立春→立春）的 12 个月，按节气分。
calcLiuYue(2023, '辛')
// [{ index:1, ganzhi:'甲寅', term:'立春', startSolar:{year:2023,month:2,day:4,...}, shishen:'正财' }, …]
// 第 12 个月是丑月（小寒），落在次年一月。

// 流日：某公历日的日柱。
calcLiuRi(2023, 3, 21, '辛')
// { year:2023, month:3, day:21, ganzhi:'戊寅', shishen:'正印', xunkong:['申','酉'] }

// 流时：某公历日的 12 个时辰，时干按五鼠遁从日干推。
calcLiuShi(2023, 3, 21, '辛')
// [{ index:0, ganzhi:'壬子', hourRange:[0,1], shishen:'伤官' }, …]

约定：流月按节（立春寅、惊蛰卯……大雪子、小寒丑）分，月干走五虎遁；流日取当天正午定柱，避开子时换日的歧义；流时索引 0 是当天早子时（00:00–01:00），12 个时辰覆盖 00:00–23:00。晚子时（23:00–24:00）按 sect=2 归次日，要查就调用次日的 calcLiuShi。

把流月挂进 paipan() 输出

默认 paipan() 不带流月（避免 JSON 膨胀）。需要的话开 include.liuYue，每个流年和小运下就会挂上当年的 12 个流月：

const chart = paipan({
  year: 1990, month: 6, day: 15, hour: 14, gender: 'male',
  include: { liuYue: true },
})

chart.dayun.pillars[0].liunian[0].liuYue // [{ index:1, ganzhi:'戊寅', term:'立春', … }, …]（12 个）
chart.dayun.xiaoYun[0].liuYue            // 小运那年的 12 个流月

流日、流时仍只走独立函数（calcLiuRi / calcLiuShi），不进 paipan() 输出。

出生地与城市表

经度校正可以直接给 longitude，也可以给 city（内置城市表的 id）自动填经度 + 时区。三者都可选——都不填则按 120°E 标准经线 / UTC+8 计算，不做经度校正。显式 longitude / timeZone 会覆盖 city，未知的城市 id 直接抛错。

import { paipan, CITIES, getCityById, searchCities } from 'paipan'

paipan({ year: 1990, month: 6, day: 15, hour: 14, gender: 'male', city: 'cn-urumqi' })
// 自动用乌鲁木齐 87.62°E / Asia/Shanghai 做真太阳时

searchCities('上海')      // 按名称 / 拼音 / 别名 / 时区模糊搜
getCityById('cn-shanghai') // → { id, name, longitude, timeZone, ... }

城市表覆盖中国全部地级市/州盟 + 主要海外华人圈与各大洲城市，含拼音/英文别名和 IANA 时区。

出生时间不详

省略 hour 即可。年月日三柱照常排出，时柱相关的字段返回 null：

• pillars.hour / trueSolar / dayun / gongwei → null
• sanyuan.minggong / sanyuan.shengong → null（胎元只用月柱，照算）

const chart = paipan({ year: 1990, month: 6, day: 15, gender: 'male' })
// chart.pillars.hour === null
// chart.dayun === null

精度

底层用 lunar-typescript 算历法（节气分月、立春分年、sect=2 起运）。排盘前做真太阳时校正（经度偏移 + 均时差，Meeus 公式）。

许可

MIT