DeepSeek Harness 完整上手指南：部署安装、模型配置到必装社区插件

发布日期：2026年8月18日 | 话题：AI Agent · DeepSeek · 开发者工具 · 插件生态

DeepSeek Harness（dsh）是DeepSeek AI于2026年8月13日开源的Agent运行框架，5天内累计15万星，MIT协议，核心理念是"一切皆插件"——模型、工具、技能、会话、沙箱、存储、循环、调度、UI等所有Agent能力均由插件提供，通过Cordis内核加载和依赖管理，开发者无需改动源码即可在配置层自由替换和组合。这篇文章覆盖从零到跑通第一个任务的完整链路：两分钟npx快速部署、官方DeepSeek API接入、自定义提供方配置（以七牛云为例）、四种运行模式的选择逻辑，以及从社区15万星仓库里精选的高质量插件。

DeepSeek Harness 是什么，凭什么5天冲上15万星

DeepSeek Harness不是模型，不是IDE，而是一个Agent运行框架（Harness）。官方定位是：

Agent = Model + Harness 模型是Agent的灵魂。Harness给予Agent理解环境、使用工具，并在真实场景中持续工作的能力。

和Claude Code、Codex等一体化工具不同，DeepSeek Harness把每一项能力都做成可插拔的插件——你可以换掉默认模型、替换UI、接入自定义存储、或者通过社区插件扩展工具集，而不需要fork仓库或改动源码。

另一个关键设计是运行可追溯性：模型看到的一切都写入仅追加设计的会话日志，包括系统提示词、思维链、工具调用与结果、子Agent调度，以及每一次上下文注入。在Trajectory视图里，你可以按来源查看这些信息，还可以恢复、分叉、检索与回放。这对调试Agent行为极为有价值。

15万星的积累速度（前两天就达到9.5万）说明需求是真实的：开发者需要一个足够灵活、可审计、可替换组件的Agent运行环境，而不是被单一厂商的工具链锁定。

两分钟部署：npx 一行启动 vs 源码安装

快速体验（推荐首次安装）

安装Node.js后，直接运行：

npx @deepseek-ai/dsh web

命令自动拉取并启动Web UI，服务默认跑在 http://127.0.0.1:3080，浏览器打开即可开始配置。不需要事先clone仓库，适合快速验证。

源码安装（完整项目，适合自定义开发）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

源码安装给你完整的项目结构，可以修改插件、查看文档、参与开发。如果你打算写自己的dsh插件，从源码安装起步更方便。

注意：DeepSeek Harness目前处于开发者预览版阶段，官方明确说明会有兼容性破坏性变更（COMPATIBILITY-BREAKING CHANGES）。正式项目依赖时注意锁定版本。

模型配置（一）：接入官方 DeepSeek API

Web UI启动后，第一件事是配置模型。

打开 Settings → Models，DeepSeek卡片已预置，只需要一个操作：

在DeepSeek卡片的API Key字段输入密钥（从 platform.deepseek.com 获取）
点击保存

模型路由立即可用，不需要重启服务器。API Key存储在 $DSH_HOME/.credentials.yaml，页面只保留凭证引用，不会在设置中明文存储密钥。

默认 $DSH_HOME 是 ~/.dsh，你可以通过环境变量覆盖：

export DSH_HOME=/path/to/your/dsh-home
npx @deepseek-ai/dsh web

如果你更喜欢通过环境变量而非Web UI管理密钥，也可以在启动时通过环境变量传入（具体settings.yaml格式参见 dsh-llm-deepseek文档）：

export DEEPSEEK_API_KEY=sk-your-deepseek-key
npx @deepseek-ai/dsh web

模型配置（二）：添加自定义提供方（以七牛云为例）

DeepSeek Harness支持接入任意OpenAI兼容端点作为自定义提供方。这对于需要使用国内稳定API、或希望通过聚合平台统一管理多个模型的团队特别实用。

以七牛云AI大模型广场（qiniu.com/ai/models）为例，该平台支持DeepSeek、Kimi、GLM、MiniMax等25个主流国产模型，兼容OpenAI接口格式，一个API Key统一接入。

Web UI配置步骤

在 Settings → Models 页面：

点击 Add a custom provider
填写以下字段：

字段	值
Provider ID	`qiniu`（全小写，创建后不可改名）
Display name	七牛云AI大模型广场
Base URL	`https://api.qnaigc.com/v1`
API protocol	OpenAI compatible
API Key	从七牛云控制台获取

点击 Fetch available models 自动拉取模型列表，勾选你需要的模型
点击保存

settings.yaml 方式（推荐生产环境）

llm-pi-ai:
  providers:
    qiniu:
      apiKeyEnv: QINIU_API_KEY
      api: openai-completions
      baseURL: https://api.qnaigc.com/v1
      models:
        - id: deepseek/deepseek-v4-flash
        - id: deepseek/deepseek-v4-pro
        - id: moonshotai/kimi-k3
        - id: z-ai/glm-5.2
        - id: minimax/minimax-m3

配置后启动：

export QINIU_API_KEY=sk-your-qiniu-key
npx @deepseek-ai/dsh web

进入模型选择器，选择 qiniu/deepseek-v4-flash（或你添加的任何模型）。选定后，该模型成为新会话的默认模型。

注意事项：手动输入的模型默认被视为纯文本模型。如果你添加的模型支持图片输入，需要在 settings.yaml 里为该模型添加 input: [text, image]；否则，携带图片的请求会在发送前被拒绝。

四种运行模式：选对模式省一半力气

DeepSeek Harness提供四种预置模式（preset），应对不同任务场景：

标准模式（Standard） — 日常编码Agent的首选

功能最全面：文件编辑、Shell执行、文件与网页检索、Skills、计划、目标、子Agent调度和工作流。绝大多数编程任务用这个模式就够了。

PTC模式（Program-Tool-Call） — 复杂多步操作专用

在标准模式的基础上，通过Code Mode SDK向模型呈现工具——让模型用一段TypeScript程序来组合多轮工具调用，而不是逐步执行。适合需要动态组合多步操作、流程逻辑复杂的场景。

极简模式（Minimal） — 基准测试和最小化环境

只保留两个工具：持久bash和str_replace_editor。没有额外工具噪音，适合对模型能力进行受控测试，或在资源受限环境下运行Agent。

创造模式（Creation） — 构建自定义Agent preset

具备标准模式的全部能力，同时提供运行时检查、内存中插件实验、以及创作新preset的引导界面。如果你想构建自己的定制Agent，从这个模式开始。

在Web UI中，点击会话输入框左侧的模式选择器切换预设模式；通过源码安装可以在创造模式里创建并保存自定义preset，下次启动时直接加载。

社区必装插件：从 dsh-plugin 标签精选

GitHub上以 dsh-plugin 标签发布的社区插件已有数百个，以下是按Star数精选的高质量插件（数据截至2026年8月18日）：

open-design（88,349 stars）— nexu-io/open-design

DeepSeek Harness设计生成插件，支持原型、落地页、仪表盘、幻灯片、图片和视频生成，输出真实文件（HTML/PDF/PPTX/MP4）。它同时兼容Claude Code、Codex、Cursor等20多个AI CLI工具（BYOK模式）。适合需要AI生成可交付视觉产出的团队。

# 通过插件市场（Settings → Plugins）搜索安装
# 或访问 github.com/nexu-io/open-design 按仓库说明本地加载

OpenViking（28,909 stars）— volcengine/OpenViking

自进化上下文数据库，统一Agent记忆、知识RAG和技能管理。解决的是长会话和多Agent场景下的信息持久化问题：Agent之前的工作成果、代码规范、项目背景都可以作为知识库持续积累和检索。

voyager（19,597 stars）— Nagi-ovo/voyager

面向Gemini、AI Studio、Claude、ChatGPT的增强套件，内置提示词管理器，兼容包括DeepSeek Harness在内的任意Web UI。如果你需要在Harness里维护一套精细的提示词库，voyager提供可视化管理界面。

archify（13,884 stars）— tt-a1i/archify

架构图、工作流、时序图、数据流、生命周期图生成技能。输出自包含HTML，支持动效和清晰导出。适合技术文档、系统设计评审场景。

EverOS（12,085 stars）— EverMind-AI/EverOS

便携记忆层：本地优先、Markdown原生、用户所有，跨应用工具和工作流持久化。与OpenViking的区别在于EverOS更强调本地优先和用户主权，不依赖云端存储。

跑第一个任务：让 Agent 真正动起来

完成部署和模型配置后，选择工作区（项目目录），在会话输入框发送：

Summarize this repository and identify its main packages.

这是官方文档推荐的入门任务。Agent会：

读取项目目录结构
分析主要包和依赖关系
生成摘要报告

如果遇到需要权限审批的操作（比如执行Shell命令），Web UI会弹出审批请求，你确认后才会继续。

几个实用的入门任务变体，逐步验证Agent能力：

# 验证文件读写能力
List all TODO comments in the codebase and create a TODO.md summary.

# 验证执行能力
Run the test suite and summarize the results.

# 验证多步任务
Find all functions longer than 100 lines and refactor the longest one, 
then run tests to verify nothing broke.

观察Trajectory视图，你可以看到Agent的完整思维链、每次工具调用的输入输出，以及每步耗时。这是DeepSeek Harness最有价值的调试工具之一。

FAQ

DeepSeek Harness和Claude Code、Codex有什么本质区别？

Claude Code和Codex是厂商一体化的编程Agent工具，模型、工具、Agent循环深度耦合，灵活性受限于厂商。DeepSeek Harness是一个开放的Agent运行框架，所有组件都是插件——你可以保留Harness的基础设施，替换掉模型、UI、工具，甚至Agent循环本身。两者定位不同：一个是产品，一个是框架。

开发者预览阶段意味着什么，能用于生产吗？

DeepSeek明确说明"会有兼容性破坏性变更"。这意味着API签名、配置字段名、插件接口可能在版本间不向后兼容。对于个人项目和实验性使用完全没问题；正式生产环境使用前，建议锁定具体版本号，并在升级前阅读changelog。

Cordis是什么，为什么选择它作为内核？

Cordis是一个元框架，只负责插件的加载、卸载和依赖关系管理，本身不承载任何Agent能力。DeepSeek Harness基于Cordis构建，让所有能力都通过插件的服务与事件机制协作。Cordis的论文《A Programming Paradigm for Spatiotemporal Composability》描述了这种设计的理论基础。

自定义提供方的Provider ID可以改吗？

不可以直接改名，因为已有的请求记录、保存的会话、模型默认配置都引用了Provider ID。如果需要"重命名"，正确做法是添加一个新Provider ID的提供方，然后删除旧的。Display name、Base URL、API Key和模型列表都可以随时编辑。

总结

DeepSeek Harness用"一切皆插件"的架构重新定义了Agent运行框架的边界：开发者不需要在工具链上妥协，可以自由替换模型、扩展工具、接入自定义提供方，同时拥有完整的运行轨迹可追溯性。从npx一行启动，到接入官方DeepSeek API或自定义提供方（如七牛云等OpenAI兼容平台），再到通过社区高星插件扩展能力，整个链路的上手成本很低。当前处于开发者预览阶段，锁定版本使用、关注社区插件质量（特别是供应链安全）是两个值得注意的实践原则。

本文数据来源：DeepSeek Harness官网（deepseek.com/harness，2026年8月）、GitHub仓库（github.com/deepseek-ai/deepseek-harness，Stars数据截至2026年8月18日）、官方文档（docs/user/guide/providers.md，2026年8月版）、社区插件Stars数据来自GitHub Topics：dsh-plugin（2026年8月18日）。

延伸阅读