八字 × 易經 × 奇門遁甲 — 每日時辰推演工具
https://donma.github.io/PeekFate/
速窺運勢是一個純前端 PWA 命理規則引擎工具。所有推算在瀏覽器端完成，不依賴後端服務，不上傳使用者資料。
系統整合三套傳統命術：
- 八字：四柱推算、十神、地支關係、藏干、納音、大運、神煞、用神喜忌
- 易經：六十四卦象、變卦、五行個人化
- 奇門遁甲：時家奇門盤、八門、九星、八神
使用者輸入西元生日與出生時間，系統推算今日與明日每個時辰的吉凶，並提供 14 天每日概述。
- 今日 + 明日 24 時辰獨立計分，附白話解釋
- 接下來 14 天每日運勢概述與趨勢圖
- 事件類型專用計分（就職、金牌、結婚、逝世、封殺等 22 種子類型）
- 河圖幸運數字（依喜用神五行推算）
- 性別選填，自動推算大運
- 節氣資料涵蓋 1900–2100 年
- 可離線使用，可安裝至手機桌面
- 所有計分來源可追溯
/
├── index.html # 首頁
├── manifest.json # PWA 清單
├── service-worker.js # 離線快取
├── favicon.png / favicon.ico
├── verification-report.html # 歷史事件回測報告
│
├── css/
│ └── app.css
│
├── js/
│ ├── main.js # 入口
│ ├── app-optimized.js # 主程式
│ ├── performance-monitor.js
│ ├── pwa-install.js
│ │
│ └── engines/
│ ├── date-engine.js # 日期引擎
│ ├── ganzhi-engine.js # 干支引擎
│ ├── bazi-engine.js # 八字引擎
│ ├── iching-engine.js # 易經引擎
│ ├── qimen-engine.js # 奇門遁甲引擎
│ ├── scoring-engine.js # 計分引擎
│ └── interpretation-engine.js
│
├── data/
│ ├── core/ # 節氣等核心資料
│ ├── bazi/ # 八字規則
│ ├── iching/ # 易經規則
│ ├── qimen/ # 奇門遁甲規則
│ ├── interpretation/ # 解釋模板
│ └── celebrities/ # 回測名人與事件資料
│
├── tests/
│ ├── bazi-tests.json
│ ├── iching-tests.json
│ ├── qimen-tests.json
│ └── integration-tests.json
│
├── docs/
│ ├── verification-method.md # 驗證方法說明
│ ├── trick.md # 優化方法論
│ └── accuracy-optimization-guide.md
│
├── test-validation.html # 瀏覽器端測試頁面
├── test-local.js # 本地測試腳本
│
├── scripts/
│ ├── generate-solar-terms.py # 節氣資料生成腳本
│ └── run-verification.js # Node.js 歷史回測腳本
│
├── icons/ # PWA 圖標
└── CHANGELOG.md
使用任何 HTTP 伺服器開啟 index.html：
# Python
python -m http.server 8000
# Node.js
npx serve .
# VS Code Live Server
# 右鍵 index.html → Open with Live ServerAndroid Chrome：開啟網站 → 點擊「安裝到桌面」
iOS Safari：開啟網站 → 分享按鈕 →「加入主畫面」
- 上傳至 GitHub
- Settings → Pages → 選擇 main 分支
- 訪問
https://<username>.github.io/<repo>/
本專案使用 JSON 測試資料進行規則檢查。
| 檔案 | 內容 |
|---|---|
tests/bazi-tests.json |
八字引擎測試案例 |
tests/iching-tests.json |
易經引擎測試案例 |
tests/qimen-tests.json |
奇門遁甲引擎測試案例 |
tests/integration-tests.json |
整合測試案例 |
- 瀏覽器端：開啟
test-validation.html，自動載入引擎並執行測試 - 本地腳本：執行
test-local.js（需 Node.js 環境） - 手動檢查：確認各命術模組能正確載入 JSON 資料並產出結果
本專案包含一份歷史事件回測報告（verification-report.html），用於評估計分引擎對已知歷史事件的分類能力。
- 295 位華人名人（政治、演藝、體育、企業、科學、文學等）
- 281 筆已知事件（就職、金牌、結婚、逝世、入獄、醜聞、封殺等）
- 回測通過率：94.7%（其中 50 筆為獨立盲測資料，詳見下方版本更新說明）
- 正向事件（就職、金牌等）：分數 ≥ 45
- 負向事件（逝世、逮捕等）：分數 ≤ 52
- 中性事件（退休等）：分數 45–60
本報告屬於歷史事件回測，用於檢查規則引擎是否能對已知事件產生合理分數區間。結果不可解讀為未來事件預測準確率，也不代表科學驗證結論。
詳細方法說明見 docs/verification-method.md。
| 項目 | 版本 |
|---|---|
| App Version | v126 |
| Rule Version | v126 |
| Verification Report | v126 |
| Data Version | 2026-07-06 |
版本紀錄見 CHANGELOG.md。
- 不登入、不上傳生日、不保存個資
- 所有推算在瀏覽器端完成
- 歷史事件資料僅用於回測，不涉及使用者輸入
- 可離線使用，無需網路連線
- 本專案使用本地 JSON 資料，不會上傳任何使用者資訊
- 節氣資料使用天文演算覆蓋 1900–2100 年，偶有 ±1 日誤差（影響月柱邊界日出生者）（v123 已修正節氣名稱錯字問題）
- 子時跨日規則固定為 23:00 換日
- 奇門遁甲流派繁多，本系統採固定時家奇門規則
- 性別為選填，未填則不推算大運
- 歷史事件回測資料用於檢查規則引擎行為，不代表未來預測能力
- 目前尚未建立常態性 holdout dataset；v126 曾執行過一次盲測（50 筆全新華人事件，調參時未接觸），通過率 94%，證實與已調參資料集的 95% 差距不大，但該 50 筆已併入主資料集，之後若要重新檢查是否過擬合，需另建新的盲測資料
- 部分事件分類受人工規則影響，可能存在標註偏差
- 屬民俗文化參考，不作為醫療、法律、投資、婚姻或人生重大決策依據
本次稽核並修正四個影響命理計算精度的 bug：
| # | 修正項目 | 影響 |
|---|---|---|
| 1 | 節氣資料錯字：solar-terms.json 中「驚蟄」→「驚蛇」、「芒種」→「芒种」 |
全年約 1/6 日期月柱算錯，大運起運誤差可達 4 個月 |
| 2 | 納音表錯字：庚戌/辛亥「釵環金」→「釵釧金」、甲午/乙未「砂石金」→「砂中金」 | 純顯示文字錯誤 |
| 3 | 奇門節氣判斷順序錯誤：qimen-engine.js 陣列排序錯誤，全年 350+ 天被誤判為「大寒」 |
奇門盤（值符/值使/九星八門）全年幾乎恆為空值或錯誤盤面 |
| 4 | 奇門旬首定位漏步驟：calculateHourBoard() 直接用日干+時支查六十甲子，漏掉「五鼠遁推時干」步驟 |
大量時辰查出 hourIndex = -1，奇門盤直接回傳 null |
修正後驗證結果：
test-local.js全引擎煙霧測試：25% → 100% 通過（0 個錯誤）- 231 筆歷史事件回測：218/231 (94%) → 219/231 (95%)，無退步
- 新增
scripts/run-verification.js供未來每次引擎修改後快速重跑回歸測試
修正「年干合化」「月干合化」顯示為英文（如「年干合化：fire」）的問題。bazi-engine.js 內部以英文（wood/fire/earth/metal/water）作為五行資料的內部 key，這個慣例在其他地方（用神忌神、日主標籤、雷達圖、健康建議等）都有正確透過 _elementToChinese() 轉換成中文再顯示，唯獨「年干合化/月干合化」這兩行漏掉了轉換步驟，直接把英文字串塞進中文模板。已修正，並同步補上分享簡報卡片原本缺漏的這兩個欄位。
補充「個人基本盤」顯示區塊的神煞、特殊日柱與格局，純顯示層擴充，不影響 231 筆歷史事件回測的計分邏輯：
新增特殊日柱
- 魁罡日（庚辰、壬辰、戊戌、庚戌）
- 日德日（甲寅、丙辰、戊辰、庚辰、壬戌）
新增神煞
- 羊刃（古典陽干版本）
- 國印貴人
修正既有邏輯
- 「陰差陽錯」原本只檢查日支是否為子午卯酉，不是真正的干支組合規則；已修正為傳統十二日柱清單
新增格局
- 建祿格、羊刃格（填補月支本氣為比肩/劫財時原本判定為「無格」的空缺）
- 傷官配印、傷官生財、食神制殺、殺印相生、官印相生、財官印全（作為既有格局之上的「十神組合特徵」補充標記，非獨立格局，最多顯示 2 個避免洗版）
新增解釋文字
- 所有神煞、格局、組合特徵現在都附有解釋文字，一律採用「傳統上常解讀為……」「可能表現為……」「仍需配合……」等有慢語氣，不使用「一定」「必然」等絕對斷語
計分影響：新增神煞比照既有 23 個神煞（每個 ±2 分），計入既有的每日/每時辰即時計分；新增格局與十神組合特徵維持 0 分，不影響即時計分或歷史回測（scoring-engine.js 本就不使用神煞/格局資料，231 筆回測仍為 219/231 (95%) 不變）。
為了檢查 95% 通過率是否只是「對同一批資料反覆調參」的假象，執行了一次真正的盲測：
第一次嘗試（有瑕疵，僅供記錄）：找了 50 位西方名人（未使用中國標準時區換算）做盲測，結果只有 78%（正向 100%、負向 69%）。後來發現這是方法論缺陷——bazi-engine.js 沒有時區轉換，而系統原本 231 筆資料全部是中國/台灣/香港人物（隱含 UTC+8 假設），西方名人的出生時間套進去會系統性算錯日柱甚至月柱，準確率下降主要是時區問題，不是十神規則真的過擬合。
修正後重測：改用 50 位華人歷史/政治/演藝/體育人物（與原資料集同時區假設），逐一以維基百科查證生日與事件日期（過程中修正了 18 處原本記錯的生日/死亡日期，主要集中在演藝圈人物）。真正盲測結果：47/50 (94%)，正向 8/8 (100%)、負向 39/42 (93%)——與已調參的 231 筆資料集（95%）相差僅 1 個百分點，證實核心十神計分規則對全新華人資料有一定程度的泛化能力，不是單純記住訓練資料。
這 50 筆盲測資料已併入主資料集（231→281 筆事件，245→295 位名人），合併後回測通過率 266/281 (94.7%)。過程中也發現兩個分類規則覆蓋不全的漏洞：「墜機身亡」「遭擊斃」等死亡描述方式未被 classifyEvent() 的負向事件正則捕捉，會落到偏正向的 default profile 計分，導致分數偏高——這是具體、待修的已知問題。
MIT License
開發：當麻實驗室