goodbuddy/docs/features/local-tool-environment/ui-design.md

工具执行环境 UI 设计

文档信息

项目	内容
状态	已实施
版本	0.2
日期	2026-09-02
关联 PRD	工具执行环境 PRD
功能逻辑	工具执行环境功能逻辑设计
全局规范	GoodBuddy 统一界面设计系统

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

1. 信息架构

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

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

一级分类副标题固定为：

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

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

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

1.1 分阶段显示

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

[ Skills ] [ MCP ]

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

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

2. 页面结构

能力与工具
管理 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：

<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：

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

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

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

邻近说明：

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

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

5. 工具环境来源选择

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

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

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

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

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

候选项格式：

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

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

6. Node.js 卡片

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 未安装：

Python

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

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

安装中使用卡片内进度：

正在下载 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
• 远程托管环境
• 开发环境