故障排查与术语¶
常见问题¶
新项目为什么不能计算？¶
新项目故意只有 START Marker，RF、beam、aperture、acceptance 和闭合晶格都缺失。先建立有正长度元件且满足结构/闭环门槛的晶格。.vmaproj 可以保存不完整草稿；JSON export、optics 和 tracking 只在当前严格 snapshot 就绪后启用。
Test SSH 成功，但 Engine 失败¶
SSH 成功只表示认证和远程命令可用。检查 Output 面板中的 executable path、protocol、source/build、permissions、CPU 和 limits。高版本页面还会拒绝只支持 v0.1 的 Engine。
Managed Connect 没有弹出认证窗口¶
确认 target 使用 Managed tunnel (interactive MFA)、Engine executable 是远端绝对路径，
并且系统 ssh 客户端在 PATH 中。打包后的 Studio 必须在应用可执行文件旁包含
vm-accelerator-studio-ssh-askpass。旧 per-RPC 模式刻意采用非交互认证，不能请求
Authenticator 动态码。
askpass 可执行文件本身是 headless 的。它通过每次 attempt 独有的私有本地通道，把 OpenSSH 提示交给 Studio 应用内的认证 broker/dialog，不应再弹出第二个独立窗口。还要注意： 启动或仅选中 target 都不会开始认证；请显式点击 Connect、Test Engine，或在计算 源窗口中确认 检测计算源（Check source）。
Managed 连接启动是有界的：Studio 给本地 ssh -G 检查 10 秒；随后总时限为目标的网络
Connect timeout 再加 2 分钟，用于交互认证和等待私有 gateway ready marker。超时后会
进入 Connection failed、关闭认证窗口并允许重试，不会永久占用连接状态；点击
Cancel 或 Disconnect 也会关闭本次连接的活动认证窗口。这些操作会立即让 attempt
失效并异步退役其进程；界面不会阻塞等待 OpenSSH 退出。
隧道已连接，但 gateway 或 Engine 测试失败¶
Connected 只证明 Studio 持有的 SSH 会话和私有转发可用，不代表 Engine ready。所选
Engine 环境必须包含 vm_accelerator.rpc_tcp_gateway；其 Python 解释器由配置的 Engine
绝对路径推导。请部署包含 gateway 的 Engine snapshot，再运行 Test Engine，不要把
gateway 端口暴露为公共服务。
隧道丢失后需要重新认证；已经接受的持久任务仍按 Engine 生命周期继续，建立新会话后可 再次连接。
计算按钮是灰色¶
按顺序检查：
- 项目 Schema 是否适合该路线；
- 是否至少配置了一个计算源；
- 草稿是否 current 且非 stale；
- 本地 project/content/physics 输入是否齐全；
- validity/warning 是否满足该路线；
- 是否已有冲突中的一次性计算或未完成提交。
target-specific 前置结果及 v0.8–v0.18 精确 runtime gate，会在点击 Run、选择计算源并确认 检测计算源（Check source） 后检查，不会在启动时自动协商。
为什么启动后没有自动恢复 pending submission？¶
这是预期行为。启动只发现本地 journal；恢复是绑定 journal 原 target 的显式操作，只有在 你确认恢复后才开始 SSH。取消恢复提示没有网络副作用。
修改晶格后平衡或下游结果消失了¶
它们没有被删除，而是变成旧修订证据。非 RF 晶格编辑还会撤回 supplied radiation slices。重新生成 lattice-derived slices/equilibrium，再运行下游。
结果 Refresh 后不见了¶
刷新会重新验证文件。被改动、缺 sidecar、hash 不一致或身份交叉的记录会以 UNVERIFIED 被 withheld。看 summary tooltip 和 Output；不要手工修补记录来绕过验证。
Reconnect 显示 credential missing¶
Job bookmark 仍在，但系统凭据库中的 token 不可用，可能因为换了用户、主机、Keychain/Secret Service 未解锁或设置被迁移。确认使用原操作系统账户和 target。Studio 不会把 token 从项目中恢复，因为它从未写入项目。
点了 Cancel，为什么仍显示 Running？¶
持久任务是合作式取消。先是 request accepted，然后 worker confirmed，最后进入 terminal cancelled；期间继续观察是正确行为。Detach 不等于 Cancel。
v0.6 Touschek 为什么不能提交？¶
该版本存在已确认公式错误，永久禁用新 Submit 和 replay。只能恢复以前的 job 并查看隔离原始证据。新任务使用 corrected v0.7。
专用路线显示 source revision mismatch¶
使用能力矩阵列出的精确 Engine 构建，并为不兼容 source 建立不同
targets。当前 v0.8 直连 gate 是 5253d675…，v0.9 是 3b14dbcc…，v0.11–v0.17 统一部署
是 ecd919a6…，v0.18 Slurm/CUDA 是 e9677a5a…。Studio 会校验来源/能力；不要假设更晚的
commit 自动兼容。
为什么有些界面文字仍是英文？¶
协议名、Schema、公式、单位、哈希、Engine evidence 和固定 qualification 值不会被本地化。它们保持原字节是可追溯性的一部分。若普通按钮/说明未翻译，可在 Output/截图中记录具体字符串供补充翻译。
Lattice Geometry 或 Mirror Cell 能否用于工程布置？¶
不能。Lattice Geometry 是根据硬边长度和弯转角积分出的参考轨迹，项目并不包含 survey 坐标；Mirror 只反转 occurrence order，不改变场符号、极性、RF 相位或对准约定。
RF bucket height 能否当作 LMA？¶
不能。它只可作为纵向搜索/比较边界。正式 LMA 来自 v0.5 local kickDelta 路线，且当前仍是 sparse-aperture screening。
诊断信息收集¶
报告问题时提供：
- Studio commit/version 和操作系统；
- 打开的项目类型与 project ID；
- content/physics revision（可从 Evidence 复制）；
- target 显示名和 Engine build/source，不要提供私钥或 token；
- 具体按钮和完整错误；
- Output 面板中相关阶段；
- job ID、artifact ID/hash；
- 是否使用
--offline； - 最小复现步骤。
不要在工单里粘贴 SSH 私钥、密码、MFA 响应、gateway session token、reconnect token 或未脱敏的敏感路径。
术语速查¶
| 术语 | 含义 |
|---|---|
| content SHA | 整个规范项目内容的身份 |
| physics revision | 影响物理模型部分的稳定身份 |
| artifact | Engine 产生并由 Studio 严格验证的结果对象 |
| evidence | 证明项目、Engine、产物、资格和检查关系的信息 |
| CURRENT / STALE | 结果是否属于当前打开的精确修订 |
| SCREENING | 设计筛选证据，声明上限低于机器预测/验证 |
| one-shot | 客户端中断后无持久重连保证 |
| durable | 远端 job 有稳定身份、状态和重连路径 |
| target route | Studio 本机保存的 SSH 路径标签，不是 Engine 签名身份 |
| Family | 一组可原子编辑共同参数的设计对象 |
| Cell | Studio 对连续 occurrence 的命名布局/复用结构 |
| RF bucket | RF 纵向稳定区域，不等于 local momentum acceptance |
| DA / LMA | transverse dynamic aperture / local momentum acceptance，两者不可互换 |