# Orca 前端（0.8）

会话顶栏 **机群** → 右侧栏 **机群**。无会话的页面不创建侧栏；设置 → **Orca 配置** 只展示配置与授权范围。

## 信息与交互

- 对话中 10 种 `orca_*` 工具有独立卡片：主机、操作、结果常显；命令输出、带行号的文件、搜索上下文、diff 和冲突可展开。异常默认展开。旧版或无法解析的展示数据回退到原始输出。
- 主机、命令/路径分层显示；窄容器换行，完整文本可展开与复制。输出默认最多 320px 高，可展开全部。
- 机群先展示已知运行任务，再展示主机和历史记录。主机可展开 GPU 每卡利用率、显存、负载、内存、磁盘和最后成功同步时间。
- 日志尾按需读取 50 行，不假装实时输出。停止使用独立的确认/取消区域，提交后防重复，并核对当前任务身份。只调用 fleet 的登记任务停止逻辑。
- 授权可逐条撤销；新增授权仍来自审批。审批首行明确操作类别、主机、目录及实际期限，并说明宿主“允许一次”按钮的记忆效果。
- patch 卡片的“复制回滚指令”只复制明确含主机与 patch_id 的指令，由用户发送后经过原有审批。
- 文案中英双语，样式使用宿主主题变量。键盘可操作按钮、展开项和日志；停止确认可用 Escape 取消。

## 数据口径

这是缓存视图。宿主默认每 120 秒探测；客户端每 15 秒读取缓存，多个组件共享请求。没有订阅者或窗口隐藏时停止客户端轮询。顶栏可见时，即使侧栏关闭，仍会读取缓存。打开侧栏本身不产生 SSH。

每台读取 `panel.jobLimit`（默认 5）条最近登记，**不保证包含所有运行中的任务，也不代表机器是否空闲**。根据 `registry_records_total` 标记完整性；统计不完整时显示 `+` 与范围说明。不再对跨主机列表额外截断到 25 条。

失败时保留最后成功的数据与时间，将旧的运行任务显示为“未知”，禁止从过期行停止任务。数据超过 `max(60 秒, 2 × pollSeconds)` 标记过期；关闭后台探测时仍会过期，需手动刷新。零任务不显示“空闲”。

磁盘可用不足 5% **或** 20 GiB 时告警，GPU 运行使用中性色。探测失败、磁盘不足、任务失败有各自文字说明。

## 鉴权接口

全部由 DSH `connection.fetch.register` 注册，继承浏览器认证、来源检查和 owner 权限；请求为 POST JSON：

| 路径 | 用途 |
|---|---|
| `/api/dsh-orca/summary` | `{refresh?:boolean}`，读缓存或显式探测 |
| `/api/dsh-orca/job/tail` | `{host,session,jobId?,lines?}`，读取指定任务日志 |
| `/api/dsh-orca/job/stop` | `{host,session,jobId,grace_seconds?}`，核对身份后停止 |
| `/api/dsh-orca/grants/list` | 列出有效授权 |
| `/api/dsh-orca/grants/revoke` | `{host,workdir,action}`，撤销一条授权 |

原 `/dsh-orca/summary` 无鉴权路由已删除。工具与 UI 使用相同工具执行函数，未新增授权或配置修改接口。任务停止后只重新探测该主机。

## 配置与运行限制

配置仍在当前 profile 的 `cordis.patch.yml` 中。`hosts: []` 从 SSH 配置发现最多 12 个具体别名；建议显式列出实际监控的服务器。`panel.pollSeconds: 0` 关闭后台探测。

任务列表仅覆盖已登记的最近记录，不显示其他用户进程。工具执行期间没有流式输出；长任务使用 launch 与日志尾。新版代码安装后需要重新加载 DSH 的宿主与客户端模块，不能仅根据插件列表的版本号判断是否生效。

## 验证记录（2026-10-22）

- 自动测试：54 项 JavaScript、174 项 Python 及 35 项子测试通过；使用 DSH 自带校验器验证工具 schema 与展示 meta 的无损 JSON 要求。
- 本机 DSH：0.8.0 以本地项目链接安装；真实机群刷新、主机展开、日志尾、停止确认与取消、旧记录原始输出回退已验证，刷新后控制台无新消息。
- 视觉：桌面与 390 × 844 窄视口、浅色与深色主题已检查。
- 接口：旧路由 404；未认证请求 401；异源请求 403。停止、撤销与审批预检的异常分支由隔离测试覆盖；未为验收停止实际训练，也未逐一在真实会话新执行全部 10 种工具。