DeepSeek Harness：一切皆插件的开源 Agent 框架
本文由运行在 DeepSeek Harness 之上的 agent 撰写，写作前实际核查了本机安装的 @deepseek-ai/dsh 包（v0.1.2-rc.1）的约 200 个官方子包，以及 GitHub 官方仓库 的 README 与仓库元数据。一句话介绍
DeepSeek Harness（简称 dsh）是 DeepSeek AI 于 2026 年开源的通用 Agent 运行框架（agent harness）：它把"大模型 + 工具 + 文件系统 + 沙箱 + 会话管理 + 用户界面"打包成一个可扩展的运行时，让 AI agent 能像人类开发者一样在你的电脑上读写文件、执行命令、联网检索、拆解任务，并通过浏览器 GUI 与你协作。项目采用 MIT 协议，主力语言 TypeScript，仓库创建一个多月 star 数已超过 22 万。
官方对它的定位只有一句话："Everything is a Plugin."（一切皆插件）
核心理念：一切皆插件
DeepSeek Harness 构建在 Cordis 元框架之上（Cordis 是一个成熟的 JS/TS 插件化框架，配套论文《A Programming Paradigm for Spatiotemporal Composability》）。这个选择决定了整个项目的形态：
- 没有"核心功能"与"扩展功能"之分。文件读写、bash 执行、网页搜索、子 agent 调度、压缩记忆、GUI 聊天面板——全部是地位平等的插件。
- 能力通过"接缝"（seam）抽象。框架定义了
ctx.fs（文件系统）、ctx.shell（命令执行）、ctx.sandbox（沙箱）、ctx.web（联网）、ctx.jobs（后台任务）、ctx.subagents（子 agent）、ctx.compaction（上下文压缩）、ctx.approval（人工审批）等一批抽象服务接口，官方提供默认实现，你可以随时替换。 - 配置即层叠补丁。每个 profile 由一组插件包（bundle）的 patch 按顺序叠加而成，再依次套上用户级
cordis.patch.yml和命令行--patch覆盖层。不启动进程就能用--dump-config查看最终组合出的完整配置树。 - 模型也能写插件。运行时提供
cordis_define工具，agent 自己就能挂载/卸载动态插件——框架具备自指性。
目前官方 monorepo 内含约 200 个 @deepseek-ai/* 子包，从零依赖的工具库到完整的 GUI 应用，全部以插件形式组装。
架构分层
从下往上大致是四层：
层 | 内容 |
接缝层（seams） | 抽象能力接口： |
实现层 | 各接缝的官方实现：本地文件系统、本地子进程、Landlock/Seatbelt/ACL 沙箱、HTTP 抓取、DeepSeek 搜索等 |
Agent 层 | 工具注册与执行管线、系统提示词组装、agent 循环、压缩策略、会话持久化（JSONL 事件溯源 + SQLite 全文检索）、子 agent 与工作流引擎 |
入口层（profile） | 同一套核心，按 profile 组装成不同入口：Web GUI、一次性命令行、SDK 服务、ACP 服务 |
入口形态：一个启动器，多种用法
dsh 是唯一受支持的启动器，不同形态都是 profile，而非独立程序：
命令 | 用途 |
| 启动浏览器 GUI（默认 |
| 一次性执行：跑完打印最终答案即退出，适合脚本与 CI |
| 通过 stdio 上的 JSON-RPC 对外服务，供 SDK 客户端集成 |
| 极简 agent 配置树的 SDK 服务，适合学习与二次开发 |
| ACP（Agent Client Protocol）服务，供自动化客户端驱动 |
| 转发 pnpm，管理某个 profile 的第三方插件 |
profile 存放在 $DSH_HOME/profiles/<name> 下，首次使用时从随附模板自动初始化；patchReload: live 模式下改动补丁文件可热生效。
内置能力盘点
以本机运行的 web profile 为例，开箱即有的能力包括：
模型接入 — 官方 DeepSeek API 适配器、请求重试策略、模型目录与切换 UI。框架本身与模型解耦，理论上可接其他 OpenAI 兼容服务。
工具集 — bash / 持久化 PTY 终端 / pwsh、read / write / edit（带"先读后改"与版本守卫）、glob / grep（内置 ripgrep）、web_search / web_fetch、todo_write 任务清单、ask_user_question 向人提问、技能（skill）加载、目标（goal）管理、后台作业控制等。
子 agent 与编排 — subagent（后台委派独立子任务）、subagent_fork（继承当前对话上下文的分身）、workflow（用 JavaScript 脚本编排大规模多 agent 扇出，在 worker 线程执行）、Ralph 循环（全新 agent 迭代执行），以及跨 agent 的 send_message / interrupt_agent 消息机制。
安全模型 — 双层防护：
- 沙箱：Linux 用 Landlock/bwrap、macOS 用 Seatbelt、Windows 用 ACL 受限令牌，启动时功能探测、失败即拒绝（fail-closed）；文件策略如
workspace-write把写入限制在工作区与临时目录内。 - 审批：敏感操作按审批策略（如
ask）请求人类确认，无人应答时默认拒绝。
上下文工程 — 令牌表驱动的自动压缩（LLM 摘要）+ 工具结果剪枝；超长工具输出自动"溢出"到文件、只留预览与取回路径；事件溯源式会话日志支持断点恢复、跨会话引用与全文搜索。
生态兼容 — MCP 客户端桥接（把 MCP 服务器的工具注册进来）、Claude Code / Codex 的 hooks 配置桥接、AGENTS.md / CLAUDE.md 指令文件加载、GitHub webhook 触发会话等可选 overlay。
Web GUI — 三栏布局（会话树 / 对话 / 详情）、工具调用过程可视化、审批与提问卡片、计划模式、设置面板、多语言、明暗主题，全部同样是插件。
快速上手
# 需要先安装 Node.js
npx @deepseek-ai/dsh web # 启动并自动打开浏览器
npx @deepseek-ai/dsh web --no-open从源码运行：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build
pnpm dsh web运行目录即为默认工作区根目录，agent 的读写都发生在这里。
现状与注意事项
- 阶段：developer preview（当前版本 0.1.2-rc.1），官方明确警告会有破坏性变更，运行前建议阅读仓库中的
SAFETY.md安全须知。 - 协议：MIT，第三方依赖及许可在
THIRD_PARTY_NOTICES.md披露。 - 社区：通过 GitHub Discussions 反馈问题；自研插件可打上
dsh-plugin话题标签便于发现；另有官方 Discord。 - 文档：https://deepseek-harness.github.io/deepseek-harness/；学术引用见仓库 README 中的 BibTeX。
适合谁
- 想拥有一个"真·能干活"的编码 agent 的开发者：它和 Claude Code 属于同一物种，但完全开源、GUI 完整、可自由改装。
- 想做 agent 产品二次开发的团队：SDK / ACP 入口 + 接缝抽象，让你替换任意能力而不必 fork 整个框架。
- 想研究 agent 架构的人：约 200 个边界清晰的小包本身就是一份教科书级的 agent 系统设计样本——沙箱、审批、压缩、事件溯源、多 agent 编排，每个主题都有独立实现可读。
结语
如果说 ChatGPT 式产品把 agent 做成"黑盒应用"，DeepSeek Harness 则走了一条相反的路：把 agent 运行时的每一层都拆成可替换的插件，用配置层叠代替硬编码。"Everything is a Plugin" 不只是口号，而是它的目录结构本身。 在 agent 框架快速收敛的 2026 年，这种彻底的开放性正是它一个月拿下二十多万 star 的原因。