e2m2e.api package

任务级一档接口（ADR 0014）：把 CR3BP 初猜、星历修正、长期预报、转移设计、 时空转换等能力封装为 Facade 方法，供上层规划系统（CLI / MCP 工具）调用。

接口层：Facade 门面、配置、Pydantic 模型、MCP、CLI。

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

  • facade.py：Facade 门面，唯一公开顶级入口，粗粒度任务方法。

  • config.py：配置（只管运行环境：内核路径/精度阈值/日志）。

  • models.py：公开数据模型（Pydantic，全手写）。

  • mcp/：MCP 服务（create_server(facade) 进程内 + CLI mcp-serve 薄包装）。

  • cli/：命令行（子命令 = Facade 方法）。

实现状态：一档任务（design/control）与二档子任务（family/stability/proximity） 已接入 algorithm/；transfer_design/orbit_propagation/spacetime_transform 及 MCP/CLI 依赖 [mcp] extra，保持占位。

e2m2e.api.config module

运行配置：内核路径、精度阈值、日志级别。

只管**运行环境** （ADR 0014）；物理常量归 data/templates/。构造注入 Facade （Facade(config=Config(...))），内部默认从环境变量读。SPICEManager 全局句柄、 r2s2 进程单例作为已知限制用 Config 显式管理。

实现状态：骨架。字段待定稿。

class e2m2e.api.config.Config(kernel_dir=<factory>, log_level='WARNING', rtol=1e-12, atol=1e-12, catalog_dir=<factory>, catalog_enabled=True, catalog_baseline_import=<factory>)[源代码]

基类：object

e2m2e 运行配置。

变量:

  • kernel_dir (str) -- SPICE 内核目录（默认 $SPICE_KERNEL_DIR 或仓库 kernels/）。

  • log_level (str) -- 日志级别。

  • tolerance -- 默认数值容差（积分 rtol/atol）。

  • catalog_dir (str) -- 轨道库目录（默认 $E2M2E_CATALOG_DIR 或 ./catalog；ADR 0031）。

  • catalog_enabled (bool) -- 产物型方法成功后是否自动入库；测试场景可关闭以避免 文件副作用。

  • catalog_baseline_import (bool) -- 首次打开库时是否从包内导入基线数据集 （ADR 0036）；默认 $E2M2E_CATALOG_BASELINE_IMPORT 或开。

参数:
kernel_dir: str
log_level: str = 'WARNING'
rtol: float = 1e-12
atol: float = 1e-12
catalog_dir: str
catalog_enabled: bool = True
catalog_baseline_import: bool

e2m2e.api.facade module

Facade 门面：唯一公开顶级入口，粗粒度任务方法。

两层粒度（ADR 0014）：Facade 暴露粗粒度任务方法（人类/Agent 常用），算法层 保留细粒度 API（专家用）。MCP 工具 = Facade 方法全集（纯派生），方法带 mcp_exposed 元数据控制是否对 MCP 暴露。

实现状态：一档任务已接入 algorithm/ 编排器（design_orbit/control_orbit/ transfer_design/orbit_propagation/spacetime_transform），二档子任务已接入 已有算法（family/stability/proximity）。

class e2m2e.api.facade.Facade(config=None)[源代码]

基类：object

e2m2e 唯一公开入口。

Facade(config=Config(...)) 构造注入配置（ADR 0014）。方法对应任务级 能力，一档任务（稳定骨架，会增）：orbit_design / orbit_control / transfer_design / orbit_propagation / spacetime_transform。二档子任务 （会增）标 mcp_exposed=True，三档辅助标 False。

参数:

config (Config | None)

__init__(config=None)[源代码]

构造 Facade。

参数:

config (Config | None) -- 运行配置（api/config.py Config），缺省从环境变量读。

返回类型:

None

design_orbit(**params)[源代码]

任务轨道设计（一档）。

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

返回类型:

DesignOrbitResponse

control_orbit(**params)[源代码]

轨道保持（一档）。

薄封装 algorithm/station_keeping/control_orbit。

返回类型:

ControlOrbitResponse

transfer_design(**params)[源代码]

转移轨道设计（一档）。

薄封装 algorithm/transfer/transfer_orbit：Pydantic 校验 → 编排 → 结果翻译为 Response。

返回类型:

TransferDesignResponse

orbit_propagation(**params)[源代码]

轨道预报（一档）。

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

返回类型:

PropagationResponse

spacetime_transform(**params)[源代码]

时空坐标转换（一档）。

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

返回类型:

SpacetimeTransformResponse

orbit_family_generation(**params)[源代码]

轨道族生成（二档）。

Pydantic 模型校验（#411）→ 按 orbit_type 分派到算法层族生成入 口（#428、#502）→ 结构化错误。八族均已实现，成功返回统一容器 FamilyGenerationResponse``（兼容 ``OrbitFamily 读取接口）； Lissajous 是拟周期参数采样，族上显式标注 periodicity=quasi-periodic。软失败使用同一响应保留部分族。

返回类型:

FamilyGenerationResponse

orbit_stability(**params)[源代码]

稳定性分析（二档）：薄封装 algorithm/stability。

返回类型:

Any

转移网格搜索（二档）。

实现状态：占位。

返回类型:

Any

low_thrust_design(**params)[源代码]

小推力转移设计（二档）。

实现状态：占位。

返回类型:

Any

manifold_analysis(**params)[源代码]

不变流形分析（二档）。

实现状态：占位。

返回类型:

Any

low_energy_transfer(**params)[源代码]

低能转移（二档）。

实现状态：占位。

返回类型:

Any

relative_motion(**params)[源代码]

相对运动（二档）。

实现状态：占位。待接入 algorithm/proximity 的 RelativeDynamics。 chief/deputy 参数需映射为 TargetOrbit + dynamics 对象后接入。

返回类型:

Any

catalog_query(**params)[源代码]

多维过滤查询，返回摘要列表（不含数组段与请求快照）。

返回类型:

CatalogQueryResponse

catalog_get(**params)[源代码]

按 record_id 取完整记录（含数组段）；不存在抛 RECORD_NOT_FOUND。

返回类型:

CatalogRecordResponse

catalog_delete(**params)[源代码]

按 record_id 删除记录（文件与索引条目）；删除不可撤销。

返回类型:

CatalogDeleteResponse

catalog_tag(**params)[源代码]

写教学标注入 JSON 记录（随文件走）；tags 整体替换，note=None 保留。

返回类型:

CatalogTagResponse

catalog_promote(**params)[源代码]

把族成员提升为独立记录（source_record_id 指向所属族）。

返回类型:

CatalogPromoteResponse

catalog_export(**params)[源代码]

把查询子集打包导出（标注随包）；包可直接作为库打开。

返回类型:

CatalogExportResponse

catalog_sweep(**params)[源代码]

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

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

返回类型:

CatalogSweepResponse

class e2m2e.api.facade.ToolInfo(name, mcp_exposed, status, request_model=None)[源代码]

基类：object

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

参数:

  • name (str)

  • mcp_exposed (bool)

  • status (Literal['implemented', 'placeholder'])

  • request_model (type[Any] | None)

name: str
mcp_exposed: bool
status: Literal['implemented', 'placeholder']
request_model: type[Any] | None = None
e2m2e.api.facade.mcp_tools(facade)[源代码]

返回对 MCP 暴露的 Facade 方法名（纯派生，ADR 0014）。

参数:

facade (Facade)

返回类型:

list[str]

e2m2e.api.facade.tool_inventory(facade)[源代码]

返回对 MCP 暴露的 Facade 工具及其实现元数据。

参数:

facade (Facade)

返回类型:

list[ToolInfo]

e2m2e.api.models module

公开数据模型（Pydantic，全手写）。

输入/输出/错误模型精雕参数单位、默认值、取值域（ADR 0014）。Pydantic 只在 api/ 边界，算法层用 numpy/dataclass。每个 Facade 方法一个 Request/Response， 外加统一错误模型 OrbitError。

exception e2m2e.api.models.OrbitError(code='ERROR', message='', details=None, status=ConvergenceState.FAILED, cause=FailureCause.UNKNOWN)[源代码]

基类：Exception

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

变量:

  • code -- 错误码（如 "NOT_IMPLEMENTED"/"NOT_CONVERGED"/"INVALID_PARAMS"）。

  • message -- 可读错误信息。

  • details -- 附加细节。

参数:
返回类型:

None

class e2m2e.api.models.NumericRange(minimum=None, maximum=None, minimum_inclusive=True, maximum_inclusive=True, excluded_values=())[源代码]

基类：object

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

参数:
minimum: float | None = None
maximum: float | None = None
minimum_inclusive: bool = True
maximum_inclusive: bool = True
excluded_values: tuple[float, ...] = ()
contains(value)[源代码]

判断值是否落在此区间内且不属于排除值。

参数:

value (float)

返回类型:

bool

format_interval()[源代码]

返回用于校验错误的紧凑区间表示。

返回类型:

str

class e2m2e.api.models.ResultResponse(*, status, cause, message)[源代码]

基类：_ApiModel

Facade 成功处理后的任务最终状态三元组。

参数:
status: ConvergenceState
cause: FailureCause
message: str
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.DesignOrbitRequest(*, orbit_type, amplitude=None, phase=None, collinear_point=None, north_south=None, amplitude_in=None, amplitude_out=None, phase_in=None, phase_out=None, perilune_height=None, inclination=None, arg_of_pericenter=None, semi_major_axis=None, epoch=(2024, 1, 1, 0, 0, 0.0), duration=None, output_step=3600.0, perturbation=None, dyb=None, earth_degree=10, moon_degree=10, correction_method='two_level', correction_revolutions=1)[源代码]

基类：_ApiModel

任务轨道设计输入。

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

参数:

  • orbit_type (str)

  • amplitude (float | 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)

orbit_type: str
amplitude: float | 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, *, collinear_point=None)[源代码]

返回指定轨道类型和上下文下适用的条件数值范围。

参数:

  • orbit_type (str)

  • collinear_point (int | None)

返回类型:

dict[str, NumericRange]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.DesignOrbitResponse(*, status, cause, message, orbit_type, epoch_utc, duration_day, initial_state, cr3bp_jacobi, correction_iterations, correction_method=None, force_config, mu=None, states=<factory>, times=<factory>, ephemeris=None, drift_e=None, drift_aop_deg=None, drift_rp_km=None, secular_aop_rate_deg_per_year=None, record_id=None)[源代码]

基类：ResultResponse

任务轨道设计输出。

几何字段（mu / states / times / ephemeris，#312）让下游 （画图 / 落盘 / 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]]
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
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.ControlOrbitRequest(*, input_ephemeris=None, input_record_id=None, control_mode=1, is_nrho=0, special_mode=1, control_interval=30.0, feedback_arc=28.0, special_crossings=3, num_controls=120, num_monte_carlo=5, output_step=86400.0, position_accuracy=1500.0, velocity_accuracy=0.002, thrust_angle_err=0.333, thrust_mean=10.0, thrust_rel_err=0.003, thrust_abs_err=0.033, thrust_min=0.1, thrust_max=100.0, thrust_total=1000.0, srp_error_level=0.1, perturbation=None, dyb=None, earth_degree=2, moon_degree=2, real_perturbation=None, real_dyb=None, real_earth_degree=10, real_moon_degree=10, engine_layout=None, momentum_interval=5.0, srp_offset_m=None, spacecraft_mass=1000.0, srp_torque=None, tight_tolerance_km=0.1, tight_max_iter=6, special_damping_factor=1.0, mu=None)[源代码]

基类：_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
mu: float | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.ControlOrbitResponse(*, status, cause, message, num_failed, sk_statistic, maneuvers, controlled_ephemeris=None, mu=None, record_id=None)[源代码]

基类：ResultResponse

轨道保持输出。

几何字段（controlled_ephemeris / mu，#312）：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
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.TransferDesignRequest(*, transfer_type, tli_epoch, parking_alt_km=200.0, incl_deg=28.5, flight_path_deg=0.0, target_ephemeris=None, target_orbit_radius_km=None, tof_range=None, lga_search_params=None, wsb_search_params=None, engine_config=None, initial_mass=None, n_segments=10, target_oe=None, solver_method='shooting', duration_days=30.0, departure_state=None, target_state=None)[源代码]

基类：_ApiModel

转移轨道设计输入（对齐 algorithm/transfer 的 transfer_orbit 参数）。

参数:
transfer_type: str
tli_epoch: Any
parking_alt_km: float
incl_deg: float
flight_path_deg: float
target_ephemeris: Any
target_orbit_radius_km: float | None
tof_range: list[float] | None
lga_search_params: Any
wsb_search_params: Any
engine_config: dict[str, Any] | None
initial_mass: float | None
n_segments: int
target_oe: list[float] | None
solver_method: str
duration_days: float
departure_state: list[float] | None
target_state: list[float] | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.TransferDesignResponse(*, status, cause, message, transfer_type, delta_v, trajectory, details)[源代码]

基类：ResultResponse

转移轨道设计输出。

参数:
transfer_type: str
delta_v: float
trajectory: list[list[float]] | None
details: dict[str, Any]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.PropagationRequest(*, initial_state, epoch, duration, force_config=None, output_step=3600.0)[源代码]

基类：_ApiModel

轨道预报输入（对齐 algorithm/propagation 的 propagate_orbit 参数）。

参数:
initial_state: list[float]
epoch: Any
duration: float
force_config: dict[str, Any] | None
output_step: float
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.PropagationResponse(*, status, cause, message, epoch_utc, duration_sec, output_step, n_points, time_sec, times_jd_tdb, position_km, velocity_km_s, final_state)[源代码]

基类：ResultResponse

轨道预报输出。

参数:
epoch_utc: str
duration_sec: float
output_step: float
n_points: int
time_sec: list[float]
times_jd_tdb: list[float]
position_km: list[list[float]]
velocity_km_s: list[list[float]]
final_state: list[float]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.SpacetimeTransformRequest(*, states, times, transform_type, et0_jd, ephemeris_path=None)[源代码]

基类：_ApiModel

时空坐标转换输入。

参数:
states: list[list[float]]
times: list[float]
transform_type: str
et0_jd: float
ephemeris_path: str | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.SpacetimeTransformResponse(*, status, cause, message, states, times, transform_type, details)[源代码]

基类：ResultResponse

时空坐标转换输出。

参数:
states: list[list[float]]
times: list[float]
transform_type: str
details: dict[str, Any]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.FamilyGenerationRequest(*, orbit_type, libration_point=None, max_amplitude_km=None, min_amplitude_km=None, north_south=None, perilune_height_max_km=None, amplitude_in_km=None, amplitude_out_km=None, phase_in=None, phase_out=None, continuation_direction=None, sampling_mode=None, match_tolerance_km=None, n_orbits=50)[源代码]

基类：_ApiModel

轨道族生成输入（二档 Facade.orbit_family_generation）。

公开参数用平动点统一术语（libration_point，1=L1 … 5=L5），由 Facade 映射到各族算法参数。按 orbit_type 分派校验取值域 （与 DesignOrbitRequest 同构）：共线族（Halo/NRHO/Axial）仅 L1/L2，Lissajous 支持 L1/L2/L3，三角族（SPO/LPO/Horseshoe）仅 L4/L5，DRO 是月心族不绑定平动点（请求不得携带 libration_point）。 八族均已实现（#428、#502）：周期族返回严格周期成员，Lissajous 返回拟周期有界轨迹的参数采样（族上显式标注 quasi-periodic）。

按族适用的字段：

  • HALO/AXIAL：max_amplitude_km （带符号，区分北/南或上/下族）

  • NRHO：north_south、perilune_height_max_km、continuation_direction

  • LISSAJOUS：amplitude_in_km、amplitude_out_km、phase_in、phase_out

  • SPO/LPO/HORSESHOE：振幅上下限、延拓方向与 match_tolerance_km

  • DRO：振幅上下限（距月心距离 min/max 均值，km）

sampling_mode 显式登记各族固定的首版采样规则；传入其他规则会 结构化拒绝，而不是静默改用默认算法。

参数:

  • orbit_type (str)

  • libration_point (int | None)

  • max_amplitude_km (float | None)

  • min_amplitude_km (float | None)

  • north_south (int | None)

  • perilune_height_max_km (float | None)

  • amplitude_in_km (float | None)

  • amplitude_out_km (float | None)

  • phase_in (float | None)

  • phase_out (float | None)

  • continuation_direction (str | None)

  • sampling_mode (str | None)

  • match_tolerance_km (float | None)

  • n_orbits (int)

orbit_type: str
libration_point: int | None
max_amplitude_km: float | None
min_amplitude_km: float | None
north_south: int | None
perilune_height_max_km: float | None
amplitude_in_km: float | None
amplitude_out_km: float | None
phase_in: float | None
phase_out: float | None
continuation_direction: str | None
sampling_mode: str | None
match_tolerance_km: float | None
n_orbits: int
classmethod valid_ranges(orbit_type, *, libration_point=None)[源代码]

返回指定族和上下文下适用的条件数值范围。

参数:

  • orbit_type (str)

  • libration_point (int | None)

返回类型:

dict[str, NumericRange]

classmethod valid_options(orbit_type)[源代码]

返回指定族的公开离散选项（延拓方向与采样规则）。

参数:

orbit_type (str)

返回类型:

dict[str, tuple[str, ...]]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.FamilyGenerationResponse(*, status, cause, message, orbits, family_type=None, system=None, metadata=<factory>, requested_members, generated_members, record_id=None)[源代码]

基类：_ApiModel, OrbitFamily

轨道族生成响应。

继承 OrbitFamily 保持既有成功返回的读取接口，同时由 Pydantic 在 Facade 接缝直接承载状态三元组。算法层软失败的部分成员使用同一响应。

参数:
model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: ConvergenceState
cause: FailureCause
message: str
orbits: list[Orbit]
family_type: str | None
system: Any
metadata: dict[str, Any]
requested_members: int
generated_members: int
record_id: str | None
validate_result_contract()[源代码]

校验状态组合和成员计数。

返回类型:

FamilyGenerationResponse

class e2m2e.api.models.CatalogQueryRequest(*, orbit_family=None, libration_point=None, jacobi_min=None, jacobi_max=None, amplitude_min_km=None, amplitude_max_km=None, has_cr3bp=None, has_ephemeris=None, status=None, tags=None)[源代码]

基类：_ApiModel

轨道库多维查询过滤；各维度可独立组合（逻辑与）。

参数:
orbit_family: str | None
libration_point: int | None
jacobi_min: float | None
jacobi_max: float | None
amplitude_min_km: float | None
amplitude_max_km: float | None
has_cr3bp: bool | None
has_ephemeris: bool | None
status: ConvergenceState | None
tags: list[str] | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogRecordSummary(*, record_id, created_at, source_tool, source_record_id, orbit_family, libration_point, jacobi, amplitude, has_cr3bp, has_ephemeris, status, cause, message, member_count, tags, note)[源代码]

基类：_ApiModel

记录摘要：浏览大量记录时轻量，不含数组段与请求快照。

参数:
record_id: str
created_at: str
source_tool: str
source_record_id: str | None
orbit_family: str | None
libration_point: int | None
jacobi: list[float] | None
amplitude: list[float] | None
has_cr3bp: bool
has_ephemeris: bool
status: ConvergenceState
cause: FailureCause
message: str
member_count: int
tags: list[str]
note: str
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogQueryResponse(*, status, cause, message, records)[源代码]

基类：ResultResponse

catalog_query 输出。

参数:
records: list[CatalogRecordSummary]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogGetRequest(*, record_id)[源代码]

基类：_ApiModel

按 record_id 取完整记录。

参数:

record_id (str)

record_id: str
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogRecordResponse(*, record_id, created_at, source_tool, source_record_id, orbit_family, libration_point, jacobi, amplitude, has_cr3bp, has_ephemeris, status, cause, message, member_count, tags, note, scalars, request, members, arrays)[源代码]

基类：CatalogRecordSummary

完整记录：元数据全文 + 数组段（numpy 值，键含 / 段前缀）。

参数:
model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scalars: dict[str, Any]
request: dict[str, Any]
members: list[dict[str, Any]]
arrays: dict[str, Any]
to_ephemeris_table()[源代码]

把星历段重建为 EphemerisTable 实例（供接续计算）；无星历段返回 None。

返回类型:

Any | None

to_orbit()[源代码]

把单轨道 CR3BP 段重建为 Orbit；族记录与纯星历记录返回 None。

返回类型:

Any | None

class e2m2e.api.models.CatalogDeleteRequest(*, record_id)[源代码]

基类：_ApiModel

按 record_id 删除记录。

参数:

record_id (str)

record_id: str
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogDeleteResponse(*, status, cause, message, record_id, deleted)[源代码]

基类：ResultResponse

catalog_delete 输出。

参数:
record_id: str
deleted: bool
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogTagRequest(*, record_id, tags=<factory>, note=None)[源代码]

基类：_ApiModel

写教学标注（随 JSON 记录走）；tags 整体替换，note=None 保留原注释。

参数:
record_id: str
tags: list[str]
note: str | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogTagResponse(*, status, cause, message, record)[源代码]

基类：ResultResponse

catalog_tag 输出：更新后的记录摘要。

参数:
record: CatalogRecordSummary
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogPromoteRequest(*, record_id, member_index)[源代码]

基类：_ApiModel

把族成员提升为独立记录（source_record_id 指向所属族）。

参数:

  • record_id (str)

  • member_index (int)

record_id: str
member_index: int
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogPromoteResponse(*, status, cause, message, record)[源代码]

基类：ResultResponse

catalog_promote 输出：提升出的独立记录。

参数:
record: CatalogRecordResponse
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogExportRequest(*, orbit_family=None, libration_point=None, jacobi_min=None, jacobi_max=None, amplitude_min_km=None, amplitude_max_km=None, has_cr3bp=None, has_ephemeris=None, status=None, tags=None, dest)[源代码]

基类：CatalogQueryRequest

子集打包导出：过滤条件同 catalog_query，外加目标路径。

参数:
dest: str
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogExportResponse(*, status, cause, message, dest, record_ids, exported_count)[源代码]

基类：ResultResponse

catalog_export 输出。

参数:
dest: str
record_ids: list[str]
exported_count: int
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogSweepRequest(*, orbit_types, libration_points=None, max_amplitudes_km=None, perilune_heights_max_km=None, jacobi_windows=None, amplitude_ins_km=None, amplitude_outs_km=None, n_orbits=20)[源代码]

基类：_ApiModel

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

扫描网格 = 族 × 平动点 × 主参数维度。主参数维度三选一（同传报错）：

  • 一维主参数：HALO/AXIAL/SPO/LPO/HORSESHOE 扫 max_amplitudes_km， NRHO 扫 perilune_heights_max_km；

  • 能量（Jacobi）窗口：jacobi_windows——同一（族、平动点）只走 一次延拓 trace（族延拓范围取各族默认），各窗口成员分别成记录， 记录 jacobi 包络落在窗口内；窗口零成员时该点无记录、结局可查；

  • LISSAJOUS 二维振幅网格：amplitude_ins_km × amplitude_outs_km 笛卡尔积逐点采样（相位取请求默认值）；能量窗口不适用于 LISSAJOUS （其族生成是参数采样而非延拓 trace）。

部分参数点失败时已产出的记录保留（ADR 0020 软失败语义）。

参数:
orbit_types: list[str]
libration_points: list[int] | None
max_amplitudes_km: list[float] | None
perilune_heights_max_km: list[float] | None
jacobi_windows: list[list[float]] | None
amplitude_ins_km: list[float] | None
amplitude_outs_km: list[float] | None
n_orbits: int
classmethod supported_grid_dimensions(orbit_type)[源代码]

返回该族可作为扫描主参数维度的请求字段（条件取值域公开）。

GUI/CLI/MCP 不得解析错误文本或维护本地副本（ADR 0014 决策 8）； Facade 的网格展开与校验共用本接口。LISSAJOUS 的两个振幅字段是 同一维度（须同给）；其余族的 jacobi_windows 与一维振幅字段 互斥，由请求级校验器拒绝同传。

参数:

orbit_type (str)

返回类型:

tuple[str, ...]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogSweepPointOutcome(*, orbit_type, libration_point, parameter_km=None, jacobi_window=None, amplitudes_km=None, status, cause, message, record_id, generated_members)[源代码]

基类：_ApiModel

扫描单参数点的结局：成功（含软失败）保留 record_id，硬失败保留原因。

参数:
orbit_type: str
libration_point: int
parameter_km: float | None
jacobi_window: list[float] | None
amplitudes_km: list[float] | None
status: ConvergenceState
cause: FailureCause
message: str
record_id: str | None
generated_members: int
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class e2m2e.api.models.CatalogSweepResponse(*, status, cause, message, points, record_ids, succeeded, failed)[源代码]

基类：ResultResponse

catalog_sweep 输出。

succeeded 为产出记录的参数点数（含软失败但有成员产出的点）； failed 为硬失败（无产出）参数点数；软失败且零成员的点两者都 不计，其结局见 points 逐点状态。

参数:
points: list[CatalogSweepPointOutcome]
record_ids: list[str]
succeeded: int
failed: int
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

e2m2e.api.cli package

命令行：人类入口。

CLI 子命令 = Facade 方法（mcp_exposed=True 的），参数从同一份 Pydantic 模型生成 （ADR 0014）。CLI 与 MCP 完全对称。

实现状态：骨架。待 Facade 实现后生成子命令。

e2m2e.api.cli.main module

e2m2e 命令入口。

实现状态：mcp-serve 子命令（MCP 部署薄包装，ADR 0014 §6，issue #510）、 serve-stdio 子命令（GUI sidecar 入口，ADR 0035，issue #518）。 完整 CLI 子命令（= Facade 方法，参数从同一份 Pydantic 模型生成）另立 issue。

e2m2e.api.cli.main.main(argv=None)[源代码]
参数:

argv (Sequence[str] | None)

返回类型:

int

e2m2e.api.cli.main.build_parser()[源代码]
返回类型:

ArgumentParser

e2m2e.api.mcp package

MCP 服务子包（ADR 0014）。

  • envelope：统一信封 {status, data, error, meta} 与异常翻译。

  • tools：由 Facade 纯派生的工具规格（placeholder 不注册）。

  • server：create_server(facade)``（依赖 ``[mcp] extra）。

server 惰性导出：sidecar（ADR 0035）复用 envelope/tools 但不依赖 [mcp] extra，本包在缺 mcp 库时仍可导入。

e2m2e.api.mcp.server module

MCP 服务：LLM 工具入口。

进程内库为主体 + CLI 薄包装 mcp-serve（ADR 0014）：create_server(facade) 函数（进程内、可测试）+ e2m2e mcp-serve 子命令。一个 Facade 实例 = 一个 server。MCP 工具 = facade 上 mcp_exposed=True 的方法（纯派生，见 tools.py）， 传输层包统一信封（见 envelope.py）。

依赖 [mcp] extra：本模块在缺 mcp 库时导入即失败，调用方（CLI）负责 给出安装提示。

e2m2e.api.mcp.server.create_server(facade)[源代码]

创建 MCP 服务器（绑定传入的 Facade）。

一个 Facade 实例 = 一个 server；工具清单在每次 tools/list 时由 Facade 纯派生，与 tool_inventory() 单一同源。注册走 add_request_handler （mcp 1.x/2.x 兼容：2.0 移除了装饰器 API）。

参数:

facade (Facade) -- Facade 实例。

返回:

mcp.server.Server 对象（配合 mcp.server.stdio.stdio_server 运行）。

返回类型:

Server

e2m2e.api.mcp.server.handle_list_tools(facade)[源代码]

列出工具（纯函数，便于测试）。

参数:

facade (Facade)

返回类型:

list[Tool]

e2m2e.api.mcp.server.handle_call_tool(facade, name, arguments)[源代码]

调用工具并包信封（纯函数，便于测试）。

参数:
返回类型:

CallToolResult

e2m2e.api.mcp.tools module

MCP 工具注册：由 Facade 方法自动派生。

纯派生 + 元数据标记（ADR 0014）：MCP 工具 = Facade 方法全集，凡 mcp_exposed=True 的方法都注册。清单单一来源是 tool_inventory()， 本模块只消费它，不维护第二份清单。

placeholder 状态的工具**不注册**（issue #510 决策）：Agent 不应调到空实现； 待其落地为 implemented 后由清单单一来源自动出现在 server 上。

class e2m2e.api.mcp.tools.ToolSpec(name, description, input_schema, method)[源代码]

基类：object

一个可注册的 MCP 工具规格。

参数:
name: str
description: str
input_schema: dict[str, Any]
method: Callable[[...], Any]
e2m2e.api.mcp.tools.tool_specs(facade)[源代码]

由 Facade 纯派生工具规格（placeholder 不注册）。

参数:

facade (Facade)

返回类型:

list[ToolSpec]