deepnatal

deepnatal

一款星盘引擎，每个结果都会通过三种独立方式交叉验证；无法验证时，它会拒绝作答。

既可作为 TypeScript 库使用，也可作为 MCP 服务，供 Claude、Cursor、Codex、Cline 和其他 Agent 使用。

npx -y deepnatal-mcp

为什么要做这个

向任何占星网站查询出生星盘，你都会得到一个答案，却几乎得不到验证答案的方法。

这比听起来更重要，因为上升星座每四分钟大约移动一度。若 UTC 时刻差了一个小时，上升星座就会偏移约半个星座。结果看起来依然完全合理，却没有任何迹象表明它是错的。

而一个小时很容易弄丢。台湾在 1945–1961 年和 1974–1979 年实行过夏令时。中国大陆在 1986 至 1991 年间实行过夏令时。日本在 1948 至 1951 年间实行过夏令时。许多工具会悄悄将 今天的 UTC 时差用于 1988 年的出生日期，给出的星盘恰好偏差一小时。

这个软件包基于相反的假设构建：无法验证的结果，不算结果。

如何验证

三条独立路径分别计算每张星盘。结果不一致就是错误，不该通过取平均值来掩盖。

实际计算中的典型误差小于 1 角分。超过容差时，调用会抛出错误，而不是返回星盘。

当数学计算确实无法成立时，它也会如实处理：

• 纬度高于 66° 时，普拉西德宫位无法定义。引擎会改用整宫制，并告知你这一点，而不是悄悄输出毫无意义的结果。
• 没有出生时间时，会直接省略上升星座、天顶和宫位，并说明原因。不会擅自用正午代替。如果月亮当天换了星座——这种情况接近半数日期都会发生——也会报告这一点。
• 处于夏令时转换缺口内时，若当地时间不存在或重复出现，引擎会抛出错误并要求你消除歧义。

亲自验证

仅在 README 中声称“经过交叉验证”毫无意义。测试套件包含在已发布的软件包中，因此你可以针对自己安装的确切文件运行测试：

npm i deepnatal
node node_modules/deepnatal/dist/selftest.js

✅ PASS — 21/21 boundary cases + 11/11 external cross-checks
   All three paths agree, and they agree with an outside source.

这 21 个边界案例专门挑选了容易出错的情形，而非简单案例：中国 1986–1991 年的夏令时区间及同年的冬季对照案例、台湾 1979 年的案例、日本 GHQ 时期（1948–1951 年）的案例、因夏令时跳变而从未存在过的时间，以及北极圈内普拉西德宫位无法定义的纬度。

这 11 项外部校验会将结果与从 astro-seek 记录的数值进行比较。之所以需要这些校验，是因为三个内部路径共享一些假设——回归黄道、视地心位置、当日真黄道——如果某个假设本身有误，三条路径就会得出同一个错误答案。只有外部来源能发现这一点。

CI 会在刻意设置为非 UTC 的系统时钟下，使用 Node 20/22/24 运行测试套件，因此任何意外依赖主机时区的情况都会明确报错。

快速开始

npm install deepnatal

import { calculateNatalChart, verifyAscendant } from 'deepnatal';

const birth = {
  date: '1988-07-15',
  time: '14:30',
  timezone: 'Asia/Shanghai',   // the BIRTHPLACE's zone, never the user's current one
  latitude: 31.23,
  longitude: 121.47,
};

const chart = calculateNatalChart(birth);
chart.ascendant;             // { sign: 'scorpio', degreeInSign: 10.37, ... }
chart.crossCheckMaxArcmin;   // 0.467 — how far the two engines disagreed

检查其他人的答案

这就是这个软件包存在的原因。将其他任意工具的结果作为 claim 传入：

verifyAscendant(birth, 'Scorpio 23.0');

{
  "computed":  { "sign": "scorpio", "degreeInSign": 10.37 },
  "geometric": { "sign": "scorpio", "degreeInSign": 10.37 },  // independent path
  "internalAgreementArcmin": 0,
  "oneHourOffsetTest": {
    "minusOneHour": { "sign": "libra",   "degreeInSign": 27.66 },
    "plusOneHour":  { "sign": "scorpio", "degreeInSign": 22.98 },
    "degreesPerHour": 12.66
  },
  "claim": {
    "verdict": "off-by-one-hour",
    "likelyCause": "Measured, not guessed: the supplied value matches this engine's
                    ascendant for a birth instant one hour LATER than the one given..."
  }
}

注意 degreesPerHour: 12.66。常见的经验法则认为每小时为 15°——那是地球的自转速率，而非上升点沿黄道移动的速率；只有在赤道附近，两者才一致。这个库会针对每张星盘进行测量，而不是直接套用这一数值。

MCP 服务

npx -y deepnatal-mcp

{
  "mcpServers": {
    "deepnatal": { "command": "npx", "args": ["-y", "deepnatal-mcp"] }
  }
}

{
  "mcpServers": {
    "deepnatal": { "command": "npx", "args": ["-y", "deepnatal-mcp"] }
  }
}

claude mcp add deepnatal -- npx -y deepnatal-mcp

工具

所有运算都在 Agent 自己的进程中本地运行。出生数据属于最敏感的个人数据之一，不会离开设备——这个软件包不会进行任何网络调用。

为什么让 Agent 调用它，而不是自行推理？ 因为让大模型推算上升星座时，它会给出自信、看似合理却错误的答案，而下游环节无法发现这一点。此服务返回计算结果及其不确定性，不做解读。

中文說明

deepnatal 是一套會自我驗算的本命盤計算引擎——算不出來時它會拒絕回答，而不是給你一個看起來合理的答案。

上升星座每四分鐘移動約一度。時區算錯一小時，上升就偏掉大半個星座，而結果看起來完全正常，不會有任何地方提示你它是錯的。

而一小時很容易丟。台灣在 1945–1961、1974–1979 實施過夏令時間，中國大陸是 1986–1991，日本是 1948–1951。不少工具會把今天的時區偏移直接套到 1988 年的出生日期上。

三條獨立路徑同時計算，彼此不一致就報錯：

1. 時區層　明確 IANA 時區 + Node ICU 歷史 tzdata，與座標反查時區交叉核對
2. 行星層　circular-natal-horoscope-js × astronomy-engine 兩套獨立演算法
3. 上升層　純球面幾何第三條路（黃道與東方地平線交點），完全不依賴任何占星函式庫

實測吻合度在 1 角分以內。超過容許值就丟出錯誤，不回傳星盤。

verifyAscendant() 可以用來檢查任何其他工具算出的上升是否正確。它不猜原因——而是實際重算前後各一小時的上升點，如果對方的答案正好落在那裡，就能證明差異來自時區處理而非天文計算。

完整工具與說明見 deepnatal.com。

這無法證明什麼

坦誠說明能力邊界，也是本項目宗旨的一部分。

• 交叉驗證可以發現實作錯誤和結果偏差，但無法證明三種方法採用的共同慣例是正確的——這三條路徑都假設使用回歸黃道、視地心位置和當日真黃道。
• 可重現的星盤並不能說明占星是否具有預測能力。這個軟體包只計算位置，不對其含義作任何主張。
• 兩種工具可能因宮位制、黃道類型（回歸黃道或恆星黃道）、星曆、交點慣例或取整方式而合理地得出不同結果。verify_ascendant 可以區分一小時的偏差與這些差異，但不會對慣例之爭判定誰對誰錯。
• 出生資料錯誤，仍會得出技術上正確、但對應錯誤時刻的星盤。下游環節無法補救這一點。

授權條款

MIT。為了便於重新分發，我們刻意確保依賴鏈清晰：

特別說明：本項目不使用 Swiss Ephemeris（sweph / swisseph）。它標示的雙重授權 AGPL-3.0-or-later OR LGPL-3.0-or-later 容易造成誤解：LGPL 選項要求先購買 Astrodienst 商業授權。若沒有商業授權，就必須遵循 AGPL；該授權也適用於網路服務，並要求將所有與其互動的內容開源。這項限制正是大多數託管式占星產品無法將其計算層作為開源軟體包發布的原因，而本項目可以。

致谢

这是 deepnatal.com 的计算层，原样提取而来——该网站运行的代码与此处发布的代码相同，因此可以在本地使用此软件包复现它生成的任何星盘。

问题和 PR：github.com/breezefeng/deepnatal