1. 项目概述一个为AI工具注入传统智慧的八字计算引擎最近我完成了一个挺有意思的项目把一套流传了上千年的中国命理计算体系——八字也叫四柱推命用TypeScript完整地实现了一遍并且做成了可以无缝集成到各种AI编程工具里的组件。这个项目叫shunshi-bazi-core本质上是一个高精度、可编程的八字排盘引擎。但和市面上大多数同类开源库不同我重点解决了几个长期被忽视但至关重要的计算准确性问题比如真太阳时校正和子时换日问题然后把整个引擎打包成了MCP服务器和Claude Code技能让AI助手也能直接调用进行专业的八字分析和解读。你可能会问在AI和现代编程的语境下做这个有什么意义我的出发点很实际我发现无论是个人开发者想做个相关应用还是研究者想进行一些文化或社会学的分析都缺乏一个可靠、透明、可验证的计算基础。网上能找到的JavaScript或Python库要么计算逻辑不透明要么存在明显的时区或历法处理错误导致排盘结果不一致更别提集成到现代开发工作流中了。而八字排盘本身是一套基于农历、干支纪年和真太阳时的精密计算系统任何一个环节的偏差都会导致完全不同的结果。所以我决定从最底层的天文历算原理开始构建一个经得起推敲的、可用于生产环境的开源核心并让它变得极易被AI调用。2. 核心问题拆解为什么大多数开源八字库不准在动手编码之前我花了大量时间调研了GitHub和NPM上能找到的几乎所有相关开源库。结论让人有点沮丧它们或多或少都存在一些根本性的缺陷导致排盘结果与专业命理师的手工推算或权威商业软件的结果对不上。这些问题主要集中在三个方面而它们恰恰是八字计算中最关键的环节。2.1 真太阳时校正的缺失这是最普遍也是最严重的问题。八字中的“时柱”是根据出生时的“真太阳时”来确定的而不是我们手表或手机上的“平太阳时”即标准时钟时间。地球绕太阳公转的轨道是椭圆形的并且地轴是倾斜的这导致真太阳在天空中的视运动速度并不均匀。因此真太阳时与我们的标准时间之间存在着一个差值这个差值叫做“时差”一年中最大可达到约30分钟。这30分钟在八字里意味着什么八字的一个时辰是2小时例如子时是23:00-01:00。如果一个人的出生时钟时间是23:15但当地的真太阳时是23:45那么按照时钟时间他属于当天的晚子时如果采用“晚子时”学派而按照真太阳时他已经进入了第二天的早子时。时柱一变整个八字的格局、十神、用神都可能随之改变解读结果也就南辕北辙了。大多数开源库直接忽略了这一点它们简单地将用户输入的北京时间或UTC时间当作真太阳时使用。这对于出生在时区中心经度附近比如东八区的东经120度线附近如杭州、上海的人来说误差可能不大。但对于出生在中国西部如乌鲁木齐虽然用东八区时间但地理经度在东经87度左右、日本北海道、美国西部或西欧的人来说时差可能高达数小时排盘结果几乎肯定是错的。shunshi-bazi-core的解决方法是要求用户提供出生城市名或具体的经纬度。库内部会查询该地点的经纬度结合出生公历日期计算出精确的时差并对输入的时钟时间进行自动校正。2.2 “子时”的换日争议处理子时23:00至01:00横跨两天这就引出了一个经典争议出生于23:00之后的人其日柱应该按当天算还是按第二天算命理学界主要有两派“晚子时”派认为23:00-24:00属于当天的最后一个时辰日柱用当天时柱用次日的子时“早子时”派则认为23:00-24:00已经是次日的子时日柱和时柱都用次日。很多库在这里采取了“鸵鸟政策”内部写死一种规则也不对外说明。用户发现排盘结果和某些网站或师傅算的不一样时根本不知道问题出在哪里。shunshi-bazi-core的做法是将选择权透明地交给开发者。在调用API时可以通过参数明确指定采用哪一种学派sect1 或 sect2并且在返回的结果中清晰标明所用的规则。这样无论是个人使用还是对接不同流派的命理师都有了明确的依据和灵活性。2.3 缺乏可验证的基准测试开源项目的可信度建立在可验证的基础上。如果一个八字库说它算得准拿什么来证明如果没有一套公认的、覆盖各种边界条件的“黄金测试用例”开发者就无法确认这个库的计算逻辑是否正确更无法在版本迭代中保证计算的一致性。为此我建立了自己的验证体系。首先我使用shunshi-bazi-core的计算结果与我自己维护的、经过大量人工校验的Shunshi.AI生产环境Python后端进行比对。其次我选取了其他一些较为成熟的开源或商业库如cantian-tymext作为参考在特定的边界案例如春节交界、23:48出生等上进行交叉验证。最终我固化了一组包含5个典型复杂案例的测试集确保每次代码更改都不会破坏核心计算的正确性。这种“基准测试”思维是工程化一个传统文化计算项目所必需的。3. 引擎架构与核心功能实现shunshi-bazi-core被设计成一个纯净的、无外部依赖的TypeScript计算库。它的目标单一而明确给定出生时间、地点和性别输出一个完整、准确、结构化的八字命盘对象。整个库的架构分为清晰的几个层次。3.1 数据输入与预处理层这一层负责接收和清洗原始输入。核心函数getBaziChart接受一个配置对象interface BaziInput { year: number; // 公历年份如1990 month: number; // 公历月份1-12 day: number; // 公历日期 hour: number; // 时钟小时0-23 minute: number; // 时钟分钟 gender: 0 | 1; // 性别0为女1为男 city?: string; // 出生城市名用于真太阳时计算 longitude?: number; // 或直接提供经度 latitude?: number; // 和纬度 sect?: 1 | 2; // 子时换日规则1早子时2晚子时 }预处理流程如下日期合法性校验检查输入的日期时间是否有效。地理位置解析如果提供了city会通过内置的地理编码数据一个精简的、包含全球主要城市经纬度的JSON文件查找其坐标。如果直接提供了longitude和latitude则跳过此步。真太阳时计算根据经纬度计算该地的“平太阳时”地方平均时。根据公历日期通过一个简化但精确的算法计算“时差”。这个算法模拟了地球轨道方程能计算出指定日期的真太阳时与平太阳时的分钟差值。将用户输入的时钟时间加上时区偏移根据经纬度推算再加上时差得到最终的真太阳时。农历转换将校正后的真太阳时对应的公历日期转换为农历日期。这里涉及到复杂的朔望月计算和闰月规则是另一个需要精细处理的部分。注意内置的城市数据库是精简版的如果遇到非常小众的地点建议用户直接传入经纬度坐标以获得最高精度。3.2 干支历计算核心这是整个库的“心脏”。它负责根据预处理后的农历日期和时间推算出四柱八字。年柱计算八字年柱的划分不是以公历元旦或农历正月初一为准而是以立春为界。例如公历1990年2月4日立春那么2月3日出生的人年柱仍是己巳2月4日立春之后出生的人年柱才是庚午。库内封装了从1900年至2100年的立春精确时刻表用于快速判断。月柱计算月柱同样以节气为界。每个月包含一个“节”和一个“气”月柱依据“节”来变换。例如寅月正月从立春开始卯月从惊蛰开始。库内也内置了主要节气的时刻表。日柱计算这是计算量最大的一环。需要根据公历日期通过特定的公式如基姆拉尔森计算公式的变体或逐日累加推算出当日的干支。这里必须正确处理格里高利历的闰年规则。如果遇到“子时换日”问题则依据sect参数对日柱进行相应调整。时柱计算根据日柱的天干和真太阳时所属的时辰子、丑、寅、卯...通过“五鼠遁”或“五虎遁”口诀推算出时柱。3.3 命盘信息衍生层计算出四柱八个字后大量的衍生信息就可以基于规则推导出来十神将四柱天干与日干进行生克比和关系的映射得出正官、七杀、正印、偏印等十神这是分析性格、六亲、事业的核心。五行强弱统计四柱天干地支包括地支藏干中金、木、水、火、土的数量和力量计算出各自的百分比用于判断八字五行平衡。神煞根据特定的日柱、年支等规则推算出一系列“神煞”如天乙贵人、文昌、桃花、羊刃等。shunshi-bazi-core目前计算超过40种常见神煞。大运与流年起运根据性别和出生月令的阴阳顺逆确定起运的岁数。这是通过计算出生日到下一个节顺排或上一个节逆排的天数以三天折合一岁、一天折合四个月、一个时辰折合十天来计算的。排大运从月柱出发依据阳男阴女顺排、阴男阳女逆排的规则排出每一步大运的干支。每步大运管十年。标记当前大运根据当前年份和起运岁数自动标记出命主正处于哪一步大运之中。特殊关系计算天干五合、地支六合、三合、六冲、三刑、相害等关系这些关系影响着八字内部的互动和能量流动。空亡根据日柱计算旬空即“空亡”的地支。最终所有这些信息被组织成一个结构化的JSON对象返回给调用者包含了从原始输入到最终解读所需的所有数据。// 返回的命盘数据结构示例简化 { input: { /* 原始输入及校正后信息 */ }, pillars: { year: { heavenlyStem: 庚, earthlyBranch: 午, hiddenStems: [丁, 己] }, month: { heavenlyStem: 己, earthlyBranch: 卯, hiddenStems: [乙] }, day: { heavenlyStem: 戊, earthlyBranch: 子, hiddenStems: [癸] }, hour: { heavenlyStem: 丁, earthlyBranch: 巳, hiddenStems: [丙, 庚, 戊] } }, tenGods: { /* 各柱十神 */ }, fiveElements: { wood: 12.5, fire: 37.5, earth: 25.0, metal: 12.5, water: 12.5 }, shensha: { /* 神煞列表 */ }, dayun: [ { range: 1995-2005, pillars: 庚辰, age: 5-15 }, { range: 2005-2015, pillars: 辛巳, age: 15-25, current: true } // ... ] }4. 与AI开发工具链的深度集成一个准确的计算引擎是基础但如何让它产生更大的价值我的思路是让它变得极其易用尤其是能够被当下最活跃的AI编程助手直接调用。为此我构建了三个层次的集成方案。4.1 作为MCP服务器集成到Claude Desktop和CursorModel Context Protocol是Anthropic推出的一套协议旨在让AI模型能够安全、结构化地调用外部工具。我开发了shunshi-bazi-mcp这个包它本质上是一个命令行程序遵循MCP协议将shunshi-bazi-core的计算能力暴露为AI可用的工具。部署极其简单用户只需要运行一行命令npx -y shunshi-bazi-mcp然后在Claude Desktop或Cursor的MCP配置文件中添加几行配置指明这个服务器的路径。// Claude Desktop 配置文件片段 { mcpServers: { shunshi_bazi: { command: npx, args: [-y, shunshi-bazi-mcp] } } }配置完成后重启Claude Desktop。当你在聊天框中输入“帮我算一下1990年3月24日上午10点28分在广州出生的男性的八字”时Claude会识别出这是一个需要调用工具的请求。它会自动调用shunshi_bazi服务器提供的calculate_bazi工具将你的自然语言描述解析成结构化的参数年、月、日、时、性别、地点发送给MCP服务器。MCP服务器调用核心库进行计算然后将完整的、结构化的命盘JSON返回给Claude。Claude内置的强大的分析和总结能力此时就能大显身手了。它不再是简单地复述数据而是能够基于返回的十神、五行、大运等信息生成一段专业、流畅的命理解读。比如它会分析“日主戊土生于卯月木旺克土身偏弱。月干己土劫财帮身时柱丁巳正印生扶为印星护身的格局。早年走庚辰、辛巳食伤大运利于学习技艺。目前正行壬午大运财星透干事业上有求财机遇但午火为羊刃也需注意人际关系...” 这相当于你拥有了一个随时待命、知识渊博的命理分析AI助手。4.2 构建Claude Code技能ClawHub对于更喜欢命令行效率的开发者我将其打包成了一个Claude Code技能并发布在ClawHub技能市场上。Claude Code是Anthropic的命令行AI工具。安装后你只需要在终端里输入类似命令/bazi 1993-08-18 14:30 male 广州或者更自然的语言/bazi 帮我算一下农历一九九三年七月初一下午两点半男北京出生技能会自动解析这些信息调用计算引擎并在终端里输出一个格式清晰、包含表格和关键分析的结果。它甚至能支持多语言输入中、英、日、韩并且提供交互式选项比如在基础排盘后你可以选择继续查看未来几年的流年运势或者进行合婚分析。这里踩过一个重要的坑安全性。最初版本的技能为了简化部署尝试在运行时动态执行npm install来安装依赖。这被ClawHub的OpenClaw安全扫描器果断标记为“可疑”行为。这是完全合理的因为允许一个技能在用户机器上任意安装npm包是巨大的安全风险。我立刻重构了项目将所有依赖明确声明在package.json中技能本身只是一个纯粹的调用入口。重新提交后扫描结果变成了“良性高置信度”。这个经历让我深刻体会到在AI工具生态中安全性和信任是产品设计的首要前提。4.3 作为独立的NPM库直接使用对于想要构建自己的八字应用、网站或进行学术研究的开发者shunshi-bazi-core本身就是一个独立的NPM包。它没有任何外部框架依赖可以在Node.js环境或浏览器中直接运行。npm install shunshi-bazi-coreimport { getBaziChart, getSolarTerm } from shunshi-bazi-core; // 计算八字 const chart getBaziChart({ year: 2000, month: 1, day: 1, hour: 12, minute: 0, gender: 1, city: Tokyo }); console.log(chart.pillars); // 也可以单独使用其历法功能比如查询某个日期是否为立春 const isStartOfSpring getSolarTerm(2000-02-04) 立春;这种分层架构的好处是清晰的所有计算逻辑都集中在核心库。MCP服务器和Claude Code技能只是这个核心的不同“包装器”。一旦核心库修复了一个bug或增加了一个新功能所有上层的集成方案都能立即受益保证了整个生态体系的一致性。5. 开发中的挑战与经验总结这个项目从构思到完成经历了多次迭代和问题排查其中一些经验教训对于开发类似的、涉及传统文化与精确计算的工具型项目很有参考价值。5.1 历法与天文计算的精度是生命线八字排盘本质上是一个天文历法计算问题。最初的版本我依赖了一个第三方农历转换库但在测试一些历史日期和极端案例时发现与权威参考数据有出入。这迫使我不得不深入农历算法的细节。我最终实现了一套基于现代天文算法简化版的农历计算逻辑虽然不如专业天文台精确到秒但对于日级别的八字排盘已经足够并且做到了完全自包含、可审计。对于关键的基础计算尤其是涉及标准的问题尽可能自己实现或选择最透明、可验证的方案避免黑盒依赖。5.2 建立“黄金测试用例”至关重要如何证明你的库算得准光说自己逻辑正确没用必须有客观的参照系。我花费了大量时间从古籍、专业软件和资深从业者那里收集、验证了多个“标杆案例”。这些案例覆盖了各种边界条件除夕夜子时出生、双春年闰月出生、真太阳时校正前后日柱变化等。我将这些案例写成单元测试每次代码提交都会自动运行。这不仅是保证代码质量的“安全网”更是给潜在使用者的一颗“定心丸”。他们可以看到这个库是经过严格验证的。5.3 为国际化做好准备八字文化不仅在中国在日本四柱推命、韩国사주팔자和越南等地也非常流行。因此从项目一开始我就考虑了多语言支持。这不仅仅是把界面文字翻译一下更重要的是术语映射确保“正官”、“七杀”等十神术语在不同语言中有准确的对应词。输入解析技能要能理解“1993年8月18日”、“1993-08-18”、“一九九三年七月初一”等多种日期格式以及“男”、“male”、“男性”等性别表达。SEO与发现在NPM包的description和GitHub的README中同时写上中文“八字”、日文“四柱推命”、韩文“사주팔자”和英文“Four Pillars of Destiny”让来自不同文化背景的开发者都能搜索到这个项目。5.4 AI工具集成生态正在快速成熟当我开始做MCP服务器时相关的工具和文档还比较零散。但就在项目开发过程中我明显感觉到整个生态在加速发展。ClawHub这样的技能市场出现了MCP的协议规范更加清晰开发工具链也在完善。这印证了一个趋势未来AI编程助手的能力边界将极大地由它们所能连接的专业工具MCP服务器所定义。将自己的专业领域能力封装成MCP服务器可能是开发者们赋能AI、同时也让自己的工作被更多人看见的新方式。6. 实际应用场景与扩展思考这个项目开源后我收到了一些反馈也看到了它的一些实际应用可能性远远超出了我最初的设想。场景一文化研究与数据分析。有社会学专业的学生联系我希望用这个库批量分析历史人物的八字数据研究某些十神或五行组合是否与历史记载的人物性格、命运轨迹存在统计学上的相关性。库的结构化JSON输出非常适合做这种批量处理和数据挖掘。场景二个性化应用开发。有开发者基于核心库快速搭建了一个结合用户生辰和当日天干地支的“每日运势”小程序。还有人在尝试将其与星座、塔罗等西方占卜系统结合做文化对比类的趣味应用。场景三传统行业的数字化工具。一些命理咨询师或培训机构对这个项目表现出兴趣。他们看中的是计算结果的准确性和可编程性希望能将其集成到自己的客户管理系统或在线教学平台中为学员提供自动化的排盘练习和验证工具。关于未来的扩展我个人最感兴趣的方向是“解释层”的开放。目前核心库只负责“计算”而“解读”由集成的AI如Claude或开发者自己完成。但八字解读本身也有深厚的规则比如取用神、断格局。或许可以设计一个插件化的“解读规则引擎”允许不同的学派或专家将自己的解读逻辑规则集以代码或配置的形式加入进来让这个开源项目不仅能准确排盘还能提供多样化、可追溯的解读框架。最后所有代码都在GitHub上以MIT协议开源。无论是想直接使用检查算法实现还是在此基础上进行二次开发都非常自由。我也持续维护着这个项目修复大家提交的Issue。做这个项目的初衷是希望为感兴趣的人提供一个可靠的技术基石让古老的知识能以一种现代、开放、可验证的方式延续和互动。当你看到AI助手基于精确的计算娓娓道来一段命理分析时那种传统与现代、感性与理性交织的感觉或许就是这个项目带给我的最独特的乐趣。