这是《DeepSeek Harness 权威指南 》系列的第 1 篇。 源码基线：deepseek-harness @
47f9438（v0.1.0-rc.5）；本地截图和命令输出均标注为 2026-08-16 的单次观察。
数据口径：这些数字说明什么，不说明什么
本文的 GitHub 数字取各项目仓库 REST API 的 stargazers_count 快照；表中的 dsh npm 数字取 downloads/point/last-week/@deepseek-ai/dsh 的 downloads 字段，即抓取日前滚动 7 天下载量。它不是安装量、活跃用户数、付费用户数，也不能直接推出生态成熟度。表中的“开源时间”和“用时”按各项目公开仓库日期计算到同一快照日。
在 2026-08-16 的快照中，dsh 的 GitHub star 为 120,895；仓库公开日期为 2026-08-13。这个速度值得记录，但本文不会把 star 或下载量当作框架能力的证据。能力判断以下面的插件结构、配置树和本机运行证据为准。
一、定义：三个关键词
官方仓库的描述只有一句话：
DeepSeek Harness: Everything is a Plugin.
这句话不是营销文案，是对架构的事实陈述。三个关键词拆开：
Harness（框架）。Harness 在 agent 语境下指"智能体的运行框架"：编排模型调用、工具执行、会话管理、权限控制这些外围工程。模型本身（如 DeepSeek V4）不在 harness 里，harness 是让模型能干活的脚手架。
Plugin（插件）。在 dsh 里，模型适配器是插件、工具注册表是插件、会话日志是插件、权限策略是插件、连 agent 主循环本身都是插件。没有一个需要打补丁的"特权内核"。
Everything（一切）。这里的“一切”不是靠固定插件数量定义。2026-08-16 的本机 Web 会话截图里，插件列表显示 133 个已挂载插件，包含 llm（模型层）、agent-loop（主循环）、tool-fs（文件工具）和 ui-conversation（对话界面）。这个计数取决于 commit、profile、操作系统、已安装插件、home patch 与命令行 overlay；它记录的是那次组装结果，不是 dsh 的固定产品规格。
图：2026-08-16 的本机 Web 会话插件列表截图。133 是该会话的观测值；不同版本、profile 与 patch 的结果会不同。
二、与 Claude Code、Codex、OpenClaw 的定位差异
先看数据（GitHub API 快照，核验时间 2026-08-16，star 数会持续变化）：
| 维度 | Claude Code | OpenAI Codex | OpenClaw | DeepSeek Harness |
|---|---|---|---|---|
| 开发者 | Anthropic | OpenAI | 社区（原 chatgpt-on-wechat 团队） | DeepSeek AI |
| GitHub stars | 141,598 | 106,175 | 386,426 | 120,895（3天） |
| 开源时间 | 2025-02 | 2025-04 | 2025-11 | 2026-08-13 |
| 语言 | Python | Rust | TypeScript | TypeScript |
| 核心定位 | 终端编程 agent | 终端编程 agent | 个人助理 agent | 可扩展 agent 框架 |
| 扩展方式 | Skills/子代理 | AGENTS.md/Skills | Skills/插件 | 一切皆插件（Cordis） |
| 默认形态 | CLI | CLI | CLI/多平台 | Web UI + Headless |
| 许可证 | 商业 | Apache-2.0 | MIT | MIT |
| 模型绑定 | Claude | GPT 系列 | 多模型 | 任意 OpenAI/Anthropic 兼容端点 |
这张表有三个值得注意的差异。
第一，模型中立是刻进设计的。 Claude Code 绑 Claude，Codex 绑 GPT，OpenClaw 是多模型个人助理。dsh 把"任意 OpenAI/Anthropic 兼容端点"做成一等公民——我们在设置界面确认过，自定义提供方支持 openai-completions、openai-responses、anthropic-messages 三种协议。一个 DeepSeek 出的框架，默认不绑定 DeepSeek 模型。
第二，不要把 dsh 与 Claude Code/Codex 简化成同类功能对比。 Claude Code、Codex 的目标是直接完成编程任务；dsh 的架构文档明确把会话日志、工具注册表、模型适配器和 agent loop 都列为可从配置替换的插件。需要开箱即用的编程 agent 时，前两者通常更省事；需要替换会话、工具、模型或运行表层时，dsh 提供的是可组装底座。本文不把这种架构差异表述成“唯一”或“绝对更好”。
第三，star 是发现信号，不是能力或生态结论。 3 天内的 120,895 star 说明该仓库在快照期获得了大量关注。仓库 README 的原文是“为你的插件仓库添加 dsh-plugin
话题，便于被发现。”这个 topic 只是带标签仓库的聚合入口；它不能单独证明话题由官方创建，也不能推出插件生态、教程需求或人才流动已经发生。
三、本地真实验证：两种运行形态
全部在本机真实跑过（Node v24.16.0 + pnpm 11.13.0）：
# 从源码构建
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
# 启动 Web UI
pnpm dsh web
# 输出：dsh web: http://127.0.0.1:3080
启动后的 Web UI 是一个完整的 agent 工作台：会话列表、工作区管理、模型配置、插件管理、权限模式（Workspace Write 等）、Agent 预设。界面流程是：内测声明 → 配置 API Key（可跳过）→ 主界面。
# Headless 模式：不用浏览器，一条命令跑完一个任务
pnpm dsh --profile headless --help
# Usage: dsh --profile headless [options] [task...]
# Answer one task, print the final assistant message, and exit.
web 和 headless 是同一个框架的两种组合：web profile = dsh-base + dsh-web-app，headless = dsh-base + dsh-headless，零代码切换。这是"一切皆插件"的第一个实际收益——同一套代码，两种产品形态。
图：本地真实运行的 dsh Web UI 主界面（侧边栏会话树 + 工作区 + 输入框）
四、选型边界
适合用 dsh 的场景：
- 要做 agent 产品，需要自定义工具集、审批流、会话存储——dsh 的插件 seam 提供标准扩展点，不用 fork 源码。
- 要接多家模型，不想被单一厂商绑定——模型适配器 seam 原生支持多协议。
- 要学习 agent 架构——在
47f9438的docs/subsystems/中可数到 46 篇中文.zh.md页面与 46 篇对应英文.md页面。这说明文档覆盖范围较广；它不等于每个 seam 都已完整说明，遇到具体改造仍应回到对应包和配置核对。 - 要定制 CLI/Web 形态——headless 和 web 只是两个 profile 模板，组合自己的 profile 是文档化的标准流程。
什么情况别选 dsh：
- 只要一个开箱即用的编程 agent——Claude Code / Codex 的默认体验更成熟。dsh 目前是开发者预览阶段；README.zh.md 的原文是：
DeepSeek Harness 目前处于 开发者预览 阶段，正在快速迭代。未来将出现破坏兼容性的变更。
生产集成应锁定版本或 commit，并在升级前做回归验证；这段声明不承诺插件 seam、配置格式或事件词汇在未来保持兼容。 2. 要极致的单任务性能——插件树带来灵活性的同时有组装开销，headless 单次任务不如专用 CLI 轻量。 3. 团队没有 TypeScript 基础——插件开发是 TS 生态，纯 Python 团队要补语言成本。
按你的诉求选：
要开箱即用的编程 agent？ → Claude Code / Codex
要多模型个人助理？ → OpenClaw
要可改造的 agent 底座（二开）？ → DeepSeek Harness
要理解 agent 原理？ → 两个都学：本系列 + 本站的 Rust harness 系列
五、系列路线
- 线 A（原理）：第 2 篇讲架构总览——“一切皆插件"在没有特权内核的前提下如何成立；第 3 篇深讲插件树（挂载/卸载/依赖注入/可逆副作用），这是理解 dsh 一切机制的地基；之后依次拆解会话与事件、工具系统、LLM 流式、安全沙箱。
- 线 B（实战）：从环境搭建和第一个插件开始，写工具插件、LLM 适配器、权限 hook、UI 节点，最后是一个完整的端到端实战案例（代码在 rex-dhs-core ）。
下一篇：架构总览：没有特权内核的插件世界
FAQ
Q：DeepSeek Harness 需要 GPU 吗？ 不需要。dsh 是本地运行的控制框架，通过 API 调用模型，推理在云端完成。本机只需要 Node.js 22.19+。
Q：DeepSeek Harness 只能配 DeepSeek 模型吗？ 不是。自定义提供方支持 openai-completions、openai-responses、anthropic-messages 三种协议，任何兼容端点都能接。
Q：它和本站之前的 Rust harness 系列是什么关系？ 《写一个 Coding Agent Harness》是"从零用 Rust 造一个 agent 框架"的教学系列（基于 grok-build 源码）；本系列是"理解并用好 DeepSeek Harness 这个生产级框架”。一个造轮子学原理，一个用轮子做产品，互为补充。
Q：现在学 dsh 会不会学完就过时？ 官方处于开发者预览阶段，接口会有破坏性变更。但架构思想（插件树、事件驱动、seam 设计）不会过时，本系列会随版本更新。学的是架构，不是 API 快照。
互动模块
① 站队：你更看好"终端编程 agent"（Claude Code/Codex）还是"可扩展 agent 框架"（dsh）路线？A. 终端 agent，开箱即用才是王道 B. 框架路线，可定制才有护城河 C. 现阶段两者都太早，看生态
② 征集：你在生产环境用过哪些 agent 框架/harness？遇到过什么"必须 fork 源码才能改"的痛点？评论区贴出你的经历，我会在二开系列里针对高频痛点出专题。
③ 转发：如果你身边有人正在纠结"该学哪个 agent 框架"，把这篇文章转给他——3 天 12 万 star 的项目值得花 5 分钟了解。