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

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

basic/moon_phase_ephemeris_instance.go

@@ -0,0 +1,115 @@
+package basic
+
+import (
+	"math"
+
+	. "b612.me/astro/tools"
+)
+
+func sunMoonSeekWithInstance(jde, degree float64, inst *Instance) float64 {
+	if inst == nil {
+		return SunMoonSeek(jde, degree)
+	}
+	p := HMoonApparentLoWithInstance(jde, inst) - HSunApparentLoWithInstance(jde, inst) - degree
+	for p < -180 {
+		p += 360
+	}
+	for p > 180 {
+		p -= 360
+	}
+	return p
+}
+
+func refineSunMoonPhaseWithInstance(jde, degree float64, inst *Instance) float64 {
+	estimateJD, ok := eventNewtonRefine(jde, 0.00001, func(prevJD float64) float64 {
+		value := sunMoonSeekWithInstance(prevJD, degree, inst)
+		slope := (sunMoonSeekWithInstance(prevJD+0.000005, degree, inst) - sunMoonSeekWithInstance(prevJD-0.000005, degree, inst)) / 0.00001
+		return value / slope
+	})
+	if !ok {
+		return math.NaN()
+	}
+	return estimateJD
+}
+
+// MoonPhaseWithInstance 月球照明比例 / illuminated lunar fraction with an explicit ephemeris instance.
+func MoonPhaseWithInstance(jde float64, inst *Instance) float64 {
+	if inst == nil {
+		return MoonPhase(jde)
+	}
+	moonBo := HMoonTrueBoWithInstance(jde, inst)
+	sunLo := HSunApparentLoWithInstance(jde, inst)
+	moonLo := HMoonApparentLoWithInstance(jde, inst)
+	tmp := Cos(moonBo) * Cos(sunLo-moonLo)
+	earthSunDistance := EarthAwayNWithInstance(jde, -1, inst) * astronomicalUnitKM
+	i := earthSunDistance * Sin(ArcCos(tmp)) / (HMoonAwayWithInstance(jde, inst) - earthSunDistance*tmp)
+	i = ArcTan(i)
+	if i < 0 {
+		i += 180
+	}
+	if i > 180 {
+		i -= 180
+	}
+	return (1 + Cos(i)) / 2
+}
+
+// SunMoonSeekWithInstance 日月黄经差相位残差 / Sun-Moon longitude phase residual with an explicit ephemeris instance.
+func SunMoonSeekWithInstance(jde, degree float64, inst *Instance) float64 {
+	return sunMoonSeekWithInstance(jde, degree, inst)
+}
+
+// CalcMoonSHByJDEWithInstance 按历元求朔望时刻 / calculate a syzygy from an epoch with an explicit ephemeris instance.
+func CalcMoonSHByJDEWithInstance(jde float64, phaseType int, inst *Instance) float64 {
+	if inst == nil {
+		return CalcMoonSHByJDE(jde, phaseType)
+	}
+	return refineSunMoonPhaseWithInstance(jde, float64(phaseType*180), inst)
+}
+
+// CalcMoonSHWithInstance 按年份求朔望时刻 / calculate a syzygy from a year with an explicit ephemeris instance.
+func CalcMoonSHWithInstance(year float64, phaseType int, inst *Instance) float64 {
+	if inst == nil {
+		return CalcMoonSH(year, phaseType)
+	}
+	return refineSunMoonPhaseWithInstance(CalcMoonSWithInstance(year, phaseType, inst), float64(phaseType*180), inst)
+}
+
+// CalcMoonSWithInstance 按年份估算朔望基准时刻 / estimate a syzygy base time from a year with an explicit ephemeris instance.
+func CalcMoonSWithInstance(year float64, phaseType int, inst *Instance) float64 {
+	if inst == nil {
+		return CalcMoonS(year, phaseType)
+	}
+	return CalcMoonS(year, phaseType)
+}
+
+// CalcMoonXHByJDEWithInstance 按历元求弦月时刻 / calculate a quarter phase from an epoch with an explicit ephemeris instance.
+func CalcMoonXHByJDEWithInstance(jde float64, quarterType int, inst *Instance) float64 {
+	if inst == nil {
+		return CalcMoonXHByJDE(jde, quarterType)
+	}
+	degree := -90.0
+	if quarterType == 0 {
+		degree = 90
+	}
+	return refineSunMoonPhaseWithInstance(jde, degree, inst)
+}
+
+// CalcMoonXHWithInstance 按年份求弦月时刻 / calculate a quarter phase from a year with an explicit ephemeris instance.
+func CalcMoonXHWithInstance(year float64, quarterType int, inst *Instance) float64 {
+	if inst == nil {
+		return CalcMoonXH(year, quarterType)
+	}
+	degree := -90.0
+	if quarterType == 0 {
+		degree = 90
+	}
+	return refineSunMoonPhaseWithInstance(CalcMoonXWithInstance(year, quarterType, inst), degree, inst)
+}
+
+// CalcMoonXWithInstance 按年份估算弦月基准时刻 / estimate a quarter-phase base time from a year with an explicit ephemeris instance.
+func CalcMoonXWithInstance(year float64, quarterType int, inst *Instance) float64 {
+	if inst == nil {
+		return CalcMoonX(year, quarterType)
+	}
+	return CalcMoonX(year, quarterType)
+}