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

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

basic/planet_phase.go

@@ -1,7 +1,6 @@
 package basic
 
 import (
-	"b612.me/astro/planet"
 	. "b612.me/astro/tools"
 )
 
@@ -12,9 +11,9 @@ func MercuryPhaseAngle(jde float64) float64 {
 	return MercuryPhaseAngleN(jde, -1)
 }
 
-// MercuryPhaseAngleN 水星相位角（截断版） / truncated phase angle of Mercury.
-func MercuryPhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(1, jd, n)
+// MercuryPhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func MercuryPhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(1, jd, n, inst)
 }
 
 // MercuryIlluminatedFraction 水星被照亮比例 / illuminated fraction of Mercury.
@@ -22,9 +21,9 @@ func MercuryIlluminatedFraction(jd float64) float64 {
 	return MercuryIlluminatedFractionN(jd, -1)
 }
 
-// MercuryIlluminatedFractionN 水星被照亮比例（截断版） / truncated illuminated fraction of Mercury.
-func MercuryIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(1, jd, n)
+// MercuryIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func MercuryIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(1, jd, n, inst)
 }
 
 // MercuryBrightLimbPositionAngle 水星亮面中心位置角 / position angle of Mercury bright limb.
@@ -32,9 +31,9 @@ func MercuryBrightLimbPositionAngle(jde float64) float64 {
 	return MercuryBrightLimbPositionAngleN(jde, -1)
 }
 
-// MercuryBrightLimbPositionAngleN 水星亮面中心位置角（截断版） / truncated position angle of Mercury bright limb.
-func MercuryBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, MercuryApparentRaDecN)
+// MercuryBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func MercuryBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jde float64, n int) (float64, float64) { return MercuryApparentRaDecNWithInstance(jde, n, inst) }, inst)
 }
 
 // VenusPhaseAngle 金星相位角 / phase angle of Venus.
@@ -42,9 +41,9 @@ func VenusPhaseAngle(jde float64) float64 {
 	return VenusPhaseAngleN(jde, -1)
 }
 
-// VenusPhaseAngleN 金星相位角（截断版） / truncated phase angle of Venus.
-func VenusPhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(2, jd, n)
+// VenusPhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func VenusPhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(2, jd, n, inst)
 }
 
 // VenusIlluminatedFraction 金星被照亮比例 / illuminated fraction of Venus.
@@ -52,9 +51,9 @@ func VenusIlluminatedFraction(jd float64) float64 {
 	return VenusIlluminatedFractionN(jd, -1)
 }
 
-// VenusIlluminatedFractionN 金星被照亮比例（截断版） / truncated illuminated fraction of Venus.
-func VenusIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(2, jd, n)
+// VenusIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func VenusIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(2, jd, n, inst)
 }
 
 // VenusBrightLimbPositionAngle 金星亮面中心位置角 / position angle of Venus bright limb.
@@ -62,9 +61,9 @@ func VenusBrightLimbPositionAngle(jde float64) float64 {
 	return VenusBrightLimbPositionAngleN(jde, -1)
 }
 
-// VenusBrightLimbPositionAngleN 金星亮面中心位置角（截断版） / truncated position angle of Venus bright limb.
-func VenusBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, VenusApparentRaDecN)
+// VenusBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func VenusBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jd float64, n int) (float64, float64) { return VenusApparentRaDecNWithInstance(jd, n, inst) }, inst)
 }
 
 // MarsPhaseAngle 火星相位角 / phase angle of Mars.
@@ -72,9 +71,9 @@ func MarsPhaseAngle(jde float64) float64 {
 	return MarsPhaseAngleN(jde, -1)
 }
 
-// MarsPhaseAngleN 火星相位角（截断版） / truncated phase angle of Mars.
-func MarsPhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(3, jd, n)
+// MarsPhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func MarsPhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(3, jd, n, inst)
 }
 
 // MarsIlluminatedFraction 火星被照亮比例 / illuminated fraction of Mars.
@@ -82,9 +81,9 @@ func MarsIlluminatedFraction(jd float64) float64 {
 	return MarsIlluminatedFractionN(jd, -1)
 }
 
-// MarsIlluminatedFractionN 火星被照亮比例（截断版） / truncated illuminated fraction of Mars.
-func MarsIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(3, jd, n)
+// MarsIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func MarsIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(3, jd, n, inst)
 }
 
 // MarsBrightLimbPositionAngle 火星亮面中心位置角 / position angle of Mars bright limb.
@@ -92,9 +91,9 @@ func MarsBrightLimbPositionAngle(jde float64) float64 {
 	return MarsBrightLimbPositionAngleN(jde, -1)
 }
 
-// MarsBrightLimbPositionAngleN 火星亮面中心位置角（截断版） / truncated position angle of Mars bright limb.
-func MarsBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, MarsApparentRaDecN)
+// MarsBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func MarsBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jd float64, n int) (float64, float64) { return MarsApparentRaDecNWithInstance(jd, n, inst) }, inst)
 }
 
 // JupiterPhaseAngle 木星相位角 / phase angle of Jupiter.
@@ -102,9 +101,9 @@ func JupiterPhaseAngle(jde float64) float64 {
 	return JupiterPhaseAngleN(jde, -1)
 }
 
-// JupiterPhaseAngleN 木星相位角（截断版） / truncated phase angle of Jupiter.
-func JupiterPhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(4, jd, n)
+// JupiterPhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func JupiterPhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(4, jd, n, inst)
 }
 
 // JupiterIlluminatedFraction 木星被照亮比例 / illuminated fraction of Jupiter.
@@ -112,9 +111,9 @@ func JupiterIlluminatedFraction(jd float64) float64 {
 	return JupiterIlluminatedFractionN(jd, -1)
 }
 
-// JupiterIlluminatedFractionN 木星被照亮比例（截断版） / truncated illuminated fraction of Jupiter.
-func JupiterIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(4, jd, n)
+// JupiterIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func JupiterIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(4, jd, n, inst)
 }
 
 // JupiterBrightLimbPositionAngle 木星亮面中心位置角 / position angle of Jupiter bright limb.
@@ -122,9 +121,9 @@ func JupiterBrightLimbPositionAngle(jde float64) float64 {
 	return JupiterBrightLimbPositionAngleN(jde, -1)
 }
 
-// JupiterBrightLimbPositionAngleN 木星亮面中心位置角（截断版） / truncated position angle of Jupiter bright limb.
-func JupiterBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, JupiterApparentRaDecN)
+// JupiterBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func JupiterBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jd float64, n int) (float64, float64) { return JupiterApparentRaDecNWithInstance(jd, n, inst) }, inst)
 }
 
 // SaturnPhaseAngle 土星相位角 / phase angle of Saturn.
@@ -132,9 +131,9 @@ func SaturnPhaseAngle(jde float64) float64 {
 	return SaturnPhaseAngleN(jde, -1)
 }
 
-// SaturnPhaseAngleN 土星相位角（截断版） / truncated phase angle of Saturn.
-func SaturnPhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(5, jd, n)
+// SaturnPhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func SaturnPhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(5, jd, n, inst)
 }
 
 // SaturnIlluminatedFraction 土星被照亮比例 / illuminated fraction of Saturn.
@@ -142,9 +141,9 @@ func SaturnIlluminatedFraction(jd float64) float64 {
 	return SaturnIlluminatedFractionN(jd, -1)
 }
 
-// SaturnIlluminatedFractionN 土星被照亮比例（截断版） / truncated illuminated fraction of Saturn.
-func SaturnIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(5, jd, n)
+// SaturnIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func SaturnIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(5, jd, n, inst)
 }
 
 // SaturnBrightLimbPositionAngle 土星亮面中心位置角 / position angle of Saturn bright limb.
@@ -152,9 +151,9 @@ func SaturnBrightLimbPositionAngle(jde float64) float64 {
 	return SaturnBrightLimbPositionAngleN(jde, -1)
 }
 
-// SaturnBrightLimbPositionAngleN 土星亮面中心位置角（截断版） / truncated position angle of Saturn bright limb.
-func SaturnBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, SaturnApparentRaDecN)
+// SaturnBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func SaturnBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jd float64, n int) (float64, float64) { return SaturnApparentRaDecNWithInstance(jd, n, inst) }, inst)
 }
 
 // UranusPhaseAngle 天王星相位角 / phase angle of Uranus.
@@ -162,9 +161,9 @@ func UranusPhaseAngle(jde float64) float64 {
 	return UranusPhaseAngleN(jde, -1)
 }
 
-// UranusPhaseAngleN 天王星相位角（截断版） / truncated phase angle of Uranus.
-func UranusPhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(6, jd, n)
+// UranusPhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func UranusPhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(6, jd, n, inst)
 }
 
 // UranusIlluminatedFraction 天王星被照亮比例 / illuminated fraction of Uranus.
@@ -172,9 +171,9 @@ func UranusIlluminatedFraction(jd float64) float64 {
 	return UranusIlluminatedFractionN(jd, -1)
 }
 
-// UranusIlluminatedFractionN 天王星被照亮比例（截断版） / truncated illuminated fraction of Uranus.
-func UranusIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(6, jd, n)
+// UranusIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func UranusIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(6, jd, n, inst)
 }
 
 // UranusBrightLimbPositionAngle 天王星亮面中心位置角 / position angle of Uranus bright limb.
@@ -182,9 +181,9 @@ func UranusBrightLimbPositionAngle(jde float64) float64 {
 	return UranusBrightLimbPositionAngleN(jde, -1)
 }
 
-// UranusBrightLimbPositionAngleN 天王星亮面中心位置角（截断版） / truncated position angle of Uranus bright limb.
-func UranusBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, UranusApparentRaDecN)
+// UranusBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func UranusBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jd float64, n int) (float64, float64) { return UranusApparentRaDecNWithInstance(jd, n, inst) }, inst)
 }
 
 // NeptunePhaseAngle 海王星相位角 / phase angle of Neptune.
@@ -192,9 +191,9 @@ func NeptunePhaseAngle(jde float64) float64 {
 	return NeptunePhaseAngleN(jde, -1)
 }
 
-// NeptunePhaseAngleN 海王星相位角（截断版） / truncated phase angle of Neptune.
-func NeptunePhaseAngleN(jd float64, n int) float64 {
-	return planetPhaseAngleN(7, jd, n)
+// NeptunePhaseAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func NeptunePhaseAngleNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetPhaseAngleN(7, jd, n, inst)
 }
 
 // NeptuneIlluminatedFraction 海王星被照亮比例 / illuminated fraction of Neptune.
@@ -202,9 +201,9 @@ func NeptuneIlluminatedFraction(jd float64) float64 {
 	return NeptuneIlluminatedFractionN(jd, -1)
 }
 
-// NeptuneIlluminatedFractionN 海王星被照亮比例（截断版） / truncated illuminated fraction of Neptune.
-func NeptuneIlluminatedFractionN(jd float64, n int) float64 {
-	return planetIlluminatedFractionN(7, jd, n)
+// NeptuneIlluminatedFractionNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func NeptuneIlluminatedFractionNWithInstance(jd float64, n int, inst *Instance) float64 {
+	return planetIlluminatedFractionN(7, jd, n, inst)
 }
 
 // NeptuneBrightLimbPositionAngle 海王星亮面中心位置角 / position angle of Neptune bright limb.
@@ -212,29 +211,37 @@ func NeptuneBrightLimbPositionAngle(jde float64) float64 {
 	return NeptuneBrightLimbPositionAngleN(jde, -1)
 }
 
-// NeptuneBrightLimbPositionAngleN 海王星亮面中心位置角（截断版） / truncated position angle of Neptune bright limb.
-func NeptuneBrightLimbPositionAngleN(jde float64, n int) float64 {
-	return planetBrightLimbPositionAngleN(jde, n, NeptuneApparentRaDecN)
+// NeptuneBrightLimbPositionAngleNWithInstance 用指定星历实例求值；inst 为 nil 时用进程当前模型 / evaluation with an explicit instance; nil uses the process model.
+func NeptuneBrightLimbPositionAngleNWithInstance(jde float64, n int, inst *Instance) float64 {
+	return planetBrightLimbPositionAngleN(jde, n, func(jd float64, n int) (float64, float64) { return NeptuneApparentRaDecNWithInstance(jd, n, inst) }, inst)
 }
 
-func planetPhaseAngleN(planetIndex int, jd float64, n int) float64 {
-	return ArcCos(planetPhaseCosineN(planetIndex, jd, n))
+func planetPhaseAngleN(planetIndex int, jd float64, n int, instances ...*Instance) float64 {
+	inst := instanceValue(instances)
+
+	return ArcCos(planetPhaseCosineN(planetIndex, jd, n, inst))
 }
 
-func planetIlluminatedFractionN(planetIndex int, jd float64, n int) float64 {
-	return (1 + planetPhaseCosineN(planetIndex, jd, n)) / 2
+func planetIlluminatedFractionN(planetIndex int, jd float64, n int, instances ...*Instance) float64 {
+	inst := instanceValue(instances)
+
+	return (1 + planetPhaseCosineN(planetIndex, jd, n, inst)) / 2
 }
 
-func planetPhaseCosineN(planetIndex int, jde float64, n int) float64 {
-	planetSunDistance := planet.WherePlanetN(planetIndex, 2, jde, n)
-	planetEarthDistance := planetEarthAwayN(planetIndex, jde, n)
-	earthSunDistance := EarthAwayN(jde, n)
+func planetPhaseCosineN(planetIndex int, jde float64, n int, instances ...*Instance) float64 {
+	inst := instanceValue(instances)
+
+	planetSunDistance := PlanetCoordinateNWithInstance(planetIndex, 2, jde, n, inst)
+	planetEarthDistance := planetEarthAwayNWithInstance(planetIndex, jde, n, inst)
+	earthSunDistance := EarthAwayNWithInstance(jde, n, inst)
 	cosine := (planetSunDistance*planetSunDistance + planetEarthDistance*planetEarthDistance - earthSunDistance*earthSunDistance) / (2 * planetSunDistance * planetEarthDistance)
 	return clampUnit(cosine)
 }
 
-func planetBrightLimbPositionAngleN(jde float64, n int, apparentRaDec planetRaDecNFunc) float64 {
-	sunRa, sunDec := HSunApparentRaDecN(jde, n)
+func planetBrightLimbPositionAngleN(jde float64, n int, apparentRaDec planetRaDecNFunc, instances ...*Instance) float64 {
+	inst := instanceValue(instances)
+
+	sunRa, sunDec := HSunApparentRaDecNWithInstance(jde, n, inst)
 	planetRa, planetDec := apparentRaDec(jde, n)
 	y := Cos(sunDec) * Sin(sunRa-planetRa)
 	x := Sin(sunDec)*Cos(planetDec) - Cos(sunDec)*Sin(planetDec)*Cos(sunRa-planetRa)