2.1 宏观架构总览

本章概览：把前面学的零件（Cordis、配置树、能力缝、会话日志）拼成一张全景图——启动引导、配置层叠、核心包脊柱、事件驱动与派生数据，并用一张图给出"数据怎么流"。

一张图：DSH 的分层

启动引导（boot sequence）

dsh 进程的启动由 dsh-app-boot 的 boot() 串联（apps/cli 提供 bin）：

resolveConfigPath：确定绝对配置路径（replay 快照模式会换用 cordis.snapshot.yml）；
loadLayeredEnv：构造冻结的"继承环境 > 项目 .env > 用户 .env"快照；
创建根 Context，向 Loader 的 !!js 配置表达式暴露 dshHomePath(...segments)；
安装 Loader，挂载 include 树（cordis:include / cordis:group 内置注册）；
assertEntriesLoaded / assertEntriesActivated：审计每个启用的条目都有 fiber 且激活成功，否则带明确报错 dispose 部分上下文后退出（fail loud）；
可选 prepare 钩子（dsh 在此捕获根上下文，供终端释放用）；
返回根上下文，或 dispose 部分上下文并拒绝带标签的错误。

出处：packages/boot/app-boot/README.md（deepseek-harness-src/packages/boot/app-boot/README.md）

配置层叠

空根
 ├─ 1. dsh.profile.bundles（有序组合包：dsh-base → dsh-web-app / dsh-headless）
 ├─ 2. profile 的 cordis.patch.yml
 ├─ 3. $DSH_HOME/cordis.patch.yml
 └─ 4. --patch overlay

每一层要么按 id 整体替换某条目的 config，要么插入新条目。组合结果可用 dsh --profile web --dump-config 查看。

出处：docs/architecture.md（deepseek-harness-src/docs/architecture.md）

核心包脊柱（core spine）

七个包构成产品 API 脊柱（完整表见 docs/architecture.md）：

包	职责	`ctx` 键	类型
`core/session`	只追加事件日志与内存存储	`ctx.sessions`	core
`core/system-prompt`	提示词片段与工具 schema 组装	`ctx.systemPrompt`	core
`core/tools`	作用域工具注册表 + 把关执行流水线	`ctx.tools`	core
`core/agent`	Agent 接口、注册表、`agent/*` 事件	`ctx.agents`	core
`core/agent-loop`	实现该接口的默认驱动器	`ctx.agentLoop`	bundle
`core/scope`	按 agent 作用域的注册原语	库	core
`llm/llm`	消息/流式词汇 + 适配器 seam	`ctx.llm`	seam

事件域与数据流

DSH 的数据流围绕"三个事件域 + 一个日志"：

持久会话事件（写入 Session 日志，经 session/event 广播）：turn/*、step/*、user/message、assistant/*、tool/*；
实时 agent 事件（agent/*）：inbox、状态、pre-step、request、错误恢复、turn-stopping；
能力事件：seam 上的策略/适配器附加点（fs/*、tools/*、telemetry/*）。

派生产物全部从会话日志计算：模型历史（deriveMessages）、fork/恢复、transcript、遥测、标题、投影、压缩。

出处：docs/architecture.md 与 docs/event-producer-consumer.md

三大执行世界

从"能做什么"的视角，DSH 的能力集中在三个执行世界：

模型世界：LLM 适配（ctx.llm）、提示词组装（ctx.systemPrompt）、工具呈现（ctx.tools 的 native/Code Mode）；
本机世界：shell（ctx.shell）、subprocess（ctx.subprocess）、terminal（ctx.terminals）、fs（ctx.fs）、sandbox（ctx.sandbox）、LSP、code-runtime；
编排世界：subagent（ctx.subagents）、workflow（ctx.workflowEngine）、jobs（ctx.jobs）、goal（ctx.goals）、schedule。

NOTE

本机世界的各 seam 共享"同一执行世界"假设：把 fs/subprocess 提供方换成远程实现，shell/terminal/LSP 跟着换。这是 DSH 把"远程沙箱化"做成配置级能力的根基。

出处：docs/architecture.md（deepseek-harness-src/docs/architecture.md）

关键架构性质（复习清单）

性质	含义
一切皆插件	无特权内核；loop 也是插件
注册即副作用	每个 `register*` 返回 disposer；HMR 可撤销
模型可见 ⟺ 已记录	模型输入必须能从会话日志重建
能力缝三角色	Definition / Provider / Consumer 一体设计
fail loud	配置/加载错误带明确报错退出，绝不静默
作用域化	注册按 agent 作用域分层（agent → preset → global）

小结

宏观架构 = 组合式启动 + 事件驱动内核 + 会话事件溯源 + 能力缝模块化。接下来三章分别深入内核的三个最关键机制：轮次流程（2.2）、工具流水线（2.3）、LLM 层（2.4）。

参考资料

docs/architecture.md — 官方架构文档（deepseek-harness-src/docs/architecture.md）
docs/capability-seams.md — 服务全景表（deepseek-harness-src/docs/capability-seams.md）
packages/boot/app-boot/README.md — 启动引导
docs/module-graph.md — 包依赖图（生成）（deepseek-harness-src/docs/module-graph.md）

2.1 宏观架构总览 ​

一张图：DSH 的分层 ​

启动引导（boot sequence） ​

配置层叠 ​

核心包脊柱（core spine） ​

事件域与数据流 ​

三大执行世界 ​

关键架构性质（复习清单） ​

小结 ​

参考资料 ​