DeepSeek Harness in Depth

外观

使命 ​

用仓库自己的话来说，DeepSeek Harness（dsh）是：

由 DeepSeek AI 开发的开源 agent harness（智能体框架）。

所谓 agent harness（智能体框架），是包裹 LLM 代理的运行时外壳：它管理会话、向模型喂入上下文与工具 schema、执行模型调用的工具、执行沙箱与审批策略，并持久化对话记录。dsh 是 DeepSeek AI 对这一外壳的 实现，而且它的结构保证了外壳内的一切都是可替换的插件——没有特权的核心。

这句一句话概括直接来自根 README.md：

它采用一切皆插件的架构，并由 Cordis 驱动，其设计参见 论文 A Programming Paradigm for Spatiotemporal Composability。

这句话里的两个思想承载了整个设计。其一，基底是一个插件框架：框架建立在 Cordis 之上——一个内嵌的 框架，插件在其中向共享上下文注册服务、类型化的事件与可逆的效果。其二，一切都是插件：模型适配器、 工具注册表、会话日志，乃至 agent 主循环，全都只是挂载在这个上下文上的插件。 哲学一章将展开这给你带来什么。

运行它：Web UI ​

主要界面是一个浏览器应用。通过 npm：

sh
npx @deepseek-ai/dsh web

这会启动 Web UI，默认位于 http://127.0.0.1:3080。自 rc.8 起，Web UI 就绪后会在你的默认浏览器中自动打开 （通过 SSH 启动时跳过；传入 --no-open 可退出）。web 是 --profile web 的硬编码别名，它启动 web profile——启动器知道如何堆叠的、一个命名的、用户可编辑的插件组合（参见启动流程与 CLI）。 这个 profile 是 @deepseek-ai/dsh-web-app 束叠加在共享 @deepseek-ai/dsh-base 束之上，因此浏览器端 本身也只是一组插件行。

在 Web UI 中，你选择工作区、在 Settings → Models 中配置模型，然后运行任务。agent 可以读取/编辑 工作区文件、运行命令、委派工作并维护计划，在权限策略要求的操作前请求审批（参见用户指南）。

Headless 模式 ​

除了 Web UI，dsh 还附带一个headless（无头）一次性模式——一个没有服务器、没有 Host、没有浏览器的 运行器：

sh
dsh --profile headless "summarize this workspace"

@deepseek-ai/dsh-headless 束提供编码人格与工具模式，其 headless-runner 插件从注入的 headlessStartup 提供商读取任务，通过 ctx.agents 创建一个全新持久会话，把任务作为普通用户消息提交， 等待静默，打印最后一段非空 assistant 文本并退出（turn/end 正常结束 → 0，否则 1）。它不打开任何 监听端口。在 Web profile 中，同样的基础栈被使用，但叠加了浏览器行；headless 是在同一 dsh-base 之上的 真正不同端——参见 packages/bundle/headless/README.md。

SDK 与 JSON-RPC ​

对于程序化用途，存在一个真实的客户端/服务端故事，而不仅仅是 CLI：

  • @deepseek-ai/dsh-sdk-client、@deepseek-ai/dsh-sdk-jsonrpc-server、@deepseek-ai/dsh-sdk-protocol 位于 packages/sdk/， 定义了一个建立在 JSON-RPC 协议之上、由外部进程驱动框架的 SDK。
  • 仓库附带一个 Python SDK（deepseek-harness-sdk），其教程位于 docs/user/guide/python-sdk.md； 它通过 JSON-RPC 端驱动一个远程框架。
  • 一个现成的示例曾位于 examples/jsonrpc-agent，它通过 Python SDK 与 JSON-RPC 驱动一个无人值守的 编码 agent——随顶层 examples/ 层一起从仓库退役，因此上面的 SDK 教程才是仍有效的入口。

因此，除交互式 GUI 之外，dsh 还将其 agent 能力暴露为供自动化使用的线上协议。

盒内自带的内容 ​

已发布的启动器包让这些端具体化。位于 packages/bundle/ 的束家族已从三个扩展到六个——原有 base/web-app/headless 之外新增 acp-app、sdk-app 与 sdk-minimal（每个都对应一个随附的 profile 模板，见快速上手）：

包端角色
@deepseek-ai/dsh-base共享核心每个 profile 的第一层束：适配器、工具、持久化、策略、设置、凭据、遥测
@deepseek-ai/dsh-web-app浏览器添加 webserver、API 网关、浏览器插件清单、客户端 HMR 重载链
@deepseek-ai/dsh-headless一次性添加 headless 运行器；无 Host、无 HTTP 服务器、无浏览器
@deepseek-ai/dsh-acp-appACP stdio叠加在共享核心上的纯自动化 Agent Client Protocol 服务器端（acp profile）
@deepseek-ai/dsh-sdk-appSDK stdio叠加在共享核心上的 JSON-RPC harness 运行时（sdk profile）
@deepseek-ai/dsh-sdk-minimal独立不带共享核心、单独发布的极简双工具编码 agent（sdk-minimal profile）
@deepseek-ai/dsh（CLI）启动器dsh 二进制；通过叠加这些束层来启动一个 profile

这些包合在一起，正是让 npx @deepseek-ai/dsh web 与 --profile headless 都能工作的原因：启动器用 某个特定端的束来组合同一个共享核心。

示例与社区 ​

仓库的顶层 examples/ 目录已被退役（上游 commit 4125514a08 "refactor(repo): retire top-level examples"）——原先的 headless-agent、jsonrpc-agent、mcp-memory、web-cordis、web-schedule 与 acp-agent 演示不再随树发布。幸存的演示现在以补丁覆盖的形式位于 apps/cli/config/examples/{cordis,github-review,mcp-memory,schedule}，测试位于 apps/cli/tests/profiles/； 参见示例与演示。

README.md 记录了社区端：

  • 通过 GitHub Discussions 提交反馈或 bug 报告。
  • 为插件仓库打上 dsh-plugin GitHub 话题以便被发现。
  • 一个 DeepSeek Harness Discord 服务器（https://discord.gg/Ycq5dCaS4）。中文版 README.zh.md 额外介绍了企微群（WeCom）与微信公众号。

许可证与 Cordis 的关系 ​

dsh 采用 MIT 许可证（LICENSE）；第三方许可证披露于 THIRD_PARTY_NOTICES.md。尽管名字里有 「AI」，但该框架在核心层面并非针对特定模型：它以插件形式注册模型适配器（ctx.llm），而 DeepSeek 适配器只是其中之一。它依赖 Cordis 的方式值得注意：它并不像普通依赖那样从 npm 拉取 Cordis，而是把框架 内嵌进 monorepo 的 vendor/ 下（重命名进 @deepseek-ai 作用域，例如 @deepseek-ai/cordis），从而 完全拥有并可以修补自己的框架层。参见内嵌（Vendor）库。

延伸阅读 ​

  • 「一切皆插件」哲学 —— 架构核心思想。
  • 快速上手 —— 今天就安装并运行 dsh。
  • Monorepo 结构解剖 —— 一条 dsh 命令背后的 51 组、251 个包。
  • README.md —— 上游的一句话概括与运行说明。
  • docs/architecture.md —— 上游架构深入解析。
  • packages/bundle/web-app/README.md —— web 束的角色与局限。

DeepSeek Harness in Depth