故障排查与术语¶
常见问题¶
新项目为什么不能计算？¶
新项目故意只有 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。
计算按钮是灰色¶
按顺序检查：
- 项目 Schema 是否适合该路线；
- 是否选中 execution target；
- 草稿是否 current 且非 stale；
- 前置结果是否属于同一 target/project/content/physics revision；
- validity/warning 是否满足该路线；
- 是否已有冲突中的一次性计算或未完成提交；
- v0.8/v0.9 runtime gate 是否精确通过；
- 是否用
--offline阻止了自动能力协商。
修改晶格后平衡或下游结果消失了¶
它们没有被删除，而是变成旧修订证据。非 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。
v0.8/v0.9 显示 source revision mismatch¶
使用被接受的精确 Engine 构建。v0.8 要求 5253d675…，v0.9 要求 3b14dbcc…；为它们建立不同 targets，并给 v0.9 填写专用 state directory/source/build 三项。
为什么有些界面文字仍是英文？¶
协议名、Schema、公式、单位、哈希、Engine evidence 和固定 qualification 值不会被本地化。它们保持原字节是可追溯性的一部分。若普通按钮/说明未翻译，可在 Output/截图中记录具体字符串供补充翻译。
环形图或 Mirror Cell 能否用于工程布置？¶
不能。环形图只是按路径长度的拓扑投影；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 私钥、密码、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，两者不可互换 |