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
parent dba3380a06
commit 2f1881a414
56 changed files with 1763 additions and 765 deletions
@@ -0,0 +1,192 @@
+# 本机工具环境 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
+- 远程托管环境