紫微斗数（OpenClaw / zwds 技能）

何时使用

用户需要紫微斗数结构化命盘（十二宫、主星、四化、流年年龄列表等），或在此基础上解盘、论命时启用本技能。

硬禁止

• 不得在运行环境中 pip install py-iztro 或依赖 pythonmonkey。
• 不得用 Python 直接调用 iztro。
• 不得依赖外部在线排盘 API、地理编码服务或远程数据库；经度仅来自本技能自带的 zwds-cli/data/longitudes.json 或用户提供的 longitude。

标准排盘：须使用本目录下的 zwds-cli（内置真太阳时、time_index 映射及统一 JSON 输出，见下文 shell 契约）。

直接调用 iztro npm 库：仅当你要写额外 Node 脚本（例如按官方文档试验 horoscope、流耀 API）时使用；见下文「iztro 官方文档与库用法」。跳过 CLI 时不会自动套用 zwds-cli 内的时辰与真太阳时规则，产盘可能与标准流程不一致。

环境前置

1. 安装 Node.js >= 18。

2. 在仓库中进入：

   openclaw-skill/zwds/zwds-cli

3. 安装依赖：

   npm ci

   若失败可改用 npm install，并检查网络、registry、文件权限。

Shell 契约（避免「虚构工具名」）

• 工作目录：openclaw-skill/zwds/zwds-cli

• 命令：

  node src/index.js

• 标准输入：一段 JSON（可多行，解析前会 trim）。

• 标准输出：单行 JSON。先解析 success；为 true 时使用 data 解盘，为 false 时读取 error。

示例：

cd openclaw-skill/zwds/zwds-cli
echo '{"birth_time":"2000-08-16T06:00:00","gender":"female","birth_place":"上海市"}' | node src/index.js

不要将排盘封装为平台未注册的「工具名」；统一用上述 终端 + stdin/stdout 方式（或平台等价的进程调用）。

iztro 官方文档与库用法（给 Agent 的 API 速查）

完整说明、类型定义、运限与流耀细节见官方文档：iztro 快速开始（紫微研习社 / ziwei.pro）。以下摘录排盘最常用的调用面，便于在 Node 中与文档对照。

安装与引入

npm install iztro

// CommonJS（与 zwds-cli 一致）
const { astro } = require("iztro");

// ES Module
// import { astro } from "iztro";

取本命盘：astro.bySolar

const astrolabe = astro.bySolar(solarDateStr, timeIndex, gender, fixLeap, language);

农历入口为 astro.byLunar(lunarDateStr, timeIndex, gender, isLeapMonth?, fixLeap?, language?)，内部会换算阳历后再排盘（见快速开始）。

返回值为星盘对象：含 solarDate、lunarDate、chineseDate、time、palaces（十二宫数组，每宫含 majorStars / minorStars / adjectiveStars 等）。字段名为 camelCase；zwds-cli 对外 JSON 转为 snake_case，便于解盘阶段阅读。

取运限：astrolabe.horoscope

const h = astrolabe.horoscope("2023-8-28"); // 或 new Date()
// h.decadal / h.yearly / h.monthly / h.daily / h.hourly
// 各层含 palaceNames、mutagen、天干地支等（结构以官方文档为准）

第二参数可传 timeIndex；若 date 中带小时，可省略 timeIndex（见文档）。

流耀（进阶）

大限/流年流耀一般在 horoscope() 返回结构里；单独按干支取流耀可用 star.getHoroscopeStar（见快速开始 中「获取流耀」一节）。

const { star } = require("iztro");
// star.getHoroscopeStar(heavenlyStem, earthlyBranch, "decadal" | "yearly")

与 zwds-cli 的分工（重要）

两阶段工作流

1. 阶段 A — 排盘：仅运行 CLI，得到 data（命盘 JSON）。不要在此阶段长篇解盘。
2. 阶段 B — 解盘：仅基于 data 与用户需求做分析；不要重新臆造宫位或星曜。解盘方法与约束见下一节。

固定存档（可选）：若同一命盘会多次解读，可将「入参 + CLI 完整输出」存为 fixtures/*.json（在 zwds-cli 下执行 npm run save-fixture，见 examples.md）。之后对话直接 @ 该文件即可，无需每次重跑排盘；读盘仍只使用其中的 data（及 meta 告警），_fixture 仅说明该盘对应的生辰与地点。

阶段 B — 解盘（必读约束）

数据来源与诚实性

• 唯一事实来源：success === true 时响应里的 data。meta 仅用于判断经度是否降级、是否缺出生地等，不参与星曜判断。
• 逐字引用：提到的宫位名、主星/辅星/杂曜名、四化（禄权科忌）、亮度（庙旺利陷等）必须能在对应宫位的 major_stars / minor_stars / adjective_stars 的 name、mutagen、brightness 中找到；禁止凭记忆往盘里加星或改宫。
• 若用户问的内容在 data 里没有对应字段（例如未提供额外流月流日 API），应说明「当前 JSON 未包含该层运限」，不要编造。

建议阅读顺序（本命盘）

1. birth_info：确认阳历、农历四柱摘要、time/time_range、性别；若有 true_solar_time，解盘开头可一句说明「已按出生地经度做了简化真太阳时校正」。
2. five_elements_class（五行局） 与 soul_palace / body_palace（命身）：命宫主星见 soul_palace.soul，身宫地支见 body_palace；再在 palaces 里找到 name === "命宫" 的那一项，读取其 major_stars（可能多主星或空宫借星，以数组为准）。
3. 十二宫：对 palaces 逐项查看 name、heavenly_stem、earthly_branch、三类星曜列表、长生十二神等字段。
4. 四化：只认各星对象上的 mutagen 非空值；无则该星在所列层级未标四化。
5. 大限：每宫有 decadal.range（起止虚岁）与干支；论「当前大限」时需用户告知年龄或年份，再在对应宫找到覆盖该年龄区间的 decadal。
6. 流年：每宫有 yearly（年龄列表：age = 目标阳历年 − 出生公历年，且在该年 **Y-02-04（立春当日）锚点**下，本命该宫为 iztro 的流年命宫 horoscope('Y-2-4').yearly.index）。禁止用 yearly.palaceNames[i] 与本命 palaces[i] 下标对齐推断流年宫（二者顺序不一致）。当前 JSON 采用立春当日口径，不细分立春具体交接时刻。

三方四正（简则）

• 本命盘上：本宫索引 i，对宫为 (i+6)%12，财帛位 (i+4)%12，官禄位 (i+8)%12（本技能内三方四正取宫规则）。
• 解某一宫时：除读本宫外，应结合上述三宫的星曜与四化作综合叙述，且每一处论断仍须指向具体宫位条目中的星曜数据。

同气为大（内化判断，非固定输出标题）

紫微斗数实务中常讲「同气为大」：同一类意象的星曜若在本宫与三方四正（本宫 + 对宫 + 财帛位 + 官禄位，共四宫）内多处会齐，则该意象的能量被放大（常见表述为「一加一大于二」）。解盘时先在分析过程中内化判断，仍须逐颗能对应 JSON 的 name，不得凭空加星。

输出上不要求每次读盘都单独开章节讲解「同气为大」理论；当且仅当某类星曜在四宫内确实会齐、叠加明显时，在该宫本段总结、Step 2 整盘定性或文末要点里用短句自然点破即可，例如：桃花旺、财星旺 / 财机足、贵人运厚、煞气偏重、空劫感重、文书口舌偏重等。不必反复贴标签；全盘若多宫同显，可在 Step 2 或文末合并点一两句，避免十二宫各抄一遍。

本技能内常用「同气」分类（仅作归类标签，星名以 JSON 为准）：

用法规则：

1. 检索范围：只统计上述四宫内出现的星曜；推论前在内心完成归类即可，不必为证明同气而额外列一张「分类清单表」。
2. 叠加则写入总结：若同一类在四方会到 2 颗及以上（如桃花：红鸾、咸池、天姚等会齐），在总结句里用口语点破（如「这条线桃花很旺」）；若再加贪狼、廉贞等桃花主星，可加重一档（如「桃花非常旺」）。仍避免「必定出轨」等无法从盘证实的道德定罪式断言。
3. 煞 + 空劫：煞与空劫在三方四正会齐时，总结里可写「煞气偏重」「波折损耗感强」等；若用户需要核对，再补一句星名与宫位即可。
4. 昌曲魁钺辅弼会齐：总结里可写「贵人厚」「利文书考试口碑」等；不必先讲理论名词。
5. 与「输出边界」的关系：同气成立时，总结语气可比泛泛「倾向」更肯定；禁止无星曜依据的恐吓、诅咒式断语，以及与人身、法律后果挂钩的绝对断言。

按用户问题映射宫位（常见）

用户若明确指定宫位名称，以用户指定为准，但仍只在 data.palaces 中查找该 name 对应的项。

输出风格与边界

• 先简要列出依据（宫位 + 星曜 + 四化原文），再作推论；默认避免无依据的绝对化断语（不说死、不吓人）。读盘时按「同气为大」一节内化判断；若同类星在四宫会齐、叠加明显，在总结里自然写出（如桃花旺、财星旺、煞气偏重），不必先解释「什么叫同气为大」；仍须遵守该节禁止项。
• 推论用语要接地气：像跟熟人聊天那样说清楚「会怎样、为啥、咋办」，少用公文腔、套话、空洞词（如滥用「赋能」「闭环」「抓手」「需注重提升」等）。可用口语、短句、打比方，但不得因口语化而省略可核对的星曜依据，也不得用俏皮话掩盖说不清依据的结论。
• 若用户明确嫌「太官方」「不接地气」，解盘时白话推论占比应提高；「依据」段仍可偏简练，保持星曜名与亮度、四化与 JSON 一致。
• 若用户要求「详细解读」或未限制范围，默认给出十二宫逐宫详解；每宫至少包含：
  1. 宫位基础信息（name、地支、是否身宫/来因宫）；
  2. 星曜依据（主星、辅星、杂曜、可见四化与亮度）；
  3. 该宫主题下的倾向与建议（明确区分「依据」与「推论」）。
• 逐宫详解时，建议按 palaces 数组顺序输出（夫妻→兄弟→命宫...），并在每宫结尾用一句话收束「该宫重点」。
• 当用户要求「进一步细化」或明确提到「三方四正」时，逐宫解读必须升级为三方四正联读：
  1. 先给本宫依据；
  2. 再补对宫 (i+6)%12、财帛位 (i+4)%12、官禄位 (i+8)%12 的关键星曜与四化；
  3. 最后给综合推论，说明三方四正如何共同影响该宫主题。
• 三方四正联读时，禁止只给抽象结论；每条结论都应能回溯到本宫或三方四正宫位中的具体星曜字段。
• 若 meta.warnings 非空或 longitude_resolution.source === "default"，应在解盘前或文末提醒：出生地经度可能为默认 120°，时辰与真太阳时仅供参考。
• 流派差异（如晚子时换日、中州派安星）与本 CLI 默认（全书系、早子映射）不一致时，应主动说明「本盘按技能约定规则排定」，避免与用户从其他渠道看到的盘硬争对错。

标准化展示模板（Step 1～Step 5）

当用户明确要求「按固定模板展示」「完整版」「像示例那样输出」时，按以下结构输出；除非用户要求缩略，否则不得跳步：

1. Step 1：信息采集
   • 1.1 基础信息 表格：性别、出生日期、农历、生肖、五行局、命宫/身宫摘要、真太阳时（若无则写 null 或「未提供」）。
   • 1.2 命宫与身宫 表格：宫位、地支、主星、关键辅煞。
   • 1.3 生年四化 表格：禄/权/科/忌 + 对应星曜 + 所在宫位（仅列 JSON 中存在的 mutagen）。
   • 1.4 当前状态 表格：当前年龄、当前大限、大限命宫落点（按 decadal.range 反查）。
2. Step 2：整盘定性（100字内）
   • 用 60～100 字先给总判断，至少点名 1 个核心优势 + 1 个核心风险 + 1 个阶段结论；若全盘某类「同气」特别集中，可在此顺带用短词点出（如桃花旺、财星旺），不展开理论。
3. Step 3：分宫详解（含三方四正）
   • 必须覆盖 12 宫，建议按 palaces 顺序。
   • 每宫固定小结构：
     • 本宫分析（约50%）：主星/辅星/杂曜/四化与亮度。
     • 三方四正分析（约50%）：对宫、财帛位、官禄位的关键星曜与四化。
     • 本宫总结：1～3 句白话结论；若该宫三方四正内某类同气明显，在此总结中顺带点出（如桃花旺、魁钺厚、煞偏重），不要单独再设「同气为大」小标题。
4. Step 4：大运流年
   • 用表格列出关键大限（至少覆盖当前大限、上一限、下一限）。
   • 若用户问到年份，用 age = 目标年 − 出生年 查哪一宫 yearly 含该 age（与 CLI 的 **Y-02-04（立春当日）锚点**一致）；若 JSON 无更细层级，不得扩展编造流月/流日。
5. Step 5：落地建议
   • 至少给 4 类建议：感情、事业、财务、健康。
   • 每类用「诊断/建议」或「建议/具体行动」二列表格，确保可执行。

组合与评分规则（可选展示）

• 全盘若桃花、财星、煞气等同气特别突出，可在 Step 2 或 文末用两三词收束（如「全盘桃花偏旺」「财机足但要防煞」）；与下表评分可二选一或合并，均非 iztro 官方字段。
• 允许展示「组合识别」「能量评分」，但必须声明：这是解读辅助标尺，非 iztro 官方字段。
• 组合中的每颗星都必须能在本宫或三方四正四宫内被检索到；禁止跨宫乱拼。
• 若输出分数，需给出统一口径（例如：本宫占 50%，三方四正占 50%），并在文末注明「仅作相对参考」。
• 不得把分数写成绝对命运结论（如“必离婚”“注定失败”）。

输入与精度说明

• birth_time 使用 ISO 字符串中的字面年月日时分参与时辰划分（不按时区把同一时刻换算成另一套钟表时间）；请确保与用户约定好字符串写法与时区含义。
• 有 birth_place 时：经度来自内置表或用户提供的 longitude；表外地名会退回东经 120° 并在 meta.warnings 中提示。
• 真太阳时为 简化模型：1986–1991 年中国夏令时 + 相对东八区 120° 的经度修正，不含均时差。

更细的规则与字段说明见同目录 reference.md；示例见 examples.md。