{"_id":"@buddhilive/dsh-launch-environment","name":"@buddhilive/dsh-launch-environment","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-launch-environment","description":"Immutable DeepSeek Harness launch environment that records which layer supplied each value","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/launch-environment"},"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-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-launch-environment@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-7RDKpPISIQbbkzU0MDL/psWwtax5dakybl2Jl6O4ehDk/ksJIevvFn2Dv98XY6+MEWrxTfl0P4Jb3ysSb9clQw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-launch-environment-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-launch-environment-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-7RDKpPISIQbbkzU0MDL/psWwtax5dakybl2Jl6O4ehDk/ksJIevvFn2Dv98XY6+MEWrxTfl0P4Jb3ysSb9clQw==","shasum":"24e2ebb08b9c54ff3946ceb46dd1293b0c336980","tarball":"https://registry.npmjs.org/@buddhilive/dsh-launch-environment/-/dsh-launch-environment-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":21519,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCuMzYCQMyGmJCSsti+T4X2Qc7GkM5f6cyA4dO/q7OUEQIgS+f63T7KhvcM9Cki0ckKZAr45VzCLa6Xqsi6cr/5C4s="}]},"_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-launch-environment_0.1.2-alpha.3_1788165505245_0.13190855585582106"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:38:25.118Z","0.1.2-alpha.3":"2026-08-31T08:38:25.378Z","modified":"2026-08-31T08:38:25.600Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Immutable DeepSeek Harness launch environment that records which layer supplied each value","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/util/launch-environment"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"本次运行环境的不可变快照，记住每个值来自哪一层；供必须以不信任压平 process.env 的方式解析面向用户值的包使用。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-launch-environment\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-launch-environment` 在启动时把本次运行的环境冻结为一份不可变快照，并记录每个值来自哪一层。解析一个名字会按可信度从高到低搜索各层——继承的进程环境、调用目录的 `.env`、然后是 Harness 主目录的 `.env`——因此胜出的值总是携带其来源。调用方也可以只从命名的层子集中解析，这是拒绝而非降级：无论之后信任顺序如何变化，被省略的层都不可达。这些值仍会进入 `process.env` 供配置表达式与第三方库使用，但 harness 解析任何内容都不把那份压平视图当作依据。它是一个零依赖库，由产品包直接导入；`cordis.yml` 无法加载它。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n当各层并非同等可信时，通过快照而非 `process.env` 解析面向用户的值——例如调用方绝不能从项目目录取得的凭据覆盖值。\n\n### 解析一个值\n\n```ts\nimport { launchEnvironmentOf } from '@buddhilive/dsh-launch-environment'\n\ndeclare const ctx: import('@deepseek-ai/cordis').Context\nconst endpoint = launchEnvironmentOf(ctx).get('DEEPSEEK_BASE_URL')?.value\n```\n\n`get(name)` 按可信度从高到低搜索所有层。`getFrom(name, sources)` 只搜索指定的层，不改变这一可信顺序——绝不能接受某一层的调用方不把它列进去，因此后续任何重新排序都无法让它回来。\n\n### 各层的优先级\n\n| 层 | 它是什么 |\n|---|---|\n| 继承的进程环境 | 启动 shell、CI 任务或容器传入的内容——本次运行的明确意图 |\n| `<invocation cwd>/.env` | harness 被启动于其中的项目；产品信任它配置自己的 agent（智能体） |\n| `$DSH_HOME/.env` | 用户自己的机器级默认值 |\n\n变量名按平台自身的规则匹配：POSIX 上精确匹配，Windows 上不区分大小写。在 Windows 上做大小写敏感的查找会选错层——shell 里的 `deepseek_api_key` 与项目 `.env` 里的 `DEEPSEEK_API_KEY` 对操作系统而言是同一个变量。\n\n### 没有启动器引导这棵树时\n\n当产品 CLI 引导了这棵树时，`launchEnvironmentOf(ctx)` 返回启动器的快照；否则返回只含继承环境的那一层。该回退并不削弱规则：SDK 宿主或裸 `cordis.yml` 从未发现过任何文件，因此它拥有的一切就是它被启动时的环境。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n快照建立在一个分离之上：启动器决定存在哪些文件，快照决定值如何排序。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | `createLaunchEnvironmentSnapshot`、`launchEnvironmentOf` 与 `ctx.launchEnvironment` 槽位 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；快照在任何 fiber 启动前即已冻结） |\n\n### 快照如何保持冻结\n\n`createLaunchEnvironmentSnapshot` 在构造时复制每一层的值，因此之后对源对象的修改无法改变快照。无论构造顺序如何，查找都按规范信任顺序进行；在 Windows 上，名字在存储前折叠为大写，因此大小写变体无法拆分优先级。\n\n### 省略意味着什么\n\n`getFrom` 按规范顺序过滤，绝不按调用方列表的顺序。省略一层就是拒绝：该值在该调用中不可达，这正是调用方在某个决策绝不能被某层影响时使用的机制。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当你需要构建快照的启动器或通过快照解析的消费方时，阅读以下页面。\n\n- [boot 包](../../boot/app-boot/README.zh.md)——在任何配置项挂载之前填充 `ctx.launchEnvironment` 的启动器。\n- [凭据存储](../../credentials/credentials-local/README.zh.md)——针对快照各层解析已存储的凭据。\n- [DeepSeek 提供方](../../llm/llm-deepseek/README.zh.md)——通过启动环境读取提供方配置。\n\n-----\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明快照何时不是安全边界。它们是当前包约束，不是任务积压。\n\n- **快照不是子进程边界**——每一层同样会被物化进 `process.env`，因此项目里的普通变量会按 [`dsh-subprocess`](../../subprocess/subprocess/README.zh.md) 的清洗规则抵达子进程；产品启动器的 [`.env` 约定](../../boot/app-boot/README.zh.md) 会在物化之前拒绝 bootstrap 变量。\n- **没有按工作区划分的层**——项目层是调用目录，在启动时固定；之后在 Web UI 中选择的工作区不贡献任何内容，这是刻意的，因为跟随它等于让模型自己的工作区在会话中途改变 harness 环境。\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-f4f5cb00b769e4721376bb8362bfc5c4"}