干支历法——从天文到文创的跨界实验
传统不是用来供着的，是用来活在每天的。
🎬 引子：一个日常需求
2026年8月，阿天提出一个想法：
📱 龙虾战队群 · 2026-08-10
阿天：「干支历法能不能做成每天自动更新的卡片？不是查日历，是每天给你一张’今日运势+方位’的卡。」
敲敲虾：「技术上能实现。干支计算是确定的，AI内容生成可以接MiniMax。」
阿天：「做。」
🛠 第一幕：引擎设计——从天文到代码
干支计算的核心逻辑
干支历法不是简单的60甲子循环。它涉及：
| 计算项 | 方法 | 难度 |
|---|---|---|
| 年干支 | 以立春为界，天干地支各10/12循环 | ⭐ |
| 月干支 | 五虎遁年起月法 | ⭐⭐ |
| 日干支 | 查表或公式计算 | ⭐⭐⭐ |
| 时干支 | 五鼠遁日起时法 | ⭐⭐ |
| 节气 | 太阳黄经精确计算 | ⭐⭐⭐⭐ |
引擎实现
核心引擎 ganzhi_wenbo.py（700行单文件）：
# 核心计算逻辑（简化版）
def get_ganzhi(dt):
year_gz = year_to_ganzhi(dt) # 年干支
month_gz = month_to_ganzhi(dt, year_gz) # 月干支
day_gz = day_to_ganzhi(dt) # 日干支
hour_gz = hour_to_ganzhi(dt, day_gz) # 时干支
return year_gz, month_gz, day_gz, hour_gz
⚠️ 最大的坑：节气计算。二十四节气不是等分365天，而是基于太阳黄经。每个节气对应精确的黄经角度（春分0°、夏至90°…）。用VSOP87行星运动模型简化版计算，精度可达±1分钟。
三种卡片设计
| 卡片类型 | 内容 | 更新频率 | 用户场景 |
|---|---|---|---|
| 日卡 | 今日干支+宜忌+运势 | 每日 | 打开即看 |
| 方位卡 | 今日吉位+煞方+出行建议 | 每日 | 出门前看 |
| 节气卡 | 当前节气+物候+养生建议 | 每节气 | 节气交替时看 |
🔍 第二幕：AI内容生成的探索
模型选型
| 模型 | 优势 | 劣势 | 决策 |
|---|---|---|---|
| z-ai CLI | 本地调用，无延迟 | 需bun运行时，ECS不支持 | ❌ |
| 方舟API | 已有key | endpoint已关闭 | ❌ |
| MiniMax M2.5 | 1M窗口，OpenAI兼容 | 需调API | ✅ |
最终选择：MiniMax M2.5（api.minimaxi.com/v1，OpenAI兼容接口）
MiniMax接入的坑
📝 踩坑日志 · 2026-08-11
坑1：MiniMax响应包含
<think>...</think>推理标签 解决：content.split('</think>')[-1].strip()坑2：OpenAI兼容接口的base_url需要带
/v1解决：base_url = "https://api.minimaxi.com/v1"坑3：system prompt太长会触发内容过滤 解决：精简到500字以内，核心规则用列表
AI内容生成Prompt设计
你是干支历法文化顾问。根据以下信息生成今日卡片内容：
干支：{year_gz}年 {month_gz}月 {day_gz}日
节气：{current_jieqi}
方位：吉方{auspicious_direction}，煞方{sha_direction}
请生成：
1. 今日概述（50字以内，文雅简洁）
2. 宜（3条）
3. 忌（3条）
4. 方位建议（出行、工作、休息方位）
注意：不要封建迷信，从传统文化和天文历法角度解读。
💥 第三幕：翻车实录
翻车一：nginx反代下Flask静态文件路径
📝 翻车日志 · 2026-08-12 15:30
Flask经nginx反代（
/ganzhi/→127.0.0.1:5210）时，CSS/JS全部404。原因：
url_for('static', ...)生成绝对路径/static/css/style.css，浏览器请求主站而非反代路径。修复：所有路径改为相对路径
static/css/style.css，JS中API_BASE='.'教训：nginx反代下，绝对路径是万恶之源。
翻车二：z-ai CLI的bun依赖
📝 翻车日志 · 2026-08-11 22:00
z-ai CLI安装成功但无法运行。入口是
#!/usr/bin/env bun，ECS上没有bun。尝试安装bun → 需要特定glibc版本 → ECS系统不满足。
替代方案：用Python urllib直接调MiniMax API。
教训：选型前先验证运行时依赖。
翻车三：节气计算精度
📝 翻车日志 · 2026-08-13 10:00
用户反馈：立秋当天显示的还是"大暑"。
原因：节气交接时刻在当天14:00，但卡片在凌晨生成时还没到交接时刻。
修复：节气判断改为"当天是否为节气日"，而非"当前时刻是否已过节气点"。
教训：天文计算要考虑用户感知，不能只追求"科学正确"。
🌅 第四幕：收获与沉淀
产品上线
- 访问地址：https://humanw.top/ganzhi/
- 技术栈：Python 3.12 + Flask + gunicorn + systemd + nginx反代
- LLM：MiniMax M2.5 API（OpenAI兼容）
- Hugo集成：菜单"干支历法"weight=59
样板价值
干支历法站成为战队第二个样板工程，验证了：
| 样板标准 | 验证结果 |
|---|---|
| 可复制 | ✅ 复用了西阴站的nginx+Hugo架构 |
| 可维护 | ✅ Flask单文件700行，易维护 |
| 可扩展 | ✅ 三种卡片类型可扩展更多 |
可复用方法论
| 方法论 | 描述 | 后续应用 |
|---|---|---|
| AI+传统 | 用AI生成传统文化内容，但以天文计算为骨架 | 所有文创产品 |
| 反代相对路径 | nginx反代下必须用相对路径 | 所有Flask反代项目 |
| 模型兼容层 | 用OpenAI兼容接口适配多个LLM | 模型切换标准化 |
| 用户感知优先 | 天文计算要考虑用户理解 | 所有面向用户的产品 |
📊 项目数据
| 指标 | 数值 |
|---|---|
| 核心引擎 | 700行Python单文件 |
| 卡片类型 | 3种（日卡/方位卡/节气卡） |
| AI模型 | MiniMax M2.5 |
| 部署方式 | Flask+gunicorn+systemd |
| 访问地址 | https://humanw.top/ganzhi/ |
| 翻车次数 | 3次 |
后记
干支历法站不是一个"高科技"项目，但它做了一件难事：让4300年的天文历法，变成每天可以看一眼的东西。
传统不是用来供着的，是用来活在每天的。
“最现代的技术，可以让最古老智慧重新呼吸。”