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.

docs/features/local-tool-environment/README.md

@@ -0,0 +1,39 @@
+# 本机工具环境
+
+本目录是 GoodBuddy“本机工具环境”功能的唯一文档入口。该功能为本机 SKILL 和本机
+stdio MCP 提供明确、可诊断的 Node.js 与 Python 环境，同时允许专业用户选择自己维护的
+解释器。
+
+本功能不作用于 SSH Host 上的 GoodBuddy Agent、固定 Node、签名 Runtime、SKILL 或 MCP。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、产品目标、范围、需求和产品验收 |
+| [User Stories](./user-stories.md) | 用户角色、使用场景和逐故事验收 |
+| [功能逻辑](./logic-design.md) | 不变量、状态机、决策表、失败恢复和跨场景一致性 |
+| [UI 设计](./ui-design.md) | 页面结构、组件、状态、文案和无障碍一致性 |
+| [技术设计](./technical-design.md) | Main、Runtime、MCP、打包、生命周期和测试架构 |
+| [功能进度](./progress.md) | 已完成、进行中、待实施、阻塞项和验证证据 |
+
+## 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| 本机工具环境 | GoodBuddy 在桌面所在设备上向本机 Runtime 和 stdio MCP 提供的工具命令环境 |
+| GoodBuddy 托管 | 由 GoodBuddy 提供、验证并解析的 Node.js 或 Python |
+| 自定义环境 | 用户从检测结果中选择或直接指定的外部解释器 |
+| 工具就绪 | 解释器及配套命令通过真实诊断 |
+| 能力依赖就绪 | 某个 SKILL 或 MCP 所需的第三方包和入口通过实际验证 |
+
+## 文档维护规则
+
+1. 产品范围只在 PRD 定义，其他文档链接引用。
+2. 界面视觉和交互只在 UI 设计定义，并服从仓库根目录的
+   [统一界面设计系统](../../../UI-DESIGN.md)。
+3. 状态转换、优先级和冲突决策只在功能逻辑中定义。
+4. 进度文档只记录已验证事实，不复制未来设计。
+5. 技术实现变化先更新技术设计；用户行为变化同时更新 PRD、User Stories、功能逻辑和
+   UI 设计。
+6. 每次完成功能阶段后立即更新进度、验证命令和剩余阻塞项。

docs/features/local-tool-environment/logic-design.md

@@ -0,0 +1,374 @@
+# 本机工具环境功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 计划 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-01 |
+| 关联 PRD | [本机工具环境 PRD](./prd.md) |
+| 关联场景 | [本机工具环境 User Stories](./user-stories.md) |
+
+本文是本功能业务规则、状态转换、决策表和跨场景一致性的权威来源。它不定义组件视觉，也
+不规定代码模块如何实现。
+
+## 1. 逻辑目标
+
+1. 同一用户操作在不同本机 Runtime 和 stdio MCP 中得到一致的解释器选择。
+2. 系统不通过隐式回退掩盖配置错误。
+3. 工具可执行、配套命令可执行和具体能力依赖可用是三个可区分事实。
+4. 已运行进程使用稳定环境，不被设置变化中途改写。
+5. 安装、更新、取消、失败和删除都有唯一、可恢复的结果。
+6. 本机环境和远程 Host 环境没有隐式传播。
+
+## 2. 核心不变量
+
+### INV-1 单一明确来源
+
+Node.js 和 Python 各自恰好保存一个来源：`managed` 或 `custom`。不存在 `auto`、候选优先级
+列表或运行时动态选择。
+
+### INV-2 禁止静默回退
+
+当前来源不可用时，该工具明确不可用。即使发现另一套系统解释器，也不会自动切换。
+
+### INV-3 配套命令同源
+
+- `node`、`npm`、`npx` 必须属于同一 Node 来源。
+- `python`、`python3`、`pip` 必须属于同一 Python 来源。
+- `pip` 等价于当前 Python 的 `-m pip`，不能解析到其他解释器。
+
+### INV-4 三层状态独立
+
+1. **解释器状态**：Node 或 Python 本身能否执行。
+2. **工具组合状态**：npm/npx 或 pip/venv/SSL 是否完整。
+3. **能力依赖状态**：具体 SKILL/MCP 的入口和第三方依赖是否通过验证。
+
+任一上层成功都不能推导下一层成功。
+
+### INV-5 进程环境不可变
+
+每个 Runtime/MCP 进程在启动时取得一份环境快照。设置变化只影响之后启动的进程，不改写
+已运行进程的 PATH 或解释器。
+
+### INV-6 绝对命令优先
+
+stdio MCP 配置的绝对 command 表达用户对该 MCP 的明确覆盖，原样执行，不经过全局工具
+命令替换。
+
+### INV-7 本机与远程隔离
+
+本机工具选择、shim、Python 包、SKILL 包和 stdio MCP 配置不上传到远程 Host。
+
+### INV-8 不推断能力依赖已就绪
+
+能力没有专属实际诊断时，状态只能是“未验证”，不能根据解释器版本或文件存在推断“已就绪”。
+
+## 3. 状态维度
+
+### 3.1 来源选择
+
+```text
+managed
+custom(executablePath)
+```
+
+这是唯一持久状态。
+
+### 3.2 托管 Python 安装状态
+
+```text
+not-installed
+downloading
+verifying
+installing
+testing
+ready
+update-available
+error
+```
+
+`error` 同时携带“是否仍有旧版可用”。若旧版可用，实际工具状态仍基于旧版诊断。
+
+托管 Node 随 GoodBuddy 存在，不使用下载安装状态，但仍可能因打包损坏进入诊断失败。
+
+### 3.3 工具诊断状态
+
+```text
+unknown
+testing
+ready
+partial
+unavailable
+```
+
+- `ready`：解释器和本功能承诺的配套命令全部通过。
+- `partial`：解释器通过，至少一个配套命令失败。
+- `unavailable`：解释器本身不能使用。
+
+### 3.4 能力依赖状态
+
+```text
+unknown
+checking
+ready
+missing
+incompatible
+error
+```
+
+- `unknown` 在 UI 中显示“依赖未验证”。
+- `missing` 表示明确缺少包或入口。
+- `incompatible` 表示解释器版本、架构或 ABI 不满足已声明要求。
+- `error` 表示诊断本身没有得出有效结论。
+
+## 4. 来源解析决策表
+
+| 保存来源 | 当前事实 | 解析结果 | 是否回退 |
+| --- | --- | --- | --- |
+| 托管 Node | 完整诊断通过 | 使用 Electron Node 与锁定 npm/npx | 否 |
+| 托管 Node | Node 通过，npm/npx 失败 | Node 部分可用，显示失败项 | 否 |
+| 托管 Node | Node 失败 | Node 不可用，提示修复/重装 GoodBuddy | 否 |
+| 托管 Python | 未安装 | Python 不可用，提供安装 | 否 |
+| 托管 Python | 已安装且诊断通过 | 使用托管 Python | 否 |
+| 托管 Python | 更新失败但旧版健康 | 继续使用旧版并显示更新失败 | 否 |
+| 托管 Python | 安装损坏 | Python 不可用，提供重新安装/删除 | 否 |
+| 自定义 | 路径及诊断通过 | 使用该绝对路径 | 否 |
+| 自定义 | 路径失效 | 保持选择并显示路径不可用 | 否 |
+| 自定义 | 解释器通过、配套命令失败 | 部分可用并显示失败项 | 否 |
+| 任意 | 发现其他有效解释器 | 只作为候选展示 | 不自动使用 |
+
+## 5. 命令解析决策表
+
+| 调用形式 | 结果 |
+| --- | --- |
+| `node ...` | 当前 Node |
+| `npm ...` | 当前 Node 配套 npm |
+| `npx ...` | 当前 Node 配套 npx |
+| `python ...` | 当前 Python |
+| `python3 ...` | 当前 Python |
+| `pip ...` | 当前 Python `-m pip` |
+| `#!/usr/bin/env node` | 从进程工具 PATH 解析当前 Node |
+| `#!/usr/bin/env python3` | 从进程工具 PATH 解析当前 Python |
+| stdio MCP 绝对 command | 原样执行 |
+| 未托管裸命令，例如 `uvx` | 按原筛选 PATH 处理；找不到则明确失败 |
+| HTTP/SSE MCP | 不参与本机命令解析 |
+
+绝对 command 的子进程若自行调用裸 `node` 或 `python`，仍会看到该 MCP 进程启动时的工具
+PATH。这不改变绝对 command 本身。
+
+## 6. 首次使用和迁移
+
+### 6.1 全新安装
+
+| 工具 | 默认选择 | 首次状态 |
+| --- | --- | --- |
+| Node.js | GoodBuddy 托管 | 立即真实诊断 |
+| Python | GoodBuddy 托管 | 未安装，展示安装入口 |
+
+系统候选可以展示，但不会改变默认选择。
+
+### 6.2 旧版本升级
+
+1. 设置中没有工具环境字段时执行一次迁移。
+2. 分别按旧版本实际 PATH 解析 Node 和 Python 3。
+3. 有效解释器固化为 `custom + 绝对真实路径`。
+4. 无有效解释器时选择 `managed`。
+5. 持久化后不再因 PATH 变化迁移。
+
+迁移中 Node 和 Python 独立决策，不要求二者使用同一种来源。
+
+## 7. 托管 Python 生命周期
+
+### 7.1 首次安装
+
+```text
+not-installed
+→ downloading
+→ verifying
+→ installing
+→ testing
+→ ready
+```
+
+任一步失败：
+
+```text
+→ 删除本次暂存
+→ error（没有活动版本）
+→ 用户可重试
+```
+
+### 7.2 取消
+
+| 取消阶段 | 结果 |
+| --- | --- |
+| 下载 | 终止下载、删除暂存、回到安装前状态 |
+| 校验 | 终止校验、删除暂存、回到安装前状态 |
+| 解压/安装 | 完成本次有界清理、回到安装前状态 |
+| 测试 | 停止诊断、删除未发布候选、回到安装前状态 |
+
+取消不发布候选版本，不把取消显示为安装失败。
+
+### 7.3 更新
+
+1. 下载和验证候选时，旧版继续服务现有进程。
+2. 应用候选前，页面说明需要停止依赖托管 Python 的本机 Runtime/MCP。
+3. 用户确认后通过现有生命周期取消/停止相关进程。
+4. 无法确认停止时不替换当前版本。
+5. 候选完整诊断通过后才发布。
+6. 失败继续使用旧版，并显示更新失败。
+
+首期不让两个托管 Python 版本长期并存。候选暂存只服务本次更新。
+
+### 7.4 删除
+
+| 条件 | 行为 |
+| --- | --- |
+| 没有使用中进程 | 确认后删除托管目录 |
+| 有使用中进程 | 说明影响，用户确认后停止相关进程再删除 |
+| 进程停止失败 | 不删除，保留当前环境 |
+| 当前选择为自定义 | 删除托管包不改变自定义来源 |
+| 当前选择为托管 | 删除后保持托管选择，状态变为未安装 |
+
+## 8. 设置保存与进程生效
+
+### 8.1 保存时
+
+- 验证待保存来源。
+- 自定义路径必须在保存前通过解释器诊断；配套命令可以形成 `partial`。
+- 保存成功后标记本机 Runtime 环境配置已变化。
+- 不直接修改任何运行中进程。
+
+### 8.2 后续进程
+
+- 没有活动请求的缓存 Runtime 在下次使用前按现有重建入口重建。
+- 有活动请求的 Runtime 完成或被用户停止前保持原环境。
+- 已启动 stdio MCP 保持原环境，正常关闭、重连或显式测试后使用新环境。
+- 新启动的 Runtime/MCP 立即使用新环境。
+
+每个工具调用的活动记录应归属于实际承载它的进程，不根据最新设置追改历史来源。
+
+## 9. 能力依赖逻辑
+
+### 9.1 诊断输入
+
+能力可以声明：
+
+- 需要 Node 或 Python。
+- 最低/最高解释器版本。
+- 可选依赖文件位置。
+- 可选的无副作用诊断入口。
+
+首期声明只用于显示、版本比较和显式诊断，不触发自动安装。
+
+### 9.2 状态推导
+
+| 工具状态 | 能力诊断 | 能力状态 |
+| --- | --- | --- |
+| unavailable | 不执行 | missing 或 incompatible，附工具原因 |
+| partial | 能力不依赖失败配套项且实际诊断成功 | ready |
+| partial | 能力依赖失败配套项 | missing |
+| ready | 没有能力诊断 | unknown |
+| ready | 实际诊断成功 | ready |
+| ready | 明确缺包 | missing |
+| ready | 版本/ABI 不满足 | incompatible |
+| 任意 | 诊断自身异常 | error |
+
+“依赖未验证”不是错误，也不能显示为“已就绪”。
+
+## 10. Ask、Execute 与 MCP
+
+| 场景 | 解释器是否可见 | 是否允许执行 |
+| --- | --- | --- |
+| 本机 Execute Runtime | 是 | 按现有 Execute 权限 |
+| 本机 Ask Runtime | 可以存在于进程环境 | 仍由 Runtime Ask 边界决定，不能因此获得命令权限 |
+| Main 启动的已启用 stdio MCP | 是 | 按当前 MCP 分配和模式规则 |
+| HTTP/SSE MCP | 不适用 | 按当前网络 MCP 规则 |
+| 远程 Runtime | 否 | 使用远程 Host 自身环境 |
+
+工具环境不创建新的工具，不扩大 Runtime 当前允许的工具集合。
+
+## 11. 网络受限与离线
+
+### 11.1 托管 Node
+
+随 GoodBuddy 提供，安装后可离线使用。
+
+### 11.2 托管 Python
+
+- 首期支持当前官方 GitHub/镜像来源。
+- 下载源不可达时保持未安装或旧版可用状态，并显示准确原因。
+- 首期不提供 Python 离线包导入，避免引入未经选型的包格式和导入流程。
+- 完全离线用户可以选择已经离线安装的自定义 Python。
+
+未来若加入离线导入，必须在 PRD、User Stories、逻辑状态和技术包校验中同时定义，不能只
+增加一个文件按钮。
+
+## 12. 冲突与一致性检查
+
+| 可能冲突 | 唯一规则 |
+| --- | --- |
+| 全局工具选择 vs MCP 绝对 command | 绝对 command 优先 |
+| 新设置 vs 运行中进程 | 运行中进程保留启动快照 |
+| 新托管版本 vs 健康旧版本 | 候选完整通过后才发布 |
+| 系统发现新版本 vs 已保存自定义路径 | 不自动切换 |
+| 解释器成功 vs 缺少第三方包 | 工具 ready，能力 missing/unknown |
+| Ask 环境包含解释器 vs Ask 只读 | Ask 权限边界优先 |
+| 本机设置 vs 远程项目 | 远程隔离优先 |
+| 镜像不可达 vs 其他来源可用 | 不在同一次操作中静默切换来源 |
+
+## 13. 逻辑评估结论
+
+### 13.1 完整性评估
+
+| 评估维度 | 结论 | 依据 |
+| --- | --- | --- |
+| 首次使用 | 通过 | 托管 Node 立即诊断，托管 Python 明确未安装 |
+| 正常执行 | 通过 | SKILL 与 stdio MCP 共用同一命令解析 |
+| 自定义环境 | 通过 | 明确路径、真实诊断、禁止静默回退 |
+| 部分失败 | 通过 | 解释器、工具组合、能力依赖三层状态独立 |
+| 安装生命周期 | 通过 | 安装、取消、失败、重试有唯一结果 |
+| 更新生命周期 | 通过 | 候选通过后发布，失败保留健康旧版 |
+| 删除生命周期 | 通过 | 使用中进程先停止，失败不删除 |
+| 设置生效 | 通过 | 进程启动快照不可变，新进程使用新设置 |
+| 升级兼容 | 通过 | 旧系统解释器一次性固化为自定义路径 |
+| Ask/Execute | 通过 | 工具环境不扩大工具集合或权限 |
+| 远程边界 | 通过 | 本机配置不进入 Host |
+| 受限网络 | 通过 | 来源失败可见，不在同次操作静默切换 |
+| 完全离线 | 有明确限制 | Node 可用；Python 首期要求已有自定义环境 |
+
+### 13.2 一致性评估
+
+- “两种来源”与自定义候选探测不冲突：候选只是自定义来源的选值，不是第三种来源。
+- “禁止回退”与升级迁移不冲突：迁移只发生一次，完成后按普通保存选择处理。
+- “进程环境不可变”与 Runtime 重建不冲突：只有空闲或后续启动的进程使用新环境。
+- “工具环境就绪”与“能力依赖就绪”不冲突：两者属于独立状态维度。
+- “绝对 MCP command 优先”与 PATH 注入不冲突：command 不替换，但其子进程继承启动快照。
+- “更新保留旧版”不要求长期多版本管理：旧版只在候选发布前保持当前，候选失败即删除。
+
+### 13.3 当前未决项
+
+没有未决的产品逻辑分支。以下属于实施前必须解决的技术选型，不改变业务规则：
+
+1. 六平台 CPython 独立发行包、固定版本、许可证和摘要。
+2. SKILL/MCP 运行要求声明的最小 schema 和无副作用诊断入口。
+3. 各 Runtime 当前缓存进程的精确空闲判定与既有重建入口接线。
+
+若技术选型无法满足当前逻辑，例如目标 Python 工件不包含可用 pip/venv，必须回到 PRD 和
+逻辑设计调整承诺，不能在实现中静默降级。
+
+## 14. 需求追踪
+
+| 逻辑范围 | PRD | User Stories |
+| --- | --- | --- |
+| 明确来源与禁止回退 | FR-3、FR-8 | US-C1、US-C2、US-D3 |
+| 托管 Node | FR-1 | US-A1、US-B2 |
+| 托管 Python 生命周期 | FR-2、FR-9 | US-A2、US-D2、US-D4、US-D5 |
+| 三层状态 | FR-6 | US-A3、US-A4 |
+| MCP 命令解析 | FR-5 | US-B1、US-B2、US-B3 |
+| 生效时机 | FR-7 | US-C3、US-C4 |
+| Ask/Execute | FR-10 | US-D6 |
+| 远程隔离 | FR-7、FR-9 | US-D1 |
+| 受限网络与离线 | FR-2 | US-E1、US-E2 |

docs/features/local-tool-environment/prd.md

@@ -0,0 +1,158 @@
+# 本机工具环境 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 计划 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-01 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 关联文档 | [功能入口](./README.md)、[User Stories](./user-stories.md)、[功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md)、[功能进度](./progress.md) |
+
+## 1. 背景
+
+GoodBuddy 的部分 SKILL 通过 Node.js 或 Python 脚本生成成果，部分本机 stdio MCP 也以
+`node`、`npm`、`npx`、`python` 或 `python -m` 启动。当前安装包没有向这些能力提供统一
+解释器，用户是否成功取决于系统 PATH 和预装软件。
+
+普通用户不应为了使用一个 SKILL 或 MCP 手工安装开发环境。专业用户已有项目 Node、
+Python、虚拟环境或 Conda 环境时，也不能被 GoodBuddy 静默替换。
+
+## 2. 产品目标
+
+1. 全新设备无需预装 Node.js 即可运行普通 JavaScript SKILL 和 Node.js stdio MCP。
+2. 用户可在 GoodBuddy 内按需安装 Python，并运行 Python SKILL 和 stdio MCP。
+3. 专业用户可以选择检测到的解释器或指定其他可执行文件。
+4. 设置始终展示实际来源、版本、路径、工具状态和能力依赖状态。
+5. 本机工具环境不修改系统环境，也不传播到远程主机。
+6. 保持 Ask/Execute、Runtime、MCP、取消和进程清理的现有边界。
+
+## 3. 核心决策
+
+### 3.1 每种工具只有两个来源
+
+- **GoodBuddy 托管（推荐）**
+- **自定义环境**
+
+不提供“自动选择”。“系统安装”和“指定路径”合并为“自定义环境”，因为两者最终都是
+用户明确选择的外部可执行文件，区别只在发现方式。
+
+### 3.2 配套命令跟随解释器
+
+- Node.js 保证 `node`、`npm`、`npx` 来自同一来源。
+- Python 保证 `python`、`python3`、`pip` 来自同一来源；`pip` 实际绑定当前 Python。
+- 首期不托管 `uv`、`uvx`、Conda、Poetry、pyenv 或 nvm。
+
+### 3.3 工具就绪不等于能力依赖就绪
+
+解释器通过诊断后标记“工具环境已就绪”。只有 SKILL 或 MCP 的实际入口及所需第三方包
+通过验证后，才能标记“能力依赖已就绪”。GoodBuddy 首期不自动扫描和安装任意能力依赖。
+
+## 4. 功能范围
+
+### 4.1 包含
+
+- 本机 OpenCode、Continue、DeepSeek Harness 加载的 SKILL。
+- Main 或本机 Runtime 启动的 stdio MCP。
+- 托管 Node.js、npm、npx。
+- 按需下载安装的托管 Python 3、pip、venv。
+- 系统解释器探测、自定义文件选择和真实诊断。
+- 工具来源、版本、路径、安装、删除、更新和错误状态。
+- 新启动本机 Runtime 和 MCP 的 PATH 注入。
+
+### 4.2 不包含
+
+- SSH Host 的 PATH、Agent、固定 Node、Runtime、SKILL 或 MCP。
+- HTTP/SSE MCP 服务端环境。
+- 普通助手工作栏终端的 Shell 环境。
+- 通用语言版本管理器。
+- 每项目或每 SKILL 的解释器覆盖。
+- 自动合并或求解多个 `requirements.txt`、`package.json`。
+- 自动执行任意第三方安装脚本。
+- 修改系统 PATH、注册表或 Shell Profile。
+- 无条件把完整 Python 打入桌面安装包。
+- 首期导入托管 Python 离线包；完全离线用户可选择已有的自定义 Python。
+
+## 5. 功能需求
+
+### FR-1 Node.js 托管环境
+
+- 安装 GoodBuddy 后托管 Node.js 即可用，不需要额外下载。
+- 实际版本通过运行命令诊断，不仅根据 Electron 版本推断。
+- `node`、`npm`、`npx` 必须来自同一托管组合。
+- Electron Node 原生扩展兼容限制必须可见。
+
+### FR-2 Python 托管环境
+
+- Python 未安装时展示安装入口，不把完整 Python 放入所有桌面安装包。
+- 下载复用“关于与更新”的官方 GitHub/镜像来源。
+- 展示下载、校验、安装、取消、可更新、删除和失败状态。
+- 下载失败保留已验证旧安装。
+
+### FR-3 自定义环境
+
+- 探测 PATH 和常见安装位置中的有效候选。
+- 候选同时展示版本和规范化绝对路径。
+- 用户可以选择未被探测到的可执行文件。
+- 保存前执行真实诊断。
+- 已保存路径失效时保持用户选择并报错，不静默回退。
+
+### FR-4 SKILL 接入
+
+- SKILL 可以稳定调用 `node`、`npm`、`npx`、`python`、`python3` 和 `pip`。
+- SKILL 不需要知道解释器真实安装目录。
+- 缺失解释器或第三方依赖时返回准确错误。
+- 工具环境不自动安装 SKILL 声明的依赖。
+
+### FR-5 stdio MCP 接入
+
+- 裸命令通过当前工具环境解析。
+- `env node`、`env python3` 形式的脚本使用当前工具环境。
+- MCP 中配置的绝对命令路径保持原样，不被替换。
+- Python 和 Node.js MCP 均使用与 SKILL 相同的来源。
+
+### FR-6 状态与诊断
+
+- 分别显示“工具环境状态”和“能力依赖状态”。
+- Node 诊断覆盖 Node、npm、npx、标准库和子进程。
+- Python 诊断覆盖 Python 3、架构、标准库、SSL、pip 和 venv。
+- 诊断使用临时目录并在结束后清理。
+
+### FR-7 生效范围
+
+- 设置只对新启动的本机 Runtime 和 stdio MCP 生效。
+- 已运行进程不被中途替换环境。
+- 不影响普通终端、系统环境和远程主机。
+
+### FR-8 升级兼容
+
+- 全新用户默认选择 GoodBuddy 托管。
+- 已发布版本升级时，将当前有效系统解释器一次性固化为自定义绝对路径。
+- 没有有效系统解释器时迁移到托管来源。
+- 后续系统 PATH 变化不自动改变选择。
+
+### FR-9 生命周期
+
+- 安装、诊断、Runtime 和 MCP 子进程支持取消和应用退出清理。
+- 删除只作用于 GoodBuddy-owned 目录。
+- 不删除系统解释器、自定义环境、用户工作区或远程文件。
+
+### FR-10 权限模式
+
+- Ask 不因解释器可用而获得额外命令或写入权限。
+- Execute 继续使用当前本机账号的完整授权。
+- 不为工具环境增加第二套批准流程。
+
+## 6. 产品验收
+
+- 无系统 Node.js 时，托管 Node 可以真实执行 JavaScript SKILL 和 stdio MCP。
+- 无系统 Python 时，用户可安装托管 Python 并真实执行现有 Python SKILL 和 MCP。
+- Node、npm、npx 来源一致；Python、python3、pip 来源一致。
+- 用户可明确选择并锁定自定义解释器。
+- 自定义路径失效不触发静默切换。
+- 工具就绪与能力依赖就绪不会混为同一状态。
+- 本机 Skills、MCP 和工具环境不会应用于远程主机。
+- 中英文界面、键盘操作、焦点和状态反馈符合统一设计系统。
+- 全量测试、类型检查、Lint 和生产构建通过。

docs/features/local-tool-environment/progress.md

@@ -0,0 +1,89 @@
+# 本机工具环境功能进度
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档类型 | 功能进度 |
+| 状态 | 计划中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-01 |
+| 关联入口 | [本机工具环境](./README.md) |
+
+## 当前结论
+
+功能尚未进入源码实施。产品范围、User Stories、功能逻辑评估、UI 一致性和技术方案已经
+形成首版文档。
+
+## 已完成
+
+- [x] 明确功能只服务本机 SKILL 和本机 stdio MCP。
+- [x] 明确远程 Host 不接收本机工具环境、SKILL 或 MCP。
+- [x] 将来源收敛为“GoodBuddy 托管”和“自定义环境”。
+- [x] 明确 Node、npm、npx 同源，Python、python3、pip 同源。
+- [x] 区分工具环境就绪与能力依赖就绪。
+- [x] 定义现有用户解释器的一次性兼容迁移。
+- [x] 定义状态机、来源和命令决策表、失败恢复与生效时机。
+- [x] 定义设置页结构、状态、文案和无障碍要求。
+- [x] 定义 Main 服务、shim、探测、诊断、PATH 注入和 Python 生命周期。
+- [x] 远程主机设置副标题已说明本机 Skills 和 MCP 不作用于远程主机。
+
+## 待实施
+
+### 阶段 1：设置、探测和界面
+
+- [ ] Shared 设置、状态、操作和 IPC schema。
+- [ ] 旧用户迁移。
+- [ ] Node/Python 候选探测。
+- [ ] 完整环境诊断。
+- [ ] Agent Runtime 设置中的本机工具环境卡片。
+
+### 阶段 2：托管 Node
+
+- [ ] 提取并复用 DSH Node shim。
+- [ ] 提供 node/npm/npx。
+- [ ] 注入 OpenCode、Continue、DeepSeek Harness。
+- [ ] 注入 Main 和 Runtime 的 stdio MCP。
+- [ ] 安装包真实 Node、npm、npx smoke。
+
+### 阶段 3：托管 Python
+
+- [ ] 选型并锁定六平台 CPython 工件。
+- [ ] 完成许可证和下载目录。
+- [ ] 下载、校验、安装、更新、取消和删除。
+- [ ] 提供 python/python3/pip。
+- [ ] Python 标准库、SSL、pip、venv 真实诊断。
+
+### 阶段 4：端到端验收
+
+- [ ] Node SKILL 实际成果。
+- [ ] Python SKILL 实际成果。
+- [ ] Node stdio MCP 实际调用。
+- [ ] Python stdio MCP 实际调用。
+- [ ] 自定义 Node/Python 路径。
+- [ ] Ask/Execute、Runtime 重建、取消、退出。
+- [ ] 六平台 CI、许可证和生产构建。
+
+## 当前阻塞项
+
+- 尚未完成六平台可再分发 CPython 工件选型，因此托管 Python 版本、体积和下载摘要未锁定。
+- 尚未开始源码接入。
+
+## 已验证证据
+
+### 2026-08-31
+
+- 确认安装包携带 Electron Node 能力和锁定 npm CLI，但未向通用 SKILL/MCP 提供 `node`
+  命令。
+- 确认 DSH 插件安装器已有 `ELECTRON_RUN_AS_NODE=1` shim，可作为复用基线。
+- 确认远程 Agent ACP Session 使用空 MCP Server 列表，本机 SKILL/MCP 不进入远程路径。
+- 远程主机设置文案聚焦测试通过：`80/80`。
+- 当时完整类型检查通过；完整测试和 Lint 被并行开发中的 `RightAssistantSidebar` 变更
+  阻塞，不作为本功能实现验证。
+
+## 进度维护要求
+
+- 只有真实源码和生产路径完成后才能勾选对应实施项。
+- 测试失败时保留未完成状态并记录失败原因。
+- 每次更新记录日期、实际命令、结果和外部阻塞。
+- 不在本文件复制未来设计，需求变化回写 PRD/UI/技术设计。

docs/features/local-tool-environment/technical-design.md

@@ -0,0 +1,284 @@
+# 本机工具环境技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 计划 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-01 |
+| 关联 PRD | [本机工具环境 PRD](./prd.md) |
+| 功能逻辑 | [本机工具环境功能逻辑设计](./logic-design.md) |
+| 相关架构 | [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md)、[SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md) |
+
+## 1. 当前基线
+
+GoodBuddy 已具备：
+
+- Electron 内置 Node Runtime。
+- 安装包中的锁定 npm CLI。
+- DSH 插件安装器使用的 `process.execPath + ELECTRON_RUN_AS_NODE=1` shim。
+- OpenCode、Continue、DeepSeek Harness 的独立本机进程环境入口。
+- SKILL 按 Runtime 目标分配和暂存。
+- Main 和 Runtime 的 stdio MCP 启动链路。
+- Runtime 可执行文件探测、版本读取和自定义路径模式。
+- 下载、摘要校验、进度、取消和暂存清理模式。
+
+当前缺少统一工具来源设置、通用 PATH 注入和托管 Python。
+
+## 2. 设置契约
+
+```ts
+type LocalToolEnvironmentSelection =
+  | { source: 'managed' }
+  | { source: 'custom'; executablePath: string }
+
+type LocalToolEnvironmentSettings = {
+  node: LocalToolEnvironmentSelection
+  python: LocalToolEnvironmentSelection
+}
+```
+
+只持久化用户意图。不持久化候选列表、版本、PATH、shim 路径、诊断结果或可重新读取的托管
+包元数据。
+
+### 2.1 兼容迁移
+
+- 全新用户默认 `managed`。
+- 旧设置没有该字段时，Main 按升级前 PATH 分别解析有效 Node 和 Python 3。
+- 有效候选写成 `custom + 规范化绝对路径`。
+- 没有有效候选时写成 `managed`。
+- 迁移只执行一次，后续 PATH 变化不改变选择。
+
+## 3. Main 服务
+
+新增一个 `LocalToolEnvironmentService`，负责：
+
+- 设置读取和保存。
+- Node/Python 候选探测。
+- 自定义解释器诊断。
+- 当前工具组合解析。
+- 受管工具 bin 创建。
+- 托管 Python 安装、更新、删除。
+- 有界状态和进度发布。
+- 应用退出时取消安装并清理本次暂存。
+
+不为每项职责增加持久 Manager、注册表或恢复状态机。失败安装删除暂存，下次重新执行。
+
+## 4. 解析结果
+
+```ts
+type ResolvedLocalToolEnvironment = {
+  binDirectory: string
+  node?: {
+    executablePath: string
+    npmCliPath?: string
+    npxCliPath?: string
+  }
+  python?: {
+    executablePath: string
+  }
+}
+```
+
+工具 bin：
+
+| 平台 | 命令 |
+| --- | --- |
+| Windows | `node.cmd`、`npm.cmd`、`npx.cmd`、`python.cmd`、`python3.cmd`、`pip.cmd` |
+| macOS/Linux | `node`、`npm`、`npx`、`python`、`python3`、`pip` |
+
+shim 使用绝对路径。`pip` 固定调用 `<python> -m pip`，避免解释器错配。
+
+## 5. Node.js 托管环境
+
+托管 Node shim：
+
+```text
+ELECTRON_RUN_AS_NODE=1 <process.execPath> <arguments...>
+```
+
+约束：
+
+- 复用 DSH 已有的平台转义实现。
+- `ELECTRON_RUN_AS_NODE` 不写入 Main 全局环境。
+- npm/npx 使用安装包中同一锁定 npm 发行版的 CLI。
+- npm 子进程范围设置 `npm_execpath` 和 `npm_node_execpath`。
+- 自定义 Node 只使用与其配套且验证成功的 npm/npx，不混入 GoodBuddy npm。
+- 普通 JavaScript 和 Node 内置模块属于支持路径。
+- 普通 Node 原生扩展可能受 Electron ABI 影响，不承诺兼容。
+
+## 6. Python 托管环境
+
+### 6.1 包
+
+- 使用包含 pip、venv、SSL 和标准库的固定 CPython 独立发行包。
+- 每个平台/架构锁定一个版本。
+- 目录包含版本、平台、架构、来源、字节数、SHA-256 和许可证。
+- 下载复用当前官方 GitHub/镜像来源，不增加来源设置。
+- 安装包不无条件携带完整 Python。
+
+具体发行包和版本必须在实现前完成六平台工件、许可证、维护状态和 pip/venv 可用性核验。
+
+### 6.2 安装
+
+```text
+读取固定目录
+→ 下载到 GoodBuddy-owned 暂存
+→ 校验大小和 SHA-256
+→ 解压到新版本目录
+→ 运行完整环境诊断
+→ 发布为当前托管 Python
+→ 删除暂存
+```
+
+失败保留已验证旧安装。删除只作用于 GoodBuddy-owned Python 目录。
+
+### 6.3 包依赖
+
+首期提供解释器和 pip，不自动扫描或安装任意 `requirements.txt`。第三方包由 SKILL/MCP
+安装流程或用户明确命令准备。出现可复现的包冲突后，再评估能力级虚拟环境。
+
+## 7. 自定义环境探测
+
+### 7.1 Node
+
+候选来源：
+
+- 筛选后的 PATH。
+- Windows/macOS/Linux 常见安装目录。
+- 已保存路径。
+
+每个候选运行分离参数的 `--version`，确认普通文件、可执行、成功退出和可解析版本，并按
+真实路径去重。
+
+### 7.2 Python
+
+- Windows 探测 `python.exe`。
+- macOS/Linux 优先 `python3`，其次为明确的 Python 3 `python`。
+- 拒绝未安装的 Windows Store App Execution Alias。
+- 诊断 Python 3、版本、架构和解释器绝对路径。
+
+单候选和总探测具有超时、输出上限、取消和进程树清理。
+
+## 8. 完整诊断
+
+### 8.1 Node
+
+- `node --version`
+- 加载标准库
+- 启动最小子进程
+- `npm --version`
+- `npx --version`
+- npm/npx 实际 Node 来源一致
+
+### 8.2 Python
+
+- Python 3、版本和架构
+- 标准库导入
+- SSL/证书模块
+- `python -m pip --version`
+- 在临时目录创建最小 venv
+
+诊断不联网，使用 GoodBuddy-owned 临时目录并清理。
+
+## 9. 环境注入
+
+新启动的以下本机进程将工具 bin 放到现有筛选 PATH 前面：
+
+- OpenCode Server。
+- Continue Utility Process。
+- DeepSeek Harness Utility Process。
+- Main 启动的 stdio MCP。
+- Runtime 启动的 stdio MCP。
+
+不注入 Main 全局环境、Renderer、普通终端、SSH 请求、Agent 或远程 Runtime。
+
+设置变化后，有活动请求的 Runtime 保持启动时快照；空闲 Runtime 在下次使用前使用既有
+重建入口。已运行 MCP 在正常关闭、重连或显式测试后使用新环境，不增加热切换协议。
+
+## 10. SKILL 与 MCP
+
+SKILL 稳定调用命令名，不接收真实安装路径。
+
+stdio MCP：
+
+- 裸 `node`、`npm`、`npx`、`python`、`python3`、`pip` 使用工具 bin。
+- `env node`/`env python3` 脚本通过 PATH 使用同一来源。
+- 绝对 command 保持原样。
+- HTTP/SSE 不受影响。
+- 工具环境不自动安装 MCP 第三方依赖。
+
+## 11. Renderer 状态与 IPC
+
+Renderer 接收：
+
+- 当前选择。
+- 当前实际来源、版本、路径。
+- 有界候选列表。
+- 托管安装状态、版本、占用空间。
+- 工具诊断分项结果。
+- 安装进度和脱敏错误。
+
+Renderer 不能提交 PATH、环境变量、下载 URL、摘要、安装目录、shim 内容或任意命令参数。
+所有 IPC 输入使用共享 Zod schema，Main 重新验证路径和解释器。
+
+## 12. 权限与远程边界
+
+- Ask/Execute 语义不变。
+- 不新增解释器批准流程。
+- 不上传 shim、Python、pip 包或自定义路径。
+- 不修改 Host PATH。
+- 不把本机 SKILL 或 stdio MCP 传给远程 ACP Session。
+- 远程 Agent 固定 Node 继续只服务 Agent、模型桥和签名 Runtime。
+
+## 13. 实施顺序
+
+### 阶段 1：契约、迁移、探测和 UI
+
+- Shared schema、设置迁移、IPC。
+- Node/Python 候选探测和完整诊断。
+- 设置卡片和状态。
+
+### 阶段 2：托管 Node 与执行链路
+
+- 提取 DSH shim。
+- 增加 node/npm/npx。
+- 注入本机 Runtime 和 stdio MCP。
+
+### 阶段 3：托管 Python
+
+- 锁定六平台工件。
+- 下载、校验、安装、更新、取消、删除。
+- 增加 python/python3/pip。
+
+### 阶段 4：真实端到端验收
+
+- Node SKILL 与 MCP。
+- Python SKILL 与 MCP。
+- 自定义解释器。
+- Ask/Execute、重建、取消和退出。
+- 六平台打包和许可证。
+
+这些阶段是开发顺序，不是可长期发布的残缺功能。合并能力前完成普通用户和专业用户的完整
+生产路径。
+
+## 14. 验证
+
+单元测试覆盖设置迁移、探测、版本解析、shim 转义、PATH 顺序、失效路径、下载摘要和暂存
+清理。
+
+集成测试覆盖安装包 Electron Node、npm/npx、托管 Python、三个本机 Runtime 和两类 stdio
+MCP 的实际进程路径。
+
+项目验证：
+
+```text
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+生产资源通过六平台原生 CI 打包验证。若后续改动触及 Agent、远程协议或远程 Runtime，
+再按远程架构文档执行共享 Linux x64 Host 验证。

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

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

docs/features/local-tool-environment/user-stories.md

@@ -0,0 +1,264 @@
+# 本机工具环境 User Stories
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 计划 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-01 |
+| 关联 PRD | [本机工具环境 PRD](./prd.md) |
+| 关联逻辑 | [本机工具环境功能逻辑设计](./logic-design.md) |
+
+## 1. 角色
+
+### 1.1 普通用户
+
+希望直接使用文档、演示文稿或数据处理 SKILL，不理解 Node.js、Python、pip 或 PATH。
+
+### 1.2 MCP 使用者
+
+希望配置一个本机工具服务，并由 GoodBuddy 解决其基础解释器启动问题。
+
+### 1.3 专业开发者
+
+已有明确的 Node、Python、虚拟环境或 Conda 环境，希望控制实际版本和绝对路径。
+
+### 1.4 内网与离线用户
+
+无法稳定访问公网，需要使用选定镜像或离线准备环境，同时不向远程 Host 传播本机配置。
+
+## 2. Epic A：普通用户无需预装环境
+
+### US-A0 首次看到准确默认状态
+
+作为普通用户，我希望第一次打开设置时看到 GoodBuddy 已提供什么、还需要安装什么，以免
+误以为所有工具都已就绪。
+
+验收：
+
+- 全新安装默认选择 GoodBuddy 托管 Node 和 Python
+- 托管 Node 立即执行真实诊断并显示版本
+- 未安装的托管 Python 显示“尚未安装”和安装入口
+- 检测到的系统解释器只作为自定义候选，不改变默认来源
+- 页面持续说明只对新启动的本机 Runtime 和 stdio MCP 生效
+
+### US-A1 直接使用托管 Node
+
+作为普通用户，我希望安装 GoodBuddy 后即可使用 Node.js SKILL，以免单独安装 Node.js。
+
+验收：
+
+- Given 系统 PATH 没有 Node.js
+- When 本机 Execute 请求运行普通 JavaScript SKILL
+- Then `node` 使用 GoodBuddy 托管来源
+- And `npm`、`npx` 与该 Node 来源一致
+- And 设置显示实际 Node 版本
+
+### US-A2 按需安装 Python
+
+作为普通用户，我希望在设置中安装 Python，以便运行 Python SKILL 而不离开 GoodBuddy。
+
+验收：
+
+- Given 系统没有 Python 且托管 Python 未安装
+- When 用户点击安装
+- Then 页面显示下载、校验和安装进度
+- And 成功后真实 Python、pip、venv 诊断通过
+- And 失败不会留下半安装目录
+
+### US-A3 看懂缺失依赖
+
+作为普通用户，我希望区分“没有 Python”和“缺少 python-pptx”，以便采取正确修复操作。
+
+验收：
+
+- 工具解释器不可用时显示工具环境错误
+- 解释器可用但能力包缺失时显示能力依赖错误
+- 页面不把 `python --version` 成功描述为 SKILL 已完全可用
+- 错误保留原任务和可执行的下一步
+
+### US-A4 看懂部分就绪
+
+作为用户，我希望知道解释器可用但配套命令损坏，以免把所有失败都理解为没有安装环境。
+
+验收：
+
+- Node 可用而 npm/npx 失败时显示“部分可用”和具体失败项
+- Python 可用而 pip、venv 或 SSL 失败时显示“部分可用”和具体失败项
+- 不依赖失败项的能力仍可通过实际诊断标记就绪
+- 没有能力专属诊断时显示“依赖未验证”，不推断为就绪
+
+## 3. Epic B：本机 MCP 使用一致环境
+
+### US-B1 启动 Python MCP
+
+作为 MCP 使用者，我希望 `python -m my_mcp_server` 使用设置中的 Python，以免配置第二套
+解释器。
+
+验收：
+
+- 裸 `python`、`python3` 和 `pip` 解析到当前选择
+- Main 直连工具链和本机 Runtime 使用相同来源
+- 绝对命令路径不被替换
+- MCP 自身包缺失时准确报告依赖错误
+
+### US-B2 启动 Node.js MCP
+
+作为 MCP 使用者，我希望 `node server.js` 或 `npx package` 使用同一 Node 组合。
+
+验收：
+
+- `node`、`npm`、`npx` 来源一致
+- npm lifecycle 子进程使用当前 Node
+- 取消或关闭应用后没有遗留 MCP 进程
+
+### US-B3 保持网络 MCP 不变
+
+作为 MCP 使用者，我希望 HTTP/SSE MCP 不受本机解释器设置影响。
+
+验收：
+
+- HTTP/SSE 配置不显示本机解释器要求
+- GoodBuddy 不管理远端 MCP 服务端依赖
+- 切换本机工具环境不重建 HTTP/SSE 服务
+
+## 4. Epic C：专业用户明确控制环境
+
+### US-C1 使用检测到的系统解释器
+
+作为专业开发者，我希望从版本和绝对路径列表中选择解释器，以便使用已有工具链。
+
+验收：
+
+- 候选经过真实版本和架构诊断
+- 相同真实路径不重复显示
+- 保存后状态显示实际生效来源
+- PATH 后续变化不会自动替换选择
+
+### US-C2 指定项目虚拟环境
+
+作为专业开发者，我希望选择未被自动发现的 Python，以便使用自己的 venv 或 Conda 环境。
+
+验收：
+
+- 文件选择由 Main 管理
+- 保存前验证 Python 3、版本和架构
+- GoodBuddy 不安装、升级或删除该环境
+- 路径失效时不静默回退
+
+### US-C3 返回托管环境
+
+作为专业开发者，我希望随时切回 GoodBuddy 托管环境，以便恢复标准组合。
+
+验收：
+
+- 切换前显示新启动进程才生效
+- 新 Runtime 和 stdio MCP 使用托管来源
+- 已运行进程不中途换环境
+
+### US-C4 明确设置何时生效
+
+作为专业开发者，我希望知道环境切换何时影响进程，以免一个运行中的任务突然换解释器。
+
+验收：
+
+- 保存前后都说明只对新启动进程生效
+- 有活动请求的 Runtime 保持启动时环境
+- 空闲 Runtime 在下一次使用前按现有入口重建
+- 已启动 stdio MCP 在关闭、重连或显式测试后使用新环境
+- 活动记录不根据最新设置改写历史解释器来源
+
+## 5. Epic D：范围和生命周期可理解
+
+### US-D1 不影响远程主机
+
+作为远程项目用户，我希望清楚知道本机环境不会上传到 Host，以免错误预期远程脚本可用。
+
+验收：
+
+- 本机工具环境页显示范围说明
+- 远程主机设置页显示本机 Skills 和 MCP 不适用
+- Host PATH、Agent 包和 Runtime 包不包含本机选择
+
+### US-D2 删除托管 Python
+
+作为用户，我希望删除不再使用的托管 Python，以便释放磁盘空间。
+
+验收：
+
+- 删除前说明受影响的本机 SKILL 和 MCP
+- 只删除 GoodBuddy-owned Python 目录
+- 不删除系统、自定义或工作区文件
+- 使用中的进程先按现有生命周期停止
+
+### US-D3 升级后保持既有解释器
+
+作为现有用户，我希望升级 GoodBuddy 后已有脚本仍使用原来的系统解释器。
+
+验收：
+
+- 首次迁移把有效系统解释器保存为自定义绝对路径
+- 无有效解释器时才选择托管来源
+- 迁移结果只写一次
+
+### US-D4 取消 Python 安装
+
+作为用户，我希望可以取消耗时的 Python 安装，并在之后重试。
+
+验收：
+
+- 下载、校验、安装和候选诊断阶段都响应取消
+- 取消后清理本次暂存
+- 取消不发布未验证候选
+- 页面回到操作前的未安装状态或健康旧版本
+- 取消不显示为安装失败
+
+### US-D5 安全更新托管 Python
+
+作为用户，我希望更新托管 Python 失败时仍能使用旧版本，以免现有能力全部中断。
+
+验收：
+
+- 下载和验证候选期间旧版继续服务已有进程
+- 应用更新前说明需要停止哪些本机 Runtime/MCP
+- 用户确认后才通过现有生命周期停止相关进程
+- 无法停止时不替换当前版本
+- 候选完整诊断成功后才发布
+- 更新失败继续使用健康旧版本
+
+### US-D6 安装解释器不扩大 Ask 权限
+
+作为 Ask 用户，我希望安装 Node/Python 后仍保持原有只读边界，以免环境准备改变授权范围。
+
+验收：
+
+- 工具环境不新增 Runtime 工具
+- Ask 是否允许命令仍由当前 Runtime 边界决定
+- Ask 中禁止的写入和执行不会因解释器存在而放行
+- Execute 继续使用用户已授权的本机账号权限
+
+## 6. Epic E：受限网络与离线行为明确
+
+### US-E1 通过所选官方来源安装 Python
+
+作为内网用户，我希望托管 Python 使用“关于与更新”中选择的官方来源，以便符合当前网络
+条件。
+
+验收：
+
+- Python 安装复用当前 GitHub/镜像来源
+- 来源不可达时显示来源和准确失败原因
+- 同一次安装不静默切换到另一来源
+- 失败保留健康旧版本或未安装状态
+
+### US-E2 完全离线时使用已有环境
+
+作为完全离线用户，我希望清楚知道首期可用路径，以免等待一个无法完成的下载。
+
+验收：
+
+- 托管 Node 安装后可离线使用
+- 托管 Python 未缓存且来源不可达时明确说明无法下载
+- 首期不展示未实现的 Python 离线导入入口
+- 用户可以选择设备上已经离线安装的自定义 Python