路径、文件夹与环境变量优先级

hstack 存储 home/工作区/运行时/栈的位置，以及环境变量优先级的工作机制。

本文档介绍 hstack 使用的目录结构（home/workspace/runtime/stacks）以及 hstack 采用的环境配置文件优先级。

若不确定当前设备实际生效的配置，可运行：

hstack where

术语速查

CLI 根目录（CLI root dir）
- 存放当前 hstack 命令所执行的 @Kaiwu-dev/stack 脚本（scripts/*.mjs）的目录。
- 该目录不一定是当前 shell 的 cwd。
- 它可以是：
  - 克隆的代码仓库检出目录（例如 /Users/⟦K4⟧/.../Kaiwu-dev），或
  - 安装在 ~/.Kaiwu-stack/runtime/node_modules/@Kaiwu-dev/stack 下的运行时包（参见“运行时目录”）。
Home 目录（Home dir）（Kaiwu_STACK_HOME_DIR）
- 默认路径：~/.Kaiwu-stack
- 用于存储全局用户配置及缓存，可能包含运行时安装。
运行时目录（Runtime dir）（Kaiwu_STACK_RUNTIME_DIR）
- 默认路径：~/.Kaiwu-stack/runtime
- 供 hstack self update 安装或升级锁定的 @Kaiwu-dev/stack 运行时包使用。
工作区目录（Workspace dir）（Kaiwu_STACK_WORKSPACE_DIR）
- 默认路径：~/.Kaiwu-stack/workspace（存在时）。
- hstack 用于存储 Kaiwu monorepo 检出与工作树的存储工作区。
- 通常包含：
  - ⟦K5⟧/main（稳定版 monorepo 检出）
  - ⟦K6⟧/dev（开发版 monorepo 检出；由 hstack setup-from-source --profile=dev 创建）
  - ⟦K7⟧/pr/...（PR 工作树）
  - ⟦K8⟧/local/⟦K9⟧/...（本地工作树）
  - ⟦K10⟧/tmp/⟦K11⟧/...（临时工作树）
仓库目录（Repo dir）（Kaiwu_STACK_REPO_DIR）
- 默认路径：⟦K12⟧/main
- 当前激活的 Kaiwu monorepo 检出目录（main、dev 或某个工作树）。
- hstack wt use ... 与 hstack stack wt ⟦K13⟧ -- use ... 会更新该值。
工作树（Worktrees）
- PR：⟦K14⟧/pr/...
- 本地：⟦K15⟧/local/⟦K16⟧/...
- 临时：⟦K17⟧/tmp/⟦K18⟧/...
栈存储目录（Stacks storage dir）
- 默认路径：~/.Kaiwu/stacks
- 每个栈存放在 ~/.Kaiwu/stacks/⟦K19⟧/... 下，并拥有独立的环境变量文件：
  - ~/.Kaiwu/stacks/⟦K20⟧/env

“我到底是从哪里运行的？”

hstack 可能会**重新执行（re-exec）**至另一个 CLI 根目录（例如使用已安装的 shim 但希望运行本地检出时）。

运行 hstack where 可查看：
- rootDir（CLI 根目录）
- homeDir（栈 home 目录）
- runtimeDir
- workspaceDir
- 解析出的环境变量文件路径

提示：若要将 shim 固定到本地检出，可使用：

hstack self use-cli dev

提示：hstack where --json 更易于脚本解析。

环境配置文件与优先级（从低到高）

hstack 在 scripts/utils/env.mjs 中加载环境变量。

0) “规范指针”环境文件（用于发现路径）

若未设置 Kaiwu_STACK_HOME_DIR，系统会先尝试读取**规范指针（canonical pointer）**环境文件以发现目标 home 目录（适用于 LaunchAgents、SwiftBar 或极简 shell 环境）。

默认规范指针路径：~/.Kaiwu-stack/.env
覆盖规范指针位置：
- Kaiwu_STACK_CANONICAL_HOME_DIR=/some/dir（指针变为 ⟦K21⟧/.env）

1) 全局默认配置（home 配置）或克隆仓库默认配置

若存在 home 配置，将加载：

~/.Kaiwu-stack/.env（默认值）
~/.Kaiwu-stack/env.local（覆盖项，支持 Kaiwu_STACK_* 前缀匹配）

若不存在 home 配置（即运行 hstack init 之前的克隆仓库使用场景），将加载：

<cliRootDir>/.env
<cliRootDir>/env.local（支持 Kaiwu_STACK_* 前缀匹配）

2) 仓库 `.env` 回退项（便于本地开发）

即使存在 home 配置，系统仍会加载：

<cliRootDir>/.env（非覆盖式回退项）

此机制让仓库本地开发配置（例如 Kaiwu_CODEX_ACP_BIN）直接生效，无需每个人重复复制到 ~/.Kaiwu-stack/env.local 中。

注意：

这仅作为回退项（override: false）：不会覆盖环境变量或 home 配置中已有的值。
在“存在 home 配置”的分支中，系统特意不自动加载 <cliRootDir>/env.local，因为其优先级较高，可能会与栈配置产生非预期的冲突。

3) 栈环境覆盖层（最高优先级）

最后，系统加载当前激活的栈环境文件（override = true）：

Kaiwu_STACK_ENV_FILE
若二者均未设置，系统会自动选择当前栈对应的环境文件（默认为 main，如果存在）

栈环境文件允许包含无前缀的配置项（如 DATABASE_URL），这是实现单栈隔离所必需的。

各项配置该写在哪里？（经验法则）

全局且整台设备生效的默认项，请写入 ~/.Kaiwu-stack/.env。
个人本地覆盖项，请写入 ~/.Kaiwu-stack/env.local。
单栈隔离配置，请写入对应的栈环境文件 ~/.Kaiwu/stacks/⟦K22⟧/env（这也是 hstack stack edit 与 hstack stack wt 所修改的文件）。
仅限仓库本地的开发默认项，请写入 <cliRootDir>/.env（在该检出目录作为 CLI 根目录运行时效果最佳）。

沙箱与测试安装（完全隔离）

若需完整测试安装与配置流程，且不影响真实安装环境，可运行：

npx @Kaiwu-dev/stack@latest --sandbox-dir /tmp/hstack-sandbox where

在沙箱模式下，hstack 会将 home/workspace/runtime/storage 重定向到沙箱目录内（直接 rm -rf 该目录即可彻底重置）。

沙箱模式下默认禁用全局系统级副作用（修改 PATH、安装 SwiftBar 插件、注册 LaunchAgents/systemd 服务）。如需在测试中显式启用这些操作，请设置：

Kaiwu_STACK_SANDBOX_ALLOW_GLOBAL=1