myastro 0.3.0__tar.gz

myastro-0.3.0/.gitignore

@@ -0,0 +1,27 @@
+.venv/
+__pycache__/
+*.pyc
+.ipynb_checkpoints/
+# 数据不进 git
+data/
+*.fits
+*.fit
+*.fz
+*.csv
+out/
+*.png
+!docs/**/*.png
+.env
+lightkurve-cache/
+
+# 构建产物：可再生产物不进 git（发布时由 CI/本地构建生成）
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+
+# 本机环境路径（每台机器不同，不进版本控制）
+.myastro-env
+
+# 编辑器配置（个人设置不进版本库）
+.vscode/

myastro-0.3.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+本文件记录对使用者有影响的变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.3.0] - 2026-10-10
+
+**首个公开发布**（0.2.0 为私有基线，未发布）。PyPI 上的起点。
+
+### 新增
+
+- **双语用户文档**：英文 `README.md` + 中文 `README.zh-CN.md`；`docs/en/` 与 `docs/zh/`
+  下的安装与快速上手成对存在，并有守卫检查中英章节结构一致（防止只更新一边）。
+- **CI（GitHub Actions）**：lint（ruff + pyflakes）、test（ubuntu + macos × Python
+  3.11/3.12/3.13，全量离线测试）、build（构建 + `twine check` + 安装 wheel + `doctor` 冒烟）；
+  标签发布走 **PyPI Trusted Publishing（OIDC，无长期 token）**，另有 TestPyPI 演练工作流。
+- **社区文件**：`CONTRIBUTING.md`（含分层测试规则与"回归测试必须能变红"）、`SECURITY.md`
+  （凭据处理与漏洞报告）、`CITATION.cff`、issue/PR 模板。
+- `[test]` extra（pytest/pytest-asyncio/ruff/pyflakes），CI 用它而不必装 jupyterlab。
+
+### 变更
+
+- **默认数据根**改为 `~/myastro-data`（此前是本机个人布局）。`doctor` 在未显式设置
+  `MYASTRO_DATA` 时给出提示与 export 写法。数据可以放 NAS，账本必须在本地磁盘。
+- `githooks/pre-push` 不再硬编码本机环境路径：候选链 `MYASTRO_ENV_BIN` → 仓库内
+  `.myastro-env`（gitignore）→ 当前 venv → `.venv` → PATH，每个候选先用
+  `pytest --collect-only` 预检；找不到时给出三种修复方式。
+- notebook 输出已清空（体积 2.2MB → 28KB），公开仓库不含执行结果。
+
+### 修复
+
+- 发布产物内容明确化：sdist 1.9MB → 179KB（排除 notebooks / `.vscode` / conda 环境记录）。
+- 开发向命令（`test-map` / `doc-sync`）在已安装环境里不再抛栈或写入 site-packages，
+  改为清晰报错 + 退出码 2。
+
+## [0.2.0] - 2026-10-10
+
+首个打标签的基线（此前为私有开发，未发布）。0.x 阶段允许破坏性变更，但都会写在本文件里。
+
+### 新增
+
+- **数据获取**：10 个描述符源（tess / gaia / ztf / ztf-meta / ztf-lc / mpc / simbad /
+  vizier / legacy / unwise），另有 manifest 清单批量下载、exoplanet 目录查询；
+  asassn 为休眠源（后端失联）。
+- **账本与去重**：SQLite 账本（数据存 UTC，显示转本地时区），缓存键规范化
+  （同参数二次调用零网络），`meta_json` 溯源持久化。
+- **本地检索**：按源/目标/文件名/时间检索；**精确圆锥坐标检索**
+  （入库时解析坐标 → SQL 包围盒粗筛 → haversine 精判 → 按角距排序带 `sep_deg`）。
+- **批量与调度**：批次下单与整批重试；launchd 定时任务（健康检查、索引更新）。
+- **索引**：legacy-bricks（366k 行）、ztf-fields（1776 场）本地索引，
+  前缀查询走缓存 + bisect（实测每次按键 0.5ms）。
+- **TUI**（`myastro top`）：三面板（数据源/作业/存储）、F1 新建、F2 预填充、F12 批量；
+  索引字段带原生补全（→ 接受）与输入前可见的 `（索引）` 标记。
+- **CLI**：20 个子命令；`fetch` 参数由描述符自动生成；`--version`；`init`（建数据根/账本）、`doctor`（环境自检）、`backup`/`restore`（账本备份与恢复）。
+- **环境自检**：`ma.doctor()` 检查依赖、路径可写性、账本 schema、**账本文件系统（NFS 上 SQLite WAL 不可用）**、文件抽查、索引、平台能力；有 FAIL 时退出码 1。
+- **账本备份/恢复**：`ma.backup()` / `ma.restore()`，SQLite 在线备份 API，恢复默认拒绝覆盖、覆盖前自动留 `.pre-restore-*.bak`、支持旧 schema 备份再迁移。
+- **可验证的工程**：能力矩阵（capabilities）+ 生成的测试地图；设计守卫（注册表漂移、
+  文档同步、层边界、门面覆盖、落盘路径不变量）。
+
+### 修复
+
+- **路径安全**：名字型参数（`brick`/`ffd`/`target`）此前可经 `..` 把产物写到数据根之外；
+  现在输入即拒（`FieldSpec.pattern`/`name_like`）+ 落库前运行时兜底。
+- **检索参数**：越界输入（负半径、dec 越界、`limit<1`、日期格式错）此前静默返回空结果，
+  其中 `limit=-1` 会按切片语义返回"除最后一条外的全部"；现在一律 `ParamError`。
+- **TUI 闪烁**：选中项在视口外时，每 2 秒刷新会先画一帧"列表顶部"再滚回（帧级实测 2 帧/次）；
+  现在内容签名短路（无变化不重绘）+ 重建后同步恢复滚动（1 帧）。
+- **TUI 首屏列宽**：本地资产首屏"文件名"列被截断（自动列宽在"只有列还没有行"时定宽），
+  排序后才正常；现在列宽按内容确定性计算。
+- **CLI 错误处理**：`myastro retry 999999` 此前直接抛栈崩溃；现在错误消息 + 退出码
+  契约（0/1/2/3/4/5/130）。
+- **连接生命周期**：自建 SQLite 连接此前靠 GC 回收；现在用完即关，传入的连接不受影响。
+
+### 变更
+
+- 依赖声明与实际使用对齐：补 `numpy`/`pyarrow`；重依赖移入 `[processing]` extras；
+  `pyasassn`/`ztfquery` 为可选后端。
+- 采用 MIT 许可。
+
+[0.2.0]: https://github.com/DanJiabi/myastro/releases/tag/v0.2.0

myastro-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DanJiabi
+
+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.

myastro-0.3.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: myastro
+Version: 0.3.0
+Summary: Personal astronomy data toolkit: fetch, ledger, dedup, coverage, TUI
+Project-URL: Homepage, https://github.com/DanJiabi/myastro
+Project-URL: Repository, https://github.com/DanJiabi/myastro
+Project-URL: Issues, https://github.com/DanJiabi/myastro/issues
+Project-URL: Changelog, https://github.com/DanJiabi/myastro/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astronomy,astroquery,data-management,legacy-survey,tess,tui,ztf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Requires-Dist: astropy
+Requires-Dist: astroquery
+Requires-Dist: lightkurve
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: textual
+Requires-Dist: transitleastsquares
+Provides-Extra: asassn
+Requires-Dist: pyasassn; extra == 'asassn'
+Provides-Extra: dev
+Requires-Dist: jupyterlab; extra == 'dev'
+Requires-Dist: pyflakes; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: processing
+Requires-Dist: astroalign; extra == 'processing'
+Requires-Dist: ccdproc; extra == 'processing'
+Requires-Dist: matplotlib; extra == 'processing'
+Requires-Dist: photutils; extra == 'processing'
+Requires-Dist: scipy; extra == 'processing'
+Requires-Dist: skyfield; extra == 'processing'
+Provides-Extra: test
+Requires-Dist: pyflakes; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: ruff; extra == 'test'
+Requires-Dist: ztfquery; extra == 'test'
+Provides-Extra: ztfquery
+Requires-Dist: ztfquery; extra == 'ztfquery'
+Description-Content-Type: text/markdown
+
+# myastro
+
+[![CI](https://github.com/DanJiabi/myastro/actions/workflows/ci.yml/badge.svg)](https://github.com/DanJiabi/myastro/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/myastro.svg)](https://pypi.org/project/myastro/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**A personal astronomy data toolkit with a memory.** Fetch from public surveys and
+keep a local ledger of *what you already have* — so you stop re-downloading the same sky.
+
+`myastro` answers questions plain query tools don't:
+
+- "Have I already downloaded this patch of sky?" → precise cone search over your ledger
+- "How much of the brick/field index is local?" → coverage against a full catalogue
+- "Which files rotted on disk?" → sha256 baseline audit
+- "Is it still fetchable?" → deduplicated fetches plus source probes
+
+Three entry points, one contract:
+
+| Entry point | Use |
+|---|---|
+| Library | `import myastro as ma` — the only public import (`ma.__all__`) |
+| CLI | `myastro fetch / search / coverage / audit / doctor / backup …` |
+| TUI | `myastro top` — jobs / storage / sources, no config file needed |
+
+> Status: **0.3.0 — alpha**. The facade is the public API; `myastro.io.*` is internal
+> and may change. Breaking changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install myastro                      # from PyPI
+pip install -c constraints.txt myastro   # with known-good dependency versions
+pip install "myastro[processing]"        # + photometry/imaging deps (planned P2/P3)
+myastro doctor                           # self-check: deps, paths, ledger, filesystem
+```
+
+Python ≥ 3.11. macOS and Linux are supported; Windows is untested (scheduling is
+macOS/Linux only). Optional extras: `[processing]`, `[asassn]`, `[ztfquery]`.
+
+## Quick start
+
+```python
+import myastro as ma
+
+# 1) fetch — deduplicated: the same params never hit the network twice
+r = ma.fetch("tess", target="WASP-12", sector=20)
+print(r.paths[0])
+
+# 2) what do I already have near this position?
+for hit in ma.search(near=(97.6367, 29.6723), radius_deg=0.5):
+    print(f"{hit['source']:10s} sep={hit['sep_deg']:.4f}°  {hit['path']}")
+
+# 3) coverage against a full catalogue index
+print(ma.coverage("legacy-bricks"))      # {'local': 7, 'total': 366912, ...}
+
+# 4) integrity: build a sha256 baseline, then detect silent corruption
+print(ma.audit())
+```
+
+Data root defaults to `~/myastro-data`; the ledger defaults to
+`~/.local/state/myastro/astro.db`. Both are overridable:
+
+```bash
+export MYASTRO_DATA=/path/to/your/data               # may live on a NAS
+export MYASTRO_DB=~/.local/state/myastro/astro.db    # must be a LOCAL disk (SQLite WAL)
+```
+
+Keeping the ledger local while data lives on a NAS is the intended layout —
+`myastro doctor` fails when the ledger sits on NFS/CIFS.
+
+## CLI
+
+```bash
+myastro init                               # create data root + ledger (idempotent)
+myastro doctor                             # environment self-check (exit 1 if broken)
+myastro backup --out ~/myastro-backup      # online SQLite backup + manifest
+myastro restore ~/myastro-backup/<stamp> --force   # refuses to overwrite unless --force
+myastro fetch tess --target "WASP-12" --sector 20  # args generated from descriptors
+myastro jobs / wait / retry / delete / retry-batch
+myastro search --near 196.18 33.35 --radius 0.2
+myastro coverage legacy-bricks
+myastro audit                              # sha256 baseline / corruption report
+myastro index list | index update <name>   # local indexes (Legacy bricks, ZTF fields)
+myastro health | schedule install health   # source probes, launchd (macOS)
+myastro top                                # TUI
+```
+
+Exit codes are a contract, so scripts can branch:
+`0` ok · `1` partial failure / doctor found problems · `2` bad parameter ·
+`3` not found · `4` network · `5` state not allowed · `130` interrupted.
+
+## What's inside
+
+- **Ledger** — every fetch is a job; datasets, files, parameters, provenance and
+  coordinates are recorded. Data files are the truth, the ledger is the index.
+- **Deduplication** — cache key is a normalized `(source, params)` hash: the same
+  request never hits the network twice; cache hits return the original metadata.
+- **10 sources** — TESS light curves, Gaia DR3 cones, ZTF frames / metadata / light
+  curves, MPC ephemerides, SIMBAD, VizieR, Legacy Surveys tractor bricks, unWISE
+  cutouts, plus YAML manifests for bulk URL lists.
+- **Precise cone search** — coordinates are resolved at ingest time (params → meta →
+  index lookup → filename fallback), stored in the ledger, then queried with a
+  bounding box plus haversine refinement and sorted by separation.
+- **Local indexes** — 366k Legacy bricks and 1776 ZTF fields, cached in memory and
+  searched with binary search (sub-millisecond per keystroke in the TUI).
+- **Verifiability** — a capability matrix (`docs/capabilities.md`), a generated test
+  map (`docs/test-map.md`) and design guards: tests fail when docs or registries drift.
+
+## Documentation
+
+| Document | Language | Audience |
+|---|---|---|
+| [Install](docs/en/install.md) · [Quick start](docs/en/quickstart.md) | EN | users |
+| [安装](docs/zh/install.md) · [快速上手](docs/zh/quickstart.md) | 中文 | 用户 |
+| [capabilities.md](docs/capabilities.md) | 中文 | roadmap: what exists, at which maturity |
+| [processing.md](docs/processing.md) | 中文 | pipeline behaviour and failure semantics |
+| [design-io.md](docs/design-io.md) · [design-top.md](docs/design-top.md) | 中文 | layer design and decisions |
+| [testing.md](docs/testing.md) · [test-map.md](docs/test-map.md) | 中文 | test layers, guards, generated map |
+| [release.md](docs/release.md) | 中文 | release process and public-mirror model |
+
+Developer docs are maintained in Chinese; user-facing docs are bilingual.
+
+## Development
+
+```bash
+git clone https://github.com/DanJiabi/myastro && cd myastro
+pip install -e ".[dev]"                 # or: pip install -e . pytest ruff pyflakes ztfquery
+git config core.hooksPath githooks      # versioned pre-push gate (full suite + pyflakes)
+pytest -q                               # 372 tests, offline (network is stubbed)
+pytest -m "unit or guards" -q           # fast lane (~3 s)
+myastro test-map && myastro doc-sync    # regenerate docs (guards fail when stale)
+```
+
+> `requirements-lock.txt` is the maintainer's conda environment record (it contains
+> conda `file://` sources, so it is not a pip lock file). For reproducible pip installs
+> use `constraints.txt`.
+
+The pre-push hook resolves a usable interpreter itself (`MYASTRO_ENV_BIN` →
+`.myastro-env` → active venv → `.venv` → PATH, each pre-flighted with
+`pytest --collect-only`) and never pipes command output, so a red suite cannot slip through.
+
+## Data, privacy, credentials
+
+- Everything stays on your machine: no telemetry, no account, no upload.
+- Downloads use public survey endpoints (MAST, IRSA, VizieR, SIMBAD, NERSC, unwise.me).
+  ZTF metadata via IRSA may benefit from a free account configured in your own tooling —
+  **myastro never stores credentials**.
+- Survey data belongs to the surveys; this tool only fetches it. Cite the surveys you use.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+<sub>中文说明见 [README.zh-CN.md](README.zh-CN.md)。</sub>

myastro-0.3.0/README.md

@@ -0,0 +1,154 @@
+# myastro
+
+[![CI](https://github.com/DanJiabi/myastro/actions/workflows/ci.yml/badge.svg)](https://github.com/DanJiabi/myastro/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/myastro.svg)](https://pypi.org/project/myastro/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**A personal astronomy data toolkit with a memory.** Fetch from public surveys and
+keep a local ledger of *what you already have* — so you stop re-downloading the same sky.
+
+`myastro` answers questions plain query tools don't:
+
+- "Have I already downloaded this patch of sky?" → precise cone search over your ledger
+- "How much of the brick/field index is local?" → coverage against a full catalogue
+- "Which files rotted on disk?" → sha256 baseline audit
+- "Is it still fetchable?" → deduplicated fetches plus source probes
+
+Three entry points, one contract:
+
+| Entry point | Use |
+|---|---|
+| Library | `import myastro as ma` — the only public import (`ma.__all__`) |
+| CLI | `myastro fetch / search / coverage / audit / doctor / backup …` |
+| TUI | `myastro top` — jobs / storage / sources, no config file needed |
+
+> Status: **0.3.0 — alpha**. The facade is the public API; `myastro.io.*` is internal
+> and may change. Breaking changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Install
+
+```bash
+pip install myastro                      # from PyPI
+pip install -c constraints.txt myastro   # with known-good dependency versions
+pip install "myastro[processing]"        # + photometry/imaging deps (planned P2/P3)
+myastro doctor                           # self-check: deps, paths, ledger, filesystem
+```
+
+Python ≥ 3.11. macOS and Linux are supported; Windows is untested (scheduling is
+macOS/Linux only). Optional extras: `[processing]`, `[asassn]`, `[ztfquery]`.
+
+## Quick start
+
+```python
+import myastro as ma
+
+# 1) fetch — deduplicated: the same params never hit the network twice
+r = ma.fetch("tess", target="WASP-12", sector=20)
+print(r.paths[0])
+
+# 2) what do I already have near this position?
+for hit in ma.search(near=(97.6367, 29.6723), radius_deg=0.5):
+    print(f"{hit['source']:10s} sep={hit['sep_deg']:.4f}°  {hit['path']}")
+
+# 3) coverage against a full catalogue index
+print(ma.coverage("legacy-bricks"))      # {'local': 7, 'total': 366912, ...}
+
+# 4) integrity: build a sha256 baseline, then detect silent corruption
+print(ma.audit())
+```
+
+Data root defaults to `~/myastro-data`; the ledger defaults to
+`~/.local/state/myastro/astro.db`. Both are overridable:
+
+```bash
+export MYASTRO_DATA=/path/to/your/data               # may live on a NAS
+export MYASTRO_DB=~/.local/state/myastro/astro.db    # must be a LOCAL disk (SQLite WAL)
+```
+
+Keeping the ledger local while data lives on a NAS is the intended layout —
+`myastro doctor` fails when the ledger sits on NFS/CIFS.
+
+## CLI
+
+```bash
+myastro init                               # create data root + ledger (idempotent)
+myastro doctor                             # environment self-check (exit 1 if broken)
+myastro backup --out ~/myastro-backup      # online SQLite backup + manifest
+myastro restore ~/myastro-backup/<stamp> --force   # refuses to overwrite unless --force
+myastro fetch tess --target "WASP-12" --sector 20  # args generated from descriptors
+myastro jobs / wait / retry / delete / retry-batch
+myastro search --near 196.18 33.35 --radius 0.2
+myastro coverage legacy-bricks
+myastro audit                              # sha256 baseline / corruption report
+myastro index list | index update <name>   # local indexes (Legacy bricks, ZTF fields)
+myastro health | schedule install health   # source probes, launchd (macOS)
+myastro top                                # TUI
+```
+
+Exit codes are a contract, so scripts can branch:
+`0` ok · `1` partial failure / doctor found problems · `2` bad parameter ·
+`3` not found · `4` network · `5` state not allowed · `130` interrupted.
+
+## What's inside
+
+- **Ledger** — every fetch is a job; datasets, files, parameters, provenance and
+  coordinates are recorded. Data files are the truth, the ledger is the index.
+- **Deduplication** — cache key is a normalized `(source, params)` hash: the same
+  request never hits the network twice; cache hits return the original metadata.
+- **10 sources** — TESS light curves, Gaia DR3 cones, ZTF frames / metadata / light
+  curves, MPC ephemerides, SIMBAD, VizieR, Legacy Surveys tractor bricks, unWISE
+  cutouts, plus YAML manifests for bulk URL lists.
+- **Precise cone search** — coordinates are resolved at ingest time (params → meta →
+  index lookup → filename fallback), stored in the ledger, then queried with a
+  bounding box plus haversine refinement and sorted by separation.
+- **Local indexes** — 366k Legacy bricks and 1776 ZTF fields, cached in memory and
+  searched with binary search (sub-millisecond per keystroke in the TUI).
+- **Verifiability** — a capability matrix (`docs/capabilities.md`), a generated test
+  map (`docs/test-map.md`) and design guards: tests fail when docs or registries drift.
+
+## Documentation
+
+| Document | Language | Audience |
+|---|---|---|
+| [Install](docs/en/install.md) · [Quick start](docs/en/quickstart.md) | EN | users |
+| [安装](docs/zh/install.md) · [快速上手](docs/zh/quickstart.md) | 中文 | 用户 |
+| [capabilities.md](docs/capabilities.md) | 中文 | roadmap: what exists, at which maturity |
+| [processing.md](docs/processing.md) | 中文 | pipeline behaviour and failure semantics |
+| [design-io.md](docs/design-io.md) · [design-top.md](docs/design-top.md) | 中文 | layer design and decisions |
+| [testing.md](docs/testing.md) · [test-map.md](docs/test-map.md) | 中文 | test layers, guards, generated map |
+| [release.md](docs/release.md) | 中文 | release process and public-mirror model |
+
+Developer docs are maintained in Chinese; user-facing docs are bilingual.
+
+## Development
+
+```bash
+git clone https://github.com/DanJiabi/myastro && cd myastro
+pip install -e ".[dev]"                 # or: pip install -e . pytest ruff pyflakes ztfquery
+git config core.hooksPath githooks      # versioned pre-push gate (full suite + pyflakes)
+pytest -q                               # 372 tests, offline (network is stubbed)
+pytest -m "unit or guards" -q           # fast lane (~3 s)
+myastro test-map && myastro doc-sync    # regenerate docs (guards fail when stale)
+```
+
+> `requirements-lock.txt` is the maintainer's conda environment record (it contains
+> conda `file://` sources, so it is not a pip lock file). For reproducible pip installs
+> use `constraints.txt`.
+
+The pre-push hook resolves a usable interpreter itself (`MYASTRO_ENV_BIN` →
+`.myastro-env` → active venv → `.venv` → PATH, each pre-flighted with
+`pytest --collect-only`) and never pipes command output, so a red suite cannot slip through.
+
+## Data, privacy, credentials
+
+- Everything stays on your machine: no telemetry, no account, no upload.
+- Downloads use public survey endpoints (MAST, IRSA, VizieR, SIMBAD, NERSC, unwise.me).
+  ZTF metadata via IRSA may benefit from a free account configured in your own tooling —
+  **myastro never stores credentials**.
+- Survey data belongs to the surveys; this tool only fetches it. Cite the surveys you use.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+<sub>中文说明见 [README.zh-CN.md](README.zh-CN.md)。</sub>

myastro-0.3.0/constraints.txt

@@ -0,0 +1,20 @@
+# 已知可用的依赖版本（用于可复现安装）
+#
+#   pip install -c constraints.txt myastro
+#
+# 这些是 0.2.0 开发与测试时使用过的版本，不强制锁定——没有特别需要时
+# 直接 `pip install myastro` 即可。注意 transitleastsquares 需 >=2.0：
+# 2.0 起自带凌星模型（不再需要 batman）且算法有变化，1.x 的 API 不同。
+astropy==8.0.1
+astroquery==0.4.11
+lightkurve==2.6.0
+transitleastsquares==2.0
+numpy==2.5.3
+pandas==2.3.3
+pyarrow==25.0.0
+PyYAML==6.0.3
+requests==2.34.2
+textual==8.2.8
+rich==15.0.0
+numba==0.68.0
+scipy==1.18.1

myastro-0.3.0/docs/capabilities.md

@@ -0,0 +1,118 @@
+# myastro 领域能力清单（master 规划文档） <!-- cap:design.guards -->
+
+版本：0.1｜地位：**最高规划文档**。roadmap 从"做哪个功能"改为"把哪项能力
+推进到哪级"；TUI/CLI/文档都是呈现层客户端，不再牵引架构。
+
+## 0. 工作模式与成熟度
+
+```
+能力 → 契约（门面 API + 契约测试）→ 内核实现 → 呈现（TUI/CLI/文档）
+```
+
+| 级 | 含义 |
+|---|---|
+| L0 | 缺失 |
+| L1 | 内核有实现，无契约 |
+| L2 | 契约就绪（门面导出 + 测试 + 文档生成） |
+| L3 | 至少一个呈现客户端暴露 |
+| L4 | 自动化就绪（无人值守/定时/自愈） |
+
+验收单位是**能力**而非屏幕行为；呈现层 bug（如焦点/布局）不进入本清单。
+
+能力的**证据**在测试层：每个测试挂 `cap` 标记，`myastro test-map` 生成能力→测试映射，四条守卫保证不漂移（见 [testing.md](testing.md)）。
+
+## 1. 数据源管理（source）
+
+| 能力 | 级 | 现状 |
+|---|---|---|
+| 源注册表（schema 化描述符） | L3 | 10 源；SOURCES/URL_SOURCES/TASKS/INDEXES 四表互指有守卫 | <!-- cap:source.registry -->
+| 源健康监测 | L3 | `ma.health()` 端点探测 + 落库 + info 面板新鲜覆盖；实测发现 unwise 已恢复 |。**探测深度=所填 URL**：只探域名根会漏报（unwise 根 200 而 `/cutout_fits` 因参数错返 500）——凡能给出合法最小请求的源都应填该请求 <!-- cap:source.health -->
+| 源接入指南 | L1 | 隐含在代码模式里；缺"接一个新源要动哪几处"的 checklist | <!-- cap:source.contract -->
+| 休眠源处置 | 决策已定 | asassn（后端失联）保留实现+测试防腐烂，恢复日做真实验证；弃用则代码/测试/注册表一并删 | <!-- cap:source.dormant -->
+| 凭据管理 | L1 | IRSA 账号手动配 ~/.ztfquery；无统一凭据层 |
+
+## 2. 下载管理（acquire）
+
+| 能力 | 级 | 现状 |
+|---|---|---|
+| 单件获取 fetch（缓存幂等） | L3 | 门面 + TUI + CLI | <!-- cap:acquire.fetch -->
+| 计划型查询 query（不落盘） | L3 | | <!-- cap:acquire.query -->
+| 批量 batch（批次生命周期） | L3 | 提交/查看/`ma.retry_batch`（失败半批一键重跑）/CLI retry-batch | <!-- cap:acquire.batch --> <!-- cap:acquire.manifest -->
+| 重试/强制重下/删除 | L3 | 含跨进程重建、僵尸判定 | <!-- cap:acquire.retry --> <!-- cap:acquire.cancel -->
+| 断点续传 | L2 | aria2 原生，依赖 daemon 存活 |
+| 定时获取 schedule | L3 | launchd 代理（health 每日/index 每周），`myastro schedule list/install/remove`；调度不自建 | <!-- cap:acquire.schedule -->
+| 带宽礼仪 | L1 | IRSA 夜间建议靠文档；无速率配置 |
+
+## 3. 数据管理（ledger，本地/云端共管）
+
+| 能力 | 级 | 现状 |
+|---|---|---|
+| 溯源账本（params 可反查） | L3 | datasets/files/jobs 三表 | <!-- cap:manage.ledger -->
+| 文件在盘核对 | L2 | exists 三态标记（storage/assets/jobs 产出列） |
+| 完整性校验 | L3 | `ma.audit()` sha 基线+核对（首次建基线，此后测损坏）+ `audit_detail`；CLI `myastro audit`；实测 25 文件基线建立 | <!-- cap:manage.integrity -->
+| 环境自检 `doctor` | L3 | 依赖/路径可写/账本/文件系统/索引/平台；退出码 1 表示有 FAIL | <!-- cap:manage.doctor -->
+| 账本备份与恢复 | L3 | `ma.backup()` / `ma.restore()`；SQLite 在线备份、默认拒绝覆盖、覆盖前留 `.pre-restore-*.bak` | <!-- cap:manage.backup -->
+| 索引浏览 + ✓/☁ 共管视图 | L3 | 批量屏；索引两枚：legacy-bricks（36 万，url 型）/ ztf-fields（1776，builder 型本地构造）；批量资格=索引字段可单独标识获取 | <!-- cap:manage.index -->
+| 按需云端下载 | L3 | 同屏勾选 ☁ → Ctrl+S |
+| 覆盖率统计 | L3 | `ma.coverage(index)`；实测 legacy-bricks 7/366912 | <!-- cap:manage.coverage -->
+| 本地检索（按坐标/时间/目标查已有） | L3 | `ma.search(target/near/since/name)` + CLI `--near/--radius`；**坐标精确化**：入库时解析（params/meta/编号→索引/文件名兜底）存 `datasets.ra/dec`，查询走 SQL 包围盒 + haversine 精判、按角距排序带 sep_deg | <!-- cap:manage.search -->
+| 保留策略 retention | L0 | 无"旧 job 归档、冷数据清理"策略 |
+
+## 4. 数据处理（process）——逐步拓展，先立边界
+
+**边界**：处理逻辑住在 notebook/脚本层（用户域），myastro 的职责是
+**保证原料稳定**（schema 契约）+ **供处理层调用的最小工具**。
+
+判据：**"换个目标还会一模一样地做"的进库**（纯变换、可测试、契约稳定），
+**"取决于这次想干什么"的留 notebook**（选目标、挑参数、画图、叙述）。
+
+| 能力 | 级 | 现状 |
+|---|---|---|
+| 产物 schema 稳定承诺 | L2 | SCHEMA_VERSION=1 声明；列名即契约 |
+| 处理示例 | L3 | 三个阶梯 notebook（凌星/造父/ZTF 差分） |
+| **lc 时序工具库** | **L3** | 9 函数（归一化/筛选/折叠/分箱/幅度/周期搜索/凌星搜索）+ 17 测试；01/02 两片 notebook 已重构使用，数字与重构前逐项对账一致 | <!-- cap:process.lc -->
+| phot 测光工具库 | L0 | 下一步 P2（检测/孔径测光/Gaia G 定标打底、APASS 校验） |
+| imaging 图像工具库 | L0 | P3（对齐/叠加/差分），智能望远镜到手后做 |
+| 派生产物目录约定 | 决策已定 | `data/derived/<目标>/`，与原始数据物理分离；实现待 P4 |
+| 派生数据集溯源（derived_from） | L0 | P4：产物入账本、可反查原料 dataset 与处理参数 |
+| 管线编排（处理链描述/重跑） | L0 | 远期；防止过度设计先不做 |
+
+> **教训载体**：库函数不只是去重，还承载 notebook 里以文字记录的坑——
+> `transit_search` 内部强制归一化（否则 TLS 静默 nan）并返回真深度
+> （TLS `depth` 是凌内/凌外比）；`period_search` 默认 LS+PDM 两步
+> （LS 对非正弦光变系统性偏峰）。测试里有对应的回归项。
+
+## 5. 格式转换（convert）——领域概念确认
+
+天文领域该概念**真实存在且分两层**，但须防"格式金字塔"。
+原则：**正典格式 + 边缘按需转换**（正典 = 表格 parquet / 图像 fits）。
+
+| 能力 | 级 | 现状 |
+|---|---|---|
+| 文件格式（fits 表 → parquet） | L1 | 隐式散在源实现里（tess/meta 即转换） |
+| 时间系统（JD/MJD/BJD ↔ 相位） | L1 | notebook 手写；无统一工具 |
+| 星等 ↔ 流量（含归一化） | L1 | 项目 2 手写 f/median；ZTF mag 列原生 |
+| 坐标系（ICRS ↔ Galactic） | L0 | astropy 一行的事，按需暴露 |
+| 互操作导出（CSV/AstroImageJ/VStar） | L0 | 有真实场景（AAVSO 上报）再做 |
+
+> 判断标准：转换能力只在**第二个真实消费者出现**时升 L2（老规矩）。
+
+## 6. 呈现层（presentation，非能力域）
+
+| 客户端 | 现状 |
+|---|---|
+| TUI（top） | 三面板 + 新建/批量/**预填充**模态（F1 新建、F2 从选中作业预填）；身份寻址契约 | <!-- cap:present.tui -->
+| CLI | 16 子命令：fetch 参数由描述符自动生成；错误→退出码 2/3/4/5 | <!-- cap:present.cli -->
+| 文档 | 矩阵生成（doc-sync）；API 参考未生成 |
+| 第三方 | 门面 + 错误契约（含作业失败类型映射）+ 扩展点 register_source + `ma.prefill`（spec→表单，客户端共用） | <!-- cap:facade.api -->
+
+## 7. 当前最高价值的缺口（按能力排序）
+
+3. **保留策略 retention**（L0）：job 归档、冷数据清理
+4. **本地检索坐标精确化**：现为 params 粗匹配，量级上来后需空间索引
+
+## 8. 维护纪律
+
+- 本文档随能力变动更新（提交含能力变化时必须同步）
+- 新工作入队格式："把 X 能力从 Ln 推到 Lm"，呈现层工作单列
+- 每次架构 review 对照本文档检查：是否有能力降级/无契约实现