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