UI 指南

当前的 Pyruns UI 已经不再是“附带页面”，而是一套真正承担主流程的 React 工作台。
它的目标不是做得花，而是做得顺、做得稳、做得像你每天真的会打开的工具。

Web UI 必须显式启动；裸 pyr 或 pyruns 只显示 CLI 帮助：

pyr ui
pyr ui train.py
pyr ui train.py --config configs/default.yaml
pyr ui shell
pyr ui shell --no-browser

服务只监听本机回环地址。启动时会生成新的随机访问令牌；浏览器首次打开完整 URL 后， 服务器写入持久的 HttpOnly、SameSite=Strict 会话 cookie，并重定向到不含令牌的 干净地址。会话在使用时自动续期，并可跨同一主机、端口和工作区的正常更新或重启保留； 只有清除浏览器数据或本地 ~/.pyruns/sessions 状态后才需要重新打开最新 URL。 --no-browser 会在终端打印完整访问 URL，请勿共享。Pyruns UI 不是面向公网或多用户的服务。

新手引导

浏览器首次成功连接工作区时，会弹出欢迎框。点击“开始引导”可依次认识首页、 工作区选择、任务生成、任务管理、日志监控、运行环境，以及语言和明暗主题按钮。 点击高亮的导航入口可以进入真实页面，也可以使用“下一步”和“上一步”。

工作区与运行设置在引导中仅供预览，不会创建任务、执行命令或保存运行配置。 有未保存的草稿时，需要先保存草稿才能开始；关闭欢迎框不会丢弃草稿。 随时可以按 Esc 或点击“跳过”退出，引导打开的预览面板会一起关闭。

欢迎框在同一浏览器中只自动显示一次。之后可以从侧栏或偏好设置中的“新手指南” 重新打开。引导跟随当前界面语言和主题；禁止浏览器存储时仍可使用，但刷新后无法 记住完成状态。

页面整体气质

这一版 UI 的收口方向很明确：

• 更紧凑
• 更有层级
• 更少噪声
• 更像实验工作台，而不是资讯面板

侧边栏与工作区

左下区域会显示当前：

• workspace 路径
• 当前脚本名，或 _shell_
• shell runtime 来源

长文本支持悬停查看完整内容，这一点在深层路径和 shell workspace 下尤其重要。

切换脚本工作区

选择一个 .py 文件后，Pyruns 会定位它旁边的：

<project>/_pyruns_/<script_name>/

切换 Shell Workspace

从脚本工作区切换到 shell workspace 后，当前工作区会变成：

<project>/_pyruns_/_shell_/

脚本和配置发现可以通过 Cancel 或 Escape 取消，读取超过 10 秒会提示重试。 已经提交的工作区打开操作会等待结果。

Generator

Generator 是整个 UI 最像“工作台”的页面。

在脚本工作区

支持：

• Grid
• Tree
• YAML

Grid / Tree

适合：

• 调整多个参数
• 使用 batch 语法
• pin 常用字段

当前特点：

• Grid 适合快速扫描和编辑扁平参数，Tree 配合 Outline 按配置路径浏览
• 类型 chip 会按模板声明类型稳定显示
• pin 顶部参数不再强行重新排位，而是更强调状态变化
• batch 触发项会被单独标记
• 右侧固定生成区始终在视线里

YAML

适合：

• 直接编辑完整配置
• 一次只生成一个任务
• 想保留完整 YAML 语义的人

当前编辑器已经补上更强的高亮和更宽松的编辑空间。

在 Shell Workspace

固定为：

• Shell

特点：

• 编辑的是脚本正文
• 每次只生成一个任务
• 落盘文件为当前 runtime 对应的 config.ps1 / config.cmd / config.sh
• 默认跟随启动 Web UI 时的终端语义执行

创建成功会立即显示任务结果；随后刷新模板列表不会阻塞继续操作。

Runtime：运行环境与 GPU 调度

GPU 等待（GPU wait）是 UI 的任务调度规则，适合在共享 GPU 机器上按显存与空闲率排队运行任务。

侧栏 Runtime 面板按 Python、Env、GPU 三个标签组织运行设置。Python 和环境变量设置用于后续从 UI 提交的任务；GPU 设置是项目运行时的持久化调度规则。修改后必须点击 Save，标签上的未保存标记会提示尚未写入；Reset 恢复当前已保存值。

GPU scheduling / GPU wait

在 Runtime -> GPU 打开 GPU scheduling 后，UI 只会在 GPU 满足规则时启动之后提交的任务。它是 UI 的持续设置，作用于后续 UI 任务；CLI 的 pyr exec / pyr run 仍须在单次命令中显式传入 --gpu-wait。关闭 UI 开关或不传 CLI 参数都表示不等待 GPU。

UI 字段	含义
GPUs required	一次任务需要同时满足条件的 GPU 数量；多张卡必须一起达标
Minimum free memory (GiB)	每张候选卡最低空闲显存，单位固定为 GiB
Minimum GPU idle (%)	每张候选卡最低空闲率；空闲率等于 100 - GPU utilization
Stable for (sec)	显存和空闲率连续达标的秒数；0 表示立即启动
Maximum wait (hr)	启动前最长排队时间；0 表示不限时，不限制任务开始后的运行时间

GPU 预览会逐卡显示当前显存、利用率、Pass / Blocked 和原因。预览只反映当前指标；真正启动时还会检查任务的 CUDA_VISIBLE_DEVICES、工作区内 GPU reservation、稳定时间和可用性。指标缺失不会被当成空闲，也不会在超时后自动退回 CPU。

Advanced scheduling rules 可选择 Auto pick 或 Specific indices（例如 0,1），并可开启 Respect task CUDA_VISIBLE_DEVICES 和 Require the same model for multi-GPU tasks。UI 不再要求单独填写 tasks per GPU 或 GPU per task；一次任务所需卡数统一由 GPUs required 表达。

任务进入排队后，Monitor 会显示 Waiting for GPU capacity、已就绪/所需卡数、稳定时间、剩余等待时间以及每张 GPU 的显存、空闲率、预留和缺失指标等阻塞原因。完整的 CLI 五段规则、单位、指定卡写法和 ready / blocked 输出见 GPU 空闲等待规则。

Manager

Manager 是任务的调度台。
你不只是看见任务，而是要快速决定“接下来对它做什么”。

你可以做什么

• 搜索任务
• 按状态筛选
• 选择多个任务批量运行 / 删除
• pin 任务
• 查看详情
• 直接跳转 Monitor 日志

当前交互约定

• Pinned 区域独立展示，不只是排序提前
• 主按钮、危险按钮、次按钮已经尽量统一语义
• 卡片底部动作保持紧凑，减少鼠标移动距离
• 搜索框默认检索全部字段，可选择任务名、备注、Python 配置、Shell 脚本、任务 Env 或完整日志，并组合区分大小写、全词和正则匹配

搜索按原样保留空格与换行，默认不区分大小写。按 Enter 立即搜索，Shift+Enter 插入换行；多行文本必须在同一个字段或日志文件内连续出现。

Manager 和 Monitor 均支持 Ctrl/Cmd+Shift+F 聚焦并选中查询。在首行按 ↑ 回看历史，在末行按 ↓ 返回较新的查询，最后回到未提交的草稿；多行输入内部仍按普通光标键移动。最近 100 条查询在当前浏览器保存、去重并由两页共用，可在搜索设置中清空。自动搜索的历史延迟 2 秒记录，避免保存连续输入的每一步。

搜索框旁的筛选按钮提供搜索设置：默认边输入边搜索、等待 300 ms、最多 20,000 个匹配。结果分批出现，达到上限后会提示，可选择不限制数量重新搜索。设置在 Manager 和 Monitor 间共用并保存在当前浏览器。搜索结果不会定时重扫，日志或任务变化后使用刷新按钮更新；搜索中点击停止按钮或按 Escape 可以取消。

完整日志搜索使用随依赖安装的 ripgrep，按原始 UTF-8 文件内容匹配；颜色转义仅在结果预览中隐藏。扫描期间就会显示已找到的匹配，不必等当前日志文件读完；后续进度合并推送，减少界面刷新开销。点击结果仍会打开对应历史日志的匹配位置。日志追加、重写或替换后，下次搜索会重新检查文件。

任务详情面板

常见标签包括：

• Info
• Config
• Notes
• Env

其中：

• Info 显示任务模式、目录和完整 Run History
• 展开一条运行记录后，点击 Saved input 查看启动前保存的脚本或配置；点击 Compare runs，选择同一工作区中的任务名与运行编号，比较输入、汇总指标、耗时、状态、Git 来源与运行环境。默认选择本任务的上一次运行，可直接输入其他任务名与编号。
• 比较内容仅在点击时读取，不加载训练曲线。旧运行没有保存输入时会明确提示，其余已记录信息仍可比较；正在运行的记录显示本次读取时的值。
• python 任务显示 config.yaml
• shell 任务显示当前 runtime 对应的 config.ps1 / config.cmd / config.sh

Notes 和 Env 保存会检查编辑时的字段值与任务身份。若原任务被同名任务替换，草稿仍保留， 请关闭并重新打开详情后再编辑新任务；旧草稿不能直接覆盖新任务。

Monitor

Monitor 的目标不是“把日志显示出来”，而是把日志变成一个可工作的界面。

默认行为

• 直接从侧边栏或 tab 进入时默认不选中任何任务
• 只有从任务卡片或 Dashboard 显式跳转时，才会带着当前任务进入
• 当前选中的任务消失时会清空选中状态，不会自动跳到别的任务

日志查看

当前实现重点：

• xterm 实例只初始化一次
• 切任务时避免重复 reset
• 请求带竞态保护，避免旧响应覆盖新内容
• websocket chunk 会校验任务身份，避免串日志

monitor_scrollback=0 关闭终端历史滚动，当前屏幕仍显示初始尾部与新增输出。日志连接成功读取文件状态后才显示 Live；持续读盘失败会显示提示，并尝试重连与增量读取，正常无输出的任务仍保持连接。

日志面板显示当前选定的日志内容；完整原始日志始终保存在任务目录中，可直接从任务目录读取或归档。Copy current log 只复制当前已加载的内容。

浏览器标签页进入后台时，Monitor 暂停任务事件和实时日志连接；返回时更新任务状态，并从已接收的位置继续读取日志。Manager、Monitor 和 Dashboard 的定时刷新也会在后台暂停，返回时立即补刷。搜索结果仍需使用刷新按钮更新。

Monitor 收到任务变更事件后读取服务端已有快照，合并短时间内的连续事件。连接正常时，前端额外每 60 秒发起一次磁盘校验请求，断连时改为每 5 秒重试；手动刷新会立即同步磁盘。服务端的任务调度和磁盘发现仍按自身周期运行。

实时订阅期间，服务端约每秒检查目录和任务状态，约每 4 秒校验配置、脚本内容；任务元数据发生变化时会一起加载最新配置。网页请求与调度器共享扫描结果，慢扫描结束后才开始计算下次间隔。外部编辑配置后可使用手动刷新立即同步。

导出

Monitor 支持选择多个任务并导出任务指标 CSV；日志文件保存在各任务目录中。

Dashboard

Dashboard 是第一页，也是最适合做“工作区展示图”的页面。

现在它主要承担：

• 当前 workspace 的任务摘要和最近任务
• CPU / RAM / GPU 状态
• 多 GPU 卡片布局
• GPU 显存占用与进程明细入口

四页统一设计语言

当前 UI 的统一目标包括：

• section 结构统一
• pin 语义统一为紫色
• 选中态统一
• 信息密度更高但不显得挤
• 一致的搜索框、对话框、状态 badge 和 action button

相似组件尽量共享同一套语言，这样用户不用每页重新学习一次。