Files

T

mesalogo 2f1881a414 docs: organize product design by feature

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.

2026-09-01 14:52:22 +08:00

5.0 KiB

Raw Blame History

本机工具环境 UI 设计

文档信息

项目	内容
状态	计划
版本	0.1
日期	2026-09-01
关联 PRD	本机工具环境 PRD
功能逻辑	本机工具环境功能逻辑设计
全局规范	GoodBuddy 统一界面设计系统

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

1. 信息架构

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

区块顶部持续显示：

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

2. 页面结构

本机工具环境
范围说明

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

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

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

3. 来源选择

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

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

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

候选项格式：

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

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

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

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

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
远程托管环境

5.0 KiB Raw Blame History