7.1 KiB
description, kind
| description | kind |
|---|---|
| 受管 DSH_* shell 环境，供选择、配置或扩展每次模型 shell 调用所运行环境的使用者与维护者阅读。 | package-reference |
@deepseek-ai/dsh-shell-env
English | 中文
概述
dsh-shell-env 提供每次模型 shell 调用——bash 或 pwsh——所运行的受信 DSH_* 环境：内置事实如 DSH_HOME、DSH_SHELL=1 与 agent（智能体）的 DSH_SESSION_ID，以及活跃持久化后端定位到 JSONL 产物时的 DSH_SESSION_JSONL。插件作者可以注册自己的事实，带声明键、按每次执行收集，并随插件释放；重复所有权或未声明的运行时键会响亮失败，而不是静默覆盖。注册表不会改变模型看到的其他任何内容——shell 工具拥有各自的 schema 与提示词。任何挂载了模型 shell 工具的组合都适合选择它；配置只决定 Harness 主目录。
目录
使用本包
在任何挂载模型 shell 工具（dsh-tool-bash 或 dsh-tool-pwsh）的组合中加载本插件：此后每次前台或后台 shell 调用都会运行在新收集的受管环境中，而不是进程继承来的任意 DSH_* 值。
每次 shell 调用都会收到什么
每次调用都会收到 DSH_HOME（Harness 主目录的绝对路径）、DSH_SHELL=1，agent 调用还会收到 DSH_SESSION_ID（调用方会话的 id）。当活跃持久化后端为该会话定位到 JSONL 产物时，调用还会收到带绝对目标路径的 DSH_SESSION_JSONL——这只是位置提示，不是保证：首次 flush 之前文件可能不存在，也可能不包含当前缓冲中的轮次，而且该值不是授权凭据。
添加你自己的环境事实
其他插件通过注册一个 contributor 来贡献事实，需要提供稳定名称、它可能返回的完整 DSH_* 键集合、每个键的描述，以及为一次执行计算取值的 resolver：
import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-shell-env'
export const inject = ['shellEnv']
export function apply(ctx: Context): void {
ctx.shellEnv.register({
name: 'deployment-region',
variables: { DSH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },
resolve: execution => execution.agent === undefined ? {} : { DSH_DEPLOYMENT_REGION: 'cn-north' },
})
}
contributor 必须声明它返回的每个键；返回未声明或非字符串的值会让该次调用失败。注册随注册插件的释放而释放，因此热重载插件会移除它的事实。
选择 Harness 主目录
唯一配置字段决定暴露为 DSH_HOME 的主目录；默认解析顺序为 dshHome 配置、环境变量 $DSH_HOME，然后是 ~/.dsh。
| 字段 | 默认值 | 含义 |
|---|---|---|
dshHome |
$DSH_HOME，然后 ~/.dsh |
暴露为 DSH_HOME 的 Harness 主目录绝对路径 |
生成的配置目录是每个受支持字段及其 JSDoc 的穷尽式真源。
可能出什么问题
两个 contributor 声明同一个键，或 contributor 声称拥有保留内置键（DSH_HOME、DSH_SHELL、DSH_SESSION_ID），都会让插件加载响亮失败。DSH_* 键必须全大写并带下划线（例如 DSH_REGION），缺少描述也会让注册失败。
理解实现
实现细节——点击展开
本节解释注册表背后的设计决策，并指出实现它们的代码位置；可观察行为已在使用本包中完整说明。
设计理念
- 受信命名空间，每次调用重建。 环境是归 Harness 所有的
DSH_*命名空间：shell 执行器丢弃继承的DSH_*值，并为每次执行合并注册表的当前快照，因此嵌套 harness 与并发的父子 agent 无法泄漏陈旧身份，process.env也永不被修改。 - 声明的所有权，响亮的冲突。 contributor 预先声明键，使重复所有权在第一条命令之前就被发现；resolver 只能返回已声明的键。
- 内置键留在这里。
DSH_HOME、DSH_SHELL与DSH_SESSION_ID为注册表保留；DSH_SESSION_JSONL由本插件自己的持久化翻译器贡献，它读取与后端无关的sessionPersistence.locate()seam。
源码地图
| 文件 | 职责 |
|---|---|
src/index.ts |
插件入口、ShellEnvRegistry 服务、内置事实与持久化 contributor |
src/invariant.ts |
不变式伴生插件（无运行时不变式；收集可通过工具执行观察） |
收集
collect(execution) 从内置键出发，当执行携带 agent 时加入会话 id，再按 contributor 名称排序合并每个已注册 contributor 解析出的值。结果是一个冻结、按键排序的快照，通过 ShellExecRequest.dshEnv 传递。list() 枚举声明而不运行 resolver，因此无法反映依赖执行的值。
进一步探索
当包级约定不够用时阅读以下页面。它们从 shell 家族逐步进入执行器 seam 与生成目录。
- shell 包映射——bash 能力家族及其角色。
- Bash 执行器子系统——工具执行所经由的
ctx.shellseam。 - tool-bash——消费本环境的 bash 工具。
- tool-pwsh——消费本环境的 pwsh 工具。
- home paths 包——
DSH_HOME如何解析。 - 生成的配置目录——每个受支持配置字段及其源声明。
模型体验
通过 shell 工具（dsh-tool-bash、dsh-tool-pwsh）间接产生影响；这些工具把本注册表的受管 DSH_* 事实暴露在每次 shell 工具调用中。
KV Cache 影响
受管环境永远不会进入请求前缀，因此不会使提供方缓存复用失效；shell 工具的定义与当前请求信封拥有任何前缀变更。
已知限制与延期工作
这些限制说明注册表何时不合适或需要小心使用。它们是当前包约束，不是任务积压。
list()只枚举插件贡献的变量——注册表自有的内置键（DSH_HOME、DSH_SHELL、DSH_SESSION_ID）不包含在内，因此诊断、prompt 或 UI 代码不得把list()当作完整的环境目录。DSH_SESSION_JSONL只是位置提示，不是保证——首次 flush 之前文件可能不存在，也可能不包含当前缓冲中的轮次，而且该值不是授权凭据。
开发备注
维护者的工作上下文——点击展开
无。