源文件索引：packages/interaction

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

图例

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

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

packages/interaction/commands/src/brand.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：品牌类型
这个文件有什么用：它为人机交互、品牌类型定义带语义的品牌类型，使编译器能阻止不同用途的标识符互相替换。
为什么这样设计：在编译期区分语义不同的标识符，能把一类容易被普通字符串掩盖的调用错误提前暴露，而不增加运行时序列化成本。
文件级设计证据：源码顶部注释把它定位为“dsh-commands' owned branded id: command lifecycle pairing across the session log, the wire admission response, and client-side flow pairing. The Branded<B> primitive lives in @deepseek-ai/dsh-brand; this module is a pure type/constructor outlet (no cordis i...”；固定提交中扫描到的声明包括 CommandId；本地静态 import 图显示它直接依赖 1 个源文件，并被 14 个源文件直接引用。
直接协作者：packages/interaction/commands/README.md、packages/util/brand/src/index.ts、packages/client/connection/src/client/fixture.ts、packages/client/runtime/src/client/sessions/conversation.ts、packages/client/ui-goal/src/client/goal-command-input.ts
对应测试：packages/compaction/compaction-basic/tests/manual-compaction.spec.ts、packages/compaction/compaction/tests/invariant.spec.ts、packages/host/apiproxy/tests/api-proxy-blank.spec.ts、packages/plan/plan-mode/tests/projection.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/interaction/commands/README.md、入口和消费者，再读当前契约，沿着 packages/client/connection/src/client/fixture.ts、packages/client/runtime/src/client/sessions/conversation.ts、packages/client/ui-goal/src/client/goal-command-input.ts 看它怎样约束运行时，最后对照 packages/compaction/compaction-basic/tests/manual-compaction.spec.ts、packages/compaction/compaction/tests/invariant.spec.ts、packages/host/apiproxy/tests/api-proxy-blank.spec.ts。
代码证据：固定提交归档实际读取结果：约 29 行；扫描到的声明包括 CommandId；源码顶部原注释（英文，仅作回查线索）：dsh-commands' owned branded id: command lifecycle pairing across the session log, the wire admission response, and client-side flow pairing. The Branded<B> primitive lives in @deepseek-ai/dsh-brand; this module is a pure type/constructor outlet (no cordis i...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/commands/src/index.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把人机交互相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Plugin-owned human-command registry shared by interactive UI adapters. @module @deepseek-ai/dsh-commands”；固定提交中扫描到的声明包括 name、CommandInvocation、CommandDefinition、ParsedCommand、parseCommand；本地静态 import 图显示它直接依赖 10 个源文件，并被 19 个源文件直接引用。
直接协作者：packages/interaction/commands/README.md、packages/attachment/attachment/src/index.ts、packages/attachment/attachment/src/types.ts、packages/core/agent/src/index.ts、apps/web/tests/shipped-composition.e2e.ts
对应测试：apps/web/tests/shipped-composition.e2e.ts、packages/compaction/command-compact/tests/command-compact.spec.ts、packages/compaction/command-compact/tests/loader-composition.spec.ts、packages/feedback/command-feedback/tests/command-feedback.spec.ts、packages/feedback/command-feedback/tests/loader-composition.spec.ts、packages/goal/command-goal/tests/command-goal.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：apps/web/tests/scaffold.ts
阅读顺序：先读 packages/interaction/commands/README.md、入口和消费者，再读当前契约，沿着 apps/web/tests/shipped-composition.e2e.ts、packages/compaction/command-compact/src/index.ts、packages/compaction/command-compact/tests/command-compact.spec.ts 看它怎样约束运行时，最后对照 apps/web/tests/shipped-composition.e2e.ts、packages/compaction/command-compact/tests/command-compact.spec.ts、packages/compaction/command-compact/tests/loader-composition.spec.ts。
代码证据：固定提交归档实际读取结果：约 457 行；扫描到的声明包括 name、CommandInvocation、CommandDefinition、ParsedCommand、parseCommand、CommandRuntime、CommandLayer、abortError；源码顶部原注释（英文，仅作回查线索）：Plugin-owned human-command registry shared by interactive UI adapters. @module @deepseek-ai/dsh-commands。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/commands/src/invariant.ts

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

packages/interaction/commands/src/types.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：类型契约
这个文件有什么用：它描述人机交互中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
文件级设计证据：源码顶部注释把它定位为“Durable command event vocabulary and the registry's Cordis event declaration, shared with type-only consumers. Client-safe: nothing here reaches a Host-only symbol, so a Client compilation face reads the same commands/change signature the Host emits. @modul...”；固定提交中扫描到的声明包括 CommandInputDescriptor、CommandResult、CommandExecution、CommandDescriptor、CommandSourceMap；本地静态 import 图显示它直接依赖 1 个源文件，并被 11 个源文件直接引用。
直接协作者：packages/interaction/commands/README.md、packages/interaction/commands/src/brand.ts、apps/web/tests/goal-command-presentation.e2e.ts、packages/api/remotes/src/client/index.ts、packages/api/remotes/src/index.ts
对应测试：apps/web/tests/goal-command-presentation.e2e.ts、packages/client/runtime/tests/session.client.spec.ts、packages/client/ui-commands/tests/service.client.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：apps/web/tests/scaffold.ts、apps/web/tests/support.ts、packages/client/runtime/tests/event-script.client.ts、packages/client/runtime/tests/fake-api.client.ts
阅读顺序：先读 packages/interaction/commands/README.md、入口和消费者，再读当前契约，沿着 apps/web/tests/goal-command-presentation.e2e.ts、packages/api/remotes/src/client/index.ts、packages/api/remotes/src/index.ts 看它怎样约束运行时，最后对照 apps/web/tests/goal-command-presentation.e2e.ts、packages/client/runtime/tests/session.client.spec.ts、packages/client/ui-commands/tests/service.client.spec.ts。
代码证据：固定提交归档实际读取结果：约 110 行；扫描到的声明包括 CommandInputDescriptor、CommandResult、CommandExecution、CommandDescriptor、CommandSourceMap、CommandSource；源码顶部原注释（英文，仅作回查线索）：Durable command event vocabulary and the registry's Cordis event declaration, shared with type-only consumers. Client-safe: nothing here reaches a Host-only symbol, so a Client compilation face reads the same commands/change signature the Host emits. @modul...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/commands/tests/commands.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“parseCommand()”、“CommandRuntime”、“lists immutable global descriptors with input metadata”、“sorts distinct effective command names”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“parseCommand()”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 command、mount、mintAgentScope、lifecycleOf、storeOf；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/commands/README.md、packages/attachment/attachment/src/index.ts、packages/core/agent/src/index.ts、packages/core/scope/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/attachment/attachment/src/index.ts、packages/core/agent/src/index.ts、packages/core/scope/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 627 行；扫描到的声明包括 command、mount、mintAgentScope、lifecycleOf、storeOf、accepting；扫描到的测试主题包括 “parseCommand()”、“CommandRuntime”、“lists immutable global descriptors with input metadata”、“sorts distinct effective command names”、“uses agent-scoped shadows and removes them with their scope”、“removes a registration when its contributing plugin fiber is disposed”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/commands/tests/invariant.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“command lifecycle invariants”、“accepts a success outcome linked to an earlier non-command domain event”、“rejects an error settlement carrying a success-only source reference”、“attributes an invalid durable prefix during late companion loading”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“command lifecycle invariants”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 mount、appendRun；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/commands/README.md、packages/core/session/src/index.ts、packages/interaction/commands/src/index.ts、packages/interaction/commands/src/invariant.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/session/src/index.ts、packages/interaction/commands/src/index.ts、packages/interaction/commands/src/invariant.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 89 行；扫描到的声明包括 mount、appendRun；扫描到的测试主题包括 “command lifecycle invariants”、“accepts a success outcome linked to an earlier non-command domain event”、“rejects an error settlement carrying a success-only source reference”、“attributes an invalid durable prefix during late companion loading”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/permission-presets/src/client.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：外部能力适配层
这个文件有什么用：它把外部协议转换成人机交互、浏览器端能理解的内部协议。转换集中在边界，核心逻辑就不必到处处理供应商差异。
为什么这样设计：把“接口是什么”和“这一版怎样实现”分开，替换实现或写测试替身时不必改动使用者。
文件级设计证据：源码顶部注释把它定位为“Client-namespace projection of the permission domain: a pure re-export of the package's types outlet. Client code imports ONLY the client namespace (repo discipline), so ./client projects the same single-source content ./types serves to host consumers — zer...”；本地静态 import 图显示它直接依赖 1 个源文件，并被 3 个源文件直接引用。
直接协作者：packages/interaction/permission-presets/README.md、packages/interaction/permission-presets/src/types.ts、packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx、packages/client/ui-permission-presets/src/client/index.ts、packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts
对应测试：packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/interaction/permission-presets/README.md 和入口，再读当前实现，沿着 packages/interaction/permission-presets/src/types.ts 和 packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx、packages/client/ui-permission-presets/src/client/index.ts、packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts 确认输入输出，最后对照 packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts。
代码证据：固定提交归档实际读取结果：约 10 行；源码顶部原注释（英文，仅作回查线索）：Client-namespace projection of the permission domain: a pure re-export of the package's types outlet. Client code imports ONLY the client namespace (repo discipline), so ./client projects the same single-source content ./types serves to host consumers — zer...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/permission-presets/src/index.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把人机交互相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“User-facing permission presets over the independent sandbox-mode and approval-policy knobs. A switch records the selected preset, then writes changed knobs through their canonical setters. Execution, prompt narration, and replay keep reading their knob fold...”；固定提交中扫描到的声明包括 PresetSpec、CUSTOM_PRESET、PERMISSION_SETTINGS_NAMESPACE、effectivePermissionPreset、KnobState；本地静态 import 图显示它直接依赖 11 个源文件，并被 4 个源文件直接引用。
直接协作者：packages/interaction/permission-presets/README.md、packages/core/session/src/index.ts、packages/interaction/commands/src/index.ts、packages/interaction/permission-presets/src/types.ts、apps/web/tests/shipped-composition.e2e.ts
对应测试：apps/web/tests/shipped-composition.e2e.ts、packages/host/apiproxy/tests/api-proxy-blank.spec.ts、packages/interaction/permission-presets/tests/permission-presets.spec.ts、packages/interaction/permission-presets/tests/projection.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：apps/web/tests/scaffold.ts
阅读顺序：先读 packages/interaction/permission-presets/README.md、入口和消费者，再读当前契约，沿着 apps/web/tests/shipped-composition.e2e.ts、packages/host/apiproxy/tests/api-proxy-blank.spec.ts、packages/interaction/permission-presets/tests/permission-presets.spec.ts 看它怎样约束运行时，最后对照 apps/web/tests/shipped-composition.e2e.ts、packages/host/apiproxy/tests/api-proxy-blank.spec.ts、packages/interaction/permission-presets/tests/permission-presets.spec.ts。
代码证据：固定提交归档实际读取结果：约 449 行；扫描到的声明包括 PresetSpec、CUSTOM_PRESET、PERMISSION_SETTINGS_NAMESPACE、effectivePermissionPreset、KnobState、applyKnobEvent、PermissionSettings、Config；源码顶部原注释（英文，仅作回查线索）：User-facing permission presets over the independent sandbox-mode and approval-policy knobs. A switch records the selected preset, then writes changed knobs through their canonical setters. Execution, prompt narration, and replay keep reading their knob fold...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/permission-presets/src/invariant.ts

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

packages/interaction/permission-presets/src/types.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：类型契约
这个文件有什么用：它描述人机交互中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
文件级设计证据：源码顶部注释把它定位为“Pure types of the permission domain: the ONE home of the permissions projection-key declaration plus its payload types, free of this package's host-side value imports (cordis, schemastery). Two namespace projections serve it — the package root re-export for...”；固定提交中扫描到的声明包括 PresetOption、PermissionSelect；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/interaction/permission-presets/README.md、packages/interaction/permission-presets/src/client.ts、packages/interaction/permission-presets/src/index.ts
对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/shipped-composition.e2e.ts、packages/client/ui-conversation/tests/input-bar.client.spec.tsx、packages/client/ui-conversation/tests/input-matrix.client.spec.tsx、packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx、packages/client/ui-conversation/tests/skeleton.client.spec.tsx、packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts
测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
阅读顺序：先读 packages/interaction/permission-presets/README.md、入口和消费者，再读当前契约，沿着 packages/interaction/permission-presets/src/client.ts、packages/interaction/permission-presets/src/index.ts 看它怎样约束运行时，最后对照 apps/web/tests/shipped-composition.e2e.ts、packages/client/ui-conversation/tests/input-bar.client.spec.tsx、packages/client/ui-conversation/tests/input-matrix.client.spec.tsx。
代码证据：固定提交归档实际读取结果：约 44 行；扫描到的声明包括 PresetOption、PermissionSelect；源码顶部原注释（英文，仅作回查线索）：Pure types of the permission domain: the ONE home of the permissions projection-key declaration plus its payload types, free of this package's host-side value imports (cordis, schemastery). Two namespace projections serve it — the package root re-export for...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/permission-presets/tests/invariant.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“permission invariants”、“accepts configured preset events and ignores other session data”、“rejects a durable preset that the active table cannot resolve”、“rejects an unknown preset already present on late registration”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“permission invariants”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 PermissionProbe、setup、presetEvent；本地静态 import 图显示它直接依赖 4 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/permission-presets/README.md、packages/core/session/src/index.ts、packages/interaction/permission-presets/src/invariant.ts、packages/runtime-diagnostics/invariants/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/session/src/index.ts、packages/interaction/permission-presets/src/invariant.ts、packages/runtime-diagnostics/invariants/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 53 行；扫描到的声明包括 PermissionProbe、setup、presetEvent；扫描到的测试主题包括 “permission invariants”、“accepts configured preset events and ignores other session data”、“rejects a durable preset that the active table cannot resolve”、“rejects an unknown preset already present on late registration”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/permission-presets/tests/permission-presets.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“effectivePermissionPreset”、“folds to the last event, or undefined without one”、“PermissionPresetService”、“advertises the preset table in declaration order and resolves bundles”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“effectivePermissionPreset”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 MemorySettings、mounted、freshSession、mountedStore；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/permission-presets/README.md、packages/core/session/src/index.ts、packages/interaction/permission-presets/src/index.ts、packages/interaction/user-approval/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/session/src/index.ts、packages/interaction/permission-presets/src/index.ts、packages/interaction/user-approval/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 301 行；扫描到的声明包括 MemorySettings、mounted、freshSession、mountedStore；扫描到的测试主题包括 “effectivePermissionPreset”、“folds to the last event, or undefined without one”、“PermissionPresetService”、“advertises the preset table in declaration order and resolves bundles”、“current() derives from the effective knobs: composition defaults hit workspace-write, a switch hits its preset”、“a knob state matching no table entry derives custom — a state, not an error”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/permission-presets/tests/projection.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互、状态投影的具体场景，包括“permissions projection unit”、“serves the pinned new-session default select”、“folds the knob events and notifies the change feed per knob append”、“appends custom as a current-only option when the knobs match no preset”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“permissions projection unit”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：源码顶部注释把它定位为“The permissions projection unit and the /permission command: mounting the permission service beside the projection registry serves the whole select (table options + effective current value, custom appended exactly while derived) folded from the three knob e...”；固定提交中扫描到的声明包括 harness、agentFor；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/permission-presets/README.md、packages/core/agent/src/index.ts、packages/core/scope/src/index.ts、packages/core/session/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/scope/src/index.ts、packages/core/session/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 133 行；扫描到的声明包括 harness、agentFor；扫描到的测试主题包括 “permissions projection unit”、“serves the pinned new-session default select”、“folds the knob events and notifies the change feed per knob append”、“appends custom as a current-only option when the knobs match no preset”、“has no permissions key without the service, and drops it on unload (HMR safety)”、“/permission command”；源码顶部原注释（英文，仅作回查线索）：The permissions projection unit and the /permission command: mounting the permission service beside the projection registry serves the whole select (table options + effective current value, custom appended exactly while derived) folded from the three knob e...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/tool-ask-user/src/index.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把人机交互、工具相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Model-facing Consumer of the ctx.userQuestions capability seam. The tool pauses until a UI provider returns a human answer, then feeds that answer back into the agent loop as an ordinary tool result. @module @deepseek-ai/dsh-tool-ask-user”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 3 个源文件，并被 2 个源文件直接引用。
直接协作者：packages/interaction/tool-ask-user/README.md、packages/core/tools/src/index.ts、packages/interaction/user-questions/src/index.ts、vendor/cordis/src/index.ts、packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts
对应测试：packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/interaction/tool-ask-user/README.md、入口和消费者，再读当前契约，沿着 packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts、scripts/gen-tool-catalog.ts 看它怎样约束运行时，最后对照 packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts。
代码证据：固定提交归档实际读取结果：约 101 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Model-facing Consumer of the ctx.userQuestions capability seam. The tool pauses until a UI provider returns a human answer, then feeds that answer back into the agent loop as an ordinary tool result. @module @deepseek-ai/dsh-tool-ask-user。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/tool-ask-user/src/invariant.ts

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

packages/interaction/tool-ask-user/tests/tool-ask-user.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互、工具的具体场景，包括“ask_user_question tool”、“registers a model-facing tool schema”、“asks the registered user-questions provider and projects structured answers to text”、“passes recommended option labels through without adding schema fields”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“ask_user_question tool”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 setup、stubAgent；本地静态 import 图显示它直接依赖 7 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/tool-ask-user/README.md、packages/core/agent/src/index.ts、packages/core/system-prompt/src/index.ts、packages/core/tools/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/system-prompt/src/index.ts、packages/core/tools/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 320 行；扫描到的声明包括 setup、stubAgent；扫描到的测试主题包括 “ask_user_question tool”、“registers a model-facing tool schema”、“asks the registered user-questions provider and projects structured answers to text”、“passes recommended option labels through without adding schema fields”、“projects custom answers and multi-select choices”、“passes the tool abort signal to the user-questions request”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-approval/src/index.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把人机交互相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing answerers fail closed; grants apply only to the requested action. @module @deepseek-ai/dsh-user-approval”；固定提交中扫描到的声明包括 ApprovalPolicy、APPROVAL_POLICIES、effectiveApprovalPolicy、setApprovalPolicy、ApprovalRequest；本地静态 import 图显示它直接依赖 8 个源文件，并被 24 个源文件直接引用。
直接协作者：packages/interaction/user-approval/README.md、packages/core/agent/src/index.ts、packages/core/scope/src/index.ts、packages/core/session/src/index.ts、apps/web/tests/approval-composer.e2e.ts
对应测试：apps/web/tests/approval-composer.e2e.ts、apps/web/tests/shipped-composition.e2e.ts、packages/acp/acp/tests/approval.spec.ts、packages/core/tools/tests/tools.spec.ts、packages/fs/tool-fs/tests/tools.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
测试支持：apps/web/tests/scaffold.ts、apps/web/tests/support.ts、packages/acp/acp/tests/harness.ts
阅读顺序：先读 packages/interaction/user-approval/README.md、入口和消费者，再读当前契约，沿着 apps/web/tests/approval-composer.e2e.ts、apps/web/tests/shipped-composition.e2e.ts、packages/acp/acp/src/index.ts 看它怎样约束运行时，最后对照 apps/web/tests/approval-composer.e2e.ts、apps/web/tests/shipped-composition.e2e.ts、packages/acp/acp/tests/approval.spec.ts。
代码证据：固定提交归档实际读取结果：约 347 行；扫描到的声明包括 ApprovalPolicy、APPROVAL_POLICIES、effectiveApprovalPolicy、setApprovalPolicy、ApprovalRequest、Config、ApprovalService、hasOpenTurn；源码顶部原注释（英文，仅作回查线索）：Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing answerers fail closed; grants apply only to the requested action. @module @deepseek-ai/dsh-user-approval。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-approval/src/invariant.ts

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

packages/interaction/user-approval/src/types.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：类型契约
这个文件有什么用：它描述人机交互中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
文件级设计证据：源码顶部注释把它定位为“Wire-safe approval identifiers and outcome vocabulary, free of cordis/service imports so browser type chains (apiproxy api → client) can consume them without loading this package's Context augmentation. @module @deepseek-ai/dsh-user-approval/types”；固定提交中扫描到的声明包括 ApprovalRequestId、ApprovalOutcome；本地静态 import 图显示它直接依赖 1 个源文件，并被 4 个源文件直接引用。
直接协作者：packages/interaction/user-approval/README.md、packages/util/brand/src/index.ts、packages/host/apiproxy/src/api/approvals.schema.ts、packages/host/apiproxy/src/api/approvals.ts、packages/host/apiproxy/src/api/events.ts
对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/cli/tests/memory-mcp-configs.spec.ts、apps/cli/tests/web-agent-presets.e2e.ts、apps/web/tests/agent-preset-selection.e2e.ts、apps/web/tests/approval-composer.e2e.ts、apps/web/tests/plan-control-row.e2e.ts、apps/web/tests/shipped-composition.e2e.ts
测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
阅读顺序：先读 packages/interaction/user-approval/README.md、入口和消费者，再读当前契约，沿着 packages/host/apiproxy/src/api/approvals.schema.ts、packages/host/apiproxy/src/api/approvals.ts、packages/host/apiproxy/src/api/events.ts 看它怎样约束运行时，最后对照 apps/cli/tests/memory-mcp-configs.spec.ts、apps/cli/tests/web-agent-presets.e2e.ts、apps/web/tests/agent-preset-selection.e2e.ts。
代码证据：固定提交归档实际读取结果：约 29 行；扫描到的声明包括 ApprovalRequestId、ApprovalOutcome；源码顶部原注释（英文，仅作回查线索）：Wire-safe approval identifiers and outcome vocabulary, free of cordis/service imports so browser type chains (apiproxy api → client) can consume them without loading this package's Context augmentation. @module @deepseek-ai/dsh-user-approval/types。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-approval/tests/approval.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“ApprovalService.request”、“throws before appending anything when no turn has ever opened (idle ask)”、“throws between turns — a closed turn does not satisfy the enclosure precondition”、“fails closed to unavailable when nobody listens, auditing the asked/decided pair”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“ApprovalService.request”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 fakeAgent、mounted、requestOf、sessionAgent；本地静态 import 图显示它直接依赖 7 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/user-approval/README.md、packages/core/agent/src/index.ts、packages/core/scope/src/index.ts、packages/core/session/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/scope/src/index.ts、packages/core/session/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 514 行；扫描到的声明包括 fakeAgent、mounted、requestOf、sessionAgent；扫描到的测试主题包括 “ApprovalService.request”、“throws before appending anything when no turn has ever opened (idle ask)”、“throws between turns — a closed turn does not satisfy the enclosure precondition”、“fails closed to unavailable when nobody listens, auditing the asked/decided pair”、“omits absent optional fields from the asked audit event”、“borrows the exact readonly request for scoped dispatch and audit”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-approval/tests/invariant.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“approval invariants”、“accepts paired audit events and closed policy values”、“rebuilds an unmatched question from an existing session”、“adopts a bare session first observed through publication”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“approval invariants”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 setup、startTurn；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/user-approval/README.md、packages/core/session/src/index.ts、packages/interaction/user-approval/src/index.ts、packages/interaction/user-approval/src/invariant.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/session/src/index.ts、packages/interaction/user-approval/src/index.ts、packages/interaction/user-approval/src/invariant.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 106 行；扫描到的声明包括 setup、startTurn；扫描到的测试主题包括 “approval invariants”、“accepts paired audit events and closed policy values”、“rebuilds an unmatched question from an existing session”、“adopts a bare session first observed through publication”、“rejects audit events outside any open turn”、“rejects an unenclosed audit event when replaying an existing session”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-approval/tsdown.config.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：构建或测试配置
这个文件有什么用：它告诉工具链怎样处理人机交互：从哪里开始、使用哪个环境、解析哪些依赖以及输出什么产物；这些规则集中后，构建和测试才可重复。
为什么这样设计：工具链配置独立于业务实现，构建、测试和发布可以复用同一套入口规则；改配置时也能单独看出运行环境变化。
文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 0 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/user-approval/README.md
对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
阅读顺序：先读 packages/interaction/user-approval/README.md，再读本配置/脚本，沿着所在包的入口或服务确认它如何影响入口和产物，最后对照对应 gate 或快照测试。
代码证据：固定提交归档实际读取结果：约 30 行。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-questions/src/index.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：模块入口
这个文件有什么用：它把人机交互相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
文件级设计证据：源码顶部注释把它定位为“Service Definition for the user-questions capability seam (ctx.userQuestions): a UI-backed service for pausing an agent tool call until the human answers a question. The model- facing tool lives in @deepseek-ai/dsh-tool-ask-user; UI packages provide the sin...”；固定提交中扫描到的声明包括 AskUserQuestionRequest、UserQuestionProvider、UserQuestionError、UserQuestionService；本地静态 import 图显示它直接依赖 4 个源文件，并被 26 个源文件直接引用。
直接协作者：packages/interaction/user-questions/README.md、packages/core/agent/src/index.ts、packages/interaction/user-questions/src/types.ts、packages/llm/llm/src/index.ts、examples/acp-agent/tests/fixtures/child-question-tripwire.ts
对应测试：packages/client/ui-user-questions/tests/node-plugin.client.spec.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts、packages/host/apiproxy/tests/api-proxy-blank.spec.ts、packages/host/apiproxy/tests/api-proxy-cold.spec.ts、packages/host/apiproxy/tests/api-proxy-config.spec.ts
测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
阅读顺序：先读 packages/interaction/user-questions/README.md、入口和消费者，再读当前契约，沿着 examples/acp-agent/tests/fixtures/child-question-tripwire.ts、packages/client/ui-user-questions/tests/node-plugin.client.spec.ts、packages/host/apiproxy/src/api-proxy.ts 看它怎样约束运行时，最后对照 packages/client/ui-user-questions/tests/node-plugin.client.spec.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts。
代码证据：固定提交归档实际读取结果：约 143 行；扫描到的声明包括 AskUserQuestionRequest、UserQuestionProvider、UserQuestionError、UserQuestionService；源码顶部原注释（英文，仅作回查线索）：Service Definition for the user-questions capability seam (ctx.userQuestions): a UI-backed service for pausing an agent tool call until the human answers a question. The model- facing tool lives in @deepseek-ai/dsh-tool-ask-user; UI packages provide the sin...。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-questions/src/invariant.ts

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

packages/interaction/user-questions/src/types.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：类型契约
这个文件有什么用：它描述人机交互中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
文件级设计证据：源码顶部注释把它定位为“Wire-safe question and answer types, free of cordis/service imports so browser type chains (apiproxy api → client) can consume them without loading this package's Context augmentation. @module @deepseek-ai/dsh-user-questions/types”；固定提交中扫描到的声明包括 AskUserQuestionOption、AskUserQuestionIntent、AskUserQuestionItem、AskUserQuestionAnswerItem、AskUserQuestionAnswer；本地静态 import 图显示它直接依赖 0 个源文件，并被 5 个源文件直接引用。
直接协作者：packages/interaction/user-questions/README.md、packages/host/apiproxy/src/api/events.schema.ts、packages/host/apiproxy/src/api/events.ts、packages/host/apiproxy/src/api/questions.schema.ts
对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/plan-control-row.e2e.ts、packages/api/gateway/tests/gateway.client.spec.ts、packages/client/connection/tests/api-helpers.client.spec.ts、packages/client/connection/tests/client-apply.client.spec.ts、packages/client/connection/tests/connection.client.spec.ts、packages/client/connection/tests/fixture-commands.client.spec.ts
测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
阅读顺序：先读 packages/interaction/user-questions/README.md、入口和消费者，再读当前契约，沿着 packages/host/apiproxy/src/api/events.schema.ts、packages/host/apiproxy/src/api/events.ts、packages/host/apiproxy/src/api/questions.schema.ts 看它怎样约束运行时，最后对照 apps/web/tests/plan-control-row.e2e.ts、packages/api/gateway/tests/gateway.client.spec.ts、packages/client/connection/tests/api-helpers.client.spec.ts。
代码证据：固定提交归档实际读取结果：约 66 行；扫描到的声明包括 AskUserQuestionOption、AskUserQuestionIntent、AskUserQuestionItem、AskUserQuestionAnswerItem、AskUserQuestionAnswer；源码顶部原注释（英文，仅作回查线索）：Wire-safe question and answer types, free of cordis/service imports so browser type chains (apiproxy api → client) can consume them without loading this package's Context augmentation. @module @deepseek-ai/dsh-user-questions/types。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/interaction/user-questions/tests/user-questions.spec.ts

所属层：packages/interaction：可复用的 Harness 功能包
文件角色：测试用例
这个文件有什么用：它用自动化测试检查人机交互的具体场景，包括“UserQuestionService”、“delegates ask requests to the registered provider”、“rejects ask requests when no provider is registered”、“registers providers with HMR-safe disposal”；这些断言把“应该发生什么”变成可以重复运行的证据。
为什么这样设计：把测试主题“UserQuestionService”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
文件级设计证据：固定提交中扫描到的声明包括 provider、stubAgent；本地静态 import 图显示它直接依赖 3 个源文件，并被 0 个源文件直接引用。
直接协作者：packages/interaction/user-questions/README.md、packages/core/agent/src/index.ts、packages/interaction/user-questions/src/index.ts、vendor/cordis/src/index.ts
对应测试：本文件本身就是测试用例。
测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/interaction/user-questions/src/index.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
代码证据：固定提交归档实际读取结果：约 222 行；扫描到的声明包括 provider、stubAgent；扫描到的测试主题包括 “UserQuestionService”、“delegates ask requests to the registered provider”、“rejects ask requests when no provider is registered”、“registers providers with HMR-safe disposal”、“rejects duplicate providers instead of replacing the active UI”、“fails before reaching the provider when the signal is already aborted”。
固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

源文件索引：packages/interaction ​

图例 ​

源文件索引：packages/interaction

图例