尧图网页设计 
DeepChat Managed ToolchainsNode 与 uv 运行时的按需托管与统一解析架构解析【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat导读DeepChat 引入了一套名为Managed Toolchains托管工具链的运行时管理体系用于解决 Node.js 与 uv 两种语言运行时在 MCP、ACP、Skill、OCR 等功能间的解析口径不一致问题。本文以 docs/architecture/managed-toolchains/spec.md 为骨架结合仓库中src/main/toolchains/的实际实现完整讲解工具链的 Source 模型、首次运行迁移、托管下载与原子激活、OCR 版本约束、Settings 界面、CLI Electron 宿主以及打包终态。读完本文你将掌握 DeepChat 如何做到每种运行时只有一个解析器、一个持久化来源、一次托管下载并理解其安全、隐私与失败处理设计。背景为什么需要 Managed Toolchains在引入托管工具链之前DeepChat 通过 scripts/install-runtime.mjs 和 electron-builder.yml 把 Node、uv、RTK 直接复制进安装包各消费方各自查询RuntimeHelper对缺少运行时的行为各执一词导致行为不一致消费方缺少随包运行时时的行为MCP stdio整棵树缺失 → 退回原始命令 / 系统 PATH半安装 → 派生一个不存在的路径ACP npx/uvx退回原始命令 / 静默走 PATHSkillauto先系统、后随包两者都失败才抛错OCR / CLI随包 Node 缺失时直接失败fail closed此外bunRuntimePath只是nodeRuntimePath的别名Bun 从 v0.2.4 起被随包分发、在 v0.4.9 被移除今天并不安装。GitHub issue #2153 的核心诉求是停止在应用产物中携带语言运行时把它们当作可选、独立管理的安装物。本 RFC 的取舍是uv 保留为随包种子移除一个小二进制再重新下载成本高于保留官方 Node 改为按需托管安装RTK、OCR 模型/native、CUA、DuckDB VSS 维持各自的生命周期不纳入本体系。目标与明确非目标规范定义了 8 条目标让ToolchainService成为 Node 与 uv 的唯一解析器为每种工具链持久化一个显式来源bundled | managed | system | custom | unconfigured一次性首次运行迁移之后绝不静默切换来源最多下载一个官方 Node 发行版OCR 校验过的 pin存放于{userData}/toolchains/uv 保留为随包种子同时允许可选的更新版托管 uvDeepChat CLI 用 Electron 托管ELECTRON_RUN_AS_NODE1既不用官方 Node 也不用托管 Node删除假的 Bun 别名与无用的useBuiltinRuntimei18n一旦托管路径、Settings UI、CLI 宿主就绪安装包不再携带 Node/npm/npx/corepack。同时明确排除Bun 下载器、完整 CPythonSkill 继续用 uv 或显式系统 Python、mise/asdf/nvm 等版本管理器垫层、把 RTK/OCR/CUA/DuckDB VSS 迁移进本生命周期、启动即自动下载、静默切换来源、用 Electron 的 NodeABI 145跑 OCR 原生模块或npxMCP、维护两个托管 Node 版本以及就地修补损坏的随包内容先提供托管安装最后才重装应用。统一所有权ToolchainService 是唯一 Node/uv 解析器规范的核心架构是单一所有权模型Settings / MCP / ACP / Skill / OCR │ ▼ ToolchainService ← only Node/uv resolver │ ├── bundled probe (app.asar.unpacked/runtime/{node,uv}) ├── managed tree ({userData}/toolchains/{node,uv}/version) ├── system PATH └── custom path在源码中ToolchainService类位于 src/main/toolchains/service.ts它以单例形式被 src/main/toolchains/index.ts 暴露并通过 src/main/app/composition.ts 注入到应用组合根。它提供的核心能力包括resolve(kind, options)按持久化选择解析出ResolvedNodeToolchain/ResolvedUvToolchain每个解析结果会被冻结Object.freeze并放入内存缓存rewriteCommand(command, args)把node/npm/npx/corepack/uv/uvx改写为解析出的真实可执行文件路径prependResolvedToEnv(env)把解析出的 bin 目录前置到子进程 PATHinstall/repair/revert/cancelInstall/setSource/clearSource/getStatus。值得注意的边界RuntimeHelper仍然保留 RTK 探测与小型 PATH/展开工具但 Node 与 uv 的命令改写必须绕开它。CLI 不解析工具链——CLI 宿主始终是打包的 Electron 二进制 ELECTRON_RUN_AS_NODE1Electron 41.10.4 恰好对齐 Node v24.18.0 只是巧合不是不变式。从调用链看src/main/mcp/mcpClient.ts、src/main/agent/acp/runtime/acpProcessManager.ts、src/main/skill/skillExecutionService.ts 与 OCR 相关模块都经由ToolchainService解析运行时印证了唯一解析器的落地。五种来源模型Sources来源含义bundled随应用分发的只读文件uv 的默认值仅当安装包仍携带 Node 时对 Node 有效managedDeepChat 拥有的、下载到userData的版本通过state.json指针原子激活而非符号链接system用户 PATH 上已有的二进制绝不产生第二次 DeepChat 下载custom用户自选的绝对可执行文件或工具链根目录unconfigured诚实的空状态不派生下次功能需要时再询问关键设计约束是auto不是一种来源。来源类型定义在 src/shared/types/toolchains.ts 的TOOLCHAIN_SOURCES中解析失败的原因也在此文件中以联合类型定义unconfigured | missing | incomplete | version_mismatch | abi_mismatch | path_invalid | unsupported_platform | transient。首次运行迁移与绝不静默切换当{userData}/toolchains/state.json缺失时首次运行迁移记录机器上已有什么Node随包树完整 → 持久化bundled否则系统存在node→ 持久化system否则unconfigureduvuv与uvx都存在 → 持久化bundled否则 PATH 上两者都在 →system否则unconfigured。这是一次性记录不是每次解析时的回退链。写入之后来源只会在用户或 Repair/Revert操作时改变唯一的例外是首次运行的unconfigured无explicit标记在登录 shell PATH 就绪后每个 userData 最多一次被提升为system——即使提升发生在 PATH 尚未就绪时的重启之后。bundled → system的记忆化绝不允许发生。清除来源会持久化{ source: unconfigured, explicit: true }该选择跨重启存活且永不被提升。在实现中ensureFirstRunPersisted()与promoteUnconfiguredFromDetectedSystem()见 src/main/toolchains/service.ts精确实现了这一逻辑src/main/toolchains/stateStore.ts 负责state.json的读取、解析与隔离损坏状态。升级场景也有明确定义当安装包移除 Node 后若持久化来源是bundled且随包树已消失保留bundled并以missing失败不自动切到 systemSettings 横幅提供托管安装或显式 system/custom 选择。完整性检查Completeness种类Bundled / system / customManagedNodenodenpmnpxnodenpmnpxcorepackuvuvuvxuvuvx半安装如缺少 npm/npx的状态是incomplete不会退回 PATH。在实现中probeNodeSelection对managed来源调用probeNodeRoot(..., true)对bundled调用probeNodeRoot(..., false)区分是否要求 corepack 存在resolveNode对incomplete直接抛出ToolchainResolutionError。purpose 是版本约束不是第二份下载purpose不触发第二份下载OCR要求解析出的官方 Node 满足24.18.0 25且NODE_MODULE_VERSION 137MCP / ACP / Node Skills可以使用用户显式选择的系统 Node若系统 Node 不满足 OCR 约束OCR 会要求托管 pin——DeepChat 仍然只下载一个 Node 版本。握手约束helper 的nodeVersion必须等于已激活的解析版本managed 用state.json指针bundled/system/custom 用探测到的版本且该版本必须在范围内不要在 Node 可以独立更新后再去和烘焙死的runtime-versions.json字符串比对。源码中src/main/toolchains/catalog.ts 定义了NODE_MODULE_VERSION 137、NODE_COMPAT_MIN_INCLUSIVE 24.18.0、NODE_COMPAT_MAX_EXCLUSIVE 25.0.0与isNodeVersionInCompatRange()src/main/toolchains/service.ts 的resolveNode在purpose ocr时依次校验版本范围version_mismatch与 ABIabi_mismatch并通过spawnSync(executable, [-p, JSON.stringify({v:process.version,m:Number(process.versions.modules)})])探测真实版本与模块 ABI。目录布局与原子激活{userData}/toolchains/ state.json node/version/ # official distro root uv/version/ download/kind-version/ # in-progress, never the active pointer激活流程是写临时文件 fsync 重命名state.json被中断的下载永远不会替换正在工作的版本。这在 src/main/toolchains/stateStore.ts 的saveToolchainState中实现写入state.json.tmp、fsyncSync、再renameSync到正式路径。目录规划函数集中在 src/main/toolchains/layout.tsmanagedKindRoot、downloadStagingDir、bundledKindRoot等。安装时先解压到 staging 的extract目录用probeNodeRoot/probeUvRoot校验完整性后经replaceDirectory原子替换到 managed 目录最后才setSource(kind, { source: managed, version })。下载器代理、校验与单飞锁下载复用主进程代理栈ProxyConfig/ undici 全局 dispatcher并增加 sha256、断点续传与每个工件的单飞锁。镜像选择采用 npm 测速的模式custom cache 并发探测 fallback但不用它的 URL 列表也不采用失败即写npmmirror缓存的行为失败的探测只留在内存里只有成功的探测才被缓存见 src/main/toolchains/downloader.ts 的successfulProbeCache与selectDownloadUrl官方源是内存回退。GitHub 镜像可选且默认空不做 ipinfo。隐私模式下不进行后台探测locale/timezone 只能用于给探测列表排序。下载阶段的本地化错误原因类型化dns | timeout | http | proxy | checksum_mismatch | disk | cancelled | activation_failed | unsupported_platform下载器细节同样值得展开见 src/main/toolchains/downloader.ts探测用Range: bytes0-0只取头接受 200 或 206下载支持Range续传416 时清空重来60 秒停滞看门狗STALL_TIMEOUT_MS150ms 节流的进度回调先以.partial后缀落盘sha256File校验通过后才rename为正式文件校验失败即删除并抛checksum_mismatch。托管 pin 的工件清单官方 URL、文件名、sha256由 src/main/toolchains/catalog.ts 维护Node 固定v24.18.0darwin/linux/win32 × arm64/x64 共 6 个归档uv 固定0.9.18同样 6 个平台组合resolveToolchainArtifact对不支持的 platform/arch 抛unsupported_platform。安装阶段src/main/toolchains/service.ts 的installManaged依次经历probing → downloading → verifying → extracting → activating五个阶段进度通过ToolchainInstallProgress事件上报。Settings 界面与用户路径入口Settings → Toolchains位于 Tools 分组下。交互原则每种工具链一个来源选择器检测到系统二进制时高亮提示零下载Install / Repair / Revert 是三个独立的显式操作自动连接路径上缺运行时一个服务端错误 一条聚合横幅绝不弹出 N 个对话框只有用户主动发起的路径才显示三选一选择器。Bun 保留为 schema 桩以备未来 catalog 需要该槽位但 UI 隐藏、无下载器。渲染进程通过类型化路由与主进程通信路由在 src/main/toolchains/routes.ts 中注册toolchains.getStatustoolchains.setSourcetoolchains.installtoolchains.cancelInstalltoolchains.repairtoolchains.reverttoolchains.pickCustom进度通过 DeepChat 事件传递而不是 settings 快照 key。选择持久化在{userData}/toolchains/state.json而非app-settings.json指针与下载树共享同一目录、同一原子写者。Skill 策略映射Skill 偏好解析方式autoToolchainService持久化来源builtin仅 bundled不完整即失败system仅 system缺失即失败Skillauto不再优先系统高于随包——首次运行迁移 显式 Settings 选择取代了旧的隐式链。Python Skill 通过ToolchainService解析 uvSkillauto在该持久化 uv 来源上 fail-close绝不回退到系统 CPython显式 Skillsystem仍可使用系统 CPython。DeepChat 不下载 CPython。打包终态与 CLI Electron 宿主安装包含app、uvuvx 种子、OCR 模型/native、RTK、DuckDB VSS、CLI 脚本、skills、官方插件。安装包不包含Node/npm/npx/corepack、Bun、完整 CPython。install-runtime.mjs继续安装 uv和 RTKNode 安装变成打包期 no-op。打包期对任何残留的 Node 种子与每个托管工件必须校验完整性集合npm/npx/corepack而不只是node本身。Windows OCR smoke 防火墙规则当前指向随包node.exe翻转后必须指向解析出的官方 Node。CLI 由打包的 Electron 以ELECTRON_RUN_AS_NODE1托管——即使托管 Node 已安装CLI 宿主仍是 Electron。这在 docs/architecture/managed-toolchains/plan.md 的第 4 切片CLI Electron host中有完整落地步骤deepchat.mjs由 Electron 托管launcher 与build-cli.mjs不再依赖runtime/node下次 GUI 启动时刷新 launcher。兼容性、不变式与失败行为兼容性已有完整随包 Node 的用户迁移到bundled来源并继续工作直到后续版本把 Node 移出工件因随包 Node 缺失而依赖系统 PATH 的用户在系统存在node时迁移到systemuseBuiltinRuntime保持删除、死 i18n key 清理bunRuntimePath删除、调用方改用 Nodeissue #2153 的 AC 行工件不含 uv是已接受的偏差——uv 保留为随包种子 托管覆盖需要在提 PR 时在 issue 上重新协商。十大不变式节选关键一个解析器每种 kind 一个持久化来源、解析绝不走到下一个来源一个托管 Node pin、catalog 永不列出第二个 Node 版本官方 Node ABI 137 供 OCRElectron Node 只跑 DeepChat 自己的 JSCLI 宿主是 Electron被中断的下载绝不成为活动指针失败的镜像探测不写磁盘缓存Repair 与 Revert 严格区分uv 的 Revert 回到随包种子随包损坏不在原地修补隐私模式不后台探测镜像。失败行为unconfigured/missing/incomplete/version_mismatch/abi_mismatch/path_invalid/unsupported_platform均为类型化错误自动连接路径汇聚为一条横幅并让功能闲置用户发起的安装暴露类型化下载原因OCR 握手不匹配时销毁 helper绝不回退到 Electron Node。实现中mergeMissingNotices会按严重程度transient unconfigured/missing incomplete version_mismatch abi_mismatch聚合缺失通知。安全与隐私、性能安全/隐私custom 路径必须展开后为绝对路径拒绝 URL 中的凭据激活前校验 sha256绝不执行半写下载跟随活动ProxyConfig不另起代理栈隐私模式无后台网络发现不记录可能含用户名的完整 custom 路径遵循既有 logger 约定。性能解析结果内存缓存来源变更/激活/显式刷新时失效热路径MCP/ACP 改写、Skill 派生只是文件系统元数据 缓存不在每次连接时跑node -v每个可执行路径最多派生一次版本/ABI 探测然后缓存瞬态失败有 2 秒 TTL 的inspectTransientUntil每个下载 key 单飞PATH 扫描上限 256 条与 Skill 一致。验收标准Acceptance CriteriaMCP、ACP、Skill、OCR 只通过ToolchainService解析 Node/uv首次运行持久化后只有 Settings以及 Repair/Revert能改变后续解析来源唯一例外是一次性首次运行unconfigured → system登录 shell PATH 到达时用户选择的unconfigured永不被提升失败或被中断的 Node 下载保留上一个可用版本为活动版本OCR helper 握手接受已激活的官方 pin拒绝 Electron Node 与范围外版本安装包移除 Node 后 CLI 仍可运行Electron 宿主打包翻转后安装包尺寸不再包含 Node 发行版不下载、不携带任何 Bun 二进制uv 保留在工件中Revert 恢复该种子隐私模式在用户主动安装前不做任何工具链探测死代码bunRuntimePath与useBuiltinRuntime副本彻底移除。被否决的替代方案方案否决理由mise需要额外分发的工具、隐式 shim、我们不想要的版本管理器 UX直接下载官方 Node 发行版隐式 PATH 回退链生产环境的痛点静默换源用 Electron Node 跑 OCR / npxABI 145 vs 137无 npm/npx/corepack两个托管 Node 版本OCR 与 MCP 共享一个 pin系统 Node 是用户的二进制不是第二次下载恢复 Bun纯历史包袱v0.4.9 已移除schema 桩、UI 隐藏、无下载器现在就移除工件中的 uv移除种子再重下更糟且解耦 CVE 的覆盖仍需托管路径保留种子 托管覆盖落地路线Plandocs/architecture/managed-toolchains/plan.md 把实现切分为 6 个可独立评审、每步后应用仍可用的切片解析器与显式来源引入ToolchainService、持久化state.json、首次迁移、MCP/ACP/Skill/OCR 全量改写、删除 Bun 别名与死 i18n、OCR 握手改为解析出的官方 Node 版本下载器 / catalog / 打包期完整性单 pin Node catalog、官方发行版下载器、managed 激活、Repair/Revert、打包期校验 npm/npx/corepackSettings UI 与缺运行时横幅来源选择器、系统二进制高亮、安装进度、聚合横幅CLI Electron 宿主ELECTRON_RUN_AS_NODE1托管deepchat.mjs停止分发 Node从安装流程移除 Node升级用户看到missing 横幅Windows OCR smoke 指向解析出的官方 Node审查、验证与清理全量对照 spec 审查保留迁移、resolve-never-switches、完整性、原子激活、OCR purpose 约束与下载恢复的持久化测试。质量门禁为pnpm run format、pnpm run i18n、pnpm run lint、pnpm run typecheck加最小相关 Vitest 套件测试策略实现优先——切片 1 之后补迁移/解析/完整性/改写契约测试切片 2 之后补激活与中断下载测试UI 与打包切片依赖既有门禁加一个小的 status-route 测试且不添加复述私有控制流的实现耦合 mock。结语Managed Toolchains 的整套设计围绕三个朴素原则展开单一解析器、单一持久化来源、单一托管 pin。配合原子激活、类型化失败、隐私默认关闭与打包期校验完整性集合等细节DeepChat 得以在不牺牲用户既有环境的前提下逐步把 Node 移出安装包同时为 OCR 的 ABI 约束和 MCP/ACP/Skill 的通用解析需求提供一条清晰的托管路径。对于希望深入源码的读者建议从 src/main/toolchains/service.ts解析与安装主逻辑、src/main/toolchains/catalog.ts版本 pin 与工件清单、src/main/toolchains/downloader.ts校验下载和 src/shared/types/toolchains.ts类型契约四个文件开始阅读。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepChat Managed Toolchains：Node 与 uv 运行时的按需托管与统一解析架构解析
DeepChat Managed ToolchainsNode 与 uv 运行时的按需托管与统一解析架构解析【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat导读DeepChat 引入了一套名为Managed Toolchains托管工具链的运行时管理体系用于解决 Node.js 与 uv 两种语言运行时在 MCP、ACP、Skill、OCR 等功能间的解析口径不一致问题。本文以 docs/architecture/managed-toolchains/spec.md 为骨架结合仓库中src/main/toolchains/的实际实现完整讲解工具链的 Source 模型、首次运行迁移、托管下载与原子激活、OCR 版本约束、Settings 界面、CLI Electron 宿主以及打包终态。读完本文你将掌握 DeepChat 如何做到每种运行时只有一个解析器、一个持久化来源、一次托管下载并理解其安全、隐私与失败处理设计。背景为什么需要 Managed Toolchains在引入托管工具链之前DeepChat 通过 scripts/install-runtime.mjs 和 electron-builder.yml 把 Node、uv、RTK 直接复制进安装包各消费方各自查询RuntimeHelper对缺少运行时的行为各执一词导致行为不一致消费方缺少随包运行时时的行为MCP stdio整棵树缺失 → 退回原始命令 / 系统 PATH半安装 → 派生一个不存在的路径ACP npx/uvx退回原始命令 / 静默走 PATHSkillauto先系统、后随包两者都失败才抛错OCR / CLI随包 Node 缺失时直接失败fail closed此外bunRuntimePath只是nodeRuntimePath的别名Bun 从 v0.2.4 起被随包分发、在 v0.4.9 被移除今天并不安装。GitHub issue #2153 的核心诉求是停止在应用产物中携带语言运行时把它们当作可选、独立管理的安装物。本 RFC 的取舍是uv 保留为随包种子移除一个小二进制再重新下载成本高于保留官方 Node 改为按需托管安装RTK、OCR 模型/native、CUA、DuckDB VSS 维持各自的生命周期不纳入本体系。目标与明确非目标规范定义了 8 条目标让ToolchainService成为 Node 与 uv 的唯一解析器为每种工具链持久化一个显式来源bundled | managed | system | custom | unconfigured一次性首次运行迁移之后绝不静默切换来源最多下载一个官方 Node 发行版OCR 校验过的 pin存放于{userData}/toolchains/uv 保留为随包种子同时允许可选的更新版托管 uvDeepChat CLI 用 Electron 托管ELECTRON_RUN_AS_NODE1既不用官方 Node 也不用托管 Node删除假的 Bun 别名与无用的useBuiltinRuntimei18n一旦托管路径、Settings UI、CLI 宿主就绪安装包不再携带 Node/npm/npx/corepack。同时明确排除Bun 下载器、完整 CPythonSkill 继续用 uv 或显式系统 Python、mise/asdf/nvm 等版本管理器垫层、把 RTK/OCR/CUA/DuckDB VSS 迁移进本生命周期、启动即自动下载、静默切换来源、用 Electron 的 NodeABI 145跑 OCR 原生模块或npxMCP、维护两个托管 Node 版本以及就地修补损坏的随包内容先提供托管安装最后才重装应用。统一所有权ToolchainService 是唯一 Node/uv 解析器规范的核心架构是单一所有权模型Settings / MCP / ACP / Skill / OCR │ ▼ ToolchainService ← only Node/uv resolver │ ├── bundled probe (app.asar.unpacked/runtime/{node,uv}) ├── managed tree ({userData}/toolchains/{node,uv}/version) ├── system PATH └── custom path在源码中ToolchainService类位于 src/main/toolchains/service.ts它以单例形式被 src/main/toolchains/index.ts 暴露并通过 src/main/app/composition.ts 注入到应用组合根。它提供的核心能力包括resolve(kind, options)按持久化选择解析出ResolvedNodeToolchain/ResolvedUvToolchain每个解析结果会被冻结Object.freeze并放入内存缓存rewriteCommand(command, args)把node/npm/npx/corepack/uv/uvx改写为解析出的真实可执行文件路径prependResolvedToEnv(env)把解析出的 bin 目录前置到子进程 PATHinstall/repair/revert/cancelInstall/setSource/clearSource/getStatus。值得注意的边界RuntimeHelper仍然保留 RTK 探测与小型 PATH/展开工具但 Node 与 uv 的命令改写必须绕开它。CLI 不解析工具链——CLI 宿主始终是打包的 Electron 二进制 ELECTRON_RUN_AS_NODE1Electron 41.10.4 恰好对齐 Node v24.18.0 只是巧合不是不变式。从调用链看src/main/mcp/mcpClient.ts、src/main/agent/acp/runtime/acpProcessManager.ts、src/main/skill/skillExecutionService.ts 与 OCR 相关模块都经由ToolchainService解析运行时印证了唯一解析器的落地。五种来源模型Sources来源含义bundled随应用分发的只读文件uv 的默认值仅当安装包仍携带 Node 时对 Node 有效managedDeepChat 拥有的、下载到userData的版本通过state.json指针原子激活而非符号链接system用户 PATH 上已有的二进制绝不产生第二次 DeepChat 下载custom用户自选的绝对可执行文件或工具链根目录unconfigured诚实的空状态不派生下次功能需要时再询问关键设计约束是auto不是一种来源。来源类型定义在 src/shared/types/toolchains.ts 的TOOLCHAIN_SOURCES中解析失败的原因也在此文件中以联合类型定义unconfigured | missing | incomplete | version_mismatch | abi_mismatch | path_invalid | unsupported_platform | transient。首次运行迁移与绝不静默切换当{userData}/toolchains/state.json缺失时首次运行迁移记录机器上已有什么Node随包树完整 → 持久化bundled否则系统存在node→ 持久化system否则unconfigureduvuv与uvx都存在 → 持久化bundled否则 PATH 上两者都在 →system否则unconfigured。这是一次性记录不是每次解析时的回退链。写入之后来源只会在用户或 Repair/Revert操作时改变唯一的例外是首次运行的unconfigured无explicit标记在登录 shell PATH 就绪后每个 userData 最多一次被提升为system——即使提升发生在 PATH 尚未就绪时的重启之后。bundled → system的记忆化绝不允许发生。清除来源会持久化{ source: unconfigured, explicit: true }该选择跨重启存活且永不被提升。在实现中ensureFirstRunPersisted()与promoteUnconfiguredFromDetectedSystem()见 src/main/toolchains/service.ts精确实现了这一逻辑src/main/toolchains/stateStore.ts 负责state.json的读取、解析与隔离损坏状态。升级场景也有明确定义当安装包移除 Node 后若持久化来源是bundled且随包树已消失保留bundled并以missing失败不自动切到 systemSettings 横幅提供托管安装或显式 system/custom 选择。完整性检查Completeness种类Bundled / system / customManagedNodenodenpmnpxnodenpmnpxcorepackuvuvuvxuvuvx半安装如缺少 npm/npx的状态是incomplete不会退回 PATH。在实现中probeNodeSelection对managed来源调用probeNodeRoot(..., true)对bundled调用probeNodeRoot(..., false)区分是否要求 corepack 存在resolveNode对incomplete直接抛出ToolchainResolutionError。purpose 是版本约束不是第二份下载purpose不触发第二份下载OCR要求解析出的官方 Node 满足24.18.0 25且NODE_MODULE_VERSION 137MCP / ACP / Node Skills可以使用用户显式选择的系统 Node若系统 Node 不满足 OCR 约束OCR 会要求托管 pin——DeepChat 仍然只下载一个 Node 版本。握手约束helper 的nodeVersion必须等于已激活的解析版本managed 用state.json指针bundled/system/custom 用探测到的版本且该版本必须在范围内不要在 Node 可以独立更新后再去和烘焙死的runtime-versions.json字符串比对。源码中src/main/toolchains/catalog.ts 定义了NODE_MODULE_VERSION 137、NODE_COMPAT_MIN_INCLUSIVE 24.18.0、NODE_COMPAT_MAX_EXCLUSIVE 25.0.0与isNodeVersionInCompatRange()src/main/toolchains/service.ts 的resolveNode在purpose ocr时依次校验版本范围version_mismatch与 ABIabi_mismatch并通过spawnSync(executable, [-p, JSON.stringify({v:process.version,m:Number(process.versions.modules)})])探测真实版本与模块 ABI。目录布局与原子激活{userData}/toolchains/ state.json node/version/ # official distro root uv/version/ download/kind-version/ # in-progress, never the active pointer激活流程是写临时文件 fsync 重命名state.json被中断的下载永远不会替换正在工作的版本。这在 src/main/toolchains/stateStore.ts 的saveToolchainState中实现写入state.json.tmp、fsyncSync、再renameSync到正式路径。目录规划函数集中在 src/main/toolchains/layout.tsmanagedKindRoot、downloadStagingDir、bundledKindRoot等。安装时先解压到 staging 的extract目录用probeNodeRoot/probeUvRoot校验完整性后经replaceDirectory原子替换到 managed 目录最后才setSource(kind, { source: managed, version })。下载器代理、校验与单飞锁下载复用主进程代理栈ProxyConfig/ undici 全局 dispatcher并增加 sha256、断点续传与每个工件的单飞锁。镜像选择采用 npm 测速的模式custom cache 并发探测 fallback但不用它的 URL 列表也不采用失败即写npmmirror缓存的行为失败的探测只留在内存里只有成功的探测才被缓存见 src/main/toolchains/downloader.ts 的successfulProbeCache与selectDownloadUrl官方源是内存回退。GitHub 镜像可选且默认空不做 ipinfo。隐私模式下不进行后台探测locale/timezone 只能用于给探测列表排序。下载阶段的本地化错误原因类型化dns | timeout | http | proxy | checksum_mismatch | disk | cancelled | activation_failed | unsupported_platform下载器细节同样值得展开见 src/main/toolchains/downloader.ts探测用Range: bytes0-0只取头接受 200 或 206下载支持Range续传416 时清空重来60 秒停滞看门狗STALL_TIMEOUT_MS150ms 节流的进度回调先以.partial后缀落盘sha256File校验通过后才rename为正式文件校验失败即删除并抛checksum_mismatch。托管 pin 的工件清单官方 URL、文件名、sha256由 src/main/toolchains/catalog.ts 维护Node 固定v24.18.0darwin/linux/win32 × arm64/x64 共 6 个归档uv 固定0.9.18同样 6 个平台组合resolveToolchainArtifact对不支持的 platform/arch 抛unsupported_platform。安装阶段src/main/toolchains/service.ts 的installManaged依次经历probing → downloading → verifying → extracting → activating五个阶段进度通过ToolchainInstallProgress事件上报。Settings 界面与用户路径入口Settings → Toolchains位于 Tools 分组下。交互原则每种工具链一个来源选择器检测到系统二进制时高亮提示零下载Install / Repair / Revert 是三个独立的显式操作自动连接路径上缺运行时一个服务端错误 一条聚合横幅绝不弹出 N 个对话框只有用户主动发起的路径才显示三选一选择器。Bun 保留为 schema 桩以备未来 catalog 需要该槽位但 UI 隐藏、无下载器。渲染进程通过类型化路由与主进程通信路由在 src/main/toolchains/routes.ts 中注册toolchains.getStatustoolchains.setSourcetoolchains.installtoolchains.cancelInstalltoolchains.repairtoolchains.reverttoolchains.pickCustom进度通过 DeepChat 事件传递而不是 settings 快照 key。选择持久化在{userData}/toolchains/state.json而非app-settings.json指针与下载树共享同一目录、同一原子写者。Skill 策略映射Skill 偏好解析方式autoToolchainService持久化来源builtin仅 bundled不完整即失败system仅 system缺失即失败Skillauto不再优先系统高于随包——首次运行迁移 显式 Settings 选择取代了旧的隐式链。Python Skill 通过ToolchainService解析 uvSkillauto在该持久化 uv 来源上 fail-close绝不回退到系统 CPython显式 Skillsystem仍可使用系统 CPython。DeepChat 不下载 CPython。打包终态与 CLI Electron 宿主安装包含app、uvuvx 种子、OCR 模型/native、RTK、DuckDB VSS、CLI 脚本、skills、官方插件。安装包不包含Node/npm/npx/corepack、Bun、完整 CPython。install-runtime.mjs继续安装 uv和 RTKNode 安装变成打包期 no-op。打包期对任何残留的 Node 种子与每个托管工件必须校验完整性集合npm/npx/corepack而不只是node本身。Windows OCR smoke 防火墙规则当前指向随包node.exe翻转后必须指向解析出的官方 Node。CLI 由打包的 Electron 以ELECTRON_RUN_AS_NODE1托管——即使托管 Node 已安装CLI 宿主仍是 Electron。这在 docs/architecture/managed-toolchains/plan.md 的第 4 切片CLI Electron host中有完整落地步骤deepchat.mjs由 Electron 托管launcher 与build-cli.mjs不再依赖runtime/node下次 GUI 启动时刷新 launcher。兼容性、不变式与失败行为兼容性已有完整随包 Node 的用户迁移到bundled来源并继续工作直到后续版本把 Node 移出工件因随包 Node 缺失而依赖系统 PATH 的用户在系统存在node时迁移到systemuseBuiltinRuntime保持删除、死 i18n key 清理bunRuntimePath删除、调用方改用 Nodeissue #2153 的 AC 行工件不含 uv是已接受的偏差——uv 保留为随包种子 托管覆盖需要在提 PR 时在 issue 上重新协商。十大不变式节选关键一个解析器每种 kind 一个持久化来源、解析绝不走到下一个来源一个托管 Node pin、catalog 永不列出第二个 Node 版本官方 Node ABI 137 供 OCRElectron Node 只跑 DeepChat 自己的 JSCLI 宿主是 Electron被中断的下载绝不成为活动指针失败的镜像探测不写磁盘缓存Repair 与 Revert 严格区分uv 的 Revert 回到随包种子随包损坏不在原地修补隐私模式不后台探测镜像。失败行为unconfigured/missing/incomplete/version_mismatch/abi_mismatch/path_invalid/unsupported_platform均为类型化错误自动连接路径汇聚为一条横幅并让功能闲置用户发起的安装暴露类型化下载原因OCR 握手不匹配时销毁 helper绝不回退到 Electron Node。实现中mergeMissingNotices会按严重程度transient unconfigured/missing incomplete version_mismatch abi_mismatch聚合缺失通知。安全与隐私、性能安全/隐私custom 路径必须展开后为绝对路径拒绝 URL 中的凭据激活前校验 sha256绝不执行半写下载跟随活动ProxyConfig不另起代理栈隐私模式无后台网络发现不记录可能含用户名的完整 custom 路径遵循既有 logger 约定。性能解析结果内存缓存来源变更/激活/显式刷新时失效热路径MCP/ACP 改写、Skill 派生只是文件系统元数据 缓存不在每次连接时跑node -v每个可执行路径最多派生一次版本/ABI 探测然后缓存瞬态失败有 2 秒 TTL 的inspectTransientUntil每个下载 key 单飞PATH 扫描上限 256 条与 Skill 一致。验收标准Acceptance CriteriaMCP、ACP、Skill、OCR 只通过ToolchainService解析 Node/uv首次运行持久化后只有 Settings以及 Repair/Revert能改变后续解析来源唯一例外是一次性首次运行unconfigured → system登录 shell PATH 到达时用户选择的unconfigured永不被提升失败或被中断的 Node 下载保留上一个可用版本为活动版本OCR helper 握手接受已激活的官方 pin拒绝 Electron Node 与范围外版本安装包移除 Node 后 CLI 仍可运行Electron 宿主打包翻转后安装包尺寸不再包含 Node 发行版不下载、不携带任何 Bun 二进制uv 保留在工件中Revert 恢复该种子隐私模式在用户主动安装前不做任何工具链探测死代码bunRuntimePath与useBuiltinRuntime副本彻底移除。被否决的替代方案方案否决理由mise需要额外分发的工具、隐式 shim、我们不想要的版本管理器 UX直接下载官方 Node 发行版隐式 PATH 回退链生产环境的痛点静默换源用 Electron Node 跑 OCR / npxABI 145 vs 137无 npm/npx/corepack两个托管 Node 版本OCR 与 MCP 共享一个 pin系统 Node 是用户的二进制不是第二次下载恢复 Bun纯历史包袱v0.4.9 已移除schema 桩、UI 隐藏、无下载器现在就移除工件中的 uv移除种子再重下更糟且解耦 CVE 的覆盖仍需托管路径保留种子 托管覆盖落地路线Plandocs/architecture/managed-toolchains/plan.md 把实现切分为 6 个可独立评审、每步后应用仍可用的切片解析器与显式来源引入ToolchainService、持久化state.json、首次迁移、MCP/ACP/Skill/OCR 全量改写、删除 Bun 别名与死 i18n、OCR 握手改为解析出的官方 Node 版本下载器 / catalog / 打包期完整性单 pin Node catalog、官方发行版下载器、managed 激活、Repair/Revert、打包期校验 npm/npx/corepackSettings UI 与缺运行时横幅来源选择器、系统二进制高亮、安装进度、聚合横幅CLI Electron 宿主ELECTRON_RUN_AS_NODE1托管deepchat.mjs停止分发 Node从安装流程移除 Node升级用户看到missing 横幅Windows OCR smoke 指向解析出的官方 Node审查、验证与清理全量对照 spec 审查保留迁移、resolve-never-switches、完整性、原子激活、OCR purpose 约束与下载恢复的持久化测试。质量门禁为pnpm run format、pnpm run i18n、pnpm run lint、pnpm run typecheck加最小相关 Vitest 套件测试策略实现优先——切片 1 之后补迁移/解析/完整性/改写契约测试切片 2 之后补激活与中断下载测试UI 与打包切片依赖既有门禁加一个小的 status-route 测试且不添加复述私有控制流的实现耦合 mock。结语Managed Toolchains 的整套设计围绕三个朴素原则展开单一解析器、单一持久化来源、单一托管 pin。配合原子激活、类型化失败、隐私默认关闭与打包期校验完整性集合等细节DeepChat 得以在不牺牲用户既有环境的前提下逐步把 Node 移出安装包同时为 OCR 的 ABI 约束和 MCP/ACP/Skill 的通用解析需求提供一条清晰的托管路径。对于希望深入源码的读者建议从 src/main/toolchains/service.ts解析与安装主逻辑、src/main/toolchains/catalog.ts版本 pin 与工件清单、src/main/toolchains/downloader.ts校验下载和 src/shared/types/toolchains.ts类型契约四个文件开始阅读。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考