单文件项目

PASS 的 GUI 和命令行均支持普通独立 JSON 输入和单文件 .passproj 项目。 GUI 顶部文件菜单区分 JSON、项目以及导出操作。

保存与打开

独立模式下，保存 JSON 和 JSON 另存为 写入普通 PASS 输入。项目模式下，保存项目 将所有输入 JSON、输入依赖、源文件和生成设置写入一个容器。 Ctrl+S 根据当前模式选择保存目标。打开 JSON 打开独立文档，不会隐式导入当前项目；后者使用 导入 JSON 到项目。替换文档或关闭窗口时，可以先保存未保存的修改。

文件操作显示进度，并暂时禁止编辑。取消操作可能需要等待正在进行的读取或写入完成；已经完成的保存按成功处理。JSON 另存到其他目录时同步更新相对输入路径，包括撤销与重做历史中的引用，使其仍指向同一源文件。

从当前输入创建项目 将当前配置打包。可以继续导入其他 JSON，通过输入选择框切换。项目复制所引用的粒子分布、偏移表、RF 分量程序、Bump 波形、 WakeField 模型文件和磁铁 ramping 文件，也保留导入前的原始 JSON、MAD-X TFS 和生成设置。缺失输入会报告其在 JSON 中的位置，阻止保存不完整项目。在 项目内容 中还可以添加其他源文件。

查看和复用参数

项目内容 列出输入 JSON、源文件和生成设置。选择 JSON 或其中的命令，查看参数表与原始文本；可以复制单个值或当前命令 JSON。 复制命令到当前输入 还会带入引用的空间电荷配置、切片器和文件依赖。 WakeField 同时复制其 Slicer，并在名称冲突时同步更新切片集引用。设计时钟由目标输入派生，不作为独立资源复制。导入 RFCavity 可能改变目标的理想纯 RF 设计轨迹及其他依赖该时钟的命令。显式 RF 频率表保留物理频率；谐波 RF 采用目标派生时钟。这不是跟踪束流或尾场历史状态的迁移。目标中已有名称保持不变；导入名称冲突时添加数字后缀。也可以只读打开另一份项目作为参数来源。

复制命令到当前输入只增加一个撤销步骤，不会清空此前历史。撤销/重做包含一同导入的命名配置、切片器及选择复制的时钟设置。准备过程使用独立候选项目，取消或失败不会改变当前项目；依赖文件会保留供重做使用，另存到新位置后仍可正确引用。

TFS 和 CSV 提供最多 500 行的数据预览。文本预览限制为 2 MiB，参数表限制为 5,000 项；可以随时导出完整原文件。二进制文件显示元信息并提供导出。向独立 JSON 复制的依赖在保存时放入旁边的 <json-name>_files 目录。

生成设置用于记录命令来源。载入生成设置 恢复表单，供预览和插入，不会自动覆盖已经手动编辑的命令。普通 JSON 保存生成后的命令，不保存这部分额外生成元数据。

运行

运行页选择 Beam 0，以及可选的另一份 Beam 1 输入。项目可保存多份候选配置，不代表引擎一次执行全部配置。相对输出目录以 JSON 或已保存项目所在目录为基准；未保存项目以当前工作目录为基准。

安装 PASS 后，也可通过命令行运行已保存项目，无需 Qt：

pass-run example.passproj
pass-run --passproj example.passproj
python -m PASS example.passproj

这些命令等价。.passproj 后缀触发项目读取，包括归档和校验和验证。命令行使用 GUI 保存的 run_settings.beam0 和可选的 run_settings.beam1。未保存 Beam 0 选择时，使用 active_config_id 对应配置；未选择 Beam 1 时仅运行单束流。已保存的选择不再存在，或两束选择了同一份配置时，会明确报错。项目中的其他配置不会自动执行，项目文件也不能与第二个输入参数组合使用。位置参数与命名输入选项不能混用。--passproj 不能与 --beam0 或 --beam1 组合使用；这两个选项用于选择独立 JSON 输入，具体用法见输入文件生成（命令行模式）。

未覆盖输出目录时，命令行项目运行使用 run_settings.output_directory，默认为 output。相对路径以已保存项目所在目录为基准，不受命令行当前工作目录或所选 JSON 内输出目录影响；绝对路径保持不变。结果与输入快照采用下述布局，均位于项目临时缓存之外。运行不会修改项目文件。

使用 --output DIR 为本次运行选择其他输出根目录：

pass-run example.passproj --output results
python -m PASS example.passproj --output "results/project run"

此选项优先于保存的输出设置，不会修改项目。相对覆盖路径以启动时的工作目录为基准；快照和结果均使用所选根目录，并保留下述布局。pass-run --help 或 pass-run -h 显示输入方式、选项、路径规则和示例，包括 --stop-file 的用法，退出码见输入文件生成（命令行模式）。

GUI 先固定所选配置，再在后台线程中依次校验输入、复制依赖和校验快照；依赖复制使用与 PASS.main.main 相同的快照服务，完成后才启动子进程。准备过程显示当前阶段并支持取消；准备和运行期间不能重复启动。准备失败或取消时，保留此前显示的运行记录。单次校验调用完成后才会响应取消请求。

每次 GUI 运行和命令行项目运行使用独立的结果目录，输入快照保存在其 input 子目录中，采用与独立 JSON 运行相同的日期布局：

<output>/<YYYY_MMDD>/<HHMM_SS>/       # 本次仿真结果
    input/
        beam0.json                  # 固定运行输入；可选 beam1.json
        configuration0.json         # 用于比较的原始配置
        assets/<filename>           # 已复制的依赖字节
        run.json                    # 运行记录
        gui.log                     # GUI 运行的完整进程日志

依赖直接复制到 assets/ 中，不创建编号子目录。保留原文件名；检查重名时不区分大小写，冲突时在扩展名前追加编号，例如 rf1.tfs、rf2.tfs。运行 JSON 使用指向这些已复制文件的相对路径，并以绝对路径指定输出根目录。准备阶段在复制输入前分配按日期组织的结果目录，并将路径保存到 run.json 的 results_directory。初始化使用该目录，不再追加一层日期和时间。必要时为时间目录添加后缀，以避免复用已有结果目录。运行 ID 仍保存在 run.json 中，不再单独作为一层目录。跟踪读取这些已复制的输入，不再创建第二份快照。之后编辑项目不会改变正在运行的任务，新运行也不共用前次结果目录。结果及其中的输入快照均位于项目临时缓存之外。

通过命令行/Python 入口运行独立 JSON 时使用相同快照格式和结果布局，见输入文件生成（命令行模式）。未启用资源的缺失依赖记录在 unavailable_dependencies，并保留原有校验警告；已启用功能所需输入缺失则阻止运行。

停止在圈边界协作结束运行：先完成当前圈，再执行命令收尾以保存已有输出，并跳过运行后的自动绘图。运行记录标为 stopped，退出码为 3。耗时初始化或单圈计算结束后，停止请求才会生效。 强制结束 直接终止子进程，记录为独立状态；未写出的缓冲区及未完成输出可能丢失。关闭 GUI 时会请求取消准备或正常停止，并在保持事件循环响应的情况下等待，等待期间仍可强制结束。KeyboardInterrupt 等中断记录为 interrupted，退出码为 130，不保证当前圈已完成。初始化、跟踪或输出异常记录为 failed，退出码为 1；中断期间若输出失败，同样记录为失败。正常完成的退出码为 0。受控运行入口要求异常向外传播，通过执行结果判定状态。已有历史保留原先存储的状态和退出码。

日志支持跟随、搜索和级别过滤。滚动离开末尾或搜索时会关闭跟随。界面最多显示 20,000 行，gui.log 及日志导出则保留未过滤的完整进程日志。运行页还可直接打开结果目录。

运行历史与复现

运行历史 列出最近登记的 100 条运行记录，可打开快照或结果目录、比较两次运行的原始配置，以及按选中快照重跑。重跑会核对运行 JSON、比较配置和依赖的 SHA-256 校验和，再创建新的快照及结果目录；使用记录中的输入字节，不使用当前编辑器内容。移动或修改快照文件可能使该记录无法重跑。

run.json 记录开始/结束时间、状态、退出码、结果路径、输入和依赖校验和，以及各 Injection 的输入名称、命令名称和种子。其中还包括 Python、依赖包和 PASS 版本、计算后端及粒子精度。 source 记录实际源码根目录和 Python 源码哈希；Git 可用时，还记录 HEAD 及 PASS 源码目录的修改状态。源码信息补充 PASS 版本字符串，后者可能来自已安装包的元数据。 configured_device_ids 表示请求的设备，observed_gpu 则仅在实际选择 GPU 后填写，包含设备名称、运行时及驱动版本；CPU 运行或 GPU 初始化前保持 null。

重跑通过 source_run 记录来源运行，从初始条件开始，不继续跟踪检查点。快照保留输入，但不会自动恢复当时的 Python 环境或源码版本。 Random Seed: null 仍采用非确定性采样；即使种子为整数，代码、依赖库、精度或硬件变化后也不保证结果完全一致。

已应用的参数修改支持撤销/重做；当前文本框和 JSON 编辑器保留各自的文本撤销/重做。保存前需要处理尚未应用的属性或 JSON 修改。 GUI 新建高斯束团使用 1e-6 m rad 的正横向发射度，运行前拒绝零范围的高斯采样。

导出

导出当前 JSON 仅输出配置副本，不包含引用文件，也不改变当前正在编辑的文档。 导出可运行输入包 将运行页所选输入及其依赖写入 ZIP，附带 run.py 和英文使用说明。完整解压后，在安装了 PASS 的环境执行 python run.py。启动脚本以解压目录为基准解析路径，运行输入包不需要安装 Qt。

恢复已有草稿

GUI 不会自动备份草稿，请通过 JSON 或项目保存操作主动保存修改。应用的 AppLocalDataLocation/recovery 目录中的已有副本仍然可用， GUI 启动或关闭时不会删除这些文件。

需要时从 文件 → 恢复未保存草稿 查找并选择已有副本。点击此操作后才在可取消的后台任务中读取列表；启动时不扫描草稿，也不保留后台备份写入线程。恢复后是未保存的文档或项目，不会覆盖原文件。依据副本中的内容，可恢复未应用的属性字段、原始 JSON（包括无效 JSON）、已应用配置、项目生成与运行设置以及临时依赖资产。切换项目中的活动输入不会将来源恢复记录标为已处理；来源记录保持待处理，直到恢复后的文档被保存或用户明确放弃修改。正常关闭会将已处理记录标为 resolved，但不删除恢复文件。

容器格式

格式版本 2 使用标准 ZIP/ZIP64，元数据采用 UTF-8 JSON：

manifest.json                  # 格式/PASS 版本、输入和文件清单
configs/<配置名称>.json         # 普通 PASS 输入 JSON
assets/<文件名>                # 原始输入/源文件字节
recipes/<index>.json            # 生成设置和源文件引用

在 PASS 外查看内容时，可用支持 ZIP 的压缩软件打开文件，或复制一份并将副本改名为 .zip 后解压。 manifest.json 和 configs/*.json 可用普通文本编辑器阅读。 GUI 中的 项目内容 可直接预览配置和源文件，无需手工解压。修改后应通过 GUI 保存项目，使依赖索引和校验和一同更新；手工修改归档成员可能导致项目校验失败。

文件直接放在 configs/ 和 assets/ 中，不再使用 UUID 子目录。配置使用其显示名称，依赖文件保留原始文件名；中文和空格保留，不安全的文件名字符会被替换。同一目录内出现重名时，在扩展名前依次添加 1、2、3 等，例如 rf.tfs、rf1.tfs、rf2.tfs。配置文件也遵循相同规则，例如 beam.json 和 beam1.json。

稳定 ID 仅用于清单内部引用，不决定文件名。配置采用相对路径引用资产；清单记录 SHA-256 校验和、依赖索引、当前活动配置和运行设置。移动项目只需复制一个文件，不需要携带临时编辑缓存；运行输入不依赖原电脑路径。源文件是快照，外部同名文件变化不会自动改变项目。

保存时先写入并校验新归档，再替换旧文件。版本 2 拒绝不支持的格式版本、不安全路径、重复条目、校验和或依赖索引不一致。限制为 100,000 个条目、256 GiB 解压后总大小以及每个 JSON 条目 64 MiB。大型项目保存需要写入完整新归档的时间和额外磁盘空间。大型仿真输出不自动归档；显式添加为输入或源文件的内容会被内嵌，包括作为下一次输入使用的结果文件。