奇門遁甲排盤系統 - Qimen Dunjia divination chart generator with Chai Bu method
npm install qimen-dunjia本系統實現奇門遁甲的完整排盤運算,採用拆補法定局,將特定時刻的干支資訊轉化為多層次的空間分布圖,用於時空決策分析。
---
1. 理論背景
2. 系統架構
3. 快速開始
4. API 參考
5. 網頁介面
6. 拆補法定局原理
7. 節氣局數表
8. 檔案結構
9. Release 發布策略
10. 版本歷史
11. 授權
---
河圖(先天八卦)代表宇宙形成前的理想秩序,強調陰陽對立配對,體現「天地定位、山澤通氣、雷風相薄、水火不相射」的對稱結構。
洛書(後天八卦)代表萬物形成後的實際運作,數字排列為「戴九履一、左三右七、二四為肩、六八為足、五居中央」,對應八方位與四季循環。
奇門遁甲以洛書九宮為空間載體,在其上疊加多層時間資訊,形成動態的時空分析模型。
奇門遁甲的盤局由五層組成,各層獨立運算後疊加於洛書九宮:
第一層:地盤
三奇六儀(乙丙丁戊己庚辛壬癸)的靜態分布,根據局數(1-9)與陰陽遁確定。陽遁順布,由一宮起始依洛書軌跡順飛;陰遁逆布,由九宮起始逆飛。甲為十干之首,象徵主帥,遁入六儀之下而不直接顯現,此即「遁甲」之意。
第二層:天盤
天干隨時辰的動態位移。以時干位置為放置起點、符首位置為取值起點,沿飛布軌跡旋轉映射。天盤與地盤的干支組合形成「奇門格局」,是斷事的核心依據。
第三層:八門
門戶飛布,代表地理空間的吉凶屬性。八門為休、生、傷、杜、景、死、驚、開,各有本位宮與飛布後的落宮。值使門隨時辰輪轉,主事態發展的通道。
第四層:九星
星曜飛布,代表天象對人事的影響。九星為天蓬、天芮、天沖、天輔、天禽、天心、天柱、天任、天英。值符星隨時辰輪轉,主事態的主導力量。天禽居中宮無定位,寄於二宮或八宮。
第五層:八神
神煞飛布,代表超自然力量的介入。陽局八神為值符、騰蛇、太陰、六合、勾陳、朱雀、九地、九天;陰局將勾陳、朱雀替換為白虎、玄武。八神以時干位置為起點飛布。
旬首:六十甲子分為六旬,每旬以甲日起始。六旬首為甲子、甲戌、甲申、甲午、甲辰、甲寅。
符首:甲所遁藏的六儀。對應關係為:
- 甲子旬 → 戊(甲子遁戊)
- 甲戌旬 → 己(甲戌遁己)
- 甲申旬 → 庚(甲申遁庚)
- 甲午旬 → 辛(甲午遁辛)
- 甲辰旬 → 壬(甲辰遁壬)
- 甲寅旬 → 癸(甲寅遁癸)
值符:當前主事的九星,由符首在地盤上的位置決定。
值使:當前主事的八門,由符首在地盤上的位置決定。
空亡:每旬末兩個地支無天干配對,為空亡位,主虛無、延遲、變數。
---
```
┌─────────────────────────────────────────────────────────┐
│ index.js │
│ (統一入口) │
├─────────────────────────────────────────────────────────┤
│ qimen.js │
│ (主控函數:整合排盤) │
├──────────────┬──────────────┬───────────────────────────┤
│ constants.js │ utils.js │ calculations.js │
│ (常數表) │ (工具函數) │ (五層運算函數) │
├──────────────┴──────────────┴───────────────────────────┤
│ lunar-javascript (npm) │
│ (農曆轉換:node_modules) │
└─────────────────────────────────────────────────────────┘
---
直接用瀏覽器開啟 index.html,輸入日期時間即可自動排盤。
#### 安裝依賴
`bash`
npm install
#### 常用指令
| 指令 | 說明 |
|------|------|
| npm test | 執行單元測試(21 個測試案例) |npm run build
| | 打包為 ES Module(排除 lunar-javascript) |npm run build:standalone
| | 打包為獨立 IIFE(包含所有依賴) |
#### 單元測試
`bash`
npm test
測試涵蓋:
- 陽遁/陰遁局數計算
- 甲遁邏輯處理
- generateChartByDatetime API(日期解析、節氣、三元)generateChartNow
- API
- 輸入驗證(格式、範圍檢查)
- API 一致性驗證
#### 打包
ES Module 格式(需外部引入 lunar-javascript):
`bash`
npm run build輸出:dist/qimen.min.js
獨立 IIFE 格式(瀏覽器直接使用):
`bash`
npm run build:standalone輸出:dist/qimen.standalone.min.js
使用:window.Qimen.generateChartByDatetime('2024011510')
首次打包前需安裝開發依賴:
`bash`
npm install
#### 只有日期時間,自動起局(推薦)
這是最常見的使用場景。輸入西曆日期時間,系統自動完成:農曆轉換 → 四柱推算 → 節氣判定 → 拆補法定局 → 完整排盤。
`javascript
import { generateChartByDatetime, chartToObject } from './index.js';
// 2024年1月15日上午10時
const chart = generateChartByDatetime('2024011510');
const result = chartToObject(chart);
console.log('節氣:', result['節氣']); // 小寒
console.log('三元:', result['三元']); // 中元
console.log('陰陽遁:', result['陰陽']); // 陽
console.log('局數:', result['局數']); // 8
console.log('四柱:', result['年柱'], result['月柱'], result['日柱'], result['時柱']);
console.log('值符:', result['值符']);
console.log('值使:', result['值使']);
console.log('地盤:', result['地盤']);
console.log('天盤:', result['天盤']);
console.log('八門:', result['天門']);
console.log('九星:', result['九星']);
console.log('八神:', result['八神']);
`
#### 依據當前時間起盤
適用於即時占卜場景,一行代碼搞定:
`javascript
import { generateChartNow, chartToObject } from './index.js';
// 使用系統當前時間自動起盤
const chart = generateChartNow();
const result = chartToObject(chart);
console.log('當前時間盤局:');
console.log(${result['年柱']}年 ${result['月柱']}月 ${result['日柱']}日 ${result['時柱']}時);${result['節氣']} ${result['三元']} ${result['陰陽']}遁${result['局數']}局
console.log();`
#### 已知四柱與局數,手動起局
若已有四柱資訊與局數,可直接調用主函數:
`javascript
import { generateQimenChart, chartToObject, chartToJSON } from './index.js';
// 輸入參數:[年柱, 月柱, 日柱, 時柱, 局數, 陰陽]
const data = ['甲辰', '丙寅', '戊午', '庚申', 5, '陽'];
// 生成盤局(第一個參數為識別碼,可為任意字串)
const chart = generateQimenChart('my-chart-001', data);
// 轉換為物件格式
const obj = chartToObject(chart);
// 或轉換為 JSON 字串
const json = chartToJSON(chart);
`
#### 單獨調用各層運算
若需要更細緻的控制,可直接調用各層函數:
`javascript
import {
// 基礎查詢
getXunHead, // 查詢旬首
getFuShou, // 查詢符首
getKongWangDirection, // 查詢空亡方位
// 五層運算
getDiPan, // 取得地盤
calculateTianPan, // 計算天盤
calculateEightDoors, // 計算八門
calculateNineStars, // 計算九星
calculateEightGods, // 計算八神
// 定局
calculateJuByChaiBu, // 拆補法定局
JIEQI_JUSHU, // 節氣局數配置表
YUAN_NAMES // 三元名稱
} from './index.js';
// 範例:查詢「庚申」時辰的旬首與符首
const xunHead = getXunHead('庚申'); // 返回 '甲午'
const fuShou = getFuShou('甲午'); // 返回 '辛'
// 範例:取得陽遁五局的地盤
const diPan = getDiPan(true, 5);
// 返回:['辛', '壬', '癸', '庚', '戊', '乙', '己', '丙', '丁']
`
---
#### generateChartByDatetime(datetime)
從日期時間字串直接起盤。自動完成四柱計算、節氣判定、拆補法定局。
參數:
- datetime (string):日期時間字串,格式 yyyyMMddHH(24小時制,HH 為 0-23)
返回: Map 物件,包含完整盤局資訊,額外包含:
- 節氣:當前節氣名稱三元
- :上元/中元/下元節後天數
- :距離節氣交接的天數
範例:
`javascript
import { generateChartByDatetime, chartToObject } from './index.js';
const chart = generateChartByDatetime('2024011510');
const obj = chartToObject(chart);
console.log(obj['節氣']); // 小寒
console.log(obj['三元']); // 中元
console.log(obj['局數']); // 8
`
錯誤處理:
- 格式不正確(非10位數字字串)會拋出錯誤
- 月份、日期、小時超出範圍會拋出錯誤
#### generateChartNow()
依據當前系統時間起盤。適用於即時占卜場景。
返回: Map 物件,包含完整盤局資訊(同 generateChartByDatetime)
範例:
`javascript
import { generateChartNow, chartToObject } from './index.js';
const chart = generateChartNow();
const obj = chartToObject(chart);
console.log(${obj['節氣']} ${obj['三元']} ${obj['陰陽']}遁${obj['局數']}局);`
#### generateQimenChart(id, data)
生成完整的奇門遁甲盤局。需手動提供四柱和局數。
參數:
- id (string):盤局識別碼data
- (array):[年柱, 月柱, 日柱, 時柱, 局數, 陰陽]'甲子'
- 年柱、月柱、日柱、時柱:干支字串,如 '陽'
- 局數:1-9 的整數
- 陰陽: 或 '陰'
返回: Map 物件,包含完整盤局資訊
#### chartToObject(chart)
將盤局 Map 轉換為普通物件。
#### chartToJSON(chart)
將盤局 Map 轉換為 JSON 字串。
#### calculateJuByChaiBu(solar, jieQiJuShu, yuanNames)
根據拆補法計算定局。
參數:
- solar:lunar-javascript 的 Solar 物件jieQiJuShu
- :節氣局數配置表(使用 JIEQI_JUSHU)yuanNames
- :三元名稱陣列(使用 YUAN_NAMES)
返回:
`javascript`
{
jieQiName: '小寒', // 當前節氣
yuan: 1, // 三元索引(0=上元, 1=中元, 2=下元)
yuanName: '中元', // 三元名稱
isYang: true, // 是否陽遁
yinYang: '陽', // '陽' 或 '陰'
gameNumber: 8, // 局數 1-9
daysSinceJieQi: 7 // 距離節氣交接的天數
}
#### getXunHead(ganZhi)
查詢干支所屬旬首。
`javascript`
getXunHead('庚申') // 返回 '甲午'
getXunHead('甲子') // 返回 '甲子'
#### getFuShou(xunHead)
查詢旬首對應的符首(甲所遁藏的六儀)。
`javascript`
getFuShou('甲子') // 返回 '戊'
getFuShou('甲午') // 返回 '辛'
#### getKongWangDirection(xunHead)
查詢旬首對應的空亡方位。
`javascript`
getKongWangDirection('甲子') // 返回 '西北'(戌亥空)
#### getDiPan(isYang, gameNumber)
取得地盤配置。
參數:
- isYang (boolean):是否陽遁gameNumber
- (number):局數 1-9
返回: 九宮天干陣列
#### calculateTianPan(isYang, diPan, hourGan, flyStep)
計算天盤飛布。
#### calculateEightDoors(isYang, diPan, zhiShiDoor, flyStep)
計算八門飛布。
#### calculateNineStars(isYang, zhiFuStar, flyStep)
計算九星飛布。
#### calculateEightGods(isYang, tianGan, diPan)
計算八神飛布。
---
index.html 是一個極簡風格的 API 示例頁面,專注於展示排盤系統生成的完整數據。
- 極簡風格:簡潔的 CSS 樣式,清晰的面板佈局
- 模組化代碼:JavaScript 分為 QimenCore(計算模組)與 App(應用邏輯)
- API 數據優先:完整展示所有 API 輸出,包含 JSON 原始數據
- 向後兼容:結構設計便於未來擴充分析功能與格局拆解
- 日期時辰選擇(自動轉換為四柱)
- 一鍵設定當前時間
- 自動拆補法定局
- 分面板展示各類資訊
- 基本資訊:四柱、時干、陰陽遁、局數
- 定局資訊:節氣、三元、節後天數
- 時間樞紐:旬首、符首、值符、值使、飛步
- 四柱空亡:年月日時空亡方位
- 綜合盤局:九宮格展示五層疊加資訊
- 分層盤面:地盤、天盤、八門、九星、八神各自獨立展示
- JSON 輸出:API 原始數據,便於開發調試
直接用瀏覽器開啟 index.html,無需安裝任何依賴。lunar-javascript 庫透過 CDN 載入。
---
奇門遁甲有兩種主要的定局方法:置閏法與拆補法。本系統採用拆補法,因其規則更為直接明確。
拆補法以節氣交接時刻為嚴格分界點,從節氣交接開始計算天數來判定三元:
- 上元:節後第 1-5 天
- 中元:節後第 6-10 天
- 下元:節後第 11-15 天
「拆」指將跨節氣的旬拆開,節氣前用舊局、節氣後用新局。「補」指節氣後的天數直接補入新局計算。
置閏法考慮符頭(甲子、己卯等)與節氣的配合,有「超神」、「接氣」、「置閏」等複雜處理。當符頭先於節氣到來稱為超神,節氣先於符頭到來稱為接氣,超過一定天數則需置閏。
拆補法則完全以節氣為準,不考慮符頭,規則更為簡明。
一年分為陽遁與陰遁兩個階段:
- 陽遁:冬至到芒種(12個節氣),局數順飛,陽氣漸生
- 陰遁:夏至到大雪(12個節氣),局數逆飛,陰氣漸生
---
| 節氣 | 上元 | 中元 | 下元 |
|------|------|------|------|
| 冬至 | 1 | 7 | 4 |
| 小寒 | 2 | 8 | 5 |
| 大寒 | 3 | 9 | 6 |
| 立春 | 8 | 5 | 2 |
| 雨水 | 9 | 6 | 3 |
| 驚蟄 | 1 | 7 | 4 |
| 春分 | 3 | 9 | 6 |
| 清明 | 4 | 1 | 7 |
| 穀雨 | 5 | 2 | 8 |
| 立夏 | 4 | 1 | 7 |
| 小滿 | 5 | 2 | 8 |
| 芒種 | 6 | 3 | 9 |
| 節氣 | 上元 | 中元 | 下元 |
|------|------|------|------|
| 夏至 | 9 | 3 | 6 |
| 小暑 | 8 | 2 | 5 |
| 大暑 | 7 | 1 | 4 |
| 立秋 | 2 | 5 | 8 |
| 處暑 | 1 | 4 | 7 |
| 白露 | 9 | 3 | 6 |
| 秋分 | 7 | 1 | 4 |
| 寒露 | 6 | 9 | 3 |
| 霜降 | 5 | 8 | 2 |
| 立冬 | 6 | 9 | 3 |
| 小雪 | 5 | 8 | 2 |
| 大雪 | 4 | 7 | 1 |
---
``
qimen/
├── index.html # 極簡 API 示例頁面(CDN 載入 lunar-javascript)
├── index.js # 統一入口,匯出所有公開 API
├── constants.js # 常數定義
│ # - JIEQI_JUSHU:節氣局數配置表
│ # - YUAN_NAMES:三元名稱
│ # - PALACE:九宮索引
│ # - FLY_PATH:飛布軌跡
│ # - 天干地支、九星、八門、八神名稱
│ # - 六甲旬首與符首對應
│ # - 地盤配置(陰陽各九局)
├── utils.js # 通用工具函數
│ # - 陣列旋轉與飛布序列生成
│ # - 旬首、符首查詢
│ # - 空亡方位查詢
│ # - 天干地支提取
├── calculations.js # 五層運算函數
│ # - 河圖、洛書基礎
│ # - 地盤、天盤計算
│ # - 八門、九星、八神飛布
│ # - 拆補法定局(calculateJuByChaiBu)
├── qimen.js # 主控函數
│ # - generateQimenChart:手動起盤
│ # - generateChartByDatetime:日期時間起盤
│ # - generateChartNow:當前時間起盤
│ # - chartToObject / chartToJSON:格式轉換
├── test.js # 測試模組(21 個測試案例)
├── package.json # 專案配置(ES Module)
├── dist/ # 打包輸出目錄(npm run build 生成)
│ ├── qimen.min.js # ES Module 格式(~13KB,需外部 lunar-javascript)
│ ├── qimen.standalone.min.js # IIFE 格式(~337KB,已包含 lunar-javascript)
│ └── API.md # 打包產物使用說明
├── CHANGELOG.md # 版本歷史
└── README.md # 本文件
---
本專案採用打包產物 + GitHub 自動源碼的 Release 模式。
每個 Release 包含:
| 附件 | 內容 | 用途 |
|------|------|------|
| qimen-dunjia-v{版本}.zip | 打包產物 + 示例 + 文檔 | 快速使用 |Source code (zip/tar.gz)
| | 完整源碼 | GitHub 自動生成,二次開發用 |
``
qimen-dunjia-v{版本號}.zip
├── qimen.min.js # ES Module(~13KB,需外部 lunar-javascript)
├── qimen.standalone.min.js # IIFE(~337KB,瀏覽器直接使用)
├── API.md # API 使用說明
└── index.html # 網頁示例
| 需求 | 使用檔案 |
|------|----------|
| 瀏覽器