DeepSeek Harness 源码解析 · 第 1 讲
DeepSeek Harness 源码解析系列 第 1 讲：整体架构与 Cordis 插件框架 基于 DeepSeek Harness 源码 · 2026-08-15 一、系列介绍 DeepSeek Harness 是一个开源的 AI Agent 框架，由 DeepSeek 团队开发。它采用插件化架构，核心是一个名为 Cordis 的插件框架，所有能力（LLM、工具、Shell、文件系统、沙箱等）都作为插件注册到 Cordis 上下文中。 本系列共 44 讲，将从源码层面逐层剖析 Harness 的架构设计。本文将聚焦其最底层的基石——Cordis 插件框架和整体包结构。 二、项目结构总览 DeepSeek Harness 是一个 TypeScript monorepo，源码分为两个区域： 📁 项目目录结构 deepseek-harness/ ├── packages/ # 60+ 功能包（npm scope: @deepseek-ai/dsh-*） │ ├── core/ # 产品 API 骨干：Agent、Loop、Prompt、Tools │ ├── api/ # RPC 网关 │ ├── llm/ # LLM 适配器 │ ├── shell/ # Shell 执行能力 │ ├── fs/ # 文件系统能力 │ ├── sandbox/ # 沙箱隔离 │ ├── session/ # Session 持久化 │ └── ... # 其余能力包 ├── vendor/ # Cordis 框架及其基础库（源码 vendored） │ ├── cordis/ # 核心插件框架 │ ├── loader/ # 插件加载器 │ ├── include/ # YAML 表达式插值 │ ├── group/ # 插件分组 │ └── cosmokit/ # 工具库 ├── docs/ # 文档 └── AGENTS.md # 开发规范 整个架构的核心思想是： vendor/cordis 提供插件框架， packages/ 下的每个包是一个或多个插件，通过 cordis.yml 组合在一起。这种设计让框架本身只负责"如何运行插件"，而所有业务逻辑都在插件中。 三、Cordis 五大核心概念 Cordis 的官方文档 docs/cordis-primer.md 用五个概念概括了整个框架： Cordis 五大核心概念 🔹 Plugin（插件） — 实现了 Service 接口的对象，可以是函数（带 inject/apply）或 Service 子类 🔹 Context（上下文） — 服务的仓库，每个服务声明一个 ctx 键名如 ctx.tools、ctx.llm 🔹 Inject（依赖声明） — 插件通过 inject 声明依赖，加载顺序由依赖关系自动推导 🔹 Typed Events（类型化事件） — 服务通过 TypeScript 声明合并定义事件，支持 emit/waterfall/parallel/serial 四种分发模式 🔹 Reversible Effects（可逆注册） — 所有注册通过 ctx.effect()/ctx.on() 安装，卸载时自动撤销 四、Context：插件框架的心脏 Context 是 Cordis 最核心的类，它本质上是一个 Proxy —— 所有属性读取都通过服务解析器路由。源码如下： 📄 vendor/cordis/src/context.ts（第 1-33 行） export interface Context { /** Isolation map: service name → scope label */ [symbols.isolate]: Dict<symbol> /** Intercept map: service name → config merged into that service's per-plugin config */ [symbols.intercept]: Dict /** The root context of the application */ root: this /** Base URL used to resolve relative plugin/modu…