中华玄学推算 Skill
用途
- 八字：根据公历出生信息计算四柱、五行、十神、日主强弱、喜用神、大运，并附地支合局/刑冲害破与神煞。
- 择日：根据事项（结婚/搬家/开业/动土/出行/安葬/入学/求医）在日期范围内筛选吉日。
- 八宅命卦：根据出生年+性别推算命卦（东四/西四命）与八方吉凶方位。
- 八字合婚：比较两人八字，输出生肖匹配、日柱关系、五行互补、强弱互补与综合参考等级。
- 流年运势：结合命局+当前大运+流年干支，输出刑冲合害、喜用契合与综合倾向。
- 生肖年运：据生肖与流年地支关系判定犯太岁类型（值/冲/害/刑/破/合/平）。
- 玄空飞星：根据建造/入伙年（或运数）与房屋坐向（24山）排出运盘/山盘/向盘九宫飞星，并判断旺山旺向。
核心原则（最重要）
所有命理计算都由 scripts/ 下的脚本完成，模型绝不自行推算干支、五行、十神、强弱、喜用神、宜忌或方位。模型只负责四件事：
1. 从用户消息提取参数；
2. 运行对应脚本获取结构化事实（JSON）；
3. 依据 references/ 中的"含义数据"把代码输出的符号映射为对应文字；
4. 按 references/ 中的模板输出解读，并附免责声明。
> 任何命理结论必须取自脚本 JSON，不得由模型凭空生成或修正。
安全与隐私（Trust）
- 纯本地计算，无外部 API：所有排盘/择日/命卦/玄空飞星均由内置脚本在本地完成，不调用任何海外或第三方网络接口，符合国内网络环境可用要求。
- 唯一依赖：仅
sxtwl（天文历库）一个第三方包，且由脚本在运行时按需自动安装（国内镜像优先）。不安装任何其他组件、不执行任意网络下载、不修改系统配置。 - 不收集数据：出生年月日时等输入仅作为命令行参数在当次进程内计算，脚本不进行任何文件落盘、不上传、不留存。
- 最小权限：脚本只做"读参数→计算→打印 JSON"，不读写用户工程文件、不访问系统敏感目录。
能力边界 / 不适用场景（Adaptability）
- 适用：用户主动询问八字排盘、五行十神、大运、择吉日（择日）、八宅方位、合婚比较、流年/生肖年运、玄空飞星等传统文化推算时。
- 不适用（务必先说明再附免责声明，不强行给出"决策"）：
- 不替代专业命理师、医生、律师、理财顾问；
- 结论仅为传统文化/民俗参考，不构成婚恋、健康、投资、选址等任何现实决策依据；
- 不处理占卜、塔罗、星座等非本 skill 范畴的需求（应明确告知不在能力范围内）。
- 参数前置：运行脚本前必须拿到完整且合法的输入（如八字需年/月/日/性别，时辰可省略; 占卦场景直接走 Z 一句话占卦 路径(时柱按午时近似)，缺项勿逐项追问时辰/出生地）。
智能意图路由（Smart Routing）
模型在执行工作流前，须先完成以下智能判断：
1. 意图识别优先级
用户消息可能包含多个意图或模糊表述，按以下优先级路由：
1. 最简入口优先：用户只给「出生年月日 + 性别」且未明确指定功能时，走 Z. 一句话占卦 路径，一次性返回八字+流年+生肖年运。不要让用户在八字/流年/生肖之间做选择。
2. 显式功能优先：用户明确提到功能关键词（如"合婚""择日""飞星""命卦""排八字""流年""生肖运"），直接走对应路径。
3. 多意图合并：用户消息含多个意图（如"帮我排个八字，顺便看看2026年运势和生肖运"），优先用一句话占卦（zhan_gua.py）一次拿到全部数据，而非分三次调脚本。
2. 参数智能提取
- 日期格式兼容：用户可能写"1990年8月15日""1990-08-15""90年8月15""8月15号1990年"等，统一解析为 year/month/day。
- 性别格式兼容："男/女""male/female""m/f""乾/坤"均接受。
- 时辰格式兼容：用户可能说"早上7点""辰时""7:30"，小时用 0-23 整数；传统时辰名（子时/丑时/...）自行换算为对应小时（子=23/0, 丑=1/2, 寅=3/4, ... 亥=21/22），取该时辰的中间小时。
- 生肖格式兼容："属马""生肖马""1990年生的"均接受；有出生年时优先用出生年推算生肖（更准确），而非直接用用户口述的生肖。
- 坐向格式兼容："子山午向""坐北朝南""坐子向午"均接受；"坐北朝南"需换算为 sitting=子, facing=午（北=坎/子，南=离/午，东=震/卯，西=兑/酉）。
3. 上下文复用（多轮对话）
- 用户在同一会话中可能分多次提供参数（如先说"我1990年8月15日生的，男的"，后说"帮我看看2026年运势"）。模型应记住前序消息中已提取的参数，后续意图直接复用，不重复追问已提供的信息。
- 若用户在排完八字后追问"那我呢？""再看看合婚呢？"，应自动复用已有出生信息，补充对方信息即可。
4. 缺参智能兜底
- 时辰缺失：所有涉及时辰的脚本（bazi/liunian/hunhe/zhan_gua）均支持时辰缺省（按午时12:00近似），不要因缺时辰而拒绝服务或逐项追问。仅在输出中透明提示"时柱按午时近似"即可。
- 出生地缺失：真太阳时换算缺出生地时按北京时间（经度120）处理，不影响排盘基本可用，仅时柱精度略有差异。不追问。
- 流年缺失：liunian/zhan_gua 默认取当前年份，不追问。
- 必填项缺失：仅当年/月/日/性别（八字类）或出生年+性别（命卦类）或生肖/出生年（生肖年运类）或事项+日期范围（择日类）或坐向+运数/年份（玄空类）缺失时，才向用户索要，且一次性说清需要什么。
错误处理约定（Reliability）
- 每个 CLI 入口已用
S.run_cli(main)统一兜底：未预期异常会被捕获并输出结构化中文错误 JSON（{"error":..., "error_type":..., "hint":...}），不会抛出 Python traceback，便于模型稳定解析并向用户返回友好提示。 - 输入校验：非法日期（如 2 月 30 日、月份越界）、非法坐向/坐向卦、未知事项等会在运行期给出明确中文报错。
- 依赖降级：未装
sxtwl时自动降级为内置近似算法并在notes中透明告知，不影响其他功能可用。
共享引擎
scripts/suanli.py 提供日历、四柱、真太阳时、五行/十神/强弱/喜用神/大运、建除十二神、八宅命卦、玄空飞星等公共计算，各 CLI 均复用它。计算精度：已安装 sxtwl 时年/月/日柱走天文级排盘；否则用内置近似算法（节气±1天）。缺库自动安装（国内网络优先）：各脚本入口会调用 _ensure_sxtwl()，若运行环境未安装 sxtwl 会自动 pip install sxtwl，依次尝试清华/腾讯/阿里国内镜像源，最后回退官方 PyPI（设置环境变量 BZ_NO_AUTO_INSTALL=1 可关闭）。安装结果会写入输出 notes（如"已装 sxtwl…"或"已尝试安装但失败…已降级为内置近似"），保证发布到 skillhub 后他人首次运行即获得合格精度且状态透明。
工作流（按意图路由）
Z. 一句话占卦（最简入口，推荐）
> 用户只给「出生年月日 + 性别」就想听一卦时，走这条路径，不要让他补一堆参数。
- 提取：出生年/月/日、性别（必填）；时辰可不填（缺省按午时 12:00 近似）、出生地（城市/经度）可选。
- 运行：
python {baseDir}/scripts/zhan_gua.py --year <年> --month <月> --day <日> --gender <男|女> # 合并写法: python {baseDir}/scripts/zhan_gua.py --date 1990-08-15 --gender 男 # 特定流年: 追加 --liu-year 2026 ; 精确时柱: 追加 --hour <时> [--minute <分>] - 该脚本一次性返回
bazi+liunian（默认当年）+shengxiao_yun三块结构化事实。 - 读取
references/zhan_gua_template.md的翻译指引，输出一段"一卦"解读（时柱近似时开头轻轻提醒即可，不要反过来追问卡住用户），并附免责声明。
A. 八字排盘
- 提取：年/月/日（公历）/性别(m/f) 为必填；时辰（公历，24h）可选（不填则按午时近似）；以及可选的出生地（城市名或经度，用于真太阳时）。
- 运行：
python {baseDir}/scripts/bazi.py --year <年> --month <月> --day <日> --hour <时> --gender <m|f> [--city 成都 | --longitude 105.0] - 读取
references/interpret.md的"八字"部分，逐符号翻译，按references/prompt_template.md输出。
B. 择日
- 提取：事项(purpose)、起算年月日、扫描天数(默认30)、用户生肖(可选，用于避冲)。
- 运行：
python {baseDir}/scripts/zeri.py --purpose 结婚 --year 2026 --month 8 [--day 1] [--days 30] [--zodiac 马] - 读取
references/interpret.md的"择日"部分，把候选日与宜忌翻译输出。若候选日含purpose_match字段（非 null），说明该日宜列表中有与用户事项直接对应的条目（如用户问"结婚"，宜列表中的"嫁娶"会被匹配），翻译时优先提及匹配项。
C. 八宅命卦
- 提取：出生年、性别(m/f)，可选房屋坐向卦(用于宅命匹配)。
- 运行：
python {baseDir}/scripts/bazhai.py --birth-year 1990 --gender m [--zhaixiang 坎] - 读取
references/interpret.md的"八宅命卦"部分，翻译命卦/四吉方/四凶方输出。
D. 八字合婚
- 提取：甲方与乙方各自的公历 年月日、性别（必填）；时辰可不填（缺省按午时近似）；以及可选的出生地（经度/城市，用于真太阳时）。
- 运行：
# --ah/--bh 可省略（默认午时近似） python {baseDir}/scripts/hunhe.py \ --ay 1990 --am 8 --ad 15 --ah 7 --ag m \ --by 1992 --bm 3 --bd 20 --bh 12 --bg f \ [--a-city 成都 | --a-longitude 105.0] [--b-city ... | --b-longitude ...] - 读取
references/interpret.md的"八字合婚"部分，按references/hunhe_template.md翻译输出，并附合婚免责声明。
E. 流年运势
- 提取：出生年月日、性别、目标流年（如 2026）（必填）；时辰可不填（缺省按午时近似）；以及可选出生地（经度/城市）。
- 运行：
# --hour 可省略（默认午时近似） python {baseDir}/scripts/liunian.py --year 1990 --month 8 --day 15 --hour 7 --gender m \ --liu-year 2026 [--city 成都 | --longitude 105.0] - 读取
references/interpret.md的"流年运势"部分，按references/liunian_template.md翻译输出，附免责声明。
F. 生肖年运
- 提取：生肖（如 马）或出生年，目标流年（如 2026）。
- 运行：
python {baseDir}/scripts/shengxiao_yun.py --zodiac 马 --liu-year 2026 # 或: python {baseDir}/scripts/shengxiao_yun.py --birth-year 1990 --liu-year 2026 - 读取
references/interpret.md的"生肖年运"部分，按references/shengxiao_yun_template.md翻译输出，附免责声明。
G. 玄空飞星
- 提取：建造/入伙年份（或运数 1-9）、房屋坐向（如
子山午向或 坐山子+ 向首午）。 - 运行：
python {baseDir}/scripts/xuankong.py --year 2024 --sitting 子 --facing 午 # 或: python {baseDir}/scripts/xuankong.py --zuo-xiang 子山午向 --year 2024 # 或: python {baseDir}/scripts/xuankong.py --period 9 --sitting 子 --facing 午 - 读取
references/interpret.md的"玄空飞星"部分，按references/xuankong_template.md翻译九宫飞星输出，附免责声明。
输出约束
- 不得出现绝对化预测（如"必发财""一定婚姻不顺"）。
- 语气正面、不恐吓。
- 涉及健康/医疗时，提醒以专业医生为准。
- 若八字 JSON 中
engine为builtin-approx，注明排盘为近似精度（已自动尝试安装 sxtwl，失败则降级）；建议用户在可联网环境重跑以获得天文级精度。 - 择日/命卦/玄空结论为传统文化参考，末尾附免责声明："命理分析仅供参考，不构成任何决策依据。"
数据来源
- 干支/五行/纳音/十神/五行属性：
data/tiangan.json、data/dizhi.json、data/nayin.json、data/wuxing_relation.json。 - 地支关系（合局/刑冲害破）：
data/dizhi_relation.json。 - 神煞规则：
data/shensha.json。 - 生肖关系（六合/六冲/六害/三合）：
data/zodiac_relation.json。 - 城市经度（真太阳时）：
data/cities.json。 - 黄历宜忌/建除/冲煞：
data/huangli.json。 - 八宅命卦方位：
data/bazhai.json。 - 玄空飞星（24山阴阳/洛书飞序/运盘纪年/九星吉凶）：
data/xuankong.json。 - 含义映射与解读要点：
references/interpret.md。 - 输出模板：
references/prompt_template.md、references/zhan_gua_template.md、references/zeri_template.md、references/bazhai_template.md、references/hunhe_template.md、references/liunian_template.md、references/shengxiao_yun_template.md、references/xuankong_template.md。 - 运行依赖：
requirements.txt（sxtwl，缺库时脚本运行时自动安装）。
版本与更新（Convention）
- 版本号与变更记录见
VERSION（语义化MAJOR.MINOR.PATCH）。 - 脚本公共参数/JSON 字段结构保持稳定；若调整字段，将在
VERSION注明BREAKING项。 - 当前版本：
V1.0.1—— 八字排盘/择日/八宅命卦/合婚/流年/生肖年运/玄空飞星七大类功能；修复日主强弱得地计算Bug；新增破太岁检测；合婚/流年支持时辰缺省；择日输出增加事项匹配标注；SKILL.md 新增智能意图路由/参数提取/多意图/上下文复用指引；sxtwl 自动安装（国内镜像源优先 + 多源 fallback，状态透明）；全部 CLI 统一异常兜底与输入校验；模型只做查表翻译。
