社区导读

简体中文

English

简体中文

English

外观

源文件索引：packages/workspace ​

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

图例 ​

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

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

packages/workspace/workspace/src/entity.ts ​

  • 所属层：packages/workspace：可复用的 Harness 功能包
  • 文件角色：Workspace 领域实现
  • 这个文件有什么用：这个文件定义 workspace 的实体、路径和约束，让文件、会话和沙箱共享同一工作区语义。
  • 为什么这样设计：workspace 是文件、会话和沙箱共享的边界，集中定义实体与路径可以避免各包对工作目录作不同解释。
  • 文件级设计证据：源码顶部注释把它定位为“Package-private workspace entity: the single Workspace implementation. Holds a record snapshot that is swapped in place after each durable mutation; every write funnels through the private mutate so updatedAt stamping and invalid-account pruning happen exac...”；固定提交中扫描到的声明包括 WorkspaceMoveInvalidError、WorkspaceEntityHost、WorkspaceEntity；本地静态 import 图显示它直接依赖 5 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/workspace/workspace/README.md、packages/core/session/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/workspace/workspace/src/paths.ts、packages/workspace/workspace/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.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/workspace/workspace/README.md 和入口，再读当前实现，沿着 packages/core/session/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/workspace/workspace/src/paths.ts 和 packages/workspace/workspace/src/index.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 221 行；扫描到的声明包括 WorkspaceMoveInvalidError、WorkspaceEntityHost、WorkspaceEntity；源码顶部原注释（英文，仅作回查线索）：Package-private workspace entity: the single Workspace implementation. Holds a record snapshot that is swapped in place after each durable mutation; every write funnels through the private mutate so updatedAt stamping and invalid-account pruning happen exac...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/workspace/workspace/src/index.ts ​

packages/workspace/workspace/src/invariant.ts ​

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

packages/workspace/workspace/src/paths.ts ​

  • 所属层：packages/workspace：可复用的 Harness 功能包
  • 文件角色：路径边界
  • 这个文件有什么用：它负责路径的解析、规范化和安全约束，统一处理不同平台的路径差异与越界检查。
  • 为什么这样设计：路径是跨平台且涉及安全的输入，集中规范化和越界判断可以避免不同调用方产生不一致的文件目标。
  • 文件级设计证据：源码顶部注释把它定位为“Path canonicalization for workspace identity. @module @deepseek-ai/dsh-workspace/src/paths”；固定提交中扫描到的声明包括 realpathNormalize；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/workspace/workspace/README.md、packages/workspace/workspace/src/entity.ts、packages/workspace/workspace/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.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/workspace/workspace/README.md 和入口，再读当前实现，沿着相关类型、协议或实现和 packages/workspace/workspace/src/entity.ts、packages/workspace/workspace/src/index.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 22 行；扫描到的声明包括 realpathNormalize；源码顶部原注释（英文，仅作回查线索）：Path canonicalization for workspace identity. @module @deepseek-ai/dsh-workspace/src/paths。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/workspace/workspace/src/spec.ts ​

  • 所属层：packages/workspace：可复用的 Harness 功能包
  • 文件角色：Workspace 领域实现
  • 这个文件有什么用：这个文件定义 workspace 的实体、路径和约束，让文件、会话和沙箱共享同一工作区语义。
  • 为什么这样设计：workspace 是文件、会话和沙箱共享的边界，集中定义实体与路径可以避免各包对工作目录作不同解释。
  • 文件级设计证据：源码顶部注释把它定位为“The workspace domain declaration: record schema and the defineDomain spec the registry opens. The zod schema is the durable-boundary validator today and the direct source of the RPC wire projection in a later phase. @module @deepseek-ai/dsh-workspace/src/spec”；固定提交中扫描到的声明包括 workspaceRecord、WorkspaceRecord、workspaceDomainState、WorkspaceDomainState、workspaceDomainSpec；本地静态 import 图显示它直接依赖 3 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/workspace/workspace/README.md、packages/core/session/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/workspace/workspace/src/types.ts、packages/workspace/workspace/src/entity.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.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/workspace/workspace/README.md 和入口，再读当前实现，沿着 packages/core/session/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/workspace/workspace/src/types.ts 和 packages/workspace/workspace/src/entity.ts、packages/workspace/workspace/src/index.ts 确认输入输出，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 75 行；扫描到的声明包括 workspaceRecord、WorkspaceRecord、workspaceDomainState、WorkspaceDomainState、workspaceDomainSpec；源码顶部原注释（英文，仅作回查线索）：The workspace domain declaration: record schema and the defineDomain spec the registry opens. The zod schema is the durable-boundary validator today and the direct source of the RPC wire projection in a later phase. @module @deepseek-ai/dsh-workspace/src/spec。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/workspace/workspace/src/types.ts ​

  • 所属层：packages/workspace：可复用的 Harness 功能包
  • 文件角色：类型契约
  • 这个文件有什么用：它描述 packages/workspace/workspace 包里的 src/types.ts 中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
  • 为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
  • 文件级设计证据：源码顶部注释把它定位为“Public type vocabulary of the workspace entity: the WorkspaceId brand and the Workspace consumer interface. Types only — the WorkspaceId factory lives in index.ts (this file carries no runtime code). @module @deepseek-ai/dsh-workspace/src/types”；固定提交中扫描到的声明包括 WorkspaceId、Workspace；本地静态 import 图显示它直接依赖 2 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/workspace/workspace/README.md、packages/core/session/src/index.ts、packages/util/brand/src/index.ts、packages/workspace/workspace/src/entity.ts、packages/workspace/workspace/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：apps/web/tests/sidebar-subagent-activity.e2e.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/workspace/workspace/README.md、入口和消费者，再读当前契约，沿着 packages/workspace/workspace/src/entity.ts、packages/workspace/workspace/src/index.ts、packages/workspace/workspace/src/spec.ts 看它怎样约束运行时，最后对照 apps/web/tests/sidebar-subagent-activity.e2e.ts、packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts、packages/host/apiproxy/tests/api-proxy-approval.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 104 行；扫描到的声明包括 WorkspaceId、Workspace；源码顶部原注释（英文，仅作回查线索）：Public type vocabulary of the workspace entity: the WorkspaceId brand and the Workspace consumer interface. Types only — the WorkspaceId factory lives in index.ts (this file carries no runtime code). @module @deepseek-ai/dsh-workspace/src/types。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/workspace/workspace/tests/invariant.spec.ts ​

  • 所属层：packages/workspace：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“invariant”写出可重复运行的断言，覆盖的场景包括“workspace cache/table invariant”、“accepts a put whose record has a cached entity and ignores foreign events”、“fails deletion while the registry still publishes the entity”、“allows deletion after the registry removed the cache entry for rollback or explicit del...”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“workspace cache/table invariant”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 setup；本地静态 import 图显示它直接依赖 5 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/workspace/workspace/README.md、packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/workspace/workspace/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/runtime-diagnostics/invariants/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/workspace/workspace/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 61 行；扫描到的声明包括 setup；扫描到的测试主题包括 “workspace cache/table invariant”、“accepts a put whose record has a cached entity and ignores foreign events”、“fails deletion while the registry still publishes the entity”、“allows deletion after the registry removed the cache entry for rollback or explicit deletion”、“fails a put whose record the registry cache does not hold”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/workspace/workspace/tests/workspace.spec.ts ​

  • 所属层：packages/workspace：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它围绕“workspace”写出可重复运行的断言，覆盖的场景包括“WorkspaceRegistry lifecycle and bootstrap”、“stays pending without sessionPersistence and never opens or marks the domain”、“bootstraps once from list headers only, in workspace/session createdAt order”、“breaks equal bootstrap timestamps by session id and canonical path”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“WorkspaceRegistry lifecycle and bootstrap”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 harness、storageContext、selectiveFailureBackend、record、storedPool；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/workspace/workspace/README.md、packages/core/session/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 测试支持：packages/storage/storage-domain/tests/helpers/memory-backend.ts
  • 阅读顺序：先看它直接导入的被测实现 packages/core/session/src/index.ts、packages/storage/storage-domain/src/index.ts、packages/storage/storage/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 944 行；扫描到的声明包括 harness、storageContext、selectiveFailureBackend、record、storedPool、storedRecord、storedState、makeDir；扫描到的测试主题包括 “WorkspaceRegistry lifecycle and bootstrap”、“stays pending without sessionPersistence and never opens or marks the domain”、“bootstraps once from list headers only, in workspace/session createdAt order”、“breaks equal bootstrap timestamps by session id and canonical path”、“does not rerun bootstrap for a genuinely initialized empty registry”、“reuses partial records after a bootstrap record write fails”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。