DeepSeek Harness 架构深度解析：一切皆插件的 Agent 运行时

文章目录

• • 概述
  • 一、Cordis：dsh 的插件底座
  • • 1.1 五个核心概念
    • 1.2 四种事件分发模式
    • 1.3 Waterfall 语义：环绕中间件
    • 1.4 Loader 与配置
  • 二、Profile 与 Bundle：组合的艺术
  • • 2.1 核心概念
    • 2.2 五层叠加模型
    • 2.3 dsh-base：78 个插件行的基础层
    • 2.4 模式 Bundle：Web 与 Headless
  • 三、核心包：六包构成的脊柱
  • • 3.1 Session：追加式日志，唯一真相源
    • 3.2 System Prompt：提示词组装器
    • 3.3 Tools：作用域注册表 + 守卫流水线
    • 3.4 Agent：接口、注册表与生命周期
    • 3.5 Agent Loop：默认驱动器
    • 3.6 Scope：按 Agent 划分作用域的原语
  • 四、轮次流程：一次问答的完整生命周期
  • • 4.1 Turn 与 Step 的定义
    • 4.2 流程图解
    • 4.3 Turn/Start 与 Claim
    • 4.4 Pre-Step：决策点
    • 4.5 Step/Start 与消息追加
    • 4.6 模型历史派生
    • 4.7 模型请求与流式响应
    • 4.8 工具调用批次
    • 4.9 Turn-Stopping 与 Turn/End
    • 4.10 输入路由：同一个 Inbox
    • 4.11 取消与错误恢复
  • 五、工具执行流水线
  • • 5.1 流水线全景
    • 5.2 Pre-Execute：允许/拒绝/询问
    • 5.3 Monotonic Guards：不可撤销的拒绝
    • 5.4 Execute：环绕分发
    • 5.5 Tool Body：实际执行
    • 5.6 Post-Execute：结果处理
    • 5.7 FinalizeContent：最后的内容守卫
    • 5.8 Tools/Result：不可变的权威结果
    • 5.9 并行工具调用
    • 5.10 UI 展示词汇
  • 六、能力缝（Capability Seam）：可替换性的设计模式
  • • 6.1 三角色模型
    • 6.2 核心能力缝一览
    • 6.3 Seam 的威力：一键切换执行环境
    • 6.4 新行为的归属位置
  • 七、事件三域：选择正确的事件
  • • 7.1 会话事件（Session Events）
    • 7.2 Agent 事件（`agent/*`）
    • 7.3 能力事件（Seam Events）
    • 7.4 Waterfall 事件汇总
    • 7.5 Serial 事件
  • 八、Agent Preset：按会话组合能力
  • • 8.1 为什么需要 Preset
    • 8.2 Preset 工作机制
    • 8.3 Isolate Realm
  • 九、LLM 流式接口
  • • 9.1 消息与内容块
    • 9.2 适配器注册
    • 9.3 请求配置
  • 十、其他关键子系统
  • • 10.1 Approval（审批）
    • 10.2 Credentials（凭证）
    • 10.3 Settings（设置）
    • 10.4 Sandbox（沙箱）
    • 10.5 Spill（溢出文件）
    • 10.6 Compaction（上下文压缩）
    • 10.7 Subagent（子Agent）
    • 10.8 Goal（目标）
    • 10.9 Workflow 与 Ralph
    • 10.10 Session Telemetry（遥测）
  • 十一、全仓通用类型模式
  • • 11.1 Map → Derived Union 模式
    • 11.2 品牌化 ID（Branded IDs）
  • 十二、运行时架构总览图
  • 附录 A：Cordis 核心 API 深度参考
  • • A.1 Context 上下文
    • A.2 Service 与 Config
    • A.3 Fiber：上下文隔离与继承
    • A.4 Inject 依赖声明
    • A.5 事件分发四种模式
  • 十三、会话日志深度解析
  • • 13.1 SessionEventMap 完整事件词汇
    • 13.2 请求头事件：可重建性的保证
    • 13.3 TurnEndReason：轮次为何结束
    • 13.4 deriveMessages()：从日志到模型历史
    • 13.5 追加式日志的不变量
  • 十四、Shell 与沙箱子系统深度解析
  • • 14.1 Shell 执行器：请求与规格分离
    • 14.2 正交结果独立报告
    • 14.3 沙箱模式与强制执行
    • 14.4 沙箱 argv 包装与方言分类
    • 14.5 沙箱策略解析
  • 十五、持久化子系统深度解析
  • • 15.1 持久化 Seam 架构
    • 15.2 批量写入与 Flush 检查点
    • 15.3 崩溃恢复
    • 15.4 SessionHeader：日志旁的元数据
    • 15.5 格式拒绝
  • 十六、审批子系统深度解析
  • • 16.1 审批模型
    • 16.2 按会话策略
    • 16.3 请求与分发
    • 16.4 审计事件
  • 十七、API Gateway 与 Typert 类型安全 RPC
  • • 17.1 编程模型
    • 17.2 组件职责
    • 17.3 严格生成流水线
    • 17.4 运行时调用流程
  • 十八、LLM 流式接口与适配器 Seam
  • • 18.1 消息词汇表
    • 18.2 适配器注册与重试策略
    • 18.3 请求配置与解析
  • 十九、其他关键子系统
  • • 19.1 文件系统子系统（ctx.fs）
    • 19.2 子进程子系统（ctx.subprocess）
    • 19.3 Jobs 后台任务（ctx.jobs）
    • 19.4 技能系统（ctx.skills）
    • 19.5 子 Agent（ctx.subagents）
    • 19.6 代码运行时（ctx.codeRuntime）
    • 19.7 会话投影与查询（ctx.sessionProjection / ctx.sessionQuery）
    • 19.8 会话遥测（ctx.sessionTelemetry）
    • 19.9 用户问题与命令
    • 19.10 定时器（ctx.timer）
    • 19.11 Web 能力（ctx.web）
  • 二十、系统提示词组装流水线
  • 二十一、工具定义 DSL 详解
  • • 工具输出的三种呈现
    • 工具结果的 additionalContexts
  • 二十二、测试架构与策略
  • • 22.1 单元测试（vitest）
    • 22.2 覆盖率门控（test:coverage）
    • 22.3 真实 API 端到端测试（test:e2e）
    • 22.4 快照测试（test:snapshot）
    • 22.5 源码启动测试
  • 二十三、防御性编程模式详解
  • • 23.1 正交结果独立报告
    • 23.2 空 catch 块必须命名所吞之物
    • 23.3 注册即副作用
    • 23.4 信任 TypeScript，在边界验证
    • 23.5 Waterfall 监听器必须调用 next()
    • 23.6 失败关闭（Fail-Closed）
  • 二十四、常见问题解答（FAQ）
  • 二十五、架构设计原则总结
  • 结语

概述

在 AI Agent 框架百花齐放的今天，大多数框架要么选择\”黑盒魔法\”路线，把循环逻辑硬编码在核心模块中；要么选择\”极简内核\”路线，把几乎所有能力都推给用户自行组装。DeepSeek Harness（以下简称 dsh）走出了第三条路：一切皆插件，但不是无政府主义的插件——而是有明确契约、可替换能力缝、严格生命周期管理的插件体系。

dsh 构建在自研的 Cordis 插件框架之上，采用\”服务定义 + 服务提供方 + 消费方\”三角色能力缝（capability seam）模式，使得从 LLM 适配器到文件系统、从 Shell 执行器到子 Agent 委派，每一个环节都可以被替换、被扩展、被组合，而无需修改核心循环代码。

本文将带你从底层框架到上层运行时，逐层拆解 dsh 的架构设计，理解它如何做到\”没有特权内核\”的同时保持系统的健壮性和可预测性。

一、Cordis：dsh 的插件底座

1.1 五个核心概念

Cordis 是 dsh 以 vendor 方式引入的插件框架，理解它是理解整个 dsh 架构的前提。Cordis 的设计可以概括为五个核心概念：