架构总览
一句话版：DSH 由几十个
@deepseek-ai/*包组成：抽象能力(seam)在packages/core,具体实现在各领域包,组合规则在packages/bundle,一切通过 cordis 的 Context/插件机制串起来。
这是讲清"DSH 这套东西是怎么搭出来的"的一篇。读前建议先过了 DSH 是什么。
一、包分组地图
| 分组 | 职责 | 代表包 |
|---|---|---|
core/ | 抽象服务与核心循环 | agent、agent-loop、scope、session、system-prompt、tools |
sandbox/ | 进程沙箱 | sandbox(约定)、sandbox-local、sandbox-policy |
session/ | 会话系统 | session-persistence-jsonl/sqlite、session-projection、session-telemetry |
llm/ | 模型层 | llm、llm-deepseek、llm-pi-ai、llm-retry |
context/ | 上下文注入源(非装配) | session-reference、time-context、agent-instructions |
compaction/ | 上下文压缩 | compaction、compaction-basic、command-compact |
shell/ fs/ terminal/ | 执行后端 | bash-sandbox、fs-observation-policy、terminal-bash |
web/ | Web 工具/搜索 | tool-web、web-search-deepseek/exa/perplexity |
bundle/ | 组合层 | base、headless、web-app、sdk-app、sdk-minimal、acp-app |
boot/ + apps/cli | 启动/命令 | app-boot、cmdline |
client/ host/ | Web UI 双进程 | 浏览器端 / 宿主机端 |
extensions/ | 动态 Cordis 扩展 | tool-cordis、cordis-host-runner、cordis-client-runner、client-ui-cordis |
| 其他 | 能力 | mcp、goal、guard、schedule、subagent、subprocess、jobs、workflow、settings、skill、storage、credentials、plan、preset、acp、lsp、code-runtime 等 |
二、分层结构
- 应用层决定"跑哪个模式"(web / headless)和"挂哪些插件"(你的 profile)
- 核心服务层是所有抽象能力(agent loop、会话、模型、工具、沙箱)
- 组合层是 cordis,负责把上面两层加起来、注入依赖、发事件
三、关键设计:Seam(能力缝)
每个能力缝 = 接口定义包 + 实现包分离。以沙箱为例:
packages/sandbox/sandbox：只定义约定(ctx.sandbox.confine+ 词汇),零依赖后端packages/sandbox/sandbox-local：实现(Linux bwrap / macOS Seatbelt / Windows ACL)
替换实现 = 换 provider,消费方代码不变。 这贯穿 llm、session、storage、subagent 等几乎所有能力：这是"一切皆插件"能成立的结构基础。
四、组合规则:Bundle → Profile
- bundle 是"自带 patch 的插件包",作为一层加入 profile
- profile 是 bundle 层 + 用户覆盖层的叠加(
$DSH_HOME/profiles/<name>) - 完整应用序与 patch 语义见 插件解剖
sdk-minimal 是独立完整树，不继承 base，并有意省去多数 base 服务。Web 客户端通过 api/gateway 与领域 controller（session-controller、settings-controller、workspace-controller）通信；浏览器状态（client/store）与 React 适配（ui-session、ui-chat、ui-approval）也各有 owner。详见 Web UI 与 SDK。
五、一条"做一次工具调用"的请求怎么流经各层
每一步都在对应层的 seam 上,正是 Agent 主循环 讲的过程。
六、查看当前组合
dsh web --dump-config | head -50 # 看组合树 + 每行来源注释
dsh web --dump-default-config # 只看 bundle 层(无用户层)
--dump-config 是"某层配了什么"的权威工具(见 启动与配置)。