mesalogo
8a14cf356a
The tool environment page always displayed an unverified capability-dependency state even though it had no Skill or MCP evidence behind it. The page now shows only actual interpreter and companion-tool diagnostics; capability dependency status remains reserved for capability details with real validation results. Release note: 工具执行环境页不再显示没有实际验证依据的能力依赖占位状态。
306 lines
9.4 KiB
Markdown
306 lines
9.4 KiB
Markdown
# 工具执行环境 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`。
|
||
- 窄屏时外层页签保持单行并允许水平滚动，不折成多行，不替换为下拉框。
|
||
|
||
## 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
|
||
- 远程托管环境
|
||
- 开发环境
|