DeepSeek Harness in Depth

工作区

dsh 是在根 package.json 中声明的 pnpm 工作区：

json

"workspaces": [
  "vendor/*",
  "packages/*/*",
  "native/landlock-run",
  "native/landlock-run/packages/*",
  "apps/*",
  "website"
]

这里可见三种结构性模式：

packages/*/*——产品本体，组织为 packages/<group>/<pkg>，即「一组包」的直观形态。
vendor/*——内嵌的框架层（Cordis 及其伙伴），行为上像一个独立层级。
apps/*、native/...、website、python——产品组装物与部署根。

顶层布局

apps/         产品启动器：`cli`（`dsh` 二进制）与 `web`（前端）
docs/         官方双语文档源（上游）
native/       原生代码：`landlock-run` 及其按平台拆分的包
packages/     产品层——51 个组目录
python/       Python SDK 及其运行时
scripts/      仓库工具（门禁、生成器、发布）
vendor/       源码内嵌的 Cordis 框架与基础库
website/      投影 docs/ 源选集的 VitePress 站点（`@deepseek-ai/website`）

packages 层：51 个组

按目录统计，packages/ 下共有 51 个组目录；解析 packages/*/*/package.json glob 得到 251 个包层包。本 commit 下可复现的数值是 51 个组、251 个包层项目，加上 apps/vendor/native/website 后共 267 个工作区成员。各组及其角色：

组	一行角色
`core`	agent 主循环、会话、scope、工具注册表、系统提示词
`session`	`SessionEvent` 日志、会话领域、投影/引用材料
`context`	喂入模型可见历史的上下文来源
`compaction`	把长日志整理成摘要上下文
`sandbox`	限制后端、沙箱策略、文件系统观测
`fs`	文件系统服务、本地/沙箱提供商、文件系统工具
`shell`	bash/pwsh 能力接缝与工具（典型接缝示例）
`llm`	LLM 服务、DeepSeek 提供商、Token 计量
`api`	API 网关与 remotes（Host↔Client RPC）
`host`	Host 平台：webserver、frontend-static、plugin-inventory、directory-picker 家族
`client`	浏览器/运行时一侧与每个 UI 模块（`ui-*`）
`sdk`	JSON-RPC SDK：`client`、`server`、`protocol`
`subagent`	子代理能力接缝及其众多提供商
`workflow`	工作流/worker-thread 编排
`goal`	同会话目标与目标轮次驱动
`plan`	计划模式
`skill`	技能注册表、文件系统技能、tool-skill
`mcp`	MCP 客户端
`lsp`	LSP 集成
`acp`	Agent Client Protocol 服务器端
`hooks`	Claude Code / Codex hooks 桥
`storage`	持久化后端
`settings`	设置服务
`credentials`	凭据存储
`guard`	超时 / 重复提醒守卫
`feedback`	用户反馈采集
`identity`	节点身份 / 会话身份
`interaction`	运行时的命令、提问、审批
`jobs`	后台任务服务
`schedule`	持久提醒
`spill`	上下文溢出（spill）
`attachment`	消息附件
`bundle`	组合束：`base`、`web-app`、`headless`
`boot`	启动胶水与命令行：`app-boot`、`cmdline`
`code-runtime`	代码执行运行时
`e2b`	E2B 提供商
`examples`	`agent-spine-demo`——幸存的演示包（顶层 demos 已退役）
`experimental`	排除在官方发布之外的实验性能力：agent-team 家族、跨领域 inspector、webworker 运行时/打包器
`extensions`	额外扩展点
`runtime-diagnostics`	运行时诊断工具
`test-support`	测试框架、mock LLM 服务器
`typert`	类型反射 / 代码生成器
`util`	小型共享工具（`home-paths`、`timeout`、`brand`…）
`web`	web/搜索能力工具（`tool-web`、`web-fetch-http`、搜索提供商）
`webhook`	经验证的外部事件 → Sessions：`webhook` 运行时 + `webhook-github` 签名适配器
`workspace`	工作区模型（根、选择）
`preset`	`agent` preset 组合
`session-query`	会话上的查询/日志导出
`subprocess`	进程派生
`terminal`	持久终端（PTY）后端
`todo`	todo 工具

（有些组把面向模型的工具放进兄弟组——例如 todo/tool-todo、session-query/tool-session-query——而非内联，这就是为什么用一行给出某个组的角色只是近似。docs/module-graph.md 是生成的、权威的依赖图。）

其余层级

在 packages/ 之外，工作区还包含：

层	成员	角色
`apps/`	`cli`（`@deepseek-ai/dsh`）、`web`（`@deepseek-ai/dsh-web-frontend`）	`dsh` 启动器与浏览器前端构建
`vendor/`	9 个包（`cordis`、`loader`、`include`、`group`、`hmr`、`timer`、`logger-console`、`cosmokit`、`schemastery`）	源码内嵌框架，重命名进 `@deepseek-ai` 作用域
`native/`	`landlock-run` + Linux arm64/x64 平台包 + entry	Landlock 沙箱启动器
`website/`	`@deepseek-ai/website`	文档站
`python/`	`sdk`、`sdk-runtime`	Python SDK（`deepseek-harness-sdk`）与捆绑运行时部署根

顶层的 examples/ 层已被退役（上游 commit 4125514a08 "refactor(repo): retire top-level examples"）：演示移入 apps/cli/config/examples/{cordis,github-review,mcp-memory,schedule} 作为补丁覆盖，测试移入 apps/cli/tests/profiles/{acp,headless,sdk}。packages/examples/ 作为产品组仍存在，但现在只包含 agent-spine-demo。

vendor 层对读者而言或许是意义最大的层：产品中任何一处 import 的 cordis，实际解析为 vendor/cordis 下的 @deepseek-ai/cordis，因此框架本身也是本仓库中一个固定、带差异防护的部分（参见内嵌（Vendor）库）。

命名约定

每个产品包都是 @deepseek-ai/dsh-<name>——即 harness 家族。值得注意的是：

CLI 包就叫 @deepseek-ai/dsh（无后缀），根清单是 @deepseek-ai/dsh-root，前端是 @deepseek-ai/dsh-web-frontend。
内嵌框架使用同样的作用域，但使用不同的家族标记：@deepseek-ai/cordis、 @deepseek-ai/cordis-plugin-loader 等，让 harness 包（dsh-*）与托管的框架（cordis-*）在视觉上区分开来。
在同一组内，包共享 dsh- 前缀并常有角色后缀：@deepseek-ai/dsh-tool-bash、@deepseek-ai/dsh-bash-local、 @deepseek-ai/dsh-bash-sandbox。

一个能力接缝 → 若干包

命名是更深层组织原则的症状：一个能力接缝对应多个包，每包一个角色。 位于 packages/shell/ 的 bash/shell 接缝是典型示例：

包	角色
`@deepseek-ai/dsh-shell`	服务定义——`ShellExecutor`（`ctx.shell`）+ 词汇
`@deepseek-ai/dsh-bash-local`	服务提供商——本地子进程
`@deepseek-ai/dsh-bash-sandbox`	服务提供商——同样的机制，经由 `ctx.sandbox` 限制
`@deepseek-ai/dsh-tool-bash`	消费者——面向模型的 bash 工具

这正是 docs/architecture.md 中「服务定义 / 提供商 / 消费者」三角色模式，它在整个 monorepo 中反复出现：子代理（定义 subagent/subagent、提供商 subagent-*、消费者 tool-subagent）、文件系统（fs/fs、fs/fs-local + fs/fs-sandbox、fs/tool-fs）、LLM（llm/llm、llm-* 提供商、无常设工具）。一个包可以合并角色，但单独一个角色并非接缝——这就是仓库往往在一个组里放多个小包而非一个肥大包的原因。

这些数字从何而来

两个生成文件给出了结构的可验证基准：

docs/module-graph.md —— 从每个包的 peerDependencies 推导的包间依赖图，并按 packages/<group>/<pkg> 分组。
docs/graph-atlas.md —— 关系图的索引（模块图、工具目录、能力接缝、应用组合、事件矩阵、生命周期）。

用 pnpm run gen-module-graph 重新生成模块图；用 pnpm run verify-module-graph 验证。apps/cli/composition.md 文件渲染了 CLI 组合后的 dsh-base 共享 profile。

工作区 ​

顶层布局 ​

packages 层：51 个组 ​

其余层级 ​

命名约定 ​

一个能力接缝 → 若干包 ​

这些数字从何而来 ​

延伸阅读 ​

工作区