bazi-pillars-from-datetime

Use when a task involves deriving bazi chart data from Gregorian datetime and timezone, or generating a grounded user-language analysis from an existing chart JSON plus the local knowledge files.

vastaq@vastaq

Install

openclaw skills install @vastaq/bazi-pillars-from-datetime

八字排盘与分析

概览

这个 skill 现在包含两个明确模式，必须先判断当前任务属于哪一种：

chart 模式：把公历日期时间转换成可复现的八字排盘结果。
analysis 模式：基于已有盘面 JSON、用户问题和本地知识文件生成适配用户语言的分析。

不要把两种模式混用。排盘负责事实，分析负责表达与建议。

何时使用

使用 `chart` 模式

用户提供出生日期、时间、时区、地点，要求排盘、算四柱、看大运、看流年。
任务需要结构化 JSON 结果，供后续程序或分析环节消费。
需要稳定、可重复的计算结果，而不是自由发挥的解释。

使用 `analysis` 模式

已经有 chart 盘面 JSON，用户要求分析事业、婚恋、健康、整体趋势或指定年份。
任务需要生成面向用户的中文报告，而不是重新计算排盘。
需要引用 knowledge.md 的解释素材，并遵循 prompt.md 的输出结构。

使用顺序

如果用户同时要“排盘 + 分析”，先执行 chart，再把结果传给 analysis。
如果用户只给了 chart，不要重复排盘。
如果用户只给了生日信息但要分析，先排盘，再分析。

共享约束

排盘事实以 main.py 为准。
分析不得篡改盘面字段，不得臆造盘面中不存在的干支、岁运或结论。
不使用农历换算。
不输出宿命化、绝对化、恐吓式表达。
信息不足时，明确说明缺口和影响，不强行补全。
分析语言默认跟随用户；若未指定也无法判断，则默认使用简体中文。

模式一：`chart`

目标

输出一个确定性、可复现、可被程序消费的八字 JSON 合同。该模式不生成用户面向的自然语言分析。

输入合同

输入为 JSON，对应 main.py 从标准输入读取的 payload：

json

{
  "datetime": "YYYY-MM-DDTHH:MM:SS",
  "timezone": "IANA/Timezone",
  "location": {
    "name": "City/Region",
    "longitude": 0.0,
    "latitude": 0.0,
    "lookup_mode": "auto|local|online",
    "lookup_provider": "nominatim|amap|tencent",
    "lookup_key": "optional-api-key",
    "lookup_path": "/path/to/cities.json",
    "cache_path": "/path/to/city_cache.json",
    "lookup_timeout": 6
  },
  "gender": "female|male|other",
  "rules": {
    "year_boundary": "lichun",
    "month_rule": "solar_terms",
    "day_boundary": "00:00",
    "time_correction": "mean_solar_time",
    "require_dayun": false
  },
  "flows": {
    "datetime": "YYYY-MM-DDTHH:MM:SS",
    "timezone": "IANA/Timezone"
  },
  "mode": "strict"
}

必填字段

datetime：本地日期时间字符串，不带 offset。
timezone：IANA 时区，例如 Asia/Shanghai。

条件必填字段

location：当 time_correction 为 mean_solar_time 或 true_solar_time 时必填。
gender：当需要计算大运且 require_dayun=true 时必填。
flows.datetime：只有请求流年/流月/流日时才需要。

可选字段与默认值

rules.year_boundary 默认 lichun
rules.month_rule 默认 solar_terms
rules.day_boundary 默认 00:00
rules.time_correction 默认 mean_solar_time
rules.require_dayun 默认 false
mode 默认 strict
location.lookup_provider 默认 nominatim
location.lookup_path 默认 ./cities.json
location.cache_path 默认 ./city_cache.json
location.lookup_timeout 默认 6

地点解析规则

优先使用 longitude 和 latitude。
只有 name 时，按 lookup_mode 解析：
- local：仅查本地映射。
- online：仅查在线地理编码。
- auto：先本地，后在线。
amap 和 tencent 需要 lookup_key，也可走环境变量 BAZI_GEOCODE_KEY。
可通过环境变量覆盖默认路径和服务：
- BAZI_CITY_MAP_PATH
- BAZI_CITY_CACHE_PATH
- BAZI_GEOCODE_PROVIDER
- BAZI_GEOCODE_KEY
- BAZI_GEOCODE_TIMEOUT

固定计算规则

年界：立春
月界：按节气切月
日界：默认 00:00
时差修正：
- mean_solar_time：只做经度修正
- true_solar_time：经度修正 + 均时差
require_dayun：默认 false
日柱基准：1984-02-02 为 丙寅日
strict 模式下，缺少关键时间信息应直接报错

处理顺序

解析 datetime 与 timezone
根据 rules 决定是否做平太阳时或真太阳时修正
计算年柱、月柱、日柱、时柱
如请求大运，则根据性别与年干阴阳顺逆推算
如请求流转信息，则计算 flows
返回节气信息、元信息与置信度

成功输出

json

{
  "ok": true,
  "bazi": {
    "year": { "tg": "...", "dz": "..." },
    "month": { "tg": "...", "dz": "..." },
    "day": { "tg": "...", "dz": "..." },
    "hour": { "tg": "...", "dz": "..." }
  },
  "dayun": {
    "direction": "forward|backward",
    "start_age_years": 0.0,
    "start_age_months": 0.0,
    "start_datetime": "YYYY-MM-DDTHH:MM:SS",
    "cycles": [
      {
        "index": 1,
        "tg": "...",
        "dz": "...",
        "gz": "...",
        "start_age_years": 0.0,
        "start_datetime": "YYYY-MM-DDTHH:MM:SS",
        "end_datetime": "YYYY-MM-DDTHH:MM:SS"
      }
    ]
  },
  "flows": {
    "datetime": "YYYY-MM-DDTHH:MM:SS",
    "year": { "tg": "...", "dz": "...", "gz": "..." },
    "month": { "tg": "...", "dz": "...", "gz": "..." },
    "day": { "tg": "...", "dz": "...", "gz": "..." }
  },
  "solar_terms": {
    "prev": { "name": "...", "datetime": "..." },
    "next": { "name": "...", "datetime": "..." }
  },
  "meta": {
    "timezone": "IANA/Timezone",
    "rules_used": {
      "year_boundary": "lichun",
      "month_rule": "solar_terms",
      "day_boundary": "00:00",
      "time_correction": "mean_solar_time",
      "require_dayun": false
    },
    "true_solar_time": {
      "method": "mean_solar_time|true_solar_time",
      "datetime": "...",
      "delta_minutes": 0.0,
      "equation_of_time_minutes": 0.0,
      "longitude_correction_minutes": 0.0
    },
    "location": {
      "name": "...",
      "longitude": 0.0,
      "latitude": 0.0
    },
    "confidence": "high|medium|low",
    "notes": []
  }
}

失败输出

json

{
  "ok": false,
  "error": {
    "code": "INVALID_DATETIME|INVALID_TIMEZONE|INVALID_LOCATION|MISSING_DATE|MISSING_TIMEZONE|MISSING_LOCATION|MISSING_GENDER",
    "missing": ["date|time|timezone|location|gender"],
    "message": "Human-readable error for agent use"
  }
}

错误处理约定

MISSING_DATE：缺少 datetime
INVALID_DATETIME：日期时间格式不合法
MISSING_TIMEZONE：缺少 timezone
INVALID_TIMEZONE：时区无效
MISSING_LOCATION：需要地点但无法解析
MISSING_GENDER：请求大运时缺少性别

最低测试覆盖

立春前后跨年边界
节气切月边界
00:00 日界
同一 UTC 在不同时区对应不同本地日
缺地点时的报错路径
请求大运但缺性别时的报错路径

调用入口

入口文件：main.py

bash

echo '{"datetime":"1998-08-12T15:30:00","timezone":"Asia/Shanghai","location":{"name":"广州"},"rules":{"time_correction":"true_solar_time"}}' | python3 main.py

模式二：`analysis`

目标

基于盘面事实与本地知识库，生成可对话展示、语言跟随用户的分析报告。该模式不重新计算排盘，只消费已有 chart 数据。

必需输入

user_query：用户当前问题，可为简体中文或其他语言。
chart：由 main.py 产生的排盘 JSON。
knowledge：解释和建议素材，来源于 knowledge.md。

语言适配规则

语言选择优先级如下：

用户明确指定的输出语言
user_query 的主要语言
简体中文（默认）

补充约束：

若用户使用非中文提问，可按该语言输出，但核心术语如“十神”“天干”“地支”“大运”“流年”可保留中文并加简短解释。
若用户要求双语输出，可先给主语言版本，再附简短中文术语对照。
若用户未要求翻译，不要为了“国际化”主动输出双语。

事实来源优先级

chart
knowledge.md
用户问题中的补充条件

当知识库与盘面事实冲突时，以 chart 为准，并明确说明不确定性。

分析前检查

先识别用户问的是整体、事业、婚恋、健康、还是指定年份。
确认 chart 是否包含 dayun、flows、meta.confidence 等关键字段。
若缺少时辰、地点、性别或用户关注年份，要说明影响范围。

输出结构

输出使用 Markdown，并固定以下标题顺序：

盘面摘要
本次问题结论
时间轴（仅在用户询问年份或趋势时使用）
建议
依据与补充
可信度与缺失信息

每部分要求

1. 盘面摘要

四柱按年、月、日、时顺序展示。
大运写当前正在走的运；无法确定时写“当前大运不确定”。
流年仅在 chart.flows.year.gz 可用时展示，否则写“流年未指定”。

2. 本次问题结论

输出 3 到 6 条核心判断。
每条都尽量包含：现象、影响、建议。
结论必须围绕 user_query，不要泛泛而谈。

3. 时间轴

用户问未来趋势、具体年份、近三年变化时再输出。
可按今年、明年、后年逐年列重点。
若无对应流年数据，提示用户补年份。

4. 建议

输出 3 到 7 条动作化建议。
尽量区分“适合做什么”和“避免做什么”。
建议要现实、可执行，避免空泛玄学口号。

5. 依据与补充

只引用与当前盘面相关的知识点。
引用来源应对应 knowledge.md 的条目或章节。
引用尽量短，不超过 25 个字，可适度改写。
这里只提供解释依据，不新增结论。

6. 可信度与缺失信息

可信度优先使用 chart.meta.confidence。
明确指出缺失信息会影响哪些判断。
如需追问，只提最关键的一项或两项。

写作原则

输出语言与用户请求保持一致；无法判断时默认简体中文。
多用“倾向于”“可能”“建议”等词，避免绝对断言。
不做医学诊断、法律建议或恐吓式表达。
不堆砌术语，首次出现可顺手白话解释。

禁止事项

不凭空创造新的八字理论。
不脱离 chart 事实做判断。
不把知识库内容整段照搬。
不因为用户追问就伪造缺失的大运、流年或时柱。

参考文件

输出格式与分析任务要求：prompt.md
解释依据与建议素材：knowledge.md

模式切换与交接

排盘结果是分析输入，不是分析结论。
当同一请求同时包含出生信息和分析诉求时，先产出 chart，再基于 chart 输出分析。
分析阶段如果发现 chart 关键字段缺失，只说明限制，不在分析阶段偷偷补算。

快速判定

问“帮我排盘 / 算四柱 / 算大运” -> chart
问“帮我看看事业 / 婚恋 / 健康 / 今年运势”且已有盘面 -> analysis
问“这是我的生日，顺便分析一下” -> chart 然后 analysis

bazi-pillars-from-datetime

Install

八字排盘与分析

概览

何时使用

使用 chart 模式

使用 analysis 模式

使用顺序

共享约束

模式一：chart

目标

输入合同

必填字段

条件必填字段

可选字段与默认值

地点解析规则

固定计算规则

处理顺序

成功输出

失败输出

错误处理约定

最低测试覆盖

调用入口

模式二：analysis

目标

必需输入

语言适配规则

事实来源优先级

分析前检查

输出结构

每部分要求

1. 盘面摘要

2. 本次问题结论

3. 时间轴

4. 建议

5. 依据与补充

6. 可信度与缺失信息

写作原则

禁止事项

参考文件

模式切换与交接

快速判定

Related skills

使用 `chart` 模式

使用 `analysis` 模式

模式一：`chart`

模式二：`analysis`