mesalogo
2f1881a414
Define repository and feature-scoped documentation rules for PRDs, User Stories, logic, UI, technical design, and progress evidence. Move feature-owned documents under docs/features, add one entry point per feature, remove the redundant docs index, and update all affected cross-references. Expand the local tool environment design with explicit product, story, logic, UI, technical, and progress documents.
193 lines
5.0 KiB
Markdown
193 lines
5.0 KiB
Markdown
# 本机工具环境 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
|
|
- 远程托管环境
|