# Yingqi 六爻應期規則與證據排序

## Abstract

Yingqi 是 Quizzman I-Ching 的六爻應期引擎。引擎以卦象、用神及曆法情境產生目標地支，再連同規則證據進行排序。本文說明演算法 1.1.0、規則集 `zengshan_core_v1`、18 個規則識別碼、飛伏神處理、證據合分及十二地支循環。六組示例、144 組地支距離與 5,760 個排序案例提供可重現的數值模型。輸出分數表示規則排序權重，並非事件發生機率。

## 1 範圍

實作位於 `libiching/yingqi/` [@REF-YINGQI-SOURCE]。Yingqi 在六爻確定後計算應期。[QP-SYS-002](https://paper.quizzman.com/papers/QP-SYS-002/zht/) 說明整體架構，[QP-SYS-003](https://paper.quizzman.com/papers/QP-SYS-003/zht/) 說明起卦。應期引擎讀取卦象及其衍生狀態。

## 2 背景文獻

規則集參照《增刪卜易》的各門類應期總注與飛伏神章 [@REF-YINGQI-ZENGSHAN]。數值權重、同分處理及資料介面是 Quizzman 的軟體約定。古籍提供傳統規則的脈絡，並未定義這些數值常數。

## 3 術語

應期指依卦象條件推得的時點或時間範圍。用神是所選爻位或六親。所需六親不現於本卦時，從本宮首卦尋找伏神；同位置的顯爻為飛神。`trigger` 是指向某地支的一筆規則證據；`candidate` 將同支證據合併後取得排名。

## 4 記號

地支以 1..12 表示子、丑、寅、卯、辰、巳、午、未、申、酉、戌、亥；爻位從下至上為 1..6。a 為基準支、b 為目標支、G_b 為其證據集合、s_i 為單筆權重、d(a,b) 為循環位移、S_b 為合分。

## 5 時間約定

`yingqi_predict_from_solar_datetime` 從 calendar SDK 取得日干、日支及月支。無效日期不產生候選，文件輸出標示 `unavailable`。直接傳入干支的介面檢查日干 1..10、日支 1..12。曆法、時區及換日政策由提供情境的曆法層負責。

Horizon 支援 `hour`、`day`、`month`、`year`，其他值歸為 `day`。top-k 不為正數時預設為 3；無效基準支改用日支。目標支等於基準支時，取下一輪的第 12 步，不取位移零。

## 6 計算結構

流程為選用神、推導爻位事實、產生 trigger、按目標支合併、排序及輸出 `result_document.timing`。規則層計算條件與數值，呈現層將結構化結果寫成文字。因此顯示的時點能回查到爻位與貢獻規則。

## 7 來源與材料

來源清單記錄 15 個 Yingqi 檔案的 SHA-256、演算法 1.1.0 與規則集 `zengshan_core_v1` [@REF-YINGQI-SOURCE]。`rules.json` 列出 18 個規則識別碼及優先序。向量僅使用合成 trigger。Python 驗證程式只需標準函式庫，並固定隨機種子 [@REF-YINGQI-VERIFY]。

## 8 用神與飛伏神

目標六親為 1..5 時，先選相符的動爻。程式從初爻掃至上爻並覆寫動爻選擇，因此多個動爻符合時取位置最高者。沒有相符動爻時，從下至上取第一個相符爻。六親不上卦時，改從本宮首卦尋伏神，並保留同位置飛神之支。

仍未選到爻時，獨發情況取提供的主動爻位置；其餘取世爻。衍生資料包含地支、五行、動靜、變支、同五行數、獨發或獨靜位置，以及飛伏神的生剋關係。問題分類及關鍵詞函式可協助選六親；核心也接受明確的目標六親。

伏神評估考慮時令、日月生助、飛神與動爻。只有評估為有用，才發出 `R_HIDDEN_SPIRIT_VALUE` 與 `R_HIDDEN_SPIRIT_CLASH_FLY`。飛伏神因此直接參與計算與候選生成。

## 9 形式模型

相沖地支為：

$$c(b)=1+((b+5)\bmod12). \tag{1}$$

嚴格取未來一輪的位移為：

$$d(a,b)=1+((b-a-1)\bmod12),\quad 1\le d\le12. \tag{2}$$

對非空 G_b 及規則集中非負的權重：

$$S_b=\max_{i\in G_b}s_i+3(|G_b|-1). \tag{3}$$

同支每增加一筆 trigger 加三分。計數依據是紀錄筆數，而非不同規則識別碼數；重複輸入會增加分數。規則程式以固定順序發出紀錄，候選保留全部相關證據。

## 10 條件生成與排序

規則族涵蓋旬空、月破填實與逢合、沖開墓庫、合待沖開、進退神、衰弱生扶、值支、動合靜沖、太旺、依大象處理受剋、獨發獨靜及飛伏神。一條規則可產生多個目標支。例如旬空以原支 55 分、沖支 48 分產生候選；一般值支為 52 分、動合 47 分、靜沖 45 分。完整清單見 [rules.json](https://paper.quizzman.com/papers/QP-YINGQI-001/artifacts/rules.json)。

同支主規則取單筆分數最高者，同分則取優先序較小者；分數及優先序均相同時保留較早紀錄。各支依下列鍵升序排列：

$$K_b=(-S_b,p_b,d(a,b),b). \tag{4}$$

先看總分，再看規則優先序、較近時點及較小支序。每支只選一次，故候選最多十二個；提高 top-k 不會產生虛構地支。

## 11 實作介面

候選包含 `rank`、`target_branch`、`relativeFrom`、`relativeTo`、`unit`、`score`、`primary_rule` 及 `evidence`。證據包含 `ruleId`、`line`、`weight`；文件保存 `algorithm_version` 及 `ruleset`。目前 `evidence.weight` 為 1；式 (3) 的權重取自 `trigger.score`。

候選 `strength` 的分界為 40、50；整體 timing 的 `confidence` 依首名分數，以 48、54 為分界。因此 52 分的 strength 為 high，confidence 為 medium，兩者皆為 `RULE_SCORE` 標籤。

式 (2) 是所選 horizon 的地支循環位移。時支是地支時計的相位；月支、年支亦需曆法解析。排序模組的相對欄位本身不構成帶時區的民用時間戳。

## 12 模型驗證

於 artifacts 執行 `python3 verify.py` 可重建向量及紀錄 [@REF-YINGQI-VERIFY]。檢查涵蓋全部 144 組基準支與目標支、12 個相沖與六合對合性輸入、六組手算向量、5,760 個排序對照案例及八個標籤邊界案例。排序對照採另一套批次分組與鍵值排序。此為有限域數學模型驗證，並非 Vir 原生執行紀錄。

## 13 結果與示例

YINGQI-V001 以子為基準。值子得 52 分、位移 12；午得 45 分、位移 6。子仍先列，因分數優先於遠近。

YINGQI-V002 以辰為基準。寅的兩筆權重 55、52 合為 58；申的 48、45 合為 51。排序為寅、申，位移分別為 10、4。YINGQI-V003 在兩支皆 50 分時顯示規則優先序先於遠近。第 12 節列出的檢查全部通過；JSON 向量保留輸入及預期輸出。

## 14 討論

此結構區分卦象事實、規則條件、分數與顯示文字，能指出選中某支的原因、證據匯合情況及同分決勝規則。n 筆 trigger 選 k 支的目前重複選取演算法成本為 O(k n²)；k≤12，使單一卦象的規則計算有明確界限。

## 15 解讀界限

證據加分是排序政策，尚未校準為事件命中率。第 12 節驗證循環位移與排序，不涵蓋所有六親推導、飛伏神路徑或曆法轉換。將目標支解析成民用日期時間，需要呼叫端一致的曆法情境與 horizon 約定。

## 16 結論

Yingqi 是 Quizzman I-Ching 中獨立的應期引擎，具用神推導、飛伏神、18 個規則識別碼、證據合分、確定的同分處理及可追溯輸出。本文公開公式、來源校驗碼及重現材料，讓讀者直接核對所述計算。

## Bibliography

- [@REF-YINGQI-SOURCE] Yingqi 來源清單與演算法版本。
- [@REF-YINGQI-ZENGSHAN] 《增刪卜易》應期與飛伏神章。
- [@REF-YINGQI-VERIFY] 合成向量與應期模型驗證。
