奇門遁甲排盤系統

本系統實現奇門遁甲的排盤與判斷：將特定時刻的干支資訊轉化為多層次的空間分布圖，再據以判格局、十干克應與旺相休囚。

定局法提供拆補與符頭兩派並列（預設拆補）。判斷層的每則判定都帶出處（書／篇／原文），典籍有異說者並列而不代為擇一——這是本專案與其他排盤工具最大的不同。

目錄

1. 理論背景
2. 系統架構
3. 快速開始
4. 判斷層
5. API 參考
6. 網頁介面
7. 定局法：拆補與符頭
8. 夜子時：日柱換日之界
9. 基準自陳
10. 節氣局數表
11. 檔案結構
12. Release 發布策略
13. 版本歷史
14. 授權

理論背景

河圖與洛書

河圖（先天八卦）代表宇宙形成前的理想秩序，強調陰陽對立配對，體現「天地定位、山澤通氣、雷風相薄、水火不相射」的對稱結構。

洛書（後天八卦）代表萬物形成後的實際運作，數字排列為「戴九履一、左三右七、二四為肩、六八為足、五居中央」，對應八方位與四季循環。

奇門遁甲以洛書九宮為空間載體，在其上疊加多層時間資訊，形成動態的時空分析模型。

盤局結構

奇門遁甲的盤局由五層組成，各層獨立運算後疊加於洛書九宮：

第一層：地盤

三奇六儀（乙丙丁戊己庚辛壬癸）的靜態分布，根據局數（1-9）與陰陽遁確定。陽遁順布，由一宮起始依洛書軌跡順飛；陰遁逆布，由九宮起始逆飛。甲為十干之首，象徵主帥，遁入六儀之下而不直接顯現，此即「遁甲」之意。

第二層：天盤

天干隨時辰的動態位移。以時干位置為放置起點、符首位置為取值起點，沿飛布軌跡旋轉映射。天盤與地盤的干支組合形成「奇門格局」，是斷事的核心依據。

第三層：八門

門戶飛布，代表地理空間的吉凶屬性。八門為休、生、傷、杜、景、死、驚、開，各有本位宮與飛布後的落宮。值使門隨時辰輪轉，主事態發展的通道。

第四層：九星

星曜飛布，代表天象對人事的影響。九星為天蓬、天芮、天沖、天輔、天禽、天心、天柱、天任、天英。值符星隨時辰輪轉，主事態的主導力量。天禽居中宮無定位，寄於二宮或八宮。

第五層：八神

神煞飛布，代表超自然力量的介入。陽局八神為值符、騰蛇、太陰、六合、勾陳、朱雀、九地、九天；陰局將勾陳、朱雀替換為白虎、玄武。八神以時干位置為起點飛布。

核心概念

旬首：六十甲子分為六旬，每旬以甲日起始。六旬首為甲子、甲戌、甲申、甲午、甲辰、甲寅。

符首：甲所遁藏的六儀。對應關係為：

• 甲子旬 → 戊（甲子遁戊）
• 甲戌旬 → 己（甲戌遁己）
• 甲申旬 → 庚（甲申遁庚）
• 甲午旬 → 辛（甲午遁辛）
• 甲辰旬 → 壬（甲辰遁壬）
• 甲寅旬 → 癸（甲寅遁癸）

值符：當前主事的九星，由符首在地盤上的位置決定。

值使：當前主事的八門，由符首在地盤上的位置決定。

空亡：每旬末兩個地支無天干配對，為空亡位，主虛無、延遲、變數。

孤虛：與空亡有別。《奇門遁甲統宗》〈孤虛〉：「年月日時俱以前一位空亡為孤，孤沖為虛。如子年亥為孤，巳為虛。」孤虛逐支推算，與該柱屬於哪一旬無關；本系統另以 年旬空 等欄位提供旬空亡方位（統宗所謂「旬孤」）。用於「背孤擊虛」。

系統架構

┌─────────────────────────────────────────────────────────┐
│                      index.js                           │
│                    （統一入口）                          │
├─────────────────────────────────────────────────────────┤
│                      qimen.js                           │
│                （主控函數：整合排盤）                     │
├──────────────┬──────────────┬───────────────────────────┤
│ constants.js │   utils.js   │     calculations.js       │
│  （常數表）   │ （工具函數）  │    （五層運算函數）        │
├──────────────┴──────────────┴───────────────────────────┤
│               lunar-javascript (npm)                    │
│              （農曆轉換：node_modules）                  │
└─────────────────────────────────────────────────────────┘

快速開始

方式一：npm 安裝（推薦）

npm install qimen-dunjia

import { generateChartByDatetime, chartToObject } from 'qimen-dunjia';

// 指定時間起盤
const chart = generateChartByDatetime('2024011510');  // 2024-01-15 10:00
const result = chartToObject(chart);
console.log(result['節氣'], result['三元'], result['局數']);  // 小寒 中元 8

方式二：網頁介面（最簡單）

直接用瀏覽器開啟 index.html，輸入日期時間即可自動排盤。

方式三：本地開發

安裝依賴

git clone https://github.com/arc119226/qimen_dunjia.git
cd qimen_dunjia
npm install

常用指令

| 指令 | 說明 | |------|------| | npm test | 執行單元測試（99 個測試，約 1.7 秒） | | 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 chart = generateQimenChart({
    年柱: '甲辰',
    月柱: '丙寅',
    日柱: '戊午',
    時柱: '庚申',
    局數: 5,
    陰陽: '陽'
});

// 轉換為物件格式
const obj = chartToObject(chart);

// 或轉換為 JSON 字串
const json = chartToJSON(chart);

單獨調用各層運算

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

import {
    // 基礎查詢
    getXunHead,           // 查詢旬首
    getFuShou,            // 查詢符首
    getKongWangDirection, // 查詢旬空亡方位
    getXunKongWang,       // 查詢旬孤虛（孤與虛各兩個方位）
    getGuXu,              // 查詢孤虛（統宗逐支規則）
    
    // 五層運算
    getDiPan,             // 取得地盤
    calculateTianPan,     // 計算天盤
    calculateEightDoors,  // 計算八門
    calculateNineStars,   // 計算九星
    calculateEightGods,   // 計算八神
    
    // 定局
    calculateJuByChaiBu,  // 拆補法定局
    JIEQI_JUSHU,          // 節氣局數配置表
    YUAN_NAMES            // 三元名稱
} from './index.js';

// 範例：查詢「庚申」時辰的旬首與符首
const xunHead = getXunHead('庚申');  // 返回 '甲寅'（庚申為甲寅旬第 7 位）
const fuShou = getFuShou('甲寅');    // 返回 '癸'

// 範例：取得陽遁五局的地盤
const diPan = getDiPan(true, 5);
// 返回：['乙', '壬', '丁', '丙', '戊', '庚', '辛', '癸', '己']
// 對應宮位：  巽    離    坤    震    中    兌    艮    坎    乾

判斷層

排好的盤可以再送進判斷層。patterns.js 與 qimen.js 並列而非其下游—— 每個判定器都是 chartToObject() 輸出的純函數，不依賴排盤過程， 故不同流派排出的盤只要格式相同就都能判。

三條貫穿的原則：

1. 每則判斷帶出處（書／篇／原文）。典籍時常彼此矛盾，沒有出處的規則日後無從裁決。
2. 異說並列，以 讀法 標明，不代為擇一。
3. 能推導的先推導，再拿典籍明列的表去對——門迫由五行關係推得， 而後與《法竅》明列的十三對逐對核驗。

格局判斷

排好的盤可以再送進 detectPatterns() 判格局。判定器只讀盤面，不依賴排盤過程：

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

const chart = chartToObject(generateChartByDatetime('2024011510'));

for (const item of detectPatterns(chart)) {
    console.log(item.吉凶, item.格, item.宮 || '（全盤）');
    console.log('  ', item.細節);
    console.log('  出處：《' + item.出處[0].書 + '》' + item.出處[0].篇);
}
// 凶 門迫 坤宮
//    傷門（木）臨坤宮（土），門克宮
//   出處：《奇門法竅》論八門迫制
// 吉 三奇得使 艮宮
//    天盤丙奇加地盤戊（甲子）於艮宮
//   出處：《奇門遁甲統宗》奇門四十格

每則判定包含：

| 欄位 | 說明 | |---|---| | 類 | 格局 或 十干克應 | | 格 | 格局名稱 | | 吉凶 | 吉／凶／中性 | | 宮 | 落宮；全盤性者為 null | | 細節 | 該例的具體條件 | | 出處 | 書名、篇名與原文 | | 讀法 | 僅在典籍有異說時出現 | | 異名 | 僅在他書另有命名時出現（十干克應多有）|

兩類判定要分開看。「格局」是各有專名的格；「十干克應」是天盤干加地盤干的 九宮逐格判定，每盤必得九則。兩類會撞名 —— 十干克應的戊戊格典籍即名「伏吟」， 與盤面層級的伏吟（天盤地盤全同）不是一回事，故以 類 區分。

異說並列，不代為擇一。 例如六儀擊刑的判定範圍，《法竅》「甲子直符臨三宮」的 字面只算值符之儀，另有一說算天盤任一六儀，兩者出現率相差近四倍。本系統兩種都給， 以 讀法 標明，由使用者依所遵流派過濾。

目前已實作：

• 格局十一條：伏吟、反吟、門迫、宮迫、和義、五不遇時、三奇得使、三奇入墓、 天地人三遁、六儀擊刑、截路空亡

• 十干克應 81 格：天盤九干 × 地盤九干（甲遁於六儀不上盤，故為 9×9 而非 10×10）。 以《旨歸》卷五與《秘笈大全》〈十干剋應訣〉為底，《法竅》另一套命名收於 異名。 每格帶 斷語——典籍真正說的話，而非只有格名與吉凶標籤。

  吉凶 不是典籍所標，是本專案據斷語所判。 四部書皆無吉／凶標籤。 可外部驗證者僅《寶鑒御定》明列的四格（「螣蛇夭矯、朱雀投江、青龍逃走、 白虎猖狂已上四格俱主凶」）與《統宗》〈奇門四十格〉的十二則， 兩者皆未參與建表而寫成測試；其餘各格請以斷語為準。

門迫、宮迫、和義：一句賦文與它自己的註

專案原先只輸出門克宮一種，據《法竅》卷一賦文「宮制其門不為迫」。 但同一段的下一行註就給出了兩張表並重新定義「迫」：

宮迫者，謂開驚兩門臨離宮，火克金也…此宮克門也。凡宮迫門者，為主克客也。 門迫者，開驚二門臨震巽二宮，金克木也…此門克宮也。 蓋迫者，逼也，急切受制，或門受制於宮，或宮受制於門，彼此相抗，扼抑不容。

賦文說「宮制其門不為迫」，它自己的註卻名之為「宮迫」——這是書內張力， 依專案原則呈現而不代為裁決。三者互斥，每宮至多一則：

| 格 | 關係 | 主客 | 吉凶 | 對數 | |---|---|---|---|---| | 門迫 | 門克宮 | 客克主 | 凶 | 13 | | 宮迫 | 宮克門 | 主克客 | 凶 | 13 | | 和義 | 宮生門 | 主生客 | 吉 | 12 |

和義出自同一句賦文「宮若生門則為義」；〈論八門迫制〉稱「和義」—— 「凶門和義，其凶不凶；吉門和義，其吉益吉」。

門生宮與比和不立格名：《法竅》〈論門宮生克〉雖論門生宮（客生主）卻未命名， 依專案慣例不代為命名。

出處篇名亦一併更正。 原掛〈論八門迫制〉，但該篇實際在卷八， 內容為不分方向的「吉門迫制，吉事不成…凶門和義，其凶不凶」； 賦文與其註在卷一。

五不遇時：兩種讀法差在合不合論干支

煙波釣叟歌本身是欠定的——「時干來克日干上，甲日須知時忌庚」只給了甲日一例， 未言同性與否。定式來自緊貼歌句下方的注疏，而兩部書以完全不同的方法得到同一組：

• 《遁甲演義》葛洪注直接列出十組：甲日庚午、乙日辛巳、丙日壬辰、丁日癸卯、戊日甲寅、 己日乙丑、庚日丙子、辛日丁酉、壬日戊申、癸日己未
• 《奇門寶鑒御定》〈釋五不遇時〉給構造法：「其法以庚加午逆行，越過戌亥，為時之定局」 ——自庚午起逆行、越過戌亥兩支，所得與《演義》所列逐字相同（test.js 直接跑這個構造法）

《寶鑒》把兩派的分野講得最清楚：

凡十干環列，順數七干，逆數五干，皆克第一干。順數者，止論其干，故名七殺。 逆數者，合論其干支，故曰五不遇時。

也就是說「五」正是合論干支才數得出來的。故兩讀並列：

| 讀法 | 出處 | 120 格中命中 | 每日 | |---|---|---|---| | 干支定式 | 《演義》《寶鑒》 | 10 | 1.00 次 | | 陽克陽陰克陰（即七殺） | 《法竅》〈論五不遇時〉 | 12 | 1.21 次 |

兩者差在己日乙亥、庚日丙戌兩格——定式合論干支故只取一格，《法竅》只論干故兩格皆取。 定式為同性讀法的子集，十組定式必同時觸發兩則判定（比照六儀擊刑的寬嚴兩式）。

同性這個限制不可省。 若只查五行相克而不論陰陽，會命中 24 格、每日觸發 2.43 次， 而九部書無一列出其中任何一格。

旺相休囚

旺相休囚決定的是吉凶之輕重而非有無（《法竅》：「吉門有氣益吉，無氣減吉； 凶門有氣益凶，無氣減凶」），故不列入 detectPatterns，另以 assessVigor() 提供：

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

const chart = chartToObject(generateChartByDatetime('2024122512'));
const vigor = assessVigor(chart);

vigor.月令;    // { 支: '子', 五行: '水' }
vigor.八節;    // { 卦: '坎', 旺門: '休門' }
vigor.九星[6]; // { 宮: '艮', 星: '天蓬', 五行: '水', 關係: '同類',
               //   諸家: [ { 讀法, 狀態, 出處 }, … 4 ] }
vigor.八門[5]; // { 宮: '艮', 門: '休門', 狀態: '旺' }

九星旺相四家並列。 語料中互不相容者至少七家，本專案收其中有完整算例的四家：

| 星與月令的關係 | 釣叟歌通行本 | 法竅注本 | 統宗卷一 | 三元經 | |---|---|---|---|---| | 同類 | 相 | 旺 | 相 | 相 | | 我生 | 旺 | 相 | 旺 | 旺 | | 生我 | 廢 | 廢 | 死 | 死 | | 我克 | 休 | 休 | 廢 | 休 | | 克我 | 囚 | 囚 | 囚 | 囚 |

旺與相在各家之間互換，故取任一家為代表都會失真。

出處分別為《寶鑒御定》〈釋氣應〉、《法竅》卷一〈煙波釣叟賦注釋〉、 《統宗》卷之一〈九星旺相〉、《欽定古今圖書集成》〈釋九星休旺〉引《三元經》。

收錄的門檻是「自帶算例」。 四家皆附天蓬水星的五格算例，可用其算例反驗 其對照表——對照表是從規則那句話讀出來的，算例是獨立的一組月份，兩者相符 才證明那句話被讀對了。test.js 逐家跑這個反驗。

鍵名不用書名。 《遁甲演義》一書之內即並存三說、《統宗》並存二說、 《秘笈大全》並存二說——「某書主某說」在這幾部書上都不成立，只能逐篇認定。

未收的三家記於 VIGOR_READINGS_NOT_ADOPTED 並各附理由，不靜默丟棄： 《演義》引《三元經》與《秘笈大全》卷二十三皆無算例； 《演義》〈五行旺相休囚〉為方位式而非月令式，連「廢」格都沒有。

《統宗》卷三〈旺相休囚〉那條四季表不列為任何一家的書證：原文 「春木相火旺水廢金囚土休」有兩讀——「春」是月令抑或木星？兩讀所得五格有 四格相反，而原文全條無一「星」字（夾在〈天馬方〉與〈天目〉之間）。

八門旺相依《統宗》〈八節應八門旺相〉的八節輪轉，該節所屬之卦其本位門為旺， 其餘依八門固定次序推得旺絕胎沐死囚休廢。需要節氣，故手動起盤 （generateQimenChart）時 八門 為 null 而非臆測。

API 參考

便捷起盤函數（推薦）

generateChartByDatetime(datetime, options?)

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

參數：

• datetime (string)：日期時間字串，格式 yyyyMMddHH（24小時制，HH 為 0-23）
• options.定局法 (string, 選填)：'拆補'（預設）或 '符頭'，見定局法

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

• 節氣：當前節氣名稱
• 三元：上元/中元/下元
• 定局法：實際採用的定局法

拆補法另有：

• 節後天數：距離節氣交接的天數（自交接時刻起算取整，節氣當日為 0）

符頭法另有：

• 上元符頭：統領本循環的上元符頭（甲子／己卯／甲午／己酉）
• 符頭：本元之符頭（甲己日）
• 超接：超神／接氣／正授
• 超接天數：符頭與節氣相距的天數
• 閏局：是否為重用本氣三元的閏局

兩法皆有基準自陳：

• 時間基準：輸入的時刻被當成哪一種時（見下）
• 曆法基準：節氣時刻取自哪一種曆（見下）

範例：

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(options?)

依據當前系統時間起盤。適用於即時占卜場景。

參數：

• options.時區（選填）：目標時區，如 'UTC+8'、'+8'、8、'UTC-05:30'
• 其餘同 generateChartByDatetime

返回： Map 物件，包含完整盤局資訊（同 generateChartByDatetime），另加：

• 時鐘來源：所用時刻的來源與其與盤面基準的落差

不設猜測性預設。 未指定 時區 時取本機牆上時鐘（行為不變）， 並自陳其與盤面基準的落差：

generateChartNow();
// 時鐘來源: { 來源: '本機時鐘', 本機時區: 'UTC-05:00',
//            與盤面基準時差: -13, 一致: false, 警告: '…' }

⚠️ 節氣算在 UTC+8，故在非 UTC+8 的機器上，本機牆上時刻會被直接當成 盤面基準時刻排盤——同一物理瞬間，UTC 與 UTC+8 得到的日柱與時柱皆不同。

指定 時區 則把當下這一瞬間換算到該時區的牆上時刻，那是明示的選擇：

generateChartNow({ 時區: 'UTC+8' });   // 換算到東八區的牆上時刻
generateChartNow({ 時區: -5 });        // 換算到西五區

無法解析的寫法會拋錯而非默默取本機（如 'Asia/Taipei' 這類 IANA 名稱 目前不支援，只收 UTC 偏移）。

本專案不代為猜測：多數流派對境外起課用當地時間定時辰， 逕自換成 UTC+8 等於替使用者選了一派。

範例：

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

const chart = generateChartNow();
const obj = chartToObject(chart);

console.log(`${obj['節氣']} ${obj['三元']} ${obj['陰陽']}遁${obj['局數']}局`);

主函數

generateQimenChart(pillars)

生成完整的奇門遁甲盤局。需手動提供四柱和局數。

參數： pillars (object)

• 年柱、月柱、日柱、時柱：干支字串，如 '甲子'
• 局數：1-9 的整數
• 陰陽：'陽' 或 '陰'

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

generateQimenChart({
    年柱: '甲辰', 月柱: '丙寅', 日柱: '戊午', 時柱: '庚申',
    局數: 5, 陰陽: '陽'
});

舊式簽名：generateQimenChart(id, [年柱, 月柱, 日柱, 時柱, 局數, 陰陽]) 仍可使用， 但不建議 —— 其中的 id 從未參與運算，而位置陣列在日柱與時柱寫反時不會報錯， 只會安靜地產出另一張盤。

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      // 距離節氣交接的天數（節氣當日為 0）
}

基礎查詢函數

getXunHead(ganZhi)

查詢干支所屬旬首。

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

getFuShou(xunHead)

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

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

getGuXu(ganzhi)

依《奇門遁甲統宗》〈孤虛〉逐支推算：孤為該支前一位，虛為孤之對沖。

getGuXu('癸卯')  // { 孤: '東北東', 虛: '西南西' }（卯前一位為寅，寅沖申）

getXunKongWang(ganzhi)

查詢該干支所屬旬的旬孤虛。

getXunKongWang('乙丑')
// { 孤: ['西北西', '北北西'], 虛: ['東南東', '南南東'] }（甲子旬空戌亥）

getKongWangDirection(xunHead)

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

getKongWangDirection('甲子')  // 返回 ['西北西', '北北西']（戌亥空）
// 注意：返回的是陣列，兩個元素分別對應兩個空亡地支的方位

五層運算函數

getDiPan(isYang, gameNumber)

取得地盤配置。

參數：

• isYang (boolean)：是否陽遁
• gameNumber (number)：局數 1-9

返回： 九宮天干陣列

calculateTianPan(isYang, diPan, hourGan, flyStep)

計算天盤飛布。

calculateEightDoors(isYang, diPan, zhiShiDoor, flyStep)

計算八門飛布。

calculateNineStars(zhiFuStar, tianGan, diPan)

計算九星飛布。

參數：

• zhiFuStar (string)：值符星
• tianGan (string)：當前時干（已處理甲遁）
• diPan (Array)：地盤配置

calculateEightGods(isYang, tianGan, diPan)

計算八神飛布。

網頁介面

index.html 是一個極簡風格的 API 示例頁面，專注於展示排盤系統生成的完整數據。

設計理念

• 極簡風格：簡潔的 CSS 樣式，清晰的面板佈局
• 模組化代碼：JavaScript 分為 QimenCore（計算模組）與 App（應用邏輯）
• API 數據優先：完整展示所有 API 輸出，包含 JSON 原始數據
• 向後兼容：結構設計便於未來擴充分析功能與格局拆解

功能特點

• 日期時辰選擇（自動轉換為四柱）
• 一鍵設定當前時間
• 自動拆補法定局
• 分面板展示各類資訊

顯示資訊

• 基本資訊：四柱、時干、陰陽遁、局數
• 定局資訊：節氣、三元、節後天數
• 時間樞紐：旬首、符首、值符、值使、飛步
• 四柱旬空與孤虛：旬空亡方位（年旬空…）與統宗孤虛（年孤虛…）分別列出
• 綜合盤局：九宮格展示五層疊加資訊
• 分層盤面：地盤、天盤、八門、九星、八神各自獨立展示（八門的 API 欄位名為 天門）
• JSON 輸出：API 原始數據，便於開發調試

使用方式

直接用瀏覽器開啟 index.html，無需安裝任何依賴，也不需要網路連線。

頁面載入的是 dist/qimen.standalone.min.js（已內含 lunar-javascript），與 Node.js 端使用完全相同的一份計算邏輯。網頁不再自帶引擎副本——先前那份副本與函式庫逐漸分歧， 曾導致五個節氣期間靜默算出錯誤盤局。

若你修改了原始碼，需重新執行 npm run build:standalone 讓網頁反映變更。

定局法：拆補與符頭

兩派之爭

奇門遁甲的定局法有兩大流派，典籍中留有正面交鋒的紀錄。《奇門寶鑒御定》斥拆補派 「不顧尊甲之義，止以節氣為准」「創為拆補以亂符頭」「殊違尊甲之旨」； 拆補派則以規則簡明、不需置閏為長。

本專案兩法俱備，不代為擇一：

generateChartByDatetime('2024061512')                    // 芒種中元 陽遁3局（拆補，預設）
generateChartByDatetime('2024061512', { 定局法: '符頭' }) // 夏至上元 陰遁9局（符頭）

兩者不是同一件事的兩個名字。2024 全年逐日取午時比對，97.3% 的時刻局數不同—— 選哪一派，盤就完全不同。

拆補法原理

拆補法以節氣交接時刻為嚴格分界點，自該時刻起算經過的時間長度決定三元：

• 上元：交接後 0 ～ 未滿 5 天
• 中元：交接後 5 ～ 未滿 10 天
• 下元：交接後 10 天以後

注意分界點是「交接時刻」而非午夜。例如 2024 年小寒交接於 1 月 6 日 04:49， 則 1 月 11 日 03:00 仍屬上元、同日 06:00 已入中元。若採用逐日計算的流派， 兩者都會被歸為中元——本系統刻意採前者，兩種算法在每個節氣的第 6、11 兩天 會有數小時的差異。

「拆」指將跨節氣的旬拆開，節氣前用舊局、節氣後用新局。「補」指節氣後的天數直接補入新局計算。

符頭法原理（超神接氣置閏）

符頭法以符頭（甲己日）為體、節氣為用。《寶鑒御定》： 「考古法以甲子、己卯、甲午、己酉為符頭者，緣尊甲以制奇門，故立符以定元首也。 是以符頭為體，節氣為用。」

• 上元符頭只有四日：甲子、己卯、甲午、己酉（皆值子午卯酉），每十五日一見
• 自上元符頭起，五日一元（「五日都來換一元」），依次上元、中元、下元
• 每個循環依序統領下一個節氣；除非置閏（見下）

三態：

| 態 | 條件 | 典籍語 | |---|---|---| | 超神 | 節氣在符頭之後 | 符先節後 | | 接氣 | 節氣在符頭之前 | 節先符後 | | 正授 | 同日 | 三元順序始為正受 |

置閏：綁在芒種與大雪，不是綁在日數

符頭循環固定十五日，節氣平均 15.2184 日，故節氣漸漸落到符頭之後（超神）。 但置閏不是「超神滿幾日就閏」——三部書一致把它綁在兩個特定節氣上：

《遁甲演義》：「置閏定在芒種、大雪之後。設遇小滿、小雪二氣之交， 雖超九日、十日，不可置閏。」又：「閏奇若不居芒種，便是陰終大雪時。」 《寶鑒御定》：「遇芒種大雪，重用本氣三元。」

日數只是啟用窗口。《演義》：「超越經旬或九朝，或過十一日無饒。 閏奇額在斯三日，更不加前與後稍。」

《統宗》康熙五十七年的算例把這一步寫得最清楚：

自十六甲子至二十四壬申，已超九日，為期大遠。故十六日甲子不作夏至上局， 而為芒種閏奇上局……六月初二日己卯始得為夏至上局。

觸發的是候選節氣（夏至）離符頭太遠，而閏落在當前節氣（芒種）。

計數口徑：典籍用含頭計數。上引「超九日」的曆日之差其實是八日 （五月十六至五月廿四）；《演義》「四月初五日是甲子，已在立夏前九日矣」亦然。 本專案輸出的 超接天數 是曆日之差，讀典籍時請記得其數大一。

1800–2100 實測：置閏 105 次（每 2.87 年一閏，理論值 2.86）， 全部落在芒種或大雪，且未跳過任何一個節氣（《統宗》「俾三元之次序不紊」）。

驗證：《統宗》的正授是外部錨點

符頭鏈由純規則自 1700 年附近的任意起點走出，並未把任何歷史日期餵進去。 若規則正確，《統宗》所記的正授必然自己浮現：

直至康熙五十八年六月二十三日立秋，而甲子符頭恰當日，是為正授， 本日即是陰遁二局。

該日為 1719-08-08，程式所得正是立秋上元、正授、陰遁二局。test.js 斷言此事—— 錨點是檢查而非建構輸入。

另有兩則完整算例逐日重現：《統宗》康熙五十六至五十八年（10 個檢核點， 含整段閏奇），與《法竅》〈論拆局補局〉（7 個檢核點）。

已知從缺

1. 時粒度的疊局。《法竅》〈論拆局補局〉的原文本身即以時刻定義，一段文字裡 疊局出現三次（如「子丑二時與寅初之三刻，卻是己酉上元符頭統領，法當疊作 處暑上局補之」）。本實作為日粒度，該日全日歸於同一元。可觀測的後果： 1962-09-08 白露交於寅初三刻，《法竅》作「符先節後，法當用超」而本專案作 「正授」。test.js 以斷言釘住此一分歧——日後若實作疊局，該則會變紅。
2. 《秘笈大全》另記一個閾值：「夫閏奇者，有過九日而後閏者， 有過十四日而值閏者，各有決例。」該書只報告兩派並存，未給十四日一派的 完整規則，亦無算例可驗，故依本專案的收錄門檻（自帶算例）記載於 FU_TOU_LEAP_THRESHOLD_VARIANT 而不實作。

夜子時：日柱換日之界

夜間十一時至十二時（子時前半）究竟算當日還是次日，兩派並存。 這不是邊角——它佔全部時辰的 1/12（8.3%），而日柱一翻， 旬首、符首、值符、值使全部連鎖改變，是整張盤改。

generateChartByDatetime('2024011523')                    // 日柱己卯、時柱甲子（預設，次日派）
generateChartByDatetime('2024011523', { 夜子時: '當日' }) // 日柱戊寅、時柱壬子

時柱隨日柱而變（五鼠遁）：己日子時為甲子（甲己還加甲），戊日子時為壬子（戊癸壬子頭）。

兩派給的是兩張完全不同的盤，無法像格局的異說那樣在同一輸出中並列， 故比照定局法作為選項，並在輸出中自陳：

| 欄位 | 意義 | |---|---| | 夜子時 | 實際採用的派別 | | 落於夜子時 | 所問時刻是否落在夜間十一時至十二時 |

定局不受此選影響——拆補與符頭都以時刻／曆日為準，非以日柱。

典籍依據：查無明文，但兩派各有可考的用例

九部書沒有任何一部寫出定義句——「子初屬前日」「子正方換日」之類的話 一次也沒有出現，「夜子」二字全語料只見一次。兩派都是自用例反推的。

《遁甲演義》唯一一句正面陳述是「凡換奇皆子時換也」，只說子時， 不辨子初子正，兩派共用。

次日派（日柱於子初 23:00 換）——《法竅》卷二〈論拆局補局〉三個刻數算例

這一派的證據最硬，因為它可用算術檢驗：原文自報時辰與刻數，只有一種 換日法對得上（時憲書九十六刻制，一時辰＝八刻＝二小時）。

| 原文 | 子初法 | 子正法 | |---|---|---| | 「己丑自子時起至辛卯辰初一刻止，計二十八時零一刻」 | 28 時 1 刻 ✓ | 27 時 5 刻 ✗ | | 「子丑二時與寅初之三刻……雖少二時零三刻」 | 2 時 3 刻 ✓ | 1 時 7 刻 ✗ | | 「甲子日之子丑寅卯辰五時」 | 5 時 ✓ | 4 時 4 刻 ✗ |

三例皆合子初法而皆不合子正法。刻數對照由《旨歸》卷三十八「果於十點鐘亥正 生女」校準（亥正＝22:00，故子初＝23:00）。test.js 逐例重算。

當日派（日柱於子正 00:00 換）——《統宗》〈置閏法〉的紀日寫法

《統宗》記康熙五十六年夏至在「五月十三日丙寅夜子初二刻」，把夜子時刻 繫於當日（丙寅）而非次日（丁卯）；同段「十一日甲子……已超三日」用的是 十一、十二、十三的含頭計數，與此自洽。

但這是曆書的紀日寫法——民用日以子夜為界，二十三時半本來就還算十三日。 《欽定古今圖書集成》〈釋諸求發斂加時〉的曆算公式亦同（其「命起子初，算外」 等於明說子初＝23:00、曆日始於子正），那是曆法之日，未必等於起課之日柱。

故預設取次日派：它有三個可算的算例，而當日派只有紀日寫法。 但兩派並列，因為典籍終究沒有明文裁決。

基準自陳

排盤有兩個外部基準，不宣告，使用者就無從得知自己拿到的是什麼。 兩者都只陳述、不改動任何一格盤面，並且都可被外部事實證偽（見 test.js）。

曆法基準：定氣，非平氣

節氣時刻取視太陽黃經（定氣），即清順治二年（1645）行用時憲曆之法， 對一切年份一律適用。此前中土行平氣——將回歸年均分二十四份，即授時曆之法。

二者相差可達二日餘，而三元一桶僅五日寬，故明代以前的日期， 其三元與局數未必與當時曆書相合。

這不是實作瑕疵，而是典籍自身即分屬兩曆：

| 典籍 | 原文 | 所據 | |---|---|---| | 《奇門法竅》〈論拆局補局〉 | 「如遵時憲書節氣為憑，其正授、超神、接氣、置閏不辨而自明矣」 | 定氣 | | 《遁甲演義》 | 「以授時歷看，審訂太陽過宮」 | 平氣 | | 《奇門遁甲秘笈大全》 | 同一句已改作「用時憲書審定太陽過宮」 | 定氣 |

以《統宗》康熙五十六至五十八年（1717–19）的算例驗證是妥當的（時憲曆行用之後）； 以《演義》明代算例驗證則須留意此差。

時間基準：UTC+8 牆上時鐘

節氣交接時刻依東經 120 度標準時推算（實測 2024 春分為 11:06:25， 恰為天文值 03:06 UTC 加八小時），故輸入的日期時間亦一律視為 UTC+8 牆上時鐘。

三項未做的校正：

| 項目 | 狀態 | 影響 | |---|---|---| | 時區 | 未校正 | generateChartNow 取本機時鐘，見上 | | 夏令時間 | 未校正 | 臺灣 1945–61、1974–75、1979，中國大陸 1986–91。牆鐘早實際時刻一小時，足以跨越時辰分界 | | 真太陽時／經度 | 未校正 | 東經 120 度以外可差數十分鐘 |

const obj = chartToObject(generateChartByDatetime('2024011510'));
obj.曆法基準.節氣;      // '定氣'
obj.時間基準.時區;      // 'UTC+8'
obj.時間基準.夏令時間;  // '未校正'

陽遁與陰遁

一年分為陽遁與陰遁兩個階段：

• 陽遁：冬至到芒種（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 示例頁面（載入 dist/qimen.standalone.min.js）
├── index.js        # 統一入口，匯出所有公開 API
├── constants.js    # 常數定義
│                   # - JIEQI_JUSHU：節氣局數配置表
│                   # - YUAN_NAMES：三元名稱
│                   # - PALACE：九宮索引
│                   # - FLY_PATH：飛布軌跡
│                   # - 天干地支、九星、八門、八神名稱
│                   # - 六甲旬首與符首對應
│                   # - 地盤配置（陰陽各九局）
├── utils.js        # 通用工具函數
│                   # - 陣列旋轉與飛布序列生成
│                   # - 旬首、符首查詢
│                   # - 空亡方位查詢
│                   # - 天干地支提取
├── calculations.js # 五層運算函數
│                   # - 河圖、洛書基礎
│                   # - 地盤、天盤計算
│                   # - 八門、九星、八神飛布
│                   # - 定局：拆補（calculateJuByChaiBu）
│                   #       符頭（calculateJuByFuTou，超神接氣置閏）
├── qimen.js        # 主控函數
│                   # - generateQimenChart：手動起盤
│                   # - generateChartByDatetime：日期時間起盤（可選定局法）
│                   # - generateChartNow：當前時間起盤
│                   # - chartToObject / chartToJSON：格式轉換
├── patterns.js     # 判斷層（與 qimen.js 並列，非其下游）
│                   # - detectPatterns：格局十一條
│                   # - detectShiGanKeYing：十干克應 81 格（帶斷語）
│                   # - assessVigor：旺相休囚（九星四家並列、八門八節輪轉）
│                   # - 每則判斷帶出處（書／篇／原文），異說並列不代為擇一
├── build.mjs       # 建置腳本（含第三方授權聲明）
├── test.js         # 測試模組（99 個測試，約 1.7 秒）
├── package.json    # 專案配置（ES Module）
├── dist/           # 打包輸出目錄（npm run build 生成）
│   ├── qimen.min.js           # ES Module 格式（~70KB，需外部 lunar-javascript）
│   ├── qimen.standalone.min.js # IIFE 格式（~396KB，已包含 lunar-javascript）
│   ├── THIRD-PARTY-LICENSES.txt # 內嵌之第三方軟體授權
│   └── 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（~70KB，需外部 lunar-javascript）
├── qimen.standalone.min.js # IIFE（~396KB，瀏覽器直接使用）
├── THIRD-PARTY-LICENSES.txt # 內嵌之第三方軟體授權（MIT 條款要求隨副本散布）
├── 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 開發維護。