wangnengdejiamao/Astro_Agent

# Astro 代理 一款端到端的天文研究智能体，将巡天数据获取、定量建模、证据审计和论文撰写连接到一个可审计的 LangGraph 工作流中。 本仓库仅包含**代码、提示词、配置和可复现脚本**。 私有 API 密钥、下载的论文、FITS/光谱产品、SQLite 索引、本地知识图谱工作空间和个人报告均被排除在版本控制之外，并在运行时从本地 `.env` 文件加载。 ## 1. 项目概述 Astro Agent 围绕一个问题构建：*“科学级研究工作流能否表示为一个由确定性、可审查的智能体组成的图？”* 系统包含两个协作层： - **`Astro_Agent/analysis_agent`** — 一个 LangGraph 状态机，负责解析目标、获取多源巡天数据、运行建模迭代、根据物理学原理审计结果、从本地文献中检索可比方法，并在质量保证门控通过后生成一份符合 ApJ 风格的论文及同行评审笔记。 - **`Astro_Agent/astro_toolbox`** — 一个包含巡天客户端和科学建模模块的领域工具箱（光谱、测光、光变曲线、SED、白矮星拟合、径向速度/周期分析、消光、运动学回溯、星团成员判定、致密双星诊断）。 第三个仅限本地的系统（一个基于文献的知识图谱）可通过 `ASTRO_AGENT_KG_WORKSPACE` 接入。图谱本身、其语料库和提取流水线**并非本仓库的一部分**——仅提供查询外部工作空间的导航器节点。 ## 2. 系统架构 ``` ┌────────────────────────────────────────┐ │ CLI · FastAPI server · Web UI │ └───────────────────┬────────────────────┘ │ ┌───────────────────────▼───────────────────────┐ │ analysis_agent (LangGraph state machine) │ │ resolve → data_fetch → memory_advisor → │ │ structure_planner → rag/kg navigator → │ │ method_scout → source_research → │ │ iteration_1/2/3 → model_supervisor → │ │ claude_code_delegate → qa_gate ⇄ replan → │ │ drafter → paper_qc ⇄ reflexion → peer_review │ └───────┬─────────────────────────────┬─────────┘ │ │ ┌───────────▼──────────┐ ┌────────────▼────────────┐ │ astro_toolbox │ │ local RAG + optional │ │ (survey + modeling) │ │ KG workspace (private) │ └──────────────────────┘ └─────────────────────────┘ ``` 智能体与工具箱仅通过写入每次运行目录的结构化 JSON 工件进行通信。这使得每个步骤都可检查、可回放，而无需重新运行上游节点。 ## 3. 工作流设计 ### 3.1 为何选择状态图而非自由 ReAct 循环 天文学分析是**长周期、审计密集型且部分确定性的**：目标分类决定了哪种物理模型有效，建模主张必须有具体证据支持。自由思维链智能体在证据缺失时容易凭空捏造参数值。而 LangGraph 状态机强制执行： - 明确的节点职责和类型化状态（`AnalysisState` TypedDict）， - 用于重规划 / 反思 / 异常退出的条件边， - 最多三次建模迭代和两次重规划 / 两次反思重写的硬性上限， - 文件系统检查点（`01_resolved_target.json`、`02_data_fetch.json`、…）同时作为人类可读的溯源记录。 ### 3.2 节点职责 | 节点 | 职责 | 备注 | |------|----------------|-------| | `resolve` | 对名称进行 SIMBAD 交叉识别 ↔ 赤经/赤纬 | 通过 `--skip-simbad` 支持离线模式 | | `data_fetcher` | 并行调用 `astro_toolbox` 中的 20 多个巡天客户端 | 写入统一的 `run_summary` | | `memory_advisor` | 读取过去方法/工具结果的 SQLite 账本 | 引导规划器走向已知的成功路径 | | `structure_planner` | 根据 SIMBAD 类别（白矮星 / 亚矮 OB / 激变变星 / 磁激变变星 / …）路由到光谱+SED、HRD+SED 测光后备方案、仅 SED 或数据不足 | 每个分支解锁不同的证据集 | | `rag_navigator` | 在本地 SQLite 文献索引上进行 BM25 搜索，预先标记了 46 种仪器和 24 个方法族 | 对领域术语精准 | | `kg_navigator` | 在外部 KG 工作空间上进行可选的方法迁移搜索 | 缺失时优雅降级 | | `method_scout` | 比较 RAG/KG 命中结果与当前工具箱能力，标记能力差距 | 可选 LLM 辅助 | | `source_research` | 针对每个目标的证据包：SIMBAD 关联的参考文献、精确 RAG 匹配、HST/SED/光谱线质量保证 | 决定下游建模主张的门控 | | `iteration_1/2/3` | 强制性的基线 → 残差 → 系统误差传递 | 每个必须收敛或被标记为未收敛 | | `model_supervisor` | 审计残差、网格边界拟合、缺失导出、无光谱主张，生成带有 `owner / priority / acceptance` 的修复操作 | | | `claude_code_delegate` | 可选地将修复操作移交给 Claude Code 子进程 | | | `qa_gate` | 路由 `clear_for_draft` → 起草器，`model_mismatch` → 重规划，否则 → 异常报告 | | | `drafter` | PaperOrchestra 五智能体论文流水线（大纲 / 绘图 / 文献综述 / 段落写作 / 润色），生成 `aastex631` LaTeX | | | `paper_qc` | ApJ 检查清单：参数表、单位、引用、图表 | | | `reflexion` | 驱动质量检查的针对性重写，设有硬性上限 | | | `peer_reviewer` | 生成四条科学问题评审笔记 | | | `toolbox_evolution` | 记录已确认的能力差距及所需的代码/文档更新 | | ### 3.3 强制性的三次建模迭代 `iteration_1_baseline → iteration_2_residuals → iteration_3_systematics` 是不可跳过的：没有残差诊断和系统检查的单一最佳拟合值将被 `qa_gate` 拒绝。这是智能体拒绝发布缺乏足够支持的主张的主要机制。 ### 3.4 模型不匹配自愈 当 SIMBAD 识别目标为例如亚矮 OB 或激变变星，但活动分支是白矮星拟合时，`qa_gate` 发出 `model_mismatch`，条件边路由回 `structure_planner`，重试计数器将重规划限制为两次尝试。如果目标的流水线未实现，运行将以 `replan_blocked` 和人工触发条目终止，而不是生成论文。 ### 3.5 反思循环 `paper_qc` 失败（缺少参数表、不受支持的主张、引用缺口）将结构化发现反馈到 `reflexion`，该节点仅对有问题的部分进行*针对性*重写，而不是重新运行整个起草器。该循环限制为两次重写。 ## 4. 方法论选择 ### 4.1 BM25 + 规则标记检索 vs. 稠密向量 天文学文本包含大量高度特定的标记（`DA white dwarf`、`logg`、`Balmer lines`、`Lomb-Scargle`、`Bayestar2019`）。经验证，带有领域规则预标记器（46 种仪器 × 24 个方法族）的 BM25 在方法迁移查询上优于通用稠密检索，同时保持廉价且可审计。`rag_navigator` 和 `method_scout` 使用相同的存储。 ### 4.2 文件系统作为记忆 每个节点向运行目录写入一个带编号的 JSON 工件。这： - 消除了框架锁定（无专有检查点格式）， - 提供人类可读的溯源链， - 允许 `--astrotool-run ` 恢复运行而无需重新下载巡天产品， - 使比较两次运行只需一个 `diff`。 一个单独的 SQLite **方法成功账本**跨运行维护并由 `memory_advisor` 读取；它仅存储聚合结果，不存储原始数据。 ### 4.3 证据门控的参数主张 `source_research` 生成一个针对每个目标的包，明确列出哪些建模主张*当前被支持*，哪些*因证据缺失而被阻止*。在 `photometric_hrd_sed_fallback`（无光谱）中，智能体可以报告来自 SED + Gaia HRD 的初步有效温度 / 半径 / 光度，但会阻止最终光谱分类、谱线检测、化学组成、精确表面重力、质量和冷却年龄，直到添加更强的证据。起草器和 `paper_qc` 遵守这些门控。 ### 4.4 主管发布的修复操作 `model_supervisor` 不“修复”结果；它发出结构化的修复任务（`所有者`、`优先级`、`验收标准`）。然后，修复操作由下一个迭代节点执行，或者可选地由 `claude_code_delegate` 调用 Claude Code 作为子进程执行。这使科学决策和代码更改保持在单独可审查的工件上。 ### 4.5 PaperOrchestra：五智能体论文流水线 起草被拆分为确定性的子角色： - **大纲智能体** — 每个部分所需的部分计划和证据， - **绘图智能体** — 关联到证据工件的图表列表， - **文献综述智能体** — 基于 RAG 的参考文献， - **段落写作智能体** — 根据大纲生成每个部分的 LaTeX， - **内容润色智能体** — 一致性、单位、主张/证据关联。 每个子角色的提示清单位于 `paper_orchestra/agents_manifest.json`；Codex 风格的工具/上下文规则（有限上下文窗口、结构化工具 I/O、审查优先质量保证）位于 `paper_orchestra/codex_style_guidance.json`。 ## 5. Astro 工具箱 ### 5.1 巡天覆盖 光谱：SDSS DR18、DESI DR1、LAMOST DR8、HST COS/STIS、JWST NIRSpec/MIRI、GALAH DR4、KOA/Keck。 测光：SDSS *ugriz*、Gaia DR3、2MASS、WISE、GALEX、SPHEREx。 时域：ZTF DR23、TESS、Kepler/K2、Gaia 历元测光、NEOWISE。 X 射线：通过 HEASARC 的 ROSAT / XMM / Chandra。 ### 5.2 建模模块 `sed`、`sed_decoupled` (Lin+2025 UPK 13-c2 双组分解耦)、`wd_fitting` (Koester / TLUSTY 大气模型 + 冷却轨迹 + 质量-半径)、`cooling_age`、`rv_fitting` (互相关 / 模板匹配)、`period_analysis` (Lomb–Scargle + 折叠)、`orbit_traceback` (六维相空间积分)、`hr_diagram`、`cluster_membership` (运动学 + 空间 χ²)、`extinction` (Bayestar2019 / SFD98)、`compact_binary_report`、`disk_eclipse_mcmc`、`ingress_measurement`、`binary_orbit`、恒星模板。 ### 5.3 单目标驱动器 `run_single_target_all_tools.py` 编排整个工具箱并生成 `data_fetcher` 消费的 JSON `run_summary`。 ## 6. 仓库布局 ``` . ├── Astro_Agent/ │ ├── analysis_agent/ # LangGraph workflow, LLM clients, QA, paper pipeline │ ├── astro_toolbox/ # survey clients + scientific modeling modules │ ├── claude_code_toolbox/ # optional Claude Code subprocess wrapper │ ├── scripts/ # ablation, prompt tuning, review, helper scripts │ ├── web/ # local web UI │ └── USAGE.md # extended usage notes ├── rag_pipeline/ # local literature RAG utilities ├── start_services.sh # local launcher ├── stop_services.sh # local stopper └── README.md ``` 注意：私有的文献 → KG 工作空间可以位于磁盘上的任何位置，并通过 `ASTRO_AGENT_KG_WORKSPACE` 引用。其构建代码、语料库和导出**不**属于本仓库。 ## 7. 设置 Python 3.10+。 ``` python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install numpy pandas scipy matplotlib astropy astroquery requests \ python-dotenv pyyaml networkx fastapi uvicorn python -m pip install openai langgraph json-repair scikit-learn ``` 可选，取决于您使用的模块： ``` python -m pip install lightkurve galpy dustmaps emcee corner sentence-transformers ``` 复制并编辑本地环境文件（切勿提交）： ``` cp Astro_Agent/analysis_agent/.env.example Astro_Agent/analysis_agent/.env cp Astro_Agent/astro_toolbox/.env.example Astro_Agent/astro_toolbox/.env ``` 常见变量： ``` ASTRO_AGENT_MODEL_PROVIDER=deepseek # or gemini / kimi DEEPSEEK_BASE_URL=https://api.deepseek.com DEEPSEEK_MODEL=deepseek-v4-pro DEEPSEEK_API_KEY=... ADS_DEV_KEY=... GAIA_TOKEN=... LAMOST_TOKEN=... ASTRO_AGENT_KG_WORKSPACE=/absolute/path/to/private/kg_workspace # optional ``` ## 8. 运行 ``` python -m Astro_Agent.analysis_agent.cli "Gaia DR3 865415642195374464" \ --ra 232.3955 --dec 29.4672 ``` 完整的工具箱支持分析： ``` python -m Astro_Agent.analysis_agent.cli "Gaia DR3 865415642195374464" \ --ra 232.3955 --dec 29.4672 --execute ``` LLM 支持的写作/审阅： ``` python -m Astro_Agent.analysis_agent.cli "Gaia DR3 865415642195374464" \ --ra 232.3955 --dec 29.4672 --execute --use-llm --llm-provider deepseek ``` 本地 HTTP 服务 + Web UI： ``` python -m uvicorn Astro_Agent.analysis_agent.server:app \ --host 0.0.0.0 --port 8765 --reload # 然后打开 http://localhost:8765/ ``` 工具箱独立使用： ``` python -m Astro_Agent.astro_toolbox.run_single_target_all_tools ``` ## 9. 输出 每次运行将结果写入 `Astro_Agent/output/analysis_agent/_/`，包含： - 每个节点的带编号 JSON 检查点， - 来自工具箱的 `run_summary.json`， - `source_research/` 证据包， - 要么是 `paper/.tex` + 图表 + 参考文献，要么是当 QA 阻止发布时的 `abnormal_analysis_report.md`， - `peer_review.md`、`toolbox_evolution.md`， - 主管修复操作账本。 所有输出均被 gitignore。 ## 10. 数据、归属、安全 本仓库仅包含编排代码，不重新分发第三方巡天数据。如果您发布基于工具箱获取的数据得出的结果，请引用原始提供商并遵守其条款（SIMBAD/CDS、VizieR、ADS、Gaia、SDSS、DESI、MAST、ZTF、WISE、2MASS、GALEX、LAMOST、GALAH、KOA/Keck、HEASARC 等）。 推送前： ``` git status --short git ls-files --others --exclude-standard rg -n "sk-[A-Za-z0-9_-]{20,}|BEGIN .*PRIVATE KEY|password\s*=" \ -g '!**/.git/**' -g '!**/.env' . find . -path './.git' -prune -o -type f -size +50M -print ``` 仅应提交代码、公开提示词、公开配置、文档和轻量级示例。将 `.env`、PDF、FITS、SQLite 索引、KG 工作空间、私有报告和运行工件保留在本地。 ## 许可证 仅供研究使用。请遵守您在本地配置的外部数据服务和模型提供商的条款。

标签：AV绕过, FastAPI, LangGraph, TCP SYN 扫描, Web UI, 人工智能代理, 代理工作流, 光变曲线分析, 光度测量, 光谱分析, 光谱能量分布拟合, 可重现科学计算, 命令行界面, 多波段勘测, 多波段数据获取, 天体物理, 天文学, 天文数据归档, 学术稿件生成, 定量建模, 工作流引擎, 数据科学, 数据驱动研究, 状态机, 白矮星建模, 知识图谱集成, 科学研究自动化, 科学自动化, 端到端工作流, 证据门控, 质量保证审计, 资源验证, 逆向工具