feat: 引入可切换星历模型并扩展天象观测链路

- 新增半解析、旧模型、自定义与多源堆叠星历实例，提供 Context、Instance、SPK 读取及状态与视位置计算 - 统一太阳、月球和行星实例接口，扩展黄经穿越、留、相位、最近角距、偕日可见、任意高度升落、轨道节点及凌日等天象查询 - 完善日月食、月掩与凌日的月缘剖面、有限盘面接触、站心修正、局地可见性、全球路径和地图输出 - 新增 SVG、GeoJSON、KML 天象输出及凌日、月掩和月缘地形相关缓存与几何求解 - 新增恒星星表导入与查询，支持 CSV、Hipparcos、BSC5、Stellarium 等格式及名称、交叉标识、锥面检索和星等过滤 - 补充 IAU 2006、地球定向、折射消光、大气观测、轨道传播及半解析行星/月球数据支持 - 将默认未来民用时标切换为 TimeScaleLeapHour，更新 2027–2400 农历速查表、中文日期解析和时区边界处理 - 增加事件基线、跨模型回归、几何边界、月缘地形和输出契约测试，完善中英文手册、示例资源、NOTICE 与忽略规则
2026-10-15 23:54:15 +08:00
parent 16c62a97d5
commit 044f2f4381
674 changed files with 62983 additions and 8396 deletions
@@ -2,12 +2,12 @@

 [English](en/planets.md) | [返回 README](../../README.md)

-七大行星各对应一个同名包：`mercury`、`venus`、`mars`、`jupiter`、`saturn`、`uranus`、`neptune`。它们的公开接口按同一套形状组织：以 `time.Time` 传入民用时刻，以 `float64` 返回角度或距离，事件搜索返回 `time.Time` 或结构体。内行星（水星、金星）额外提供上合/下合、大距与地心凌日；外行星（火星到海王星）额外提供冲日与方照；木星独有伽利略卫星，土星独有土星环参数。
+七大行星各对应一个同名包：`mercury`、`venus`、`mars`、`jupiter`、`saturn`、`uranus`、`neptune`。它们的公开接口按同一套形状组织：以 `time.Time` 传入民用时刻，以 `float64` 返回角度或距离，事件搜索返回 `time.Time` 或结构体。内行星（水星、金星）额外提供上合/下合、大距与地心、站心凌日；外行星（火星到海王星）额外提供冲日与方照；木星独有伽利略卫星，土星独有土星环参数。

-低层的 VSOP87 级数与日月解析级数放在 `planet` 包，被这七个包与 `sun` / `moon` 共用。
+低层内置半解析模型与 Legacy 的 VSOP87/日月级数放在 `planet` 包，被这七个包与 `sun` / `moon` 共用；默认构建使用半解析模型，可用显式 Context 固定模型。

 - 七个包公共能力的函数名一致（例如都提供 `ApparentRa`、`ApparentDec` 与 `ApparentRaDec`），差异只体现在各自额外的那几族接口上；调用时必须带对应包名前缀，不能跨包混用。
- 位置接口给出的是**地心视位置**；站心量与地平坐标单独由 `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` 提供，公式入口见[坐标工具](coord.md)。
+- 位置接口给出的是**地心视位置**；地平量单独提供：`Altitude` / `Azimuth` / `Zenith` 是站心量，`HourAngle` / `ParallacticAngle` 是地心量（不含站心视差），公式入口见[坐标工具](coord.md)。
 - 事件搜索族都成对出现（`Last...` / `Next...`，部分另有 `Closest...`），一律取"当前或之前/之后最近一次"并包含端点。
 - 行星本身没有独立的 SVG 出图入口；月掩相关出图（含土星环月掩）见[月掩手册](occultation.md#月掩出图)。

@@ -17,7 +17,7 @@
 - [API 参考](#api-参考)
  - [按行星横向对照](#按行星横向对照)
  - [通用能力与单位](#通用能力与单位)
-  - [`...N` 截断族](#n-截断族)
+  - [`...N` 族](#n-族)
 - [常用场景](#常用场景)
  - [今晚能看到哪颗行星](#今晚能看到哪颗行星)
  - [冲日、合日、大距、留与逆行](#冲日合日大距留与逆行)
@@ -37,7 +37,7 @@
  - [与其他手册的分工](#与其他手册的分工)
  - [物理星历](#物理星历)
  - [木星伽利略卫星](#木星伽利略卫星)
-  - [与 `planet` 包共用的类型与常量](#与-planet-包共用的类型与常量)
+  - [与 `planet` 包共用的低层入口](#与-planet-包共用的低层入口)
 - [参数与返回值约定](#参数与返回值约定)
  - [时标与民用时刻](#时标与民用时刻)
  - [单位与口径](#单位与口径)
@@ -80,7 +80,7 @@ func main() {

 下表按能力对照七个行星包。调用时加包名前缀，例如 `mars.NextOpposition`；`/` 分隔并列函数，`—` 表示该包没有对应接口。

-| 能力 | `mercury` | `venus` | `mars` | `jupiter` | `saturn` | `uranus` | `neptune` |
+| 计算项 | `mercury` | `venus` | `mars` | `jupiter` | `saturn` | `uranus` | `neptune` |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | 视黄经 / 视黄纬 | `ApparentLo` / `ApparentBo` | `ApparentLo` / `ApparentBo` | `ApparentLo` / `ApparentBo` | `ApparentLo` / `ApparentBo` | `ApparentLo` / `ApparentBo` | `ApparentLo` / `ApparentBo` | `ApparentLo` / `ApparentBo` |
 | 视赤经 / 视赤纬 | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | `ApparentRa` / `ApparentDec` / `ApparentRaDec` |
@@ -89,7 +89,7 @@ func main() {
 | 轨道升交点 / 降交点 | `AscendingNode` / `DescendingNode` | `AscendingNode` / `DescendingNode` | `AscendingNode` / `DescendingNode` | `AscendingNode` / `DescendingNode` | `AscendingNode` / `DescendingNode` | `AscendingNode` / `DescendingNode` | `AscendingNode` / `DescendingNode` |
 | 视直径 / 视半径 | `Diameter` / `Semidiameter` | `Diameter` / `Semidiameter` | `Diameter` / `Semidiameter` | `Diameter` / `Semidiameter` | `Diameter` / `Semidiameter` | `Diameter` / `Semidiameter` | `Diameter` / `Semidiameter` |
 | 相位角 / 照亮比例 / 亮面位置角 | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` | `PhaseAngle` / `Phase` / `IlluminatedFraction` / `BrightLimbPositionAngle` |
-| 站心地平量 | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` |
+| 地平量 | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` | `Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` |
 | 升 / 落 / 中天 | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` | `RiseTime` / `SetTime` / `DownTime` / `CulminationTime` |
 | 物理星历 | `Physical` / `PhysicalN` | `Physical` / `PhysicalN` | `Physical` / `PhysicalN` | `Physical` / `PhysicalN` / `CentralMeridians` / `CentralMeridiansN` | `Physical` / `PhysicalN` / `PhysicalSystemIII` / `Ring` | `Physical` / `PhysicalN` / `PhysicalSystemIII` | `Physical` / `PhysicalN` |
 | 合日 | `LastConjunction` / `NextConjunction` | `LastConjunction` / `NextConjunction` | `LastConjunction` / `NextConjunction` | `LastConjunction` / `NextConjunction` | `LastConjunction` / `NextConjunction` | `LastConjunction` / `NextConjunction` | `LastConjunction` / `NextConjunction` |
@@ -98,23 +98,25 @@ func main() {
 | 冲日 | — | — | `LastOpposition` / `NextOpposition` | `LastOpposition` / `NextOpposition` | `LastOpposition` / `NextOpposition` | `LastOpposition` / `NextOpposition` | `LastOpposition` / `NextOpposition` |
 | 方照 | — | — | `LastEasternQuadrature` / `NextEasternQuadrature` / `LastWesternQuadrature` / `NextWesternQuadrature` | `LastEasternQuadrature` / `NextEasternQuadrature` / `LastWesternQuadrature` / `NextWesternQuadrature` | `LastEasternQuadrature` / `NextEasternQuadrature` / `LastWesternQuadrature` / `NextWesternQuadrature` | `LastEasternQuadrature` / `NextEasternQuadrature` / `LastWesternQuadrature` / `NextWesternQuadrature` | `LastEasternQuadrature` / `NextEasternQuadrature` / `LastWesternQuadrature` / `NextWesternQuadrature` |
 | 大距 | `LastGreatestElongation` / `NextGreatestElongation` / `LastGreatestElongationEast` / `NextGreatestElongationEast` / `LastGreatestElongationWest` / `NextGreatestElongationWest` | `LastGreatestElongation` / `NextGreatestElongation` / `LastGreatestElongationEast` / `NextGreatestElongationEast` / `LastGreatestElongationWest` / `NextGreatestElongationWest` | — | — | — | — | — |
-| 地心凌日 | `LastTransit` / `NextTransit` / `ClosestTransit` | `LastTransit` / `NextTransit` / `ClosestTransit` | — | — | — | — | — |
+| 凌日 | `LastTransit` / `NextTransit` / `ClosestTransit` / `LocalTransit` | `LastTransit` / `NextTransit` / `ClosestTransit` / `LocalTransit` | — | — | — | — | — |
 | 伽利略卫星 | — | — | — | `Satellites` / `SatellitePhenomena` / `LastGalileanPhenomenonEvent` / `NextGalileanPhenomenonEvent` / `ClosestGalileanPhenomenonEvent` / `LastGalileanPhenomenonContactEvent` / `NextGalileanPhenomenonContactEvent` / `ClosestGalileanPhenomenonContactEvent` | — | — | — |
-| 结果类型 | `PhysicalInfo` / `TransitInfo` | `PhysicalInfo` / `TransitInfo` | `PhysicalInfo` | `PhysicalInfo` / `CentralMeridianInfo` / `GalileanSatellitesInfo` / `GalileanPhenomenaInfo` / `GalileanSatellitePosition` / `GalileanSatellitePhenomenon` / `GalileanPhenomenonEvent` / `GalileanPhenomenonContactEvent` | `PhysicalInfo` / `RingInfo` | `PhysicalInfo` | `PhysicalInfo` |
+| 结果类型 | `PhysicalInfo` / `TransitInfo` / `LocalTransitInfo` | `PhysicalInfo` / `TransitInfo` / `LocalTransitInfo` | `PhysicalInfo` | `PhysicalInfo` / `CentralMeridianInfo` / `GalileanSatellitesInfo` / `GalileanPhenomenaInfo` / `GalileanSatellitePosition` / `GalileanSatellitePhenomenon` / `GalileanPhenomenonEvent` / `GalileanPhenomenonContactEvent` | `PhysicalInfo` / `RingInfo` | `PhysicalInfo` | `PhysicalInfo` |

-七个包的**截断族**都叫同样的名字：给任意一个瞬时求值接口加 `N` 后缀即可，`n < 0` 用全部内置项、`n >= 0` 截断，详见 [`...N` 截断族](#n-截断族)。事件搜索族（`Last...` / `Next...` / `Closest...`）没有 `N` 版本。
+七个包的 **`...N` 族**都叫同样的名字：给任意一个瞬时求值接口加 `N` 后缀即可。`n < 0` 用完整级数，半解析的所有 `n >= 0` 用同一张快速表，Legacy 按 `n` 截断，详见 [`...N` 族](#n-族)。事件搜索族（`Last...` / `Next...` / `Closest...`）没有 `N` 版本。

 ### 通用能力与单位

-| 能力 | 用途 | 单位与口径 |
+| 计算项 | 用途 | 单位与口径 |
 | --- | --- | --- |
 | `ApparentLo` / `ApparentBo` | 地心视黄经、视黄纬 | 度；当日真春分点，含光行时、光行差与章动 |
 | `ApparentRa` / `ApparentDec` / `ApparentRaDec` | 地心视赤经、视赤纬 | 度；当日真赤道；`ApparentRaDec` 一次返回两者 |
 | `ApparentMagnitude` | 视星等 | 星等（无量纲） |
-| `Altitude` / `Azimuth` / `Zenith` / `HourAngle` | 站心地平坐标 | 度；方位角自正北向东增加，`Zenith` 等于 `90 - Altitude` |
+| `Altitude` / `Azimuth` / `Zenith` | 站心地平坐标 | 度；方位角自正北向东增加，`Zenith` 等于 `90 - Altitude` |
+| `HourAngle` | 地心视时角，不含站心视差 | 度 |
 | `RiseTime` / `SetTime` / `DownTime` | 当地民用日内的升起、落下 | `time.Time`，保持输入时区；`DownTime` 是 `SetTime` 的兼容别名 |
+| `RiseTimeWithAtmosphere` / `SetTimeWithAtmosphere` | 按实测气压（hPa）、气温（℃）计算升落 | `time.Time`；恒带大气折射 |
 | `CulminationTime` | 上中天时刻 | `time.Time`，保持输入时区 |
-| `ParallacticAngle` | 视差角（天顶方向角） | 度 |
+| `ParallacticAngle` | 地心视差角（天顶方向角），由地心时角与赤纬求得 | 度 |
 | `Diameter` / `Semidiameter` | 地心视直径、视半径 | 角秒 |
 | `PhaseAngle` | 太阳–行星–地球夹角 | 度 |
 | `IlluminatedFraction` / `Phase` | 被照亮比例 | `0–1`；`Phase` 是 `IlluminatedFraction` 的别名 |
@@ -122,16 +124,21 @@ func main() {
 | `EarthDistance` / `SunDistance` | 地心距、日心距 | AU |
 | `AscendingNode` / `DescendingNode` | 轨道面与黄道面交点的黄经 | 度；同一时刻两者相差约 `180°` |
 | `Physical` | 盘面朝向、子地/子日经纬度、北极位置角 | 度；经度正方向按各天体 IAU 约定 |
-| `planet.WherePlanet` / `planet.WherePlanetN` | VSOP87 黄经、黄纬、日心距 | 度 / AU；越界返回 `NaN` 而不 panic |
+| `planet.WherePlanet` / `planet.WherePlanetN` | 当前内置模型的黄经、黄纬、日心距 | 度 / AU；越界返回 `NaN` 而不 panic |

-### `...N` 截断族
+### `...N` 族

-每个瞬时求值接口都有 `...N` 后缀版本，用来在精度与开销之间取舍：`n < 0` 使用全部内置项，与非 `N` 接口等价；`n >= 0` 时按约 `n` 个主项截断并等比缩短高阶项。事件搜索族（`Last...` / `Next...` / `Closest...`）没有 `N` 版本。
+每个瞬时求值接口都有 `...N` 后缀版本，用来在精度与开销之间取舍：`n < 0` 使用完整级数，与非 `N` 接口等价；半解析的所有 `n >= 0` 使用同一张快速表，增大 `n` 不提高精度；Legacy 按 `n` 控制主项并等比缩短高阶项。

-带 `N` 的族包括 `ApparentLoN`、`ApparentBoN`、`ApparentRaN`、`ApparentDecN`、`ApparentRaDecN`、`ApparentMagnitudeN`、`EarthDistanceN`、`SunDistanceN`、`AltitudeN`、`AzimuthN`、`ZenithN`、`HourAngleN`、`CulminationTimeN`、`RiseTimeN`、`SetTimeN`、`DownTimeN`、`ParallacticAngleN`、`DiameterN`、`SemidiameterN`、`PhaseAngleN`、`PhaseN`、`IlluminatedFractionN`、`BrightLimbPositionAngleN`、`AscendingNodeN`、`DescendingNodeN`、`PhysicalN`，以及木星的 `CentralMeridiansN`、土星的 `RingN` 与 `PhysicalSystemIIIN`、天王星的 `PhysicalSystemIIIN`。
+带 `N` 的族按用途分组：
+
+- 位置与距离：`ApparentLoN`、`ApparentBoN`、`ApparentRaN`、`ApparentDecN`、`ApparentRaDecN`、`EarthDistanceN`、`SunDistanceN`
+- 地平与时刻：`AltitudeN`、`AzimuthN`、`ZenithN`、`HourAngleN`、`CulminationTimeN`、`RiseTimeN`、`SetTimeN`、`DownTimeN`、`ParallacticAngleN`
+- 视面与相位：`ApparentMagnitudeN`、`DiameterN`、`SemidiameterN`、`PhaseAngleN`、`PhaseN`、`IlluminatedFractionN`、`BrightLimbPositionAngleN`
+- 轨道交点与自转：`AscendingNodeN`、`DescendingNodeN`、`PhysicalN`，以及木星的 `CentralMeridiansN`、土星的 `RingN` 与 `PhysicalSystemIIIN`、天王星的 `PhysicalSystemIIIN`

 ```go
-fmt.Println(mars.ApparentLo(date), mars.ApparentLoN(date, 8))   // 视黄经：全部内置项 / 截断到约 8 项
+fmt.Println(mars.ApparentLo(date), mars.ApparentLoN(date, 8))   // 完整级数 / 快速表；Legacy 按 n 截断。
 fmt.Println(mars.SunDistance(date), mars.SunDistanceN(date, 8)) // 日心距，AU
 ```

@@ -151,7 +158,7 @@ fmt.Println(mars.Altitude(date, lon, lat), mars.Azimuth(date, lon, lat)) // 火
 31.194578177219057 152.07031660415714
 ```

-`Altitude` 大于 `0` 才在地平线上，方位角自正北向东增加；`aero = true` 按标准大气折射把几何地平线降到约 `-0.5667°`，逐参数口径与极区哨兵错误见[升落与中天](#升落与中天)。
+方位角自正北向东增加；`aero = true` 按标准大气折射把几何地平线降到约 `-0.5667°`，逐参数口径与极区哨兵错误见[升落与中天](#升落与中天)。

 ### 冲日、合日、大距、留与逆行

@@ -182,7 +189,26 @@ true 2032-11-13 14:41:13.161198198 +0800 CST 2032-11-13 16:54:12.821315824 +0800
 4h26m2.695272267s 572.0643215495325
 ```

-`TransitInfo.Valid` 为假表示搜索窗口内没有凌日、其余字段是零值；凌日只判断地心几何，不判断观测地当时太阳是否在地平线上。四触、偏凌与内切口径见[大距与地心凌日](#大距与地心凌日)。
+`TransitInfo.Valid` 为假表示搜索窗口内没有凌日、其余字段是零值；`TransitInfo` 是地心几何结果。某个地点看到的接触时刻用 `LocalTransit` 求站心结果：
+
+```go
+transit := mercury.NextTransit(time.Date(2019, 1, 1, 0, 0, 0, 0, time.UTC))
+local := mercury.LocalTransit(transit, -77.0, 38.9, 0)        // 华盛顿，经度、纬度、海拔米
+fmt.Println(local.Valid, local.HasInternal, local.Visible)     // 站心有凌日、有内切接触、太阳在视地平上
+fmt.Println(local.Start.Time, local.Start.SunAltitude)         // 站心一触与当时太阳高度
+```
+
+```text
+true true true
+2019-11-11 12:36:09.037762284 +0000 UTC 7.933256722170642
+```
+
+站心接触对太阳与行星分别做视差修正后重解，所以各地接触时刻与地心值不同：金星可达约 ±7 分钟，水星约 ±2 分钟。
+
+- `SunAltitude` 是日心几何高度。
+- `Visible`、`Sunrise`、`Sunset` 按太阳中心是否在视地平上判定，计入标准大气（1010 hPa、10 °C）折射，几何阈值约 −34′。
+- 地心有内切接触、站心可能只是掠凌（例如 1999-11-15 水星凌日在南半球高纬），此时 `HasInternal` 为假，`InternalStart` / `InternalEnd` 是零值。
+- 全球可见图与站心日面图见[日月食与凌日](eclipse.md#凌日出图)；四触、偏凌与内切口径见[大距与地心凌日](#大距与地心凌日)。

 ### 相位、视直径、视星等与节点

@@ -198,7 +224,7 @@ fmt.Println(mars.AscendingNode(date), mars.DescendingNode(date)) // 升降交点
 49.71479005849112 229.71479005849113
 ```

-`Phase` 是 `IlluminatedFraction` 的别名，取值 `0–1`；升降交点同一时刻相差约 `180°`。各量的定义、别名与截断版见[节点、相位、视星等、视直径与视差角](#节点相位视星等视直径与视差角)。
+`Phase` 是 `IlluminatedFraction` 的别名，取值 `0–1`；升降交点同一时刻相差约 `180°`。各量的定义、别名与 `n` 变体见[节点、相位、视星等、视直径与视差角](#节点相位视星等视直径与视差角)。

 ### 物理星历与木星伽利略卫星

@@ -219,7 +245,7 @@ fmt.Println(sats.Io.OffsetXJupiterR, sats.Io.InFrontOfJupiter) // 木卫一偏
 ### 与外部资料的对照口径

 ```go
-fmt.Println(mars.ApparentLo(date), mars.ApparentLoN(date, 8)) // 全部内置项 / 约 8 项截断的视黄经
+fmt.Println(mars.ApparentLo(date), mars.ApparentLoN(date, 8)) // 完整级数 / 快速表；Legacy 按 n 截断。
 _, err := mars.RiseTime(date, 0, 89, 0, true)                 // 极区观测点
 fmt.Println(errors.Is(err, mars.ERR_MARS_NEVER_RISE), errors.Is(err, mars.ERR_MARS_NEVER_SET))
 ```
@@ -229,7 +255,7 @@ fmt.Println(errors.Is(err, mars.ERR_MARS_NEVER_RISE), errors.Is(err, mars.ERR_MA
 true false
 ```

-`ApparentLo` 等是**当日真春分点**的地心视位置，与外部 J2000 或平位置对表前先用 `coord.Precess` 归算；截断族 `n < 0` 用全部内置项、`n >= 0` 截断。伽利略卫星接触事件与 JPL Horizons / IMCCE 年表的口径差异见[与外部资料对照](#与外部资料对照)，整体边界见[参数与返回值约定](#参数与返回值约定)。
+`ApparentLo` 等是**当日真春分点**的地心视位置。与外部 J2000 或平位置对表时，需同时统一坐标框架、章动与视位置修正，不能仅用岁差变换消除全部差异。`n` 的模型相关语义见 [`...N` 族](#n-族)。伽利略卫星接触事件与外部年表的口径差异见[与外部资料对照](#与外部资料对照)，整体边界见[参数与返回值约定](#参数与返回值约定)。

 ## 基础示例

@@ -283,21 +309,21 @@ func main() {

 输出结果：

-```
-2019-11-11 23:21:41.971051096 +0800 CST // 水星上次下合
-2021-03-26 14:57:42.052354216 +0800 CST // 金星下次上合
-2019-11-01 04:31:49.749019145 +0800 CST // 水星上次由顺行转逆行的留
-2020-06-25 02:07:41.599749326 +0800 CST // 金星下次由逆行转顺行的留
-2019-10-20 12:01:37.740152478 +0800 CST // 水星上次东大距
-2020-08-13 08:14:46.304587125 +0800 CST // 金星下次西大距
-2020-01-01 10:02:34.172435402 +0800 CST <nil> // 西安当天金星升起时刻；无错误
-2020-01-01 20:25:37.36411482 +0800 CST <nil> // 西安当天金星落下时刻；无错误
+```text
+2019-11-11 23:21:41.729008555 +0800 CST // 水星上次下合
+2021-03-26 14:57:43.352850079 +0800 CST // 金星下次上合
+2019-11-01 04:31:49.712648391 +0800 CST // 水星上次由顺行转逆行的留
+2020-06-25 02:07:26.280500292 +0800 CST // 金星下次由逆行转顺行的留
+2019-10-20 12:01:37.925546765 +0800 CST // 水星上次东大距
+2020-08-13 08:14:45.946914553 +0800 CST // 金星下次西大距
+2020-01-01 10:02:34.94517982 +0800 CST <nil> // 西安当天金星升起时刻；无错误
+2020-01-01 20:25:36.944952607 +0800 CST <nil> // 西安当天金星落下时刻；无错误
 -4 // 金星视星等
-49.98145049145023 // 金星相位角，单位度
-0.8215177914415865 // 金星被照亮比例
-255.63802053541346 // 金星亮面中心位置角，单位度
-1.2778819631550336 // 金地距离，单位 AU
-0.7262651056423838 // 金日距离，单位 AU
+49.98142313573699 // 金星相位角，单位度
+0.8215179742647736 // 金星被照亮比例
+255.63803631896667 // 金星亮面中心位置角，单位度
+1.2778823747747166 // 金地距离，单位 AU
+0.7262651318993368 // 金日距离，单位 AU
 ```

 内外行星同样提供 `Diameter` / `Semidiameter`（以及 `N` 版），返回地心视直径/视半径，单位为角秒。
@@ -322,7 +348,7 @@ fmt.Println(venus.AscendingNode(date), venus.DescendingNode(date))
 76.86008484515058 256.8600848451506 // 金星升交点、降交点黄经，单位度
 ```

-水星和金星还提供 `NextTransit` / `LastTransit` / `ClosestTransit` 地心凌日查询。这里的“地心”指从地球中心看到的行星圆面经过太阳圆面，不判断某个地点当时太阳是否在地平线上；如果要做观测计划，还需要结合本地太阳高度角和天气条件。
+水星和金星还提供 `NextTransit` / `LastTransit` / `ClosestTransit` 地心凌日查询。这里的“地心”指从地球中心看到的行星圆面经过太阳圆面，不判断某个地点当时太阳是否在地平线上；观测计划用 `LocalTransit` 求站心接触与当时太阳高度（见[水星与金星凌日](#水星与金星凌日)）。

 ```go
 package main
@@ -365,22 +391,22 @@ func main() {

 ```text
 true // 找到一次有效的地心水星凌日
-2019-11-11 12:35:31.567597389 +0000 UTC // 一触：水星外切进入太阳圆面
-2019-11-11 12:37:12.817581295 +0000 UTC // 二触：水星完全进入太阳圆面
-2019-11-11 15:19:48.36056292 +0000 UTC // 凌甚：水星中心最接近太阳中心
-2019-11-11 18:02:29.176982045 +0000 UTC // 三触：水星开始离开太阳圆面
-2019-11-11 18:04:10.637948513 +0000 UTC // 四触：水星外切离开太阳圆面
-5h28m39.070351124s // 一触到四触的地心凌日持续时间
-75.92400059923187 // 凌甚时水星中心与太阳中心的最小角距离，单位角秒
-968.8881519533047 // 凌甚时太阳视半径，单位角秒
-4.978442871670873 // 凌甚时水星视半径，单位角秒
+2019-11-11 12:35:31.142292916 +0000 UTC // 一触：水星外切进入太阳圆面
+2019-11-11 12:37:12.603219151 +0000 UTC // 二触：水星完全进入太阳圆面
+2019-11-11 15:19:48.146160542 +0000 UTC // 凌甚：水星中心最接近太阳中心
+2019-11-11 18:02:28.751637339 +0000 UTC // 三触：水星开始离开太阳圆面
+2019-11-11 18:04:10.212523341 +0000 UTC // 四触：水星外切离开太阳圆面
+5h28m39.070230425s // 一触到四触的地心凌日持续时间
+75.93592092696468 // 凌甚时水星中心与太阳中心的最小角距离，单位角秒
+968.8881399120452 // 凌甚时太阳视半径，单位角秒
+4.978442587642365 // 凌甚时水星视半径，单位角秒
 true // 找到一次有效的地心金星凌日
-2012-06-05 22:09:47.466886639 +0000 UTC // 一触：金星外切进入太阳圆面
-2012-06-05 22:27:35.865356326 +0000 UTC // 二触：金星完全进入太阳圆面
-2012-06-06 01:29:35.572371482 +0000 UTC // 凌甚：金星中心最接近太阳中心
-2012-06-06 04:31:35.068444311 +0000 UTC // 三触：金星开始离开太阳圆面
-2012-06-06 04:49:23.25597167 +0000 UTC // 四触：金星外切离开太阳圆面
-6h39m35.789085031s // 一触到四触的地心凌日持续时间
+2012-06-05 22:09:48.690456748 +0000 UTC // 一触：金星外切进入太阳圆面
+2012-06-05 22:27:37.088886201 +0000 UTC // 二触：金星完全进入太阳圆面
+2012-06-06 01:29:36.58495903 +0000 UTC // 凌甚：金星中心最接近太阳中心
+2012-06-06 04:31:35.87008953 +0000 UTC // 三触：金星开始离开太阳圆面
+2012-06-06 04:49:24.268559217 +0000 UTC // 四触：金星外切离开太阳圆面
+6h39m35.578102469s // 一触到四触的地心凌日持续时间
 ```

 ### 外行星
@@ -440,20 +466,19 @@ func main() {

 输出结果：

-```
-2020-10-14 07:25:50.441412627 +0800 CST // 火星下次冲日
-2021-01-29 09:39:33.697994649 +0800 CST // 木星下次合日
-2019-04-30 10:28:00.187439918 +0800 CST // 土星上次由顺行转逆行的留
-saturn B=23.577025 Bp=23.266930 P=6.629811 dU=1.171016 major=34.133852 minor=13.652911 // 土星环 B、B'、P、dU、长轴、短轴
-2020-01-11 15:23:23.360308706 +0800 CST // 天王星下次由逆行转顺行的留
-2019-12-08 17:00:15.517960488 +0800 CST // 海王星上次东方照
-2020-06-07 03:11:00.026179254 +0800 CST // 火星下次西方照
-2020-01-01 04:41:29.621566236 +0800 CST <nil> // 西安当天火星升起时刻；无错误
-2020-01-01 14:55:32.963508367 +0800 CST <nil> // 西安当天火星落下时刻；无错误
+```text
+2020-10-14 07:25:53.541214764 +0800 CST // 火星下次冲日
+2021-01-29 09:39:32.556620836 +0800 CST // 木星下次合日
+2019-04-30 10:28:17.254818677 +0800 CST // 土星上次由顺行转逆行的留
+saturn B=23.577010 Bp=23.266930 P=6.629810 dU=1.171003 major=34.133617 minor=13.652809 // 土星环 B、B'、P、dU、长轴、短轴
+2020-01-11 15:22:18.532456755 +0800 CST // 天王星下次由逆行转顺行的留
+2019-12-08 17:00:04.494322836 +0800 CST // 海王星上次东方照
+2020-06-07 03:10:55.059157311 +0800 CST // 火星下次西方照
+2020-01-01 04:41:30.157055854 +0800 CST <nil> // 西安当天火星升起时刻；无错误
+2020-01-01 14:55:32.792302966 +0800 CST <nil> // 西安当天火星落下时刻；无错误
 1.57 // 火星视星等
-2.1844284956325937 // 地火距离，单位 AU
-1.5897860004265403 // 日火距离，单位 AU
-
+2.1844226019239925 // 地火距离，单位 AU
+1.5897858533008575 // 日火距离，单位 AU
 ```

 `saturn.Ring` 返回 `RingInfo`：`EarthLatitude` 是土星环张角 B，`SunLatitude` 是 B'，`PositionAngle` 是北半短轴位置角，`DeltaU` 是太阳与地球在环面内的土星心黄经差，`MajorAxis` / `MinorAxis` 是土星环外缘长短轴，单位为角秒。
@@ -478,7 +503,7 @@ fmt.Println(venus.EarthDistance(date), venus.SunDistance(date))

 ### 升落与中天

-`RiseTime` / `SetTime` / `DownTime` 按**当地民用日**搜索：`date` 用于确定当地日期与输出时区（当地小时数大于 12 时内部先回退 12 小时），`height` 是椭球高（米），`aero` 为 `true` 时加入标准大气折射（几何地平线降到约 `-0.5667°`）。极昼、极夜或当天没有过零时返回[哨兵错误](#参数与返回值约定)而不是时刻。`CulminationTime` 给上中天；`Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` 是站心瞬时量族，几何公式见[坐标工具](coord.md)。
+`RiseTime` / `SetTime` / `DownTime` 按**当地民用日**搜索：`date` 用于确定当地日期与输出时区，返回的事件属于该当地民用日；`height` 是椭球高（米），`aero` 为 `true` 时加入标准大气折射（几何地平线降到约 `-0.5667°`）。极昼、极夜或当天没有过零时返回[哨兵错误](#参数与返回值约定)而不是时刻。`CulminationTime` 给上中天；`Altitude` / `Azimuth` / `Zenith` 是站心瞬时量，`HourAngle` / `ParallacticAngle` 是地心瞬时量，几何公式见[坐标工具](coord.md)。

 ```go
 // 西安市当地民用日内的升起、落下与中天；aero=true 含标准大气折射。
@@ -489,14 +514,14 @@ fmt.Println(mars.CulminationTime(date, lon))
 ```

 ```go
-// 站心地平量：经度东正西负、纬度北正南负，返回值单位度。
+// 地平量：经度东正西负、纬度北正南负，返回值单位度。
 fmt.Println(mars.Altitude(date, lon, lat), mars.Azimuth(date, lon, lat))
 fmt.Println(mars.Zenith(date, lon, lat), mars.HourAngle(date, lon))
 fmt.Println(mars.ParallacticAngle(date, lon, lat))
 ```

 ```go
-// DownTime 是 SetTime 的兼容别名；N 版按截断项求值。
+// DownTime 是 SetTime 的兼容别名；N 版按 `n` 变体求值。
 set, err := mars.DownTime(date, lon, lat, height, true)
 fmt.Println(set, err)
 fmt.Println(mars.CulminationTimeN(date, lon, 12))
@@ -560,7 +585,7 @@ fmt.Println(transit.SunSemidiameterArcsec, transit.PlanetSemidiameterArcsec)

 `AscendingNode` / `DescendingNode` 是行星轨道面与黄道面两个交点的黄经，单位度，同一时刻两者相差约 `180°`。`PhaseAngle` 是太阳–行星–地球夹角（度）；`IlluminatedFraction`（别名 `Phase`）是 `0–1` 的被照亮比例；`BrightLimbPositionAngle` 是亮面中心位置角（度）。`Diameter` / `Semidiameter` 返回地心视直径/视半径，单位角秒。

-`ParallacticAngle` 返回站心视差角（天顶方向角，度），站心坐标入口见[坐标工具](coord.md)。
+`ParallacticAngle` 返回地心视差角（天顶方向角，度），由地心时角与赤纬求得，不含站心视差；站心坐标入口见[坐标工具](coord.md)。

 ```go
 fmt.Println(mars.AscendingNode(date), mars.DescendingNode(date))                     // 升降交点黄经，度
@@ -574,7 +599,7 @@ fmt.Println(mars.ParallacticAngle(date, lon, lat))        // 视差角，度
 ```

 ```go
-// 交点与视直径同样有截断版。
+// 交点与视直径同样有 `n` 变体。
 fmt.Println(mars.AscendingNodeN(date, 12), mars.DescendingNodeN(date, 12))
 fmt.Println(mars.DiameterN(date, 12), mars.SemidiameterN(date, 12))
 ```
@@ -632,8 +657,8 @@ func main() {
 输出结果：

 ```text
-jupiter DS=54.342153 DE=1.436485 CMI=292.712909 CMII=276.309048 CMIII=147.241811 // 木星子日/子地赤纬，System I/II/III 中央经线，单位度
-saturn B=-0.608048 Bp=-2.675677 P=4.480276 major=42.709920 minor=0.453248 // 土星环 B、B'、短轴位置角、外缘长短轴，角度单位度，长短轴单位角秒
+jupiter DS=54.342201 DE=1.436449 CMI=292.712946 CMII=276.309085 CMIII=147.241848 // 木星子日/子地赤纬，System I/II/III 中央经线，单位度
+saturn B=-0.608032 Bp=-2.675667 P=4.480277 major=42.709152 minor=0.453228 // 土星环 B、B'、短轴位置角、外缘长短轴，角度单位度，长短轴单位角秒
 ```

 只需要中央经线时，可以单独调用 `CentralMeridians`：
@@ -660,7 +685,7 @@ fmt.Println(p.SubEarthLongitude, p.SubEarthLatitude, p.SubSolarLongitude, p.SubS
 ```

 ```go
-// 土星环与木星中央经线的截断版。
+// 土星环与木星中央经线的 `n` 变体。
 fmt.Println(saturn.RingN(date, 12).MinorAxis, jupiter.CentralMeridiansN(date, 12).SystemIII)
 ```

@@ -753,8 +778,8 @@ func main() {
 输出结果：

 ```text
-io x=-0.675026 y=-0.032798 front=true // 木卫一相对木星中心的 X/Y 偏移，单位木星半径；位于木星盘面前方
-europa ra=110.769133 dec=22.335828 // 木卫二视赤经、视赤纬，单位度
+io x=-0.675023 y=-0.032794 front=true // 木卫一相对木星中心的 X/Y 偏移，单位木星半径；位于木星盘面前方
+europa ra=110.769095 dec=22.335877 // 木卫二视赤经、视赤纬，单位度
 io transit=true occultation=false eclipse=false shadow=true // 木卫一正在凌日，且影子正在凌日
 europa transit=false occultation=false eclipse=false shadow=false // 木卫二此刻无凌日、掩蔽、木星食或影凌
 event valid=true sat=1 type=transit // 下一次有效事件为木卫一凌日
@@ -786,13 +811,13 @@ contact valid=true sat=2 type=occultation // 下一次有效接触事件为木
 - `GalileanPhenomenonContactEvent` 与 IMCCE 2026 年表的 D/F 接触时刻最大偏差约 `79 s`，接触持续时间最大偏差约 `17 s`。
 - `GalileanPhenomenonEvent` 与 IMCCE 的 D/F 接触定义不同，起止时刻的差异可达约 `7` 分钟。

-### 与 `planet` 包共用的类型与常量
+### 与 `planet` 包共用的低层入口

-`planet` 包是低层解析级数入口，被七个行星包与 `sun` / `moon` 共用。它只导出函数，**没有导出类型**，所以行星包之间真正共用的是同一套数值口径与截断语义，而不是共享类型：各包的 `PhysicalInfo` 是 `basic.PlanetPhysicalInfo` 的镜面结构，`TransitInfo` 是 `basic.PlanetTransitResult` 的镜面结构，字段一一对应，类型本身仍属于各自的包。
+`planet` 包提供内置模型与级数的低层入口，被七个行星包与 `sun` / `moon` 共用。它只导出函数，没有导出类型；行星包共用的是数值口径与模型选择，而不是结果类型。各包的 `PhysicalInfo` 与 `basic.PlanetPhysicalInfo`、`TransitInfo` 与 `basic.PlanetTransitResult` 字段一一对应，类型本身仍属于各自的包。外部核引擎类型位于独立子包 `planet/spk`。

 | 入口 | 作用 | 单位 |
 | --- | --- | --- |
-| `planet.WherePlanet` / `planet.WherePlanetN` | VSOP87 结果：`xt` 取 `1..7` 依次为水星到海王星、`-1` 或 `0` 为地球，`zn` 取 `0` 黄经、`1` 黄纬、`2` 日心距；`xt` / `zn` 越界返回 `NaN` 而不 panic | 度 / AU |
+| `planet.WherePlanet` / `planet.WherePlanetN` | 当前内置模型结果：`xt` 取 `1..7` 依次为水星到海王星、`-1` 或 `0` 为地球，`zn` 取 `0` 黄经、`1` 黄纬、`2` 日心距；`xt` / `zn` 越界返回 `NaN` 而不 panic | 度 / AU |
 | `planet.Distance` | 日地距离 | AU |
 | `planet.SunLo` / `planet.SunM` / `planet.SunMidFun` / `planet.SunTrueLo` / `planet.SunApparentLo` | 太阳几何黄经、平近点角、中心差、真黄经、视黄经 | 度 |
 | `planet.Earthe` / `planet.EarthPI` | 地球轨道偏心率、地球近日点黄经 | 无量纲 / 度 |
@@ -803,7 +828,7 @@ contact valid=true sat=2 type=occultation // 下一次有效接触事件为木
 ```go
 // xt=1..7 对应水星..海王星；zn=0 黄经、1 黄纬、2 日心距（AU）。
 fmt.Println(planet.WherePlanet(4, 2, 2460000.5))      // 木星日心距，AU
-fmt.Println(planet.WherePlanetN(4, 2, 2460000.5, 12)) // 截断版，保留约 12 个主项
+fmt.Println(planet.WherePlanetN(4, 2, 2460000.5, 12)) // 半解析快速表；Legacy 按 n 截断。
 fmt.Println(planet.WherePlanet(8, 0, 2460000.5))      // xt 越界：NaN
 ```

@@ -826,17 +851,17 @@ fmt.Println(planet.WherePlanet(-1, 0, 2460000.5), planet.WherePlanet(4, 0, 24600

 角度一律为度；视直径与视半径为角秒；距离按函数名区分——`EarthDistance` / `SunDistance` 与 `planet.WherePlanet` 的 `zn=2` 用 AU，`planet.MoonAway` 用 km。

-`PhaseAngle` 为度，`IlluminatedFraction` 与别名 `Phase` 为 `0–1`；`ApparentMagnitude` 为星等（无量纲）；升落、中天与所有事件搜索返回 `time.Time`，时区与输入一致。
+`PhaseAngle` 为度，`IlluminatedFraction` 与别名 `Phase` 为 `0–1`；`ApparentMagnitude` 为星等（无量纲，经典相位多项式）；`ApparentMagnitude2018` 用 Mallama & Hilton 2018 模型，水星、金星大相位角与土星环更准，火星不含自转与季节修正；升落、中天与所有事件搜索返回 `time.Time`，时区与输入一致。

 事件结构里的历时字段（`TransitInfo.Duration`、`TransitInfo.InternalDuration`、`GalileanPhenomenonEvent.Duration`、`GalileanPhenomenonContact.Duration`）是 Go 的 `time.Duration`，不是儒略日或天数；`TransitInfo` 的 `Start` / `Greatest` / `End` / `InternalStart` / `InternalEnd` 保持调用者输入的时区。

-地心量、站心量与距离是三个不同口径：`ApparentLo` / `ApparentBo` / `ApparentRa` / `ApparentDec` / `ApparentRaDec` 是地心视位置，`Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` 是站心量，`EarthDistance` / `SunDistance` 是地心几何距离。
+地心量、站心量与距离是三个不同口径：`ApparentLo` / `ApparentBo` / `ApparentRa` / `ApparentDec` / `ApparentRaDec` 是地心视位置，`Altitude` / `Azimuth` / `Zenith` 是站心量，`HourAngle` / `ParallacticAngle` 是不含站心视差的地心量，`EarthDistance` / `SunDistance` 是地心几何距离。

 ### 零值、越界与哨兵错误

 事件搜索在窗口内没有事件时返回零值或 `Valid=false` 的结构（`TransitInfo.Valid`、`GalileanPhenomenonEvent.Valid`、`GalileanPhenomenonContactEvent.Valid`），不返回错误；`TransitInfo` 在 `HasInternal` 为假时 `InternalStart` / `InternalEnd` 为零值，偏凌日没有内切。

-`planet.WherePlanet` / `planet.WherePlanetN` 的 `xt` / `zn` 越界返回 `NaN` 而不 panic；`...N` 截断族的 `n < 0` 用全部内置项、`n >= 0` 截断。`RiseTime` / `SetTime` / `DownTime`（含 `N` 版）是唯一返回 `error` 的一族：当天没有几何升/落时返回下面的哨兵错误，时刻为零值。
+`planet.WherePlanet` / `planet.WherePlanetN` 的 `xt` / `zn` 越界返回 `NaN` 而不 panic；`...N` 的 `n < 0` 用完整级数，半解析的非负 `n` 用同一张快速表，Legacy 按 `n` 截断。`RiseTime` / `SetTime` / `DownTime`（含 `N` 版）当天没有几何升/落时返回下面的哨兵错误，时刻为零值。

 每个行星包各有一套极昼/极夜错误，名字里的 `NEVER_RISE` 指"当天永不升起"（极夜），`NEVER_SET` 指"当天永不落下"（极昼），`NEVER_DOWN` 是 `NEVER_SET` 的兼容别名。

@@ -863,10 +888,10 @@ case errors.Is(err, mercury.ERR_MERCURY_NEVER_SET):

 ### 站心与地心

-`Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` 使用 `date` 的时区做地方时计算，经度东正西负、纬度北正南负，`height` 是椭球高（米，不是海拔正高）。它们与 `ApparentRa` / `ApparentDec` 的地心视位置不是一个口径，跨口径使用前先经[坐标工具](coord.md)换算。
+`Altitude` / `Azimuth` / `Zenith` / `HourAngle` / `ParallacticAngle` 使用 `date` 的时区做地方时计算，经度东正西负、纬度北正南负，`height` 是椭球高（米，不是海拔正高）。其中 `Altitude` / `Azimuth` / `Zenith` 计入站心视差，与 `ApparentRa` / `ApparentDec` 的地心视位置不是一个口径；`HourAngle` / `ParallacticAngle` 直接由地心视位置求得，不含站心视差，跨口径使用前先经[坐标工具](coord.md)换算。

 ### 精度与适用范围

-行星包使用内置 VSOP87 截断级数，覆盖 J2000 前后约 4000 年；相对完整 VSOP87 的截断误差量级见[太阳与行星](accuracy.md#太阳与行星)，整体适用范围见[适用范围与精度](accuracy.md)。`...N` 截断版会在这条基线之上继续放宽，适合批量扫描或前端实时刷新。
+行星包默认使用半解析模型，也可选择 Legacy 或自定义引擎。可用区间不代表全范围精度相同，Legacy 相对完整 VSOP87 的截断误差也不等于对 DE 星历的综合误差，详见[Legacy 截断误差](accuracy.md#legacy-截断误差)。快速表适合粗扫描；需要精修事件或比较外部年表时使用完整级数并统一时标与坐标口径。

 `saturn.Ring` 与物理星历只影响盘面与掩带表达：土星环既不参与月掩接触计算、也不作为圆盘边界绘制。行星没有独立出图入口，月掩与土星环的出图见[月掩手册](occultation.md#月掩出图)。