DeepSeek Harness 权威指南：架构解析与二次开发
本专栏是 DeepSeek Harness（
dsh）的中文权威指南，兼顾框架原理讲解与二次开发实战两条线。所有代码都在本机真实构建运行过，所有界面截图来自真实 Web UI，所有架构结论都标注了源码位置。
2026 年 8 月 13 日，DeepSeek AI 开源了 DeepSeek Harness——3 天收获 12 万 star，npm 周下载量逼近 20 万。 它的口号只有一句话：Everything is a Plugin（一切皆插件）。模型适配器是插件，工具是插件，会话日志是插件，连 agent 主循环本身都是插件。
这个专栏要回答的问题是：“一切皆插件"到底是营销口号，还是真的做到了？如果做到了，它是怎么做到的？ 以及更实际的——你如何基于它做二次开发？
快速上手（3 步）
# 1. 需要 Node.js 22.19+
npx @deepseek-ai/dsh web
# 2. 打开 http://127.0.0.1:3080
# 3. 设置 → 模型 → 填入 API 密钥（支持 DeepSeek 或任意 OpenAI 兼容端点）
系列目录
线 A：框架讲解（架构深度剖析，7 篇）
| # | 文章 | 回答的核心问题 |
|---|---|---|
| 1 | DeepSeek Harness 是什么：3 天 12 万 star 的 agent 框架 | 又一个 agent 框架，凭什么值得学？ |
| 2 | 架构总览：没有特权内核的插件世界 | 为什么每个组件都可以被替换？ |
| 3 | 插件树深讲：注册即副作用，卸载即撤销 | 插件如何做到可逆？ |
| 4 | 会话与事件：模型可见即已记录 | 日志为什么是唯一事实源？ |
| 5 | 工具系统：作用域与把关 | LLM 的信息通道宽度如何决定工具上限？ |
| 6 | LLM 与流式：适配器 seam 的边界 | 确定性系统如何与概率模型对齐？ |
| 7 | 能力 seam 与沙箱：自主与安全 | 自主性和安全性是零和的吗？ |
线 B：二次开发（8 篇）
| # | 文章 | 你会得到 |
|---|---|---|
| 1 | 环境与第一个插件 | 从源码构建 dsh，加载第一个 hello 插件 |
| 2 | 工具插件开发 | 给 agent 添加自己的工具 |
| 3 | LLM 适配器开发 | 接入任意模型端点 |
| 4 | Hook 与权限插件 | 拦截请求、控制审批 |
| 5 | Chat 节点：扩展对话 UI | 自定义对话消息节点 |
| 6 | MCP、Headless 与 Python SDK | 三种外部集成方式 |
| 7 | 插件打包与发布 | 让全世界用上你的插件 |
| 8 | 端到端实战案例 | 一个完整二开项目的全流程 |
这个专栏和其他资料有什么不同
- 官方文档是参考手册：告诉你每个字段在哪、每个配置是什么。它不回答"为什么”。
- 本专栏是权威指南：每个架构决策都有推演过程（方案 A vs 方案 B、为什么淘汰 A），每个机制都配架构图或时序图，每个关键界面都有真实截图，每段代码都真实运行过。
- 动手线：8 篇二开教程，从 hello world 到发布，含一个完整的端到端实战案例（代码在 rex-dhs-core 仓库）。
阅读建议
- 想先体验：读快速上手 → A 线第 1-2 篇 → B 线第 1-2 篇。
- 想深入原理：按 A 线顺序读，第 3 篇（插件树）是理解一切的基础，建议精读。
- 想直接二开：读 B 线第 1 篇后直接跳第 8 篇实战案例，回头再补原理。
- 做选型对比：直接看 A 线第 1 篇的对比表。
需要什么
- Node.js 22.19+（运行 dsh）
- 一个 LLM API 密钥（DeepSeek / OpenAI 兼容端点 / Anthropic 兼容端点均可）
- 想二开的话：TypeScript 基础 + pnpm
相关阅读
- 写一个 Coding Agent Harness and TUI：从零用 Rust 构建终端 AI 编程代理 ——本站另一个 harness 系列，用 Rust 从零实现一个 agent 框架，与本文互为对照
- DeepSeek V4 Pro 发布解读
