紫微斗数排盘解盘

通过 zwds-cli（Node、iztro 2.5.0）生成紫微斗数结构化命盘 JSON，并仅依据该 JSON 解盘。在用户提及紫微斗数、排盘、命盘、十二宫、四化、解盘、生辰八字时辰、命宫、大限、流年时使用。含 iztro 官方 API 速查；禁止 py-iztro 与脱离 JSON 臆造星曜。真太阳时与地名规...

Security Scan

The skill's files, instructions, and requirements are internally consistent with its stated purpose of producing and interpreting zwds (iztro) JSON charts; there are no unexplained credential requests or hidden network callbacks in normal use, though optional maintainer scripts will perform network fetches if run.

Purpose & Capability

The name/description say the skill wraps a Node-based zwds-cli (iztro@2.5.0) to produce structured 紫微斗数 JSON and then have the agent only rely on that JSON to interpret charts. The repo actually contains a CLI (src/index.js + iztroClient) and local longitude data used to compute a simplified true-solar-time. The declared surface (no env vars, no external credentials) matches what the code needs: Node and the iztro npm package. There are no unrelated credential or binary requirements.

Instruction Scope

SKILL.md gives narrow, explicit runtime instructions: install Node >=18, run npm ci, run node src/index.js with JSON on stdin, and perform Stage A (generate data) and Stage B (interpret only the returned data). The README and SKILL.md explicitly forbid calling external geocoding services at runtime and forbid using py-iztro. The runtime CLI code reads only local files and calls iztro; it does not exfiltrate environment variables or reach out over network during normal CLI operation.

Install Mechanism

There is no automatic install spec in the skill bundle (instruction-only). The project relies on standard npm installation (npm ci / npm install) to fetch iztro and its deps — expected for a Node CLI. A maintainer script (scripts/build-longitudes.mjs) will fetch many remote URLs (raw.githubusercontent.com and geo.datav.aliyun.com) if a user explicitly runs npm run generate-longitudes; this is an optional, networked maintenance step and not performed by the CLI itself. If you avoid running that script, the CLI uses the included local longitudes.json. Running npm ci will contact the npm registry to download packages (normal for Node projects).

Credentials

The skill requests no environment variables, no secret tokens, and declares no config paths. All data inputs come from stdin JSON or the included data/longitudes.json; the only external dependencies are normal npm packages (iztro and its deps). No unexpected credentials are required.

Persistence & Privilege

The skill is not forced-always, does not request elevated platform privileges, and will not automatically persist credentials or modify other skills. It can write fixtures (scripts/save-fixture.mjs) into its own fixtures/ directory when explicitly invoked — an expected, limited local persistence behavior.

Assessment

This package is internally consistent for the stated purpose — it wraps iztro to produce a standardized JSON chart and provides strict rules for how the agent must base interpretations on that JSON. Before installing, consider: 1) npm ci will download iztro and its dependencies from the npm registry (verify iztro@2.5.0 if you need to audit it). 2) Do not run npm run generate-longitudes unless you trust outbound HTTPS calls to raw.githubusercontent.com and geo.datav.aliyun.com (that script fetches many remote files and writes data/longitudes.json). 3) The CLI itself does not contact remote services at runtime; it reads local longitudes.json and the iztro library runs locally. 4) If you plan autonomous agent invocation in a sensitive environment, note the agent could run node and the save-fixture script which write files locally — run in an isolated/filtered environment if needed. If you want higher assurance, audit the iztro npm package and the included scripts (build-longitudes.mjs, save-fixture.mjs) before use.

紫微斗数（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);

参数	类型	必填	说明
solarDateStr	string	是	阳历 YYYY-M-D（月日可不补零，如 2000-8-16）
timeIndex	number	是	时辰序号 0～12（早子 0 到晚子 12，含义以官方文档为准）
gender	string	是	男 或 女
fixLeap	boolean	否	默认 true；闰月前半月算上月、后半月算下月
language	string	否	默认 zh-CN；另有 zh-TW、en-US、ko-KR、ja-JP 等

农历入口为 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 的分工（重要）

方式	何时用
zwds-cli	需要统一排盘流程、或解盘所依据的 JSON 须带 birth_info.true_solar_time / meta 等本技能约定字段时。
直接 astro.bySolar	阅读官方示例、写独立小工具、或需要链式 API（如 astrolabe.star("紫微")...）时；若要与 zwds-cli 同一套时辰与真太阳时，应复用其 solarTime.js / timeIndex.js 或继续调用 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 为准）：

同气类别	常见星曜（出现即用，未出现勿套用）
桃花	贪狼、廉贞、天姚、咸池、红鸾、天喜等（以盘中实际 name 为准）
财星 / 禄气	武曲、天府、太阴（财象时）、禄存；及带 mutagen 为禄之化禄星
贵人 / 文星（吉星组）	左辅、右弼、天魁、天钺、文昌、文曲
煞星	擎羊、陀罗、火星、铃星
空劫	地空、地劫
刚克 / 变动	七杀、破军（论宫主题时再与煞、空劫叠加看力度）

用法规则：

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

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

用户意图（示例）	优先对照宫位（palaces[].name）
性格、自我、人生基调	命宫；可参身宫所在宫
财运、收入、理财	财帛；可参福德、田宅
事业、学业、社会成就	官禄；可参命宫、财帛
感情、配偶	夫妻；可参福德、迁移
家庭、父母、长辈	父母；可参田宅
子女、生育、晚辈	子女
健康、体质	疾厄
人际、同事、下属	仆役
外出、搬迁、外部环境	迁移
精神状态、嗜好、福气	福德
不动产、家庭资产	田宅
兄弟、同辈	兄弟

用户若明确指定宫位名称，以用户指定为准，但仍只在 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。