# 主机管理与云环境界面设计

状态：主机管理一期（入口迁移与列表精简）2026-10-13 已实现，见[实施进度](./progress.md)；列表与详情两栏和云环境页面仍待实现。范围见[PRD](./prd.md)，状态及依赖遵守[功能逻辑](./logic-design.md)。视觉、页面壳层和组件遵守[统一界面设计系统](../../../UI-DESIGN.md)。

## 应用入口

应用中心新增“主机管理”和“云环境管理”两个同级应用，其中“主机管理”已实现。应用菜单、管理应用中的“打开”和常驻侧栏入口进入同一主内容区页面，关闭来源菜单或管理 Modal，不在应用中心 Modal 内管理主机。业务页面使用全局范围标识；打开页面不切换当前项目、不连接主机或执行安装。

通用启用、常驻和排序遵守[应用导航设计](../application-tool-navigation/ui-design.md)。设置中心不再包含“主机与远程执行”分类和“平台功能 > 远程项目”页签。共享远程能力开关只在应用中心的“主机管理 > 应用设置”中，开关文字为“启用远程能力”；业务页面不重复提供设置页签。

远程能力关闭时，主机管理仍可从应用菜单和应用中心打开：“主机”页签显示“远程能力未启用”及“启用远程能力”按钮，不调用主机服务；“Agent 离线包”页签照常可用，便于提前下载或导入。

## 主机页面（一期，已实现）

页面使用共享 `standard` 壳层，标题区显示“主机管理”和全局范围。页签为“主机”和“Agent 离线包”；两个面板切换时保持挂载，安装、下载和导入的进度不中断。离线包页签首次显示时才读取包清单。

“主机”页签顶部是名称或地址搜索和“添加主机”。主机多于一台时，每台主机默认收起为一行，包含：

| 区域 | 内容 |
| --- | --- |
| 左侧 | 展开按钮、名称、`用户@地址:端口` |
| 状态徽标 | 验证状态；已验证时显示执行环境摘要（环境就绪、环境待更新、环境未安装、环境未检查、安装中）；有关联项目时显示项目数 |
| 右侧 | “编辑”或“验证并保存”、“删除”，均为纯文字按钮 |

只有一台主机时默认展开。安装进行中、安装失败、版本读取失败或正在确认删除时，该主机强制展开且不能收起。保存或重新验证成功后自动展开该主机。展开后显示认证方式、凭据、验证状态、Host Key 指纹、连接结果和执行环境；执行环境的版本以表格呈现，列为“组件 / Host 已安装 / GoodBuddy 所需 / 状态”，悬停版本号显示架构。

删除确认在主机头部下方占满整行，列出会一并删除的关联项目记录，并说明不会连接主机或删除远端内容。展开状态只保存在当前页面，不持久化。

## 主机页面（后续，待实现）

后续改为列表与详情两栏，点击主机只更新详情，不重排列或滚动列表；工具栏补充来源筛选和连接状态筛选。详情使用共享 `PageTabs`：

| 页签 | 内容与操作 |
| --- | --- |
| 概览 | 名称、来源、系统架构、独立状态及检查时间；关联云实例时提供“查看云实例” |
| 连接配置 | 地址、端口、用户名、认证配置状态、Host Key；编辑与重新验证复用既有流程，不回显凭据 |
| 执行环境 | Agent / Runtime 版本、检查结果、安装进度；保留安装、更新、重装及既有下载方式选择 |
| 关联项目 | 所有引用该主机的项目，明确归档状态；提供打开项目和创建远程项目 |

云关联字段按需显示，手工主机不出现必填平台、区域和实例 ID。删除主机置于次要操作，确认内容列出本地项目影响及远端资源保留范围。

未选择主机时提示选择列表项；没有主机时提供添加入口；搜索无结果时提供清除筛选。连接失败、安装失败和数据读取失败分别显示原因与对应重试操作。用户主动检查所选主机时才连接远端，不能因列表渲染而检查全部主机。

## 云环境页面

标题区显示“云环境管理”、全局范围及“添加平台连接”。通过平台连接和适用的区域或资源范围筛选实例，列表展示名称、平台、位置、实例状态、地址和接入状态。刷新明确针对当前查询范围，并显示上次成功时间。

未接入实例提供“接入主机”，进入地址与认证选择，再完成现有验证向导。已接入实例提供“打开主机”；关联已有主机时可搜索选择，明确展示目标后验证。两个页面之间往返恢复来源筛选、所选记录和滚动位置。

实例运行、SSH 连接和环境就绪分别显示文字状态。只读平台账号可以查询实例并接入 SSH；权限不足时说明失败操作，不把整个平台笼统标为不可用。平台 API 可达但 SSH 不通时保留资源详情与修正连接的入口。

首版不展示尚未实现的创建、销毁或网络编排按钮。各适配器随真实能力交付，不能用不可操作的平台卡片代替接入功能。

## 应用设置

各应用的“应用设置”中，开关统一靠右对齐；带说明图标的开关，说明图标紧跟文字，开关仍在右侧对齐。

## 响应式与交互

一期在窄容器下，主机行的状态徽标换到第二行，地址与名称上下排列，事实列改为单列。后续两栏无法满足共享最小宽度时改为单面板，选择主机进入详情并提供“返回主机列表”，返回恢复筛选、滚动和列表项焦点。页签可横向滚动，搜索与筛选换行，长地址和错误信息折行，页面不整体横向溢出。

列表项及操作使用语义按钮，提供可访问名称和可见焦点；一期展开按钮使用 `aria-expanded` 和 `aria-controls`，名称为“展开 / 收起 {主机名} 的详情”，编辑、删除按钮名称带主机名；页签沿用 `tablist`、`tab`、`tabpanel`、方向键及 Home/End。弹窗遵守共享焦点恢复及未保存编辑规则。通知使用全局应用通知，进行中的安装进度保留在对应主机，页面切换不重启操作。

验收对应 AC-RH-1 至 AC-RH-7，覆盖浅深主题、窄窗口、键盘操作、空列表、长名称、认证失败及安装取消；具体实施记录需附真实 UI 验证结果。