簡介這是一套面向易學(xué)研究者、前端開發(fā)者及傳統(tǒng)文化愛好者的六爻占卜工具開源實(shí)現(xiàn)解決傳統(tǒng)起卦流程繁瑣、解析門檻高、跨端體驗(yàn)不一致等問題。資源為純前端TypeScript工程共23個(gè)文件含10個(gè)tsx核心組件、5個(gè)ts業(yè)務(wù)邏輯與工具類、3個(gè)json配置文件含元數(shù)據(jù)與環(huán)境變量、2個(gè)html入口與資源頁包體僅31KB輕量易部署。已有152人學(xué)習(xí)下載適合希望快速理解六爻排盤原理、定制化擴(kuò)展卦辭解讀或集成至自有應(yīng)用的中初級開發(fā)者。源碼結(jié)構(gòu)清晰分層views層組織功能視圖components封裝卦象渲染如HexagramLines.tsx、搖卦交互Coin.tsx等原子模塊services與utils提供時(shí)間排盤、六親推演、伏神計(jì)算等核心算法預(yù)留接口支持歷史記錄、AI卦解等二次開發(fā)README.md詳述運(yùn)行與拓展方式。1. 項(xiàng)目概述從“玄學(xué)”到“算法”的現(xiàn)代實(shí)踐最近在整理個(gè)人項(xiàng)目倉庫時(shí)翻出了一個(gè)幾年前寫的“六爻起卦工具”的源碼。這個(gè)項(xiàng)目源于一個(gè)非常個(gè)人化的需求我身邊有不少對傳統(tǒng)文化感興趣的朋友他們偶爾會想用六爻來輔助決策或思考但傳統(tǒng)的蓍草或銅錢起卦法步驟繁瑣且隨機(jī)性難以保證對于現(xiàn)代人來說時(shí)間和環(huán)境都不太允許。于是我就琢磨著能不能用代碼來模擬這個(gè)“隨機(jī)”的過程做一個(gè)既尊重傳統(tǒng)邏輯又方便快捷的數(shù)字化工具這個(gè)工具的核心就是用程序來模擬三次投擲硬幣或銅錢的過程根據(jù)正反面的組合生成一個(gè)“爻”重復(fù)六次得到完整的卦象并自動匹配《周易》六十四卦的卦辭、爻辭進(jìn)行解讀。這聽起來有點(diǎn)“跨界”一邊是古老的東方智慧一邊是冰冷的計(jì)算機(jī)代碼。但實(shí)際操作下來你會發(fā)現(xiàn)這本質(zhì)上是一個(gè)隨機(jī)數(shù)生成、狀態(tài)映射和規(guī)則解析的經(jīng)典編程問題。它不涉及任何“超自然”的信仰而是對一套既定規(guī)則系統(tǒng)的數(shù)字化實(shí)現(xiàn)。對于開發(fā)者而言這是一個(gè)絕佳的練手項(xiàng)目可以深入理解狀態(tài)機(jī)、數(shù)據(jù)建模如何優(yōu)雅地存儲和查詢六十四卦的復(fù)雜信息、以及如何設(shè)計(jì)一個(gè)清晰的用戶界面來呈現(xiàn)結(jié)構(gòu)化結(jié)果。對于傳統(tǒng)文化愛好者它則是一個(gè)隨時(shí)可用的“數(shù)字卦筒”消除了起卦過程中的物理限制和心理干擾讓關(guān)注點(diǎn)回歸到卦象本身的思考上。今天我就把這個(gè)項(xiàng)目的完整源碼和設(shè)計(jì)思路分享出來。無論你是想學(xué)習(xí)如何用代碼處理復(fù)雜規(guī)則系統(tǒng)還是單純想擁有一個(gè)屬于自己的起卦工具相信這份“干貨”都能給你帶來啟發(fā)。我們將從核心算法講起一步步拆解數(shù)據(jù)結(jié)構(gòu)的構(gòu)建、前后端的實(shí)現(xiàn)以及那些我踩過坑后才總結(jié)出的注意事項(xiàng)。2. 核心算法與規(guī)則的數(shù)字建模六爻起卦的規(guī)則是整個(gè)項(xiàng)目的基石。用代碼實(shí)現(xiàn)的第一步就是必須把這些流傳千年的規(guī)則毫無歧義地翻譯成計(jì)算機(jī)能理解的邏輯。2.1 爻的生成三變得一爻傳統(tǒng)方法是用50根蓍草經(jīng)過“三變”得出一爻我們常用更簡易的“錢幣法”來模擬設(shè)定硬幣正面有字面為數(shù)字3反面有圖案面為數(shù)字2。一次投擲三枚硬幣其總和只有四種可能6 222 三反老陰記為▅▅ ▅▅ X變爻7 322 一正兩反少陽記為▅▅▅▅▅不變爻8 332 兩正一反少陰記為▅▅ ▅▅不變爻9 333 三正老陽記為▅▅▅▅▅ O變爻在代碼中這就是一個(gè)典型的隨機(jī)數(shù)生成與條件判斷。我們需要一個(gè)函數(shù)模擬一次投擲返回爻的類型和其對應(yīng)的數(shù)值表示。import random def generate_yao(): 模擬三枚硬幣投擲生成一個(gè)爻。 返回: (yao_type, yao_symbol, is_change) # 模擬三枚硬幣隨機(jī)生成3或2 coins [random.choice([2, 3]) for _ in range(3)] total sum(coins) if total 6: return old_yin, ▅▅ ▅▅ X, True # 老陰變爻 elif total 7: return young_yang, ▅▅▅▅▅, False # 少陽不變 elif total 8: return young_yin, ▅▅ ▅▅, False # 少陰不變 elif total 9: return old_yang, ▅▅▅▅▅ O, True # 老陽變爻 else: # 理論上不會發(fā)生但保持健壯性 raise ValueError(fInvalid coin sum: {total})注意這里的隨機(jī)數(shù)生成器random使用的是偽隨機(jī)算法對于此類應(yīng)用完全足夠。如果你追求更不可預(yù)測的隨機(jī)源可以考慮接入系統(tǒng)熵池如os.urandom或讓用戶參與隨機(jī)過程如要求用戶輸入一個(gè)隨機(jī)字符串作為種子。但核心在于算法本身是對物理過程的模擬其“隨機(jī)性”的哲學(xué)意義應(yīng)由使用者自行理解。2.2 卦的構(gòu)成從下到上的堆疊一個(gè)完整的卦由六個(gè)爻組成順序是從下往上初爻、二爻、三爻、四爻、五爻、上爻。在程序中我們用一個(gè)列表來存儲這六個(gè)爻的信息列表的第一個(gè)元素是初爻。def generate_gua(): 生成一個(gè)完整的六爻卦 gua [] for i in range(6): yao_info generate_yao() # 存儲信息位置、類型、符號、是否為變爻 gua.append({ position: i 1, # 位置1為初爻 type: yao_info[0], symbol: yao_info[1], is_changing: yao_info[2] }) return gua2.3 本卦、變卦與動爻核心邏輯解析這是六爻推算中最精妙也最容易出錯(cuò)的部分。本卦最初生成的六個(gè)爻所直接對應(yīng)的卦。動爻變爻在生成過程中標(biāo)記為is_changing為True的爻即老陰或老陽。變卦將本卦中的所有動爻進(jìn)行陰陽轉(zhuǎn)換老陰變少陽老陽變少陰后得到的新卦。例如本卦的初爻是老陽▅▅▅▅▅ O那么在變卦中初爻就變?yōu)樯訇帹|▅ ▅▅。不變爻則保持不變。def get_changing_yao_indices(gua): 獲取卦中所有變爻的位置索引0-based從初爻開始 return [i for i, yao in enumerate(gua) if yao[is_changing]] def apply_change(gua, changing_indices): 根據(jù)變爻索引生成變卦的爻列表 changed_gua [] for i, yao in enumerate(gua): if i in changing_indices: # 陰陽互變 if yao[type] old_yang: # 老陽 - 少陰 new_yao {position: yao[position], type: young_yin, symbol: ▅▅ ▅▅, is_changing: False} elif yao[type] old_yin: # 老陰 - 少陽 new_yao {position: yao[position], type: young_yang, symbol: ▅▅▅▅▅, is_changing: False} else: # 非動爻理論上不會進(jìn)入此分支 new_yao yao.copy() changed_gua.append(new_yao) else: # 不變爻直接復(fù)制 changed_gua.append(yao.copy()) return changed_gua2.4 卦象匹配構(gòu)建六十四卦數(shù)據(jù)庫有了爻的列表我們需要將其映射到具體的六十四卦之一。六爻卦可以看作是兩個(gè)三爻的“經(jīng)卦”上下疊加而成。上卦四、五、上爻和下卦初、二、三爻各對應(yīng)八卦之一。首先定義八卦# 用三位二進(jìn)制表示八卦0為陰-1為陽—從下往上讀。 # 例如乾 (111)坤 (000)震 (001)巽 (110)... BAGUA_MAP { (1, 1, 1): (乾, 天, ?), (0, 0, 0): (坤, 地, ?), (1, 0, 0): (震, 雷, ?), (0, 1, 0): (坎, 水, ?), (1, 1, 0): (艮, 山, ?), (0, 0, 1): (巽, 風(fēng), ?), (1, 0, 1): (離, 火, ?), (0, 1, 1): (兌, 澤, ?), }將爻轉(zhuǎn)換為二進(jìn)制少陽陽爻為1少陰陰爻為0。老陽和老陰在成卦時(shí)按其變化前的狀態(tài)算即老陽為陽1老陰為陰0在變卦時(shí)則按變化后的狀態(tài)算。然后根據(jù)上下卦的組合查詢預(yù)置的六十四卦數(shù)據(jù)庫。這個(gè)數(shù)據(jù)庫需要包含卦序、卦名、拼音、上下卦組合、卦辭、彖辭、大象辭以及每一爻的爻辭和象辭。我選擇用JSON文件來存儲結(jié)構(gòu)清晰且易于維護(hù)。// gua_data.json 片段 { 1: { sequence: 1, name: 乾, pinyin: Qián, upper: 乾, lower: 乾, hexagram: ?, gua_ci: 元亨利貞。, tuan_zhuan: 大哉乾元萬物資始乃統(tǒng)天..., da_xiang: 天行健君子以自強(qiáng)不息。, yao: [ {position: 1, yao_ci: 潛龍勿用。, xiang_ci: 潛龍勿用陽在下也。}, {position: 2, yao_ci: 見龍?jiān)谔锢姶笕恕? xiang_ci: 見龍?jiān)谔锏率┢找?。}, // ... 其余四爻 ] }, 2: { sequence: 2, name: 坤, pinyin: Kūn, upper: 坤, lower: 坤, hexagram: ?, // ... 其他字段 } // ... 其余62卦 }實(shí)操心得構(gòu)建這個(gè)數(shù)據(jù)庫是最耗時(shí)但也是最基礎(chǔ)的一步。務(wù)必核對古籍確保卦辭、爻辭的準(zhǔn)確性。我最初從網(wǎng)絡(luò)爬取的數(shù)據(jù)存在不少錯(cuò)漏和格式問題手動校對了一遍才敢用。此外爻辭的索引一定要與爻位初、二、三、四、五、上嚴(yán)格對應(yīng)這是后續(xù)查詢的關(guān)鍵。3. 系統(tǒng)架構(gòu)與模塊化實(shí)現(xiàn)一個(gè)完整的工具不能只有算法還需要考慮用戶交互和數(shù)據(jù)流轉(zhuǎn)。我采用了前后端分離的簡單架構(gòu)后端提供核心計(jì)算和卦辭查詢API前端負(fù)責(zé)展示和交互。3.1 后端設(shè)計(jì)Python Flask 應(yīng)用后端主要負(fù)責(zé)三件事生成卦象、查詢卦辭、提供API接口。使用Flask是因?yàn)樗p量、快速非常適合這類小型工具。核心文件結(jié)構(gòu)/backend ├── app.py # Flask主應(yīng)用 ├── gua_generator.py # 起卦算法模塊 ├── gua_lookup.py # 卦象查詢模塊 ├── data/ │ └── gua_data.json # 六十四卦數(shù)據(jù)庫 └── requirements.txt # 依賴列表app.py主要代碼片段from flask import Flask, jsonify, request from gua_generator import generate_full_guas # 導(dǎo)入封裝的起卦函數(shù) from gua_lookup import lookup_gua_by_yao, get_gua_detail import json app Flask(__name__) app.route(/api/generate, methods[GET]) def api_generate(): 生成卦象的API端點(diǎn) try: # 調(diào)用核心算法得到本卦、變卦、動爻信息 original_gua, changed_gua, changing_positions generate_full_guas() # 查詢本卦和變卦的詳細(xì)信息 original_gua_detail lookup_gua_by_yao(original_gua) changed_gua_detail lookup_gua_by_yao(changed_gua) # 獲取動爻的爻辭只取本卦中動爻的爻辭 changing_yao_details [] for pos in changing_positions: # pos是1-based的爻位 yao_info original_gua_detail[yao][pos-1] # 獲取對應(yīng)爻辭 changing_yao_details.append({ position: pos, yao_ci: yao_info[yao_ci], xiang_ci: yao_info[xiang_ci] }) response { success: True, data: { original_gua: original_gua_detail, changed_gua: changed_gua_detail, changing_yao: changing_yao_details, changing_positions: changing_positions } } return jsonify(response) except Exception as e: return jsonify({success: False, error: str(e)}), 500 app.route(/api/gua/int:sequence, methods[GET]) def api_get_gua(sequence): 根據(jù)卦序查詢卦的詳細(xì)信息 detail get_gua_detail(sequence) if detail: return jsonify({success: True, data: detail}) else: return jsonify({success: False, error: 卦未找到}), 404 if __name__ __main__: app.run(debugTrue, port5000)gua_generator.py封裝這個(gè)文件整合了第二章節(jié)的所有算法函數(shù)提供一個(gè)干凈的接口generate_full_guas()一次性返回本卦爻列表、變卦爻列表和動爻位置。3.2 前端設(shè)計(jì)Vue.js 單頁應(yīng)用前端的目標(biāo)是提供一個(gè)直觀、美觀的界面展示卦象、爻變、卦辭和爻辭。我選擇了Vue 3因?yàn)樗憫?yīng)式系統(tǒng)能很好地處理卦象狀態(tài)變化。核心組件GuaDisplay.vue負(fù)責(zé)渲染卦象。將六個(gè)爻垂直排列從初爻到上爻并用不同的樣式或顏色高亮顯示動爻如老陽加紅色邊框老陰加藍(lán)色邊框。變卦可以并列顯示或通過切換查看。InfoPanel.vue展示卦的詳細(xì)信息。包括卦名、卦象圖、卦辭、彖傳、大象傳。通過標(biāo)簽頁Tabs切換顯示本卦和變卦的信息。YaoDetail.vue如果存在動爻這個(gè)組件會突出顯示所動之爻的爻辭和小象傳這是解卦時(shí)重點(diǎn)參考的內(nèi)容。ControlPanel.vue包含“起卦”按鈕。點(diǎn)擊后調(diào)用后端/api/generate接口獲取新卦數(shù)據(jù)并更新整個(gè)應(yīng)用狀態(tài)。關(guān)鍵交互邏輯在Vue的setup中import { ref } from vue; import axios from axios; const originalGua ref(null); const changedGua ref(null); const changingYao ref([]); const isLoading ref(false); const generateGua async () { isLoading.value true; try { const response await axios.get(http://localhost:5000/api/generate); if (response.data.success) { const data response.data.data; originalGua.value data.original_gua; changedGua.value data.changed_gua; changingYao.value data.changing_yao; // 更新UI... } } catch (error) { console.error(起卦失敗:, error); // 提示用戶 } finally { isLoading.value false; } };注意事項(xiàng)前端展示爻象時(shí)字符的兼容性很重要。我使用了▅▅▅▅▅和▅▅ ▅▅這樣的Unicode塊字符來模擬陽爻和陰爻并在動爻后加上O和X標(biāo)記。雖然不如真正的卦畫美觀但在絕大多數(shù)終端和瀏覽器中都能正確顯示。如果你想追求更完美的顯示可以考慮使用SVG繪制或者引入專門的易經(jīng)字體。4. 數(shù)據(jù)持久化與高級功能探討基礎(chǔ)功能實(shí)現(xiàn)后可以考慮增加一些提升用戶體驗(yàn)和項(xiàng)目深度的功能。4.1 起卦記錄與復(fù)盤很多使用者希望回顧之前的卦象。我們可以增加簡單的本地存儲功能。前端使用localStorage或IndexedDB存儲每次起卦的結(jié)果時(shí)間戳、卦象數(shù)據(jù)、用戶輸入的簡要問題。數(shù)據(jù)結(jié)構(gòu)const record { id: Date.now(), timestamp: new Date().toISOString(), question: userQuestion, // 用戶輸入的問題 originalGua: originalGua.value, changedGua: changedGua.value, changingYao: changingYao.value }; // 存入 localStorage const history JSON.parse(localStorage.getItem(gua_history) || []); history.unshift(record); // 新的放前面 localStorage.setItem(gua_history, JSON.stringify(history.slice(0, 100))); // 只保留最近100條界面增加一個(gè)“歷史”頁面以列表形式展示記錄點(diǎn)擊可查看詳情。4.2 手動指定動爻與自定義起卦為了滿足學(xué)習(xí)或特定場景的需求可以增加“手動模式”。功能提供一個(gè)交互式的六爻畫板讓用戶可以點(diǎn)擊每個(gè)爻來切換陰陽狀態(tài)少陽/少陰并手動標(biāo)記某個(gè)爻為“動爻”老陽/老陰。實(shí)現(xiàn)這需要修改后端的api/generate接口使其能接收一個(gè)代表六個(gè)爻狀態(tài)的數(shù)組作為POST參數(shù)然后根據(jù)這個(gè)固定狀態(tài)生成卦象和變卦而不是隨機(jī)生成。app.route(/api/generate/custom, methods[POST]) def api_generate_custom(): data request.json custom_yao_states data.get(yao_states) # 例如 [young_yang, old_yin, ...] # 根據(jù)自定義狀態(tài)生成卦...4.3 卦象解讀提示系統(tǒng)謹(jǐn)慎實(shí)現(xiàn)這是一個(gè)更進(jìn)階也更敏感的功能。核心是不提供“算命式”的斷言而是建立一個(gè)關(guān)鍵詞庫或語境提示系統(tǒng)。思路為每一卦、每一爻的辭句提取關(guān)鍵意象如“乾卦”關(guān)聯(lián)“剛健”、“開創(chuàng)”、“領(lǐng)導(dǎo)”“潛龍勿用”關(guān)聯(lián)“等待時(shí)機(jī)”、“積蓄力量”。當(dāng)用戶輸入一個(gè)簡短的問題如“問事業(yè)發(fā)展”時(shí)系統(tǒng)可以高亮顯示卦辭爻辭中與“事業(yè)”、“發(fā)展”、“行動”相關(guān)的關(guān)鍵詞句。實(shí)現(xiàn)在gua_data.json中為每條辭句增加一個(gè)tags字段包含一些中性關(guān)鍵詞。前端提供一個(gè)簡單的輸入框讓用戶描述所問之事。后端進(jìn)行非?；A(chǔ)的文本匹配或使用更簡單的規(guī)則返回匹配到的標(biāo)簽前端據(jù)此進(jìn)行視覺上的強(qiáng)調(diào)。重要警告這個(gè)功能必須嚴(yán)格設(shè)計(jì)只能作為“文本高亮”或“信息歸類”工具絕不能輸出任何結(jié)論性、預(yù)測性的語句。界面應(yīng)明確標(biāo)注“以下內(nèi)容為古籍原文解讀因人因事而異僅供參考與思考。”5. 部署、優(yōu)化與常見問題5.1 項(xiàng)目部署指南想讓別人也能用上你的工具就需要部署。后端部署推薦使用Vercel(Python Runtime) 或Railway。它們對Flask應(yīng)用支持友好有免費(fèi)額度。關(guān)鍵是修改app.py最后一行監(jiān)聽0.0.0.0和PORT環(huán)境變量提供的端口。if __name__ __main__: port int(os.environ.get(PORT, 5000)) app.run(host0.0.0.0, portport)前端部署構(gòu)建生產(chǎn)版本 (npm run build)將生成的dist文件夾內(nèi)的靜態(tài)文件部署到Netlify、Vercel (Static)或GitHub Pages。這些平臺都提供免費(fèi)的自動化部署。連接前后端部署后前端需要知道后端API的地址。在Vue項(xiàng)目中可以通過環(huán)境變量來配置。// .env.production VITE_API_BASE_URLhttps://your-flask-backend.vercel.app然后在代碼中引用axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL })。5.2 性能優(yōu)化與代碼質(zhì)量卦辭數(shù)據(jù)庫加載每次請求都讀取和解析JSON文件是低效的。應(yīng)該在服務(wù)啟動時(shí)就將gua_data.json加載到內(nèi)存中作為一個(gè)全局字典或緩存對象。import json with open(data/gua_data.json, r, encodingutf-8) as f: GUADATA json.load(f) # 后續(xù)查詢都從 GUADATA 這個(gè)字典中獲取前端懶加載如果卦辭內(nèi)容非常長可以考慮在用戶點(diǎn)擊查看詳情時(shí)再動態(tài)加載該卦的完整爻辭而不是一次性全部加載。錯(cuò)誤處理與日志在后端關(guān)鍵函數(shù)中添加try...except并記錄日志便于排查線上問題。5.3 常見問題與排查實(shí)錄在開發(fā)和用戶反饋中我遇到了以下幾個(gè)典型問題生成的卦象總是某幾個(gè)卦排查檢查隨機(jī)數(shù)生成函數(shù)generate_yao。最常見的原因是隨機(jī)數(shù)種子被固定或者硬幣正反面的概率模擬不均等random.choice([2, 3])是等概率的沒問題。確保在每次起卦時(shí)沒有重置隨機(jī)種子。解決使用random.SystemRandom()或在生成前引入時(shí)間戳等變化量作為種子。變卦查詢結(jié)果錯(cuò)誤或?yàn)榭张挪檫@是最復(fù)雜的邏輯錯(cuò)誤。首先打印出本卦和變卦的爻列表確認(rèn)陰陽轉(zhuǎn)換是否正確。其次檢查lookup_gua_by_yao函數(shù)。確保它正確地將爻列表包含老陰老陽轉(zhuǎn)換成了用于查詢的“成卦”二進(jìn)制碼老陰作陰老陽作陽。調(diào)試技巧寫一個(gè)單元測試固定一組爻手動計(jì)算它應(yīng)該對應(yīng)的卦然后看程序輸出是否一致。前端顯示亂碼或卦畫錯(cuò)位排查Unicode字符渲染問題。確保HTML文件指定了UTF-8編碼 (meta charsetUTF-8)。對于卦畫字符有些字體可能不支持可以在CSS中指定一個(gè)更通用的字體族如font-family: SimSun, NSimSun, serif;宋體通常支持較好。部署后API請求失敗CORS錯(cuò)誤現(xiàn)象前端控制臺報(bào)錯(cuò)Access-Control-Allow-Origin。解決在后端Flask應(yīng)用中安裝并啟用CORS支持。from flask_cors import CORS app Flask(__name__) CORS(app) # 允許所有來源生產(chǎn)環(huán)境應(yīng)指定具體前端地址用戶覺得“不靈”或“不準(zhǔn)”定位這不是技術(shù)問題而是產(chǎn)品定位問題。應(yīng)對在工具醒目位置添加說明明確告知“本工具是一個(gè)基于隨機(jī)數(shù)生成算法對傳統(tǒng)六爻起卦方法的程序化模擬其結(jié)果不具備任何神秘學(xué)意義。旨在為傳統(tǒng)文化愛好者提供一種便捷的參考和研習(xí)方式請理性看待切勿沉迷。” 將工具的定位從“占卜”轉(zhuǎn)向“文化學(xué)習(xí)與模擬”可以避免很多不必要的爭議。這個(gè)項(xiàng)目從構(gòu)思到實(shí)現(xiàn)再到不斷打磨讓我深刻體會到將一套復(fù)雜的傳統(tǒng)規(guī)則系統(tǒng)進(jìn)行數(shù)字化封裝最大的挑戰(zhàn)不是技術(shù)而是對原始規(guī)則的精確理解和嚴(yán)謹(jǐn)翻譯。每一行代碼背后都需要對古籍原文的反復(fù)揣摩。最終產(chǎn)出的不僅是一個(gè)工具更是一個(gè)結(jié)構(gòu)化的、可交互的“周易”數(shù)據(jù)模型。無論你對它的態(tài)度是文化研究、編程練習(xí)還是單純的興趣使然這個(gè)過程本身就是一種充滿樂趣的探索。本文還有配套的精品資源點(diǎn)擊獲取