DeepSeek Harness 快速入门

2026-09-08 00:00    #AI   #工具   #DeepSeek  

DeepSeek AI 于 2026 年 8 月正式开源了 DeepSeek Harness（dsh），一个 Agent Harness（智能体框架），MIT 许可证，TypeScript 编写。

官方理念：Agent = Model + Harness；官方标语：Everything is a Plugin.（一切皆插件）

为什么需要 Harness

瓶颈不在模型智能，而在基础设施。OpenAI 100 万行代码实验，5 个月产出全部由 Agent 完成；LangChain 仅优化外部驾驭环境，让编码 Agent 在 Terminal Bench 2.0 从 52.8% 提升至 66.5%，底层模型参数未动。

AI 工程范式三次跃迁：

范式核心问题优化对象交互模式
提示词工程怎么把话说清楚Prompt 的措辞、格式、示例一问一答
上下文工程怎么给 AI 喂信息文档、代码片段、历史对话信息注入 → 生成
驾驭工程怎么让 Agent 可靠工作约束、反馈回路、控制系统人类掌舵，Agent 执行

核心架构：一切皆插件

Cordis 内核只负责插件加载/卸载/依赖管理；模型、工具、技能、会话、沙箱、存储、循环、调度、UI 全部由插件提供，通过服务与事件协作，配置层自由组合。无特权内核：每一项能力注册都是可逆副作用，插件卸载时自动撤销。

运行时关键机制：Profile + 组合包（Bundle）。运行中的 dsh 是一棵插件树，按序叠加：

1dsh --profile web --dump-config  # 打印出的任何条目，都可以由你自己的 patch 替换

四种运行模式

模式定位能力构成
标准模式功能完整的编码 Agent文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理与工作流
PTC 模式代码组合工具调用标准模式全部能力 + 模型用一个 TypeScript 程序组合多步操作，省 Token
极简模式最小化基准测试仅保留持久 bash 与 str_replace_editor 两个工具
创造模式自定义 Agent preset标准模式全部能力 + 运行时检查、插件实验与 preset 创作

快速安装

方式一：npm 一键安装（推荐）

1npx @deepseek-ai/dsh web

首次运行自动初始化 web 配置模板，默认地址 http://127.0.0.1:3080。dsh 把调用目录作为默认文件系统位置，建议先 cd 到项目目录再启动。

方式二：源码安装

1git clone https://github.com/deepseek-ai/deepseek-harness.git
2cd deepseek-harness
3pnpm install
4pnpm run build
5pnpm dsh web

方式三：Python SDK

1pip install deepseek-harness-sdk

SDK 自带运行时，无需系统 Node.js。

首次使用三步

  1. 配置模型：设置 → 模型，填 DeepSeek API 密钥（https://platform.deepseek.com/api_keys），保存即可用，无需重启。
  2. 选择工作区：点击"选择工作区"，添加项目目录并选中。选中前会话输入框不可用。
  3. 运行任务：输入指令，如 “Summarize this repository and identify its main packages."。

权限体系（安全等级从高到低）

权限说明
Read Only仅可读取工作区文件，无法修改、无法执行命令
Workspace Write允许读写当前工作目录内文件，可在工作目录执行命令，日常开发推荐
Full access完整文件系统访问，可读写任意路径，存在较高安全风险

常用命令速查

命令作用
npx @deepseek-ai/dsh web启动 Web UI（等价于 --profile web）
dsh --profile headless "任务"一次性运行任务，打印答案后退出（脚本/CI）
dsh plugin --profile <name> <pnpm 参数>管理某 profile 的插件
dsh --profile web --dump-config查看实际启动的完整配置树
dsh --profile web --dump-default-config查看默认配置树（不含用户 patch）

常见问题排错

  1. 端口打不开：端口占用用 dsh --profile web --port 8080
  2. npx 找不到：Node.js 版本太旧，或清空 npx 缓存
  3. 会话输入框不可用/无法读写文件：最常见原因是没选择工作区
  4. Python SDK 找不到 Node.js：需 Linux x64/arm64 或 macOS 14+ (arm64)

与相关工具的关系

项目定位与 dsh 的关系
Claude Code闭源商用编码助手功能对标，但 dsh 完全开源、可自托管、能力可替换
Hermes Agent自进化个人 Agent侧重跨会话记忆；dsh 侧重插件化组合与全程可观测
LangGraph/AutoGen/CrewAIAgent 构建框架框架解决"如何构建”；dsh 是完整 Harness——“如何稳定运行”

相关资源：官网 deepseek.com/harness，GitHub 仓库 github.com/deepseek-ai/deepseek-harness，插件社区 GitHub topics: dsh-plugin。