@lixiangzhong/dsh-shell-secrets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lixiangzhong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,307 @@
+# @lixiangzhong/dsh-shell-secrets
+
+把**启动 dsh 的那个环境里**名字匹配 `KEY|PASSWORD|SECRET|TOKEN`（大小写不敏感）的变量，
+以**原始变量名**重新注入 dsh 的 bash 子进程。
+
+> ## ⚠️ 先读这一段
+>
+> 这个插件**有意绕过** harness 的凭证 scrub。启用之后，匹配到的变量会进入**每一个**
+> bash 子进程 —— 包括 `npm install` 的 postinstall、以及模型运行的任意第三方二进制。
+> 只要模型执行 `env`，这些值就会出现在 tool result（也就是会话日志和模型上下文）里。
+>
+> 请在**受信 workspace + 受信会话**里使用；不要把值直接 `echo`/`env` 到会被记录的输出里
+> （验证时用 `env | cut -d= -f1 | grep ...` 只列名字）。插件本身无法对输出脱敏。
+
+```bash
+export GITHUB_TOKEN=ghp_xxx PGPASSWORD=secret
+dsh web
+# 之后模型通过 bash 工具执行：
+#   gh auth status            # 直接读 $GITHUB_TOKEN，无需改写
+#   psql -h db -U app         # 直接读 $PGPASSWORD
+```
+
+## 它解决的问题
+
+harness 的 subprocess 层有一条固定的凭证 scrub：
+
+```
+scrubbedParentEnv()  // 剔除 /KEY|PASSWORD|SECRET|TOKEN/i 以及所有 DSH_*
+childEnv(extra) = { ...scrubbedParentEnv(), ...extra }   // extra 不再过滤
+```
+
+所以 `~/.dsh/.env`、启动环境里的密钥都进不了 bash 子进程。官方的插件接缝 `ctx.shellEnv`
+只能注册 `DSH_*` 键（命令里得写 `$DSH_GITHUB_TOKEN`），`gh`/`mysql`/`aws` 这类自己读
+环境变量的 CLI 就用不上。本插件改为接管 `ctx.shell`，往文档化的
+`ShellExecSpec.env`（"merged after the credential scrub"）里注入原始变量名。
+
+## 安装 / 卸载
+
+两条路径，**二选一**，不要同时用（`deploy.mjs` 检测到 bundle 安装时会提示）。
+
+### 方式 A：作为 dsh plugin（bundle 形式，推荐）
+
+本包在 `package.json` 里声明了 `dsh.bundle.patch`，所以 `dsh plugin` 会把它自动加进
+`dsh.profile.bundles` 层，不需要手改 profile 的任何 YAML：
+
+```bash
+# 从 npm 安装（发布后）
+dsh plugin --profile web add @lixiangzhong/dsh-shell-secrets
+dsh plugin --profile web update @lixiangzhong/dsh-shell-secrets    # 升级
+
+# 从本地源码 / tarball 安装（开发或内部分发）
+dsh plugin --profile web add file:/Users/lxz/gopath/src/github.com/lixiangzhong/dsh-shell-secrets
+dsh plugin --profile web add file:./dsh-shell-secrets-0.1.0.tgz
+
+# 卸载（同时移除依赖、bundle 层、node_modules）
+dsh plugin --profile web remove @lixiangzhong/dsh-shell-secrets
+
+# 改完本地源码后刷新已安装拷贝
+dsh plugin --profile web remove @lixiangzhong/dsh-shell-secrets && \
+dsh plugin --profile web add file:/Users/lxz/gopath/src/github.com/lixiangzhong/dsh-shell-secrets
+
+node deploy.mjs --check   # 两种安装方式都适用（只看合成后的行）
+```
+
+要点：
+
+- 从 npm 装的是**版本化的 registry 依赖**，`dsh plugin … update` 就能升级；本地 `file:` 目录
+  依赖没有版本概念，升级＝remove + add（见下一条）。
+- **本地安装必须用 `file:`，不能用 `link:`**。`link:` 会把包软链到源码目录，Node 按 realpath
+  解析 `@deepseek-ai/dsh-bash-sandbox` 时会从源码目录向上找而失败（实测 `MODULE_NOT_FOUND`）；
+  `file:` 是真实目录（pnpm 硬链接），realpath 落在 `~/.dsh/profiles` 内，能解析到 harness
+  自己那份模块（实测 hoisted 与 `.pnpm` 两种布局都解析到 npx 安装目录）。
+- 目录依赖是**硬链接**：原地修改源码会立刻反映到已安装副本；但编辑器"写临时文件再 rename"
+  的保存方式会换 inode 断链，所以**刷新请用上面的 remove + add**（实测 `pnpm update` 与
+  `pnpm install --force` 对目录依赖都会报 "Already up to date" 而不重新拷贝）。
+- `bundle` 列表在 **dsh 启动时**读取，装/卸之后要重启 dsh 才生效。
+- **pnpm 版本/store 必须与 profile 现有的 `node_modules` 匹配**。`dsh plugin` 只是转发给
+  PATH 上的 `pnpm`；如果 profile 的 `node_modules` 是用另一个大版本的 pnpm 装的，会直接失败：
+
+  ```
+  ERR_PNPM_UNEXPECTED_STORE  Unexpected store location
+  The dependencies at "~/.dsh/profiles/web/node_modules" are currently linked from the store at
+  "~/.dsh/Library/pnpm/store/v11"; pnpm now wants to use the store at ".../store/v10"
+  ```
+
+  两条出路：把匹配的 pnpm 放到 PATH 前面（本机 store v11 ↔ `~/Library/pnpm/bin/pnpm` 11.8.0）：
+
+  ```bash
+  PATH="$HOME/Library/pnpm/bin:$PATH" dsh plugin --profile web add file:<此目录>
+  ```
+
+  或者在 profile 目录里用当前的 pnpm 重建一次 `node_modules`（`cd ~/.dsh/profiles/web && pnpm install`）。
+- 从 npm 装时，**pnpm 也要指对 registry**：本机全局 registry 是腾讯镜像（`npm_config_registry`
+  环境变量，优先级高于 `~/.npmrc`），刚发布的包在镜像上通常还没同步，会 `404`。给这条命令显式指定：
+
+  ```bash
+  PATH="$HOME/Library/pnpm/bin:$PATH" dsh plugin --profile web add @lixiangzhong/dsh-shell-secrets \
+    --registry=https://registry.npmjs.org
+  ```
+
+  （`dsh plugin` 会把参数原样转发给 pnpm，所以 pnpm 自己的 flag 也能直接写。）
+- 包里的 `peerDependencies` 把 harness 包声明为**可选** peer：只为表达耦合关系，配合 profile
+  自带的 `autoInstallPeers: false`，pnpm 不会偷偷装第二份 harness 包（否则会出现两个 cordis /
+  两个 `Service` 实例，服务注册行为会错乱）。
+- 装好后 `dsh.profile.bundles` 会变成 `['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app',
+  'dsh-shell-secrets']`，profile 的 `cordis.patch.yml` 应保持干净的 `[]`。
+
+### 方式 B：deploy.mjs（拷贝 + 手工挂载，不依赖 pnpm）
+
+适合不想让 pnpm 参与、或要装进多个 profile 的场景：
+
+```bash
+node deploy.mjs            # 拷贝到 ~/.dsh/profiles/web/plugins/dsh-shell-secrets + 写入挂载行
+node deploy.mjs --check    # dsh --profile web --dump-config 校验挂载结果
+node deploy.mjs --remove   # 回滚：移除挂载行 + 删除插件目录
+PROFILE=tui node deploy.mjs  # 换 profile（默认 web）
+```
+
+它做两件事：
+
+1. **拷贝**（不是软链）插件到 `~/.dsh/profiles/<profile>/plugins/dsh-shell-secrets/`。
+   必须是拷贝：`@deepseek-ai/dsh-bash-sandbox` 要从 `~/.dsh/profiles/node_modules`（指向
+   npx 安装目录的软链）解析到 harness **同一份模块实例**，软链会让 Node 按 realpath 从
+   工作区向上找包而失败，两个模块实例混用会出问题。
+2. 在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 的 `# >>> dsh-shell-secrets` /
+   `# <<< dsh-shell-secrets` 标记段内写入：
+
+```yaml
+- id: bash-sandbox
+  disabled: true      # 不关掉官方行就会有两个 shell 服务，cordis 会大声报重复服务
+- insert:
+    - id: shell-secrets
+      name: ./plugins/dsh-shell-secrets/lib/index.js
+      config:
+        timeoutMs: 60000        # 与官方 bash-sandbox 行同值
+      disabled: !!js process.platform === 'win32'
+```
+
+### 方式 A 用的 bundle patch
+
+`cordis.patch.yml`（包内，`dsh.bundle.patch` 指向它）内容与上面等价，只是 `name` 相对包自身：
+
+```yaml
+- id: bash-sandbox
+  disabled: true
+- insert:
+    - id: shell-secrets
+      name: ./lib/index.js       # 锚定成 <包目录>/lib/index.js
+      config:
+        timeoutMs: 60000
+      disabled: !!js process.platform === 'win32'
+```
+
+## 配置（全部来自启动环境）
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `DSH_SHELL_SECRETS_PATTERN` | `KEY\|PASSWORD\|SECRET\|TOKEN`（i） | 自定义匹配正则（与 scrub 同语义是刻意的） |
+| `DSH_SHELL_SECRETS_INCLUDE` | 空 | 逗号分隔 glob（`*`/`?`），**优先于** pattern，如 `*_TOKEN,AWS_*` |
+| `DSH_SHELL_SECRETS_EXCLUDE` | 空 | 逗号分隔 glob 排除项，如 `MONKEY,KEYBOARD_*`（修子串误伤） |
+| `DSH_SHELL_SECRETS_MAX_BYTES` | `8192` | 单值上限，超长跳过 |
+| `DSH_SHELL_SECRETS_DISABLE` | 空 | 非空即停用注入（不卸载插件） |
+
+规则细节：
+
+- **`DSH_*` 永不注入**：维持 harness "ambient `DSH_*` 被丢弃" 的不变量，避免伪造 harness 事实。
+- 空值/纯空白、超长值跳过；含换行的值仍注入（保真优先）但会在装载日志里提醒。
+- 非法正则/非法上限会让**装配失败并抛错**：宁可 dsh 启动失败，也不要静默不注入。
+- 未命中的变量不会进日志（否则整个环境变量表都会变成噪音）。
+
+日志只打印**名字与原因，绝不打印值**。
+
+## 生效时机
+
+| 改了什么 | 怎么生效 |
+| --- | --- |
+| 启动环境里的密钥变量 | 重启 dsh |
+| `DSH_SHELL_SECRETS_*` 配置 | 重启 dsh |
+| `cordis.patch.yml` | web profile 是 `patchReload: live`，保存即热生效 |
+| 插件 JS 代码 | 必须重启 dsh（ESM 模块缓存） |
+
+代码改动后记得 `node deploy.mjs` 重新拷贝。
+
+## 验证
+
+```bash
+# 启动 dsh 的 shell 里
+export MY_TEST_PASSWORD=probe-ok MY_TEST_TOKEN=probe-token
+dsh web
+```
+
+之后在 bash 工具里：
+
+```bash
+echo "${MY_TEST_PASSWORD-unset}"                 # probe-ok（原始名字可用）
+# 只列名字，别 grep 值：tool result 会把它写进会话日志与模型上下文！
+env | cut -d= -f1 | grep -E '_TOKEN$|PASSWORD$|SECRET$|_KEY$' | sort
+env | cut -d= -f1 | grep '^DSH_'                 # 只应有 DSH_HOME/DSH_SHELL/DSH_SESSION_ID/DSH_WEB_URL
+```
+
+单元测试（纯逻辑，零依赖）：
+
+```bash
+node --test
+```
+
+## 实现注意事项（踩过的坑）
+
+- **执行器类里不能用 `#private` 字段/私有方法。** cordis 的 `getTraceable()` 会把服务包成
+  Proxy，方法调用时 `this` 被替换成 shadow 代理，私有字段的 brand 校验会直接失败：
+  `Error: Receiver must be an instance of class SecretsBashExecutor`，且每个命令都失败。
+  官方服务一律用普通字段/方法，照做即可（本插件用 `this.secrets` + `mergeSecrets()`）。
+- **挂载会在运行中的 dsh 上热生效**（web profile 是 `patchReload: live`）。如果新代码有致命
+  缺陷，这个会话的 bash 会立刻不可用；实测**把标记段删掉不足以卸载**已挂载的执行器
+  （服务行的卸载不会自动回滚），此时只能重启 dsh 恢复。所以：改执行器代码后建议先重启再挂载，
+  或者接受一次"重启即恢复"的窗口。
+- 插件 JS 改动受 ESM 模块缓存影响，**同一个进程内换文件内容不会重新导入**（同 URL 命中缓存）。
+
+## 兼容性与已测版本
+
+本插件绑的是 harness 内部接口，所以发布版带一个**装载期自检**（`compatibilityIssues()`）：
+
+| 检查项 | 失败时 |
+|---|---|
+| `SandboxBashExecutor` 是否仍是类，且带 `resolve/run/start` | `logger.error` 报警（不阻断启动） |
+| 本插件解析到的 `@deepseek-ai/dsh-bash-sandbox` 与 harness 自己用的是否**同一份**（防止 profile 装出第二份 harness 包 → 两个 cordis 实例） | `logger.error` 报警（不阻断启动） |
+
+自检**刻意不抛异常**：宁可 dsh 正常启动 + 日志醒目报错，也不要因为误报把用户的 dsh 弄成起不来。
+真正的致命问题（导出的不是类）会在 import 期直接炸。
+
+已实测环境：
+
+| dsh | Node | 平台 | 结果 |
+|---|---|---|---|
+| 0.1.5-rc.1（npx 安装） | v26.7.0 | macOS (darwin) | 前台 + 后台路径均注入成功；`deploy.mjs --check` 通过；单测 13/13 |
+
+未覆盖：`minimal` 预设 / `sdk-minimal` profile 的持久 PTY shell；Windows pwsh。
+
+dsh 升级后请重跑：
+
+```bash
+node --test && node deploy.mjs --check
+env | cut -d= -f1 | grep -E '_TOKEN$|PASSWORD$|SECRET$|_KEY$'   # 只列名字确认注入仍在
+```
+
+## 发布到 npm
+
+```bash
+npm version patch                                   # 或 minor/major
+npm publish                                         # publishConfig 已固定 registry=npmjs、access=public
+```
+
+- **登录也要指 registry**。若生效 registry 是只读镜像（本机 `npm_config_registry` 指向腾讯镜像），
+  `npm login` 会打到镜像上并报 `E409 ... user registration disabled`。二选一：
+
+  ```bash
+  # a) 用 npmjs 的 Access Token（推荐，尤其是账号开了 2FA 时）
+  #    在 https://www.npmjs.com/settings/<用户名>/tokens 生成 Granular Access Token（Read and write），
+  #    然后写进 ~/.npmrc（token 按 host 存，不受 registry 配置影响）：
+  #      //registry.npmjs.org/:_authToken=npm_xxxxxxxx
+  npm whoami --registry=https://registry.npmjs.org    # 应输出你的用户名
+
+  # b) 或者直接登录 npmjs（npm 11 默认 web 登录；也可加 --auth-type=legacy 走用户名/密码/OTP）
+  npm login --registry=https://registry.npmjs.org
+  ```
+
+  注意：环境变量 `npm_config_registry` 优先级高于 project/user `.npmrc`，所以"在项目里放
+  `.npmrc` 改 registry"在这里**无效**，只能用 CLI flag 或按 host 存的 token。
+- `publishConfig.registry` 显式指向 `https://registry.npmjs.org`：本机 `npm_config_registry`
+  是只读镜像时，不加这个会发布失败。
+- 发布前自查：`npm pack --dry-run`（应只含 `lib/`、`cordis.patch.yml`、`README.md`、`LICENSE`、
+  `package.json`）、`node --test`。
+- 发布后把安装方式切到 registry 版本（pnpm 也要指 registry，见上文；镜像对新包有同步延迟）：
+
+  ```bash
+  PATH="$HOME/Library/pnpm/bin:$PATH" dsh plugin --profile web remove @lixiangzhong/dsh-shell-secrets
+  PATH="$HOME/Library/pnpm/bin:$PATH" dsh plugin --profile web add @lixiangzhong/dsh-shell-secrets \
+    --registry=https://registry.npmjs.org
+  npm view @lixiangzhong/dsh-shell-secrets version --registry=https://registry.npmjs.org
+  ```
+
+## 风险与边界
+
+1. **这是有意绕过凭证 scrub**：匹配到的变量会进入**每一个** bash 子进程，包括
+   `npm install` 的 postinstall 与任意第三方二进制。只在受信 workspace 使用。
+2. 值会随命令输出进入模型可见的 tool result（例如模型跑 `env`）。插件无法对输出脱敏。
+3. 绑定了 harness 内部结构：`SandboxBashExecutor` 默认导出、`run`/`start` 语义、
+   `ShellExecSpec.env` 的"scrub 之后再合并"约定、`bash-sandbox` 行的存在，
+   以及 `ctx.shell` 服务名。dsh 升级后请重新跑一遍：
+   ```bash
+   node --test && node deploy.mjs --check
+   ```
+   并确认 `env` 里密钥仍在。
+4. 若将来 harness 给 `ShellExecSpec` 增加了插件级 env 贡献接缝，应迁移过去并删掉
+   执行器替换（少一层内部耦合）。
+5. **不覆盖**：`minimal` 预设 / `sdk-minimal` profile 的持久 PTY shell（走 `terminals`
+   服务，不经 `ctx.shell`）；Windows 的 pwsh（`SandboxPwshExecutor` 同样已导出，可同构补充）。
+
+## 目录
+
+```
+lib/secrets.js       密钥选择纯逻辑（可单测）
+lib/index.js         SecretsBashExecutor extends SandboxBashExecutor
+test/secrets.test.js node --test
+deploy.mjs           部署/回滚/校验
+cordis.patch.yml     作为独立 bundle 安装（dsh plugin add file:<dir>）时用的行
+```

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-shell-secrets 作为独立 bundle 安装时的 patch 行。
+#
+# 只有走 `dsh plugin --profile <profile> add file:<此目录>` 这条安装路径时，本文件才会
+# 被当作 bundle 层加载；此时 patch 里的相对 `name` 会被锚定到本文件所在目录。
+#
+# 常规用法是 deploy.mjs：它把插件拷进 profile 并把等价的行写进
+# ~/.dsh/profiles/<profile>/cordis.patch.yml（那条路径能保证 @deepseek-ai/* 解析到
+# harness 自己的模块实例，subclass 才安全）。
+
+# 官方 bash-sandbox 行必须先关掉：两个实现会争同一个 `shell` 服务，
+# cordis 对此会大声报重复服务（这是刻意的失败模式，不要靠顺序去赌）。
+- id: bash-sandbox
+  disabled: true
+
+- insert:
+    - id: shell-secrets
+      name: ./lib/index.js
+      # 与官方 bash-sandbox 行同值，替换后行为保持不变。
+      config:
+        timeoutMs: 60000
+      # 本期只覆盖 bash；Windows 的 pwsh 走 SandboxPwshExecutor，可同构补充。
+      disabled: !!js process.platform === 'win32'

package/lib/index.js

@@ -0,0 +1,164 @@
+/**
+ * dsh-shell-secrets：把启动环境里 KEY/PASSWORD/SECRET/TOKEN 类变量带回 bash 子进程。
+ *
+ * 为什么用"替换执行器"而不是官方 shellEnv 接缝：官方 `ctx.shellEnv` 只允许注册
+ * `DSH_*` 键，命令里就得写 `$DSH_GITHUB_TOKEN`，`gh`/`mysql`/`aws` 这类自己读环境变量
+ * 的 CLI 无法直接使用。这里改为接管 `ctx.shell`（服务名 `shell`），在文档化的
+ * `ShellExecSpec.env` 上注入原始变量名：
+ *
+ *   ShellExecSpec.env —— "Ordinary environment entries for the command, merged after
+ *   the credential scrub"（@deepseek-ai/dsh-shell 类型文档）
+ *
+ * 合并顺序（dsh-bash-local 的 spawnSpec）：
+ *   { ...ENV_OVERRIDES, ...spec.env, ...spec.dshEnv }
+ * 因此本插件的值在 scrub 之后生效，同时又顶不掉 harness 自己的 `DSH_*`（那是 dshEnv）。
+ *
+ * 装载方式：profile 用户层先 `disabled: true` 掉官方 bash-sandbox 行（否则两个实现争
+ * 同一个 `shell` 服务，cordis 会报重复服务），再 insert 本模块。详见 README.md。
+ *
+ * @module dsh-shell-secrets
+ */
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+
+import { collectEnvSecrets, describeNames, readOptionsFromEnv } from './secrets.js'
+
+/** 配置前缀说明：本插件的开关都从启动环境读取，不需要额外 schema。 */
+export const OPTION_PREFIX = 'DSH_SHELL_SECRETS_'
+
+/** 本插件绑定的 harness 包：既做 peer 声明，也做下面的同源自检。 */
+export const HARNESS_PACKAGE = '@deepseek-ai/dsh-bash-sandbox'
+
+/**
+ * 从某个模块/入口出发解析 harness 包的真实路径。
+ * @param from - 模块 URL 或文件路径。
+ * @returns 真实路径；解析不到时 undefined。
+ */
+function resolveHarnessPackage(from) {
+  try {
+    return realpathSync(createRequire(from).resolve(HARNESS_PACKAGE))
+  } catch {
+    return undefined
+  }
+}
+
+/** 本模块解析到的 harness 包路径。 */
+const OWN_HARNESS_PATH = resolveHarnessPackage(import.meta.url)
+
+/**
+ * 装载期兼容性自检。
+ *
+ * 发布出去的包会装到版本各异的 dsh 上，而本插件绑的是 harness 内部接口：
+ * `SandboxBashExecutor` 的 `resolve/run/start`、以及 `ShellExecSpec.env` 的
+ * "在凭证 scrub 之后再合并"约定。这里只检查**可检测**的部分：
+ *
+ * 1. 基类是否还提供 `resolve/run/start`；
+ * 2. harness 自己用的包与本插件解析到的是不是同一份（profile 若没有
+ *    `autoInstallPeers: false`，pnpm 可能装出第二份 harness 包 → 两个 cordis 实例）。
+ *
+ * 刻意**只报错不抛异常**：自检失败时宁可让 dsh 正常启动、日志里醒目报错，也不要
+ * 因为误报把用户的 dsh 弄成起不来。真正致命的问题（导出的不是类）在 import 期就会炸。
+ * @param base - 导入到的基类。
+ * @returns 问题描述数组，空数组表示通过。
+ */
+function compatibilityIssues(base) {
+  const issues = []
+  if (typeof base !== 'function') return [`${HARNESS_PACKAGE} 的导出不是类`]
+  for (const method of ['resolve', 'run', 'start']) {
+    if (typeof base.prototype?.[method] !== 'function') {
+      issues.push(`基类缺少 ${method}()，harness 内部接口可能已变`)
+    }
+  }
+  const entry = process.argv[1]
+  if (entry !== undefined && OWN_HARNESS_PATH !== undefined) {
+    const harnessPath = resolveHarnessPackage(entry)
+    if (harnessPath !== undefined && harnessPath !== OWN_HARNESS_PATH) {
+      issues.push(`本插件解析到 ${OWN_HARNESS_PATH}，harness 自己是 ${harnessPath}，即装了两份 ${HARNESS_PACKAGE}`)
+    }
+  }
+  return issues
+}
+
+/** 自检结果（模块级算一次）。 */
+const COMPATIBILITY_ISSUES = compatibilityIssues(SandboxBashExecutor)
+
+/**
+ * 带密钥注入的 bash 执行器。
+ *
+ * 只覆写 `run`（前台）与 `start`（后台任务）两个文档化的抽象方法，其余行为
+ * （resolve 的 workdir/超时/策略、沙箱收敛、onProcessDone 的沙箱事实、sandboxMode
+ * getter）全部继承官方实现；`static Config` 同样继承，profile 行的配置项不变。
+ *
+ * 注意（踩过的坑）：**不要在这个类里用 `#private` 字段或私有方法**。cordis 的
+ * `getTraceable()` 会把服务包成 Proxy，方法调用时 `this` 被替换成 shadow 代理，
+ * 私有字段的 brand 校验会直接失败（报 "Receiver must be an instance of class ..."，
+ * 而且是每个命令都失败）。官方服务一律用普通字段/方法，照做即可。
+ */
+export class SecretsBashExecutor extends SandboxBashExecutor {
+  /**
+   * 装载期一次性快照。
+   *
+   * 密钥来源是"启动 dsh 的那个环境"，它在进程生命周期内不再变化；一次性快照让
+   * 装载日志与后续每次注入严格一致，也避免每个命令都去遍历环境变量。
+   */
+  secrets
+
+  /**
+   * @param ctx - cordis 上下文。
+   * @param config - profile 行配置（继承 LocalBashExecutor 的 schema）。
+   * @throws 当 DSH_SHELL_SECRETS_* 配置非法时：宁可启动失败，也不要静默不注入。
+   */
+  constructor(ctx, config) {
+    super(ctx, config)
+
+    try {
+      this.secrets = collectEnvSecrets(process.env, readOptionsFromEnv(process.env))
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      throw new Error(`dsh-shell-secrets: ${detail}`)
+    }
+
+    // 只记名字与原因，绝不记值。
+    this.ctx.logger.info(`dsh-shell-secrets: ${describeNames(this.secrets)}`)
+    for (const issue of COMPATIBILITY_ISSUES) {
+      this.ctx.logger.error(`dsh-shell-secrets: 兼容性自检未通过 —— ${issue}；注入可能失效，请核对 README 的「已测版本」表`)
+    }
+    if (this.secrets.names.length === 0) {
+      this.ctx.logger.warn(
+        `dsh-shell-secrets: 没有可注入的密钥变量（检查启动环境里的敏感名变量，或 ${OPTION_PREFIX}INCLUDE / ${OPTION_PREFIX}PATTERN 配置）`,
+      )
+    }
+  }
+
+  /**
+   * 把密钥并入一次执行的显式环境。
+   * @param spec - 已解析的执行规格。
+   * @returns 新的规格；无密钥时原样返回，保持热路径零分配。
+   */
+  mergeSecrets(spec) {
+    if (this.secrets.names.length === 0) return spec
+    return { ...spec, env: { ...spec.env, ...this.secrets.values } }
+  }
+
+  /**
+   * 前台执行。
+   * @param spec - 已解析的执行规格。
+   * @returns 执行结果（与官方实现同形）。
+   */
+  run(spec) {
+    return super.run(this.mergeSecrets(spec))
+  }
+
+  /**
+   * 后台任务执行（run_in_background 与 job_* 控制走这条路径）。
+   * @param spec - 已解析的执行规格。
+   * @returns 进程句柄（与官方实现同形）。
+   */
+  start(spec) {
+    return super.start(this.mergeSecrets(spec))
+  }
+}
+
+export default SecretsBashExecutor

package/lib/secrets.js

@@ -0,0 +1,202 @@
+/**
+ * dsh-shell-secrets 的密钥选择逻辑。
+ *
+ * 只做一件事：从一个环境变量快照里挑出"应当注入 bash 子进程"的密钥变量，并保持
+ * 原始变量名。纯函数、零依赖，可直接用 `node --test` 覆盖。
+ *
+ * 背景（为什么需要它）：harness 的 subprocess 层会用 `scrubbedParentEnv()` 从子进程
+ * 环境里剔除名字匹配 `/KEY|PASSWORD|SECRET|TOKEN/i` 的变量，以及所有 `DSH_*`；而
+ * `ShellExecSpec.env` 是在那次 scrub **之后**才合并进子进程环境的。所以本插件只要把
+ * 同一批变量重新放进 `spec.env`，命令里就能继续用原来的名字（$GITHUB_TOKEN 等）。
+ *
+ * @module dsh-shell-secrets/secrets
+ */
+
+/** 默认匹配：与 harness 凭证 scrub 完全同一语义，保证"被剥掉的正好被补回来"。 */
+export const DEFAULT_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i
+
+/** harness 托管命名空间前缀：ambient `DSH_*` 一律不回流，维持既有不变量。 */
+export const RESERVED_PREFIX = 'DSH_'
+
+/** 单个密钥值的默认长度上限（字节），超过则跳过，避免把整份证书塞进环境变量。 */
+export const DEFAULT_MAX_BYTES = 8192
+
+/** 实际未注入的原因码。 */
+export const SKIP_REASONS = Object.freeze({
+  disabled: 'disabled',
+  excluded: 'excluded',
+  reserved: 'reserved-namespace',
+  empty: 'empty',
+  tooLong: 'too-long',
+})
+
+/** 已注入但值得提醒的原因码。 */
+export const NOTE_REASONS = Object.freeze({ multiline: 'multiline' })
+
+/**
+ * 把 `*`/`?` 形式的名字匹配规则编译成正则。
+ * @param glob - 例如 `*_TOKEN`、`AWS_*`、`KEYBOARD_*`。
+ * @returns 大小写不敏感、整体匹配的正则。
+ * @throws 当规则不是非空字符串时。
+ */
+function compileGlob(glob) {
+  if (typeof glob !== 'string' || glob.trim().length === 0) {
+    throw new Error('名字匹配规则必须是非空字符串')
+  }
+  const source = glob
+    .trim()
+    .replace(/[.*+?^${}()|[\]\\]/g, (char) => (char === '*' || char === '?' ? char : `\\${char}`))
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.')
+  return new RegExp(`^${source}$`, 'i')
+}
+
+/**
+ * 拆分逗号分隔的规则列表。
+ * @param raw - 环境变量原始值。
+ * @returns 去掉空白项后的规则数组。
+ */
+function splitList(raw) {
+  if (typeof raw !== 'string') return []
+  return raw
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+}
+
+/**
+ * 读取布尔开关：非空即视为开启（与 harness 对 `DSH_TELEMETRY_DISABLED` 的约定一致）。
+ * @param raw - 环境变量原始值。
+ * @returns 是否开启。
+ */
+function isEnabled(raw) {
+  return typeof raw === 'string' && raw.length > 0
+}
+
+/**
+ * 从启动环境解析插件配置。
+ *
+ * 配置只来自启动环境（与"密钥只来自启动环境"一致），所有非法值在装载期抛错，
+ * 避免"静默不注入"这种最难排查的失败模式。
+ * @param env - 启动环境快照。
+ * @returns 规格化的选项对象。
+ * @throws 当正则非法或长度上限非法时。
+ */
+export function readOptionsFromEnv(env = process.env) {
+  const patternSource = env.DSH_SHELL_SECRETS_PATTERN
+  let pattern = DEFAULT_PATTERN
+  if (typeof patternSource === 'string' && patternSource.trim().length > 0) {
+    try {
+      pattern = new RegExp(patternSource, 'i')
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      throw new Error(`DSH_SHELL_SECRETS_PATTERN 不是合法正则: ${detail}`)
+    }
+  }
+
+  let maxBytes = DEFAULT_MAX_BYTES
+  const maxBytesSource = env.DSH_SHELL_SECRETS_MAX_BYTES
+  if (typeof maxBytesSource === 'string' && maxBytesSource.trim().length > 0) {
+    maxBytes = Number.parseInt(maxBytesSource, 10)
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+      throw new Error(`DSH_SHELL_SECRETS_MAX_BYTES 必须是正整数: ${maxBytesSource}`)
+    }
+  }
+
+  return {
+    pattern,
+    include: splitList(env.DSH_SHELL_SECRETS_INCLUDE),
+    exclude: splitList(env.DSH_SHELL_SECRETS_EXCLUDE),
+    maxBytes,
+    disabled: isEnabled(env.DSH_SHELL_SECRETS_DISABLE),
+  }
+}
+
+/**
+ * 从环境快照里挑出要注入的密钥变量。
+ *
+ * 选择顺序：显式 `include` 规则优先于默认正则；随后剔除 `DSH_*` 保留命名空间、
+ * `exclude` 规则、空值、超长值。未命中的变量完全忽略（不进 `skipped`，否则会把
+ * 整个环境变量表都变成诊断噪音）。
+ * @param env - 环境变量快照。
+ * @param options - {@link readOptionsFromEnv} 的结果或等价对象。
+ * @returns `{ values, names, skipped, notes }`；`values` 保持原始值不做任何修剪。
+ */
+export function collectEnvSecrets(env, options = {}) {
+  const {
+    pattern = DEFAULT_PATTERN,
+    include = [],
+    exclude = [],
+    maxBytes = DEFAULT_MAX_BYTES,
+    disabled = false,
+  } = options
+
+  if (disabled) {
+    return { values: {}, names: [], skipped: [{ name: '*', reason: SKIP_REASONS.disabled }], notes: [] }
+  }
+
+  const includeRules = include.map(compileGlob)
+  const excludeRules = exclude.map(compileGlob)
+  const selected = []
+
+  for (const [name, value] of Object.entries(env)) {
+    if (typeof value !== 'string') continue
+
+    // 未命中者直接忽略：只有"本可以被注入"的名字才值得出现在诊断里。
+    const matched = includeRules.length > 0 ? includeRules.some((rule) => rule.test(name)) : pattern.test(name)
+    if (!matched) continue
+    selected.push([name, value])
+  }
+
+  const skipped = []
+  const notes = []
+  const entries = []
+
+  for (const [name, value] of selected) {
+    if (name.toUpperCase().startsWith(RESERVED_PREFIX)) {
+      skipped.push({ name, reason: SKIP_REASONS.reserved })
+      continue
+    }
+    if (excludeRules.some((rule) => rule.test(name))) {
+      skipped.push({ name, reason: SKIP_REASONS.excluded })
+      continue
+    }
+    if (value.trim().length === 0) {
+      skipped.push({ name, reason: SKIP_REASONS.empty })
+      continue
+    }
+    if (Buffer.byteLength(value, 'utf8') > maxBytes) {
+      skipped.push({ name, reason: SKIP_REASONS.tooLong })
+      continue
+    }
+    // 换行值仍然注入（保真优先），但记一条提醒：shell 里直接展开时可能被截断。
+    if (value.includes('\n')) notes.push({ name, reason: NOTE_REASONS.multiline })
+    entries.push([name, value])
+  }
+
+  entries.sort(([left], [right]) => left.localeCompare(right))
+  return {
+    values: Object.fromEntries(entries),
+    names: entries.map(([name]) => name),
+    skipped,
+    notes,
+  }
+}
+
+/**
+ * 生成只含名字与原因的装载说明。
+ *
+ * 存在的意义就是"绝不打印值"：调用方只需把它的返回值交给日志。
+ * @param result - {@link collectEnvSecrets} 的结果。
+ * @returns 单行说明文本。
+ */
+export function describeNames(result) {
+  const parts = [`可注入密钥变量 ${result.names.length} 个: ${result.names.join(', ') || '(无)'}`]
+  if (result.skipped.length > 0) {
+    parts.push(`已跳过: ${result.skipped.map((item) => `${item.name}(${item.reason})`).join(', ')}`)
+  }
+  if (result.notes.length > 0) {
+    parts.push(`提醒: ${result.notes.map((item) => `${item.name}(${item.reason})`).join(', ')}`)
+  }
+  return parts.join(' | ')
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@lixiangzhong/dsh-shell-secrets",
+  "version": "0.1.0",
+  "description": "DSH bundle: re-inject KEY/PASSWORD/SECRET/TOKEN variables from the launching environment into dsh bash subprocesses under their original names",
+  "license": "MIT",
+  "author": "lixiangzhong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lixiangzhong/dsh-shell-secrets.git"
+  },
+  "homepage": "https://github.com/lixiangzhong/dsh-shell-secrets#readme",
+  "bugs": {
+    "url": "https://github.com/lixiangzhong/dsh-shell-secrets/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "dsh-bundle",
+    "cordis",
+    "bash",
+    "secrets",
+    "environment-variables",
+    "credentials"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./secrets": "./lib/secrets.js"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "deploy": "node deploy.mjs",
+    "check": "node deploy.mjs --check"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash-sandbox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-bash-sandbox": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}