0.1 什么是 Agent Harness

本章概览：先回答"Agent Harness 是什么、为什么需要"，再介绍 DeepSeek Harness（DSH）的定位、核心设计原则与整体面貌，为后续章节建立坐标系。

概述

**Agent Harness（智能体框架/外壳）**是承载、编排和运行 AI Agent 的软件基础设施。如果说大语言模型（LLM）是"大脑"，那么 Harness 就是"身体"：它负责把模型接入能力（工具、文件系统、Shell、网络）、管理会话与状态、控制执行循环、处理安全与权限，并对外提供交互界面（Web UI、命令行、API）。

一个现代 Agent Harness 通常要回答以下问题：

问题	对应基础设施
模型怎么接入？	LLM 适配层（provider adapter）
模型怎么反复调用工具直到完成任务？	agent loop（智能体循环）
工具从哪来、怎么被安全调用？	工具注册表 + 执行流水线
对话与执行历史怎么保存、恢复？	会话存储（session store）
怎么委派子任务？	subagent（子代理）机制
怎么让 Agent 有长期记忆与目标？	持久化、压缩、目标管理
怎么保证它不胡作非为？	沙箱、审批、权限策略

DeepSeek Harness（dsh）是 DeepSeek AI 开发的开源 Agent Harness，采用 "一切皆插件" 的架构，底层由 Cordis 插件框架驱动（Cordis 的设计论文为 A Programming Paradigm for Spatiotemporal Composability）。

出处：README.zh.md（deepseek-harness-src/README.zh.md）

DSH 的设计定位

一切皆插件，没有特权内核

DSH 最核心的设计主张是：产品的每一部分都是插件——模型适配器、工具注册表、会话日志、甚至 agent loop 本身，都作为插件挂载到 Cordis 上下文上，因此每一部分都可以通过配置替换。官方文档明确写道：

"不存在需要打补丁的特权内核：扩展 dsh 的方式是把插件挂载到其他插件旁边，而各项注册都是副作用，会在其插件卸载时撤销。"

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

这意味着 DSH 不是一个"改内核"的项目，而是一个**组合（composition）**的项目：运行中的 dsh 是一棵插件树，由启动时按序叠加的配置层（profile、组合包、patch）拼装而成。

以 Cordis 为骨架

Cordis 提供了三个关键抽象：

1. Context（上下文）：服务的仓库。服务通过 ctx.<key>（如 ctx.tools、ctx.llm）被其他插件发现，而不是 import 具体实现。
2. Plugin（插件）：贡献服务、类型化事件与可逆副作用的最小单元。
3. Events（事件）：插件的通信方式，支持 emit / waterfall / parallel / serial 四种派发模式。

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

能力缝（capability seam）：可替换能力的组织方式

DSH 把一个"可替换能力"组织为三种角色组成的 seam：

• Service Definition：声明接口的服务（如 ctx.sandbox 定义 confine(argv, policy)）；
• Service Provider：实现该接口的插件（如 Linux 上用 bwrap/Landlock、macOS 上用 sandbox-exec 的实现）；
• Consumer：使用该接口的插件（通常是面向模型的工具，如 tool-bash）。

更换一个提供方就能改变整个产品的行为。例如把文件系统与进程提供方指向远程沙箱，Bash、PTY、LSP 便一起迁往远程，无需为每个能力写专用分支。

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

会话即事件日志（event sourcing）

每个 Agent 的完整交互历史是一条只追加（append-only）的事件日志 SessionEvent，LLM 的模型消息历史是从日志派生出来的，而不是独立保存的。由此诞生一条贯穿全项目的不变式："模型可见即已记录"（Model-visible ⟺ logged）——任何到达模型请求的内容都必须能从会话日志重建。

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

DSH 的产品形态

DSH 目前提供三种运行形态（profile）：

形态	命令	说明
Web UI	dsh --profile web（别名 dsh web）	浏览器界面，默认 http://127.0.0.1:3080
Headless	dsh --profile headless "任务文本"	一次性任务：跑完打印最终答案并退出
自定义 profile	dsh plugin --profile <name> ...	通过 pnpm 管理自定义组合

出处：@deepseek-ai/dsh README.zh.md（本地已安装包 node_modules/@deepseek-ai/dsh/README.zh.md）

版本与生态现状

• 许可：MIT。
• 阶段：开发者预览（Developer Preview），官方明示"未来将出现破坏兼容性的变更"。
• 生态：插件以 @deepseek-ai/dsh-* 命名空间发布（npm scope），仓库采用 pnpm monorepo，packages/ 下按能力分组（core、llm、shell、sandbox、fs、subagent、workflow 等）。
• 社区：GitHub Discussions、dsh-plugin topic 便于插件被发现。

出处：README.zh.md 与 packages/README.md

与同类项目的对比视角

• 相比 LangChain 式的"库 + 编排链"，DSH 是运行时（runtime）：你启动一个完整产品，而不是在代码里调用库函数。
• 相比 Claude Code 等单体 agent 产品，DSH 把 agent 的每个部件都插件化、可替换，类似 VS Code 之于编辑器。
• 相比通用应用框架，DSH 内置了 agent 特有的部件：loop、inbox、会话日志、subagent、沙箱、审批，开箱即用。

小结与下一章

本章建立了 DSH 的总体认知：一个以 Cordis 为骨架、一切皆插件、事件驱动、会话事件溯源的 Agent Harness。下一章 0.2 快速上手 将把它跑起来，用第一手体验验证这些设计。

参考资料

• README.zh.md — 项目简介与运行方式（deepseek-harness-src/README.zh.md）
• docs/architecture.md — 官方架构文档（deepseek-harness-src/docs/architecture.md）
• docs/cordis-primer.md — Cordis 五个核心概念（deepseek-harness-src/docs/cordis-primer.md）
• docs/capability-seams.md — 能力缝全景图（deepseek-harness-src/docs/capability-seams.md）
• packages/README.md — 包分组总览（deepseek-harness-src/packages/README.md）
• Cordis 项目主页