源文件索引：packages/shell

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

图例

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

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

条目按所属包分组：packages/shell/bash-local（4 条）、packages/shell/bash-sandbox（8 条）、packages/shell/pwsh-local（5 条）、packages/shell/pwsh-sandbox（5 条）、packages/shell/shell-env（3 条）、packages/shell/shell（6 条）、packages/shell/tool-bash-persistent（4 条）、packages/shell/tool-bash（6 条）、packages/shell/tool-pwsh-persistent（4 条）、packages/shell/tool-pwsh（7 条）。

packages/shell/bash-local

packages/shell/bash-local/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Local Service Provider for the bash capability seam over the subprocess capability seam. Public commands run as bash -c in a managed process group spawned through ctx.subprocess; subclasses may reuse the same mechanics with an explicit argv. This executor o...”；固定提交中扫描到的声明包括 ENV_OVERRIDES、Config、assertServiceableBashConfig、LocalBashExecutor、finalOutput；本地静态 import 图显示它直接依赖 6 个源文件，并被 15 个源文件直接引用。
直接协作者：packages/shell/bash-local/README.md、packages/settings/settings/src/index.ts、packages/shell/shell/src/index.ts、packages/subprocess/subprocess/src/index.ts、examples/headless-agent/tests/code-mode.e2e.ts
对应测试：examples/headless-agent/tests/code-mode.e2e.ts、packages/examples/agent-spine-demo/tests/agent-core.spec.ts、packages/hooks/hooks-claude-code/tests/bridge.spec.ts、packages/hooks/hooks-codex/tests/bridge.spec.ts、packages/shell/bash-local/tests/executor.spec.ts、packages/shell/bash-local/tests/settings.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：packages/core/agent-loop/tests/mock-adapter.ts
阅读顺序：先读 packages/shell/bash-local/README.md、入口和消费者，再读当前契约，沿着 examples/headless-agent/tests/code-mode.e2e.ts、examples/headless-agent/tests/fixtures/e2b/e2b/bin.ts、examples/headless-agent/tests/harness.ts 看它怎样约束运行时，最后对照 examples/headless-agent/tests/code-mode.e2e.ts、packages/examples/agent-spine-demo/tests/agent-core.spec.ts、packages/hooks/hooks-claude-code/tests/bridge.spec.ts。
代码证据：固定提交归档实际读取结果：约 333 行；扫描到的声明包括 ENV_OVERRIDES、Config、assertServiceableBashConfig、LocalBashExecutor、finalOutput、assertPositiveFinite；源码顶部原注释（英文，仅作回查线索）：Local Service Provider for the bash capability seam over the subprocess capability seam. Public commands run as bash -c in a managed process group spawned through ctx.subprocess; subclasses may reuse the same mechanics with an explicit argv. This executor o...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-local/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-bash-local. @module @deepseek-ai/dsh-bash-local/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-local/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-bash-local. @module @deepseek-ai/dsh-bash-local/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-local/tests/executor.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令的具体场景，包括“LocalBashExecutor.run”、“resolves with output and the effective timeout”、“uses config cwd, overridable per call”、“defaults cwd to process.cwd()”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“LocalBashExecutor.run”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 setup、readUntil；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-local/README.md、packages/shell/bash-local/src/index.ts、packages/shell/shell/src/index.ts、packages/subprocess/subprocess-local/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/shell/bash-local/src/index.ts、packages/shell/shell/src/index.ts、packages/subprocess/subprocess-local/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 349 行；扫描到的声明包括 setup、readUntil；扫描到的测试主题包括 “LocalBashExecutor.run”、“resolves with output and the effective timeout”、“uses config cwd, overridable per call”、“defaults cwd to process.cwd()”、“caps per-call timeouts at maxTimeoutMs”、“rejects invalid numeric config and timeout overrides”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-local/tests/settings.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令的具体场景，包括“bash settings section”、“resolves the user layer over the composition entry”、“refuses a stored value the constructor would have rejected”、“refuses a grace period longer than a timer can carry”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“bash settings section”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“The bash settings section layered over the executor's composition entry.”；固定提交中扫描到的声明包括 MemorySettings、boot；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-local/README.md、packages/settings/settings/src/index.ts、packages/shell/bash-local/src/index.ts、packages/shell/shell/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/settings/settings/src/index.ts、packages/shell/bash-local/src/index.ts、packages/shell/shell/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 115 行；扫描到的声明包括 MemorySettings、boot；扫描到的测试主题包括 “bash settings section”、“resolves the user layer over the composition entry”、“refuses a stored value the constructor would have rejected”、“refuses a grace period longer than a timer can carry”、“serves the stored section to every later read”、“falls back to the composition entry when the settings provider detaches”；源码顶部原注释（英文，仅作回查线索）：The bash settings section layered over the executor's composition entry.。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox

packages/shell/bash-sandbox/src/helpers.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：共享小工具
这个文件有什么用：这个文件放一个跨模块复用的小能力。把它单独放置可以减少重复，但它不应偷偷承担业务流程。
为什么这样设计：固定提交的文件顶部注释把它定位为“Internal sandbox-result classification helpers. @module @deepseek-ai/dsh-bash-sandbox/helpers”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
文件级设计证据：源码顶部注释把它定位为“Internal sandbox-result classification helpers. @module @deepseek-ai/dsh-bash-sandbox/helpers”；固定提交中扫描到的声明包括 isRunnerSpawnFailure、classifyDenial、classifyRunnerFailure、matchesSignature、isUsableWorkdir；本地静态 import 图显示它直接依赖 2 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、packages/sandbox/sandbox/src/index.ts、packages/shell/shell/src/index.ts、packages/shell/bash-sandbox/src/index.ts、packages/shell/bash-sandbox/tests/sandbox.spec.ts
对应测试：packages/shell/bash-sandbox/tests/sandbox.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/bash-sandbox/README.md 和入口，再读当前实现，沿着 packages/sandbox/sandbox/src/index.ts、packages/shell/shell/src/index.ts 和 packages/shell/bash-sandbox/src/index.ts、packages/shell/bash-sandbox/tests/sandbox.spec.ts 确认输入输出，最后对照 packages/shell/bash-sandbox/tests/sandbox.spec.ts。
代码证据：固定提交归档实际读取结果：约 116 行；扫描到的声明包括 isRunnerSpawnFailure、classifyDenial、classifyRunnerFailure、matchesSignature、isUsableWorkdir；源码顶部原注释（英文，仅作回查线索）：Internal sandbox-result classification helpers. @module @deepseek-ai/dsh-bash-sandbox/helpers。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令、沙箱相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Sandbox-consuming bash executor. It wraps the exact local bash argv through ctx.sandbox, inherits local process mechanics, and reports the selected mode, enforcement, and denial facts. Positive runner-launch evidence means the command never ran: foreground ...”；固定提交中扫描到的声明包括 Config、SandboxBashExecutor；本地静态 import 图显示它直接依赖 6 个源文件，并被 6 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts、packages/shell/bash-local/src/index.ts、packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts
对应测试：packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts、packages/shell/bash-sandbox/tests/bwrap.e2e.ts、packages/shell/bash-sandbox/tests/landlock.e2e.ts、packages/shell/bash-sandbox/tests/partial-landlock.spec.ts、packages/shell/bash-sandbox/tests/sandbox.spec.ts、packages/shell/bash-sandbox/tests/seatbelt.e2e.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/bash-sandbox/README.md、入口和消费者，再读当前契约，沿着 packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts、packages/shell/bash-sandbox/tests/bwrap.e2e.ts、packages/shell/bash-sandbox/tests/landlock.e2e.ts 看它怎样约束运行时，最后对照 packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts、packages/shell/bash-sandbox/tests/bwrap.e2e.ts、packages/shell/bash-sandbox/tests/landlock.e2e.ts。
代码证据：固定提交归档实际读取结果：约 182 行；扫描到的声明包括 Config、SandboxBashExecutor；源码顶部原注释（英文，仅作回查线索）：Sandbox-consuming bash executor. It wraps the exact local bash argv through ctx.sandbox, inherits local process mechanics, and reports the selected mode, enforcement, and denial facts. Positive runner-launch evidence means the command never ran: foreground ...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令、沙箱必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-bash-sandbox. @module @deepseek-ai/dsh-bash-sandbox/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/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-bash-sandbox. @module @deepseek-ai/dsh-bash-sandbox/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/tests/bwrap.e2e.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“read-only denies a write — the file must NOT exist, and EROFS text classifies as a denial”、“workspace-write lands a write inside the workspace root and still denies one beside it”、“classifies a background denial once the task settles”、“an approved escalated retry — the spec-level workspace-write override — lands the exact...”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“read-only denies a write — the file must NOT exist, and EROFS text classifies as a denial”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 tempDir、sandboxedBash；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-local/src/profiles.ts、packages/sandbox/sandbox-policy/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-local/src/profiles.ts、packages/sandbox/sandbox-policy/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 99 行；扫描到的声明包括 tempDir、sandboxedBash；扫描到的测试主题包括 “read-only denies a write — the file must NOT exist, and EROFS text classifies as a denial”、“workspace-write lands a write inside the workspace root and still denies one beside it”、“classifies a background denial once the task settles”、“an approved escalated retry — the spec-level workspace-write override — lands the exact write read-only denied”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/tests/landlock.e2e.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“read-only denies a write — the file must NOT exist, the result carries denial + enforce...”、“workspace-write lands a write inside the workspace root and still denies one beside it”、“classifies a background denial once the task settles”、“an approved escalated retry — the spec-level workspace-write override — lands the exact...”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“read-only denies a write — the file must NOT exist, the result carries denial + enforce...”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 tempDir、sandboxedBash；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、native/landlock-run/packages/entry/src/index.ts、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-policy/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 native/landlock-run/packages/entry/src/index.ts、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-policy/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 104 行；扫描到的声明包括 tempDir、sandboxedBash；扫描到的测试主题包括 “read-only denies a write — the file must NOT exist, the result carries denial + enforcement facts”、“workspace-write lands a write inside the workspace root and still denies one beside it”、“classifies a background denial once the task settles”、“an approved escalated retry — the spec-level workspace-write override — lands the exact write read-only denied”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/tests/partial-landlock.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“partial Landlock runner-failure classification”、“keeps a real malformed executable ordinary across no-shebang spawn behavior”、“reports the fatal line after the notice as SANDBOX_UNAVAILABLE detail”、“classifies a notice plus child Permission denied as a denial, not runner failure”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“partial Landlock runner-failure classification”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Deterministic real-process proofs for runner classification: the real local provider and sandbox bash executor exercise direct runner-spawn failures and a POSIX fake Landlock launcher that prints its notice before exec.”；固定提交中扫描到的声明包括 fakeLauncher、setup、setupConfiguredRunner；本地静态 import 图显示它直接依赖 7 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、native/landlock-run/packages/entry/src/index.ts、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-policy/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 native/landlock-run/packages/entry/src/index.ts、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-policy/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 270 行；扫描到的声明包括 fakeLauncher、setup、setupConfiguredRunner；扫描到的测试主题包括 “partial Landlock runner-failure classification”、“keeps a real malformed executable ordinary across no-shebang spawn behavior”、“reports the fatal line after the notice as SANDBOX_UNAVAILABLE detail”、“classifies a notice plus child Permission denied as a denial, not runner failure”、“applies the same evidence rule to notice-only background exits”、“classifies a background notice plus child Permission denied as denial”；源码顶部原注释（英文，仅作回查线索）：Deterministic real-process proofs for runner classification: the real local provider and sandbox bash executor exercise direct runner-spawn failures and a POSIX fake Landlock launcher that prints its notice before exec.。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/tests/sandbox.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“the provider hand-off”、“hands the provider the exact bash argv and the per-call policy, and runs the returned argv”、“hands the provider\”、“starts a non-Bash runner before the confined inner Bash evaluates BASH_ENV”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“the provider hand-off”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Consumer-side SandboxBashExecutor tests. A fake Cordis sandbox service makes wrapping, policy hand-off, fail-closed propagation, classification, and fact stamping deterministic; real-provider integration lives in tests/landlock.e2e.ts. A mode-0555 directory...”；固定提交中扫描到的声明包括 setup、FakeSandboxProvider、output、runResult、executionPolicy；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts、packages/shell/bash-sandbox/src/helpers.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts、packages/shell/bash-sandbox/src/helpers.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 658 行；扫描到的声明包括 setup、FakeSandboxProvider、output、runResult、executionPolicy；扫描到的测试主题包括 “the provider hand-off”、“hands the provider the exact bash argv and the per-call policy, and runs the returned argv”、“hands the provider\”、“starts a non-Bash runner before the confined inner Bash evaluates BASH_ENV”、“workspace-write rides the policy, workspaceRoot falling back to process.cwd() when not configured”、“an explicit workspaceRoot on the policy wins”；源码顶部原注释（英文，仅作回查线索）：Consumer-side SandboxBashExecutor tests. A fake Cordis sandbox service makes wrapping, policy hand-off, fail-closed propagation, classification, and fact stamping deterministic; real-provider integration lives in tests/landlock.e2e.ts. A mode-0555 directory...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/bash-sandbox/tests/seatbelt.e2e.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“read-only denies a write — the file must NOT exist, and EPERM text classifies as a denial”、“workspace-write lands a write inside the workspace root and still denies one beside it”、“evaluates BASH_ENV only after Seatbelt confines the inner Bash”、“classifies a background denial once the task settles”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“read-only denies a write — the file must NOT exist, and EPERM text classifies as a denial”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 tempDir、sandboxedBash；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/bash-sandbox/README.md、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-local/src/profiles.ts、packages/sandbox/sandbox-policy/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-local/src/profiles.ts、packages/sandbox/sandbox-policy/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 127 行；扫描到的声明包括 tempDir、sandboxedBash；扫描到的测试主题包括 “read-only denies a write — the file must NOT exist, and EPERM text classifies as a denial”、“workspace-write lands a write inside the workspace root and still denies one beside it”、“evaluates BASH_ENV only after Seatbelt confines the inner Bash”、“classifies a background denial once the task settles”、“an approved escalated retry — the spec-level workspace-write override — lands the exact write read-only denied”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-local

packages/shell/pwsh-local/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Local PowerShell Service Provider for the bash capability seam. Each command runs as pwsh -NoLogo -NoProfile -NonInteractive -Command <command> in a managed process spawned through ctx.subprocess; the executor owns command defaulting, deadlines and cause cl...”；固定提交中扫描到的声明包括 ENV_OVERRIDES、ENCODING_PREAMBLE、Config、assertServiceablePwshConfig、PwshLocalExecutor；本地静态 import 图显示它直接依赖 7 个源文件，并被 14 个源文件直接引用。
直接协作者：packages/shell/pwsh-local/README.md、packages/settings/settings/src/index.ts、packages/shell/pwsh-local/src/resolve.ts、packages/shell/shell/src/index.ts、apps/web/tests/pwsh-terminal.e2e.ts
对应测试：apps/web/tests/pwsh-terminal.e2e.ts、examples/acp-agent/tests/acp.snapshot.ts、packages/sandbox/sandbox-windows-acl/tests/runner.spec.ts、packages/shell/pwsh-local/tests/executor.spec.ts、packages/shell/pwsh-local/tests/settings.spec.ts、packages/shell/pwsh-sandbox/tests/acl.e2e.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：apps/web/tests/scaffold.ts、apps/web/tests/support.ts
阅读顺序：先读 packages/shell/pwsh-local/README.md、入口和消费者，再读当前契约，沿着 apps/web/tests/pwsh-terminal.e2e.ts、examples/acp-agent/tests/acp.snapshot.ts、packages/sandbox/sandbox-windows-acl/tests/runner.spec.ts 看它怎样约束运行时，最后对照 apps/web/tests/pwsh-terminal.e2e.ts、examples/acp-agent/tests/acp.snapshot.ts、packages/sandbox/sandbox-windows-acl/tests/runner.spec.ts。
代码证据：固定提交归档实际读取结果：约 363 行；扫描到的声明包括 ENV_OVERRIDES、ENCODING_PREAMBLE、Config、assertServiceablePwshConfig、PwshLocalExecutor、finalOutput、assertPositiveFinite；源码顶部原注释（英文，仅作回查线索）：Local PowerShell Service Provider for the bash capability seam. Each command runs as pwsh -NoLogo -NoProfile -NonInteractive -Command <command> in a managed process spawned through ctx.subprocess; the executor owns command defaulting, deadlines and cause cl...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-local/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-pwsh-local. @module @deepseek-ai/dsh-pwsh-local/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/pwsh-local/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-pwsh-local. @module @deepseek-ai/dsh-pwsh-local/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-local/src/resolve.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：Shell 执行实现
这个文件有什么用：这个文件把 Shell 命令、PowerShell 或输出处理接到统一的进程和工具边界。
为什么这样设计：Shell 差异限制在执行包内，命令、环境、输出和取消可以通过统一工具协议提供给 Agent。
文件级设计证据：源码顶部注释把它定位为“PowerShell executable resolution, dependency-free so non-package consumers (the repository's coverage-gate probe in vitest.config.ts) can share the ONE resolution definition with the executor and its suites — a probe that resolved differently from the code ...”；固定提交中扫描到的声明包括 candidatePwshPaths、resolvePwshPath、candidateExists；本地静态 import 图显示它直接依赖 0 个源文件，并被 4 个源文件直接引用。
直接协作者：packages/shell/pwsh-local/README.md、packages/shell/pwsh-local/src/index.ts、packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/terminal/terminal-bash/tests/local.spec.ts
对应测试：packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/terminal/terminal-bash/tests/local.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/pwsh-local/README.md 和入口，再读当前实现，沿着相关类型、协议或实现和 packages/shell/pwsh-local/src/index.ts、packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/terminal/terminal-bash/tests/local.spec.ts 确认输入输出，最后对照 packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/terminal/terminal-bash/tests/local.spec.ts。
代码证据：固定提交归档实际读取结果：约 79 行；扫描到的声明包括 candidatePwshPaths、resolvePwshPath、candidateExists；源码顶部原注释（英文，仅作回查线索）：PowerShell executable resolution, dependency-free so non-package consumers (the repository's coverage-gate probe in vitest.config.ts) can share the ONE resolution definition with the executor and its suites — a probe that resolved differently from the code ...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-local/tests/executor.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令的具体场景，包括“resolvePwshPath and candidatePwshPaths (pure, every platform)”、“trusts an explicit configured path verbatim”、“falls through an empty configured path to platform resolution”、“returns pwsh on non-Windows platforms regardless of the environment”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“resolvePwshPath and candidatePwshPaths (pure, every platform)”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Real-process tests for @deepseek-ai/dsh-pwsh-local: the LOCAL subprocess service plus a REAL pwsh executable, exercised through the executor seam (resolve → run/start). These verify the world — actual PowerShell runs, output capture, truncation and spill, d...”；固定提交中扫描到的声明包括 samePath、setup、readUntil、CapturingSubprocessRuntime；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/pwsh-local/README.md、packages/shell/pwsh-local/src/index.ts、packages/shell/shell/src/index.ts、packages/subprocess/subprocess-local/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/shell/pwsh-local/src/index.ts、packages/shell/shell/src/index.ts、packages/subprocess/subprocess-local/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 498 行；扫描到的声明包括 samePath、setup、readUntil、CapturingSubprocessRuntime；扫描到的测试主题包括 “resolvePwshPath and candidatePwshPaths (pure, every platform)”、“trusts an explicit configured path verbatim”、“falls through an empty configured path to platform resolution”、“returns pwsh on non-Windows platforms regardless of the environment”、“uses stable Windows roots when the environment omits both overrides”、“lists PowerShell 7, PATH entries (quotes stripped), then Windows PowerShell 5.1 on win32”；源码顶部原注释（英文，仅作回查线索）：Real-process tests for @deepseek-ai/dsh-pwsh-local: the LOCAL subprocess service plus a REAL pwsh executable, exercised through the executor seam (resolve → run/start). These verify the world — actual PowerShell runs, output capture, truncation and spill, d...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-local/tests/settings.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令的具体场景，包括“pwsh executor over the bash settings section”、“resolves the user layer over the composition entry”、“refuses a stored value the constructor would have rejected”、“re-resolves the executable when the stored path changes”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“pwsh executor over the bash settings section”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“The shared bash settings section as the pwsh executor family resolves it.”；固定提交中扫描到的声明包括 MemorySettings、boot；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/pwsh-local/README.md、packages/settings/settings/src/index.ts、packages/shell/pwsh-local/src/index.ts、packages/shell/shell/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/settings/settings/src/index.ts、packages/shell/pwsh-local/src/index.ts、packages/shell/shell/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 108 行；扫描到的声明包括 MemorySettings、boot；扫描到的测试主题包括 “pwsh executor over the bash settings section”、“resolves the user layer over the composition entry”、“refuses a stored value the constructor would have rejected”、“re-resolves the executable when the stored path changes”、“keeps the resolved executable when an unrelated field changes”、“falls back to the composition entry when the settings provider detaches”；源码顶部原注释（英文，仅作回查线索）：The shared bash settings section as the pwsh executor family resolves it.。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-sandbox

packages/shell/pwsh-sandbox/src/helpers.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：共享小工具
这个文件有什么用：这个文件放一个跨模块复用的小能力。把它单独放置可以减少重复，但它不应偷偷承担业务流程。
为什么这样设计：固定提交的文件顶部注释把它定位为“Internal sandbox-result classification helpers — deliberate call-for-call mirror of @deepseek-ai/dsh-bash-sandbox/src/helpers.ts (the pwsh twin of the bash consumer shares the identical classification dialect). @module @deepseek-ai/dsh-pwsh-sandbox/helpers”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
文件级设计证据：源码顶部注释把它定位为“Internal sandbox-result classification helpers — deliberate call-for-call mirror of @deepseek-ai/dsh-bash-sandbox/src/helpers.ts (the pwsh twin of the bash consumer shares the identical classification dialect). @module @deepseek-ai/dsh-pwsh-sandbox/helpers”；固定提交中扫描到的声明包括 isRunnerSpawnFailure、classifyDenial、classifyRunnerFailure、matchesSignature、isUsableWorkdir；本地静态 import 图显示它直接依赖 2 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/pwsh-sandbox/README.md、packages/sandbox/sandbox/src/index.ts、packages/shell/shell/src/index.ts、packages/shell/pwsh-sandbox/src/index.ts、packages/shell/pwsh-sandbox/tests/sandbox.spec.ts
对应测试：packages/shell/pwsh-sandbox/tests/sandbox.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/pwsh-sandbox/README.md 和入口，再读当前实现，沿着 packages/sandbox/sandbox/src/index.ts、packages/shell/shell/src/index.ts 和 packages/shell/pwsh-sandbox/src/index.ts、packages/shell/pwsh-sandbox/tests/sandbox.spec.ts 确认输入输出，最后对照 packages/shell/pwsh-sandbox/tests/sandbox.spec.ts。
代码证据：固定提交归档实际读取结果：约 120 行；扫描到的声明包括 isRunnerSpawnFailure、classifyDenial、classifyRunnerFailure、matchesSignature、isUsableWorkdir；源码顶部原注释（英文，仅作回查线索）：Internal sandbox-result classification helpers — deliberate call-for-call mirror of @deepseek-ai/dsh-bash-sandbox/src/helpers.ts (the pwsh twin of the bash consumer shares the identical classification dialect). @module @deepseek-ai/dsh-pwsh-sandbox/helpers。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-sandbox/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令、沙箱相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Sandbox-consuming PowerShell executor — the pwsh twin of @deepseek-ai/dsh-bash-sandbox. It wraps the exact local pwsh argv through ctx.sandbox (which on Windows resolves to the ACL restricted-token runner chain), inherits local process mechanics, and report...”；固定提交中扫描到的声明包括 Config、SandboxPwshExecutor；本地静态 import 图显示它直接依赖 6 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/pwsh-sandbox/README.md、packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts、packages/shell/pwsh-local/src/index.ts、packages/shell/pwsh-sandbox/tests/acl.e2e.ts
对应测试：packages/shell/pwsh-sandbox/tests/acl.e2e.ts、packages/shell/pwsh-sandbox/tests/sandbox.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/pwsh-sandbox/README.md、入口和消费者，再读当前契约，沿着 packages/shell/pwsh-sandbox/tests/acl.e2e.ts、packages/shell/pwsh-sandbox/tests/sandbox.spec.ts 看它怎样约束运行时，最后对照 packages/shell/pwsh-sandbox/tests/acl.e2e.ts、packages/shell/pwsh-sandbox/tests/sandbox.spec.ts。
代码证据：固定提交归档实际读取结果：约 189 行；扫描到的声明包括 Config、SandboxPwshExecutor；源码顶部原注释（英文，仅作回查线索）：Sandbox-consuming PowerShell executor — the pwsh twin of @deepseek-ai/dsh-bash-sandbox. It wraps the exact local pwsh argv through ctx.sandbox (which on Windows resolves to the ACL restricted-token runner chain), inherits local process mechanics, and report...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-sandbox/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令、沙箱必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-pwsh-sandbox. @module @deepseek-ai/dsh-pwsh-sandbox/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/pwsh-sandbox/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-pwsh-sandbox. @module @deepseek-ai/dsh-pwsh-sandbox/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-sandbox/tests/acl.e2e.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“read-only: ordinary path writes denied, reads fine, partial and denial facts ride the r...”、“workspace-write: workspace and private temp writable, ambient temp and escape denied”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“read-only: ordinary path writes denied, reads fine, partial and denial facts ride the r...”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Real-backend end-to-end: LocalSandboxProvider (win32 chain → the windows-acl runner), SandboxPolicyService, and SandboxPwshExecutor with REAL pwsh spawns confined through the runner — the debug-instance verification of both modes on ordinary user-owned path...”；固定提交中扫描到的声明包括 pwshAvailable；本地静态 import 图显示它直接依赖 7 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/pwsh-sandbox/README.md、packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/sandbox/sandbox-local/src/index.ts、packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 117 行；扫描到的声明包括 pwshAvailable；扫描到的测试主题包括 “read-only: ordinary path writes denied, reads fine, partial and denial facts ride the result”、“workspace-write: workspace and private temp writable, ambient temp and escape denied”；源码顶部原注释（英文，仅作回查线索）：Real-backend end-to-end: LocalSandboxProvider (win32 chain → the windows-acl runner), SandboxPolicyService, and SandboxPwshExecutor with REAL pwsh spawns confined through the runner — the debug-instance verification of both modes on ordinary user-owned path...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/pwsh-sandbox/tests/sandbox.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、沙箱的具体场景，包括“helpers (pure)”、“isRunnerSpawnFailure”、“attributes ENOENT/EACCES with argv[0] provenance and a usable workdir”、“rejects mismatched provenance, foreign codes, unusable workdirs, and non-object errors”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“helpers (pure)”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Consumer-side SandboxPwshExecutor tests. A fake Cordis sandbox service makes wrapping, policy hand-off, fail-closed propagation, and fact stamping deterministic; real-provider integration lives in tests/acl.e2e.ts. Requires pwsh for the integration block (s...”；固定提交中扫描到的声明包括 pwshAvailable、throwingSubprocessRuntime、setup、FakeSandboxProvider；本地静态 import 图显示它直接依赖 7 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/pwsh-sandbox/README.md、packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts、packages/shell/pwsh-local/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/sandbox/sandbox-policy/src/index.ts、packages/sandbox/sandbox/src/index.ts、packages/shell/pwsh-local/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 326 行；扫描到的声明包括 pwshAvailable、throwingSubprocessRuntime、setup、FakeSandboxProvider；扫描到的测试主题包括 “helpers (pure)”、“isRunnerSpawnFailure”、“attributes ENOENT/EACCES with argv[0] provenance and a usable workdir”、“rejects mismatched provenance, foreign codes, unusable workdirs, and non-object errors”、“classifyRunnerFailure”、“matches a fatal signature on a gated exit code, skipping informational lines”；源码顶部原注释（英文，仅作回查线索）：Consumer-side SandboxPwshExecutor tests. A fake Cordis sandbox service makes wrapping, policy hand-off, fail-closed propagation, and fact stamping deterministic; real-provider integration lives in tests/acl.e2e.ts. Requires pwsh for the integration block (s...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell-env

packages/shell/shell-env/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Tool-independent shell environment plugin: owns the ctx.shellEnv registry of trusted, per-execution DSH_* variables consumed by the model-facing shell tools (dsh-tool-bash, dsh-tool-pwsh). Built-in shell facts are owned by the registry itself while plugins ...”；固定提交中扫描到的声明包括 name、inject、Config、BashEnvVariable、BashEnvContributor；本地静态 import 图显示它直接依赖 6 个源文件，并被 13 个源文件直接引用。
直接协作者：packages/shell/shell-env/README.md、packages/core/tools/src/index.ts、packages/session/session-persistence/src/index.ts、packages/shell/shell/src/index.ts、examples/headless-agent/tests/code-mode.e2e.ts
对应测试：examples/headless-agent/tests/code-mode.e2e.ts、packages/shell/shell-env/tests/shell-env.spec.ts、packages/shell/tool-bash/tests/integration.spec.ts、packages/shell/tool-bash/tests/tools.spec.ts、packages/shell/tool-pwsh/tests/integration.spec.ts、packages/shell/tool-pwsh/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：packages/core/agent-loop/tests/mock-adapter.ts
阅读顺序：先读 packages/shell/shell-env/README.md、入口和消费者，再读当前契约，沿着 examples/headless-agent/tests/code-mode.e2e.ts、examples/headless-agent/tests/harness.ts、packages/bundle/web-app/src/index.ts 看它怎样约束运行时，最后对照 examples/headless-agent/tests/code-mode.e2e.ts、packages/shell/shell-env/tests/shell-env.spec.ts、packages/shell/tool-bash/tests/integration.spec.ts。
代码证据：固定提交归档实际读取结果：约 217 行；扫描到的声明包括 name、inject、Config、BashEnvVariable、BashEnvContributor、BashEnvVariableInfo、ShellEnvRegistry、apply；源码顶部原注释（英文，仅作回查线索）：Tool-independent shell environment plugin: owns the ctx.shellEnv registry of trusted, per-execution DSH_* variables consumed by the model-facing shell tools (dsh-tool-bash, dsh-tool-pwsh). Built-in shell facts are owned by the registry itself while plugins ...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell-env/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-shell-env. @module @deepseek-ai/dsh-shell-env/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/shell-env/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-shell-env. @module @deepseek-ai/dsh-shell-env/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell-env/tests/shell-env.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令的具体场景，包括“ShellEnvRegistry”、“collects unconditional shell facts and the current agent session id”、“resolves DSH_HOME from the ambient override or the user-home default”、“collects declared contributor variables and omits unavailable values”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“ShellEnvRegistry”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Registry tests for @deepseek-ai/dsh-shell-env: built-in facts, contributor ownership and validation, collection ordering, effect-scoped disposal, and the explicit disposer contract.”；固定提交中扫描到的声明包括 execution；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/shell-env/README.md、packages/core/agent/src/index.ts、packages/core/tools/src/index.ts、packages/llm/llm/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/tools/src/index.ts、packages/llm/llm/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 238 行；扫描到的声明包括 execution；扫描到的测试主题包括 “ShellEnvRegistry”、“collects unconditional shell facts and the current agent session id”、“resolves DSH_HOME from the ambient override or the user-home default”、“collects declared contributor variables and omits unavailable values”、“rejects duplicate variable ownership at registration time”、“rejects duplicate contributor names and malformed declarations”；源码顶部原注释（英文，仅作回查线索）：Registry tests for @deepseek-ai/dsh-shell-env: built-in facts, contributor ownership and validation, collection ordering, effect-scoped disposal, and the explicit disposer contract.。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell

packages/shell/shell/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Service Definition for the ctx.shell capability seam, covering foreground commands and background process handles. Job ids, ownership, polling, and notices belong to @deepseek-ai/dsh-jobs, keeping executors independent of sessions. @module @deepseek-ai/dsh-...”；固定提交中扫描到的声明包括 SHELL_SETTINGS_NAMESPACE；本地静态 import 图显示它直接依赖 5 个源文件，并被 26 个源文件直接引用。
直接协作者：packages/shell/shell/README.md、packages/sandbox/sandbox/src/index.ts、packages/settings/settings/src/index.ts、packages/shell/shell/src/render.ts、packages/context/tmux-context/src/index.ts
对应测试：packages/context/tmux-context/tests/tmux-context.spec.ts、packages/hooks/hook-protocol/tests/runner.spec.ts、packages/shell/bash-local/tests/executor.spec.ts、packages/shell/bash-local/tests/settings.spec.ts、packages/shell/bash-sandbox/tests/sandbox.spec.ts、packages/shell/pwsh-local/tests/executor.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/shell/README.md、入口和消费者，再读当前契约，沿着 packages/context/tmux-context/src/index.ts、packages/context/tmux-context/tests/tmux-context.spec.ts、packages/hooks/hook-protocol/src/runner.ts 看它怎样约束运行时，最后对照 packages/context/tmux-context/tests/tmux-context.spec.ts、packages/hooks/hook-protocol/tests/runner.spec.ts、packages/shell/bash-local/tests/executor.spec.ts。
代码证据：固定提交归档实际读取结果：约 103 行；扫描到的声明包括 SHELL_SETTINGS_NAMESPACE；源码顶部原注释（英文，仅作回查线索）：Service Definition for the ctx.shell capability seam, covering foreground commands and background process handles. Job ids, ownership, polling, and notices belong to @deepseek-ai/dsh-jobs, keeping executors independent of sessions. @module @deepseek-ai/dsh-...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for the bash seam. @module @deepseek-ai/dsh-shell/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/shell/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 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
代码证据：固定提交归档实际读取结果：约 22 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for the bash seam. @module @deepseek-ai/dsh-shell/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell/src/render.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：呈现转换
这个文件有什么用：它把 Shell 命令、渲染转换成界面或终端可以消费的呈现结构，执行逻辑因此不需要知道具体 UI 组件。
为什么这样设计：领域事实和可见表示分开，CLI、Web 或其他宿主可以各自渲染同一份结果；执行代码也不会被 UI 细节反向污染。
文件级设计证据：源码顶部注释把它定位为“Shared rendering helpers for the shell tools (dsh-tool-bash, dsh-tool-pwsh): the exit-status marker contract the tools' renderers emit and the presentation layer parses back. @module @deepseek-ai/dsh-shell/render”；固定提交中扫描到的声明包括 ParsedExitStatus、parseExitStatus；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/shell/README.md、packages/shell/shell/src/index.ts、packages/shell/shell/tests/render.spec.ts
对应测试：packages/shell/shell/tests/render.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/shell/shell/src/index.ts、packages/shell/shell/tests/render.spec.ts 确认状态如何进入 UI，最后对照 packages/shell/shell/tests/render.spec.ts。
代码证据：固定提交归档实际读取结果：约 42 行；扫描到的声明包括 ParsedExitStatus、parseExitStatus；源码顶部原注释（英文，仅作回查线索）：Shared rendering helpers for the shell tools (dsh-tool-bash, dsh-tool-pwsh): the exit-status marker contract the tools' renderers emit and the presentation layer parses back. @module @deepseek-ai/dsh-shell/render。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell/src/types.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：类型契约
这个文件有什么用：它描述 Shell 命令中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
文件级设计证据：源码顶部注释把它定位为“Execution types for the bash executor seam. Background job semantics belong to @deepseek-ai/dsh-jobs; this seam exposes only process handles. The managed-environment and captured-output vocabulary is owned by the subprocess seam and re-exported here so bash...”；固定提交中扫描到的声明包括 ShellSandboxInfo、ShellExecRequest、ShellExecSpec、ShellRunResult、ShellProcessStatus；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
直接协作者：packages/shell/shell/README.md、packages/sandbox/sandbox/src/index.ts、packages/subprocess/subprocess/src/index.ts、packages/shell/shell/src/index.ts
对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/pwsh-terminal.e2e.ts、apps/web/tests/shipped-composition.e2e.ts、examples/acp-agent/tests/acp.snapshot.ts、examples/headless-agent/tests/code-mode.e2e.ts、examples/headless-agent/tests/coding-task.e2e.ts、examples/headless-agent/tests/compaction.e2e.ts
测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
阅读顺序：先读 packages/shell/shell/README.md、入口和消费者，再读当前契约，沿着 packages/shell/shell/src/index.ts 看它怎样约束运行时，最后对照 apps/web/tests/pwsh-terminal.e2e.ts、apps/web/tests/shipped-composition.e2e.ts、examples/acp-agent/tests/acp.snapshot.ts。
代码证据：固定提交归档实际读取结果：约 183 行；扫描到的声明包括 ShellSandboxInfo、ShellExecRequest、ShellExecSpec、ShellRunResult、ShellProcessStatus、ShellProcessRead、ShellProcess；源码顶部原注释（英文，仅作回查线索）：Execution types for the bash executor seam. Background job semantics belong to @deepseek-ai/dsh-jobs; this seam exposes only process handles. The managed-environment and captured-output vocabulary is owned by the subprocess seam and re-exported here so bash...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell/tests/render.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、渲染的具体场景，包括“parseExitStatus”、“recovers a clean exit 0 with the body verbatim when no marker is present”、“recovers a non-zero exit and strips only its marker from the body”、“recovers a signal kill ahead of any non-zero exit marker”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“parseExitStatus”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Shared exit-status parse contract: the inverse of the exit code: N / killed by signal: X markers dsh-tool-bash and dsh-tool-pwsh append. Both tools' presenter suites round-trip their own renderers through this parse; this spec pins the parse's own edges (ma...”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/shell/README.md、packages/shell/shell/src/render.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/shell/shell/src/render.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 36 行；扫描到的测试主题包括 “parseExitStatus”、“recovers a clean exit 0 with the body verbatim when no marker is present”、“recovers a non-zero exit and strips only its marker from the body”、“recovers a signal kill ahead of any non-zero exit marker”、“keeps markers no pill shows (timeout) in the body”；源码顶部原注释（英文，仅作回查线索）：Shared exit-status parse contract: the inverse of the exit code: N / killed by signal: X markers dsh-tool-bash and dsh-tool-pwsh append. Both tools' presenter suites round-trip their own renderers through this parse; this spec pins the parse's own edges (ma...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/shell/tests/service.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令的具体场景，包括“ShellExecutor service seam”、“a concrete subclass registers as ctx.shell and serves the abstract API”、“reports no default sandbox mode from the task-free base seam”、“loading a second implementation throws (one bash service per context — cordis standard)”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“ShellExecutor service seam”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 StubExecutor、SecondExecutor；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/shell/README.md、packages/shell/shell/src/index.ts、vendor/cordis/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/shell/shell/src/index.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 84 行；扫描到的声明包括 StubExecutor、SecondExecutor；扫描到的测试主题包括 “ShellExecutor service seam”、“a concrete subclass registers as ctx.shell and serves the abstract API”、“reports no default sandbox mode from the task-free base seam”、“loading a second implementation throws (one bash service per context — cordis standard)”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash-persistent

packages/shell/tool-bash-persistent/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令、工具相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Model-facing persistent bash tool over the owner-scoped PTY seam. @module @deepseek-ai/dsh-tool-bash-persistent”；固定提交中扫描到的声明包括 name、inject、Config、apply、maybeTruncate；本地静态 import 图显示它直接依赖 6 个源文件，并被 3 个源文件直接引用。
直接协作者：packages/shell/tool-bash-persistent/README.md、packages/core/agent/src/index.ts、packages/core/tools/src/index.ts、packages/terminal/terminal/src/index.ts、packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts
对应测试：packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts、packages/shell/tool-bash-persistent/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/tool-bash-persistent/README.md、入口和消费者，再读当前契约，沿着 packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts、packages/shell/tool-bash-persistent/tests/tools.spec.ts、scripts/gen-tool-catalog.ts 看它怎样约束运行时，最后对照 packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts、packages/shell/tool-bash-persistent/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 472 行；扫描到的声明包括 name、inject、Config、apply、maybeTruncate、markers、quoteForBash、wrapCommand；源码顶部原注释（英文，仅作回查线索）：Model-facing persistent bash tool over the owner-scoped PTY seam. @module @deepseek-ai/dsh-tool-bash-persistent。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash-persistent/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令、工具必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-tool-bash-persistent. @module @deepseek-ai/dsh-tool-bash-persistent/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-bash-persistent/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-tool-bash-persistent. @module @deepseek-ai/dsh-tool-bash-persistent/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash-persistent/tests/loader-composition.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“preserves cwd and environment across calls”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“preserves cwd and environment across calls”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 PassthroughSandbox、agent、text；本地静态 import 图显示它直接依赖 14 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-bash-persistent/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 170 行；扫描到的声明包括 PassthroughSandbox、agent、text；扫描到的测试主题包括 “preserves cwd and environment across calls”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash-persistent/tests/tools.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“tool-bash-persistent”、“registers a configurable schema and reuses one owner shell”、“handles inferred idle, stdin_read fallback, shell exit, clipping, and cleanup”、“waits for status digits after a torn completion marker”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“tool-bash-persistent”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 agent、text、call、StubPtySession、stubBackend；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-bash-persistent/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 601 行；扫描到的声明包括 agent、text、call、StubPtySession、stubBackend、setup；扫描到的测试主题包括 “tool-bash-persistent”、“registers a configurable schema and reuses one owner shell”、“handles inferred idle, stdin_read fallback, shell exit, clipping, and cleanup”、“waits for status digits after a torn completion marker”、“reports the exit path when the shell exits between send settlement and the next poll”、“reports a shell exit when the backend has no code or signal”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash

packages/shell/tool-bash/src/background.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：工具能力
这个文件有什么用：它提供 Shell 命令、工具的一项可调用能力，通常同时处理参数、执行和结果展示；独立工具让权限和测试可以逐项控制。
为什么这样设计：固定提交的文件顶部注释把它定位为“Generic-task adaptation for background bash process handles. @module @deepseek-ai/dsh-tool-bash/background”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
文件级设计证据：源码顶部注释把它定位为“Generic-task adaptation for background bash process handles. @module @deepseek-ai/dsh-tool-bash/background”；固定提交中扫描到的声明包括 processOutcome；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/tool-bash/README.md、packages/shell/shell/src/index.ts、packages/shell/tool-bash/src/index.ts、packages/shell/tool-bash/tests/tools.spec.ts
对应测试：packages/shell/tool-bash/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/tool-bash/README.md 和入口，再读当前实现，沿着 packages/shell/shell/src/index.ts 和 packages/shell/tool-bash/src/index.ts、packages/shell/tool-bash/tests/tools.spec.ts 确认输入输出，最后对照 packages/shell/tool-bash/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 27 行；扫描到的声明包括 processOutcome；源码顶部原注释（英文，仅作回查线索）：Generic-task adaptation for background bash process handles. @module @deepseek-ai/dsh-tool-bash/background。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令、工具相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Model-facing Consumer of the ctx.shell capability seam. Background calls register process handles with ctx.jobs; their work uses job cancellation rather than the tool-call signal after an id is returned. TODO(permissions): deployment policy belongs in tools...”；固定提交中扫描到的声明包括 name、inject、Config、apply、validateBashArgs；本地静态 import 图显示它直接依赖 14 个源文件，并被 7 个源文件直接引用。
直接协作者：packages/shell/tool-bash/README.md、packages/core/agent/src/index.ts、packages/core/system-prompt/src/index.ts、packages/core/tools/src/index.ts、examples/headless-agent/tests/code-mode.e2e.ts
对应测试：examples/headless-agent/tests/code-mode.e2e.ts、packages/shell/tool-bash/tests/integration.spec.ts、packages/shell/tool-bash/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：packages/core/agent-loop/tests/mock-adapter.ts
阅读顺序：先读 packages/shell/tool-bash/README.md、入口和消费者，再读当前契约，沿着 examples/headless-agent/tests/code-mode.e2e.ts、examples/headless-agent/tests/harness.ts、packages/examples/agent-spine-demo/src/index.ts 看它怎样约束运行时，最后对照 examples/headless-agent/tests/code-mode.e2e.ts、packages/shell/tool-bash/tests/integration.spec.ts、packages/shell/tool-bash/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 394 行；扫描到的声明包括 name、inject、Config、apply、validateBashArgs、bashDescription、presentBashCall、presentBashResult；源码顶部原注释（英文，仅作回查线索）：Model-facing Consumer of the ctx.shell capability seam. Background calls register process handles with ctx.jobs; their work uses job cancellation rather than the tool-call signal after an id is returned. TODO(permissions): deployment policy belongs in tools...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令、工具必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-tool-bash. @module @deepseek-ai/dsh-tool-bash/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-bash/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-tool-bash. @module @deepseek-ai/dsh-tool-bash/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash/src/render.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：呈现转换
这个文件有什么用：它把 Shell 命令、工具、渲染转换成界面或终端可以消费的呈现结构，执行逻辑因此不需要知道具体 UI 组件。
为什么这样设计：领域事实和可见表示分开，CLI、Web 或其他宿主可以各自渲染同一份结果；执行代码也不会被 UI 细节反向污染。
文件级设计证据：源码顶部注释把它定位为“Model-facing result rendering for the bash tool. @module @deepseek-ai/dsh-tool-bash/render”；固定提交中扫描到的声明包括 renderResult、renderProcessRead、streamText；本地静态 import 图显示它直接依赖 2 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/tool-bash/README.md、packages/sandbox/sandbox/src/index.ts、packages/shell/shell/src/index.ts、packages/shell/tool-bash/src/index.ts、packages/shell/tool-bash/tests/tools.spec.ts
对应测试：packages/shell/tool-bash/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/shell/tool-bash/src/index.ts、packages/shell/tool-bash/tests/tools.spec.ts 确认状态如何进入 UI，最后对照 packages/shell/tool-bash/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 103 行；扫描到的声明包括 renderResult、renderProcessRead、streamText；源码顶部原注释（英文，仅作回查线索）：Model-facing result rendering for the bash tool. @module @deepseek-ai/dsh-tool-bash/render。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash/tests/integration.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“bash tool through the agent loop”、“first-turn bash receives session identity before the lazy JSONL file materializes”、“foreground: model calls bash, sees the result, replies”、“foreground: non-zero exit is reported in the result text, not as isError”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“bash tool through the agent loop”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 harness、waitForIdle、events、findEvent、resultText；本地静态 import 图显示它直接依赖 14 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-bash/README.md、packages/core/agent-loop/src/index.ts、packages/core/agent-loop/tests/mock-adapter.ts、packages/core/agent/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
测试支持：packages/core/agent-loop/tests/mock-adapter.ts
阅读顺序：先看它直接导入的被测实现 packages/core/agent-loop/src/index.ts、packages/core/agent/src/index.ts、packages/core/session/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 242 行；扫描到的声明包括 harness、waitForIdle、events、findEvent、resultText、pollUntil；扫描到的测试主题包括 “bash tool through the agent loop”、“first-turn bash receives session identity before the lazy JSONL file materializes”、“foreground: model calls bash, sees the result, replies”、“foreground: non-zero exit is reported in the result text, not as isError”、“background: start ack → completion wakes the idle agent → job_output collects it”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-bash/tests/tools.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“bash tool”、“returns stdout for a successful command”、“reports (no output) for silent commands”、“marks stderr sections”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“bash tool”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 setup、setupWithTasks、registerFakeAgent、call、text；本地静态 import 图显示它直接依赖 18 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-bash/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 1279 行；扫描到的声明包括 setup、setupWithTasks、registerFakeAgent、call、text、callUntilText、RecordingSandboxExecutor、CountingStartExecutor；扫描到的测试主题包括 “bash tool”、“returns stdout for a successful command”、“reports (no output) for silent commands”、“marks stderr sections”、“reports non-zero exits without isError”、“reports timeout kills with both markers (timeout first)”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh-persistent

packages/shell/tool-pwsh-persistent/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令、工具相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“jscpd:ignore-start -- deliberate mirror of tool-bash-persistent (persistent-pty note 2026-08-11-pwsh-persistent-pty): the PowerShell counterpart shares the session registry, polling loop, and reset contract by design.”；固定提交中扫描到的声明包括 name、inject、Config、apply、maybeTruncate；本地静态 import 图显示它直接依赖 6 个源文件，并被 3 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh-persistent/README.md、packages/core/agent/src/index.ts、packages/core/tools/src/index.ts、packages/terminal/terminal/src/index.ts、packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts
对应测试：packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/shell/tool-pwsh-persistent/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/tool-pwsh-persistent/README.md、入口和消费者，再读当前契约，沿着 packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/shell/tool-pwsh-persistent/tests/tools.spec.ts、scripts/gen-tool-catalog.ts 看它怎样约束运行时，最后对照 packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts、packages/shell/tool-pwsh-persistent/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 514 行；扫描到的声明包括 name、inject、Config、apply、maybeTruncate、markers、quoteForPwsh、wrapCommand；源码顶部原注释（英文，仅作回查线索）：jscpd:ignore-start -- deliberate mirror of tool-bash-persistent (persistent-pty note 2026-08-11-pwsh-persistent-pty): the PowerShell counterpart shares the session registry, polling loop, and reset contract by design.。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh-persistent/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令、工具必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-tool-pwsh-persistent. @module @deepseek-ai/dsh-tool-pwsh-persistent/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh-persistent/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-tool-pwsh-persistent. @module @deepseek-ai/dsh-tool-pwsh-persistent/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“preserves cwd and environment across calls”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“preserves cwd and environment across calls”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 PassthroughSandbox、agent、text；本地静态 import 图显示它直接依赖 15 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh-persistent/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 167 行；扫描到的声明包括 PassthroughSandbox、agent、text；扫描到的测试主题包括 “preserves cwd and environment across calls”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh-persistent/tests/tools.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“tool-pwsh-persistent”、“registers a configurable schema and reuses one owner shell”、“strips the echoed wrapper from captured output”、“preserves command output that equals the private shell prompt”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“tool-pwsh-persistent”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 agent、text、call、StubTerminalSession、stubBackend；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh-persistent/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 636 行；扫描到的声明包括 agent、text、call、StubTerminalSession、stubBackend、setup；扫描到的测试主题包括 “tool-pwsh-persistent”、“registers a configurable schema and reuses one owner shell”、“strips the echoed wrapper from captured output”、“preserves command output that equals the private shell prompt”、“reports the exit path when the shell exits between send settlement and the next poll”、“handles inferred idle, prompt fallback, shell exit, clipping, and cleanup”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh

packages/shell/tool-pwsh/src/background.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：工具能力
这个文件有什么用：它提供 Shell 命令、工具的一项可调用能力，通常同时处理参数、执行和结果展示；独立工具让权限和测试可以逐项控制。
为什么这样设计：固定提交的文件顶部注释把它定位为“Generic-task adaptation for background pwsh process handles — the shell-agnostic twin of dsh-tool-bash's background adaptation. @module @deepseek-ai/dsh-tool-pwsh/background”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
文件级设计证据：源码顶部注释把它定位为“Generic-task adaptation for background pwsh process handles — the shell-agnostic twin of dsh-tool-bash's background adaptation. @module @deepseek-ai/dsh-tool-pwsh/background”；固定提交中扫描到的声明包括 processOutcome；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/README.md、packages/shell/shell/src/index.ts、packages/shell/tool-pwsh/src/index.ts、packages/shell/tool-pwsh/tests/tools.spec.ts
对应测试：packages/shell/tool-pwsh/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/tool-pwsh/README.md 和入口，再读当前实现，沿着 packages/shell/shell/src/index.ts 和 packages/shell/tool-pwsh/src/index.ts、packages/shell/tool-pwsh/tests/tools.spec.ts 确认输入输出，最后对照 packages/shell/tool-pwsh/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 31 行；扫描到的声明包括 processOutcome；源码顶部原注释（英文，仅作回查线索）：Generic-task adaptation for background pwsh process handles — the shell-agnostic twin of dsh-tool-bash's background adaptation. @module @deepseek-ai/dsh-tool-pwsh/background。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh/src/index.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把 Shell 命令、工具相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Model-facing PowerShell Consumer of the ctx.shell capability seam. Intended for Windows compositions where a PowerShell executor (e.g. @deepseek-ai/dsh-pwsh-local) backs ctx.shell; the tool contract is PowerShell-dialect: native C:... paths and $env:NAME v...”；固定提交中扫描到的声明包括 name、inject、Config、apply、validatePwshArgs；本地静态 import 图显示它直接依赖 14 个源文件，并被 3 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/README.md、packages/core/agent/src/index.ts、packages/core/system-prompt/src/index.ts、packages/core/tools/src/index.ts、packages/shell/tool-pwsh/tests/integration.spec.ts
对应测试：packages/shell/tool-pwsh/tests/integration.spec.ts、packages/shell/tool-pwsh/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/shell/tool-pwsh/README.md、入口和消费者，再读当前契约，沿着 packages/shell/tool-pwsh/tests/integration.spec.ts、packages/shell/tool-pwsh/tests/tools.spec.ts、scripts/gen-tool-catalog.ts 看它怎样约束运行时，最后对照 packages/shell/tool-pwsh/tests/integration.spec.ts、packages/shell/tool-pwsh/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 446 行；扫描到的声明包括 name、inject、Config、apply、validatePwshArgs、pwshDescription、resolveWorkdir、canonicalPwshResult；源码顶部原注释（英文，仅作回查线索）：Model-facing PowerShell Consumer of the ctx.shell capability seam. Intended for Windows compositions where a PowerShell executor (e.g. @deepseek-ai/dsh-pwsh-local) backs ctx.shell; the tool contract is PowerShell-dialect: native C:... paths and $env:NAME v...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh/src/invariant.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：运行时不变量
这个文件有什么用：它检查 Shell 命令、工具必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-tool-pwsh. @module @deepseek-ai/dsh-tool-pwsh/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/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-tool-pwsh. @module @deepseek-ai/dsh-tool-pwsh/invariant。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh/src/render.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：呈现转换
这个文件有什么用：它把 Shell 命令、工具、渲染转换成界面或终端可以消费的呈现结构，执行逻辑因此不需要知道具体 UI 组件。
为什么这样设计：领域事实和可见表示分开，CLI、Web 或其他宿主可以各自渲染同一份结果；执行代码也不会被 UI 细节反向污染。
文件级设计证据：源码顶部注释把它定位为“Model-facing result rendering for the pwsh tool — the PowerShell twin of dsh-tool-bash's renderer: stdout, a marked stderr section, sandbox denial/runner-failure markers (with the same-turn escalation hint), and truncation notices with spill paths, then exi...”；固定提交中扫描到的声明包括 RenderablePwshResult、renderPwshResult、renderPwshProcessRead、streamText；本地静态 import 图显示它直接依赖 2 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/README.md、packages/sandbox/sandbox/src/index.ts、packages/shell/shell/src/index.ts、packages/shell/tool-pwsh/src/index.ts、packages/shell/tool-pwsh/tests/tools.spec.ts
对应测试：packages/shell/tool-pwsh/tests/tools.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/shell/tool-pwsh/src/index.ts、packages/shell/tool-pwsh/tests/tools.spec.ts 确认状态如何进入 UI，最后对照 packages/shell/tool-pwsh/tests/tools.spec.ts。
代码证据：固定提交归档实际读取结果：约 113 行；扫描到的声明包括 RenderablePwshResult、renderPwshResult、renderPwshProcessRead、streamText；源码顶部原注释（英文，仅作回查线索）：Model-facing result rendering for the pwsh tool — the PowerShell twin of dsh-tool-bash's renderer: stdout, a marked stderr section, sandbox denial/runner-failure markers (with the same-turn escalation hint), and truncation notices with spill paths, then exi...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh/tests/integration.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“runs a command and returns stdout with no marker on a clean exit”、“returns stderr in a marked section and a nonzero exit as a marker, not an error”、“resolves relative paths in the session workspace”、“a per-call timeout kills the run and reports the timed-out marker, not an error”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“runs a command and returns stdout with no marker on a clean exit”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Integration tests: the REAL @deepseek-ai/dsh-pwsh-local executor plus the pwsh tool, exercised through ctx.tools.execute() with a real PowerShell process. These verify the world — actual commands run, stdout/stderr come back, exit codes render, timeouts abo...”；固定提交中扫描到的声明包括 call、text；本地静态 import 图显示它直接依赖 10 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/README.md、packages/core/system-prompt/src/index.ts、packages/core/tools/src/index.ts、packages/jobs/jobs-local/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/system-prompt/src/index.ts、packages/core/tools/src/index.ts、packages/jobs/jobs-local/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 154 行；扫描到的声明包括 call、text；扫描到的测试主题包括 “runs a command and returns stdout with no marker on a clean exit”、“returns stderr in a marked section and a nonzero exit as a marker, not an error”、“resolves relative paths in the session workspace”、“a per-call timeout kills the run and reports the timed-out marker, not an error”、“an upstream cancellation aborts the run”、“a background run settles through the REAL job_output tool”；源码顶部原注释（英文，仅作回查线索）：Integration tests: the REAL @deepseek-ai/dsh-pwsh-local executor plus the pwsh tool, exercised through ctx.tools.execute() with a real PowerShell process. These verify the world — actual commands run, stdout/stderr come back, exit codes render, timeouts abo...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh/tests/loader.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“registers the pwsh surface and renders real foreground and background results”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“registers the pwsh surface and renders real foreground and background results”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“REAL-composition tier (packages/AGENTS.md): boot the examples-owned tool-pwsh Loader fixture as a subprocess through the same app/boot path a deployment uses, execute real foreground and background pwsh commands through the tool registry, and assert the ass...”；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/README.md、packages/shell/pwsh-local/src/index.ts、packages/test-support/loader-smoke/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/shell/pwsh-local/src/index.ts、packages/test-support/loader-smoke/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 63 行；扫描到的测试主题包括 “registers the pwsh surface and renders real foreground and background results”；源码顶部原注释（英文，仅作回查线索）：REAL-composition tier (packages/AGENTS.md): boot the examples-owned tool-pwsh Loader fixture as a subprocess through the same app/boot path a deployment uses, execute real foreground and background pwsh commands through the tool registry, and assert the ass...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/shell/tool-pwsh/tests/tools.spec.ts

所属层：packages/shell：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查 Shell 命令、工具的具体场景，包括“registration”、“registers the pwsh tool with its prompt section and schema”、“stays pending until ctx.shell exists (inject)”、“unregisters everything on fiber disposal (HMR safety)”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“registration”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“Consumer-surface tests for the pwsh tool over a FAKE bash executor, exercised through ctx.tools.execute() so nothing bypasses the tool registry. The fake executor makes every seam outcome scriptable — output text, truncation, timeout, abort, nonzero exits, ...”；固定提交中扫描到的声明包括 FakeBash、runResult、fakeProcess、killableProcess、setup；本地静态 import 图显示它直接依赖 15 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/shell/tool-pwsh/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 1056 行；扫描到的声明包括 FakeBash、runResult、fakeProcess、killableProcess、setup、setupWithTasks、ConfiningFakeBash、setupSandboxed；扫描到的测试主题包括 “registration”、“registers the pwsh tool with its prompt section and schema”、“stays pending until ctx.shell exists (inject)”、“unregisters everything on fiber disposal (HMR safety)”、“argument validation”、“rejects a blank command or description and a non-positive timeoutMs”；源码顶部原注释（英文，仅作回查线索）：Consumer-surface tests for the pwsh tool over a FAKE bash executor, exercised through ctx.tools.execute() so nothing bypasses the tool registry. The fake executor makes every seam outcome scriptable — output text, truncation, timeout, abort, nonzero exits, ...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

源文件索引：packages/shell ​

图例 ​

packages/shell/bash-local ​

packages/shell/bash-sandbox ​

packages/shell/pwsh-local ​

packages/shell/pwsh-sandbox ​

packages/shell/shell-env ​

packages/shell/shell ​

packages/shell/tool-bash-persistent ​

packages/shell/tool-bash ​

packages/shell/tool-pwsh-persistent ​

packages/shell/tool-pwsh ​