一、简介DeepSeek Harness简称dsh是 DeepSeek AI 于 2026年8月13日开源的 Agent智能体运行时框架。它基于“一切皆插件”的架构理念由 Cordis 微内核驱动。核心定位把大模型的理解推理能力与可扩展的执行环境结合起来——模型负责“思考”Harness 负责让 Agent 真正操作本地环境、调用工具并持续执行任务。⚠️重要提示DeepSeek Harness 目前处于开发者预览阶段正在快速迭代未来将出现破坏兼容性的变更。不建议直接用于生产环境的关键流程。二、环境要求项目要求操作系统Windows 10、macOS 10.15、主流 Linuxx64/arm64Node.jsv22.19 及以上或 v24 系列包管理器源码安装需要 pnpmnpm install -g pnpmAPI KeyDeepSeek 或其他兼容提供方的密钥Python可选Python 3.10使用 Python SDK 时硬件要求不高普通笔记本即可运行 Web 界面。三、快速开始方式一通过 npx 一键启动最快捷确保已安装 Node.js然后在终端中执行npx deepseek-ai/dsh web该命令会自动下载并启动 Web UI默认地址为http://127.0.0.1:3080。用浏览器打开即可开始使用。方式二全局安装如需固定版本或离线使用npminstall-gdeepseek-ai/dsh dsh web方式三从源码运行适合开发者/需要最新功能gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web方式四使用桌面应用Windows从 GitHub Releases 下载dsh.exe约 110 MB内嵌完整运行时双击运行即可。方式五一键部署工具DSH Launcher下载DSH Launcher-Setup-0.2.2.exe跟着「一键部署」向导走自动完成 Node.js DSH 安装。四、首次使用配置启动 Web UI 后按以下步骤操作1. 配置 API Key打开Settings → Models在 DeepSeek 卡片中填入 API Key格式sk-...点击保存。Key 存储在$DSH_HOME/.credentials.yaml中界面不会再显示明文。2. 选择工作区点击「选择工作区」添加你希望 Agent 操作的项目目录。建议单独准备一个练习目录作为工作区避免误操作重要文件。3. 发送第一个任务在对话框中输入任务例如“Summarize this repository and identify its main packages.”Agent 会读取工作区文件、运行命令、维护执行计划。涉及写操作时Web UI 会根据权限策略提示审批。4. 配置自定义模型可选Harness 支持接入任意 OpenAI 兼容端点方式一推荐打开 Settings → Models → 添加自定义提供方填写 Provider ID、API 地址和模型 ID方式二直接编辑$DSH_HOME/settings.yamlllm-pi-ai:providers:my-gateway:apiKeyEnv:GATEWAY_API_KEYapi:openai-completionsbaseURL:https://api.example.com/v1models:-id:model-name-here五、四种运行模式Harness 预置了四种运行模式面向不同使用场景模式适用场景特点标准模式日常复杂任务工具较全包含文件操作、Shell、搜索、子任务委派等PTC 模式需要流程可控的场景模型生成代码来编排多轮工具调用极简模式最小化基准测试仅保留 Shell 和文件编辑创造模式插件开发者、定制化智能体可检查当前运行时并在内存中试验插件组合六、Python SDK 使用如需在 Python 程序中程序化调用 Harness可以使用官方 Python SDK。安装gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harness python-mvenv .venvsource.venv/bin/activate# Windows 用 .venv\Scripts\activatepipinstalldeepseek-harness-sdk设置凭据exportDEEPSEEK_API_KEYsk-your-key-here# 如使用非默认端点exportDEEPSEEK_BASE_URLhttp://127.0.0.1:8000/v1# 可选指定模型exportDSH_MODELdeepseek-v4-flash基本用法frompathlibimportPathfromdeepseek_harnessimportDeepSeekHarness configPath(examples/jsonrpc-agent/minimal.cordis.yml).resolve()workspacePath(/absolute/path/to/workspace).resolve()sessionsPath(/absolute/path/to/sessions).resolve()withDeepSeekHarness(providerdeepseek-official,modeldeepseek-v4-flash,max_tokens49152,cwdstr(workspace),session_rootstr(sessions),cordisstr(config),)asharness:resultharness.run(Inspect the repository and fix the failing tests.,session_idexample-001,)print(result.final_response)注意复用同一个 harness 与 session id 会保留该会话拥有的 Bash 进程包括工作目录、已导出的变量与 shell 函数。独立任务应使用新的 session id。七、插件开发Harness 的“一切皆插件”架构允许开发者自由扩展功能。开发环境准备Node.js ^22.19 或 24熟悉 Cordis 插件机制插件开发基本步骤确定插件的唯一职责声明依赖的 service贡献配置行开始编码实现学习资源官方开发指南docs/development.md架构文档docs/architecture.md社区插件模板为你的插件仓库添加dsh-plugin话题以便被发现八、常见问题Q1首次运行npx deepseek-ai/dsh web很慢首次运行会从 npm 下载依赖包请耐心等待。后续启动会快很多。Q2Web UI 无法打开确认终端输出的地址默认http://127.0.0.1:3080检查端口是否被占用。关闭终端后服务会停止。Q3如何切换模型在 Web UI 的对话框中选择模型即可无需重启 dsh。也可以在 Settings → Models 中添加更多模型。Q4Agent 执行写操作时卡住了Web UI 默认会对写操作请求审批请在界面中确认。也可在设置中调整权限策略。Q5工作区是什么为什么需要工作区是 Agent 可以操作的目录范围是一种安全隔离机制防止 Agent 误操作系统重要文件。九、社区与支持GitHub 仓库https://github.com/deepseek-ai/deepseek-harness反馈与讨论GitHub DiscussionsDiscord 社区https://discord.gg/Ycq5dCaS4企微群扫码添加企微小助手并填写入群问卷插件发现为插件仓库添加dsh-plugin话题十、扩展学习资源社区手册dsh-handbook —— 从 0 到 1 的深度手册包含安装、插件开发、性能调优、实测案例等在线阅读https://electricitysheep.github.io/dsh-handbook/插件开发教程hello-dsh —— 零基础插件开发教程含 22 个中文技能实例