dsh-astro-plan 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sirius YANG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# dsh-astro-plan · 星野计划
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dsh-astro-plan?label=npm)](https://www.npmjs.com/package/dsh-astro-plan)
+[![license](https://img.shields.io/badge/license-MIT-3da639)](LICENSE)
+[![guide](https://img.shields.io/badge/用户指南-docs-d8b46a)](https://github.com/SiriusYANG91/dsh-repository/blob/main/docs/user-guide.md)
+
+星野计划（by Sirius YANG）：按 18 类天象与深空目标、全国 173 站、最长一年检索，结合光污染、方位、月相、星历事件与 7 天天气，给出推荐排序、地景、焦段与曝光；每条结果附 Stellarium 风格 3D 天球画面模拟（真实银河等值线、真实月相、实测天际线）。
+
+![查询区与页头](https://raw.githubusercontent.com/SiriusYANG91/dsh-repository/main/docs/images/01-overview.png)
+
+## 功能速览
+
+| 能力 | 规模 / 说明 |
+|---|---|
+| 目标类型 | **18 类**，两级菜单：星野 6（银河/流星雨/彗星/星轨/黄道光/极光）· 日月 2 · 行星 4（单个行星/冲日/大距/合）· 深空 5（全部深空/星系/星云/星团/行星状星云） |
+| 站点库 | **173 个**，覆盖 **34 个省级行政区**、8 个地区，含海拔、波特尔指数、实测天际线 |
+| 时间跨度 | 单次最长 **365 天**（夜的定义：当日 15:00 至次日 09:00） |
+| 天气 | 未来 **7 天内**接入 Open-Meteo 逐时预报，更远只按天文条件评估 |
+| 评分 | 五维加权：天象 0.4 · 天气 0.2 · 地景 0.2 · 光污染 0.1 · 月相 0.1，缺维度按参与权重归一 |
+| 画面模拟 | 立体投影 3D 天球、真实银河等值线、真实日月大小与月相、实测天际线、5°–180° 缩放、地平/赤道双坐标 |
+| 运行时依赖 | **零**（星历用 vendored astronomy-engine，星表/银河为构建期快照） |
+
+## 安装
+
+三种方式任选其一，装完**重启 DSH 桌面应用**。
+
+**1）插件市场**：侧边栏「插件」→「发现」→ 添加索引
+
+```
+https://raw.githubusercontent.com/SiriusYANG91/dsh-repository/main/docs/market-index.json
+```
+
+**2）npm**
+
+```bash
+dsh plugin --profile desktop add dsh-astro-plan@0.1.0
+```
+
+**3）本地目录（开发）**
+
+```bash
+dsh plugin --profile desktop add "<本目录绝对路径>"
+```
+
+验证：`curl http://127.0.0.1:<端口>/astro-plan/api/meta`
+
+## 打开
+
+| 入口 | 位置 |
+|---|---|
+| 会话 Tab | 侧边栏「星野计划」 |
+| 独立页面 | `http://127.0.0.1:<端口>/astro-plan/` |
+| 工具 | 对话里让模型调用 `astro_plan` |
+
+页面参数：`?theme=light|dark` 强制配色、`?withSim=0` 关闭画面模拟。
+
+## 用法（对话里）
+
+1. 「这周末海坨山能拍什么？」
+2. 「今年 8 月英仙座流星雨，华北哪个站点最好？」
+3. 「明年 3 月去西藏拍深空，推荐 3 个目标，要星系」
+4. 「10 月 14 日北京日食能看到吗？」
+5. 「下个月有没有适合拍银河的暗夜窗口？」
+6. 「M42 和 M31 哪个更适合我这周去拍？」
+7. 「给我一条青海冷湖的整夜时间轴」
+8. 「这几个目标的焦距和曝光分别是多少？」
+
+| action | 作用 |
+|---|---|
+| `search` | 按条件检索推荐（默认） |
+| `window` | 某站某夜逐小时时间轴 |
+| `meta` | 数据概览（类型、地区、站点数、天气覆盖） |
+| `events` | 天象事件（流星雨、银河季节窗口等） |
+| `params` | 某目标的拍摄参数（`targetId`，如 `m42`） |
+
+常用参数：`eventType`、`location`（站点/城市/省份/`lat,lon`/「全国」）、`region`、`province`、`dateStart`、`dateEnd`、`minAltitude`、`maxBortle`、`limit`、`originLat`/`originLon`。
+
+## 界面
+
+**查询区**：三行。拍摄日期（跨度上限一年，前端校验）；目的地与出发地（地区→省份→站点三级联动，出发地默认「目前所在地」，定位失败先复用上次结果再按北京估算）；拍摄目标（18 类两级菜单、高度角 ≥ 默认 0°、波特尔 ≤ 默认 6）。「查询」「重置」，打开页面不自动检索。
+
+**结果列表**：八列 —— `#`、推荐度、目标类型、目标、拍摄地点、日期、最佳时段、最高高度；按推荐度排序，**20 条/页**，序号跨页连续，可跳页。
+
+**便签详情**：点行展开，七个区块 —— 目标、时间与月相、地点、方位与构图、拍摄参数、天气、推荐度明细与推荐理由。维度随题材变化（日食只算天象/天气/地景；月食不算月相；行星与深空不算地景），缺维度不扣分。**窄屏（< 1100px）时画面模拟排在最上面一行，其余便签移到它下方**，宽屏仍是「左七块 + 右模拟」。
+
+**画面模拟**：便签右侧整列（或窄屏时置顶）。立体投影投满整幅画面，无圆形取景框；银河按 5 级等值线加色绘制，暗尘带是真空洞；日月按真实视直径、月球按真实相位（晨昏线椭圆、亮面朝太阳）；天际线来自实测高程（36 方位、1.5–140 km）；缩放 5°–180°，地平/赤道网格切换，HUD 给时间、坐标系、视野、高度/方位（赤道模式另给赤经赤纬）；播放覆盖最佳时段（最多 72 帧），带跟踪开关。
+
+## 评分模型
+
+| 维度 | 权重 | 说明 |
+|---|---|---|
+| 天象 | **0.4** | 可见性（高度、时长）与事件分值合并 |
+| 天气 | **0.2** | 7 天内来自 Open-Meteo；更远不参与 |
+| 地景 | **0.2** | 前景与目标的配合度、不可替代性 |
+| 光污染 | **0.1** | 波特尔指数，越低越好 |
+| 月相 | **0.1** | 月照度越低越好；月食/日食不参与 |
+
+缺哪个维度就把它的权重从分母里去掉（不会把缺失当 0 分），最后换算成百分制：**≥80** 条件很好、**60–80** 值得去、**<60** 建议换目标或日期。
+
+## 数据与更新
+
+| 数据 | 规模 | 来源 |
+|---|---|---|
+| 站点 | 173 个 / 34 省 / 8 地区 | 自建（海拔、波特尔、天际线、地景标签） |
+| 目标 | 71 个（深空 47：星系 12 / 星云 18 / 星团 11 / 行星状星云 6） | 自建 + 通用星表 |
+| 彗星 | 103 颗 | MPC 轨道根数，**每周首次启动自动重建** |
+| 天球 | 632 颗亮星（≤ 4.2 等）、76 星座、5 级银河、11 场流星雨 | d3-celestial（BSD-3-Clause），构建期快照 |
+
+页面第一行小字显示彗星库最近一次成功重建时间；除天气外，插件运行时不联网。
+
+## 截图
+
+![便签详情](https://raw.githubusercontent.com/SiriusYANG91/dsh-repository/main/docs/images/03-note.png)
+
+![合月与真实月相](https://raw.githubusercontent.com/SiriusYANG91/dsh-repository/main/docs/images/06-sim-moon.png)
+
+完整图文说明（14 章、9 张截图）见 **[用户指南](docs/user-guide.md)**。
+
+## 开发
+
+```bash
+node --test --test-isolation=none "tests/*.test.js"   # 全部测试
+node scripts/validate-sites.mjs                       # 站点库校验
+node tools/build-comets.mjs                           # 重建彗星库（需联网）
+node tools/build-sky.mjs                              # 重建星表/星座/银河（需联网）
+node tools/sync-sky-renderer.mjs                      # 改完 skyview.js 的 RENDER_SRC 后同步到 Tab
+node tools/make-guide-images.mjs                      # 重出用户指南配图（需无头 Edge）
+node tools/publish.mjs --check|--publish              # 发布 npm 并刷新市场索引
+node tools/push-repo.mjs                              # 把代码推到 GitHub
+```
+
+> 沙箱环境里 `node --test` 会为每个测试文件 spawn 子进程并被拒绝（EPERM），用 `--test-isolation=none` 单进程跑。
+
+## 目录
+
+```
+lib/index.js     宿主入口：astro_plan 工具 + /astro-plan 路由
+lib/planner.js   检索 → 可见窗口 → 五维评分 → 排序 / 时间轴
+lib/skyview.js   画面模拟：星表岁差、meta.sky、sim 数据与 3D 渲染器源码
+lib/astro.js     星历（高度方位/升落/暮光/月相，含岁差与时角）
+lib/events.js    天象事件现算（食/冲/大距/合·合月 + 站级可见性）
+lib/comets.js    MPC 轨道根数 → 二体传播 + 亮度模型
+lib/weather.js   Open-Meteo 抓取与评分（10 分钟缓存）
+lib/webui.js     自包含页面        lib/client.js  会话 Tab（零构建）
+lib/data/        站点 / 目标 / 参数 / 彗星 / 天际线 / 星表（+ NOTICE.md）
+tools/ scripts/  构建、发布、配图与校验脚本      tests/  测试
+```
+
+## 许可
+
+插件代码 MIT。`lib/vendor/astronomy-engine.js` 来自 [cosinekitty/astronomy](https://github.com/cosinekitty/astronomy)（MIT，Don Cross）；`lib/data/sky.json` 由 [d3-celestial](https://github.com/ofrohn/d3-celestial)（BSD-3-Clause，Olaf Frohn）的公开星表裁剪生成，详见 `lib/data/NOTICE.md`。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-astro-plan bundle patch: inserts the host row into the profile's plugin
+# roster. The browser half rides the package's `dsh.client` manifest (the client
+# registry serves lib/client.js), and this row materializes the astro-planning
+# host plugin on boot.
+#
+# 包名 / 行 id / client id 三者保持一致（都是 dsh-astro-plan），这是 DSH 客户端
+# 模块系统能稳定识别的形态；改成 scoped 名会让同一条 bundle 被注册两次。
+- insert:
+    - id: dsh-astro-plan
+      name: 'dsh-astro-plan'

package/docs/icon.svg

@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" role="img" aria-label="Astro Plan">
+  <defs>
+    <linearGradient id="sky" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#05070f"/>
+      <stop offset="0.62" stop-color="#0d1526"/>
+      <stop offset="1" stop-color="#16233a"/>
+    </linearGradient>
+    <linearGradient id="mw" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#cfe0f7" stop-opacity="0"/>
+      <stop offset="0.5" stop-color="#cfe0f7" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#cfe0f7" stop-opacity="0"/>
+    </linearGradient>
+    <linearGradient id="frame" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#d8b46a"/>
+      <stop offset="1" stop-color="#f0d79a"/>
+    </linearGradient>
+  </defs>
+  <rect width="256" height="256" rx="52" fill="url(#sky)"/>
+  <g>
+    <circle cx="46" cy="52" r="1.7" fill="#e8f0ff" opacity="0.85"/>
+    <circle cx="74" cy="30" r="2.2" fill="#e8f0ff" opacity="0.75"/>
+    <circle cx="196" cy="46" r="1.5" fill="#e8f0ff" opacity="0.8"/>
+    <circle cx="212" cy="86" r="2" fill="#e8f0ff" opacity="0.7"/>
+    <circle cx="34" cy="122" r="1.4" fill="#e8f0ff" opacity="0.65"/>
+    <circle cx="222" cy="150" r="1.6" fill="#e8f0ff" opacity="0.6"/>
+    <circle cx="64" cy="196" r="1.8" fill="#e8f0ff" opacity="0.55"/>
+    <circle cx="188" cy="206" r="1.3" fill="#e8f0ff" opacity="0.5"/>
+  </g>
+  <path d="M14 190 C 66 132, 132 108, 242 128" fill="none" stroke="url(#mw)" stroke-width="26" stroke-linecap="round" opacity="0.75"/>
+  <path d="M14 190 C 66 132, 132 108, 242 128" fill="none" stroke="#e8f0ff" stroke-width="4" stroke-linecap="round" opacity="0.30"/>
+  <g fill="none" stroke="url(#frame)" stroke-width="6" stroke-linecap="round">
+    <path d="M62 88 V72 H82"/>
+    <path d="M174 72 H194 V88"/>
+    <path d="M194 176 V192 H174"/>
+    <path d="M82 192 H62 V176"/>
+  </g>
+  <g fill="url(#frame)">
+    <circle cx="128" cy="132" r="7"/>
+  </g>
+  <g fill="none" stroke="url(#frame)" stroke-width="2.4" opacity="0.7">
+    <circle cx="128" cy="132" r="18"/>
+  </g>
+</svg>

package/lib/api.js

@@ -0,0 +1,84 @@
+/**
+ * dsh-astro-plan — HTTP API。
+ *
+ * 前缀 /astro-plan：
+ *   GET /api/meta                        元数据（事件类型/区域/省份/站点/目标/天气覆盖）
+ *   GET /api/search?...                  与工具同参的检索
+ *   GET /api/night?site=&date=           单站单夜时间轴
+ *   GET /astro-plan/                     自包含页面
+ */
+
+import { meta, search, timeline } from './planner.js'
+import { page } from './webui.js'
+
+function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+function sendHtml(res, status, html) {
+  res.writeHead(status, {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(html),
+  })
+  res.end(html)
+}
+
+function queryToOptions(url) {
+  const q = url.searchParams
+  const opt = {}
+  for (const key of ['action', 'eventType', 'location', 'region', 'province', 'dateStart', 'dateEnd',
+    'timeFrom', 'timeTo', 'format']) {
+    if (q.get(key)) opt[key] = q.get(key)
+  }
+  for (const key of ['minAltitude', 'maxBortle', 'limit', 'page', 'pageSize', 'siteLimit', 'maxDriveHours', 'originLat', 'originLon']) {
+    if (q.get(key) !== null && q.get(key) !== '') opt[key] = Number(q.get(key))
+  }
+  if (q.get('tracker') !== null) opt.tracker = q.get('tracker') === 'true' || q.get('tracker') === '1'
+  // 页面需要「画面模拟」数据：默认开启，?withSim=0 可关（工具直连 search 时默认不算）
+  opt.withSim = !(q.get('withSim') === '0' || q.get('withSim') === 'false')
+  return opt
+}
+
+export function installApi(ctx) {
+  const handler = async (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost')
+    const path = url.pathname
+    try {
+      if (path === '/astro-plan' || path === '/astro-plan/' || path === '/astro-plan/index.html') {
+        sendHtml(res, 200, page())
+        return
+      }
+      if (req.method === 'GET' && path === '/astro-plan/api/meta') {
+        sendJson(res, 200, { ok: true, ...meta() })
+        return
+      }
+      if (req.method === 'GET' && path === '/astro-plan/api/search') {
+        const result = await search(queryToOptions(url))
+        sendJson(res, result.ok ? 200 : 400, result)
+        return
+      }
+      if (req.method === 'GET' && path === '/astro-plan/api/night') {
+        const site = url.searchParams.get('site')
+        const date = url.searchParams.get('date')
+        if (!site || !date) {
+          sendJson(res, 400, { ok: false, error: 'bad_request', message: '需要 site 与 date 参数' })
+          return
+        }
+        const result = timeline(site, date)
+        sendJson(res, result.ok ? 200 : 404, result)
+        return
+      }
+      sendJson(res, 404, { ok: false, error: 'not_found', message: `未知路径 ${path}` })
+    } catch (error) {
+      sendJson(res, 500, { ok: false, error: 'internal', message: String(error?.message ?? error) })
+    }
+  }
+  return ctx.webServer.register({ kind: 'prefix', path: '/astro-plan', handler })
+}

package/lib/astro.js

@@ -0,0 +1,242 @@
+/**
+ * dsh-astro-plan — 天文计算适配层。
+ *
+ * 底层星历使用 vendored 的 astronomy-engine v2.1.19（MIT，见 lib/vendor）。
+ * 本层只做三件事：统一时区（中国 UTC+8）、统一站点观测者、把「地平坐标 /
+ * 升落 / 暮光 / 月相」包装成规划器好用的形状。
+ *
+ * 精度约定（与 astropy 基准对照，见 tests/astro.test.js）：
+ *   - 太阳/行星高度方位：≤0.05°
+ *   - 月亮（含视差）：≤0.4°（受月球理论差异限制，规划足够）
+ *   - 暮光 / 月升落：≤2 min
+ *   - 月照度：≤2%
+ */
+
+import * as A from './vendor/astronomy-engine.js'
+
+const D2R = Math.PI / 180
+const R2D = 180 / Math.PI
+export const TZ_OFFSET_HOURS = 8
+
+export { A }
+
+/** Date | ISO 字符串 → AstroTime。 */
+export function makeTime(value) {
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) throw new Error(`invalid date: ${value}`)
+  return A.MakeTime(date)
+}
+
+/** 站点 → astronomy-engine Observer。 */
+export function observerOf(site) {
+  return new A.Observer(site.lat, site.lon, site.altM ?? 0)
+}
+
+/** 把 "YYYY-MM-DD" + "HH:MM" 解析成 UTC+8 的 Date。 */
+export function localDate(dateStr, hhmm = '00:00') {
+  const [y, m, d] = String(dateStr).split('-').map(Number)
+  const [hh, mm] = String(hhmm).split(':').map(Number)
+  return new Date(Date.UTC(y, m - 1, d, hh - TZ_OFFSET_HOURS, mm || 0))
+}
+
+/** Date → UTC+8 本地 "YYYY-MM-DD"。 */
+export function localDateString(date) {
+  const t = new Date(date.getTime() + TZ_OFFSET_HOURS * 3600 * 1000)
+  return t.toISOString().slice(0, 10)
+}
+
+/** Date → UTC+8 本地 "HH:MM"。 */
+export function localHHMM(date) {
+  const t = new Date(date.getTime() + TZ_OFFSET_HOURS * 3600 * 1000)
+  return t.toISOString().slice(11, 16)
+}
+
+/** Date → UTC+8 本地 "YYYY-MM-DD HH:MM"（跨零点的观测窗口用这个才不歧义）。 */
+export function localDateTime(date) {
+  const t = new Date(date.getTime() + TZ_OFFSET_HOURS * 3600 * 1000)
+  return `${t.toISOString().slice(0, 10)} ${t.toISOString().slice(11, 16)}`
+}
+
+/** Date → UTC+8 本地 "MM-DD HH:MM"（表格里用短格式，省宽度）。 */
+export function localShortDateTime(date) {
+  const t = new Date(date.getTime() + TZ_OFFSET_HOURS * 3600 * 1000)
+  return `${t.toISOString().slice(5, 10)} ${t.toISOString().slice(11, 16)}`
+}
+
+/** 地方恒星时（小时，0–24），lon 为东经度。 */
+export function lstHours(time, lonDeg) {
+  const gast = A.SiderealTime(time) // 小时
+  return ((gast + lonDeg / 15) % 24 + 24) % 24
+}
+
+/** 大气折射（度），地平线以上才加，避免地平线下出现假抬升。 */
+function refracted(altDeg) {
+  if (altDeg < -1) return altDeg
+  return altDeg + A.Refraction('normal', altDeg)
+}
+
+/**
+ * 时角法高度方位（快，供固定恒星批量计算）。
+ * @param {number} raDeg 赤经（J2000，度）
+ * @param {number} decDeg 赤纬（度）
+ * @param {number} lstH 地方恒星时（小时）
+ * @param {number} latDeg 站点纬度
+ */
+export function altAzFromHA(raDeg, decDeg, lstH, latDeg) {
+  const H = ((((lstH * 15 - raDeg) % 360) + 540) % 360 - 180) * D2R
+  const phi = latDeg * D2R
+  const dec = decDeg * D2R
+  const sinAlt = Math.sin(phi) * Math.sin(dec) + Math.cos(phi) * Math.cos(dec) * Math.cos(H)
+  const altGeo = Math.asin(Math.max(-1, Math.min(1, sinAlt)))
+  // 方位必须用「几何高度」求，折射只影响高度，否则会引入约 0.5° 的方位偏差
+  const cosA = (Math.sin(dec) - Math.sin(altGeo) * Math.sin(phi)) / (Math.cos(altGeo) * Math.cos(phi) || 1e-9)
+  let az = Math.acos(Math.max(-1, Math.min(1, cosA)))
+  if (Math.sin(H) > 0) az = 2 * Math.PI - az
+  const altDeg = altGeo * R2D
+  return { alt: altDeg + (altDeg > -1 ? A.Refraction('normal', altDeg) : 0), az: (az * R2D + 360) % 360 }
+}
+
+/** J2000 星表坐标 → 当日赤道坐标（岁差），用于时角快速算法。 */
+export function ofDateRADec(raDeg, decDeg, time) {
+  const v = {
+    x: Math.cos(decDeg * D2R) * Math.cos(raDeg * D2R),
+    y: Math.cos(decDeg * D2R) * Math.sin(raDeg * D2R),
+    z: Math.sin(decDeg * D2R),
+    t: time,
+  }
+  const eqd = A.RotateVector(A.Rotation_EQJ_EQD(time), v)
+  const sph = A.EquatorFromVector(eqd)
+  return { raDeg: sph.ra * 15, dec: sph.dec }
+}
+/** 固定恒星（J2000 坐标）→ 地平坐标，矩阵法（更准，单点用）。 */
+export function starAltAz(raDeg, decDeg, time, site) {
+  const obs = observerOf(site)
+  const v = { x: Math.cos(decDeg * D2R) * Math.cos(raDeg * D2R), y: Math.cos(decDeg * D2R) * Math.sin(raDeg * D2R), z: Math.sin(decDeg * D2R) }
+  const hor = A.RotateVector(A.Rotation_EQJ_HOR(time, obs), v)
+  const sph = A.HorizonFromVector(hor, null)
+  return { alt: refracted(sph.lat), az: (sph.lon + 360) % 360 }
+}
+
+/** 太阳/月亮/行星 → 地平坐标（含视差与折射）。 */
+export function bodyAltAz(bodyName, time, site) {
+  const body = A.Body[bodyName]
+  if (body === undefined) throw new Error(`unknown body: ${bodyName}`)
+  const obs = observerOf(site)
+  const v = A.GeoVector(body, time, true)
+  const ov = A.ObserverVector(time, obs, false)
+  const topo = { x: v.x - ov.x, y: v.y - ov.y, z: v.z - ov.z, t: v.t }
+  const hor = A.RotateVector(A.Rotation_EQJ_HOR(time, obs), topo)
+  const sph = A.HorizonFromVector(hor, null)
+  return { alt: refracted(sph.lat), az: (sph.lon + 360) % 360 }
+}
+
+/**
+ * 任意「地心赤道 J2000 矢量」→ 地平坐标（含视差与折射）。
+ * 彗星等没有内建星历的天体走这里，与 bodyAltAz 完全同一条几何链路。
+ */
+export function vectorAltAz(vec, time, site) {
+  const obs = observerOf(site)
+  const ov = A.ObserverVector(time, obs, false)
+  const topo = { x: vec.x - ov.x, y: vec.y - ov.y, z: vec.z - ov.z, t: vec.t ?? time }
+  const hor = A.RotateVector(A.Rotation_EQJ_HOR(time, obs), topo)
+  const sph = A.HorizonFromVector(hor, null)
+  return { alt: refracted(sph.lat), az: (sph.lon + 360) % 360 }
+}
+
+/** 目标（星表或行星）→ 地平坐标，统一入口。 */
+export function targetAltAz(target, time, site) {
+  if (target.body) return bodyAltAz(target.body, time, site)
+  return starAltAz(target.raH * 15, target.dec, time, site)
+}
+
+/** 下一次升/落（direction: +1 升, -1 落），返回 Date 或 null。 */
+export function riseSet(bodyName, time, site, direction, limitDays = 2) {
+  const body = A.Body[bodyName]
+  if (body === undefined) throw new Error(`unknown body: ${bodyName}`)
+  const found = A.SearchRiseSet(body, observerOf(site), direction, time, limitDays, 0)
+  return found ? found.date : null
+}
+
+/** 太阳高度 → 下一次穿越目标高度的时刻。 */
+export function searchSunAltitude(time, site, altitudeDeg, direction, limitDays = 1) {
+  const found = A.SearchAltitude(A.Body.Sun, observerOf(site), direction, time, limitDays, altitudeDeg)
+  return found ? found.date : null
+}
+
+/** 月相角（0=新月, 180=满月）。 */
+export function moonPhaseAngle(time) {
+  return A.MoonPhase(time)
+}
+
+/** 月面照度百分比。 */
+export function moonIllumPercent(time) {
+  const angle = A.MoonPhase(time)
+  return ((1 - Math.cos(angle * D2R)) / 2) * 100
+}
+
+/** 月相名（中文）。 */
+export function moonPhaseName(illum, waxing) {
+  if (illum < 1.5) return '新月'
+  if (illum < 12) return waxing ? '娥眉月' : '残月'
+  if (illum < 45) return waxing ? '上弦前' : '下弦后'
+  if (illum < 55) return '弦月'
+  if (illum < 88) return waxing ? '盈凸月' : '亏凸月'
+  if (illum < 98.5) return '近满月'
+  return '满月'
+}
+
+/** 两个地平坐标的角距（度）。 */
+export function separation(alt1, az1, alt2, az2) {
+  const a1 = alt1 * D2R; const a2 = alt2 * D2R
+  const dz = (az1 - az2) * D2R
+  const c = Math.sin(a1) * Math.sin(a2) + Math.cos(a1) * Math.cos(a2) * Math.cos(dz)
+  return Math.acos(Math.max(-1, Math.min(1, c))) * R2D
+}
+
+/** 罗盘方位名。 */
+export function azName(az) {
+  const names = ['北', '东北', '东', '东南', '南', '西南', '西', '西北']
+  return names[Math.round(((az % 360) + 360) % 360 / 45) % 8]
+}
+
+/**
+ * 一"夜"的上下文：夜定义为 D 日 15:00 → D+1 09:00（UTC+8）。
+ * @param {object} site 站点
+ * @param {string} dateStr "YYYY-MM-DD"
+ * @param {{fast?: boolean}} [options] fast=true 时只算暮光与月相（检索路径用，
+ *   省掉 4 次太阳升落搜索与 2 次月升落搜索，长跨度检索可快近一倍）
+ */
+export function nightContext(site, dateStr, options = {}) {
+  const fast = options.fast === true
+  const start = makeTime(localDate(dateStr, '15:00'))
+  const endDate = localDate(dateStr, '09:00')
+  endDate.setUTCDate(endDate.getUTCDate() + 1)
+  const end = makeTime(endDate)
+
+  const sunset = fast ? null : searchSunAltitude(start, site, -0.833, -1)
+  const dusk = searchSunAltitude(start, site, -18, -1)
+  const dawn = dusk ? searchSunAltitude(makeTime(dusk), site, -18, +1) : null
+  const sunrise = fast || !dawn ? null : searchSunAltitude(makeTime(dawn), site, -0.833, +1)
+
+  const moonrise = fast ? null : riseSet('Moon', start, site, +1)
+  const moonset = fast ? null : riseSet('Moon', start, site, -1)
+  const noon = makeTime(localDate(dateStr, '22:00'))
+  const illum = moonIllumPercent(noon)
+  const phaseAngle = moonPhaseAngle(noon)
+  const waxing = phaseAngle < 180
+
+  return {
+    date: dateStr,
+    start: start.date,
+    end: end.date,
+    sunset: sunset ? sunset : null,
+    dusk: dusk ? dusk : null,
+    dawn: dawn ? dawn : null,
+    sunrise: sunrise ? sunrise : null,
+    moonrise: moonrise && moonrise <= end.date ? moonrise : null,
+    moonset: moonset && moonset <= end.date ? moonset : null,
+    moonIllum: illum,
+    moonPhase: moonPhaseName(illum, waxing),
+    waxing,
+  }
+}

package/lib/aurora.js

@@ -0,0 +1,106 @@
+/**
+ * dsh-astro-plan — 极光可见性判据。
+ *
+ * 国内只有北纬 42° 以上的站点在强地磁暴时可能看到极光，仅靠「季节 + 站点纬度」
+ * 会给出永远可拍的假结果（此前每次查询都固定 3 条）。这里用两件事判可见性：
+ *   1. 站点地磁纬度（偶极近似，地磁北极 80.65°N / 72.68°W）；
+ *   2. NOAA SWPC 的 Kp 预报（3 小时分辨率，含观测 + 未来约 3 天预测）。
+ * Kp 达不到所需阈值 → 该站该夜不产生结果；预报没覆盖到的日期 → 不产生结果，
+ * 由 planner 给出「超出 Kp 预报范围」的说明。
+ */
+
+const KP_URL = 'https://services.swpc.noaa.gov/products/noaa-planetary-k-index-forecast.json'
+const CACHE_TTL_MS = 30 * 60 * 1000
+const D2R = Math.PI / 180
+const R2D = 180 / Math.PI
+
+/** 地磁北极（IGRF 近似，2020 年代）。 */
+const MAG_POLE = { lat: 80.65, lon: -72.68 }
+
+let cache = { at: 0, data: null }
+
+/** 站点纬经度 → 地磁纬度（度）。 */
+export function geomagneticLatitude(lat, lon) {
+  const p = MAG_POLE.lat * D2R
+  const l0 = MAG_POLE.lon * D2R
+  const phi = lat * D2R
+  const lambda = lon * D2R
+  const sinM = Math.sin(phi) * Math.sin(p) + Math.cos(phi) * Math.cos(p) * Math.cos(lambda - l0)
+  return Math.asin(Math.max(-1, Math.min(1, sinM))) * R2D
+}
+
+/**
+ * 该站看到极光所需的最低 Kp。
+ * 经验式：极光卵赤道侧边界随 Kp 下降约 3°/级，Kp 0 ≈ 66.5° 地磁纬度。
+ * 漠河（地磁纬度 ~46°）需要 Kp ≥ 6.8；长白山（~40°）需要 Kp ≥ 8.8。
+ */
+export function requiredKp(magLat) {
+  return Math.max(0, Math.min(9, (66.5 - magLat) / 3))
+}
+
+function parseRows(rows) {
+  const out = []
+  for (const row of rows) {
+    const iso = String(row.time_tag ?? '').replace(' ', 'T')
+    const kp = Number(row.kp)
+    if (!iso || !Number.isFinite(kp)) continue
+    const time = new Date(`${iso}Z`)
+    if (Number.isNaN(time.getTime())) continue
+    out.push({ time, kp })
+  }
+  return out.sort((a, b) => a.time - b.time)
+}
+
+/**
+ * 取 Kp 序列（30 分钟缓存）。失败返回 null，调用方据此判定「无法确认」。
+ */
+export async function kpForecast() {
+  if (cache.data && Date.now() - cache.at < CACHE_TTL_MS) return cache.data
+  try {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), 12000)
+    const res = await fetch(KP_URL, { signal: controller.signal })
+    clearTimeout(timer)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const rows = await res.json()
+    const data = parseRows(Array.isArray(rows) ? rows : [])
+    if (data.length === 0) throw new Error('empty kp payload')
+    cache = { at: Date.now(), data }
+    return data
+  } catch (error) {
+    return null
+  }
+}
+
+/**
+ * 每个「夜」（D 15:00 → D+1 09:00，UTC+8）的 Kp 峰值。
+ * 对应 UTC 窗口 D 07:00 → D+1 01:00。
+ * @returns {Map<string, number>}
+ */
+export function kpByNight(forecast) {
+  const map = new Map()
+  if (!forecast) return map
+  for (const { time, kp } of forecast) {
+    // 夜 D（UTC+8 15:00 → 次日 09:00）= UTC D 07:00 → D+1 01:00
+    const utcHour = time.getUTCHours()
+    let dateKey
+    if (utcHour >= 7) dateKey = time.toISOString().slice(0, 10)
+    else if (utcHour <= 1) dateKey = new Date(time.getTime() - 86400000).toISOString().slice(0, 10)
+    else continue
+    const prev = map.get(dateKey)
+    if (prev === undefined || kp > prev) map.set(dateKey, kp)
+  }
+  return map
+}
+
+/** 预报覆盖的日期范围（给提示用）。 */
+export function kpCoverage(forecast) {
+  if (!forecast || forecast.length === 0) return { from: null, to: null }
+  const first = forecast[0].time.toISOString().slice(0, 10)
+  const last = forecast[forecast.length - 1].time.toISOString().slice(0, 10)
+  return { from: first, to: last }
+}
+
+export function clearAuroraCache() {
+  cache = { at: 0, data: null }
+}