架构概览
DeepSeek Harness 的整体架构：一切皆插件、profile 与 bundle、核心包地图、事件、agent loop 与能力 seam
本文概述 Harness 的整体架构，帮你判断新行为该挂到哪个扩展点。它假定你已了解 Cordis。
一切皆插件
Cordis 是 dsh 底层的框架：插件向共享上下文贡献服务、类型化事件与可逆副作用。产品的每一部分都是插件——包括模型适配器、工具注册表、会话日志，以及 agent loop（智能体循环）本身——因此每一部分都能从配置替换。
没有需要打补丁的特权内核：扩展 dsh 就是把插件挂载到其他插件旁边，而各项注册都是副作用，会在插件卸载时撤销。
架构总览图
所有能力——模型路由、工具、循环、日志、策略——都挂在同一个 Cordis Context 上，因此每一项都能被替换。
Profile 与 bundle
运行中的 dsh 是一棵插件树，由启动时按序叠加的各层组合而成。
- profile 是存放在 Harness home 中的具名组装：列出它叠放的 bundle，存放树外插件，并保存用户自己的
cordis.patch.yml。web与headless随发行版交付。 - bundle（组合包） 是 Cordis 配置项及其挂载代码的分发格式。
两者都在各自 package.json 的 dsh 字段声明：dsh.profile 列出一个 profile 的 bundle，dsh.bundle 指向一个 bundle 的 patch 文件。
各层按此顺序应用：profile 列出的每个 bundle → profile 的 cordis.patch.yml → home 级的那份 → 任意 --patch overlay。查看机器实际启动的配置树：
dsh --profile web --dump-config核心包
以下是向 Cordis 树贡献内容的部分核心包。
| 包 | 职责 | ctx 键 |
|---|---|---|
core/session | 仅追加的 SessionEvent 日志与内存存储 | ctx.sessions |
core/system-prompt | 提示词片段与工具 schema 的组装 | ctx.systemPrompt |
core/tools | 作用域化工具注册表与带把关的执行流水线 | ctx.tools |
core/agent | Agent 接口、活跃注册表与 agent/* 事件 | ctx.agents |
core/agent-loop | 实现该接口的默认驱动器 | ctx.agentLoop |
llm/llm | 消息与流式词汇表，以及适配器 seam | ctx.llm |
事件
事件就是扩展点，选对事件域是大多数改动的第一个决定。
- 会话事件是追加到日志并通过
session/event广播的持久事实。当事实必须在重新加载后仍然存在时使用。 - Agent 事件（
agent/*）携带活跃Agent，用于观察或拦截进行中的工作。 - 能力事件无需导入循环即可向某个 seam（
fs/*、tools/*、telemetry/*）附加策略与适配器。
轮次流程
一个步骤是一次模型请求加上它调用的工具；一个轮次包含零个或多个步骤。模型依次经历：领取输入 → 组装提示词片段与工具 schema → 发起模型请求 → 流式返回 → 工具调用经 tools/pre-execute → tools/execute → tools/post-execute 流水线 → 产生工具结果，直到不再欠下任何工作。
turn/*、step/*、user/message、assistant/* 和 tool/* 是持久会话事件；agent/pre-step、agent/request、llm/stream 与三个 tools/* 事件是 waterfall（瀑布式事件），其监听器必须调用 next() 才能委托。
会话日志
会话日志是模型所见上下文的真源。模型可见即已记录：抵达模型请求的一切都必须能从日志重建。因此新增一项模型可见输入就需要新增一个会话事件。
能力 seam
一个 seam 是一项可替换能力，包含三种角色：声明接口的 Service Definition、实现它的 Service Provider，以及使用它的 Consumer（通常是面向模型的工具）。一个包可以合并承担多个角色，但单一角色不是 seam；添加一项能力意味着把三者一并设计。
seam 正是替换一个提供方就能改变整个产品的原因：文件系统与进程提供方共享同一执行世界，把它们指向远程沙箱，Bash、PTY 与 LSP 就一并搬了过去。
新行为的归属
| 目标 | 机制 |
|---|---|
| 添加模型提供方 | 在 ctx.llm 注册其适配器 |
| 添加面向模型的能力 | 在 ctx.tools 注册；其 schema 加入提示词组装 |
| 添加 shell 执行 | 注册 ctx.shell 后端 |
| 添加后台工作 | 在 ctx.jobs 注册 |
| 拦截请求、工具或轮次 | 使用相应的 agent/* 或 tools/* 事件 |
| 添加模型可见上下文 | 调用 agent.inject()，落到下一次获准的请求 |
| 添加持久会话状态 | 扩展 SessionEventMap，从日志渲染与回放 |