astrology-core

一个面向 TypeScript/JavaScript 的、确定性且不包含命理解读的本命星盘计算核心。

它只回答可以通过时间、地点、天文坐标和明确规则计算的问题，例如行星黄经、星座位置、逆行、上升点、天顶、宫位和相位；不会生成性格、吉凶、运势或兼容度结论。

特性

• 太阳、月亮、水星至冥王星的地心视位置
• 热带黄道中的星座与度数
• 黄纬、距离、黄经日速度与逆行状态
• 统一的 ChartPoint 输出，覆盖行星、月交点、上升点与天顶
• 真、平均南北月交点及 Whole Sign 落宫
• Whole Sign 十二宫与行星落宫
• 行星之间以及行星与 ASC、MC 之间的五种主要相位，支持自定义容许度
• 输入时间强制带 UTC 偏移，避免运行环境时区造成不同结果
• 40 个独立星历对照盘，覆盖高纬度、南北半球、午夜、历史日期与行星停滞
• 结构化边界警告，包括高纬度、验证日期与纬度范围、行星停滞、星座边界与相位容许度边界
• 同时发布 ESM、CommonJS 和 TypeScript 类型声明
• 结果包含完整计算规则，不隐藏全局配置

安装

npm install astrology-core

使用

import { createNatalChart } from "astrology-core";

const chart = createNatalChart({
  datetime: "1990-06-15T14:30:00+08:00",
  location: {
    latitude: 31.2304,
    longitude: 121.4737,
  },
});

console.log(chart.planets);
console.log(chart.points);
console.log(chart.lunarNodes.true.north);
console.log(chart.angles.ascendant);
console.log(chart.houses);
console.log(chart.aspects);

datetime 可以是 JavaScript Date，也可以是包含 Z 或明确偏移量的 ISO 8601 字符串。无时区的字符串（如 1990-06-15T14:30:00）会被拒绝，因为它在不同机器上可能代表不同瞬间。

默认计算规则

| 项目 | v0.3.0 规则 | | --- | --- | | 黄道 | 热带黄道 | | 观测中心 | 地心 | | 坐标参考 | 当日真黄道与真春分点 | | 光行差 | 已校正 | | 宫制 | Whole Sign | | 大气折射 | 不校正 | | 逆行 | 以目标时刻前后各 0.5 日的黄经中心差分计算 | | 星历 | astronomy-engine 2.1.19 | | 平均月交点 | TT 下的 Meeus 平均升交点多项式 | | 真月交点 | astronomy-engine 月球状态向量的瞬时轨道平面 | | 默认相位点 | 十大行星、ASC、MC；不计算 ASC-MC 相位 |

所有规则都会出现在返回结果的 rules 字段中，包括实际使用的完整相位定义、精度承诺和 warning 阈值。调用方修改传入的相位数组不会反向改变已经生成的星盘结果。

验证范围与精度承诺

当前发布的独立对照盘使用 Swiss Ephemeris 2.10.3.2 的 Moshier 模式生成，不依赖本项目自身的计算结果。

| 项目 | 验证承诺 | | --- | --- | | UTC 日期范围 | 1900-01-01（含）至 2101-01-01（不含） | | 角度验证纬度 | 绝对纬度不超过 75° | | 行星黄经对照容差 | 0.05° | | ASC / MC 对照容差 | 0.01° | | 真 / 平均月交点对照容差 | 0.02° | | 固定对照盘数量 | 40 |

对照盘覆盖南北半球、高纬度、赤道、日期变更线、半小时时区、午夜、历史与未来日期、二分二至、行星停滞，以及高纬度 MC 回归案例。原始输入、期望值和来源说明位于 test/fixtures。

这里的容差是对已公开测试向量的保守回归承诺，不代表已经穷举连续时间和所有地理位置。超出验证日期或纬度范围时仍会返回计算结果，但 warnings 会明确说明该结果不在当前精度承诺内。

边界警告

warnings 是结构化数组，每条警告包含稳定的 code、可读 message 和机器可处理的 details。当前可能返回：

• DATE_OUTSIDE_VALIDATED_RANGE
• LOCATION_OUTSIDE_VALIDATED_LATITUDE
• HIGH_LATITUDE_ANGLE_SENSITIVITY
• PLANET_NEAR_STATION
• POINT_NEAR_SIGN_BOUNDARY
• ASPECT_NEAR_ORB_BOUNDARY

这些警告不会替调用方下结论，只指出结果对出生时间、坐标或配置更敏感的情况。

统一星盘点与月交点

chart.points 提供统一的 ChartPoint[]，目前依次包含十大行星、平均南北交点、真南北交点、ASC 和 MC。原有的 chart.planets、chart.angles 继续保留。

真、平均月交点是两套可审计的替代计算结果，不代表应同时用于解释：

console.log(chart.lunarNodes.mean.north);
console.log(chart.lunarNodes.mean.south);
console.log(chart.lunarNodes.true.north);
console.log(chart.lunarNodes.true.south);

每个月交点都返回黄经、星座内度数和 Whole Sign 落宫。当前默认相位集合只包含行星、ASC 和 MC；月交点相位留给后续显式配置，避免把真、平均交点同时混入相位结果。

默认相位

| 相位 | 角度 | 容许度 | | --- | ---: | ---: | | 合相 | 0° | 8° | | 六分相 | 60° | 5° | | 四分相 | 90° | 7° | | 三分相 | 120° | 7° | | 对分相 | 180° | 8° |

可以通过第二个参数替换整套相位定义：

const chart = createNatalChart(input, {
  aspects: [
    { name: "conjunction", angle: 0, orb: 6 },
    { name: "opposition", angle: 180, orb: 6 },
  ],
});

相位本身是角距离与容许度规则的结果；选择多大的容许度不是天文事实，因此结果会同时返回 point1、point2、separation、orb 和 maxOrb，方便调用方审计。body1、body2 为兼容 0.2.x 暂时保留，新代码应使用 point1、point2。

明确不做什么

• 不输出性格、吉凶、运势等解释文本
• 不把相位容许度或宫制宣称为唯一标准
• v0.3.0 不支持恒星黄道、Placidus 等其他宫制、小行星、行运或合盘
• 不把计算结果用于医疗、法律、金融或其他高风险决策

开发与发布

npm install
npm run check
npm run build
npm pack --dry-run

首次发布前，先确认 npm 登录状态和包名仍可用，再检查压缩包内容：

npm whoami --registry=https://registry.npmjs.org/
npm publish --access public

许可证与底层算法

本项目使用 MIT License。天文位置由同为 MIT 许可证的 astronomy-engine 计算。

npm 压缩包会同时包含 TypeScript 源码、测试、编译产物和 source map，使用者可以审阅实际发布的算法与测试向量。

贡献原则

新增能力应满足：输入规则明确、输出可复现、有公开测试向量、计算与解释分离。任何默认规则的变化都必须记录在变更日志中。