紫微 AI 离线 HTML 报告（整合 Skill）

Overview

本 skill 将本仓库内已验证的排盘规则、提示词与命盘上下文格式交给任意 agent：可从阳历出生资料生成命盘上下文，再输出单个 HTML 文件，含「综合批注 / 流年运势 / 人生 K 线」三节。

排盘策略（建议优先：无 Node + 真太阳时）

| 路径 | 命令要点 | 依赖 | 真太阳时 | |------|-----------|------|----------| | A. 纯 Python（默认推荐） | python3 tools/ziwei_offline.py --solar ... --time ... --gender ... [--birthplace ...] | 仅 Python 3，无 Node / npm | 默认开启：有经纬度/可解析 birthplace 时按经度+时间方程换算后再定农历与时辰；--disable-true-solar-time 可关 | | B. iztro 对齐 App 星曜 | 先 Python 输出「真太阳时后的阳历时分」，再喂 iztro，再拼上下文（见下） | 本目录 npm install + Node.js | 可一致：用 --emit-iztro-birth-json 把真太阳时口径注入 iztro | | C. iztro 仅钟表（与 App 输入框一致） | IZTRO_MODE=raw-clock 或直连 chart_iztro.cjs --solar --time | Node + npm | 否（与用户在 App 里只填钟表时间相同） |

结论：希望脱离 Node → 只用 路径 A（已含真太阳时）。希望主星与 App/iztro 一致且仍要真太阳时 → 用 路径 B（离不开 Node，因 iztro 为 JS 库），无法用「零依赖静态文件」替代。

路径 B 一键（环境变量；需已 npm install）：

cd skills/ziwei-ai-html-report
SOLAR={{SOLAR_DATE}} TIME={{BIRTH_TIME}} GENDER={{GENDER}} BIRTHPLACE="{{BIRTHPLACE}}" TARGET_YEAR={{TARGET_YEAR}} ./tools/report_payload_iztro.sh

路径 B 分步（真太阳 → iztro → 上下文）：

python3 tools/ziwei_offline.py --solar {{SOLAR_DATE}} --time {{BIRTH_TIME}} --gender {{GENDER}} \
  --birthplace "{{BIRTHPLACE}}" --target-year {{TARGET_YEAR}} --emit-iztro-birth-json \
  | node tools/chart_iztro.cjs --birth-json - \
  | python3 tools/ziwei_offline.py --from-chart-json --target-year {{TARGET_YEAR}} --format json

--emit-iztro-birth-json 输出一行 JSON（solarDate、time、gender、trueSolarApplied），chart_iztro.cjs --birth-json - 从 stdin 读取；Python 再补齐 patterns、校验与三份 Context。

路径 C（无真太阳、纯钟表 iztro）：IZTRO_MODE=raw-clock ./tools/report_payload_iztro.sh -- ... 或旧式 node chart_iztro.cjs --solar ... | python3 ... --from-chart-json。

纯 Python：tools/ziwei_offline.py（标准库）。阳历范围 1900-01-31 至 2100-12-31。路径 A 为安星自研实现，与 iztro 在个别命盘上可能仍有差异；以 iztro 为准请用路径 B/C。

核心约束：违反字面即违反本意——不可因「节省时间」「用户急了」跳过输入校验或免责声明。

示例值防污染：所有命令中的 {{SOLAR_DATE}}、{{BIRTH_TIME}}、{{GENDER}}、{{BIRTHPLACE}}、{{TARGET_YEAR}} 都必须替换为用户本轮提供或确认过的值。不得把文档示例、README 示例或历史对话中的出生信息当作默认输入；运行排盘前先回显解析到的出生资料。

完整提示词与模板见同目录：prompts.md。HTML 样板见：report-template.html。

运行前提（简化）

本 skill 运行在 agent 环境中，默认已有模型参与解读生成。
因此本文档聚焦于：离线排盘事实、提示词结构、HTML 交付一致性，不重复展开模型可用性说明。

When to Use

需要在任意聊天模型 / agent 环境中输出离线可打开的命理报告；
用户只提供阳历生日、出生小时、性别、分析年份，且无法或不愿安装额外运行时依赖；
用户已粘贴本命 AI 上下文（及流年块，若做流年节），希望直接组装报告；
交付物必须是单文件 HTML（便于保存、邮件、网盘分享）。

When NOT to Use

用户生日超出 1900-2100 且无法提供农历/命盘上下文——当前离线历法表无法覆盖；
仅需合盘：当前发布版不内置合盘节；若需要，请在本目录内新增独立提示词节；
只想在现成产品 UI 内查看，而非交付离线 HTML。

输入契约（必填 / 可选用）

A. 出生资料（首选，可独立排盘）

最小输入：

| 字段 | 说明 | |------|------| | 阳历日期 | YYYY-MM-DD，范围 1900-01-31 至 2100-12-31 | | 出生时间 | HH:mm（推荐）或 hour(0-23)；23:00-23:59 按晚子时换日 | | 性别 | male/female 或男/女 | | 出生地 | 可选；用于真太阳时换算，默认 hybrid 模式下优先在线地理编码，失败回退内置城市表 | | 流年分析年 | 可选，默认当前年 |

年龄口径：大限与流年叠宫使用虚岁（分析年 − 农历生年 + 1）。报告页眉与流年上下文会同时标注周岁（截至分析年 12 月 31 日，以及截至生成日若与年末不同）。

运行工具生成上下文：

python3 tools/ziwei_offline.py \
  --solar {{SOLAR_DATE}} \
  --time {{BIRTH_TIME}} \
  --gender {{GENDER}} \
  --birthplace "{{BIRTHPLACE}}" \
  --target-year {{TARGET_YEAR}} \
  --format json

输出 JSON 含：

| 字段 | 用途 | |------|------| | chart | 离线命盘结构化数据 | | natalContext | 综合批注用户上下文 | | yearlyContext | 流年运势用户上下文 | | klineData | 确定性人生 K 线数据，直接嵌入 HTML | | klineContext | K 线文字解读上下文；不得作为数值走势来源 |

输入模板（展示层；必须替换为用户本轮提供或确认过的值）：

阳历生日：YYYY-MM-DD
农历生日：可不填（系统自动计算）
出生时间：HH:mm
性别：男/女
出生地：省市区或经纬度

对应机器字段：

solar={{SOLAR_DATE}}
time={{BIRTH_TIME}}（或 hour={{BIRTH_HOUR}}）
gender={{GENDER}}
birthplace={{BIRTHPLACE}}
targetYear={{TARGET_YEAR}}（可选）

B. 本命上下文（备选）

在本 skill 的中州派规则下，以下内容之一视为有效本命输入：

首选：与本工具 build_prompt_context 输出等价的 Markdown 文本（以 【命盘完整信息】 开头，含 ## 十二宫星曜分布、## 十二大限、按需含 ## 近年流年信息 等）。
备选：结构化 JSON（可还原为同上 Markdown）。最小字段映射：

| 字段 | 含义 | |------|------| | 命宫主星 | { name, group?, description? }[]，至少 name | | 身宫主星 | 同上 | | 身宫位置 | 宫位名字符串 | | 十二宫 | { name, stem, majorStars[], minorStars[], adjectiveStars?, isBodyPalace?, decadalRange? }[] | | 大限 | { palaceName, ageRange, stem, mutagens[] }[] | | 流年 | { year, stem, branch, mutagens[], palaceName }[]（可为空数组） | | 四化分布 | { star, sihua: { name, effect }, palace }[] | | 格局提示 | string[] |

若出生日期超出离线工具范围且无上述内容：停止生成断语，请用户补充可靠上下文，或输出仅含「信息不足说明」的 HTML（不得编造星曜）。

流年节（若 HTML 含「年度运势」）

若使用离线工具，直接使用输出的 yearlyContext。若用户提供上下文，则除本命上下文外，还须 【流年盘信息】 块：流年干支、流年四化、流年命宫；当前大限干支与四化；重点宫位星曜。禁止仅靠公历年份自行臆造叠宫。

K 线节

默认使用离线工具输出的 klineData 作为数值来源，直接填入 report-template.html 中 #kline-data。klineContext 只用于生成 reason/brief 等文字补充，不得让模型自由决定 open/high/low/close。

数值口径（示意分，峰值稀缺）：tools/ziwei_offline.py 先计算 1-100 岁 raw score，再做全生命相对映射；收盘上限约 98、最高可到 100（常量 KLINE_CLOSE_CAP / KLINE_HIGH_CAP），允许少数最强年份接近满分，但应避免长段贴顶。校验允许 ∈ [0,100]。

路径 A 亮度：纯 Python 排盘会为主星写入 庙/旺/得/利/平/不/陷 亮度（对齐 iztro STARS_INFO），并用于 K 线评分与 HTML 排盘图展示。路径 B 仍可用于 App/iztro 对齐验证。

每条 klineData 含：age/year/ganZhi/daYun/daYunRange、OHLC、score、dimensions（事业/财/情/健）、yearlyMutagens；合并 kline-brief.json 后可加 brief、可选 reason。

报告页交互：report-template.html 在 K 线图下提供悬停详情与可展开的 1–100 岁数值表；用户无需另查 JSON 即可看每年数字与简评。流年长文仍在「年度流年运势」节。

产品对齐（历法与派别）

与本目录规则基线一致（见 docs/rules-baseline.md）：中州派、正月初一分年/运限、23:00 晚子时换日。不得在未说明的情况下改用立春或其它流派。

时间口径：

默认固定 UTC+8（不回溯历史夏令时）；
若提供经纬度或可解析出生地，将使用真太阳时：标准时 + 经度修正 + 时间方程；
CLI 默认 --geocode-mode hybrid：在线优先，失败回退 tools/cn_locations.json，再失败则回退标准时；
若需完全离线，可显式传 --geocode-mode offline；若需可复现坐标，优先传 --longitude/--latitude；
若缺少可用经纬度，则回退标准时并在输出中给出提示。

离线工具内置：

1900-2100 阳历转农历压缩表；
命宫/身宫、十二宫、五虎遁宫干、五行局；
紫微/天府与十四主星；
左辅右弼、文昌文曲、魁钺、禄存羊陀、火铃、空劫；
生年四化、大限、目标流年上下文。

当前有意保守：

不依赖外部排盘库的亮度体系，输出中亮度可为空；
不宣称与任何商业排盘工具 100% 一致，除非后续用样例逐条对齐。

执行步骤（agent）

校验输入：若有出生资料，先运行 tools/ziwei_offline.py 生成 JSON；若已有上下文，确认存在 natalContext 等价文本与 yearlyContext。
排盘自检：确认 JSON 含 chart.palaces 12 宫、fiveElementsClass、natalContext、yearlyContext、klineContext、klineData。
渲染提示词（推荐）：运行 tools/render_prompts.py --payload-json payload.json --out-dir work --work-root work，读取 prompt-manifest.json；勿手抄 prompts.md，以渲染文件为唯一注入来源。
模型生成产物：
- natal.html：用 prompts/natal.system.md + natal.user.md；
- yearly.html：用 yearly.system.md + yearly.user.md；
- kline-brief.json：用 kline.system.md + kline.user.md，仅可返回 age/brief/reason，不得返回或改写 open/high/low/close。
K 线：数值必须使用离线工具输出的 klineData；如需文字说明，只能将模型生成的 brief/reason 合并到对应年龄。
K 线自检（修正前不得写入 HTML）：
- 恰 100 条，age 为 1–100 各出现一次；
- age===1 时 open === 50；
- 对 age>1：open 与上一条 close 在数值上一致（容差 1e-6，或两位小数相等）；
- high >= max(open,close)，low <= min(open,close)，且所有数值 ∈ [0,100]；满分附近应是少数高峰，勿人为改成长段顶格。
组装 HTML：使用 tools/generate_report.py 与 report-template.html 组装；正式交付禁止 --skip-validation。页面顺序固定：紫微排盘图 → 紫微命盘综合批注 → 流年运势 → 人生运势 K 线（含悬停/表格查每年 OHLC 与 brief）→ 数据完整性状态。将命盘 JSON 填入 script#chart-data，将综合/流年正文填入对应 #content-*，将合并后的 K 线 JSON 嵌入 script#kline-data；页脚保留与提示词等价的免责声明。
输出：向用户交付完整 <!DOCTYPE html> 文档（可复制为 .html 文件后直接双击打开）。

运行模式

模式 A：模型增强（推荐）

使用离线工具得到 natalContext/yearlyContext/klineData/klineContext；
用 render_prompts.py 生成 prompt 文件与 prompt-manifest.json；
得到综合批注、流年正文与可选 kline-brief.json 后，用 generate_report.py 组装 HTML；
K 线数值由工具生成并通过强校验；模型只可补充文字，不可改变走势数值。

Quick Reference

| 报告章节 | System 提示来源 | User 数据来源 | |---------|-----------------|---------------| | 排盘上下文 | tools/ziwei_offline.py | 阳历日期 + 小时 + 性别 + 分析年 | | 综合批注 | prompts.md 第 1 节 | natalContext | | 年度运势 | prompts.md 第 2 节 | natalContext + yearlyContext | | 人生 K 线 | 离线工具确定性评分 | klineData（数值）+ klineContext（文字参考） |

Baseline Pressure Scenarios（无 skill 时常见失效）

记录在案，用于自检 skill 是否被遵守：

| 场景 | 常见错误行为 | |------|----------------| | 仅有生日性别 | 不运行离线工具，直接写命宫主星与断语 | | 用户催促 | 跳过 K 线 JSON 连续性校验，或让模型替代确定性 K 线数值 | | 环境惯性 | 在仅需 Python 路径时仍强迫 npm install / iztro（路径 A 不要 Node） | | 交付形式 | 仅给 Markdown 片段，不给单文件 HTML | | 流派 | 自行改用立春换年 |

Red Flags — STOP & Realign

有出生资料却未运行 tools/ziwei_offline.py 就产出具体星曜落宫；
离线工具报错（日期超范围/输入缺失）仍继续断语；
K 线 open[n] ≠ close[n-1] 仍入库；
有 klineData 却改用模型自由生成 open/high/low/close；
删除或改写免责声明以「更好看」；
将 npm、iztro 或 Node 列为必选才能完成报告（默认可用纯 Python；iztro 仅在为对齐 App 星曜时可选）。

Rationalization Table

| 借口 | 事实 | |------|------| | 「差不多能推出命宫」 | 必须运行离线工具或读取可靠上下文 | | 「用户没空打开应用」 | 正是使用离线工具的场景 | | 「Markdown 对用户更方便」 | 本 skill 明确要求单文件 HTML | | 「测试后再校验 K 线」 | 必须先校验再写入模板 | | 「模型更懂走势」 | 模型只适合补充描述；数值走势必须来自确定性评分工具 | | 「描述性一句话即可代替免责声明」 | 必须保留提示词中与参考性、勿执着一致的表述 |

Common Mistakes

把 HTML 外的裸 JSON 当作最终交付物；
排盘：手写星曜落宫而不是运行 tools/ziwei_offline.py；
流年：缺大限锚点或 yearlyContext 却仍写叠宫；
K 线：优先嵌入工具输出的 klineData；year 字段若填入，应与 birthYear + age - 1 一致；
在 skill 正文重复粘贴全套 system prompt——应引用 prompts.md 以保持单一事实来源。