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

工具执行环境功能进度

文档信息

项目	内容
文档类型	功能进度
状态	已实施，六平台打包验收已通过；真实 Skills/MCP 与自定义环境验收待完成
版本	0.6
日期	2026-09-03
关联入口	工具执行环境

当前结论

本机工具执行环境的生产链路已经进入源码。“能力与工具”现在显示 Skills、MCP、 工具执行环境 三个真实 Tab；Main 统一解析托管或自定义 Node/Python，并把不可变 PATH 快照应用到新启动的本机 Runtime 与 stdio MCP。Windows x64 已完成真实托管 Node 和原生 地址托管 Python 安装验证。

六个 OSS 镜像对象已发布并公开回读验证。托管 Python 继续按需下载，Desktop 发行包不额外 带入许可证文件。标准六平台打包任务已改用目标架构原生 Runner，并在打包前执行托管 Python 的真实安装、SSL、pip 和 venv 探针。不可变的 v0.12.0 尝试已通过 Windows 与 macOS， 但 Linux x64/ARM64 在发布前暴露 TAR 大小写冲突误判；v0.12.1 在同步 Agent 发布时 于原生打包前取消。已发布的 v0.12.2 随后通过全部六个原生打包任务及其托管 Python 安装、SSL、pip 和 venv 探针。

已完成

设置、迁移和界面

• Shared 严格设置、候选、诊断、进度、IPC 和 Preload 契约。
• Application Settings v10；全新用户默认托管环境和原生地址。
• v1-v9 分别执行真实 Node/Python 3 探测的一次性迁移；无有效候选时选择托管环境。
• 用户/系统 PATH、活动 venv/Conda、CONDA_ENVS_PATH、Conda/pyenv/nvm 和常见安装 位置，以及已保存自定义路径候选的规范化、去重、版本及架构诊断。
• 自定义解释器保存前真实验证；无效新选择不持久化，已保存失效路径不回退。
• “自定义环境”始终可进入；不隐式采用首个候选，取消文件选择不改设置，验证错误在 对应工具卡内显示。
• “能力与工具”统一入口及三个水平 Tab，MCP 原内层页签保持不变。
• 工具下载源、Node.js、Python、候选、诊断、安装进度、取消和删除界面。
• 工具卡只展示真实工具诊断；未接入具体能力证据前不显示固定的能力依赖占位状态。
• 使用 PageTabs、应用通知、就地操作错误、删除确认和具名进度条。

托管 Node 与进程注入

• 使用 Electron-as-Node 提供 node，使用同一 Node 和打包 CLI 提供 npm、npx。
• 自定义 Node 只使用同安装位置且验证成功的 npm/npx，不与托管 CLI 混用。
• 每次配置生成不可变 shim 目录；已有进程继续持有原 PATH，新进程读取新快照。
• OpenCode、Continue、DeepSeek Harness 和本机通用/精选 stdio MCP 接收工具 PATH。
• 工具 PATH 不修改 process.env，不进入普通终端或远程 Host。
• 解释器探针使用过滤后的环境，不接收模型凭据、GoodBuddy 或 Factory 内部变量。

托管 Python

• 锁定 CPython 3.13.15 的 Windows/macOS/Linux x64/ARM64 六平台目录、大小和 SHA-256。
• 用户选择的原生地址或 OSS 镜像在任务开始时冻结，同一次任务不回退。
• HTTPS、重定向 Host、大小、SHA-256、取消和部分文件清理。
• NuGet ZIP 与 Astral TAR 的 payload 限定、路径穿越防护、展开上限和安全链接处理。
• 归档路径唯一性遵循目标文件系统；Linux 保留大小写不同的合法 TAR 条目，所有目标 仍拒绝完全重复路径，Windows/macOS 仍拒绝大小写冲突。
• GoodBuddy-owned 暂存安装、发布、失败清理、更新保留和删除。
• python、python3、pip 同源，pip 固定使用所选 Python 的 -m pip。
• 发布前真实验证 Python 3.13.15、架构、标准库、SSL、pip，并创建和执行临时 venv。
• 取消恢复原状态且不显示为安装失败；退出时取消并等待安装清理。

待完成验收

• 发布六个平台/架构的字节完全相同 OSS 镜像对象并公开回读校验。
• 确认托管 Python 保持按需下载，Desktop 发行包不额外带入许可证文件。
• Windows ARM64、macOS x64/ARM64 原生 CI 安装、SSL、pip、venv 探针。
• Linux x64/ARM64 原生 CI 安装、SSL、pip、venv 探针；v0.12.2 标签工作流已通过。
• 最低 Windows/macOS/glibc 支持矩阵和 Windows NuGet 签名核验。
• 真实 JavaScript/Python SKILL 成果及 Node/Python stdio MCP 调用。
• 自定义 Node/Python 在产品 UI 中的真实选择和任务执行。
• 更新或删除托管 Python 时，使用现有本机 Runtime/MCP 生命周期协调受影响进程。

当前阻塞项

• 当前机器只能原生验证 Windows x64。其余五个平台必须由对应原生 CI 执行，不能用本机 mock 代替。

已验证证据

2026-09-27 MCP 编辑器遮挡修复

真实 Electron App 经“设置 → 能力与工具 → MCP → 自定义 MCP → 添加 Server”复现。 修复前编辑器层级为 70、设置为 130，输入框中心命中设置页签容器；名称输入框虽已 获得焦点，父设置仍为 inert=false。添加和编辑现接入共享 Modal 层级与背景隔离， 遮罩关闭保留触发按钮焦点。没有修改 Runtime、Agent 或 MCP 传输实现。

overlay-layering.electron.test.ts 新增真实 App 用例，复用生产 preload、IPC、 CapabilityService、设置存储与 BrowserService。已通过的场景：

场景	验证结果
无浏览器，浅色 1280 × 900、深色 960 × 420	添加/编辑鼠标命中、文字输入、父设置隔离、Tab/Shift+Tab 循环通过
右侧原生浏览器打开，浅色 1280 × 900、深色 1280 × 420	设置及 MCP 期间原生视图隐藏；设置关闭后恢复相同 webContents ID、URL 和页面内标记，无重建或刷新
关闭与焦点	X、取消、Escape、遮罩、保存成功返回原触发按钮；关闭子层保留设置，关闭设置返回其入口
持久化	四次 UI 保存经生产 IPC 写入临时配置，新建 CapabilityService 重读四条记录；编辑重开回显名称

原有 overlay Electron 用例也通过，继续覆盖解析菜单、二级结果、通知、应用中心、本机 推理监控和原生 dialog。回归禁用 Windows 原生窗口遮挡节流，避免其他桌面窗口暂停 测试的帧等待；未改变产品窗口选项。浏览器页面使用本地 HTTP 服务；MCP 测试配置保存为 停用状态，不启动外部 MCP 命令。真实模型调用 0 次。

证据范围为 Windows x64 开发态 Electron。无关启动服务使用 harness 替身，未配置的 向量模型与 Runtime 原生能力服务会返回不可用；未验收这些服务、外部 MCP 连接、远程 Agent 或其他操作系统。短窗口从已打开设置调整尺寸；宽度跨越工作栏自动收起阈值的路径 不作为浏览器保持打开的验收场景。

最终 focused 集合为 6 文件、215 项通过；npm run typecheck、npm run lint 和 git diff --check 通过。本轮未运行全仓 npm test 或打包。验证命令：

npx vitest run tests/overlay-layering.electron.test.ts src/renderer/src/McpSettingsSection.test.tsx src/renderer/src/SettingsPanel.test.tsx src/renderer/src/FloatingPortal.test.tsx src/renderer/src/WorkspacePrimitives.test.tsx src/renderer/src/RightAssistantSidebar.resize.test.tsx
npm run typecheck
npm run lint
git diff --check

调试期间的失败记录：旧代码在真实鼠标命中断言失败；接入共享焦点后补修遮罩关闭的默认 焦点转移。harness 的帧等待曾受 Windows 窗口遮挡节流影响，浏览器导航曾在创建或输入 状态提交前触发；分别关闭测试进程的遮挡节流，并等待可用控件与实际页面加载后验证。 这些失败未计为产品验收通过。中文文档扫描无阻断项；本节的并列项是实测关闭入口和覆盖 组件清单，保留以便核对。

2026-09-03 v0.12.0 失败标签恢复

• 不可变标签工作流 33704483505 的 Windows x64/ARM64 与 macOS x64/ARM64 托管 Python 安装、SSL、pip、venv 探针和打包成功；Linux x64/ARM64 在实际官方 Astral TAR 中发现 share/terminfo/2/2621A 与 share/terminfo/2/2621a 后被大小写无关去重误判为冲突。
• 最终 GitHub/OSS 发布任务跳过，GitHub 未创建 v0.12.0 Release，Latest 仍为 v0.11.14；首次恢复版本按不可变标签规则提升为 0.12.1。
• 提取器改为按工件目标平台判断路径唯一性，并继续保留完全重复路径、路径穿越、安全链接 和展开上限校验。锁定的 Linux x64 上游工件重新下载后大小与 SHA-256 匹配目录，并确认 冲突项确为大小写不同的两个合法 symlink；临时审计工件已清理。
• Release Notes 校验通过；工具环境、工作流和 Release Notes 聚焦测试 40/40 通过， live 安装项按本地发布规则未启用。最终 npm test 为 3478 通过、51 跳过， typecheck 与 lint 通过；未运行本地 production build、package 或安装探针。
• v0.12.1 的 main validators 与 production bundle 已通过，但标签工作流在同步新 Agent 版本前主动取消；未进入六目标原生矩阵，未创建 GitHub Release 或切换 OSS latest。Desktop 恢复版本继续提升为 0.12.2。
• 0.12.2 协调候选的 Release Notes 校验通过；Agent/Desktop 发布链路聚焦测试 106/106 通过、1 项平台用例跳过。最终 npm test 为 3478 通过、51 跳过， typecheck 与 lint 通过；仍未运行本地 production build、package 或安装探针。
• v0.12.2 标签工作流 33714902060 随后成功完成 source validation、production bundle、Windows/macOS/Linux x64/arm64 六个原生 package job 及各自托管 Python 安装探针，并于 2026-09-03 发布非 draft、非 prerelease 的正式 Release。

2026-09-02 完整实现

• 发布准备确认不把按需下载的托管 Python 许可证文件加入 Desktop extraResources、解包 校验或 Portable ZIP 必需文件，避免该额外资源改变现有编译和打包路径。

• 六平台打包矩阵在 npm ci 后先断言 Runner 架构，再执行 GOODBUDDY_RUN_LIVE_TOOL_ENVIRONMENT=1 的托管 Python 安装探针；Windows arm64 改用 windows-11-vs2026-arm 原生 Runner。发行资源与目录聚焦测试 47/47 通过。

• npm run typecheck 通过。

• npm run lint 通过。

• npm run build 通过，Main、Preload 和 Renderer 生产 bundle 成功。

• 工具环境聚焦测试通过：契约、设置迁移、解析/shim、服务、下载、解压、安装、IPC、 Preload、Runtime/MCP 注入、Renderer 和发行资源校验。

• Windows x64 真实托管 Node：Electron Node 24.18.0、npm 11.19.0、npx 11.19.0。

• GOODBUDDY_RUN_LIVE_TOOL_ENVIRONMENT=1 真实下载官方 NuGet、校验摘要、解压、安装并 验证 CPython 3.13.15、SSL、pip 和 venv，1/1 通过；临时安装已清理。

• 隔离 Electron 生产 bundle 自动化确认三个 Tab 均可见；“诊断全部”显示托管 Node 24.18.0、npm/npx 11.19.0。隔离进程和用户数据已清理。

• 第一次全量测试发现 3 个确定性夹具/兼容失败，修复后聚焦复跑 25/25 通过。第二次暴露 2 个 App.test.tsx 设置导航时序问题，修正为按可访问名称点击并等待设置中心。

• 最终 npm test 通过：3465 通过、51 跳过；完整 App.test.tsx 为 157/157 通过。

• 使用本机受控 Aliyun 凭据将六个已验证上游工件原样上传到 goodbuddy/tool-artifacts/python/3.13.15/<sha256>/<filename>，总计 142,251,693 字节。随后从目录中的六个公开 OSS URL 全量下载，逐个验证字节数和 SHA-256，全部一致。

• 修复无候选时禁用“自定义环境”的死路交互，并扩展 venv/Conda/常见安装位置探测； 聚焦 Main/Renderer/Settings 测试 95/95 通过，最终 npm test 为 3477 通过、 51 跳过，类型检查、功能文件定向 Lint 和生产构建通过。仓库全量 Lint 当前被并行 App.tsx 的两个 React Compiler memoization 错误阻塞，与工具执行环境文件无关。

• 隔离 Electron 实机确认“自定义环境”始终可进入，展开和刷新不会保存来源；在 64 项以上 PATH 的机器上优先发现活动 <user>\miniconda3\python.exe，真实诊断为 Python 3.13.13 · amd64，刷新后持久设置仍为 managed。

2026-09-02 菜单阶段

• 完成“能力与工具”一级菜单及 Skills/MCP Tab，并修复可滚动 Flex 布局将页签压缩为零 高度的问题；加入 flex: 0 0 auto 回归约束。

进度维护要求

• 只有真实源码和生产路径完成后才能勾选对应实施项。
• 测试失败时保留未完成状态并记录失败原因。
• 每次更新记录日期、实际命令、结果和外部阻塞。
• 不在本文件复制未来设计，需求变化回写 PRD/UI/技术设计。