前言¶

在 DSH（DeepSeek Harness）里跑智能体时，API Key、端点、本地开关往往放在 .env 或 .env.local 里。Shell 或进程管理器已经 export 过的变量，通常不应被文件再次覆盖；反过来，若插件在模块 import 时就读环境，而 dotenv 加载太晚，凭据插件可能已经用空值完成初始化。社区插件 dsh-dotenv（维护者 LIghtJUNction，目录分类 admin-security）针对的是：在 DSH 0.2.1-rc.2 启动阶段显式读指定文件，用 Node util.parseEnv 只填入 process.env 里尚未定义的键——已有值（含空字符串）一律保留。

这是什么¶

dsh-dotenv 是 Cordis 插件 bundle，npm 包名 @lightjunction/dsh-dotenv，简介为 “Explicit dotenv loading without overwriting inherited variables”。它不自动发现 .env，也不读取 Pi 的 --env-file；不配置 path 就不加载任何文件。文件由 DSH 进程所在主机的 Node 文件系统读取，不是 agent 会话目录，也不支持远程 world、sandbox 或远程 shell 注入。

核心功能¶

下面介绍 README 中已说明的行为。

1. 解析与合并：遵循 Node parseEnv 的引号、注释、export、多行语法，支持文件开头 BOM；无 shell 执行、命令替换或 $VARIABLE 插值。
2. 不覆盖：加载前可在 shell 设定变量；文件不会覆盖它们。多个加载实例同样遵守“已有值保留”，并发完成顺序不保证，建议只用一个显式文件。
3. 生命周期：插件只加载一次，无工具、命令、文件监听或模型提示词注入，也不会输出变量名、数量或值。读取失败只抛固定错误，避免文件内容进入错误信息；失败时不应用部分环境值。
4. 依赖顺序：依赖环境值的其他插件须在 dotenv 加载完成后初始化；安装 bundle 不会追溯重建已启动的模型客户端。若消费者在模块导入时就读取环境，应由启动 shell 或进程管理器设置环境。
5. dispose：会取消并等待进行中的读取，不会删除已成功加载的环境变量；改文件或重载不会替换已有值，需要新 DSH 进程才能得到干净环境。

运行要求：Node 24+（README 写明本地验收为 Node 26），DSH 0.2.1-rc.2。许可证 MIT。

安装与启用¶

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: {}。通过 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 内的绝对路径。

典型用法¶

先做配置，再启动 DSH；确保依赖环境的插件在 dotenv 之后初始化。

文件示例（占位内容，勿放真实凭据）：

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

加载前在 shell 中 export 的变量不会被文件覆盖；空字符串若已存在同样保留。

限制与安全注意¶

• 文件须在 canonical root 内、为普通单硬链接文件，不得经符号链接访问；空路径、路径逃逸、目录、FIFO/设备、超过 256 KiB 均拒绝。需支持 O_NOFOLLOW 的主机；已在 Linux 验证，未做 Windows 验收。
• 环境变量对同进程插件及继承环境的子进程可见；分类 admin-security 强调显式加载与失败时不泄露文件内容，不等于隔离整个进程。不要要求模型打印环境或凭据。
• 插件以当前 DSH 进程权限读盘；安装前应查看源码与 MIT 许可证。

开发与验证¶

上游仓库提供：

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

测试在真实 DSH Host 内挂载插件，覆盖语法、BOM/多行、不覆盖已有值、无 path 不加载、路径/符号链接/大小拒绝、dispose 等；未验收远程环境注入或 Pi CLI。

结尾¶

dsh-dotenv 适合需要在 DSH 启动早期、用单一配置文件补全 process.env、且不与 shell 已有变量冲突的场景。目录与源码：

• 社区目录：https://www.skillhub.cn/plugins/LIghtJUNction/dsh-dotenv
• GitHub：https://github.com/LIghtJUNction/dsh-dotenv

DSH 生态采用「一切皆插件」思路；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。