e2m2e.api#

接口层：任务级入口、领域接口类、配置、Pydantic 模型、MCP、CLI。

第 4 层，依赖方向：algorithm/ + data/（ADR 0012）。Pydantic 只在 api/ 边界，算法层用 numpy/dataclass。

facade.py：Facade 任务级入口与组合根（五个任务方法；经 .catalog / .spatiography 交出领域类，ADR 0043）。
catalog.py：Catalog 轨道库类（数据管理 + 族生成，ADR 0043 决策 2）。
spatiography.py：Spatiography 分区分析类（ADR 0043 决策 3）。
config.py：配置（只管运行环境：内核路径/精度阈值/日志）。
models.py：公开数据模型（Pydantic，全手写）。
mcp/：MCP 服务（create_server(facade) 进程内 + CLI mcp-serve 薄包装）。
cli/：命令行（子命令 = 工具清单 implemented 条目）。

MCP 工具 = 各暴露类 mcp_exposed 方法并集，单一清单（tool_inventory，ADR 0014 决策 2 经 ADR 0043 拓宽扫描根）。

仓库全貌与一条任务链的走读见 README 的仓库怎么读一节。

Submodules#

Exceptions#

OrbitError

结构化错误（api/ 边界翻译，ADR 0014）。

Classes#

`Catalog`	轨道库接口类（ADR 0043 决策 2）：数据管理 + 批量生成。
`Facade`	任务级入口与暴露类组合根（ADR 0043 决策 1）。
`ToolInfo`	Facade 工具的机器可读元数据。
`ControlOrbitRequest`	轨道保持输入（对齐 algorithm/station_keeping 的 control_orbit 参数）。
`ControlOrbitResponse`	轨道保持输出。
`DesignOrbitRequest`	任务轨道设计输入。
`DesignOrbitResponse`	任务轨道设计输出。
`NumericRange`	数值参数的上下界、开闭区间及离散排除值。
`RangeSpec`	NumericRange 的序列化形式（机器可读，ADR 0014 决策 8 请求侧）。
`ValidRangesResponse`	valid_ranges 输出：请求侧条件值域全量清单（ADR 0014 决策 8 请求侧）。
`Spatiography`	空间分区接口类（ADR 0043 决策 3）：无状态，纯分析入口。

Functions#

`mcp_tools`(→ list[str])	返回单个接口类实例上对 MCP 暴露的方法名（纯派生，ADR 0014）。
`tool_inventory`(→ list[ToolInfo])	返回对 MCP 暴露的工具及其元数据（多类扫描，ADR 0043 决策 5）。

Package Contents#

class e2m2e.api.Catalog(config: e2m2e.api.config.Config | None = None)#

轨道库接口类（ADR 0043 决策 2）：数据管理 + 批量生成。

Catalog(config=Config(...)) 构造注入配置；进程内调用方通常经 Facade().catalog 取同一实例。auto_ingest 与 load_record_ephemeris 是同包任务方法（Facade 的 design/control/ transfer 自动入库与 input_record_id 输入解析）的接缝，非 MCP 工具。

_config#

_catalog_store: e2m2e.data.catalog.CatalogStore | None = None#

property config: e2m2e.api.config.Config#: 运行配置（只读视图）。

_open_catalog() → e2m2e.data.catalog.CatalogStore#

懒打开库目录（首次使用时才产生目录副作用）。

未显式指定目录（Config(catalog_dir=...) 或 $E2M2E_CATALOG_DIR）时报 CATALOG_NOT_CONFIGURED，不建目录、不猜路径（ADR 0047）。

auto_ingest(builder: collections.abc.Callable[[], tuple[dict, dict[str, Any]] | None]) → str | None#

单条产物自动入库（ADR 0031 决策 8；Facade 任务方法经此接缝入库）。

无产物（站保星历缺失）返回 None；入库失败抛 CATALOG_WRITE_FAILED，不静默降级、不冒名为计算失败（ADR 0020）。

auto_ingest_family(builder: collections.abc.Callable[[], tuple[str, list[tuple[dict, dict[str, Any]]]] | None]) → str | None#

族产物逐成员自动入库（ADR 0045：一轨一记录），返回 family_id。

无产物（零成员）返回 None。逐条写入、无跨记录事务（决策 7）：中途失败时已写成员保留（诚实的部分结果）并抛 CATALOG_WRITE_FAILED；运行级溯源随每条成员走，同一 builder 单点写入，不会漂移（决策 2）。

load_record_ephemeris(record_id: str) → tuple[dict, e2m2e.data.types.trajectory.EphemerisTable]#: 取库中记录的元数据与星历段（control_orbit 的 input_record_id 输入源）。

_get_record(record_id: str) → Any#: 取完整记录；不存在抛 RECORD_NOT_FOUND，记录损坏抛 CATALOG_READ_FAILED。

_ingest_sweep_outcome(outcome: Any, family_request: Any) → str | None#: 扫描单点结果逐成员入库，返回 family_id；硬失败点（result=None）无记录。

orbit_family_generation(progress_callback: e2m2e.api.facade.ProgressCallback | None = None, **params) → e2m2e.api.models.FamilyGenerationResponse#

轨道族生成（二档）。

Pydantic 模型校验 → 按 orbit_type 分派到算法层族生成入口 → 结构化错误。九族均已实现，成功返回统一容器 FamilyGenerationResponse``（兼容 ``OrbitFamily 读取接口）； Lissajous 是拟周期参数采样，族上显式标注 periodicity=quasi-periodic。软失败使用同一响应保留部分族。 progress_callback(fraction, message) 上报阶段级进度（族生成是单次 Rust 调用，仅起止两端；逐成员进度待 Rust 侧通道）。

catalog_query(**params) → e2m2e.api.models.CatalogQueryResponse#: 多维过滤查询，返回摘要列表（不含数组段与请求快照）。

catalog_get(**params) → e2m2e.api.models.CatalogRecordResponse#: 按 record_id 取完整记录（含数组段）；不存在抛 RECORD_NOT_FOUND。

catalog_delete(**params) → e2m2e.api.models.CatalogDeleteResponse#: 按 record_id 删除记录（文件与索引条目）；删除不可撤销。

catalog_tag(**params) → e2m2e.api.models.CatalogTagResponse#: 写教学标注入 JSON 记录（随文件走）；tags 整体替换，note=None 保留。

catalog_export(**params) → e2m2e.api.models.CatalogExportResponse#: 把查询子集打包导出（标注随包）；包可直接作为库打开。

catalog_terminology() → e2m2e.api.models.CatalogTerminologyResponse#: 术语清单（ADR 0044）：分类学标签图例 + orbit_family 闭值集 + transfer_type 闭值集，无参数。包版本即术语版本：调用方每会话取一次、升级后刷新，未知标签按可读规范串原样渲染。

catalog_sweep(**params) → e2m2e.api.models.CatalogSweepResponse#

参数空间扫描批量生成并入库（编排复用 ADR 0029 的 Rust 族生成）。

网格 = 族 × 平动点 × 主参数维度（一维振幅/近月点高度、能量窗口、 LISSAJOUS 二维振幅，三选一）；部分参数点失败时已产出的记录保留，失败原因逐点可查（ADR 0020 软失败语义）。

class e2m2e.api.Facade(config: e2m2e.api.config.Config | None = None)#

任务级入口与暴露类组合根（ADR 0043 决策 1）。

Facade(config=Config(...)) 构造注入配置（ADR 0014），只承载五个任务级方法；轨道库与分区分析分别经 self.catalog / self.spatiography 暴露（决策 2/3），工具清单经 exposed_apis 跨类扫描（决策 5）。

_config#

catalog#

spatiography#

property config: e2m2e.api.config.Config#

运行配置（只读视图）。

长任务工具经 worker 子进程执行时，配置经 Config.to_payload() 随请求下发（#601），子进程用它重建 Facade——构造注入对全部工具生效，不再从环境变量静默重建。

property exposed_apis: tuple[Any, ...]#: 暴露类实例全集（ADR 0043 决策 5；tool_inventory 的扫描根）。

design_orbit(**params) → e2m2e.api.models.DesignOrbitResponse#

Mission orbit design (tier 1). / 任务轨道设计（一档）。

薄封装 algorithm/design/design_orbit：Pydantic 校验 → 编排 → 结果翻译为 Response。算法层异常翻译为 OrbitError。

control_orbit(**params) → e2m2e.api.models.ControlOrbitResponse#

Station-keeping Monte Carlo simulation (tier 1). / 轨道保持（一档）。

薄封装 algorithm/station_keeping/control_orbit。

transfer_design(progress_callback: ProgressCallback | None = None, **params) → e2m2e.api.models.TransferDesignResponse#

Transfer design (tier 1). / 转移轨道设计（一档）。

薄封装 algorithm/transfer/transfer_orbit：Pydantic 校验 → 编排 → 结果翻译为 Response。progress_callback(fraction, message) 上报长任务进度（#576 Phase 1：WSB 后端映射网格任务，其余后端仅起止）。

orbit_propagation(**params) → e2m2e.api.models.PropagationResponse#

Orbit prediction (tier 1). / 轨道预报（一档）。

薄封装 algorithm/propagation/propagate_orbit：Pydantic 校验 → 传播 → EphemerisTable 翻译为 Response。

spacetime_transform(**params) → e2m2e.api.models.SpacetimeTransformResponse#

Spacetime coordinate conversion (tier 1). / 时空坐标转换（一档）。

薄封装 algorithm/coordinate/spacetime_convert：Pydantic 校验 → 逐条转换 → 结果翻译为 Response。

valid_ranges() → e2m2e.api.models.ValidRangesResponse#: 请求侧条件值域清单（ADR 0014 决策 8）：design_orbit 与族生成的合法参数区间及族生成离散选项，无参数。包版本即值域版本：调用方每会话取一次、升级后刷新；区间与校验器同源（直接消费请求模型的 valid_ranges/valid_options，不另存副本）。键为 orbit_type 或族_Ln （LISSAJOUS 按平动点拆分，DRO 不带后缀）；区间携带字段单位（unit，如 km；缺省为无量纲或计数值）。

class e2m2e.api.ToolInfo#

Facade 工具的机器可读元数据。

name: str#

mcp_exposed: bool#

status: Literal['implemented', 'placeholder']#

request_model: type[Any] | None = None#

e2m2e.api.mcp_tools(facade: Any) → list[str]#: 返回单个接口类实例上对 MCP 暴露的方法名（纯派生，ADR 0014）。

e2m2e.api.tool_inventory(facade: Any) → list[ToolInfo]#

返回对 MCP 暴露的工具及其元数据（多类扫描，ADR 0043 决策 5）。

扫描根是暴露类实例全集：组合根（Facade）经 exposed_apis 给出三类；无该属性的单一对象（测试桩、单独构造的领域类）按自身扫描。清单仍单一来源，MCP/CLI/sidecar 消费不变。

class e2m2e.api.ControlOrbitRequest#

Bases: _ApiModel

轨道保持输入（对齐 algorithm/station_keeping 的 control_orbit 参数）。

字段与算法层业务参数一一对应；运行时参数（spice/kernel_dir/n_workers/ seed）由 Facade 注入，不进模型。默认值、单位与算法层签名一致。

输入源二选一（ADR 0031）：input_ephemeris 直接给星历，或 input_record_id 引用库中记录（取其星历段，站保产物记录自动以 source_record_id 指向该记录，谱系跨进程不断）。

input_ephemeris: Any#

input_record_id: str | None#

control_mode: int#

is_nrho: int#

special_mode: int#

control_interval: float#

feedback_arc: float#

special_crossings: int#

num_controls: int#

num_monte_carlo: int#

output_step: float#

position_accuracy: float#

velocity_accuracy: float#

thrust_angle_err: float#

thrust_mean: float#

thrust_rel_err: float#

thrust_abs_err: float#

thrust_min: float#

thrust_max: float#

thrust_total: float#

srp_error_level: float#

perturbation: dict[str, int] | None#

dyb: list[float] | None#

earth_degree: int#

moon_degree: int#

real_perturbation: dict[str, int] | None#

real_dyb: list[float] | None#

real_earth_degree: int#

real_moon_degree: int#

engine_layout: Any#

momentum_interval: float#

srp_offset_m: list[float] | None#

spacecraft_mass: float#

srp_torque: list[float] | None#

tight_tolerance_km: float#

tight_max_iter: int#

special_damping_factor: float#

classmethod _validate_perturbation(value: dict[str, int] | None) → dict[str, int] | None#: 在 API 边界校验摄动开关的键和值。

mu: float | None#

_validate_input_source() → ControlOrbitRequest#: 输入源二选一：裸星历或库记录引用。

class e2m2e.api.ControlOrbitResponse#

Bases: ResultResponse

轨道保持输出。

几何字段（controlled_ephemeris / mu）：controlled_ephemeris 为最后一次蒙特卡洛样本的受控真实轨道星历（EphemerisTable 全字段；全失败时 None）；mu 由请求透传（算法层不产 mu）。

num_failed: int#

sk_statistic: dict[str, Any]#

maneuvers: dict[str, Any]#

controlled_ephemeris: dict[str, Any] | None#

mu: float | None#

record_id: str | None#

class e2m2e.api.DesignOrbitRequest#

Bases: _ApiModel

任务轨道设计输入。

统一覆盖 CR3BP 周期轨道（DRO/NRHO/Halo/Lissajous/…）和 ELFO 冻结轨道。按 orbit_type 分派校验与默认值填充（model_validator）。 duration 统一用秒。

orbit_type: str#

amplitude: float | None#

resonance_p: int | None#

resonance_q: int | None#

phase: float | None#

collinear_point: int | None#

north_south: int | None#

amplitude_in: float | None#

amplitude_out: float | None#

phase_in: float | None#

phase_out: float | None#

perilune_height: float | None#

inclination: float | None#

arg_of_pericenter: float | None#

semi_major_axis: float | None#

epoch: Any#

duration: float | None#

output_step: float#

perturbation: dict[str, int] | None#

dyb: list[float] | None#

earth_degree: int#

moon_degree: int#

correction_method: str#

correction_revolutions: int#

classmethod valid_ranges(orbit_type: str, *, collinear_point: int | None = None) → dict[str, NumericRange]#: 返回指定轨道类型和上下文下适用的条件数值范围。

classmethod valid_range_contexts() → tuple[tuple[str, int | None], ...]#

全量导出条件值域用的 (orbit_type, collinear_point) 键集。

无平动点条件的族 point 为 None；HALO 与 LISSAJOUS 逐点展开（HALO 为 L1/L2 两档独立域，LISSAJOUS 1/2 同表、3 独立）。

classmethod field_units() → collections.abc.Mapping[str, str]#: design_orbit 条件字段的单位表；未列出者为无量纲或计数值。

_validate_conditional_ranges(selection: str) → None#: 用公开范围接口校验已填充默认值的条件参数。

_validate_orbit_type() → DesignOrbitRequest#

_dispatch_correction_method(selection: str) → None#

按族规范化星历修正方法：不稳定族强制 segmented。

未显式指定时静默分派默认值；显式传入与族冲突的值时告警后改写（不拒绝，兼容既有调用方）。请求对象经此即为事实，算法层只做防御检查。

class e2m2e.api.DesignOrbitResponse#

Bases: ResultResponse

任务轨道设计输出。

几何字段（mu / states / times / ephemeris）让下游（画图 / 落盘 / design→control 链式）可仅依赖 Facade，不必穿透 algorithm 层。states / times 为 CR3BP 参考周期轨道（无量纲会合系）， ephemeris 为标称星历（GCRS km / 速度 m/s + 会合系，EphemerisTable 全字段）。ELFO 场景下 CR3BP/修正字段为 None/默认值，漂移字段填充。

orbit_type: str#

epoch_utc: str#

duration_day: float#

initial_state: list[float]#

cr3bp_jacobi: float#

correction_iterations: int#

correction_method: str | None#

force_config: dict[str, Any]#

mu: float | None#

states: list[list[float]]#

taxonomy_labels: list[str]#

times: list[float]#

ephemeris: dict[str, Any] | None#

drift_e: float | None#

drift_aop_deg: float | None#

drift_rp_km: float | None#

secular_aop_rate_deg_per_year: float | None#

record_id: str | None#

class e2m2e.api.NumericRange#

数值参数的上下界、开闭区间及离散排除值。

minimum: float | None = None#

maximum: float | None = None#

minimum_inclusive: bool = True#

maximum_inclusive: bool = True#

excluded_values: tuple[float, ...] = ()#

contains(value: float) → bool#: 判断值是否落在此区间内且不属于排除值。

format_interval() → str#: 返回用于校验错误的紧凑区间表示。

exception e2m2e.api.OrbitError(code: str = 'ERROR', message: str = '', details: dict[str, Any] | None = None, status: e2m2e.data.templates.ConvergenceState = ConvergenceState.FAILED, cause: e2m2e.data.templates.FailureCause = FailureCause.UNKNOWN)#

Bases: Exception

结构化错误（api/ 边界翻译，ADR 0014）。

Attributes:: code: 错误码（如 "NOT_IMPLEMENTED"/"NOT_CONVERGED"/"INVALID_PARAMS"）。 message: 可读错误信息。 details: 附加细节。

code = 'ERROR'#

message = ''#

details#

status#

cause#

__str__() → str#: Return str(self).

class e2m2e.api.RangeSpec#

Bases: _ApiModel

NumericRange 的序列化形式（机器可读，ADR 0014 决策 8 请求侧）。

unit 携带字段单位（如 km）；缺省为 None 表示无量纲量或计数值。单位属于字段而非区间，同一字段在各类型下的 unit 一致。

minimum: float | None#

maximum: float | None#

minimum_inclusive: bool#

maximum_inclusive: bool#

excluded_values: list[float]#

unit: str | None#

classmethod from_numeric_range(numeric_range: NumericRange, unit: str | None = None) → RangeSpec#: 由校验侧 NumericRange 构造；只搬运数值，不复制判定逻辑。

class e2m2e.api.ValidRangesResponse#

Bases: ResultResponse

valid_ranges 输出：请求侧条件值域全量清单（ADR 0014 决策 8 请求侧）。

无参数；包版本即值域版本（清单随发布冻结，调用方每会话取一次、升级后刷新）。design_orbit 键为 orbit_type（LISSAJOUS 逐平动点拆 LISSAJOUS_L1/L2/L3）；family_generation_ranges 键为族_Ln（DRO 不绑平动点，键不带后缀）；family_generation_options 为族生成的离散选项。

design_orbit: dict[str, dict[str, RangeSpec]]#

family_generation_ranges: dict[str, dict[str, RangeSpec]]#

family_generation_options: dict[str, dict[str, list[str]]]#

class e2m2e.api.Spatiography#

空间分区接口类（ADR 0043 决策 3）：无状态，纯分析入口。

spatiography_scales(**params) → e2m2e.api.models.SpatiographyScalesResponse#

分区解析尺度计算（spatiography，二档）。/ Spatiography analytic scales (tier 2).

计算地月空间分区（Rosengren et al. 2026 Primer §5）的全部闭式边界尺度：Laplace 半径（地心/月心）、影响球族（Hill / Laplace-Tisserand / Chebotarev / Battin）、tidal parity、共振梯（Table 1/2）、平动点精确解与 Jacobi 临界值。Primer 常数口径（SPICE GM + Simon 1994 月根数）。

spatiography_classify(**params) → e2m2e.api.models.SpatiographyClassifyResponse#

分区区域分类（spatiography，二档）。/ Spatiography region classification (tier 2).

对会合系状态逐点判定五省分区（terrestrial / cislunar 内带 / cislunar 外带 / circumlunar / translunar / heliocentric，论文 Table 1 或附录 B Table 4 口径），重叠带返回多标签；附 osculating a、Jacobi 值与 Hill 五拓扑 Case 诊断。

spatiography_boundaries(**params) → e2m2e.api.models.SpatiographyBoundariesResponse#

分区边界几何（spatiography，二档）。/ Spatiography boundary geometry (tier 2).

输出可视化用边界几何数据：会合系（质心原点，z=0）的 r_L / tidal parity / 双系 Hill 与 SOI 圆族、Battin 非对称闭合曲线、L1–L5，或 (a,e) 根数平面走廊曲线族。前端只做单位归一与绘制，不在界面重算。

spatiography_resonance_atlas(**params) → e2m2e.api.models.SpatiographyAtlasResponse#

共振图集（spatiography，二档）。/ Resonance atlas (tier 2).

Primer §4.2–§4.4 / §5.3 的共振与长期解析骨架：Gallardo 半解析共振半宽包络（式 100–104，计算设置对齐 Fig. 8：共面切片、 Simon 1994 月根数、2ρ_H 近遇截断）、拱线驻定 loci（式 75–78）、 vZLK 相图与时间尺度（式 64–71）。1:1 共振带宽系统性高估（论文 §5.3 声明），不得当 gateway 边界用。

spatiography_dynamical_map(**params) → e2m2e.api.models.SpatiographyMapResponse#

六域两层天图（spatiography，二档）。/ Spatiographic dynamical map (tier 2).

Primer §7.3 (a, e) 天图管线：Table 4 六制图域网格 × 命名场景（2027-08-02 日全食历元统一初值切片），逐格传播 EM/EMS 点质量模型，输出 MEGNO Ȳ 场与八类命运场 + 诊断量。大数组建议走 sidecar 二进制帧（E2M2 帧，ADR 0035）。