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

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

internal/ephemtest/ephemtest.go

@@ -0,0 +1,31 @@
+// Package ephemtest 测试辅助：固定星历模型、按模型选择基线文件。
+package ephemtest
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"b612.me/astro/internal/ephem"
+)
+
+// Pin 在本测试内固定模型，结束后恢复 / pins the model for the duration of a test.
+func Pin(tb testing.TB, m ephem.Model) {
+	prev := ephem.Active()
+	ephem.SetActive(m)
+	tb.Cleanup(func() { ephem.SetActive(prev) })
+}
+
+// PinLegacy 只针对旧级数实现本身的测试使用 / for tests of the legacy series implementation itself.
+func PinLegacy(tb testing.TB) { Pin(tb, ephem.Legacy) }
+
+// Golden 当前模型对应的基线文件：旧模型用原路径，新模型用同目录 semianalytic/ 下的同名文件。
+func Golden(path string) string {
+	if ephem.Active() != ephem.Semianalytic {
+		return path
+	}
+	return filepath.Join(filepath.Dir(path), "semianalytic", filepath.Base(path))
+}
+
+// Update 环境变量 ASTRO_UPDATE_GOLDEN=1 时重写当前模型的基线 / whether to rewrite the active model's baselines.
+func Update() bool { return os.Getenv("ASTRO_UPDATE_GOLDEN") == "1" }

internal/ephemtest/values.go

@@ -0,0 +1,98 @@
+package ephemtest
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"b612.me/astro/internal/ephem"
+)
+
+// Values 按模型取期望值：旧模型用内联常量，新模型用 testdata/semianalytic/<name>.json。
+// 新模型且 Update() 时记录实际值，测试结束写回文件 / per-model expected values for inline-constant tests.
+type Values struct {
+	tb     testing.TB
+	path   string
+	vals   map[string]interface{}
+	semi   bool
+	update bool
+	dirty  bool
+}
+
+// NewValues 打开名为 name 的期望值表 / opens the expected-value table called name.
+func NewValues(tb testing.TB, name string) *Values {
+	tb.Helper()
+	v := &Values{
+		tb:     tb,
+		path:   filepath.Join("testdata", "semianalytic", name+".json"),
+		vals:   map[string]interface{}{},
+		semi:   ephem.Active() == ephem.Semianalytic,
+		update: Update(),
+	}
+	if !v.semi {
+		return v
+	}
+	if data, err := os.ReadFile(v.path); err == nil {
+		if err := json.Unmarshal(data, &v.vals); err != nil {
+			tb.Fatal(err)
+		}
+	} else if !v.update {
+		tb.Fatalf("%v (regenerate with ASTRO_UPDATE_GOLDEN=1 go test)", err)
+	}
+	if v.update {
+		tb.Cleanup(v.flush)
+	}
+	return v
+}
+
+// Want 返回 key 的期望值；legacy 为 0 表示该项不检查，原样返回 0 / expected value for key.
+func (v *Values) Want(key string, legacy, got float64) float64 {
+	v.tb.Helper()
+	if !v.semi || legacy == 0 {
+		return legacy
+	}
+	if v.update {
+		v.vals[key], v.dirty = got, true
+		return got
+	}
+	want, ok := v.vals[key].(float64)
+	if !ok {
+		v.tb.Fatalf("%s: no numeric expected value for %q", v.path, key)
+	}
+	return want
+}
+
+// WantString 同 Want，用于文本期望值；legacy 为空表示不检查 / string variant of Want.
+func (v *Values) WantString(key, legacy, got string) string {
+	v.tb.Helper()
+	if !v.semi || legacy == "" {
+		return legacy
+	}
+	if v.update {
+		v.vals[key], v.dirty = got, true
+		return got
+	}
+	want, ok := v.vals[key].(string)
+	if !ok {
+		v.tb.Fatalf("%s: no string expected value for %q", v.path, key)
+	}
+	return want
+}
+
+func (v *Values) flush() {
+	if !v.dirty {
+		return
+	}
+	data, err := json.MarshalIndent(v.vals, "", "  ")
+	if err != nil {
+		v.tb.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Dir(v.path), 0o755); err != nil {
+		v.tb.Fatal(err)
+	}
+	if err := os.WriteFile(v.path, append(data, '\n'), 0o644); err != nil {
+		v.tb.Fatal(err)
+	}
+	v.tb.Logf("rewrote %s: %d values", v.path, len(v.vals))
+}