ZhouYiLab - 周易实验室

项目简介

核心特性

完全模块化设计

现代构建系统

严格的代码规范

构建要求

必需工具

第三方依赖

快速开始

1 克隆项目

# 克隆项目(包含子模块)
git clone --recursive https://github.com/banderzhm/ZhouYiLab.git
cd ZhouYiLab

git submodule update --init --recursive

2 构建项目

Windows (使用 Visual Studio)

cmake -B build -G "Visual Studio 17 2022"
cmake --build build --config Release

Linux / macOS

# 使用 Ninja 构建(推荐,速度更快)
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
# 或使用多核编译
cmake --build build -j$(nproc)

3 运行示例

# 基本运行
./build/bin/ZhouYiLab
# 运行完整的 C++23 modules 演示
./build/bin/ZhouYiLab --demo
# 运行八字示例
./build/bin/example_ba_zi
# 运行大六壬示例
./build/bin/example_da_liu_ren
# 运行六爻示例
./build/bin/example_liu_yao
# 运行奇门遁甲示例
./build/bin/example_qi_men
# 运行紫微斗数示例
./build/bin/example_zi_wei

项目结构

ZhouYiLab/
 3rdparty/ # 第三方库(Git 子模块)
 fmt/ # 格式化库(支持 import fmt;)
 magic_enum/ # 枚举反射库(支持 import magic_enum;)
 nlohmann_json/ # JSON 库(支持 import nlohmann.json;)
 tyme4cpp/ # 农历日历库(通过模块包装)
 cmake/ # CMake 工具链配置
 clang.toolchain.cmake # Clang 工具链
 gcc.toolchain.cmake # GCC 工具链
 vs.toolchain.cmake # MSVC 工具链
 src/ # 源代码(纯模块化)
 common/ # 通用模块
 tian_gan/ # 天干地支系统
 ganzhi.cppm # 完整干支系统(核心)
 ba_zi_base.cppm # 八字基础定义
 wu_xing_utils.cppm # 五行工具
 tyme/ # 农历历法封装
 tyme.cpp # tyme4cpp 封装实现
 tyme_def.cppm # tyme 模块定义
 utils/ # 通用工具
 ba_zi/ # 八字模块 
 ba_zi.cppm # 八字核心算法
 ba_zi_controller.cppm # 八字控制器接口
 ba_zi_controller.cpp # 八字控制器实现
 da_liu_ren/ # 大六壬模块
 liu_yao/ # 六爻模块
 qi_men/ # 奇门遁甲模块
 zi_wei/ # 紫微斗数模块
 main.cpp # 唯一允许的 .cpp 文件
 examples/ # 示例程序 
 example_ba_zi.cpp # 八字系统示例
 example_da_liu_ren.cpp # 大六壬示例
 example_liu_yao.cpp # 六爻示例
 example_qi_men.cpp # 奇门遁甲示例
 example_zi_wei.cpp # 紫微斗数示例
 tests/ # 单元测试
 docs/ # 文档
 CMakeLists.txt # CMake 主配置
 .gitmodules # Git 子模块配置
 README.md # 本文档

模块依赖关系

main.cpp
 import fmt; (第三方库:格式化输出)
 import magic_enum; (第三方库:枚举反射)
 import nlohmann.json; (第三方库:JSON)
 import ZhouYi.GanZhi; (自定义模块:完整干支系统 核心)
 import ZhouYi.LunarCalendar; (自定义模块:农历日历)
 import std; (标准库,最后导入!)
ZhouYi.GanZhi 核心干支模块
 import magic_enum; (反射支持)
 import std; (标准库,最后导入)
 功能:
 - 天干地支枚举定义
 - 五行阴阳属性
 - 生克制化关系
 - 冲合刑害判断
 - 六十甲子系统
 - 纳音五行
 - 贵人寄宫等
ZhouYi.BaZiBase (八字基础模块)
 import ZhouYi.GanZhi; (依赖干支系统)
 import std;
 功能:
 - 八字四柱定义(年月日时)
 - 十神关系计算
 - 神煞系统
 - 大运流年计算
ZhouYi.BaZi (八字核心算法)
 import ZhouYi.BaZiBase; (基础定义)
 import ZhouYi.GanZhi; (干支系统)
 import ZhouYi.Tyme; (农历历法)
 import std;
 功能:
 - 公历/农历排盘
 - 童限计算
 - 大运起运
 - 流年流月推算
ZhouYi.BaZiController (八字控制器)
 import ZhouYi.BaZi; (核心算法)
 import fmt; (格式化输出)
 import std;
 功能:
 - 排盘接口封装
 - 结果格式化显示
 - 交互式排盘
ZhouYi.DaLiuRen (大六壬模块)
 import ZhouYi.GanZhi; (干支系统)
 import ZhouYi.Tyme; (农历历法)
 import nlohmann.json; (JSON序列化)
 import std;
 功能:
 - 天地盘系统(月将、贵人、十二神将)
 - 四课计算(干上神、支上神、阴神、阳神)
 - 三传取法(贼克、比用、涉害、遥克等)
 - 神煞系统
 - 卦体判断
 - 课式分类
ZhouYi.QiMen (奇门遁甲模块)
 import ZhouYi.GanZhi; (干支系统)
 import ZhouYi.Tyme; (农历历法)
 import std;
 功能:
 - 阴阳遁算法(阳遁九局、阴遁九局)
 - 节气自动识别
 - 九宫排盘(天盘、地盘、人盘)
 - 八门配置(休、生、伤、杜、景、死、惊、开)
 - 九星配置(天蓬、天芮、天冲、天辅、天禽、天心、天柱、天任、天英)
 - 八神配置(值符、腾蛇、太阴、六合、白虎、玄武、九地、九天)
 - 吉凶分析
ZhouYi.LiuYao (六爻模块)
 import ZhouYi.BaZiBase; (八字基础)
 import ZhouYi.WuXingUtils; (五行工具)
 import ZhouYi.DiZhiRelations; (地支关系)
 import fmt; (格式化输出)
 import nlohmann.json; (JSON序列化)
 import std;
 功能:
 - 纳甲装卦(本卦、变卦、伏神)
 - 六亲关系计算
 - 六神配置(青龙、朱雀、勾陈、螣蛇、白虎、玄武)
 - 世应标记
 - 旺衰判定
 - 神煞系统
ZhouYi.ZiWei (紫微斗数模块)
 import ZhouYi.GanZhi; (干支系统)
 import ZhouYi.Tyme; (农历历法)
 import std;
 功能:
 - 命盘排盘
 - 十二宫位
 - 主星安星
 - 辅星配置
 - 四化计算

使用示例

八字排盘

import ZhouYi.BaZiController;
import ZhouYi.GanZhi;
import ZhouYi.ZhMapper;
import std;
using namespace ZhouYi::BaZiController;
using namespace ZhouYi::GanZhi;
using namespace ZhouYi::Mapper;
// 方式1:公历排盘
auto result = pai_pan_solar(2000, 7, 15, 16, 30, true); // 最后参数:true=男,false=女
// 方式2:农历排盘
auto result_lunar = pai_pan_lunar(2000, 6, 15, 16, 30, true);
// 访问八字信息
const auto& ba_zi = result.ba_zi;
std::println("年柱:{}", ba_zi.year.to_string()); // 庚辰
std::println("月柱:{}", ba_zi.month.to_string()); // 癸未
std::println("日柱:{}", ba_zi.day.to_string()); // 甲申
std::println("时柱:{}", ba_zi.hour.to_string()); // 壬申
// 查看十神关系
auto shi_shen_year = get_shi_shen(ba_zi.day.gan, ba_zi.year.gan);
std::println("年干对日干:{}", to_zh(shi_shen_year)); // 偏财
auto shi_shen_month = get_shi_shen(ba_zi.day.gan, ba_zi.month.gan);
std::println("月干对日干:{}", to_zh(shi_shen_month)); // 伤官
// 查看童限信息
std::println("童限:{}", result.child_limit.to_string());
std::println("起运岁数:{}", result.start_age);
std::println("起运方向:{}", result.is_shun_pai ? "顺排" : "逆排");
// 查看大运
for (size_t i = 0; i < 5 && i < result.da_yun_list.size(); ++i) {
 const auto& da_yun = result.da_yun_list[i];
 std::println("大运{}: {} ({}岁-{}岁)", 
 i + 1, 
 da_yun.gan_zhi.to_string(),
 da_yun.start_age,
 da_yun.end_age);
}
// 查看流年
auto liu_nian_2025 = get_liu_nian(result, 2025);
std::println("2025年流年:{}", liu_nian_2025.gan_zhi.to_string());
// 查看流月
auto liu_yue_list = get_liu_yue_list(result, 2025);
for (const auto& liu_yue : liu_yue_list) {
 std::println("{}月:{}", liu_yue.month, liu_yue.gan_zhi.to_string());
}
// 格式化显示完整结果
display_result(result);
// 显示详细的童限和大运信息
display_child_limit_detail(result);
display_da_yun(result, 10); // 显示前10个大运
// 显示流年信息
display_liu_nian(result, 2020, 10); // 从2020年开始显示10年
// 显示流月信息
display_liu_yue(result, 2025); // 显示2025年的12个月

大六壬排盘

import ZhouYi.DaLiuRen;
import ZhouYi.DaLiuRen.Controller;
import std;
using namespace ZhouYi::DaLiuRen;
// 方式1:使用排盘引擎(非交互式)
auto result = DaLiuRenEngine::pai_pan(2024, 10, 13, 14); // 公历
// 方式2:从农历排盘
auto result_lunar = DaLiuRenEngine::pai_pan_lunar(2024, 9, 11, 7);
// 方式3:交互式排盘(控制台输入)
Controller::DaLiuRenController::interactive_pai_pan();
// 访问排盘结果
std::println("月将: {}", result.yue_jiang);
std::println("贵人: {}", result.gui_ren);
// 获取四课信息
const auto& si_ke = result.si_ke;
std::println("第一课: {}", si_ke.first.to_string());
std::println("第二课: {}", si_ke.second.to_string());
std::println("第三课: {}", si_ke.third.to_string());
std::println("第四课: {}", si_ke.fourth.to_string());
// 获取三传信息
const auto& san_chuan = result.san_chuan;
std::println("初传: {}", san_chuan.get_chu_chuan());
std::println("中传: {}", san_chuan.get_zhong_chuan());
std::println("末传: {}", san_chuan.get_mo_chuan());
std::println("课式: {}", san_chuan.get_ke_shi());
// 获取天地盘信息
const auto& tian_di_pan = result.tian_di_pan;
auto tian_pan = tian_di_pan.get_tian_pan();
auto di_pan = tian_di_pan.get_di_pan();
// 显示格式化结果
Controller::DaLiuRenController::display_result_detailed(result);
// 导出为 JSON
nlohmann::json json_result = result.to_json();
std::println("{}", json_result.dump(2));

六爻排盘

import ZhouYi.LiuYaoController;
import ZhouYi.BaZiBase;
import std;
using namespace ZhouYi::LiuYaoController;
using namespace ZhouYi::BaZiBase;
// 创建八字(用于计算旺衰、神煞)
auto bazi = BaZi::from_solar(2024, 10, 13, 14, 30);
// 方式1:直接使用主卦代码排盘
// 主卦代码:"010101"(6位二进制,'0'=阴爻,'1'=阳爻,从下到上)
// 动爻:第3爻和第5爻动
auto result = calculate_liu_yao("010101", bazi, {3, 5});
// 方式2:从爻辞生成主卦代码
std::vector<int> yao_ci = {7, 8, 6, 9, 7, 8}; // 从下到上
// 6=老阴(动), 7=少阳, 8=少阴, 9=老阳(动)
std::vector<int> changing_lines;
auto code = yao_ci_to_hexagram_code(yao_ci, changing_lines);
auto result2 = calculate_liu_yao(code, bazi, changing_lines);
// 方式3:从数字卦生成(金钱卦、梅花易数等)
std::vector<int> numbers = {3, 2, 3, 1, 2, 3}; // 从下到上
auto code3 = numbers_to_hexagram_code(numbers, true); // true=奇数为阳爻
auto result3 = calculate_liu_yao(code3, bazi);
// 访问排盘结果
std::println("卦象信息:");
for (const auto& yao : result.yao_list) {
 std::println("第{}爻:", yao.position);
 std::println(" 本卦: {} {} {}", 
 yao.mainRelative, // 六亲
 yao.mainPillar.to_string(), // 纳甲干支
 yao.mainElement); // 五行
 
 if (yao.isChanging) {
 std::println(" 变爻: {} {} {}", 
 yao.changedRelative,
 yao.changedPillar.to_string(),
 yao.changedElement);
 }
 
 std::println(" 六神: {}", yao.spirit);
 std::println(" 旺衰: {}", yao.wangShuai);
 std::println(" 世应: {}", yao.shiYingMark);
}
// 获取卦象基本信息(不进行完整排盘)
auto hexagram_info = get_hexagram_info("010101");
std::println("卦名: {}", hexagram_info.name);
std::println("卦义: {}", hexagram_info.meaning);
std::println("五行: {}", hexagram_info.fiveElement);
std::println("世爻: {}, 应爻: {}", 
 hexagram_info.shiYaoPosition, 
 hexagram_info.yingYaoPosition);
// 批量排盘
std::vector<std::tuple<std::string, BaZi, std::vector<int>>> batch_requests = {
 {"010101", bazi, {3, 5}},
 {"111000", bazi, {1}},
 {"000111", bazi, {}}
};
auto batch_results = batch_calculate_liu_yao(batch_requests);
// 导出为 JSON
std::println("{}", result.json_data.dump(2));

农历日历功能

import ZhouYi.LunarCalendar;
import std;
// 从公历创建
auto solar = ZhouYi::Lunar::SolarDate::from_ymd(1986, 5, 29);
auto lunar = solar.to_lunar();
// 获取农历信息
std::println("农历: {}", lunar.to_string()); // 农历甲寅年四月廿一
std::println("年干支: {}", lunar.get_year_gan_zhi()); // 丙寅
std::println("生肖: {}", lunar.get_zodiac()); // 虎
// 从农历创建
auto lunar2 = ZhouYi::Lunar::LunarDate::from_lunar(2025, 1, 1);
auto [y, m, d] = lunar2.to_solar(); // 转换为公历
// 二十四节气
auto terms = ZhouYi::Lunar::SolarTerm::get_terms_of_year(2025);
for (const auto& [name, date] : terms) {
 std::println("{}: {}", name, date);
}

完整干支系统

import ZhouYi.GanZhi;
using namespace ZhouYi::GanZhi;
// 定义天干地支
auto jia = TianGan::Jia;
auto zi = DiZhi::Zi;
// 获取中文名称
auto name = Mapper::to_zh(jia); // "甲"
// 获取五行属性
auto wu_xing = get_wu_xing(jia); // WuXing::Mu (木)
auto yin_yang = get_yin_yang(jia); // YinYang::Yang (阳)
// 判断地支关系
bool chong = is_chong(DiZhi::Zi, DiZhi::Wu); // 子午相冲
bool he = is_he(DiZhi::Zi, DiZhi::Chou); // 子丑相合
bool xing = is_xing(DiZhi::Zi, DiZhi::Mao); // 子卯相刑
// 地支三合
auto [is_san_he, he_wx] = is_san_he(
 DiZhi::Shen, DiZhi::Zi, DiZhi::Chen
); // 申子辰合水局
// 五行生克
bool sheng = wu_xing_sheng(WuXing::Mu, WuXing::Huo); // 木生火
bool ke = wu_xing_ke(WuXing::Mu, WuXing::Tu); // 木克土
// 六十甲子
auto jz = LiuShiJiaZi::from_index(0); // 甲子
auto na_yin = jz.get_na_yin(); // 获取纳音五行
// 天干贵人
auto gui = get_gui_ren(TianGan::Jia, true); // 甲日阳贵人
// 天干寄宫
auto gong = get_ji_gong(TianGan::Jia); // 甲寄寅宫
// 地支藏干
auto cang = get_cang_gan(DiZhi::Yin); // 寅藏甲丙戊

奇门遁甲排盘

import ZhouYi.QiMen.Controller;
import ZhouYi.QiMen;
import std;
using namespace ZhouYi::QiMen;
// 方式1:公历排盘
auto result = QiMenController::pai_pan_solar(2011, 6, 18, 3, 56);
if (result) {
 const auto& pan = result.value();
 std::println("阴阳遁:{}", pan.dun == Dun::Yang ? "阳遁" : "阴遁");
 std::println("局数:第{}局", pan.ju);
 std::println("节气:{}", pan.solar_term);
 std::println("日干支:{}", pan.day_gan_zhi.to_string());
 std::println("时干支:{}", pan.hour_gan_zhi.to_string());
} else {
 std::println("排盘失败:{}", result.error());
}
// 方式2:农历排盘
auto result_lunar = QiMenController::pai_pan_lunar(2023, 5, 5, 14, 30);
// 获取排盘摘要
if (result) {
 const auto& pan = result.value();
 auto summary = QiMenAnalyzer::get_summary(pan);
 std::println("{}", summary);
}
// 分析宫位吉凶
if (result) {
 const auto& pan = result.value();
 
 // 分析南宫(离九宫)
 auto analysis = QiMenAnalyzer::analyze_auspiciousness(pan, Palace::South);
 if (analysis) {
 std::println("南宫分析:\n{}", analysis.value());
 }
 
 // 分析其他宫位
 auto north_analysis = QiMenAnalyzer::analyze_auspiciousness(pan, Palace::North);
 auto east_analysis = QiMenAnalyzer::analyze_auspiciousness(pan, Palace::East);
 auto west_analysis = QiMenAnalyzer::analyze_auspiciousness(pan, Palace::West);
}
// 查看九宫信息
if (result) {
 const auto& pan = result.value();
 
 // 遍历九宫
 for (const auto& [palace, gong_info] : pan.gong_map) {
 std::println("宫位:{}", palace);
 std::println("天盘:{}", gong_info.tian_pan);
 std::println("地盘:{}", gong_info.di_pan);
 std::println("人盘:{}", gong_info.ren_pan);
 std::println("八门:{}", gong_info.ba_men);
 std::println("九星:{}", gong_info.jiu_xing);
 std::println("八神:{}", gong_info.ba_shen);
 std::println();
 }
}

开发规范

1 C++23 标准强制

2 模块化规范

3 算法规范

std::ranges::transform(vec, std::back_inserter(result), fn);
std::ranges::filter(vec, predicate);
std::ranges::for_each(vec, action);
std::ranges::find_if(vec, condition);
std::ranges::count_if(vec, predicate);
std::ranges::any_of(vec, predicate);

std::transform(vec.begin(), vec.end(), ...); // 传统算法
for (auto& item : vec) { ... } // 手写循环(除非必要)

4 输出规范

std::println("{}", value); // 带换行
std::print("{}", value); // 不换行

std::cout << value << std::endl; // 禁止
printf("%d", value); // 禁止
fmt::print("{}", value); // 禁止

5 错误处理规范

// 函数返回值可能失败时
std::expected<Result, Error> process_data() {
 if (error_condition) {
 return std::unexpected(Error{"错误信息"});
 }
 return Result{...};
}
// 可选值
std::optional<Value> find_value() {
 if (found) return value;
 return std::nullopt;
}

Result* process_data(); // 返回 nullptr
int process_data(Result& out); // 返回错误码
throw std::exception("error"); // 使用异常(除非必要)

常见问题

项目维护

更新第三方库

# 更新所有子模块到最新版本
git submodule update --remote --merge
# 更新指定子模块
git submodule update --remote --merge 3rdparty/fmt

清理构建

# 完全清理
rm -rf build/
# 重新构建
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

贡献指南

# 提交代码模板
git add .
git commit -m "feat(module): 添加新的天干地支计算模块"
git push

相关资源

官方文档

第三方库文档

学习资源

许可证