rexp-web 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# REXP Hub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+通过本机 Handfree SSH-MCP 读取多个 SSH 节点的 GPU / NPU 资源与 REXP 实验记录。浏览器只连接本机 Web 服务；SSH 凭据由 Handfree 保管，服务器上无需启动 HTTP 服务。
+
+## 安装与打开
+
+推荐通过 Handfree SSH-MCP 的 `plugin-list` 发现 `rexp-web`，让 Agent 安装。
+安装后 Agent 读取本包的 `web-operations` skill，询问是否开启开机自启动，
+保存宿主的 SSH 配置路径，再启动并打开控制台。首次安装不会自动修改系统启动项。
+请将打开的地址加入浏览器书签，下次直接访问。
+
+也可独立安装与启动（需要 Node.js 22 或以上及支持插件接口的 Handfree SSH-MCP）：
+
+```bash
+npm install -g rexp-web
+rexp-web open
+rexp-web status --json
+rexp-web stop
+```
+
+独立使用时，在 `~/.config/rexp-hub/web.json` 配置 SSH-MCP 程序目录、个人节点与插件文件：
+
+```json
+{
+  "mcpDir": "/absolute/path/to/handfree-ssh-mcp",
+  "mcpConfig": "/absolute/path/to/servers.yaml",
+  "mcpPlugins": "/absolute/path/to/plugins.yaml"
+}
+```
+
+通过插件接入时，这些路径由宿主传入，`configure` 自动保存；无需用户手写。
+用户路径、SSH 凭据和连接配置不会写进 npm 包。没有 YAML 覆盖时沿用 SSH-MCP 的 OpenSSH 配置。
+运行时不会再依赖相邻源码仓库。网页服务按需持有自己的 MCP 子进程，独立于 Agent 会话。
+
+默认访问地址为 `http://127.0.0.1:5173/`，服务只监听本机。
+`open` 自动复用已运行服务；关闭浏览器不停止服务，也不关闭 Agent 的通道或远端实验。
+无订阅页面时停止相应监测采样，后台保留待命。
+
+## 自启动与插件管理
+
+在网页右上角“Web 设置”中修改开机自启动；这里指用户登录电脑后启动。
+也可以让 Agent 通过通用 `plugin-run`，选择 `rexp-web` 调用以下命令：
+
+| argv | 用途 |
+| --- | --- |
+| `configure --autostart on` / `off` | 首次明确选择，并保存宿主连接路径 |
+| `autostart on` / `off` / `status --json` | 修改或查询自启动 |
+| `open` | 启动后台服务并打开页面 |
+| `start` / `stop` / `status --json` / `logs` | 管理后台服务 |
+| `skills list --json` / `skills show web-operations --json` | 获取本版本使用说明 |
+
+macOS 使用用户 LaunchAgent，Windows 使用用户启动目录，Linux 桌面使用 XDG 登录启动。
+无桌面的 Linux 保留 CLI/MCP 启动方式。关闭自启动不会关闭当前服务；手动启动也不会重新开启自启动。
+升级保留偏好和数据，运行中的 Web 需明确停止再启动以加载新版本。
+
+设置位于 `~/.config/rexp-hub/web.json`，状态与日志位于 `~/.cache/rexp-hub/web/`。
+环境变量 `HANDFREE_MCP_DIR`、`HANDFREE_MCP_CONFIG`、`HANDFREE_PLUGINS_CONFIG` 可覆盖连接路径。
+
+## 源码开发
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+发行包自带构建好的页面，普通启动不会安装依赖或执行构建。
+源码前台开发使用 `npm run dev`，按 Ctrl+C 退出；后台停止用 `npm run web:stop`。
+本地工具箱可以作为并行入口，工具本身支持独立启动。
+
+## 当前数据
+
+- 节点列表来自 SSH-MCP `list-servers`，页面可见时每 3 秒轻量刷新，切回页面立即刷新，后端列表缓存仅 1 秒。新加入的 SSH 节点无需安装 REXP 即可显示；尚未探测时显示“检测中”。主机状态约每 30 秒在后台探测，不阻塞节点列表，也不因单台主机响应慢而延迟发现其他节点。
+- 当前节点的 GPU 指标来自 SSH-MCP 的只读 `nvidia-smi` 查询。Ubuntu 的首页及 GPU 详情复用 SSH-MCP 后台流式采样；Windows 使用共享的单次查询循环，避免 POSIX `timeout`/`sh`，约每 2 秒更新一次（加查询延迟）；详情页约每 20 秒补读 GPU 进程。若流式执行不可用，会改用约 5 秒定时刷新。趋势图显示实际采样的时间、GPU 使用率和显存占用。
+- REXP 正式发行包名为 `rexprun`，终端命令和插件 id 仍为 `rexp`；Web 沿用 `rexpPath` 指定的程序，不按 Python 发行包名拼接命令或更改 API。
+- 实验记录通过通用 `plugin-run` 调用 REXP 的 `runs --json`，一次读取全部列表字段。网页约每 20 秒刷新；开启通知的标签页存在时，优先使用 Web 服务约每 30 秒经 SSH 更新的结果，否则按页面请求直接读取。接口错误会直接显示，不再回退到旧 `rexp.*` 工具。
+- 实验列表通过 `plugin-run` 的 `runs --json` 读取完整记录，展示实验说明预览、GPU 编号、状态、已处理/预计样本数和提交时间；长说明以省略号收起。展开“实验运行”后点击记录，才会通过 `plugin-run` 的 `run show <id> --json` 读取完整详情，包括项目、实验名、环境、时间、错误原因、评测及路径。旧实验缺少说明或总数时显示 `—`，不推测数据。
+- 开启通知的网页保持打开时，Web 服务约每 30 秒通过 SSH-MCP 检查在线节点的实验状态；任务进入 `COMPLETED`、`FAILED` 或 `RECOVERABLE` 时各通知一次。通知标题显示状态，正文直接显示实验说明；旧记录没有说明时显示运行编号和缺失提示。支持自定义通知图标的浏览器使用 REXP Hub 图标，点击后打开对应节点的实验列表。Safari 普通标签页会忽略通知的 `icon` 设置；网站同时提供 Web App 图标，可通过 Safari 的“添加到程序坞”使用。首次检查只建立基线，避免把历史任务误报为新变化。监测不调用 Agent，因此不消耗 Agent token。
+- 关闭最后一个已开启通知的网页标签后，Web 服务立即停止实验监测；重新打开时读取当前状态，不补发关闭期间的通知。多个标签页同时打开时，直到最后一个标签页关闭才停止监测。
+- 页面隐藏时暂停 GPU 与页面本身的轮询；只要开启通知的标签页仍打开，实验通知监测就继续运行。读取失败会显示错误，并保留已读到的旧数据供查看。
+- Ubuntu 流式命令每次最多运行约 12 秒，随后按需接续；Windows 每次只启动一次查询，不使用无限循环命令。离开 GPU 详情后不会再启动下一轮。Web 专用 MCP 进程使用 `~/.cache/rexp-hub/ssh-mcp` 存放短暂的命令日志，并自动清理，不向 Handfree 源码目录写入 Web 采样日志。
+
+## 实验管理
+
+左侧先选择 SSH 服务器，下方“当前服务器”显示别名；节点总览、实验记录、参数搜索和资源监控均属于此节点，顶部面包屑持续显示目标服务器。切换服务器会关闭原节点详情和操作确认，返回新节点总览；不会合并不同节点的同名 run。服务器较多时列表内部滚动，功能入口保持可见。
+
+普通实验的详情抽屉、Ray Tune 搜索详情顶部提供管理操作，目标始终绑定当前 SSH 节点和运行编号。操作通过同一 `plugin-run` SSH 通道执行平台 CLI，不在服务器开放 HTTP 端口。
+
+- **暂停**：`rexp run pause` 协作暂停单个 run，不停止调度器或强杀进程。PAUSING 表示请求已发送，实验脚本需响应安全边界并保存检查点，状态才变为 PAUSED。普通实验与整个 Tune 搜索共用此语义。
+- **继续**：`rexp run resume` 校验有效检查点后入队，按资源排队。调度器 OFF 时会提示先启动调度器，不会自动启动整个节点。
+- **取消**：确认目标后取消后续调度，正在运行的进程需要时间配合退出；取消不是可恢复的暂停。
+- **清理空间**：先统计 checkpoints/artifacts 的占用并显示磁盘估算，再确认一次清空两个目录内容。保留记录、脚本、配置、日志、evaluation 和 analysis；artifacts 中的汇总、所有检查点和 Ray 恢复数据也会永久删除，依赖它们的分析无法重跑。只有已结束且进程退出的 run 可以清理。
+
+原始错误默认收起，结果只在平台确认后更新；请求成功但连接中断时提示刷新核实，不自动重发写操作。管理区打开时约 10 秒刷新，标签隐藏时暂停查询。节点新版 `run show --json` 提供能力信息；旧版节点仍能继续/取消/清理，暂停显示需更新节点平台。不会因打开网页自动操作实验，也不新增提交、重试或全局启停功能。
+
+页面使用深色侧栏、浅色工作区与低饱和绿色强调，保留独立滚动、展开面板、骨架屏和右侧详情。字体采用系统字体，无需请求外部字体服务。
+
+未安装、未配置或未初始化 REXP 属于节点准备状态，不作为全局监测故障提示。
+单个节点的读取错误只在选中该节点时显示简短提示；原始错误可展开“技术详情”，默认收起。
+其他节点的查询和实验完成通知继续工作，安装完成后按正常刷新自动恢复。
+
+Windows 节点状态由 Handfree 自动选择 PowerShell 探测，进程详情使用 CIM；采集不到的 CPU/用户信息显示未知，不用零代替。SSH 已连接但资源探测失败时，不会直接把节点标成离线。新增 SSH 节点由 Handfree 的文件监听加载，插件注册内容每次调用读取；网页下次正常刷新即可显示节点与新安装的 REXP，无需重启 Codex 或 Web。网页节点列表约 45 秒刷新、后端缓存最多 30 秒，因此更新并非每次都瞬间出现在页面上。`web.json` 中 MCP 程序位置和启动参数路径属于启动设置，与节点/插件内容更新不同。
+
+## Ray Tune 参数搜索面板
+
+首页的“参数搜索”卡片展示当前节点最近搜索的说明、状态和 trial 结束数量，点击展开。
+展开后可切换搜索任务，查看资源池/单 trial 资源、目标指标、累计最优趋势、
+多目标 Pareto 散点图以及 trial 参数/指标/上报历史。点击 trial 从右侧打开详情抽屉，查看完整参数、全部指标与上报历史，支持关闭按钮、Escape 和点击遮罩返回。
+表格只显示当前选中目标的指标，长 trial 编号、设备和参数截断显示，避免多目标或长参数撑宽页面。
+图表的坐标轴标明实际指标值与 trial 序号/上报轮次；没有数据时不生成示例曲线。
+多目标没有唯一最优，金色标记为按全部目标计算的 Pareto 候选（图中仅投影前两个目标）。
+
+通过已有 SSH-MCP 通用 `plugin-run` 读取 `rexp tune list/show --json`，不要求为服务器开放新端口。
+搜索概览、尝试分页、单次详情和图表分别读取。需要节点平台提供 `tune show --summary`、`tune trials`、`tune trial`、`tune charts` 接口；不提高 SSH-MCP 输出上限，不回退到全量读取。
+面板可切换“让位普通实验”：开启后等待中的 trial 优先级为 1；关闭后为 0，与普通实验按入队顺序执行。通过同一 SSH `plugin-run` 调用 `rexp tune policy`，平台确认成功才更新开关。正在运行的 trial 继续完成。面板不提交搜索、不安装依赖、不启动调度器。父 run 进度单位是 trials，普通实验仍是样本。
+只查询选中节点：列表约 30 秒，展开的搜索详情约 15 秒；隐藏页面或离开面板停止相应轮询，
+每条轮询不重叠。旧版平台没有 tune 命令时显示版本不支持，不影响普通实验/GPU 面板。
+节点需要使用包含 `rexp tune` 命令的新版平台；旧版节点继续使用原有实验面板。
+
+普通实验列表默认每页 30 条，trial 表格默认每页 50 条；两者均支持 10/30/50/100 条和直接跳转页码，分页栏位于表格上方并随列表滚动保持可见。
+实验列表与首页预览中的原生 Ray Tune 任务带 Tune 标记，点击直接进入该搜索，无需先看普通 run 详情；普通实验继续使用右侧详情抽屉。
+trial 表格分页；图表大于 500 个点时抽样显示并标明数量，完整参数与指标仍保留在记录中。
+
+一次搜索在实验列表中只占一个父 run；展开参数搜索后查看 trial，默认按预设指标效果排序（多目标 Pareto 优先），也可选择单个指标排序。`num_samples: -1` 显示无限搜索，保留已完成数。动态开关需要节点平台支持 `yield_to_normal`；旧节点开关禁用。
+
+## 实验工作台与可读的参数搜索
+
+实验页默认显示当前任务和最近 12 条结束记录。切换“全部记录”查看分页历史，
+或在搜索框中直接检索整个节点历史；支持说明、项目、运行编号、研究问题和环境关键词，
+并可按状态、类型和阶段筛选。“研究方向”把多个代码项目汇总；旧记录缺分类时留在未分类，
+不会根据文件名猜测或修改原始记录。新分类需要节点平台支持 research_topic/study/stage。
+
+参数尝试以可读说明为主展示，完整原始 ID、原精度参数和指标在右侧详情；
+新版节点可提供中文参数标签和说明模板，旧版节点直接使用真实参数名和值生成摘要。
+图表包含搜索进展（散点和累计最优）、指标分布、参数效果、参数组合平行坐标和多目标权衡，
+问号按钮支持鼠标悬停、键盘聚焦和点击查看解释；图上可点击点或线打开对应尝试。
+这些图是对现有快照的本机分析，不启动远端 Ray/Optuna Dashboard，不额外扫描日志或轮询 GPU。
+参数关联不等于参数重要性或因果；最终效果图排除失败/未完成记录。大量绘图数据抽样并标注，表格不抽样。
+
+独立查看 UI 演示（仅本机生成的示例数据，完全不连接 SSH）：
+
+```bash
+npm run build
+node scripts/preview-ui.mjs
+```
+
+访问 `http://127.0.0.1:5186/?view=tune`，在运行终端按 Ctrl+C 退出。
+演示与正式 `5173` 服务独立；无需安装平台、Ray 或 Optuna。
+
+指标在列表、选择器、图表及详情统一显示简短中文。搜索配置的 `metric_labels` 优先，
+旧记录中的常用指标使用固定翻译；无法确定含义的自定义指标显示“指标 N”，不猜测。
+悬停标签查看原始字段名，详情可展开原始指标和完整精度；排序与计算仍使用原始字段。
+
+参数尝试按“正在运行”和其余记录分别展示，运行/暂停中的尝试置于图表前方，
+不受历史列表关键词、状态筛选或分页影响。其余列表支持提交时间从新到旧或从旧到新，
+以及原有指标排序；切换时间排序不改变图表选中的目标指标。
+每行显示样本进度和提交时间，窄屏使用卡片布局；右侧详情列出提交、实际开跑和结束时间。
+提交时间表示平台首次记录该尝试，旧节点兼容读取原 started_at；时刻按浏览器本地时间显示，
+格式 YYYY-MM-DD HH:mm:ss。进度读取 samples_completed（兼容 samples），不把 training_iteration
+当作样本数；总数由新节点查询实验配置快照提供，旧节点缺少总数显示 —。
+未上报不显示零，提前停止不假设已完成全部样本。无需更新 SSH-MCP，不额外增加远端查询。
+
+
+## GPU 与昇腾 NPU 监控
+
+资源面板按选中节点显示 GPU 或 NPU。NVIDIA 使用 `nvidia-smi`，昇腾使用 `npu-smi info -m` 与 `npu-smi info`，不导入 PyTorch，也不启动远端 HTTP 服务。监控使用轻量非登录 shell 并补充驱动库路径，避免反复加载云镜像耗时的登录初始化。
+昇腾按运行时逻辑编号展示 AICore 利用率、HBM、温度、功耗及厂商工具可见的进程；支持 A3 与 910B3 的资源表格式，缺失指标显示“—”，不补成 0。物理卡数与逻辑设备数分别标注，例如 A3 的 **1 张物理卡 · 2 个逻辑设备**，每个设备 64 GiB HBM；它们与系统 RAM 是不同资源。
+同一节点的浏览器订阅共用采样；NPU 每次查询完成后间隔 2 秒继续，实际频率受 npu-smi 耗时影响，不并行堆积查询。页面隐藏时暂停，无订阅时停止。NVIDIA 继续使用原有约 2 秒一次的流式采样。NPU 参数搜索需要远端平台支持；网页读取 `tune list` 的 `accelerator_backends` 能力列表，支持时使用原有尝试、图表、暂停/恢复和让位开关，旧节点提示升级。
+新节点需要在个人插件注册文件中设置本机对应的 `platformRoot` 与 `rexpPath`；SSH 可连接并不代表插件已配置。配置可热读取，不必重启 Codex。
+## 参数搜索的数据加载与缓存
+
+- 列表只读取当前页（默认 50 条）；页码、每页条数、关键词、状态和排序均传给服务器。
+- 运行中的尝试单独每 15 秒读取；列表与图表每 60 秒更新，页面隐藏时停止刷新。
+- 点击尝试才读取完整参数、错误和指标历史；非运行详情缓存 5 分钟。
+- 图表单独读取全体成功结果的准确统计与限量样本，不拉取全部尝试历史。
+- 浏览器会话最多缓存 100 个视图，按完整 URL 区分节点、搜索、页码、筛选和指标，合并并发请求。
+  再次进入已访问页先显示缓存，过期才查询；不预取全部页，不跨节点混用缓存。
+- 手动刷新和管理操作会使该搜索缓存失效；旧节点不支持分页时提示更新，不全量回退。
+- 服务器当前仍需扫描本地原子快照文件，再筛选分页；不宣称是数据库索引分页。
+
+
+时间展示统一使用浏览器本地时区，格式为 `YYYY-MM-DD HH:MM:SS`；嵌套的 checkpoint、清理历史等时间也会换算，原始接口记录保持带偏移时间。
+
+
+## 共享服务器的可用算力卡
+
+点击节点总览右上方的“可用卡设置”（或打开“资源监控”），在“可用算力卡范围”中勾选口头约定归你使用的设备，点击“保存范围”。设置面板独立检测能力，不依赖实验记录是否读取成功；未配置平台或版本较旧时显示对应提示。此设置只控制该节点当前平台根目录的后续分配，普通实验和 Ray Tune 共用，不会停止正在运行的任务，也不会修改系统或其他人的进程。全部取消勾选会禁止新的算力卡分配，CPU 实验仍可运行。“全部可见设备”保留原有行为，也会允许后来新增的卡，共享服务器请谨慎选择。
+
+网页显示当前卡号，但保存 NVIDIA 驱动 UUID。原卡掉线后保留授权并标为缺失，不按新卡号补位；原卡恢复后可继续使用。旧版平台提示先升级，不会静默改用数字编号。当前昇腾探针未提供经验证的稳定 UUID，因此不能勾选绑定单张 NPU，仍可使用全部可见设备或禁止分配。
+
+SSH 可连接与平台可用分别检测：未配置、未安装、未初始化的平台显示对应状态，不作为实验数据读取故障。节点概况可显示已读取的算力卡信息，实验数据不可用时显示原因，不持续显示加载骨架。
+
+## 节点调度器开机自启动
+
+节点资源页提供“调度器开机自启动”开关（远端 rexprun 0.2.6+，Linux systemd）。开启后无需先连 SSH，开机即可处理队列并恢复被节点/调度器中断的有有效断点的任务；用户主动暂停的实验保持暂停。关闭开关不停止当前实验。权限不足时显示服务诊断，非 root 需要启用用户 linger。
+
+这是选中服务器上实验调度器的开关；右上角“Web 设置”管理的仍是本机网页服务登录自启动，两者独立。终端也可使用 `rexp autostart --enable/--disable`，以及 `rexp start` / `rexp stop` 手动启停。
+
+参数搜索将控制器存活与实际执行分开展示：有尝试计算时显示“正在执行尝试”，否则提示等待调度/资源。尝试列表可筛选“等待中”，等待记录显示占用卡的其他 run；运行区计数与独立刷新的运行尝试列表保持同步。