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.
285 lines
8.3 KiB
Markdown
285 lines
8.3 KiB
Markdown
# 本机工具环境技术设计
|
||
|
||
## 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 状态 | 计划 |
|
||
| 版本 | 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 验证。
|