# Windows x64 内置工具链

## 固定来源与布局

`resources/runtimes/manifest.json` 固定 Node 24.22.0 LTS（npm/npx 11.19.1）、CPython 3.14.8（pip 26.2.1）和 PortableGit 2.56.0.windows.2（含 Git Bash）。Python 选择仍受维护的 3.14 稳定分支，不追随刚发布的 3.15。

安装后位于 `resources/runtimes/win32-x64/{node,python,git}`，不在 asar 内。Node 使用 `node.exe`、`npm.cmd`、`npx.cmd`；Python 使用 `python.exe -m pip`，命令行便利入口为 `Scripts/pip.cmd` / `pip3.cmd`；Git 使用 `cmd/git.exe`、`bin/bash.exe`（保留完整 MSYS2 依赖树）。不安装系统工具、不修改注册表或系统/用户 PATH、不做全局包安装。

## 可重现准备与打包

开发机先安装项目依赖（现有项目的 electron-vite / vite peer 范围冲突需使用该项目已有兼容策略，例如 `npm ci --legacy-peer-deps`）。然后：

```sh
npm run runtimes:prepare
npm run runtimes:verify
npm run dist:installer
```

`dist` 和 `dist:installer` 自动准备所有工具链并限定 x64；electron-builder `beforePack` 再验所有文件、缺失/损坏/非 Windows x64 均拒绝打包。直接运行 builder 不会自动联网，需先准备。源码仓库不保存大二进制，下载缓存位于 `.tmp/runtime-downloads/`（可预置同名官方包离线构建），提取结果被 Git 忽略。下载失败或哈希不符不退回系统工具、不生成空壳包。

Node 使用官方 SHASUMS256.txt；Git 使用官方 GitHub release asset SHA256；Python 使用 NuGet 官方不可变 catalog SHA512，来源 URL 随锁文件保存。每次先验证压缩包，再由锁定的构建依赖 `7zip-bin` 提取；不会运行 PortableGit 自解压 EXE。提取后的每个文件（相对路径、SHA256，确定顺序）组成 tree hash，必须匹配已审查 manifest。更新版本需重新审查来源/hash/完整提取内容并更新 tree hash；脚本不会自动改锁。

保留所有上游许可证，见随包 THIRD-PARTY-NOTICES.md；公开分发前还需完成 GPL 对应源码交付/书面提供等适用义务审查。

## Python / pip / venv

采用 Python 官方 NuGet 完整运行时，而非不支持常规 pip/venv 的 embeddable 包。实包包含 `Lib/venv`、`Lib/ensurepip`、ensurepip 内置 pip wheel 和已安装的 pip。pip.cmd 使用相对目录调用 python.exe，迁移安装目录后仍定位自身 Python，无硬编码构建机路径。调用 pip 不需要启动时联网 bootstrap。建议项目执行：

```bat
"<runtime>\python\python.exe" -m venv ".venv"
".venv\Scripts\python.exe" -m pip install <package>
```

虚拟环境是用户工作区数据，不能作为可搬移运行时打包；移动 YCode 或跨版本更新后应重建依赖其路径的 venv。缺少匹配 wheel 的原生扩展可能仍需要外部编译工具；本包不含 MSVC/完整开发 SDK，不承诺任意 Python/npm 包离线可装。基础运行时应视为只读，包依赖安装到项目 venv/项目 node_modules 或应用私有路径，而非应用安装目录。

## 验证边界

Linux 构建机可确认三份真实官方包下载、发布哈希、完整解包树哈希、PE/MZ 文件头、关键路径、版本元数据和许可证。不能把这些检查宣称为 Windows 执行成功。发布前仍须在干净 Windows x64 上验证 Node/npm/npx、Python/pip/创建 venv、Git/Bash，含空格/中文路径、开关禁用、升级和无系统工具情形。不能只验 `--version` 后声称所有包管理/沙盒链路已完成。

### PortableGit 提取后处理

实际 2.56 包使用 `ucrt64` 而非旧 `mingw64`。准备脚本按上游 `13-copy-dlls.post` 的语义，将 ucrt64/bin DLL 复制至 ucrt64/libexec/git-core（非依赖硬链接），保留 dlls-copied 标记与 dev/shm、dev/mqueue 目录。上游 post-install 脚本移入 `ycode-upstream-post-install` 审计目录，避免 Bash login 首次执行时修改安装资源。不会从构建机复制 hosts/protocols/services/networks；不会伪造 Windows 的 /etc/mtab MSYS 符号链接。这些非核心 POSIX 系统集成没有宣称完成，需按实际用途在 Windows 验证。

### 原生离线 smoke

Windows x64 运行 `npm run runtimes:smoke`，或 `node scripts/smoke-runtime-bundle.mjs "安装目录/resources/runtimes/win32-x64"`。仅在临时目录创建 venv/Git repo，无网络、全局安装或凭据操作；验证所有命令版本、venv 自带 pip、Git init 和 Bash printf，并复核资源无变化。Linux 明确输出 SKIP，不代表通过。跨目录搬移、Bash login、Git HTTPS 和实际包下载仍需单独原生测试。

## 安全中心开关与使用边界

设置 → 安全中心仅新增“内置运行时”卡片，包括总开关和 Node.js、Python、Git Bash 独立开关。偏好存入应用 userData/private-runtimes.json，原子写入、串行更新；文件损坏或不可读不会静默恢复为启用。关总开关保留单项选择。

仅对之后启动的终端、Claude 内核和 MCP stdio 子进程注入工具路径；现有进程不强制重启。关闭是停用随包工具，不是禁止系统工具或增加权限隔离。MCP 保留最小继承环境，终端继续过滤凭据；不更改发送、排队、审批或回合策略。

npm 的 prefix/cache 与 Python 的 PYTHONUSERBASE/pip cache 位于 userData/runtime-data 下，仅在相应内置工具启用时注入；不设置 PYTHONHOME、PIP_USER 或 PIP_TARGET，以免破坏项目 venv。Python 项目优先使用 venv；独立用户安装可显式使用 `python -m pip install --user <package>`。PYTHONUSERBASE 本身不保证所有裸 `pip install` 都采用 --user，安装目录可写时 pip 仍可能写入基础运行时，因此不要直接往随包环境安装依赖。

## 开发回归入口

```sh
node scripts/private-runtimes-regression.cjs
node --test scripts/runtime-bundle.test.mjs
# jsdom 不属于产品依赖；设置为测试环境已有模块的绝对路径
YCODE_TEST_DOM_MODULE=/path/to/jsdom node scripts/test-private-runtimes-dom.mjs
```

这些离线测试分别覆盖环境/持久化、打包防护和设置界面交互；不能替代 Windows 二进制执行与安装包验收。