DeepSeek_Harness白皮书_从0到1玩转DeepSeek_Harness的新手百科全书_129页_5mb

DeepSeek Harness 白皮书总结

核心内容概览

DeepSeek Harness（dsh）是 DeepSeek 官方开源的 Agent 运行时，采用“一切皆插件”架构，基于 Cordis 插件容器构建。它为开发者提供了一个灵活、可定制的平台，使他们能够自由拼装各种功能插件，从而构建个性化的 Agent 系统。

主要观点

• dsh 是 Agent 的乐高底座：提供运行时 + 核心插件，开发者可以自由拼装插件，定制行为。
• harness 是模型外面的工程层：包含会话管理、工具调用、上下文控制、错误恢复等，让模型在代码仓库中真正干活。
• 与 Claude Code 的区别：Claude Code 是“整车”，而 dsh 是“底座 + 积木”，可定制性更高。
• 生态窗口：2026 年 8 月 13 日开源，中文教程此前为零，现在是早期入场的时机。
• 适用人群：适合想要深度定制、玩生态、在 CI 中运行 Agent 的开发者；开箱即用的选 Claude Code。

关键信息

功能与架构

• 支持的运行模式：web（Web UI）、headless（CLI）、tui（终端 UI，需插件）、creator（插件开发）。
• 插件系统：一切能力都是插件，开发者可以通过插件扩展功能。
• 配置结构：通过 settings.yaml 配置模型和推理档位，通过 cordis.patch.yml 挂载插件。
• 扩展点：包括 agent/request、conversationEvents.register、ctx.slots.inject、settings 服务等，用于改行为，而非 fork 核心。

性能与生态

• 推理档位：off（最快）、low（适合简单任务）、high（默认）、max（适合复杂推理）。
• 性能模型：模型在每次工具调用前重新思考，占约 90% 的时间，调低档位可显著提速。
• 生态阶段：目前处于早期阶段，但有官方鼓励社区参与，提供丰富的插件生态。

与主流 Agent 的对比

案例对比：任务执行方式

案例对比：真实工作流

学习路径与原则

3 天学习计划

• Day 1：理解 dsh 是什么，能独立启动、对话、配置。
• Day 2：理解 profile/插件机制，写出第一个能跑的插件。
• Day 3：能评估插件质量、调优性能、理解生态玩法。

学习原则

1. 动手 > 阅读：每章命令都跑一遍，不看会后悔。
2. 先复制后理解：第 4 章完整代码先跑通，再改参数理解机制。
3. 单测 + 实机双证据：开发插件时两个都要过。
4. 善用 --dump-config：疑惑时看合成配置，比猜快。

安装与运行

安装方式

1. 方式一：直接运行（推荐新手）
   npx -y @deepseek-ai/dsh web → http://127.0.0.1:3080

2. 方式二：全局安装（推荐频繁使用）
   npm install -g @deepseek-ai/dsh

3. 方式三：免装 Node 的安装包（新手可选）
   提供 mac DMG / Windows exe，自带 Node 运行时。

常见安装坑

• 首次 npx 极慢（Windows）：建议使用 npm install -g。
• pnpm dlx 404：建议使用 npx 或 npm install -g。
• macOS 全局安装解析不到插件：建议使用 npm i -g 或 npx。
• Node < 22.19：会触发两个致命缺失，建议升级 Node.js 到 ≥22.19。

命令速查

排障速查

总结

DeepSeek Harness 是一个开源、模型无关、插件化的 Agent 运行时，适合想要深度定制、玩生态、在 CI 中运行 Agent 的开发者。它提供了多种运行模式，包括 Web UI 和 Headless CLI，并且支持丰富的插件生态。虽然当前处于 rc 阶段，迭代快、有破坏性变更，但其开源和灵活性为开发者提供了巨大的定制空间。对于新手，从 0 到 1 仅需 3 天，即可掌握基本使用并开发第一个插件。