docs(faq): add Desktop Node environment guide

newbe36524 · hagicode-ai · newbe36524 · commit 5611024bb349 · 2026-04-26T11:28:10.000+08:00
Add bilingual FAQ entry explaining why HagiCode Desktop bundles Node.js,
how it prefers bundled Node paths at runtime, and why it does not replace
the user's system Node installation.

Changes:
- Add Desktop Node Environment (English) FAQ entry
- Add Desktop Node 环境说明 (Chinese) FAQ entry
- Update FAQ index pages to include new entry links

Co-Authored-By: Hagicode &lt;noreply@hagicode.com&gt;
Signed-off-by: newbe36524 &lt;newbe36524@qq.com&gt;
diff --git a/src/content/docs/en/faq/desktop-node-environment.mdx b/src/content/docs/en/faq/desktop-node-environment.mdx
@@ -0,0 +1,38 @@
+---
+title: Desktop Node Environment
+description: Explains why HagiCode Desktop bundles Node.js and how it prefers bundled Node paths while the user runs Desktop.
+sidebar:
+  order: 20
+---
+
+HagiCode Desktop ships with a Desktop-managed Node toolchain. It does not take over the global Node installation on your computer. Its purpose is to give Desktop startup and runtime-related flows a stable and verifiable runtime foundation.
+
+Read this FAQ if you see `portable-fixed/toolchain` in diagnostics, need to know which `node` Desktop is using, or wonder why your system Node version does not directly define Desktop runtime behavior.
+
+## Why Desktop bundles Node
+
+Desktop needs to run the same supporting flows across operating systems, installation channels, and user environments. If it depended only on the user's existing Node installation, support would have to handle outdated versions, missing npm, incorrect path ordering, polluted global packages, and organization-specific registry policies all at once.
+
+Desktop describes this more specifically as an isolated Node/npm runtime for managed CLIs instead of reusing the system-wide environment. This design has these main benefits:
+
+- **Consistent versions**: Desktop uses a pinned Node 22 runtime contract instead of guessing the user's local major version.
+- **Controlled startup flows**: Desktop-managed commands can prefer the packaged `node` and `npm` entries.
+- **Clear configuration boundaries**: CLI-related configuration is kept separate from host-wide global configuration, so updates, switching, and recovery are less likely to be disrupted by system environment differences.
+- **Reduced conflicts**: Bundled paths apply to command environments created by Desktop and do not replace the user's global Node in their terminal.
+- **Non-intrusive host behavior**: This isolation avoids writing toolchain state into the user's existing Node/npm environment, and uninstalling Desktop does not disturb the Node, npm, or configuration already present on the machine.
+
+## How Desktop selects the Node path
+
+When you run Desktop normally, Desktop prefers the Node toolchain installed with the app instead of first reading the Node installation from your system. This keeps the Node version in your terminal separate from the Node version Desktop expects while it runs.
+
+When the bundled toolchain is enabled, command environments created by Desktop put bundled toolchain paths at the front of `PATH`. As a result, even if your system has another Node version installed, Desktop-managed flows resolve to Desktop's bundled Node and npm first.
+
+This only affects runtime environments created by Desktop. If you run `node`, `npm`, or other commands directly in your system terminal, they continue to use your normal system environment and shell configuration.
+
+In diagnostics or child-process environments started by Desktop, you may see a variable like this:
+
+```bash
+HAGICODE_PORTABLE_TOOLCHAIN_ROOT=/path/to/portable-fixed/toolchain
+```
+
+This variable means the Desktop-managed runtime environment recognized the bundled toolchain root. Seeing this path does not mean Desktop changed your system Node; it only means Desktop is using the Node environment shipped with the app inside its own runtime scope.
diff --git a/src/content/docs/en/faq/index.mdx b/src/content/docs/en/faq/index.mdx
@@ -1,15 +1,15 @@
 ---
 title: FAQ
-description: Review common HagiCode runtime notes, startup caveats, and future troubleshooting entries in one place.
+description: Review common HagiCode runtime notes, startup caveats, runtime environment explanations, and future troubleshooting entries in one place.
 sidebar:
   order: 1
 ---
 
 import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 
-This page collects common questions and runtime guidance for HagiCode.
+This page collects common questions, runtime guidance, and troubleshooting entry points for HagiCode.
 
-The first FAQ entry explains the Steam for Linux startup compatibility path and why the default launch currently disables Electron's sandbox layer.
+Current FAQ entries cover Desktop platform startup compatibility and the bundled Node toolchain used by Desktop-managed flows.
 
 ## Current FAQ Entries
 
@@ -19,14 +19,19 @@ The first FAQ entry explains the Steam for Linux startup compatibility path and
     href="/en/faq/steam-linux-startup"
     description="Understand why the default Steam launch uses no-sandbox compatibility flags, what security trade-off that creates, and how to launch hagicode-desktop directly to keep Electron's default sandbox."
   />
+  <LinkCard
+    title="Desktop Node Environment"
+    href="/en/faq/desktop-node-environment"
+    description="Understand why Desktop bundles Node.js, how it prefers bundled Node paths at runtime, and why it does not replace your system Node."
+  />
 </CardGrid>
 
 ## What This Section Covers
 
 The FAQ section is the place for:
 
 - startup and runtime caveats
-- compatibility notes tied to platforms, distribution channels, or packaging
+- compatibility notes tied to platforms, distribution channels, packaging, or bundled runtimes
 - troubleshooting topics that deserve a stable standalone explanation page
 
-If you are troubleshooting Steam for Linux startup behavior right now, open [Steam Linux Startup Notes](/en/faq/steam-linux-startup).
+If you are troubleshooting Steam for Linux startup behavior right now, open [Steam Linux Startup Notes](/en/faq/steam-linux-startup). If you need to confirm which Node Desktop uses or why diagnostics mention `portable-fixed/toolchain`, open [Desktop Node Environment](/en/faq/desktop-node-environment).
diff --git a/src/content/docs/faq/desktop-node-environment.mdx b/src/content/docs/faq/desktop-node-environment.mdx
@@ -0,0 +1,38 @@
+---
+title: Desktop Node 环境说明
+description: 说明 HagiCode Desktop 为什么内置 Node.js，以及用户运行 Desktop 时它如何优先使用内置 Node 路径。
+sidebar:
+  order: 20
+---
+
+HagiCode Desktop 会随应用一起提供一套由 Desktop 管理的 Node 工具链。它的目标不是接管你电脑上的全局 Node 环境，而是让 Desktop 自己启动和运行相关流程时拥有稳定、可验证的运行基础。
+
+这篇 FAQ 适合想了解以下问题时阅读：为什么诊断里出现了 `portable-fixed/toolchain` 路径、Desktop 到底用了哪个 `node`，以及为什么系统 Node 版本不会直接决定 Desktop 的运行行为。
+
+## 为什么 Desktop 要内置 Node
+
+Desktop 需要在不同操作系统、不同安装来源和不同用户环境里启动相同的一组辅助流程。如果完全依赖用户已经安装的 Node，支持团队会同时面对版本过旧、npm 缺失、路径顺序错误、全局包污染、公司镜像源策略等问题。
+
+Desktop 里还有一个更具体的说法：它使用独立的 Node/npm 运行时来承载托管 CLI，而不是直接复用系统环境。这样做主要有这些原因：
+
+- **版本一致**：Desktop 使用固定的 Node 22 运行时契约，不需要猜测用户机器上的 Node 主版本。
+- **启动流程可控**：Desktop 管理的命令可以优先使用随应用打包的 `node` 和 `npm`。
+- **配置边界清晰**：CLI 依赖的配置会与主机范围的全局配置区分开，升级、切换和恢复时不容易被系统环境差异打断。
+- **降低冲突**：内置路径只作用在 Desktop 创建的命令环境中，不会替换用户终端里的全局 Node。
+- **不污染宿主机**：这种隔离方式可以避免 HagiCode 把工具链状态写进用户原本的 Node/npm 环境；卸载 Desktop 时，也不会影响你系统里已经存在的 Node、npm 和配置。
+
+## Desktop 如何选择 Node 路径
+
+用户正常运行 Desktop 时，Desktop 会优先使用随应用一起安装的 Node 工具链，而不是优先读取系统里已经安装的 Node。这样可以避免“用户终端里的 Node 版本”和“Desktop 运行所需 Node 版本”互相影响。
+
+当内置工具链处于启用状态时，Desktop 创建的命令环境会把内置工具链相关路径放到 `PATH` 前面。因此，即使你的系统已经安装了另一个版本的 Node，Desktop 管理的流程也会优先解析到它自带的 Node 和 npm。
+
+这只影响 Desktop 自己创建的运行环境。你在系统终端中直接执行 `node`、`npm` 或其他命令时，仍然使用你原本的系统环境和 shell 配置。
+
+在诊断信息或 Desktop 启动的子进程环境中，你可能会看到类似下面的变量：
+
+```bash
+HAGICODE_PORTABLE_TOOLCHAIN_ROOT=/path/to/portable-fixed/toolchain
+```
+
+这个变量表示当前 Desktop 管理的运行环境已经识别到内置工具链根目录。看到这类路径并不表示 Desktop 修改了你的系统 Node；它只说明 Desktop 在自己的运行范围内使用了随应用提供的 Node 环境。
diff --git a/src/content/docs/faq/index.mdx b/src/content/docs/faq/index.mdx
@@ -1,15 +1,15 @@
 ---
 title: 常见问题
-description: 集中查看 HagiCode 使用过程中的常见运行说明、启动注意事项与后续补充条目。
+description: 集中查看 HagiCode 使用过程中的常见运行说明、启动注意事项、运行时环境解释与后续补充条目。
 sidebar:
   order: 1
 ---
 
 import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 
-本页汇总 HagiCode 文档中的常见问题与运行说明。
+本页汇总 HagiCode 文档中的常见问题、运行说明与排障入口。
 
-当前第一条 FAQ 重点说明 Steam for Linux 环境下的启动兼容策略，以及为什么默认启动会关闭 Electron 的沙箱保护层。
+当前 FAQ 重点覆盖 Desktop 的平台启动兼容策略，以及 Desktop 自带 Node 工具链的用途、隔离方式和排查边界。
 
 ## 当前 FAQ 条目
 
@@ -19,14 +19,19 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components';
     href="/faq/steam-linux-startup"
     description="了解默认 Steam 启动为何使用 no-sandbox 兼容参数、这带来的安全权衡，以及如何手动直启 hagicode-desktop 保留 Electron 默认沙箱。"
   />
+  <LinkCard
+    title="Desktop Node 环境说明"
+    href="/faq/desktop-node-environment"
+    description="了解 Desktop 为什么内置 Node.js、运行时如何优先使用内置 Node 路径，以及它为什么不会替换你的系统 Node。"
+  />
 </CardGrid>
 
 ## 这个分区会放什么
 
 FAQ 分区用于集中收纳以下内容：
 
 - 启动和运行时的特殊说明
-- 与平台、发行渠道或打包方式相关的兼容性提示
+- 与平台、发行渠道、打包方式或内置运行时相关的兼容性提示
 - 适合做成独立说明页的常见排障入口
 
-如果你当前遇到的是 Steam for Linux 下的启动问题，请直接阅读 [Steam Linux 启动注意事项](/faq/steam-linux-startup)。
+如果你当前遇到的是 Steam for Linux 下的启动问题，请直接阅读 [Steam Linux 启动注意事项](/faq/steam-linux-startup)。如果你想确认 Desktop 使用哪个 Node，或为什么诊断里出现 `portable-fixed/toolchain`，请阅读 [Desktop Node 环境说明](/faq/desktop-node-environment)。
