# 工具执行环境 UI 设计

## 文档信息

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

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

## 1. 信息架构

设置中心把现有 `Skills`、`MCP` 一级分类和新增的工具执行环境合并为一个“能力与工具”
一级分类。内容区使用三个水平 Tab：

```text
[ Skills ] [ MCP ] [ 工具执行环境 ]
```

一级分类副标题固定为：

> 管理 Skills、MCP 和本机工具执行环境

“工具执行环境”不放入任一 Runtime 专属卡片。该 Tab 顶部持续显示：

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

### 1.1 分阶段显示

第一阶段只实现统一菜单和现有能力页签：

```text
[ Skills ] [ MCP ]
```

此阶段不显示“工具执行环境”禁用 Tab、空页面或“开发中”占位。Node.js、Python 和工具下载源
真实可用后，再按本设计追加第三个水平 Tab。

“能力与工具”的页签条位于独立滚动的 Flex 设置内容区，直接包装层必须保持
`flex: 0 0 auto`，避免被下方长列表压缩到零高度。该规则同时服从根
[`UI-DESIGN.md`](../../../UI-DESIGN.md) 的 `PageTabs` 规范。

## 2. 页面结构

```text
能力与工具
管理 Skills、MCP 和本机工具执行环境

[ Skills ] [ MCP ] [ 工具执行环境 ]

Skills 面板
  现有 Skill 启停、导入、状态和 Runtime 分配
  五个内置 Skill；产品营销三个默认停用，通用文档工具两个默认启用

MCP 面板
  现有 MCP 配置、凭据、状态和 Runtime 分配
  [内置 MCP] [直连模型] [自定义 MCP] [电脑控制]

工具执行环境面板
  范围说明

  工具下载源
    原生地址 / OSS 镜像

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

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

产品营销的九种文档配方不单独占用 Skill 卡片。用户启用 `product-marketing` 后，
由该 Skill 根据任务按需读取内部工作流。界面只展示能够独立启停和分配 Runtime 的
五个顶层内置 Skill；已保存状态覆盖产品默认值。

工具执行环境面板内的区块顺序固定为工具下载源、Node.js、Python，不再增加页签。

## 3. 三个水平 Tab

外层页签使用共享 `PageTabs` 的 `segmented` 视觉变体，不使用页面自定义 Tab 或普通
`SegmentedControl`：

```tsx
<PageTabs
  ariaLabel="能力与工具设置"
  idPrefix="capabilities-and-tools"
  tabs={[
    { id: 'skills', label: 'Skills' },
    { id: 'mcp', label: 'MCP' },
    { id: 'tool-environment', label: '工具执行环境' }
  ]}
/>
```

交互规则：

- 普通入口默认打开 `Skills`。
- 现有 Skills/MCP 应用内入口分别定位到对应水平 Tab。
- 切换外层 Tab 不保存为产品设置，不修改任何 Skill、MCP 或工具环境值。
- 三个面板在同一次设置面板会话中保留编辑状态；切换后返回不得重置草稿。
- MCP 原有四个内层页签继续保留，外层和内层使用不同的 `aria-label` 与 `idPrefix`。
- 窄屏时外层页签保持单行并允许水平滚动，不折成多行，不替换为下拉框。

“MCP / 自定义 MCP”的添加和编辑共用设置上方的子 Modal。打开后聚焦名称输入框，
父设置与工作区保持不可交互；Tab 和 Shift+Tab 在编辑器内循环。X、取消、Escape、
遮罩及保存成功均返回原添加或编辑按钮，Escape 只关闭编辑器。保存期间禁止关闭，
失败保留输入。右侧浏览器沿用应用级 Modal 的视图释放规则，编辑器关闭后仍由父设置
保持隔离，设置关闭后恢复网页。

## 4. 工具下载源

使用原生 Radio Group：

```text
工具下载源
选择 GoodBuddy 受管 Runtime 和工具链的下载通道。

● 原生地址（默认）
  从各工件的固定上游地址下载。

○ OSS 镜像
  从 GoodBuddy OSS 下载相同工件。
```

邻近说明：

> 下载开始后会固定本次来源；失败时不会自动切换。该设置不影响模型、应用更新、Agent、
> pip/npm 依赖或用户配置的网络地址。

切换设置即时保存，不触发下载，不取消活动任务。成功通过应用通知反馈；保存失败恢复最后
确认值并在 Radio Group 附近显示错误。

## 5. 工具环境来源选择

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

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

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

“自定义环境”单选项始终可操作。尚无候选或已保存路径时，点击只展开选择区域并保持当前
实际来源，不把入口禁用，也不自动选择第一个候选。选择区域显示“刷新候选”和“选择其他
可执行文件”；只有用户明确选择且 Main 验证成功后才保存并切换来源。

文件选择取消不显示错误、不发送成功通知且保持选择区域展开。验证失败在对应 Node/Python
卡片的路径操作附近显示，保留原来源和原路径；不得只在页面顶部显示错误。刷新后出现候选
时通过正常列表更新呈现，不改变当前来源，焦点保持在触发操作或用户随后选择的候选上。

候选项格式：

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

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

## 6. 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 不可用”。

## 7. 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、自定义环境
> 和项目文件不会被删除。

## 8. 两层状态

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

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

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

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

工具执行环境页不掌握具体 SKILL/MCP 的验证证据，因此不显示固定的“依赖未验证”占位
区块。只有对应能力产生真实验证结果后，才在该能力详情中展示上述状态。

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

## 9. 生效与刷新

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

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

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

## 10. 错误与恢复

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

## 11. 无障碍与键盘

- 外层使用 `tablist`/`tab`/`tabpanel`，支持左右方向键、Home、End 和 roving focus。
- 每个外层 `tab` 通过共享组件准确关联自己的 `tabpanel`。
- 来源使用 `radiogroup`/`radio` 语义。
- 安装、测试、更新、删除和文件选择使用语义按钮。
- 下载进度使用可命名的 `progressbar`。
- 状态不只依赖颜色，必须包含文字。
- 尚无自定义候选时不得禁用“自定义环境”入口；真正因活动操作禁用的控件仍提供可理解的
  邻近说明。
- 切换到自定义环境后，焦点按正常 Tab 顺序进入候选选择框。
- 对话框关闭后焦点回到触发操作。
- 窄屏时卡片操作换行，不压缩版本和路径到不可读宽度。

## 12. 文案词汇

固定使用：

- 能力与工具
- Skills
- MCP
- 工具执行环境
- GoodBuddy 托管
- 自定义环境
- 工具环境已就绪
- 能力依赖已验证
- 新启动的本机 Runtime 和 stdio MCP
- 不应用于远程主机
- 工具下载源
- 原生地址
- OSS 镜像

不使用：

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