# 本机工具环境 UI 设计

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 计划 |
| 版本 | 0.1 |
| 日期 | 2026-09-01 |
| 关联 PRD | [本机工具环境 PRD](./prd.md) |
| 功能逻辑 | [本机工具环境功能逻辑设计](./logic-design.md) |
| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |

本文只定义本功能的界面结构和交互。颜色、字体、间距、通知、Switch、焦点和响应式行为以
全局设计系统为最终权威，不在本文件建立页面专属视觉体系。

## 1. 信息架构

“本机工具环境”位于 `Agent Runtime` 设置分类，处于默认工作区之后、具体 Runtime 高级
设置之前。它是本机 OpenCode、Continue、DeepSeek Harness 和 stdio MCP 的共享设置，
不放入任一 Runtime 专属卡片。

区块顶部持续显示：

> 用于新启动的本机 Runtime 和 stdio MCP；不修改系统环境，也不应用于普通终端或远程主机。

## 2. 页面结构

```text
本机工具环境
范围说明

Node.js 卡片
  来源
  当前状态
  自定义候选或路径操作
  测试环境

Python 卡片
  来源
  当前状态
  安装/更新/删除或自定义路径操作
  测试环境
```

卡片顺序固定为 Node.js、Python。页面不增加二级页签。

## 3. 来源选择

每张卡片使用原生单选语义，只提供：

1. **GoodBuddy 托管（推荐）**
2. **自定义环境**

不显示“自动选择”“系统安装”“指定路径”三个交叉选项。自定义环境选中后，在同一区域展示
检测候选下拉框和“选择其他可执行文件”次操作。

候选项格式：

```text
Node.js v22.14.0 · C:\Program Files\nodejs\node.exe
Python 3.13.2 · C:\Python313\python.exe
```

版本和绝对路径不能只放在 Tooltip 中。

## 4. Node.js 卡片

```text
Node.js

● GoodBuddy 托管（推荐）
  Node.js vXX · 已就绪
  npm 11.x · npx 11.x

○ 自定义环境
  [Node.js v22.x · C:\Program Files\nodejs\node.exe ▼]
  [选择其他可执行文件]

[测试环境]
```

托管 Node 随应用提供，不显示安装和删除操作。测试结果分别显示 Node、npm、npx，不能用
Node 成功代替整套组合成功。找不到配套 npm/npx 时，自定义 Node 可以保存，但状态显示
“Node.js 已就绪，npm/npx 不可用”。

## 5. Python 卡片

托管 Python 未安装：

```text
Python

● GoodBuddy 托管（推荐）
  尚未安装
  [安装]

○ 自定义环境
  [Python 3.13.x · C:\Python313\python.exe ▼]
  [选择其他可执行文件]
```

安装中使用卡片内进度：

```text
正在下载 Python 3.x
[================------] 68%
[取消]
```

安装后显示：

- Python 版本和架构。
- pip、venv 和 SSL 诊断状态。
- 安装占用空间。
- 有更新时的“更新”操作。
- “删除托管 Python”危险次操作。

删除确认说明受影响范围，不要求输入确认文字：

> 删除后，依赖托管 Python 的本机 SKILL 和 stdio MCP 将不可用。系统 Python、自定义环境
> 和项目文件不会被删除。

## 6. 两层状态

每张工具卡展示工具环境状态：

- 已就绪
- 尚未安装
- 正在安装
- 路径不可用
- 部分可用，例如 npm/npx 或 pip/venv 缺失
- 测试失败
- 可更新

SKILL/MCP 的能力详情展示能力依赖状态：

- 依赖已验证
- 依赖未验证
- 缺少第三方包
- 入口不可用

不得把工具卡的“已就绪”复用为某个 SKILL 或 MCP 的“完全可用”。

## 7. 生效与刷新

保存后在卡片中持续显示：

> 对新启动的本机 Runtime 和 stdio MCP 生效。已运行进程不会中途切换环境。

设置保存成功、安装成功、删除成功和重新检测成功使用应用通知。版本、路径、安装进度和
阻塞错误留在卡片内，不同时显示重复通知。

## 8. 错误与恢复

- 自定义路径失效：保留路径和来源选择，显示“重新检测”和“选择其他文件”。
- 下载失败：保留已验证旧安装和安装按钮。
- 诊断部分失败：逐项显示失败项，保留成功项。
- 取消安装：恢复“尚未安装”或原已安装版本。
- 字段错误：就地关联到选择控件。
- Runtime/MCP 已运行：不显示为错误，只说明新进程生效。

## 9. 无障碍与键盘

- 来源使用 `radiogroup`/`radio` 语义。
- 安装、测试、更新、删除和文件选择使用语义按钮。
- 下载进度使用可命名的 `progressbar`。
- 状态不只依赖颜色，必须包含文字。
- 禁用控件仍提供可理解的邻近说明。
- 切换到自定义环境后，焦点按正常 Tab 顺序进入候选选择框。
- 对话框关闭后焦点回到触发操作。
- 窄屏时卡片操作换行，不压缩版本和路径到不可读宽度。

## 10. 文案词汇

固定使用：

- 本机工具环境
- GoodBuddy 托管
- 自定义环境
- 工具环境已就绪
- 能力依赖已验证
- 新启动的本机 Runtime 和 stdio MCP
- 不应用于远程主机

不使用：

- 自动环境
- 系统模式
- 内置开发机
- 全局 Python
- 远程托管环境