社区导读

简体中文

English

简体中文

English

外观

源文件索引：packages/util ​

本页由 study-tools/generate-source-index.mjs 根据官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec 生成，共 21 个代码或界面源文件。每个标题对应一个真实路径；用途和拆分原因是面向初学者的结构化解释，自动索引不等于人工精读。

图例 ​

本页所有条目共用以下说明：

  • 自动索引只提供定位线索，复杂行为需要回到源码和测试确认。
  • 条目中的行数、声明、结构线索和静态 import 数字是文件级定位证据，用来约束“为什么这样设计”的解释范围；它们用于定位，不替代人工源码阅读。
  • 源码链接固定到官方提交；如果当前条目与运行版本不同，应先重新生成索引再下结论。

packages/util/atomic-write/src/index.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把 packages/util/atomic-write 包里的 src/index.ts 相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“Zero-dependency atomic file replacement and writer coordination. writeFileAtomic writes a random-suffix sibling with exclusive create and the caller's permission bits, then renames it over the target, so readers observe either the old or the new complete co...”；固定提交中扫描到的声明包括 WriteFileAtomicOptions、writeFileAtomic、FileLockOptions、withFileLock、isLockContention；本地静态 import 图显示它直接依赖 0 个源文件，并被 8 个源文件直接引用。
  • 直接协作者：packages/util/atomic-write/README.md、packages/credentials/credentials-local/src/index.ts、packages/credentials/credentials-local/tests/drain.spec.ts、packages/credentials/credentials-local/tests/migration.spec.ts
  • 对应测试：packages/credentials/credentials-local/tests/drain.spec.ts、packages/credentials/credentials-local/tests/migration.spec.ts、packages/settings/settings-file/tests/local.spec.ts、packages/util/atomic-write/tests/atomic-write.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读 packages/util/atomic-write/README.md、入口和消费者，再读当前契约，沿着 packages/credentials/credentials-local/src/index.ts、packages/credentials/credentials-local/tests/drain.spec.ts、packages/credentials/credentials-local/tests/migration.spec.ts 看它怎样约束运行时，最后对照 packages/credentials/credentials-local/tests/drain.spec.ts、packages/credentials/credentials-local/tests/migration.spec.ts、packages/settings/settings-file/tests/local.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 154 行；扫描到的声明包括 WriteFileAtomicOptions、writeFileAtomic、FileLockOptions、withFileLock、isLockContention；源码顶部原注释（英文，仅作回查线索）：Zero-dependency atomic file replacement and writer coordination. writeFileAtomic writes a random-suffix sibling with exclusive create and the caller's permission bits, then renames it over the target, so readers observe either the old or the new complete co...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/atomic-write/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查 packages/util/atomic-write 包里的 src/invariant.ts 必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-atomic-write. @module @deepseek-ai/dsh-atomic-write/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/util/atomic-write/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts、packages/util/atomic-write/tests/invariant.spec.ts
  • 对应测试：packages/util/atomic-write/tests/invariant.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和 packages/util/atomic-write/tests/invariant.spec.ts 理解状态变化，最后对照 packages/util/atomic-write/tests/invariant.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 30 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-atomic-write. @module @deepseek-ai/dsh-atomic-write/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/atomic-write/tests/atomic-write.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“atomic-write”写出可重复运行的断言，覆盖的场景包括“writeFileAtomic”、“creates the file and its parents with exactly the stated mode”、“replaces existing content and narrows a wider-permission file to the stated mode”、“replaces a symlinked target itself without writing through to the referent”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“writeFileAtomic”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 scratch、waitForLock；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/atomic-write/README.md、packages/util/atomic-write/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/util/atomic-write/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 149 行；扫描到的声明包括 scratch、waitForLock；扫描到的测试主题包括 “writeFileAtomic”、“creates the file and its parents with exactly the stated mode”、“replaces existing content and narrows a wider-permission file to the stated mode”、“replaces a symlinked target itself without writing through to the referent”、“leaves no temp sibling and rethrows when the rename fails”、“withFileLock”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/atomic-write/tests/invariant.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“invariant”写出可重复运行的断言，覆盖的场景包括“atomic-write invariant companion”、“registers its explained empty runtime invariant”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“atomic-write invariant companion”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 3 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/atomic-write/README.md、packages/runtime-diagnostics/invariants/src/index.ts、packages/util/atomic-write/src/invariant.ts、vendor/cordis/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/runtime-diagnostics/invariants/src/index.ts、packages/util/atomic-write/src/invariant.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 18 行；扫描到的测试主题包括 “atomic-write invariant companion”、“registers its explained empty runtime invariant”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/brand/src/index.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把品牌类型相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“The Branded<B> nominal-typing primitive — a type-only utility (no runtime code, no harness-package dependency) shared by every package that owns a cross-boundary id. A brand makes structurally-identical strings non-interchangeable at the type level: a Sessi...”；固定提交中扫描到的声明包括 Branded；本地静态 import 图显示它直接依赖 0 个源文件，并被 33 个源文件直接引用。
  • 直接协作者：packages/util/brand/README.md、packages/attachment/attachment/src/brand.ts、packages/client/ui-conversation/src/client/input/contract.ts、packages/compaction/compaction/src/brand.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/cli/tests/memory-mcp-configs.spec.ts、apps/cli/tests/web-agent-presets.e2e.ts、apps/web/stress-tests/reasoning-chunks.stress.ts、apps/web/tests/access-confirmation.e2e.ts、apps/web/tests/agent-preset-authoring.e2e.ts、apps/web/tests/agent-preset-selection.e2e.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/util/brand/README.md、入口和消费者，再读当前契约，沿着 packages/attachment/attachment/src/brand.ts、packages/client/ui-conversation/src/client/input/contract.ts、packages/compaction/compaction/src/brand.ts 看它怎样约束运行时，最后对照 apps/cli/tests/memory-mcp-configs.spec.ts、apps/cli/tests/web-agent-presets.e2e.ts、apps/web/stress-tests/reasoning-chunks.stress.ts。
  • 代码证据：固定提交归档实际读取结果：约 27 行；扫描到的声明包括 Branded；源码顶部原注释（英文，仅作回查线索）：The Branded<B> nominal-typing primitive — a type-only utility (no runtime code, no harness-package dependency) shared by every package that owns a cross-boundary id. A brand makes structurally-identical strings non-interchangeable at the type level: a Sessi...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/brand/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查品牌类型必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-brand. @module @deepseek-ai/dsh-brand/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/brand/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 30 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-brand. @module @deepseek-ai/dsh-brand/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/home-paths/src/index.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把路径相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“Shared filesystem path helpers for DeepSeek Harness user data. @module @deepseek-ai/dsh-home-paths”；固定提交中扫描到的声明包括 DSH_HOME_DIR_NAME、DEFAULT_DSH_HOME_DISPLAY、DSH_HOME_ENV、canonicalizeWatchPath、defaultDshHome；本地静态 import 图显示它直接依赖 0 个源文件，并被 18 个源文件直接引用。
  • 直接协作者：packages/util/home-paths/README.md、apps/cli/src/profile-boot.ts、apps/web/tests/scaffold.ts、packages/attachment/attachment-local/src/index.ts
  • 对应测试：packages/util/home-paths/tests/home-paths.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读 packages/util/home-paths/README.md、入口和消费者，再读当前契约，沿着 apps/cli/src/profile-boot.ts、apps/web/tests/scaffold.ts、packages/attachment/attachment-local/src/index.ts 看它怎样约束运行时，最后对照 packages/util/home-paths/tests/home-paths.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 112 行；扫描到的声明包括 DSH_HOME_DIR_NAME、DEFAULT_DSH_HOME_DISPLAY、DSH_HOME_ENV、canonicalizeWatchPath、defaultDshHome、expandHomePath、resolveDshHome、dshHomePath；源码顶部原注释（英文，仅作回查线索）：Shared filesystem path helpers for DeepSeek Harness user data. @module @deepseek-ai/dsh-home-paths。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/home-paths/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查路径必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-home-paths. @module @deepseek-ai/dsh-home-paths/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/home-paths/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 30 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-home-paths. @module @deepseek-ai/dsh-home-paths/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/home-paths/tests/home-paths.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查路径的具体场景，包括“dsh path helpers”、“owns the shared default DSH home directory name”、“expands tilde paths without changing non-tilde paths”、“resolves explicit path before DSH_HOME and the default”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“dsh path helpers”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/home-paths/README.md、packages/util/home-paths/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/util/home-paths/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 76 行；扫描到的测试主题包括 “dsh path helpers”、“owns the shared default DSH home directory name”、“expands tilde paths without changing non-tilde paths”、“resolves explicit path before DSH_HOME and the default”、“treats an empty or whitespace-only DSH_HOME as unset”、“joins child segments onto the resolved DSH_HOME”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/launch-environment/src/index.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把 packages/util/launch-environment 包里的 src/index.ts 相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“Immutable launch-time environment snapshot that records which layer supplied each value. Harness consumers resolve through it instead of a flattened process.env; launchers may still materialize accepted values for config expressions and third-party librarie...”；固定提交中扫描到的声明包括 LaunchEnvironmentSource、LaunchEnvironmentEntry、LaunchEnvironmentSnapshot、LaunchEnvironmentLayerInput、createLaunchEnvironmentSnapshot；本地静态 import 图显示它直接依赖 1 个源文件，并被 14 个源文件直接引用。
  • 直接协作者：packages/util/launch-environment/README.md、vendor/cordis/src/index.ts、apps/cli/src/profile-boot.ts、packages/boot/app-boot/src/index.ts、packages/bundle/web-app/src/index.ts
  • 对应测试：packages/bundle/web-app/tests/web-app.spec.ts、packages/credentials/credentials-local/tests/local.spec.ts、packages/llm/llm-deepseek/tests/adapter.spec.ts、packages/util/launch-environment/tests/launch-environment.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/llm/llm-deepseek/tests/assemble.ts、packages/llm/llm-deepseek/tests/mock-server.ts
  • 阅读顺序：先读 packages/util/launch-environment/README.md、入口和消费者，再读当前契约，沿着 apps/cli/src/profile-boot.ts、packages/boot/app-boot/src/index.ts、packages/bundle/web-app/src/index.ts 看它怎样约束运行时，最后对照 packages/bundle/web-app/tests/web-app.spec.ts、packages/credentials/credentials-local/tests/local.spec.ts、packages/llm/llm-deepseek/tests/adapter.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 124 行；扫描到的声明包括 LaunchEnvironmentSource、LaunchEnvironmentEntry、LaunchEnvironmentSnapshot、LaunchEnvironmentLayerInput、createLaunchEnvironmentSnapshot、DSH_LAUNCH_ENVIRONMENT_KEY、launchEnvironmentOf、lookupKey；源码顶部原注释（英文，仅作回查线索）：Immutable launch-time environment snapshot that records which layer supplied each value. Harness consumers resolve through it instead of a flattened process.env; launchers may still materialize accepted values for config expressions and third-party librarie...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/launch-environment/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查 packages/util/launch-environment 包里的 src/invariant.ts 必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-launch-environment. @module @deepseek-ai/dsh-launch-environment/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/launch-environment/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 30 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-launch-environment. @module @deepseek-ai/dsh-launch-environment/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/launch-environment/tests/launch-environment.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“launch-environment”写出可重复运行的断言，覆盖的场景包括“createLaunchEnvironmentSnapshot”、“resolves across every layer, most trusted first, and reports the winning source”、“filters layers without changing their trust order”、“copies each layer, so a later mutation of the source object cannot change it”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“createLaunchEnvironmentSnapshot”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/launch-environment/README.md、packages/util/launch-environment/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/util/launch-environment/src/index.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 69 行；扫描到的测试主题包括 “createLaunchEnvironmentSnapshot”、“resolves across every layer, most trusted first, and reports the winning source”、“filters layers without changing their trust order”、“copies each layer, so a later mutation of the source object cannot change it”、“keeps an empty value as a present value, for its owner to judge”、“orders lookups canonically regardless of construction order”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/native-command/src/index.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把原生边界相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“Shared no-shell execFile runner for host-native OS integrations (the native directory chooser, the open-with-default-application hand-off): utf8 stdio capture, abort propagation, Windows console hide. A library, not a plugin — no ctx, no state, no events. @...”；固定提交中扫描到的声明包括 NativeCommandRunner、runNativeCommand；本地静态 import 图显示它直接依赖 0 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/util/native-command/README.md、packages/host/apiproxy/src/native-path-opener.ts、packages/host/directory-picker-native/src/native-picker.ts、packages/util/native-command/tests/native-command.spec.ts
  • 对应测试：packages/util/native-command/tests/native-command.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读 packages/util/native-command/README.md、入口和消费者，再读当前契约，沿着 packages/host/apiproxy/src/native-path-opener.ts、packages/host/directory-picker-native/src/native-picker.ts、packages/util/native-command/tests/native-command.spec.ts 看它怎样约束运行时，最后对照 packages/util/native-command/tests/native-command.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 44 行；扫描到的声明包括 NativeCommandRunner、runNativeCommand；源码顶部原注释（英文，仅作回查线索）：Shared no-shell execFile runner for host-native OS integrations (the native directory chooser, the open-with-default-application hand-off): utf8 stdio capture, abort propagation, Windows console hide. A library, not a plugin — no ctx, no state, no events. @...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/native-command/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查原生边界必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-native-command. @module @deepseek-ai/dsh-native-command/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/native-command/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 31 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-native-command. @module @deepseek-ai/dsh-native-command/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/native-command/tests/native-command.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查原生边界的具体场景，包括“runNativeCommand”、“captures utf8 stdout and stderr on exit 0”、“rejects a non-zero exit with code, stdout, and stderr attached”、“rejects a missing executable with the spawn ENOENT code”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“runNativeCommand”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/native-command/README.md、packages/util/native-command/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/util/native-command/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 43 行；扫描到的测试主题包括 “runNativeCommand”、“captures utf8 stdout and stderr on exit 0”、“rejects a non-zero exit with code, stdout, and stderr attached”、“rejects a missing executable with the spawn ENOENT code”、“terminates the child when the signal aborts”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/output-retention/src/index.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把 packages/util/output-retention 包里的 src/index.ts 相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“A dependency-light retention library: bounded model-facing output for tools that must cap how much context they return. A caller feeds items or text chunks into a bounded object, then gets the retained content plus exact omission metadata (RetainedItems...”；固定提交中扫描到的声明包括 Omitted、PushDecision、RetainedItems、RetainedText、ItemRetentionStrategy；本地静态 import 图显示它直接依赖 0 个源文件，并被 8 个源文件直接引用。
  • 直接协作者：packages/util/output-retention/README.md、packages/context/session-reference/src/projection.ts、packages/fs/tool-fs-search/src/grep.ts、packages/fs/tool-fs-search/src/presentation.ts
  • 对应测试：packages/util/output-retention/tests/output-retention.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读 packages/util/output-retention/README.md、入口和消费者，再读当前契约，沿着 packages/context/session-reference/src/projection.ts、packages/fs/tool-fs-search/src/grep.ts、packages/fs/tool-fs-search/src/presentation.ts 看它怎样约束运行时，最后对照 packages/util/output-retention/tests/output-retention.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 443 行；扫描到的声明包括 Omitted、PushDecision、RetainedItems、RetainedText、ItemRetentionStrategy、TextRetentionStrategy、RetentionNotice、ItemRetainer；源码顶部原注释（英文，仅作回查线索）：A dependency-light retention library: bounded model-facing output for tools that must cap how much context they return. A caller feeds items or text chunks into a bounded object, then gets the retained content plus exact omission metadata (RetainedItems...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/output-retention/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查 packages/util/output-retention 包里的 src/invariant.ts 必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-output-retention. @module @deepseek-ai/dsh-output-retention/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/output-retention/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 30 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-output-retention. @module @deepseek-ai/dsh-output-retention/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/output-retention/tests/output-retention.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“output-retention”写出可重复运行的断言，覆盖的场景包括“ItemRetainer — head retention”、“keeps the first maxItems while callers keep draining for an exact omitted count”、“reports none when everything fits”、“keeps draining past the cap and reports an exact omitted count”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“ItemRetainer — head retention”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/output-retention/README.md、packages/util/output-retention/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/util/output-retention/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 376 行；扫描到的测试主题包括 “ItemRetainer — head retention”、“keeps the first maxItems while callers keep draining for an exact omitted count”、“reports none when everything fits”、“keeps draining past the cap and reports an exact omitted count”、“ItemRetainer — zero budget”、“keeps nothing and counts every pushed item as omitted”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/timeout/src/index.ts ​

packages/util/timeout/src/invariant.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查 packages/util/timeout 包里的 src/invariant.ts 必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-timeout. @module @deepseek-ai/dsh-timeout/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/timeout/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 30 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-timeout. @module @deepseek-ai/dsh-timeout/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/util/timeout/tests/timeout.spec.ts ​

  • 所属层：packages/util：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“timeout”写出可重复运行的断言，覆盖的场景包括“TimeoutReason”、“is an Error carrying the code and elapsed ms”、“clampTimeout”、“fills the default when the hint is absent”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“TimeoutReason”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/util/timeout/README.md、packages/util/timeout/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/util/timeout/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 291 行；扫描到的测试主题包括 “TimeoutReason”、“is an Error carrying the code and elapsed ms”、“clampTimeout”、“fills the default when the hint is absent”、“caps the hint at max”、“keeps a valid hint under the cap”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。