dsh-dotenv

为 DSH 0.2.1-rc.2 启动阶段显式加载 dotenv 文件。使用 Node util.parseEnv，仅填入 process.env 中尚未定义的变量；已有空字符串同样保留。Node 24+，本地验收环境为 Node 26。

安装与配置

GitHub Release 发布 v0.1.0 后，可安装其 npm tarball；此说明不表示版本已经发布：

dsh plugin --profile tui add https://github.com/LIghtJUNction/dsh-dotenv/releases/download/v0.1.0/lightjunction-dsh-dotenv-0.1.0.tgz

软件包的 bundle 默认 config: {}，不设置 path 就不加载任何文件。它不会自动发现 .env，也不读取 Pi 的 --env-file 参数。通过 profile 的 cordis.patch.yml 或 --patch overlay 显式配置：

- id: dsh-dotenv
  config:
    root: /absolute/path/to/project
    path: .env.local

root 默认是 DSH 进程启动时的 process.cwd()；path 相对于 root，也可使用 root 内的绝对路径。它不是 agent 的会话目录。文件由 DSH 进程所在主机的 Node filesystem 读取，不支持远程 world、sandbox 文件系统或远程 shell 环境注入。

文件示例（占位内容，不使用真实凭据）：

export APP_ENDPOINT="https://example.invalid"
APP_LABEL="Local # development"
APP_BANNER="first line
second line"

加载前可以从 shell 设定变量；文件不会覆盖它们。遵循 Node parseEnv 的引号、注释、export、多行语法；支持开头 BOM。无 shell 执行、命令替换或 $VARIABLE 插值。

启动顺序与生命周期

插件只加载一次，没有工具、命令、文件监听器或模型提示词注入，也不会输出变量名、数量或值。读取失败只抛固定错误，避免文件内容进入错误信息。

依赖环境值的其他插件必须在 dotenv 加载完成后初始化。尤其需要配置提供者/凭据插件的启动顺序；安装此 bundle 不会追溯重建已经启动的模型客户端。若消费者在模块导入时就读取环境，插件 apply 可能已经太晚；这种情况应由启动 shell 或进程管理器设置环境。

多个加载实例都遵守“已有值保留”：谁先完成读取，谁先填入，同名变量后续不覆盖；并发完成顺序不保证。请优先使用一个显式文件。plugin dispose 会取消并等待尚在进行的读取，不会删除已经成功加载的环境变量；这些值属于进程，恢复旧值可能破坏其他插件。修改文件或重新加载不会替换已有值，需要新的 DSH 进程才能获得一套干净的环境。

限制

• 文件必须位于 canonical root 内、为普通单硬链接文件，不得通过符号链接访问；支持 root 内普通子目录。空路径、路径逃逸、目录、FIFO/设备和超过 256 KiB 的文件均拒绝。不自动修改 .gitignore 或文件权限。
• 需要支持 O_NOFOLLOW 的主机；已在 Linux 验证，未做 Windows 验收。路径检查不是 OS sandbox，无法抵御恶意本地进程在检查和打开之间替换父目录。
• “不向模型提供秘密工具”不代表隔离整个进程：环境变量对同进程插件及后续继承环境的子进程可见，其他已授权 shell 工具仍有自己的能力。不要要求模型打印环境或凭据。
• 读取失败时不应用部分环境值；parseEnv 按 Node 自己的容错规则处理文本，不额外实现 dotenv 语法检查器。

开发验证

npm run check --workspace @lightjunction/dsh-dotenv

测试在真实 DSH Host 内挂载插件：验证 Node dotenv 语法、BOM/多行、不覆盖已有值/空字符串、无 path 时不加载、路径/符号链接/硬链接/大小拒绝、并发首次写入、dispose 及 offline agent 模型请求不含秘密值或秘密工具。未验收远程环境注入或 Pi CLI。