紫微斗数排盘引擎（iztro + lunar_python）实战手册

本技能用于自建并校验一个紫微斗数本命盘排盘引擎。星盘用 iztro-py（纯 Python、传统安星诀，与"文墨天机"同源同规），八字四柱用 lunar_python（按节气取年/月柱）。已用多张真实盘与文墨天机比对，命宫干支、五行局、四柱全部吻合。

一、依赖与运行环境

pip install iztro-py lunar_python

• iztro-py v0.5.0：星曜、十二宫、四化、大限。
• lunar_python v1.4.8：历法换算，关键是按节气取四柱（不是农历月/年）。
• 隔离环境示例（本机）：C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe，依赖已装在此 venv。

二、三个必踩的 API 坑（已实测）

坑 1：八字四柱必须走 Lunar，不能直调 Solar

lunar_python 的 Solar 对象没有 getEightChar()。正确链路：

from lunar_python import Solar
solar = Solar.fromYmdHms(y, m, d, hour, minute, second)  # 6 个位置参数，缺一不可
lunar = solar.getLunar()
ec = lunar.getEightChar()
four = " ".join([ec.getYear(), ec.getMonth(), ec.getDay(), ec.getTime()])

→ 这步解决了"月柱错成乙未、应是甲午"这类问题：lunar_python 按节气（非农历月）取月柱，生日在小暑前就是午月不是未月。

坑 2：时辰 → iztro 索引

astro.by_solar(date_str, time_index, gender) 的 time_index 是 0–11（子=0…亥=11），不是 1–12。时辰中点计时：hour = 时辰索引 * 2（子→0, 丑→2, …, 亥→22）。

坑 3：大限是 pydantic 对象，不是元组

palace.decadal 是 Decadal 对象，起止岁数在 .range（元组）。不能直接 dec[0]/dec[1]，否则 TypeError: 'Decadal' object is not subscriptable。存盘/打印前转成列表：

decadal = list(palace.decadal.range) if palace.decadal is not None else None

否则 JSON 序列化也会失败。

坑 4：真太阳时返回浮点，note 格式化与 time_to_shichen 都会被 float 污染

true_solar_time 里 (longitude-120)*4 与 equation_of_time 都是浮点，导致 total 为 float，total//60、total%60 也是 float。两个下游会炸：
- note = f"...{th:02d}:{tm:02d}..." → ValueError: Unknown format code 'd' for object of type 'float'。
- time_to_shichen(th, tm) 里 (h2+1)//2 对 float 返回 float，传给 astro.by_solar 的 time_index 时 → TypeError: list indices must be integers or slices, not float。
根治：① true_solar_time 直接 return int(total//60), int(total%60)；② time_to_shichen 入参 h2 = int(h) % 24。两处都做最稳。

三、命宫掌诀（用于手算核对，不依赖库）

"寅起正月顺数至生月，再由月宫起子逆数至生时"得命宫地支。例：农历六月生 → 从寅顺数到未（生月）；未宫起子逆数到生时。用户本盘（阳历 1981-7-2 寅时，农历六月初一寅时）即得命宫 巳，与 iztro 输出一致，可双向校验引擎。

四、真太阳时折算

紫微定时辰用真太阳时，出生地经度与东经 120° 不同会差时辰（约每经度 4 分钟）：

def true_solar_time(h, m, longitude, doy):
    total = (h*60+m) + (longitude-120)*4 + equation_of_time(doy)
    total %= 1440
    return total//60, total%60

时辰交界（23点前后、1点、11点、13点前后）必须让用户给精确时间+出生地，避免排错宫。

五、与文墨天机逐盘验证的方法

1. 用引擎排目标盘，提取：命宫干支、五行局、八字四柱、生年四化。
2. 与文墨天机截图/输出逐项比对，命宫干支和五行局是最硬的对拍点。
3. 已验证通过的基准盘（命宫/五行局/四柱）：
   - 1981-7-2 寅时 男：癸巳 / 水二局 / 辛酉 甲午 辛巳 庚寅（廉贞陷贪狼陷；四化 巨门禄·太阳权·文曲科·文昌忌）
   - 1987-9-23 亥时 女：庚戌 / 金四局 / 丁卯 己酉 乙亥 丁亥（天机利[科]天梁庙）
   - 1997-1-15 丑时 女：庚子 / 土五局
   - 1997-2-28 未时 男：丁未 / 水二局
   - 1997-10-10 酉时 女：癸丑 / 木三局
4. 任何一张盘的命宫干支或五行局对不上，先查月柱（节气）与时辰索引，再查真太阳时。

六、输出字段（解读师重点看）

four_pillars（四柱）、five_elements_class（五行局）、soul_palace（命宫干支）、body_palace（身宫）、palaces（十二宫：主星名/亮度[庙旺利陷]/四化；空宫标"空宫"）、four_transformations（生年四化，按禄权科忌分组+落宫）、decadal（各大限起止岁）。

七、铁律（解读口径）

• 引擎只负责"排盘"生成星盘结构；解读须遵循善思君的真实文风与口径——给实在建议（敢下倾向判断，但不把话说死成"必然发生"），涉及健康、法律、投资只从文化角度提醒，不替代专业决策。
• 引用星曜/格局含义以《紫微斗数全书》《斗数骨髓赋》等古籍为准，网络流派之说不凌驾古籍。

八、善思君解读文风校准（character-destiny-analysis 专家专用）

从用户提供的 13 份真实样本（杨伊萌/冯菲/ovo/郑臻/Anne/李天月 6 份年运、罗雪莹/武晓菁/田阳 3 份全盘解析、问题咨询 3 份、起名 1 份）提炼出的统一文风，agent 提示已写入，此处存档要点以便维护时文风不跑偏：

核心特征
1. 全程"你""我"第二人称，像顾问当面聊；不用"用户/咨询者/盘主"第三人称客套词。
2. 口语化衔接：其实/本身/也就是说/换句话说/那/所以/就是；可反问、可互动（"你想想是不是这个理"）。
3. 敢给明确倾向判断（"可以买房，没有问题""原盘上确实是个破财的命""最快明年就能结"），但不用空泛绝对词（绝对/必定/百分百/完美/超级/相当/极致/碾压）；用"往往/容易/一般/整体上是/大概率/需要留意"留分寸。
4. 术语/星曜必附白话解释，古籍取象翻译成生活意象；格局神煞（文星拱命格/驳婚煞/三奇加会）先点名再白话展开。
5. 建议落地可执行生活化（"下半年怀更好、听医嘱""别做运营那么累、偏策划文案轻松点"）；给方向不替人拍板，落点"供你参考"。
6. 结尾引诗词加关怀祝福（"千磨万击还坚劲，任尔东西南北风""大鹏一日同风起，扶摇直上九万里"；"你才是自己人生的主人""请勇敢走下去，为了自己，加油"）。
7. 文字铁律：写全不硬缩、像人话不端机器腔、禁半截词自造词、禁低档小作文腔（不用"第一处/第二处"编号当骨架）。

结构模板
- 流年：①信息表 ②逐条答用户具体问题 ③"以下按农历月讲重点注意事项"（正月到十二月，闰月合并）④"总结一下" ⑤诗词加祝福。
- 全盘/性格：①整体点命格（先点格局名或先答最关心问题）②逐条答具体问题（工作/财/感情/健康）③从原局跨大运逐年推流年 ④诗词加关怀收尾。

范例（1998-12-23 武汉男，巨门旺加禄存坐命，节选开头，仅作文风参考）
男命，巨门坐命于巳宫、还是旺地，同宫禄存。这种组合你先记住一句话：你是个心里有数、嘴上也能说、但容易自己跟自己较劲的人。
巨门这颗星，白话讲就是"嘴和脑子的星"——你天生敏锐，看事一眼到底，表达也有力道，不是闷葫芦；但它也有另一面，就是容易想多、在心里反复嚼一件事，把简单的嚼出苦味来。禄存是财库星，压在命宫，给你的影响是：你对钱天然偏保守，攒着比花着踏实，不算是敢一把梭的性子。
身宫落福德宫、借对面财帛宫的天机化忌来看——这意思很关键：你这辈子的安稳感，是跟"事能不能在自己手里理清、兜里有没有底"绑在一起的。天机化忌在财帛，提醒你：钱上别太算计、别因想太细反而犹豫错失，也别借钱给人或替人担保，你这盘财上最怕"想太多加信错人"。