DeepSeek Harness：插件化智能体框架

1. 项目概述

DeepSeek Harness (dsh) 是 DeepSeek AI 推出的开源插件化智能体框架，允许开发者构建、运行并全链路追踪 AI 智能体——从每一次模型调用和工具执行，直至沙箱内的代码运行——系统中的任何组件均可作为插件进行替换或重组。

2. 背景与定位

DeepSeek Harness 的诞生旨在为社区提供开放、可复用且可组合的基础设施，用于探索 AI 智能体在真实环境中的能力边界，避免每个团队都从零开始重复搭建相同的智能体脚手架——包括模型路由、工具执行、沙箱隔离、会话存储和任务调度等。

该项目的核心使命正如其自身所言：“一切皆插件”。该框架构建于 Cordis 之上，这是一个专为其作者所称的“时空可组合性”而设计的插件运行时——即无需重构周边系统，即可添加、移除或热插拔各类能力（模型、工具、技能、沙箱、存储）。

它与众多其他智能体框架的区别在于这种端到端统一的插件模型：模型、工具、技能、会话、沙箱、存储、调度循环乃至 Web UI，都是基于同一底层基座构建的一等公民插件，而非在一个固定核心上外挂少量扩展点。结合仅追加模式的会话日志以实现完整追踪，它主要面向那些不仅需要智能体给出答案，更需要对其行为进行检查、回放和审计的团队。

3. 功能分类

🧩 插件系统 —— 基础层；每项能力（模型、工具、技能、会话、沙箱、存储、循环、调度、UI）均实现为 Cordis 插件，可独立替换，使团队无需 Fork 核心代码即可自由混搭组件。
🤖 模型与工具编排 —— 可插拔的模型后端以及面向编程智能体的完整工具集，涵盖文件编辑、Shell 访问和网络搜索，使智能体能够在真实的代码库和环境中运行。
📝 会话记录与回放 —— 仅追加模式的会话日志记录了每一次模型交互，支持对过往智能体运行过程进行检查、恢复、分支创建及回放，便于调试与审计。
🖥️ 多种运行时模式 —— 标准模式（完整的编程智能体工具集）、代码模式（基于 TypeScript 的工具编排）、精简模式（轻量级基准测试环境）以及创作者模式（自定义预设开发及运行时实时检查），覆盖从生产级智能体到受控基准测试的各类用例。
🌐 Web UI —— 内置浏览器界面（本地提供服务，例如 http://127.0.0.1:3080），无需额外工具即可与运行中的智能体交互并观察其状态。
🔌 社区插件生态 —— GitHub 上有数百个标记为 dsh-plugin 的第三方插件，涵盖视觉/多模态扩展、沙箱、MCP 集成、终端 UI 及工作流工具。

4. 核心亮点

一切皆插件 —— 模型、工具、技能、会话、沙箱、存储、循环、调度和 UI 均采用相同的方式实现与替换，扩展系统时只需掌握一套统一的心智模型。
设计层面的全链路追踪 —— 会话状态采用仅追加模式，任何一次智能体运行均可被检查、恢复、分支创建或回放，这对于调试非确定性的智能体行为至关重要。
基于 Cordis 构建 —— 依托专用的插件运行时（详见论文《A Programming Paradigm for Spatiotemporal Composability》），而非临时拼凑的扩展机制，赋予了插件系统坚实的理论基础。
Host/Client 聚合架构 —— 代码库将 Host 包（tsconfig.host.json）与 Client 包（tsconfig.client.json）清晰分离，确保双方能安全地使用不同服务扩展同一个 Cordis Context 接口，避免类型冲突。
开箱即用的多种运行时预设 —— 标准、代码、精简及创作者模式分别覆盖了编程智能体、TypeScript 编排的工具调用、轻量级基准测试及自定义预设编写，无需额外配置。
零安装快速启动 —— 执行 npx @deepseek-ai/dsh web 即可立即启动可用的 Web UI，极大降低了初次使用门槛。

5. 按角色划分的使用场景

通用开发者：使用标准运行时模式启动配备文件编辑、Shell 及网络搜索工具的编程智能体，并通过 Web UI 驱动其完成日常开发任务。
DevOps/SRE：利用沙箱执行环境和仅追加会话日志来运行及审计自动化运维智能体，并在排查故障时回放历史运行记录。
数据/研究科学家：使用精简模式作为受控基准测试环境，在缩减且可复现的工具集中评估智能体或模型行为，并利用会话回放进行分析。
项目经理 / 平台团队：采用创作者模式组装并检查专为团队工作流定制的智能体预设，随后将其作为可复用插件分发。

6. 快速入门

查找所需资源 —— 浏览官方文档、开发指南以及 GitHub 上标记为 dsh-plugin 的社区插件。

安装 / 集成 —— 最快捷的方式是通过 npm，无需克隆仓库：

npx @deepseek-ai/dsh web

这将在 http://127.0.0.1:3080 启动 Web UI。若需从源码构建：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

参与贡献 —— 请阅读仓库中的 CONTRIBUTING.md 和 AGENTS.md，然后在提交更改前运行相关检查：

pnpm run typecheck
pnpm run lint
pnpm run check:all

7. 项目结构

deepseek-harness/
├── tsconfig.json          # 解决方案根目录 / tsserver 发现入口
├── tsconfig.base.json      # 共享编译器选项与路径解析
├── tsconfig.host.json      # Host 聚合：host 包、示例、测试、脚本、网站
├── tsconfig.client.json    # Client 聚合：packages/client/* 及浏览器应用
├── api/remotes/            # 唯一跨 Host 和 Client 配置拆分的包
├── docs/                   # 开发、架构及用户指南
└── AGENTS.md                # 面向智能体贡献的规范约定

每个包只能注册到一个聚合（Host 或 Client）中，绝不可同时属于两者，这避免了当双方共同编译时，经声明合并的 Cordis Context 接口发生冲突。

8. 相关生态

Cordis —— DeepSeek Harness 所基于的底层插件运行时框架，为插件提供了“时空可组合性”模型。
Model Context Protocol (MCP) —— 作为集成层受到支持，允许通过 MCP 服务器向智能体暴露外部工具（如统计或数据分析工具）。
社区插件 —— 在 GitHub dsh-plugin 话题下拥有超过 800 个仓库的不断壮大的生态系统，包括视觉/多模态插件、沙箱提供商、终端 UI 及 Web UI 主题皮肤。

9. 许可证

✅ 根据宽松的 MIT 许可证，可使用、修改和分发代码，包括用于商业目的。
✅ 可将 DeepSeek Harness 集成到专有产品中，前提是保留许可证和版权声明。
❌ 不提供任何担保——软件按“原样”提供。
ℹ️ 第三方依赖项遵循各自的许可证，已在 THIRD_PARTY_NOTICES.md 中单独说明。

10. 常见问题

问：DeepSeek Harness 是否已准备好用于生产环境？
答：目前处于开发者预览阶段且迭代迅速，维护者明确警告可能存在破坏兼容性的变更——在生产环境中依赖它之前请务必谨慎评估。

问：什么是 Cordis，为什么项目依赖于它？
答：Cordis 是支撑 DeepSeek Harness “一切皆插件”架构的底层插件运行时框架；关于设计理念，请参阅仓库中引用的论文《A Programming Paradigm for Spatiotemporal Composability》。

问：如何在不从源码构建的情况下试用？
答：运行 npx @deepseek-ai/dsh web 即可在本地 http://127.0.0.1:3080 启动 Web UI。

问：我可以编写自己的插件吗？
答：可以——插件使用 @Remote 或 @RemoteScope 装饰器在 Host 服务端声明，并在 Client 端通过 ctx.remote 消费；详情请参阅开发指南。

问：在哪里可以找到社区构建的插件？
答：浏览 GitHub 上的 dsh-plugin 话题，其中列出了用于视觉处理、沙箱、终端 UI 等的第三方插件。

11. 快速链接

代码仓库：https://github.com/deepseek-ai/deepseek-harness
开发指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
贡献指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md
社区讨论：仓库的 GitHub Discussions 以及专属 Discord 社区

12. 总结

DeepSeek Harness 提供了一种统一且完全可追踪的插件架构用于构建 AI 智能体，使团队能够在不重构技术栈的前提下自由替换模型、工具、沙箱和存储。它最适合那些需要可审计、可回放的智能体运行记录，并且能够适应快速迭代的开发者预览版而非稳定长期支持版的开发者和团队。