---
name: astronomy
description: 天文报告（skyfield 星历真算）；星图、星历、天象任务使用。
---

# astronomy — 天文·天象计算场景 skill

> 上游公共规范：`${SKILL_DIR}/../core/SKILL.md`（铁律 / 嵌入路径 / 暗色 / 渲染器兼容 / 缺装降级总则 / 自检模板）。本文件只写 astronomy 场景增量，通用规则一律引用 core，不复制漂移。

**独立成 skill 论证（一句话）**：天文表述的语汇是「天球坐标系 + 星图投影」——天体位置是时间×地点×坐标系的三元函数，凭印象画的示意必然方位/高度/月相全错，数值必须由星历（DE 系列）+ 坐标变换库（skyfield）真算，故独立成 skill。

## 触发条件

命中任一即用本场景骨架交付：

- **天象预报**：升起/落下/中天、某时刻高度方位、月相、行星视位置；
- **星图**：某地某时刻可见天空（圆顶图/全天图/局部天区）；
- **轨道与运动**：行星地心视位置、距离变化、会合/冲日类现象的有据推算；
- **坐标换算**：地平坐标（Az/Alt）与赤道坐标（RA/Dec）互算、时角问题。

不命中即换场景：物理概念讲解用 education；纯数值表格用 office；超出星历精度的航天工程设计（入轨/交会）不属本场景，声明后另行协商。

## 报告骨架模板（五段，顺序固定）

**观测问题 → 坐标系与历表声明 → 天象计算 → 图解 → 精度与适用范围声明**

| 段 | 必含内容 | 硬约束 |
|---|---|---|
| 观测问题 | 何时（UTC+当地时双口径）/ 何地（经纬度、高程）/ 看什么 | 时间·地点·目标三要素缺一不算 astronomy 交付 |
| 坐标系与历表声明 | 地平（Az/Alt）或赤道（RA/Dec）系、J2000 分点、历表名与覆盖范围（DE421：1900–2053） | 历表覆盖范围外禁算（红线 3） |
| 天象计算 | alt/az/距离/相位等数值表 | 数值必须由本机星历真算（skyfield），禁止手算近似、禁止凭记忆填数 |
| 图解 | 星图 / 轨道图 / 高度-时间曲线，单文档 ≤3 图（core §1.3） | 星图方位约定写明（北上/东左等）；折射是否计入注明 |
| 精度与适用范围声明 | 精度量级（角分级）、未计修正项、数据来源+生成时刻 | 缺本段不算 astronomy 交付 |

骨架即验收单：缺任一段或段序颠倒，不算 astronomy 交付。

## 工具链与自检

### 工具选择

- **skyfield（唯一计算引擎）**：星历加载（DE421）、时间尺度（UTC/TT）、地平/赤道坐标变换、月相（almanac）；
- **matplotlib 极坐标（渲染器）**：星空圆顶图（天顶居中、地平线外圈）、高度-时间曲线、轨道距离曲线；
- **Hipparcos 星表**：亮星底图（Vmag 过滤 + 常用星名映射，星名属引用口径须声明）；
- numpy 为底座（已装，core §7）；装包只进 viz-venv（core §5）。

### 工具自检（实测 2026-10-04）

| 工具 | 用途 | 本机检测命令（实测） | 官方下载链接 | 链接验证记录 | 缺装降级策略 |
|---|---|---|---|---|---|
| skyfield | 星历计算/坐标变换 | `<venv>\python.exe -c "import skyfield; print(skyfield.__version__)"` → 1.55 | https://rhodesmill.org/skyfield/ · https://pypi.org/project/skyfield/ | 200 · 200（2026-10-04 实测） | **天文数值不允许降级手算**：改引权威来源数值并标注「未本地复算」，或文字描述既有结论 |
| de421.bsp | 日月行星历表（1900–2053） | `ls C:\Users\Kai\.nebflow\tools\skyfield-cache\de421.bsp` → 16,788,480 B；`load('de421.bsp')` 命中 | https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/de421.bsp | HEAD 超时（2026-10-04；缓存命中无需下载，恢复后复测） | 超出 1900–2053 或需更高精度 ⇒ 需 de440s（下载受限则拒绝该时域计算并如实声明） |
| Hipparcos 星表 | 亮星位置底图 | `ls C:\Users\Kai\.nebflow\tools\skyfield-cache\hip_main.dat` → 53,316,318 B；`hipparcos.load_dataframe` 命中 118,218 颗 | skyfield `hipparcos.URL`（cdn.jsdelivr.net 分发） | 200（2026-10-04 下载成功入缓存） | 星图降级为仅日月行星并注明 |
| matplotlib | 星图/曲线渲染 | 已装 3.11.2 | 见插件 README 链接验证表 | 200（2026-10-04，README 表） | plotly（已装）或数值表格 |

本机数据缓存现状（实测 2026-10-04）：`C:\Users\Kai\.nebflow\tools\skyfield-cache\` 下 de421.bsp（16,788,480 B）与 hip_main.dat（53,316,318 B）均在盘、加载验证通过；skyfield `Loader` 指向该目录即缓存命中，不重复下载。

### 降级链

- skyfield 缺装 ⇒ 不硬算，引权威来源并标注「未本地复算」（红线 2 的替代口径）；
- 星历缺失或时域超出 DE421 覆盖 ⇒ 拒绝该计算，改文字说明并声明缺口，不空转；
- Hipparcos 缺 ⇒ 星图仅日月行星，亮星层注明缺失；
- matplotlib 缺 ⇒ 数值表格（core §5），禁止手画 SVG。

## 质量红线

1. **三要素必声明**：时间（UTC+当地时双口径）、地点（经纬度、高程）、目标，任一缺失不算交付；
2. **数值必须真算**：一切位置/相位/距离数值出自本机星历计算，禁止估算、背忆、近似手算（core §1.2 的场景特化）；
3. **历表覆盖范围外禁算**：DE421 覆盖 1900–2053，范围外换历表或拒绝；
4. **星图方位约定写明**：北半球默认北在上、东在左（南向观天惯例），非默认必注明；方位角定义 N=0° 顺时针；
5. **修正项口径注明**：默认不计大气折射（`altaz()` 未含折射）与光行差细节，凡计入/未计入必须在声明段写明；
6. **推导值标注口径**：月相照亮比例等由相位角推算的值，标注推算公式与来源星历；
7. 禁手画 SVG、单文档 ≤3 图、marked v12 兼容（core §1.3/§4）。

## 示例

- `${SKILL_DIR}/../core/references/demos/astronomy.md` —— 北京 2026-03-21 20:00（北京时间）星空圆顶图：DE421+Hipparcos 双缓存真算，木星 alt 71.452°/az 206.366° 高悬西南、月球照亮 7.77%（相位角 32.38° 推算），七天天体数值表逐字可复算。