{"_id":"@buddhilive/dsh-shell-env","name":"@buddhilive/dsh-shell-env","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-shell-env","description":"Tool-independent managed DSH_* shell environment registry","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/shell/shell-env"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-shell":"^0.1.2-alpha.3","@buddhilive/dsh-home-paths":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"dependencies":{"@deepseek-ai/schemastery":"^3.18.2"},"devDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-shell":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-home-paths":"^0.1.2-alpha.3","@buddhilive/dsh-session-persistence":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-shell-env@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-Y/+82LUTjPswdxagAcF6it+1xctaXLy5At1l2dIBiLUCV7/sGPwkIPDl1z0vdr+EipOKrKQVg0PujcQ95CKUVw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-shell-env-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-shell-env-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Y/+82LUTjPswdxagAcF6it+1xctaXLy5At1l2dIBiLUCV7/sGPwkIPDl1z0vdr+EipOKrKQVg0PujcQ95CKUVw==","shasum":"6eb51c08b67822389ff7142d027a084f1f62650e","tarball":"https://registry.npmjs.org/@buddhilive/dsh-shell-env/-/dsh-shell-env-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":30585,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFA0n47j4faW8uJbmZn1uPopoBS6JfjiPF7eY/kFfZBGAiA3TYM7N9MB8NHcSbNEh6dfFUp4dxLNBBAQhKBImfNhdQ=="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-shell-env_0.1.2-alpha.3_1788165254303_0.5609891738794139"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:34:14.155Z","0.1.2-alpha.3":"2026-08-31T08:34:14.440Z","modified":"2026-08-31T08:34:14.647Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Tool-independent managed DSH_* shell environment registry","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/shell/shell-env"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"受管 DSH_* shell 环境，供选择、配置或扩展每次模型 shell 调用所运行环境的使用者与维护者阅读。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-shell-env\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-shell-env` 提供每次模型 shell 调用——bash 或 pwsh——所运行的受信 `DSH_*` 环境：内置事实如 `DSH_HOME`、`DSH_SHELL=1` 与 agent（智能体）的 `DSH_SESSION_ID`，以及活跃持久化后端定位到 JSONL 产物时的 `DSH_SESSION_JSONL`。插件作者可以注册自己的事实，带声明键、按每次执行收集，并随插件释放；重复所有权或未声明的运行时键会响亮失败，而不是静默覆盖。注册表不会改变模型看到的其他任何内容——shell 工具拥有各自的 schema 与提示词。任何挂载了模型 shell 工具的组合都适合选择它；配置只决定 Harness 主目录。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n在任何挂载模型 shell 工具（`dsh-tool-bash` 或 `dsh-tool-pwsh`）的组合中加载本插件：此后每次前台或后台 shell 调用都会运行在新收集的受管环境中，而不是进程继承来的任意 `DSH_*` 值。\n\n### 每次 shell 调用都会收到什么\n\n每次调用都会收到 `DSH_HOME`（Harness 主目录的绝对路径）、`DSH_SHELL=1`，agent 调用还会收到 `DSH_SESSION_ID`（调用方会话的 id）。当活跃持久化后端为该会话定位到 JSONL 产物时，调用还会收到带绝对目标路径的 `DSH_SESSION_JSONL`——这只是位置提示，不是保证：首次 flush 之前文件可能不存在，也可能不包含当前缓冲中的轮次，而且该值不是授权凭据。\n\n### 添加你自己的环境事实\n\n其他插件通过注册一个 contributor 来贡献事实，需要提供稳定名称、它可能返回的完整 `DSH_*` 键集合、每个键的描述，以及为一次执行计算取值的 resolver：\n\n```ts\nimport type { Context } from '@deepseek-ai/cordis'\nimport type {} from '@buddhilive/dsh-shell-env'\n\nexport const inject = ['shellEnv']\n\nexport function apply(ctx: Context): void {\n  ctx.shellEnv.register({\n    name: 'deployment-region',\n    variables: { DSH_DEPLOYMENT_REGION: { description: 'Current deployment region.' } },\n    resolve: execution => execution.agent === undefined ? {} : { DSH_DEPLOYMENT_REGION: 'cn-north' },\n  })\n}\n```\n\ncontributor 必须声明它返回的每个键；返回未声明或非字符串的值会让该次调用失败。注册随注册插件的释放而释放，因此热重载插件会移除它的事实。\n\n### 选择 Harness 主目录\n\n唯一配置字段决定暴露为 `DSH_HOME` 的主目录；默认解析顺序为 `dshHome` 配置、环境变量 `$DSH_HOME`，然后是 `~/.dsh`。\n\n| 字段 | 默认值 | 含义 |\n|---|---|---|\n| `dshHome` | `$DSH_HOME`，然后 `~/.dsh` | 暴露为 `DSH_HOME` 的 Harness 主目录绝对路径 |\n\n生成的[配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-shell-env)是每个受支持字段及其 JSDoc 的穷尽式真源。\n\n### 可能出什么问题\n\n两个 contributor 声明同一个键，或 contributor 声称拥有保留内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`），都会让插件加载响亮失败。`DSH_*` 键必须全大写并带下划线（例如 `DSH_REGION`），缺少描述也会让注册失败。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n本节解释注册表背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。\n\n### 设计理念\n\n- **受信命名空间，每次调用重建。** 环境是归 Harness 所有的 `DSH_*` 命名空间：shell 执行器丢弃继承的 `DSH_*` 值，并为每次执行合并注册表的当前快照，因此嵌套 harness 与并发的父子 agent 无法泄漏陈旧身份，`process.env` 也永不被修改。\n- **声明的所有权，响亮的冲突。** contributor 预先声明键，使重复所有权在第一条命令之前就被发现；resolver 只能返回已声明的键。\n- **内置键留在这里。** `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID` 为注册表保留；`DSH_SESSION_JSONL` 由本插件自己的持久化翻译器贡献，它读取与后端无关的 `sessionPersistence.locate()` seam。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 插件入口、`ShellEnvRegistry` 服务、内置事实与持久化 contributor |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；收集可通过工具执行观察） |\n\n### 收集\n\n`collect(execution)` 从内置键出发，当执行携带 agent 时加入会话 id，再按 contributor 名称排序合并每个已注册 contributor 解析出的值。结果是一个冻结、按键排序的快照，通过 `ShellExecRequest.dshEnv` 传递。`list()` 枚举声明而不运行 resolver，因此无法反映依赖执行的值。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面。它们从 shell 家族逐步进入执行器 seam 与生成目录。\n\n- [shell 包映射](../README.zh.md)——bash 能力家族及其角色。\n- [Bash 执行器子系统](../../../docs/subsystems/shell.zh.md)——工具执行所经由的 `ctx.shell` seam。\n- [tool-bash](../tool-bash/README.zh.md)——消费本环境的 bash 工具。\n- [tool-pwsh](../tool-pwsh/README.zh.md)——消费本环境的 pwsh 工具。\n- [home paths 包](../../util/home-paths/README.zh.md)——`DSH_HOME` 如何解析。\n- [生成的配置目录](../../../docs/config-catalog.zh.md#buddhilivedsh-shell-env)——每个受支持配置字段及其源声明。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n通过 shell 工具（`dsh-tool-bash`、`dsh-tool-pwsh`）间接产生影响；这些工具把本注册表的受管 `DSH_*` 事实暴露在每次 shell 工具调用中。\n\n#### KV Cache 影响\n\n受管环境永远不会进入请求前缀，因此不会使提供方缓存复用失效；shell 工具的定义与当前请求信封拥有任何前缀变更。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明注册表何时不合适或需要小心使用。它们是当前包约束，不是任务积压。\n\n- **`list()` 只枚举插件贡献的变量**——注册表自有的内置键（`DSH_HOME`、`DSH_SHELL`、`DSH_SESSION_ID`）不包含在内，因此诊断、prompt 或 UI 代码不得把 `list()` 当作完整的环境目录。\n- **`DSH_SESSION_JSONL` 只是位置提示，不是保证**——首次 flush 之前文件可能不存在，也可能不包含当前缓冲中的轮次，而且该值不是授权凭据。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-9712a78cc04ebfc78ef658769b3c9c82"}