DeepSeek Harness：不是一个应用，而是一种组装智能体的方法

本文不讨论安装步骤，也不把重点放在某个界面怎么使用。我们关心的是整个 Harness 如何被组织起来，以及这种结构能给非专业程序员带来什么开发启发。

如果只看 Web 界面，DeepSeek Harness 很像一个会读写代码、执行命令的聊天工具。但打开仓库后，真正值得研究的是另一件事：它如何把一个庞大的智能体系统，拆成一组可以理解、替换、组合和撤销的零件。

这也是 Harness 这个词最贴切的地方。它可以直译为“挽具”或“线束”：它本身不是马，也不是电器，而是把多个部分约束在一起，让它们按照预期协作。放到智能体领域，它连接的是模型、上下文、工具、执行环境、会话记录、人机审批和产品界面。

一、一个 Harness，究竟“托住”了什么？

普通聊天应用通常围绕一次“提问—回答”组织。智能体系统则不同：模型可能先读文件，再搜索代码，接着运行命令；过程中可能遇到权限限制，需要询问用户；也可能把子任务交给另一个智能体，等待结果后继续。

任何一环都可能失败、被替换、需要暂停，甚至需要从历史状态重新恢复。因此，智能体产品真正困难的部分，不只是“接入一个大模型”，而是让以下部分长期保持协作：

• 模型如何被调用，以及如何替换不同提供方；
• 工具有哪些，它们能看到什么、能修改什么；
• 会话如何记录，任务中断后如何继续；
• 权限在哪里收紧，什么时候必须询问人；
• Web、CLI 和 SDK 如何共享同一套能力；
• 新功能如何加入，又如何在实验失败时完整退出。

DeepSeek Harness 的回答不是造一个更大的中心控制器，而是把这些环节放进同一种插件机制里。模型适配器是插件，工具注册表是插件，会话日志是插件，连驱动任务向前运行的 agent loop 也可以作为插件存在。

共享上下文 ctx 不是一个什么都亲自处理的万能内核。它更像一条总线：插件把服务、事件和生命周期信号放到这里，其他插件再按声明的依赖来消费。这样一来，提供能力和使用能力的模块不必彼此写死。

二、仓库很大，但不是一团代码

从目录看，这是一个规模不小的 monorepo：核心 TypeScript 包位于 packages/，此外还有应用入口、Python SDK、原生沙箱实现、示例、文档站与构建脚本。只看包名很容易被数量吓住，但它们实际上围绕三个问题分层。

1. 智能体是什么？

会话、提示词、工具、模型请求与任务循环构成产品主干。它们决定一次任务怎样开始、模型看到什么、工具结果怎样返回，以及系统什么时候认为工作完成。

2. 智能体能做什么？

文件、进程、终端、网络、LSP 和子智能体等能力模块回答行动问题。它们不只是界面上的按钮，而是有明确输入、输出、权限和生命周期的执行能力。

3. 智能体如何成为产品？

权限、持久化、Web UI、API、SDK 与 Profile 负责边界和组装。同一套内核可以投射成不同产品形态，而不是每做一个入口就复制一份逻辑。

这种分组真正重要的地方，不是“文件放得整齐”，而是依赖方向。需要文件系统的工具面对的是 ctx.fs，并不需要知道背后是本地磁盘、受限沙箱还是远程环境。更换执行环境时，上层工具不必复制一套实现。

DeepSeek Harness/
├─ packages/           产品主干与可替换能力
├─ apps/               CLI 与产品入口
├─ python/             Python SDK 与运行时
├─ native/             操作系统级沙箱能力
├─ examples/           可运行的组装样例
└─ docs/ + website/    架构说明与文档投影

仓库不是按页面划分，而是按能力和运行边界划分。页面只是某种产品投影，并不等于系统本身。

三、插件树负责“有什么”，事件日志负责“发生了什么”

理解 Harness，需要同时看两张图。

第一张是静态的插件树。一个 Profile 先叠加基础组合包，再叠加 Web 或 Headless 表层，之后应用用户 patch 和临时 overlay。它像一张配方，决定当前进程里有哪些服务、工具和策略。

第二张是动态的事件流。任务开始后，系统领取输入、组装提示词、请求模型、记录流式输出、执行工具，再判断是否还欠下一步工作。轮次、步骤、用户消息、模型消息和工具调用都会写入仅追加的会话日志。

插件树回答“现在装了什么”，事件日志回答“刚才发生了什么”。这两者缺一不可：只有配置而没有历史，问题发生后只能猜；只有日志而没有结构，又难以判断一条事件来自哪个能力边界。

“模型可见即已记录”是整个设计里最值得非专业开发者记住的原则。

模型的行为常常难以解释。如果进入模型请求的内容都能由日志重建，那么系统至少可以回答“它当时看见了什么”。这比在报错后只留下一个最终字符串可靠得多，也为回放、恢复、分叉和界面渲染提供了共同基础。

四、Service、Provider、Consumer：把能力拆成三种角色

Harness 把一项可替换能力看作一条完整的连接缝，而不是一个孤立的函数。

1. Service Definition：声明这项能力能做什么，以及其他插件通过哪个 ctx 键找到它。
2. Service Provider：给出一种具体实现，例如本地文件系统或远程沙箱文件系统。
3. Consumer：使用能力完成产品行为，常见形式是暴露给模型的工具。

这种拆法看起来比直接写一个函数更麻烦，却换来一种重要自由：产品行为与基础设施不再绑定。Shell、PTY 和 LSP 可以共享同一个执行世界；只要替换底层提供方，多个上层能力会一起迁移，而不是各改一遍。

另一个关键概念是可逆副作用。插件向上下文注册事件监听、工具 schema 和适配器时，也交出对应的清理方式。卸载插件不是“以后不再调用它”，而是撤销它对系统造成的影响。这让热重载、自修改与实验性功能不至于留下幽灵状态。

五、给非专业开发者的四点启发

个人开发最宝贵的不是掌握更多框架，而是降低“改一个地方，坏一大片”的概率。我们不必复制 DeepSeek Harness 的规模，但可以借走它的思路。

启发一：先组合，再编写

非专业程序员最容易陷入的困境，是一开始就想把“完整应用”写出来。Harness 给出的相反路径是：先列出需要哪些能力，再为每项能力找一个现成实现，最后用配置把它们拼起来。

你不需要先成为文件系统、模型调用和进程管理专家，才能做出一个有用的智能体。

可以马上尝试： 做自己的工具时，先写一张能力清单：输入、模型、文件、输出、审批。只有缺失的那一格才需要编码。

启发二：让配置成为结构图

在许多个人项目里，模块关系藏在 import 和启动脚本深处。Harness 的 Profile 与 patch 把“系统由什么组成”写成可阅读的插件树。

配置不只是参数表，它是架构的显式表达：加一层、换一层、临时覆盖一层，变化都能被看见。

可以马上尝试： 把可变选择放到配置，把稳定规则留在代码。以后换模型、换存储、换权限策略时，不必拆掉整个项目。

启发三：把修改设计成可撤销

插件挂载时注册服务、事件和工具，卸载时一并清理。这个看似工程化的细节，对业余开发尤其重要：实验总会失败，真正安全的系统不是“永远不出错”，而是允许你加上一个想法、观察效果，再完整地拿掉它。

可以马上尝试： 每次创建监听器、定时器、临时文件或连接时，同时写下它如何结束。能撤销的实验，才敢频繁进行。

启发四：记录过程，而不只保存结果

Harness 用仅追加事件日志记录轮次、消息、模型输出和工具调用。最终答案只是过程的一次投影。

对非专业开发者而言，这意味着调试不必依赖猜测：系统当时看到了什么、做了什么、为什么继续下一步，都能从事件中还原。

可以马上尝试： 为自动化项目保留“发生过什么”的时间线。日志应能回答问题，而不只是堆叠报错文本。

结语：让复杂性可以被一块块理解

DeepSeek Harness 仍是一套面向专业工程的预览项目，它的包数量、类型约束和测试纪律都远超普通个人项目。但它对非专业程序员依然有启发：不要把自己的应用想成一座必须一次建成的大楼，而要把它想成一组有明确接口、能够替换、知道如何退出，并且留下过程记录的小模块。

当系统能说清楚“由什么组成”“发生过什么”“一项能力可以换成什么”，开发就不再只是不断往代码里追加功能，而是在经营一个可以继续生长的结构。

本文基于本地 DeepSeek Harness 仓库的 README、架构文档、Cordis 入门说明与包目录整理，为非官方结构阅读札记。