奇門遁甲排盤系統

本系統實現奇門遁甲的完整排盤運算，採用拆補法定局，將特定時刻的干支資訊轉化為多層次的空間分布圖，用於時空決策分析。

目錄

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，輸入日期時間即可自動排盤。

方式二：Node.js 環境

安裝依賴

npm install

常用指令

| 指令 | 說明 | |------|------| | npm test | 執行單元測試（21 個測試案例） | | npm run build | 打包為 ES Module（排除 lunar-javascript） | | npm run build:standalone | 打包為獨立 IIFE（包含所有依賴） |

單元測試

npm test

測試涵蓋：

• 陽遁/陰遁局數計算
• 甲遁邏輯處理
• generateChartByDatetime API（日期解析、節氣、三元）
• generateChartNow API
• 輸入驗證（格式、範圍檢查）
• API 一致性驗證

打包

ES Module 格式（需外部引入 lunar-javascript）：

npm run build
# 輸出：dist/qimen.min.js

獨立 IIFE 格式（瀏覽器直接使用）：

npm run build:standalone
# 輸出：dist/qimen.standalone.min.js
# 使用：window.Qimen.generateChartByDatetime('2024011510')

首次打包前需安裝開發依賴：

npm install

只有日期時間，自動起局（推薦）

這是最常見的使用場景。輸入西曆日期時間，系統自動完成：農曆轉換 → 四柱推算 → 節氣判定 → 拆補法定局 → 完整排盤。

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['八神']);

依據當前時間起盤

適用於即時占卜場景，一行代碼搞定：

import { generateChartNow, chartToObject } from './index.js';

// 使用系統當前時間自動起盤
const chart = generateChartNow();
const result = chartToObject(chart);

console.log('當前時間盤局：');
console.log(`${result['年柱']}年 ${result['月柱']}月 ${result['日柱']}日 ${result['時柱']}時`);
console.log(`${result['節氣']} ${result['三元']} ${result['陰陽']}遁${result['局數']}局`);

已知四柱與局數，手動起局

若已有四柱資訊與局數，可直接調用主函數：

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);

單獨調用各層運算

若需要更細緻的控制，可直接調用各層函數：

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);
// 返回：['辛', '壬', '癸', '庚', '戊', '乙', '己', '丙', '丁']

API 參考

便捷起盤函數（推薦）

generateChartByDatetime(datetime)

從日期時間字串直接起盤。自動完成四柱計算、節氣判定、拆補法定局。

參數：

• datetime (string)：日期時間字串，格式 yyyyMMddHH（24小時制，HH 為 0-23）

返回： Map 物件，包含完整盤局資訊，額外包含：

• 節氣：當前節氣名稱
• 三元：上元/中元/下元
• 節後天數：距離節氣交接的天數

範例：

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）

範例：

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）

返回：

{
    jieQiName: '小寒',      // 當前節氣
    yuan: 1,               // 三元索引（0=上元, 1=中元, 2=下元）
    yuanName: '中元',       // 三元名稱
    isYang: true,          // 是否陽遁
    yinYang: '陽',          // '陽' 或 '陰'
    gameNumber: 8,         // 局數 1-9
    daysSinceJieQi: 7      // 距離節氣交接的天數
}

基礎查詢函數

getXunHead(ganZhi)

查詢干支所屬旬首。

getXunHead('庚申')  // 返回 '甲午'
getXunHead('甲子')  // 返回 '甲子'

getFuShou(xunHead)

查詢旬首對應的符首（甲所遁藏的六儀）。

getFuShou('甲子')  // 返回 '戊'
getFuShou('甲午')  // 返回 '辛'

getKongWangDirection(xunHead)

查詢旬首對應的空亡方位。

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       # 本文件

Release 發布策略

本專案採用打包產物 + GitHub 自動源碼的 Release 模式。

Release 附件

每個 Release 包含：

| 附件 | 內容 | 用途 | |------|------|------| | qimen-dunjia-v{版本}.zip | 打包產物 + 示例 + 文檔 | 快速使用 | | Source code (zip/tar.gz) | 完整源碼 | GitHub 自動生成，二次開發用 |

Zip 內容

qimen-dunjia-v{版本號}.zip
├── qimen.min.js           # ES Module（~13KB，需外部 lunar-javascript）
├── qimen.standalone.min.js # IIFE（~337KB，瀏覽器直接使用）
├── API.md                 # API 使用說明
└── index.html             # 網頁示例

使用場景

| 需求 | 使用檔案 | |------|----------| | 瀏覽器 <script> 直接用 | qimen.standalone.min.js | | Node.js / Bundler | qimen.min.js + npm install lunar-javascript | | 二次開發 / 學習 | 下載 GitHub 自動生成的 Source code |

版本歷史

詳見 CHANGELOG.md

授權

本系統為學習與研究用途，核心演算法基於傳統奇門遁甲理論。lunar-javascript 庫由 6tail 開發維護。