前言¶

在 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 / 幻方無官方從屬關係。