# 界面总览

## 三栏布局与助手边栏

主窗口按左、中、右三栏排布，右侧附可折叠的助手边栏：

| 栏 | 内容 | 作用 |
|----|------|------|
| 左栏 | 项目/轨道库页签 + 语言切换 + 项目树或过滤栏 | 浏览产物、查库 |
| 中栏 | 工具选择 + 参数面板 + 执行按钮 | 发起计算 |
| 右栏 | 画布工具栏 + Three.js 画布 + 时间轴 | 呈现与走查结果 |
| 助手边栏 | 会话切换器 + 对话流 + 输入区 | 对话式发起计算（见下文 AI 助手） |

左栏右上角的下拉在中 / EN 之间切换界面语言，选择持久化（localStorage），
重启后保留。

## 左栏：项目与轨道库

**项目页签**列出当前会话生成的产物（族生成完成后自动出现）。

**轨道库页签**打开即查询全库（空过滤条件），结果显示在下方项目树；过滤栏复用
参数面板的自动表单机制，支持按族类型、平动点、Jacobi 区间、振幅区间与标签
组合筛选，改完点查询。

点击树中任一记录，画布把该轨迹钉入**固定层**，与结果层同屏对照；按住
Ctrl 多选可同屏叠加多条（固定层软上限 5 条，超出提示但不拦截）。记录可
写备注、加星标（ADR 0024），在记录详情面板编辑；右键菜单提供删除，
过滤栏提供教学案例包导出。

## 中栏：参数面板

面板由工具的 JSON Schema 自动生成：构建期 `tools/export_tool_schemas.py`
从 e2m2e 的 Pydantic 模型导出 schema 到 `frontend/src/toolSchemas/`，前端按
schema 渲染字段：数值框、下拉、勾选（对应模型的 Optional 语义：勾选即传值，
不勾不传）。按 `orbit_type` 只显示当前族适用的字段，跨族字段不出现在表单里。

点执行前做防呆校验：必填缺失、数值越界（含独占边界）会被拦下，
message 一次列出全部问题，对应字段在表单内联标红；修改参数即清
标红。执行按钮不会因校验失败被禁用——防呆靠反馈，不靠隐藏。

运行期间执行按钮变为进度态；按钮下方状态行滚动显示 sidecar 进度
消息。

## 画布区

详见 {doc}`visualization`。画布上方一条停靠工具栏，左侧两组单选：
**投影**（3D / XY / XZ / YZ）与**中心**（质心 / 地心 / 月心 / L1 /
L2）；右侧操作组：**适配**（按轨迹包围盒复位视角）、**导出动画**
（录制 8 秒自转 webm）、**图表设置**（详见下文设置弹窗）。画布下方
时间轴显示当前时刻（T + N 天），可拖动或播放，驱动画布上的时刻
标记沿轨迹走查，机动事件以 chip 标注、点击跳转（详见
{doc}`visualization`）。左下角状态行显示运行
进度与当前画布内容统计（族成员数 / 库轨迹数）。

## AI 助手

右侧助手边栏是内嵌的对话式 agent（ADR 0022/0023）：用户以自然语言描述
目标，助手组装工具参数、经确认后调用 e2m2e 工具，再用自然语言解读结果。
助手触发的产物与手动运行同语义——同一轨道库、谱系与画布叠加。

**配置（BYOK）**：设置弹窗的「AI 助手」分区填入 OpenAI 兼容协议的
base URL、模型名与 API key（云端 DeepSeek/通义/Kimi 或本地
Ollama/LM Studio，一套协议覆盖）；key 只存系统凭据管理器，不进界面
JS 上下文。未配置时边栏显示引导。

**分级确认**：只读查询（轨道库查询、记录详情）免确认直接执行；计算与
改库工具先在对话流中出**工具卡片**，显示工具名与参数摘要，用户可确认、
编辑参数后确认或拒绝。完成后卡片折叠为单行摘要（工具名、状态、产物
记录 id），点击展开参数与结果摘要，并可跳转「查看产物」入项目树上画布。

**会话与思考等级**：会话跨重启持久化，头部会话切换器按最近活动倒序列出
历史会话，支持新建、重命名、删除与打开旧会话续聊；输入区旁可切换思考
等级（关/标准/深度三档，按会话设置）。回复以 markdown 流式呈现，模型的
思考过程为消息内可折叠区块。

已知限制（上游 e2m2e 后续跟进）：AI 触发的长计算不显示真实进度（不定态
指示），且确认开始后不可取消。

## 设置弹窗

图表工具栏的设置按钮打开设置弹窗，包含三块内容：

- **图表设置**：轨道线宽、颜色循环、天体与平动点标注、背景色、网格量程
  等，即时生效并持久化（详见 {doc}`visualization` 的图表设置一节）；
- **星历内核状态**：显示 SPICE 内核就绪状态（随安装分发，自动配置）；
- **AI 助手**：模型服务配置（见上节）。