算卦（小六壬 · 大六壬 · 六爻 · 梅花易数）

算卦综合 Skill，提供小六壬、六爻纳甲、梅花易数、大六壬四种算卦方法。含智能路由（根据问题自动推荐方法）、基础知识库（天干地支、阴阳五行、八卦、六亲）、以及可独立调用的 Python 计算脚本。所有涉时方法已升级为基于 zhdate 的精确农历/节气/干支计算。触发关键词：算、占卜、卜卦、算算、测算、求测、预测、小六壬、六爻、梅花易数、大六壬、马前课、掐指、摇卦、铜钱卦、起卦、断卦。

算卦综合 Skill

本 Skill 整合四种主流算卦方法（小六壬、六爻、梅花易数、大六壬），按"智能路由 → 按需加载 → 执行算卦"的流程工作。

📑 Quick Navigation

你想知道...	跳到
🚦 执行前必看（4 个硬约束 Checkpoint + 反模式）	MANDATORY WORKFLOW CHECKPOINTS ← 必读
⚠️ 当前实现关键点（北京时间基准 / 跨日处理）	重大变更
🪤 执行前必读（11 条已知坑 + 实战术）	已知陷阱
🏗️ 架构 + 路由	架构总览 → 路由与工作流
📚 方法细节	各方法执行流程
🛠️ 脚本使用	脚本速查
➕ 扩新术种	扩展指南
🌍 海外用户	README § 🌍 International Users
📂 真实案例	examples/re-consultation-comparison.md

🚦 MANDATORY WORKFLOW CHECKPOINTS

这段是硬约束。在执行任何算卦之前，必须按顺序完成下列每一项。任何一项跳过都视为违反本 SKILL。

🔴 在使用 clarify 工具问完这两个问题之前，禁止调用任何 --snapshot 或起卦脚本。

• Checkpoint 1: 确认起卦方法

  • 动作：用 clarify 工具问用户："用哪种方法算这个卦？"，提供 4 个选项（六爻/梅花/小六壬/大六壬）+ 推荐
  • 禁止：❌ 不要直接挑一个方法开算 ❌ 不要假设"用户上次用了六爻这次也用"
  • 例外：仅当用户自己已明确说"用六爻算"时，可跳过

• Checkpoint 2: 确认城市/经度（真太阳时校准）

  • 动作：用 clarify 工具问用户："你当前所在城市？"，提供 5 个选项（成都/北京/上海/手动经度/跳过）
  • 禁止：❌ 不要基于"用户历史对话常用 X 城市"猜测 ❌ 不要默认"用户在成都"
  • 例外：仅当用户自己已明确说"我在 X"时，可跳过

• Checkpoint 3: 报告校正结果

  • 动作：向用户展示：📍 城市（经度） + 北京时间 → 真太阳时 + 偏移分钟数 + 时辰
  • 目的：让用户看到校正结果再继续（避免默默算错）

• Checkpoint 4: 起卦 + 解读 + 免责声明

  • 必须输出：⏱ 时间标注 + 🎯 方法说明 + ⚠️ 末尾免责声明
  • 禁止：❌ 不要省略免责声明（这是本 SKILL 的合规底线）

📋 实际执行的指令模板：

text

[第 0 步] 完成上述 4 个 Checkpoint
[第 1 步] 加载 router/matching-matrix.md
[第 2 步] 加载方法对应的 references
[第 3 步] 调用 scripts/* Python 脚本
[第 4 步] 输出卦象 JSON + 解读 + 应期 + 免责声明

❌ 反模式（绝不能这样）：

• 跳过 Checkpoint 1 直接挑方法
• 跳过 Checkpoint 2 猜城市
• 跳过 Checkpoint 3 不展示校正结果
• 跳过 Checkpoint 4 的免责声明
• 用纯文字描述要问什么问题（必须用 clarify 工具实际调用）

⚠️ 重大变更（当前实现）

时间基准改为"北京时间（UTC+8）"，不再用 datetime.now() 拿本地挂钟时间。

• 影响：海外用户（西经/东经区域）能拿到正确的当地 TST，不会"跨日错位"
• API：
  • get_beijing_time() —— 强制取北京时间（零网络依赖）
  • longitude_to_true_solar(bj_dt, lon) —— 北京时间 + 经度 → 当地 TST
  • datetime_to_shichen(dt) —— datetime → 十二时辰
  • get_full_pipeline(dt=None, longitude=None) —— 一站式 pipeline
• 向后兼容：get_current_lunar_info() 入参/返回字段不变，内部已改用新 pipeline
• SKILL 流程推荐写法：

  python

  from common import get_beijing_time, get_full_pipeline
  bj = get_beijing_time()                    # 北京时间
  info = get_full_pipeline(longitude=104.06) # 成都 TST
  

• 跨日处理：TST 校正后 tst_datetime 可能落在前一天/后一天（如北京时间 6/15 06:00 → 纽约 TST 6/14 17:00），这是天文事实不是 bug

⚠️ 已知陷阱（执行前必读）

1. zhdate 版本现实与文档不符：requirements.txt 写的是 zhdate>=1.0，但 PyPI 上 Windows 平台最高只有 0.1（1.0 只发了 macOS ARM wheel，无 Windows 版本）。可直接装 pip install zhdate==0.1，API 兼容。脚本实际用到的 ZhDate.from_datetime / to_datetime / leap_month / lunar_year/month/day 在 0.1 中全部存在，已端到端验证。
2. 默认 python 解析到 Hermes venv，但 venv 没装 pip 也没装第三方包。直接 python scripts/... 会报 ModuleNotFoundError。先 bootstrap：python -m ensurepip 然后 python -m pip install zhdate==0.1。
3. common.hour_to_shichen(hour) 返回的是 (地支名字符串, 1-12 整数) 元组，不是直接的索引。用法是 shichen_name, hour_idx = common.hour_to_shichen(hour)。对应的字典是 common.DIZHI_SHICHEN（key=地支名字符串），不是按整数索引。
4. xiao_liuren 的入口是 by_month_day_hour(month, day, hour_idx)，不是 SKILL 旧版暗示的 calc_xiao_liuren()。calc_gong / LIU_GONG / by_numbers 都在，但前两者是内部辅助。
5. liuyao_yaogua.py --json --day-tg 乙 --day-dz 卯 端到端可用，输出包含世应、动爻、六亲、六神、旬空，可直接喂给 LLM 断卦。不要用 --auto（不会取冻结时间）。
6. 断卦时优先看动爻、月建、日辰三件事，六兽只作辅助（参考 references/liuyao/duangua.md）。凡遇"用神两次出现"（如本卦二爻+五爻都是官鬼）应取动爻为主静爻为辅。
7. 真太阳时校正跨时辰边界时（如 16:49 北京 → 15:46 成都 TST），必须用校正后的浮点小时重新跑 hour_to_shichen；申时(15-17)未跨则沿用原时辰。已校正的 snapshot['shichen']/shichen_idx 就是结果。
8. TST 校准对海外用户是错的（已修复）：get_current_lunar_info 早期版本把 datetime.now() 拿到的本地挂钟直接当成北京时间再做 (经度-120°)*4分钟 修正，纽约用户传 --lon -74.006 会得到错的"申时"而非真实的"寅时"。当前实现改为：先取北京时间（datetime.utcnow() + 8h）→ 再用经度做 TST 校准 → 跨日自动处理。
9. 重复复卦会"卦气散"：传统易学里对同一事反复起卦（3+ 次）会让信号失真。本 skill 工作流在路由层有"已问过同类问题 → 建议改用别的方法或休息"的设计意图，但当前还没硬限。操作建议：复卦前先回顾前 N 次结论；若前 3 次信号一致，别再问。如果前 3 次信号矛盾，可换方法或等 24 小时再问。
10. "算卦综合"是过宽的命名（已修复）：SKILL 早期版本标题/description 写"国学占卜综合"，会让 marketplace 用户以为涵盖紫微/八字/奇门/太乙，实际只覆盖 4 种起卦方法。当前统一改为"算卦综合"，命名匹配实际能力。
11. 网络降级有 0.3-0.8s 延迟：--city 未知城市名时，会调用 Open-Meteo Geocoding API（urllib 标准库，无需 requests）。首次查询慢，结果会缓存到 scripts/_geo_cache.json，下次 0ms 命中。完全离线场景下网络降级会失败，应改用 --lon 传经度。网络调用与 zhdate 安装、起卦计算完全独立，最坏情况（没网+没缓存+没坐标）只是 city 查询失败，不会影响核心起卦流程。
12. _geo_cache.json 跟踪进 git：该文件已加入 .gitignore（每用户本地缓存不同），但首先生成时会创建。

完整排查细节、API 真实签名见 references/comprehensive-divination-skill-pitfalls.md。

实战陷阱（复占 4 次后总结）

下列条目来自实际多日复占同一事件积累的教训，与第 1-7 条同等优先级：

8. 复占必须换变量。 同一问题反复起卦 → 卦气散 → 结论模糊。合法复占 = 换角度（如"会不会过"→"HR 多久回音"）。用户焦虑反复问同一事时，劝停比继续起卦更负责。
9. 日期先算后用。 用户描述"上上周四"等相对时间时，先用 date 算术出绝对日期再起卦。错一天月令可能跨，整个旺衰判断会错。
10. 跨月令 = 月柱换 = 五行背景改。 芒种/大雪等节气交月后，月干支与月令五行全变。common.py --snapshot 返回的 month_gz 是权威源，不要凭"calendar 是几月"判断。
11. 完整起卦流程（7 步）：
    1. python common.py --snapshot --city 城市 冻结时间（第一步必须做）
    2. 四维分析（领域/重要度/时效/复杂度）→ 选方法
    3. 用户确认方法后，若未提供城市则补问
    4. 按需加载 references/<method>/
    5. 调用 <method>.py 显式传参（不要 --auto）
    6. 综合 references + 五行 + 动爻月建日辰 解读
    7. 输出含时间标注 + 方法说明 + 末尾免责声明
12. 跨时区警告必须醒目。 真太阳时校正跨过时辰边界（如 16:49 北京→15:46 成都 申→未），必须用 tst_offset_min 重新跑 hour_to_shichen，不能沿用原时辰。

复占实战补充（2026-06-15）：上面 4 条坑（复占换变量 / 日期先算 / 跨月令 / 完整流程）来自用户连续 4 天问"某公司一面是否通过"的实战总结。当用户反复问同一事时，把"卦气已散、该用行动替代"明确说出来，比继续起第 5 卦更负责。

架构总览

text

用户输入 "帮我算个事"
  ↓
【第零层：时间锚定】立即冻结当前时间（datetime.now()），防止流程延迟导致边界时刻漂移
  ↓
【第一层：路由判断】加载 references/router/matching-matrix.md
  ├── 问题分析（复杂程度 / 决策重要性 / 时效性 / 领域）
  ├── 四维加权评分 → 推荐最优方法
  └── 用户确认使用哪种方法
  ↓
【Step 5.5：真太阳时校准】询问用户当前所在城市 → 城市→经纬度 → 对冻结时间做真太阳时校正
  ├── 若用户跳过（不提供位置）：默认北京时间（东经 120°）
  ├── 若用户在已知城市列表中：自动查表获得经纬度
  └── 若用户提供具体经纬度：直接使用
  ↓
【第二层：按需加载】只加载选取方法所需的 references
  ├── 小六壬：references/xiao-liuren/method.md + references/xiao-liuren/liugong.md
  ├── 六爻：references/liuyao/method.md + references/liuyao/najia.md + references/liuyao/duangua.md
  ├── 梅花易数：references/meihua-yishu/method.md
  ├── 大六壬：references/da-liuren/method.md + references/da-liuren/shier-tianjiang.md + references/da-liuren/sanzhuan-faze.md
  └── 所有方法共用：references/core/ 中的基础知识（按需读取单份文件）
  ↓
【第三层：执行占卜】
  ├── 确定性计算（干支查找、掌诀推算、摇卦模拟）
  │     → 优先调用 scripts/ 中的 Python 脚本，传入已校正的时间参数
  └── 解读性断语（五行生克、六亲应期）→ AI 基于 references 内容推理
  ↓
输出结果（含真太阳时校正标注）

路由与工作流（SKILL.md 主指令）

触发条件

当用户提出占卜相关请求且未指定具体方法时，触发路由模式。 若用户已明确指定方法（如"用六爻算"、"小六壬起一卦"），跳过路由直接进入对应方法。

路由步骤

Step 0 — 时间锚定（必须最先执行）：

当用户触发占卜（无论是否指定方法），立即冻结当前时间。注意：不要调用 datetime.now() 后再执行其他操作——必须在流程入口第一时间锚定。

Python 端执行：

bash

python scripts/common.py --snapshot [--city 城市名] [--lon 东经]

若用户尚未提供位置，先行冻结（不含 TST），待第 1.5 层补充位置后再重新计算。

返回的 JSON 结构包含：frozen_at（ISO 8601 时间戳）、bj_hour（北京时间）、ts_hour（真太阳时，若已提供位置）、shichen、shichen_idx 等全部字段。

Step 1 — 加载路由矩阵：读取 references/router/matching-matrix.md

Step 2 — 四维分析：从用户问题中提取：

• 复杂程度（简单是非题=1 / 多因素交叉=2 / 系统性推演=3）
• 决策重要性（日常琐事=1 / 中等决策=2 / 重大决策=3）
• 时效要求（即时=3 / 可等=2 / 不急=1）
• 问题领域（出行/寻物/运势/感情/事业/健康/投资/搬迁/随机）

Step 3 — 加权评分：按维度权重（决策35% + 复杂25% + 领域25% + 时效15%）计算各方法总分

Step 4 — 特殊规则：

• 用户报了数字 → 梅花易数 ×1.5 加分
• 用户指定了日期 → 大六壬 ×1.5 加分
• 问题 < 5字 → 小六壬 ×1.5 加分
• 已指定方法 → 直接放行

Step 5 — 输出推荐：排名 + 评分理由，等待用户确认

Step 5.5 — 真太阳时校准（用户确认方法后、执行前）：

在用户确认占卜方法后、开始执行前，询问位置：

请告知你当前所在的城市（如：成都），用于真太阳时校准。 若跳过，默认使用北京时间（东经 120°）。

处理逻辑：

• 用户提供城市名 → 调用 scripts/common.py --snapshot --city <城市> 重新获取含 TST 的时间快照
• 用户提供经纬度 → 调用 scripts/common.py --snapshot --lon <东经>
• 用户跳过 → 使用 Step 0 中无校正的快照，标注"基于北京时间"
• 城市不在已知列表 → 告知"未知城市，请输入当地东经（如成都=104.06）"

校正完成后，展示给用户确认：

📍 成都（104.06°E）真太阳时修正： 北京时间 15:22 → 真太阳时 14:21（−61 分钟） 时辰：申时 → 未时（已跨边界）

Step 6 — 按需加载：加载选取方法所需的 references（同原第二层）

各方法执行流程

小六壬

1. 使用 Step 0/5.5 已校正的农历月日时（或接受用户报数）
2. 执行掌诀推算：月→日→时三步定位
3. 读取 references/xiao-liuren/liugong.md 获取落宫断语
4. 可选：调用 scripts/xiao_liuren.py 明确传入 -m -d -t 参数（而非 --auto）

六爻

1. 模拟铜钱摇卦六次（随机 3 bit × 6），或直接调用 scripts/liuyao_yaogua.py --json
2. 确定本卦 → 装卦（纳甲+六亲+世应+六神；日干支使用已冻结快照中的值）
3. 读取 references/liuyao/najia.md 获取纳甲表
4. 读取 references/core/liuqin.md 获取六亲定义
5. 读取 references/liuyao/duangua.md 执行断卦规则
6. 综合五行生克 + 六兽 + 时间应期 → 输出解读

梅花易数

1. 确定起卦方式（时间法/报数法/物象法）
2. 若用时间法：使用已校正的真太阳时年支+月+日+时计算上卦、下卦、动爻
3. 读取 references/core/bagua.md 获取八卦对照表
4. 确定体卦、用卦、互卦、变卦
5. 体用五行生克判断 + 卦辞引用 → 输出解读
6. 可选：调用 scripts/meihua_qigua.py 明确传入参数

大六壬

1. 确定月将（按节气）+ 时辰（使用已校正的真太阳时时辰）
2. 构建天地盘矩阵
3. 确定四课
4. 按九大法则发传（读取 references/da-liuren/sanzhuan-faze.md）
5. 天将布局（读取 references/da-liuren/shier-tianjiang.md）
6. 综合断课 → 输出事态三阶段

基础知识加载策略

references/core/ 中的文件按实际需要加载，不一次性全部读取：

• 涉及天干地支计算 → 读 core/tiangan-dizhi.md
• 涉及五行生克 → 读 core/yinyang-wuxing.md
• 涉及八卦/六十四卦 → 读 core/bagua.md
• 涉及六亲/用神 → 读 core/liuqin.md

输出规范

所有占卜结果应包含以下元素：

1. 时间标注：显示冻结时间、地点、真太阳时校正信息

   text

   ⏱ 起卦时间：2026-05-29 15:22（北京时间）
   📍 成都（104.06°E）真太阳时：14:21（−61 分钟）
   🕐 时辰：未时
   

2. 方法说明：标注使用的占卜方法及依据

3. 免责声明（末尾必加）：

   占卜结果仅供参考，请结合实际情况理性判断。

脚本使用指南

scripts/ 目录提供可独立调用的 Python 脚本（依赖 zhdate 库，需在 venv 中运行）。

时间锚定（最先调用）：

bash

# 冻结时间 + 成都真太阳时
python scripts/common.py --snapshot --city 成都
# 仅冻结时间，不校准时区
python scripts/common.py --snapshot

占卜脚本：

脚本	功能	推荐调用方式（已校正）	Python 直接调用（agent 复用）
common.py	干支/五行/农历/月将 + 真太阳时校正 + 城市坐标查询	--snapshot --city 成都	common.get_current_lunar_info(dt=frozen, longitude=104.06)
xiao_liuren.py	小六壬掌诀推算	-m {lunar_month} -d {lunar_day} -t {corrected_hour}	xiao_liuren.by_month_day_hour(month, day, hour_idx)
liuyao_yaogua.py	六爻摇卦 + 纳甲装卦	--json --day-tg {snapshot.day_tg} --day-dz {snapshot.day_dz}	liuyao_yaogua.<主函数>（见 pitfalls.md）
meihua_qigua.py	梅花易数起卦	-d {solar_date} -t {corrected_hour}	meihua_qigua.by_time(...) 或 by_numbers(...)
da_liuren.py	大六壬天地盘 + 四课三传	-d {solar_date} -t {corrected_hour}	da_liuren.build_tiandi_pan(...)、build_sike(...)、fa_sanzhuan(...)

重要：占卜脚本的 --auto 模式始终使用 datetime.now()，不会取已冻结的快照。 在 SKILL 工作流中，应从 Step 0 的快照中提取已校正的参数，显式传递给脚本。

所有脚本的农历转换基于 zhdate 库；月将按节气判定；日干支自动推算。安装依赖：

bash

pip install -r requirements.txt

唯一外部依赖为 zhdate（PyPI 包），其余均为 Python 标准库，无系统工具依赖。可 zip 打包后在其他设备直接导入使用。

故障排查与真实 API 入口

• references/comprehensive-divination-skill-pitfalls.md — 安装踩坑、venv 引导、每个脚本的真实公开 API 入口与签名、断卦常见误区、与 references/router/matching-matrix.md 配合使用。

扩展指南

新增术种（如奇门遁甲）时：

1. 在 references/ 下新增子目录（如 qimen-dunjia/）
2. 在 scripts/ 下新增计算脚本
3. 更新本 SKILL.md 的触发关键词和路由逻辑
4. 更新 references/router/matching-matrix.md 的评分矩阵