spedas_agent_kit

# SPEDAS 代理工具包 `spedas_agent_kit` 是 SPEDAS 组织的 MCP 服务器，用于代理太阳物理工作流。它呈现了一个面向 SPEDAS 的**数据层**，并按数据源类别组织功能，而不是按用于实现它们的内部后端包。 当前设计遵循 Jason 的 A+B 方向： - **A. SPEDAS 数据层** — 源类别的统一入口点，例如 `cdaweb`、`pds` 和 `spice`/geometry。 - **B. SPEDAS 科学工作流层** — 高级规划工具，允许 Claude Code、Codex、OpenCode、LingTai 或其他代理从科学问题开始，然后选择特定于源的操作。 实现后端包应对维护人员可见，但不应成为用户的第一心理模型。 ## 仓库 - 官方仓库：<https://github.com/spedas/spedas_agent_kit> - Python 包名：`spedas-agent-kit` - Python 模块 / CLI 模块：`spedas_agent_kit` - 规范共享技能：`src/spedas_agent_kit/resources/skills/`（与工具包一起打包；包装应保持薄） - 默认 MCP 工具数量：17（兼容性和分析工具按需注册）；广告工具带有 MCP `ToolAnnotations` 和 `meta.surface`（`primary`、`advanced` 或 `compat`），以便启动器按表面和副作用提示进行筛选。 ## 运行 SPEDAS 代理工具包研究的实用指南 将本节用作研究人员和代理的 README 级操作指南。下面的详细功能映射是参考；本指南是从科学问题到可复制工件的最短安全路径。 ### 默认循环 1. **重述科学问题和约束。** 捕获目标、任务、仪器或可观察量、时间范围，以及请求是太阳物理、行星、仅几何还是本地分析导向。 2. **要求 SPEDAS 代理工具包在获取数据之前选择数据源系列。** 首先使用 `spedas_overview()`，然后调用 `search_spedas_data_sources(...)` 或 `plan_spedas_observation(...)`。不要直接跳转到低级存档工具，只是因为任务名称与后端匹配。 3. **创建运行目录。** 对于可能获取、转换、渲染或以后引用的工作，首先调用 `create_spedas_analysis_bundle(...)`，并将数据、绘图、溯源和注释保留在该包下。 4. **浏览和获取数据。** 使用数据层工具浏览源类别和参数。保持公共存档请求为小、可复制的时间间隔和明确的参数。 5. **使用几何和分析作为后续步骤。** SPICE 几何、坐标转换、光谱、场模型、粒子矩和渲染工具应使用明确的文件/工件。它们不应隐藏大型下载或直接返回批量数组。 6. **返回路径、溯源和注意事项。** 一个好的答案会命名源、数据集/产品、变量、时间窗口、输出文件、验证/注意事项和下一个可复制命令。它不会将 CDF 内容或巨大数组粘贴到聊天中。 ### 选择主要源系列 | 用户请求模式 | 主导 | 然后使用 | 常见注意事项 | |---|---|---|---| | 近地磁层、太阳风、MMS、THEMIS、Cluster、Geotail、Van Allen / RBSP、STEREO、PSP、太阳轨道器、尤利西斯、航行者号太阳系 | `source_type="cdaweb"` | CDAWeb 浏览/加载/获取工具；仅当几何是问题的一部分时使用 SPICE | 任务名称也可能出现在行星档案中；保持科学背景在计划中。 | | 行星任务字段/粒子在行星上，例如 Juno/Jupiter、Cassini/Saturn、MAVEN/Mars、新视野号/Pluto | `source_type="pds"` | PDS 发现/获取，加上 SPICE 几何，当轨迹或观测几何重要时 | 像“弓形激波”、“磁层”、“等离子体”或“高能粒子”这样的通用词不足以选择 CDAWeb，如果目标是行星。 | | 星历、距离、轨迹、帧转换、观测者-目标几何 | `source_type="spice"` | 浏览任务/帧与 `browse_data_sources` / `load_data_source`；用 `get_ephemeris`、`compute_distance`、`transform_coordinates` 计算 | SPICE 是几何，而不是测量数据。将它与 CDAWeb/PDS 结合使用时，也需要字段或粒子。 | | 任何 HAPI 兼容的服务器在捆绑类别之外 | `browse_data_sources(source_type="hapi")` | 按照 `next_tools` 到 `browse_hapi_catalog`、`fetch_hapi_data` | 直接工具从默认表面取消（问题 #87）；通过发现或 `SPEDAS_AGENT_KIT_DATASOURCE_TOOLS=1` 访问。需要可选的 `hapi` 额外功能和明确的 HAPI 服务器 URL。 | | 地面磁通量/ FDSN 站磁数据 | `browse_data_sources(source_type="fdsn")` | 按照 `next_tools` 到 `browse_fdsn_datasets`、`fetch_fdsn_data` | 直接工具从默认表面取消（问题 #87）；通过发现或设置 `SPEDAS_AGENT_KIT_DATASOURCE_TOOLS=1` 访问。需要可选的 `fdsn` 额外功能和时间范围。 | | 数据存在后的本地文件分析 | 分析工具 | 坐标转换、FAC/minvar、光谱、场/L-shell、粒子矩/光谱、`render_tplot` | 输入是文件；安装 `spedas-agent-kit[analysis]` 以获取可选后端。 | ### 最小 MCP 调用序列 对于开放式问题，安全骨架是： ```text spedas_overview() search_spedas_data_sources(question="...", target="...", observables=[...]) plan_spedas_observation(science_goal="...", start="...", stop="...", target="...", observables=[...]) create_spedas_analysis_bundle(study_name="...", output_dir="...") browse_data_sources(source_type="cdaweb|pds|spice|hapi|fdsn") load_data_source(source_type="...", source_id="...") browse_data_parameters(source_type="...", dataset_id="...") fetch_data_product(source_type="...", dataset_id="...", parameters=[...], start="...", stop="...", output_dir="...") ``` 仅当计划需要时添加几何或本地分析： ```text get_ephemeris(...) compute_distance(...) transform_timeseries_coordinates(input_file="...", output_file="...") dynamic_power_spectrum(input_file="...", output_dir="...") render_tplot(input_files=[...], output_file="...") ``` ### 实用配方 - **PSP 近日点太阳风**：首先路由科学问题，让 CDAWeb 引导测量发现，然后仅为航天器-太阳几何添加 SPICE。参见 `docs/examples/psp_perihelion_solar_wind.md`。 - **MMS 磁层顶间隔**：使用 `plan_spedas_observation` 保持任务、可观察量和间隔明确；在绘图或转换之前，将选定的 CDAWeb 变量获取到分析包中。参见 `docs/examples/mms_magnetopause_workflow.md`。 - **朱诺 / 行星等离子体相互作用**：让 PDS 引导 MAG/等离子体存档发现，并使用 SPICE 作为几何伴侣。参见 `docs/examples/juno_pds_spice_workflow.md`。 - **概述 + 地磁指数上下文**：对于 IDL-SPEDAS 样式的摘要图或 Dst/AE/Kp/SYM-H 上下文，加载 Claude 技能 `overview-geomagnetic-indices`，并使用 `spedas_overview()["guided_recipes"]` 将意图映射到 CDAWeb/HAPI OMNI 数据集或 PySPEDAS 京都/NOAA 加载器。 - **辐射带或场模型分析**：首先获取或准备位置工件，然后调用 `evaluate_magnetic_field(...)`、`calculate_lshell(...)` 或相关分析工具。记录模型参数；扭曲场模型故意需要明确的地磁输入。 - **频谱或粒子矩**：构建本地输入工件，然后将分析工具运行到输出目录。返回 `.npz`/CSV/PNG 路径和摘要范围，而不是批量矩阵。 ### 工件和溯源合同 每个非琐碎运行都应留下一个目录，另一个研究人员可以审核： ```text <run>/ requests/ 原始提示、计划或配方 data/ 获取或准备的测量文件 plots/ PNG/SVG/PDF 渲染 provenance/ 源 ID、参数、缓存注释、工具版本、哈希 notes/ 解释、注意事项和下一步骤 ``` 报告结果时，至少包括： - 科学目标和时间范围； - 选定的源系列（`cdaweb`、`pds`、`spice`、`hapi`、`fdsn` 或本地分析）； - 数据集/产品 ID 和参数/变量； - 输出文件和哈希（如果可用）； - 依赖或数据访问注意事项（`missing_dependency`、存档速率限制、缓存验证、不可用的内核、无匹配站等）； - 需要复制或扩展运行的下一个命令或 MCP 调用。 ### 代理安全检查清单 - 优先使用统一的数据层和科学工作流工具，而不是兼容的低级工具进行新工作。 - 不要从一个关键词推断源。使用目标 + 任务 + 可观察量 + 时间上下文，特别是在行星和近地使用通用词时，例如“磁层”、“弓形激波”、“辐射带”、“太阳风”和“高能粒子”。 - 保持获取范围窄。公共存档可以限制速率或冷；长间隔应有意分割并记录在溯源中。 - 将可选额外功能视为可选。分析工具未在基本安装中注册或宣传；直接 HAPI/FDSN 工具从默认表面取消（问题 #87），通过 `browse_data_sources(source_type="hapi"/"fdsn")` 发现或设置 `SPEDAS_AGENT_KIT_DATASOURCE_TOOLS=1` 访问。当缺少后端额外功能时，它们会返回明确的 `missing_dependency` 响应。安装 `analysis`、`hapi` 或 `fdsn` 仅当工作流需要该后端时。 - 在解释生成工件之前验证它们。检查文件存在、行/样本计数、时间覆盖、坐标框架以及工具是否返回警告或注意事项。 ## 分层功能映射 ### 1. 数据层工具 从这里开始，当用户请求数据、数据集、参数、产品、存档或缓存状态时。 - `browse_data_sources(source_type="all", query=None)` — 浏览 SPEDAS 数据源类别，或深入到一个类别。 - `load_data_source(source_type, source_id, mode="compact", limit=None, offset=0, instrument=None, dataset_query=None, include_full_prompt=False)` — 加载源上下文。CDAWeb 观测站默认采用紧凑的结构化数据集页面（数据集 ID、仪器、覆盖范围、下一个调用）；使用 `limit`/`offset` 和过滤器进行大型目录，或使用 `mode="full"` / `include_full_prompt=True` 获取旧版完整提示。 - `browse_data_parameters(source_type, dataset_id, dataset_ids=None)` — 浏览 CDAWeb 或 PDS 数据集的参数/元数据；对于 SPICE，返回几何/帧上下文。 - `fetch_data_product(source_type, dataset_id, parameters, start=None, stop=None, output_dir=None, format="csv", limit=None)` — CDAWeb/PDS 的统一测量/存档数据获取。SPICE 请求被路由到几何工具。`limit` 目前是一个 CDAWeb 导向的安全控制；PDS 获取应通过时间/参数缩小。 - `manage_data_cache(source_type="all", action="status", cache_dir=None, mission=None, ...)` — 源类别的统一缓存状态/维护。它通过一个宣传的工具传递源特定的缓存选项：CDAWeb（`category`、`observatory`、`dataset_ids`、`older_than_days`、`dry_run`、`detail`）、PDS（`category`、`mission`、`dataset_ids`、`older_than_days`、`dry_run`、`detail`、`force`）和 SPICE（`mission`、`filenames`）。每次调用的 `cache_dir` 仅作为指导报告；后端缓存根由 MCP 服务器环境配置。 支持的 `source_type` 值： | source_type | 用途 | 主要数据层路径 | |---|---|---| | `cdaweb` | 太阳物理观测时间序列、等离子体/场/粒子、太阳风、CDF 类间隔 | `browse_data_sources` → `load_data_source` → `browse_data_parameters` → `fetch_data_product` | | `pds` | 行星等离子体相互作用档案、行星任务数据集、PDS 元数据/产品 | `browse_data_sources` → `load_data_source` → `browse_data_parameters` → `fetch_data_product` | | `spice` | 几何、星历、轨迹、距离、坐标帧/转换 | `browse_data_sources` → `load_data_source` → 几何工具 | | `hapi` | 任何 HAPI 兼容的服务器（CDAWeb、PDS-PPI、ISWA、LISIRD、大学网络） | `browse_data_sources(source_type="hapi")` → `browse_hapi_catalog` → `fetch_hapi_data` | | `fdsn` | FDSN/MTH5 地面磁通量（MT）磁站来自 EarthScope | `browse_data_sources(source_type="fdsn")` → `browse_fdsn_datasets` → `fetch_fdsn_data` | `hapi` 和 `fdsn` 按服务器/时间范围寻址（HAPI 需要 `server_url`，FDSN 需要 `trange`），因此统一的 `load_data_source`/`browse_data_parameters`/`fetch_data_product` 工具识别这些 `source_type` 值，但将您路由到专用 `browse_hapi_catalog`/`fetch_hapi_data` 和 `browse_fdsn_datasets`/`fetch_fdsn_data` 工具（参见第 6 节）。两者都需要可选的额外功能，并在未安装时降级为明确的 `missing_dependency` 错误。 > **表面说明（问题 #87）：** 四个直接 HAPI/FDSN 工具从默认 `list_tools` 表面取消；从 `browse_data_sources(source_type="hapi"/"fdsn")` 开始并遵循其 `next_tools` 提示。设置 `SPEDAS_AGENT_KIT_DATASOURCE_TOOLS=1` 以直接在 `list_tools` 中宣传四个工具（与 `SPEDAS_AGENT_KIT_COMPAT_TOOLS=1` 对称）。它们在该标志下仍然可调用，并带有表面元数据 `meta["surface"] == "datasource"`。 紧凑的 CDAWeb 目录发现示例： ```python # 默认 MMS 页面是紧凑的（<12 KB），并包含每个数据集的精确下一个调用。 load_data_source(source_type="cdaweb", source_id="mms") # 分页或缩小大型观测站。 load_data_source(source_type="cdaweb", source_id="mms", limit=10, offset=10) load_data_source(source_type="cdaweb", source_id="mms", instrument="fgm", dataset_query="srvy") # 仅当需要时选择旧版人类提示。 load_data_source(source_type="cdaweb", source_id="mms", mode="full") ``` ### 2. 科学工作流工具 从这里开始处理开放式科学请求。 - `spedas_overview()` — 能力和推荐工作流的紧凑映射。 - `search_spedas_data_sources(question, target=None, observables=None)` — 推荐哪个数据源类别应该引导请求。 - `plan_spedas_observation(science_goal, start=None, stop=None, target=None, observables=None, data_sources=None)` — 在获取数据之前生成源特定计划。 - `compare_cdaweb_pds_spice(science_goal="")` — 解释源边界并选择正确的源系列。 - `create_spedas_analysis_bundle(study_name, output_dir, ...)` — 使用 `requests/`、`data/`、`plots/`、`provenance/` 和 `notes/` 文件夹创建请求/溯源脚手架。 ### 3. 几何工具 SPICE 作为数据源类别公开，但几何操作作为明确的工具更清晰： - 使用 `browse_data_sources(source_type="spice")` 浏览 SPICE 任务；响应还包括带有帧描述和别名的 `frame_catalog`。 - 显式浏览相同的 SPICE 坐标帧目录，使用 `load_data_source(source_type="spice", source_id="frames")` 或 `browse_data_parameters(source_type="spice", dataset_id="frames")`；使用 `supported_frame_names` 作为 `transform_coordinates` 的 `from_frame`/`to_frame` 值。 - `get_ephemeris(mission, target, start, stop, step="1h", frame="J2000", observer=None)` - `compute_distance(mission, target, observer, start, stop, step="1h")` - `transform_coordinates(mission, coordinates, from_frame, to_frame, epoch=None)` SPICE 内核缓存状态/加载/清理/检查/清除操作通过 `manage_data_cache(source_type="spice", action=..., mission=..., filenames=...)` 公开。 ### 4. 分析工具（可选 `pyspedas` 后端） 对获取的工件进行第一阶段坐标转换和第二阶段时频分析。这些工具需要可选的 `analysis` 附加包（`pip install 'spedas-agent-kit[analysis]'`，它安装 `pyspedas>=2.0` 和 `matplotlib`，以及 `PyWavelets`）。`pyspedas`/`matplotlib`/`PyWavelets` **不是** 基础安装的一部分，只有当它们的依赖项可导入时，分析工具才会向 MCP 注册。在基础安装中，它们不会出现在 `list_tools` 中；在调用 MCP 客户端之前，请安装 `spedas-agent-kit[analysis]`。它们是文件输入/文件输出：输入是获取的 CSV/JSON 产品的路径，批量输出写入磁盘，只返回路径和简洁的摘要（从不返回原始数组）。 第一阶段 — 坐标转换： - `transform_timeseries_coordinates(input_file, coord_in, coord_out, output_file, time_col="time", vector_cols=None)` — 在 `gse`/`gsm`/`sm`/`gei`/`geo`/`mag`/`j2000` 之间转换 Nx3 矢量时间序列（`pyspedas` `cotrans`）。 - `generate_fac_matrix(mag_file, output_file, other_dim="xgse", pos_file=None, time_col="time", vector_cols=None, mag_coord="gse")` — 构建每样本场向坐标（FAC）3×3 旋转矩阵（`fac_matrix_make`）。位置相关模式（`rgeo`/`mrgeo`/`phigeo`/`mphigeo`/`phism`/`mphism`）需要一个 GEI `pos_file`；如果位置时间网格与磁场时间网格不同，则响应报告 `pos_rows_in`、`mag_rows`、`position_interpolated`，以及稀疏上采样的警告，而不是静默隐藏对齐/插值。 - `analyze_minvar_coordinates(input_file, output_file=None, output_dir=None, twindow=None, tslide=None, time_col="time", vector_cols=None)` — 最小方差分析 / LMN 边界法线框架（`minvar`/`minvar_matrix_make`）。使用 `output_file` 获取显式单个工件路径（`.csv` 用于完整区间旋转的 LMN 矢量，`.npz` 用于滑动窗口矩阵），或使用 `output_dir` 获取默认的 `minvar_rotated.csv` / `minvar_matrices.npz` 文件名；`output_dir` 仍支持现有调用者。完整区间模式返回特征值、特征矢量、法线矢量和中间/最小比率；滑动窗口模式（设置 `twindow`）写入每个窗口的旋转矩阵。 第二阶段 — 时频/波浪分析（问题 #15）。每个读取单个标量通道，并将批量 `time × frequency` 谱图（及其轴）写入 `output_dir` 下的压缩 `.npz`，只返回路径、范围和形状。 将谱图与下游渲染器配对以查看它。 - `dynamic_power_spectrum(input_file, output_dir, data_col=None, nboxpoints=256, nshiftpoints=128, bin=3, nohanning=False, time_col="time")` — 滑动汉宁窗口 Welch 动态功率谱（`pyspedas` `dpwrspc`）。返回 `{spectrogram_file, data_col, shape, time_range, freq_range, ...}`。 - `wavelet_transform(input_file, output_dir, data_col=None, wavename="morl", min_period=None, max_period=None, compute_significance=False, siglvl=0.95, time_col="time")` — 通过 PyWavelets 在 Torrence & Compo 尺度上的连续小波变换（Morlet/Paul/DOG），可选地限制在某个周期带内。`compute_significance=True` 添加每个尺度的 95% 红噪声显著性（`pyspedas` `wave_signif`）；这是一个可选功能，因为显著性和宽尺度范围计算量大。返回 `{spectrogram_file, data_col, wavename, shape, time_range, freq_range, period_range, significance_computed, ...}`。 第二阶段 — 磁场模型和辐射带坐标（问题 #16，#17）。 两者都读取一个 **位置工件** — 优选具有 `(N, 3)` 形状的 `positions` 数组的 `.npz` **（GSM 坐标（公里））**，以及一个可选的 Unix 秒时间数组（裸 `.npy` Nx3 数组，或具有时间列和三个数字位置列的 CSV/JSON 也被接受）。每个样本的 B 矢量、足点和 L 系列被写入 `output_file` 作为压缩的 `.npz`；只返回汇总统计和路径。IGRF 快速且无参数；扭曲的 Tsyganenko 模型需要显式的地磁参数，否则返回 `parameters_required` 错误（无隐藏的网络下载）。 - `evaluate_magnetic_field(positions_file, output_file, model="igrf", parameters=None, trace="none", time_col="time", position_cols=None)` — 在每个地心 GSM 位置评估 `igrf`/`t89`/`t96`/`t01`/`ts04` B（nT）（`pyspedas` geopack `tigrf`/`tt89`/`tt96`/`tt01`/`tts04`），可选地跟踪每个场线（`trace` 在 `none`/`ionosphere`/`equator` 中，通过 `ttrace2endpoint`）。位置半径被限制在近地场模型域 `1..30 Re` 内；超出域的输入返回 `code="position_domain_error"`，并提示将日心/ SPICE 或行星中心矢量转换为地球中心 GSM 公里后再调用。`parameters` 携带模型索引（例如 `t89` 需要 `iopt` 或 `kp`；`t96`/`t01`/`ts04` 需要 `pdyn`/`dst`/`byimf`/`bzimf`（`/g1,g2`/`w1..w6`）或预先计算的 `parmod`）。返回 `{result_file, model, field_strength_nT: {min,max,mean,components}, footpoints_file?, lshell_summary?, ...}`。 - `calculate_lshell(positions_file, output_file, model="igrf", geomag_parameters=None, footprint=False, time_col="time", position_cols=None, parameters=None)` — 通过将每个地心 GSM 位置跟踪到磁赤道来计算 McIlwain L-shell（赤道场线顶点半径，Re）（`pyspedas` geopack `ttrace2endpoint`）。位置半径被限制在 `1..30 Re` 内用于近地科学；超出域的输入返回 `code="position_domain_error"` 而不是无意义的大 L 值。`footprint=True` 还写入北离子层足点。扭曲模型重复使用与 `evaluate_magnetic_field` 相同的地磁索引合约；`parameters=` 被接受为 `geomag_parameters=` 的别名（因此索引参数在两个工具中具有相同的名称 — `geomag_parameters` 为保持向后兼容性而保留，并且同时传递两个具有不同值的参数会产生 `invalid_argument` 错误）。返回 `{lshell_file, model, summary: {min_L, max_L, mean_L}, footprint_file?, ...}`。 第二阶段 — 粒子分布、矩和谱（问题 #18，#19，#95）。桥接工具 `load_particle_distribution_artifact` 运行 pyspedas 任务加载器/获取器（默认映射包括 MMS FPI/HPCA 和 ERG 粒子产品，可用加载器覆盖），选择请求的或最佳分布 tplot 变量，调用相同的 pyspedas 任务转换器，并写入标准 `.npz` 分布工件。对于已加载的 tplot 变量，`build_particle_distribution_artifact` 从转换器步骤开始，不会自行下载。两个桥接器都写入所需的 `magf` 字段：直接提供 `magf`，传递 `mag_tplot_name` 获取已加载的 B 字段 tplot 变量，或让 `load_particle_distribution_artifact` 尝试默认 B 字段加载器映射（MMS FGM / ERG MGF）并将 B 矢量插值到分布切片时间。所选 B 字段时间覆盖必须括住分布切片时间；桥接器返回输入错误而不是静默外推端点 B 值。只有 `load_particle_distribution_artifact` 执行加载器/获取步骤，因此任何存档下载/缓存行为都来自请求的 pyspedas 加载器，并报告在返回的出处中。两个下游工具读取此 **显式分布工件** — 一个 `.npz`（优选）或 JSON 对象，持有每个时间切片的能量/立体角立方体：`data`（T，E，A 通量），`energy`/`denergy`/`theta`/`dtheta`/`phi`/`dphi`/`bins`（与 `data` 形状相同，或单个 `(E,A)` 切片广播跨时间），标量 `charge` 和 `mass`，以及可选 `times`（Unix 秒）。这是 `pyspedas` 粒子算法消耗的相同 `data_in` 字典；任务 CDF 分布可以桥接到它，要么通过 `load_particle_distribution_artifact`（加载器/获取 + 转换器），要么通过 `build_particle_distribution_artifact` 从已加载的 tplot 变量。批量矩时间序列和谱图矩阵被写入 `output_dir`；只返回标量汇总、路径、范围和形状（完整压力/温度张量、热流立方体和谱图矩阵永远不会内联返回）。 迁移注意：`compute_particle_moments` 现在需要分布工件包括 `magf`，这是 `moments_3d` 消费的磁场方向。现有的无 `magf` 工件将返回 `invalid_argument`；将 `magf` 添加为 `(T,3)` 矢量（每个时间切片一个）或广播 `(3,)` 矢量，或通过 `mag_tplot_name`/默认加载器桥接从加载的 B 字段 tplot 变量重建工件。 - `load_particle_distribution_artifact(output_file, converter="mms_fpi", trange=None, tplot_name=None, loader_module=None, loader_function=None, loader_kwargs=None, mag_tplot_name=None, mag_loader_module=None, mag_loader_function=None, mag_loader_kwargs=None, ..., magf=None, max_slices=32)` — 端到端桥接，调用 pyspedas 任务加载器/获取器填充实际的 CDF 支持的 tplot 变量，选择 `tplot_name`（或从加载器结果中尝试最佳分布变量），从 `magf`、`mag_tplot_name` 或默认 MMS FGM / ERG MGF 加载器映射中获取磁场上下文，然后写入文档化的 `.npz` 分布工件。默认粒子加载器映射涵盖 MMS FPI/HPCA 和 ERG 粒子产品；`loader_module`/`loader_function`/`loader_kwargs` 和匹配的 `mag_loader_*` 参数允许任务产品覆盖而无需添加每个任务的 MCP 工具。返回值包括加载器后端/参数、加载/选择的分布和磁 tplot 名称、转换器出处、形状/范围和工件路径。 - `build_particle_distribution_artifact(tplot_name, output_file, converter="mms_fpi", index=None, probe=None, data_rate=None, species=None, level=None, units=None, trange=None, single_time=None, magf=None, mag_tplot_name=None, max_slices=32)` — 从预加载的实际任务 tplot/CDF 分布变量桥接到文档化的 `.npz` 模式下的 pyspedas 任务粒子转换器。`mag_tplot_name` 允许桥接读取已加载的 B 字段 tplot 变量并将其插值到输出切片时间，拒绝时间覆盖不括住每个输出切片的 B 变量。支持的转换器键在无效输入时报告；当前键包括 MMS FPI/HPCA 和 ERG LEP/MEP/HEP/XEP 产品。输出针对 `DIST_SCHEMA_DOC` 进行验证，侧车 JSON 记录转换器/磁场出处、形状、时间/能量/数据范围和如果 `max_slices` 限制工件则截断。 - `compute_particle_moments(dist_file, output_dir, sc_potential_v=0.0, energy_range_ev=None, output_format="json", no_unit_conversion=False)` — 等离子体矩（密度、速度、温度、压力张量、热流相关量）每个时间切片（`pyspedas` `moments_3d`）。需要上述分布工件字段，包括 `magf` 作为 `(T,3)` 或广播 `(3,)`。可选地限制到 `energy_range_ev=[min,max]` eV（通过屏蔽非活动 bin）并应用航天器电位。写入 `output_dir/particle_moments.{json,csv}` 完整的矩时间序列。返回 `{moments_file, n_time, time_range, density_summary, velocity_summary, temperature_summary, pressure_tensor_summary, columns, ...}`，其中 `{min,max,mean}` 标量汇总仅为 `{min,max,mean}`。单位遵循 `moments_3d`（密度 cm⁻³，速度 km/s，温度 eV，压力 eV/cm³）。 - `compute_particle_spectra(dist_file, output_dir, spectrum_types=["energy","pitch_angle"], mag_file=None, resolution=None)` — 能量 / 方位角（`phi`）/ 仰角（`theta`）/ **俯仰角** 谷谱图。能量/phi/theta 使用 `pyspedas` `spd_pgs_make_e_spec` / `spd_pgs_make_phi_spec` / `spd_pgs_make_theta_spec`，对切片中的分布进行平均。`azimuth`→`phi` 和 `elevation`→`theta` 别名被接受。场向 `pitch_angle` 谱图需要一个 `mag_file`（B 字段参考）：每个切片被旋转到场向坐标与 `spd_pgs_do_fac`（B 作为 +z），然后在共轭纬度模式下使用 `spd_pgs_make_theta_spec` 在 0-180° 中以 colatitude 模式进行极角分箱 - **不需要可选的 `spd_pgs_make_pad_spec` 后端**，因此只要有谱函数的 pyspedas 构建都提供俯仰角，通过 `mag_file` 是 `.npz`/`.json`，键 `b` 作为 `(T,3)`（每个切片一个 B 矢量，按索引匹配）或 `(3,)`（广播跨切片），在分布的坐标系中；仅使用 B 的方向。`resolution` 设置俯仰角箱数（默认 18）。当 `mag_file` 消失时，`pitch_angle` 条目报告 `needs_input`，而其他请求的谱仍然计算。每个谱图被写入 `output_dir/particle_spectra_<type>.npz`。返回 `{spectra: {energy: {spectrogram_file, axis_label, axis_units, shape, axis_range, value_range, ...}, pitch_angle: {..., n_pitch_angle_bins}, ...}, requested, succeeded, n_time, time_range, ...}`。 第二阶段 — 工件渲染/可视化（问题 #20，绘图 epic #10）。这完成了研究循环的探索/可视化步骤：上述所有数据、谱、场模型和粒子工具都将批量数组写入磁盘，只返回紧凑的摘要，而 `render_tplot` 将这些工件变成图片。它使用 `matplotlib`（无头 `Agg` 后端，无 GUI/显示）并且永远不会获取远程数据。 - `render_tplot(input_files, output_file, panel_types=None, trange=None, xsize=12, ysize=None, dpi=200, ylog=None, zlog=None, x_component=None, y_component=None)` — 从本地工件渲染一个多面板 tplot 样式 **PNG**，每个 `input_file` 一个堆叠面板（从上到下）。谱图 `.npz` 矩阵（`power`/`spectrogram` 键具有 `time` + `freq`/`axis` 轴，如 `dynamic_power_spectrum`/`wavelet_transform`/`compute_particle_spectra` 编写）渲染为 `pcolormesh` 面板并带有颜色条；CSV/JSON 表格和 1-D/2-D `.npz`/`.npy` 值数组渲染为线面板。显式 `panel_types="scatter"`/`"xy"`/`"hodogram"` 渲染一个 2-D 数值矩阵每个输入工件作为参数 x-y 面板；`x_component` 和 `y_component` 是基于零的列选择器（标量广播到所有输入，或列表匹配 `input_files`；默认为 0 vs 1）。`panel_types` 覆盖每个文件自动检测 - 每个 `auto`（默认）、`line`/`timeseries`、`spectrogram` 或 `scatter`/`xy`；传递 `None`（全部自动）、单个令牌（广播）或匹配 `input_files` 的列表。`trange` 是可选的 2 元素窗口（ISO-8601 字符串或 Unix 秒），当存在时间轴时过滤样本（否则使用样本索引）。`ylog`/`zlog`（每个面板的布尔值或标量广播）设置对数 y 轴 / 对数颜色标度，并被拒绝与 `invalid_argument` 无效时拒绝；散点图仅为线性。 `xsize`/`ysize` 是英寸，`dpi` 是有界以避免奇怪的画布。PNG 被写入 `output_file`（创建父目录）；返回 `{status, output_file, n_panels, trange: {requested, actual}, size_px, dpi, panels: [{index, type, file, shape, value_range, time_range, axis_range?/n_series?/components?, x_range?, y_range?, ylog?/zlog?], warnings?}` 仅 - **图像字节永远不会内线且不会返回批量数组**。需要 `spedas-agent-kit[analysis]`（matplotlib）。散点图按时间着色未在第一个实现中内线；时间顺序通过细连接路径和点显示。 ### 5. 外部数据源工具（可选 `hapi` / `fdsn` 后端） 两种额外的数据源可以访问三个捆绑的 SPEDAS 后端家族以外的存档。像分析工具一样，它们的后端是**可选的**，并且被延迟导入：没有安装额外的工具，每个工具都会返回一个结构化的 `status="error"`，`code="missing_dependency"`，并指定要安装的额外工具。批量数据被写入 `output_dir`；工具只返回文件路径和紧凑的元数据（优先考虑工件）。 这四个工具由于 HAPI 是基于 `server_url` 地址的，而 FDSN 是基于 `trange/network/station` 地址的 —— 与统一的基于 `dataset_id` 的动词不兼容，因此**被降级出默认的 `list_tools` 界面**（问题 #87）。可以通过 `browse_data_sources(source_type="hapi"/"fdsn")`（其 `next_tools` 提示指向此处）发现并路由到它们，或者设置 `SPEDAS_AGENT_KIT_DATASOURCE_TOOLS=1` 以直接在 `list_tools` 中宣传这四个工具。它们带有表面元数据 `meta["surface"] == "datasource"`。 HAPI（问题 #21，可选 `spedas-agent-kit[hapi]`，安装 `hapiclient`）： - `browse_hapi_catalog(server_url, query=None)` — 列出任何 HAPI 兼容服务器宣传的数据集（例如 `https://cdaweb.gsfc.nasa.gov/hapi`，`https://pds-ppi.igpp.ucla.edu/hapi`，`https://iswa.gsfc.nasa.gov/IswaSystemWebApp/hapi`，`https://lasp.colorado.edu/lisird/hapi`）。返回 `{status, server, dataset_count, datasets: [{id, title}...]}`；传递 `query` 以过滤 id/标题。 - `fetch_hapi_data(server_url, dataset_id, parameters, start, stop, output_dir, format="csv")` — 在 `[start, stop)`（停止根据 HAPI 规范独家）上获取数据集切片，并写入一个扁平的 CSV/JSON 表（时间列加上每个标量参数的一列和 `name[i]` 列用于矢量/光谱参数）。返回 `{status, file_path, format, server, dataset_id, time_range, rows, parameters_meta}`，每个参数的 `units`/`description`/`type`/`size`/`spectral` 仅限。 FDSN/MTH5（问题 #22，可选 `spedas-agent-kit[fdsn]`，安装 `pyspedas` + `mth5` + `obspy`）： - `browse_fdsn_datasets(trange, network=None, station=None, usa_only=False)` — 列出 EarthScope FDSN 磁通量测量站，它们在 `trange=['YYYY-MM-DD','YYYY-MM-DD']` 内暴露三个相同频带的磁通道（例如 `LFE/LFN/LFZ`）。返回 `{status, trange, station_count, stations: [{network, station, time_range, channels}...]}`。 - `fetch_fdsn_data(trange, network, station, output_dir, format="csv")` — 下载一个 MTH5 文件，校准计数 → nT，强制执行 3 分量 Hx/Hy/Hz 几何结构，并写入时间序列（时间列加上每个通道的一列）。返回 `{status, file_path, format, network, station, trange, rows, channels, units?}`。当窗口中不存在符合条件的 3 分量数据时，返回 `code="resource_not_found"`。 ### 6. 兼容性底层工具 这些工具仍然可用于已经知道特定于源的浏览/获取操作的客户端： - CDAWeb：`browse_observatories`，`load_observatory`，`browse_parameters`，`fetch_data` - PDS：`browse_pds_missions`，`load_pds_mission`，`browse_pds_parameters`，`fetch_pds_data` - SPICE：上述几何工具 前专用缓存工具（`manage_cdaweb_cache`，`manage_pds_cache`，`manage_spice_kernels`）不再作为 MCP 工具宣传，因为它们的操作和 kwargs 被 `manage_data_cache` 覆盖。有关兼容性映射和弃用指南，请参见 `docs/public_api_strategy.md`。 ## 推荐的代理工作流程 1. 调用 `spedas_overview()`。 2. 对于自然语言科学请求，调用 `search_spedas_data_sources(...)` 或 `plan_spedas_observation(...)`。 3. 使用数据层： - `browse_data_sources(source_type="all")` - `browse_data_sources(source_type="cdaweb" | "pds" | "spice")` - `load_data_source(...)` - `browse_data_parameters(...)` - `fetch_data_product(...)` 用于 CDAWeb/PDS 测量/存档产品 4. 直接使用几何工具进行 SPICE 星历、距离、框架和坐标转换工作。 5. 对于任何实际分析，调用 `create_spedas_analysis_bundle(...)` 并在生成的 `data/` 目录下写入获取的文件。 6. 返回紧凑的摘要和文件路径。不要将大型科学数组粘贴到聊天中。 ## 本地开发快速入门 ```bash git clone https://github.com/spedas/spedas_agent_kit.git cd spedas_agent_kit uv sync --extra dev --extra mcp uv run --extra mcp python -m spedas_agent_kit ``` 运行测试和烟雾检查： ```bash uv run --extra dev --extra mcp python -m pytest -q uv run --extra mcp python scripts/smoke_mcp_list_tools.py --json uv run --extra dev --extra mcp python scripts/validate_plugin_packages.py ``` 列表工具烟雾检查启动带有隔离临时缓存目录的标准输入输出 MCP 服务器，执行 MCP `initialize` + `list_tools`，并验证预期的宣传工具名称。它不会获取 CDAWeb/PDS 数据或下载 SPICE 内核。 可选后端通过额外功能安装，不需要基本的安装。`analysis` 额外功能还控制了十个本地分析工具的 MCP 注册，因此基本的 `list_tools` 响应保持聚焦于数据/工作流和几何表面： ```bash uv sync --extra analysis # pyspedas + matplotlib + PyWavelets（坐标/光谱/场/粒子分析，渲染） uv sync --extra hapi # hapiclient（browse_hapi_catalog / fetch_hapi_data，问题 #21） uv sync --extra fdsn # pyspedas + mth5 + obspy（browse_fdsn_datasets / fetch_fdsn_data，问题 #22） ``` ## MCP 客户端配置 stdio 配置示例： ```json { "mcpServers": { "spedas": { "command": "uv", "args": ["run", "--extra", "mcp", "python", "-m", "spedas_agent_kit"], "cwd": "/path/to/spedas_agent_kit" } } } ``` 对于插件式分发，规范的独立包装器现位于单独的 SPEDAS 组织仓库中： - <https://github.com/spedas/spedas_claude> — Claude Code 插件包装器。 - <https://github.com/spedas/spedas_codex> — Codex 插件包装器。 存储库中的 `plugins/spedas-claude/` 和 `.agents/plugins/spedas-codex/` 目录仍然是轻量级开发示例和兼容性夹具；运行时特定的打包应在独立存储库中演变，而此存储库拥有 MCP 服务器本身。 它们的共享兼容性合同记录在 `plugins/spedas-agent-kit-compatibility.json` 中，并由 `scripts/validate_plugin_packages.py` 验证：当前基准 `list_tools` 计数为 13，用于这些开发夹具所使用的 Agent Kit `main` 参考；可选分析工具、旧兼容性工具和直接 HAPI/FDSN 数据源工具（问题 #87，由 `SPEDAS_AGENT_KIT_DATASOURCE_TOOLS=1` 控制）有意不在此基准计数之外。 ## 维护者面临的定位 `spedas_agent_kit` 应该在 SPEDAS 数据/工作流层上很厚，但在后端实现层上很薄： - 用户看到一个 SPEDAS 代理工具包和一个 `data` 层。 - 数据源类别是科学概念：CDAWeb、PDS、SPICE/几何。 - 后端包保持可维护的内部实现表面。 - 高级工具应该编码可重用的 SPEDAS 科学方法：源选择、规划、来源和工件学科。 有关当前框架，请参见 `docs/maintainer_note.md` 和 `docs/examples/agent_workflow.md`。 - `docs/examples/juno_pds_spice_workflow.md` — Juno MAG/PDS 发现加上 SPICE 几何规划，包括当前警告。