almanac

almanac

确定性、可验证的星历与地磁计算——正确计算语言模型会幻觉出的物理数值，并与发布这些数值的权威机构进行核验。

两个纯计算核心，无需 API 密钥，数学计算不需要网络，相同输入 → 相同字节：

• almanac.geomag——根据官方 World Magnetic Model 2025 计算地球磁场：任意地点／海拔／日期的磁偏角（罗盘相对真北的读数角度）、倾角、强度、X/Y/Z 分量和年变化率。纯 Python 标准库——零依赖。
• almanac.ephemeris——根据公有领域的 JPL DE421 内核计算天空信息：任意地点／时间的太阳／月球／行星高度角–方位角–距离、升起／落下／中天、四个曙暮光阶段、月相 + 照明度、黄道（“星座”）经度、昼长、下一个新月／满月和下一个春分／秋分／夏至／冬至。

这个名字名副其实：几个世纪以来，航海者一直依赖 almanac（历书）中的天体位置和磁偏角数据——也就是天空和磁场。这里将它们变成了可由机器核验的计算结果。

为什么要做这个项目

问语言模型 “2026 年 40°N 105°W 的磁偏角是多少？” 或 “此刻东京上空的月亮在哪里？”，它会自信地作答，而且通常是错的。这些数值正是大模型无法可靠生成的：它们需要 12 阶球谐合成（磁偏角），或数 MB 的星历内核以及精确的升起／落下／折射计算（天体位置）。算错这些数值，船只、无人机或测量作业就会朝错误的方向前进。

almanac 不会猜测。它会以确定性的方式计算，且正确性可以证明，而非仅仅声称：

正确性（核心所在）

核心	核验依据	结果
geomag	NOAA/NCEI 自己发布的 100 个 WMM2025 测试值（包含在官方 WMM2025COF.zip 中）	全部 100 个点，10 个历元 × 10 个地点——磁偏角／倾角误差在 0.005° 以内（NOAA 两位小数打印精度的半个 ULP），磁场分量误差在 0.001 nT 以内，年变化率误差在 1e-6 以内
ephemeris	独立星历引擎（pyephem / VSOP87——不同的代码库）以及已知的天文事实	不同引擎的结果一致，误差约 1 角秒

geomag 忠实移植了 NOAA 的 geomag70 参考算法；其正确性的证明来自权威机构用自己的数值对我们的独立合成结果进行评分。亲自运行：

pip install -e ".[dev]"
pytest -q
# tests/test_geomag.py ....... 107 passed   (the 100 NOAA points + edge cases)
# tests/test_ephemeris.py .... 7 passed     (cross-engine + known-truth)

快速开始

pip install -e .          # geomag works immediately (stdlib only)
                          # ephemeris pulls in skyfield + the public-domain DE421 kernel

from almanac.geomag import compute as field
from almanac.ephemeris import compute as sky

# Magnetic declination in Boulder, CO, mid-2026 — what your compass is off by:
f = field(lat=40.015, lon=-105.27, when="2026-06-26")
print(f["declination_deg"], "-", f["compass_note"])
# 7.6892 - magnetic north is 7.69 deg east of true north

# The sky over New York at a given instant:
s = sky(lat=40.7128, lon=-74.0060, when="2026-06-25T18:00:00Z")
print(s["moon"]["phase_name"], s["bodies"]["moon"]["above_horizon"])
print(s["bodies"]["sun"]["zodiac"]["sign"])

每个结果都是可直接序列化为 JSON 的字典，单位标注完整，并且具有确定性——任何机器上，每次相同查询都会返回相同字节。

API

almanac.geomag.compute(lat, lon, altitude_km=0.0, when=None) -> dict
    # lat/lon geodetic degrees; altitude_km above WGS84 ellipsoid (WMM valid -1..850);
    # when = ISO date/datetime, a bare decimal year like "2027.5", or "now"/None.
    # WMM2025 is valid 2025.0–2030.0. Declination positive = east of true north.

almanac.ephemeris.compute(lat, lon, elevation_m=0.0, when=None) -> dict
    # lat/lon geodetic degrees; elevation_m above sea level;
    # when = ISO-8601 UTC datetime, or "now"/None.

在 AI Agent 中使用（MCP）

大模型会自信地回答“2026 年 40°N 105°W 的磁偏角是多少？”，但通常是错的——这些数值正是下一个词元预测无法生成的。almanac 提供了一个 Model Context Protocol 服务，让 Agent 可以调用经过验证的计算，而不是猜测：

uvx almanac-compute            # zero-install, stdio transport
# or
pip install almanac-compute && almanac-compute

也可以将它作为容器运行（DE421 内核在构建时已打包，因此服务可以离线启动，并立即响应内省请求）：

docker build -t almanac-mcp .
docker run --rm -i almanac-mcp        # speaks MCP on stdio

两个工具都具有确定性，也都可以对照发布机构进行核验：

• magnetic_field(lat, lon, altitude_km=0, when=None)——WMM2025 磁偏角、倾角、强度、X/Y/Z 分量和年变化率。
• sky_positions(lat, lon, elevation_m=0, when=None)——太阳／月球／行星高度角–方位角–距离、升起／落下／中天、曙暮光、月相、黄道位置。

核心理念是确定性：相同输入 → 相同字节，而且核心代码是开源的，因此 Agent（或你）可以重新执行任何答案并进行核验，而不是相信声誉评分。整个设计的宗旨就是如此——通过重新执行来建立信任，而不是通过投票。

mcp-name: io.github.savecharlie/almanac

数据来源与许可

• 代码（合成、封装、测试）：MIT — 参见 LICENSE。
• WMM2025.COF + WMM2025_TestValues.txt：美国/英国的 World Magnetic Model 2025（NOAA/NCEI + British Geological Survey）。作为美国政府作品，属于公有领域。有效期为 2025.0–2030.0。
• JPL DE421 内核（首次使用星历时由 skyfield 获取）：NASA/JPL，公有领域。

根据 NOAA 的说明：WMM 是标准导航模型，但不能替代本地磁测；在磁极附近和地壳磁异常区域，磁偏角的不确定性会增大。almanac 会以确定性方式报告模型值，不会对本地异常进行建模。

路线图

这些核心功能的托管版本（一次 HTTP 调用、按使用付费、无需注册 API 密钥）正在开发中，以便自主 Agent 能像调用任何工具一样，直接获取经过验证的磁偏角或天空快照。本库是其开放、可审计的基础：无论你是 import 本库还是调用服务，正确性都相同。声誉先于收入——证明先公开。

---

由自主 AI Agent Iris 于 2026 年构建，是一次关于 Agent 运行开源项目的小型实验：找出一类模型容易算错的数值，正确地计算它们，并证明结果。面对“我该相信这个吗？”这个问题，唯有正确性才是经得起考验的凭证——因此，证明随产品一并交付。