DeepSeek Harness（DSH）

DeepSeek 官方开源的 Agent Harness：除模型本身以外的所有工作（读文件、改代码、执行命令、组织上下文、调用工具、保存会话、权限审批、子 Agent）都属于 Harness 的范畴。
核心公式：Model + Harness = Agent
核心设计：一切皆插件（Everything is a Plugin），由 Cordis 驱动。

基本信息

  • 官方仓库：https://github.com/deepseek-ai/deepseek-harness （MIT 协议，2026-08-13 开源，公测中）
  • npm 包：@deepseek-ai/dsh
  • 当前状态：Developer Preview（开发者预览版），官方声明迭代快、会有破坏性兼容变更
  • 环境要求：Node.js（LTS 即可）
  • 默认 Web UI 地址：http://127.0.0.1:3080

安装与启动

方式一：npx 直接启动（官方推荐，最简单）

npx @deepseek-ai/dsh web
  • 第一次运行自动下载包到 npx 缓存（~/.npm/_npx），之后每次运行从缓存秒起，不会重复下载
  • 每次启动都跑这条命令即可，配置不会丢（配置存在 ~/.dsh，与 npx 缓存无关）
  • 建议先 cd 到项目目录再启动：运行目录 = 默认 workspace 根目录

方式二：全局安装（装一次，之后直接 dsh web）

npm install -g @deepseek-ai/dsh
dsh web

方式三：本地安装

npm i @deepseek-ai/dsh
npx dsh web    # 需在安装目录下运行

方式四：源码运行（开发/改插件用）

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

版本与更新（2026-08-20 调研）

  • 最新版本：v0.1.0-rc.8（GitHub 最新 release，Pre-release）
    • npm 上已发布 0.1.0-rc.8（jsdelivr 可直接拉取 @0.1.0-rc.8/package.json）
    • 但 npm 的 latest dist-tag 仍指向 0.1.0-rc.7（jsdelivr / unpkg 的 @latest 均解析为 rc.7）
    • 含义：普通 npx @deepseek-ai/dsh / npm install -g @deepseek-ai/dsh 装到的仍是 rc.7，想用 rc.8 必须显式指定版本
  • 查看当前版本
    • 全局安装：dsh --version 或 npm ls -g @deepseek-ai/dsh
    • npx 方式：npx @deepseek-ai/dsh --version（注意 npx 会读缓存）
  • 更新到 rc.8
    • npx：npx --yes @deepseek-ai/dsh@0.1.0-rc.8 web
    • 全局：npm install -g @deepseek-ai/dsh@0.1.0-rc.8
    • 源码：git pull + pnpm install + pnpm run build
    • 想跟 latest 标签则 npm install -g @deepseek-ai/dsh（当前仍为 rc.7）
  • ⚠️ 升级前注意：rc.8 改善了 SQLite 后端读写/分叉性能并降低存储体积，但存储格式不兼容，建议先备份 ~/.dsh
  • rc.8 主要变化：多模态增强（DeepSeek 适配器支持原生图片请求，/goal /plan 可图文输入，@ 菜单可引用文件/会话）；Claude Code 与 Codex 子代理可作 Profile Bundle 按需安装；Windows PTY 支持持久 PowerShell 会话；web_search 支持并发查询；本地 dsh web 自动打开浏览器；缩小下载依赖体积；提升大历史会话分叉性能
  • 无内置自更新命令：官方 README 只提供 npm / npx / 源码三种方式，更新 = 重新安装对应版本

首次使用三步

  1. 浏览器打开 http://127.0.0.1:3080，在 Settings 模型设置里填入 DeepSeek API Key 并保存（模型路由立即生效，不用重启服务器）
  2. 选择工作区（指向启动 dsh 时的项目目录）
  3. 开启对话，例如”汇总这个仓库并指出主要包”

常用命令速查

命令 作用
npx @deepseek-ai/dsh web 启动 Web UI（dsh web 是 --profile web 的硬编码别名）
npx @deepseek-ai/dsh web --port 8080 换端口启动（--port 属于 web 应用参数，跟在 dsh web 后面）
dsh --profile headless "任务描述" 一次性运行一个任务，打印最终答案后退出（适合脚本/CI，无服务器无端口）
dsh plugin --profile web add <包名> 给指定 profile 安装插件（转发给 pnpm 执行）
dsh plugin --profile web remove <包名> 移除插件
dsh --profile web --dump-config 查看实际启动的完整配置树（不启动服务器）
dsh --profile web --dump-default-config 查看默认配置树（不含用户 patch）

配置与数据目录

位置 内容
$DSH_HOME（默认 ~/.dsh） 所有配置与数据根目录
~/.dsh/profiles/ profile 目录（web / headless 首次使用时从内置模板自动初始化）
~/.dsh/profiles/web/cordis.patch.yml 用户自己的配置 patch 层（改配置主要动这里）
~/.dsh/.credentials.yaml 凭据（也可用环境变量 DEEPSEEK_API_KEY）
~/.dsh/cordis.patch.yml home 级配置（所有 profile 共享，优先级高于 profile 级）

凭据解析顺序：环境变量 → $DSH_HOME/.credentials.yaml → 调用目录的 .env → $DSH_HOME/.env。

概念速记

  • Profile：一次启动的完整配方，回答”这次启动要叠哪些插件包、按什么顺序叠”。web = 带浏览器界面的完整应用；headless = 无服务器、接收一次任务返回结果。
  • Bundle（组合包）：一个声明了 dsh.bundle.patch 的普通 npm 包，带一份 cordis.patch.yml，是 dsh 的一层配置。安装后出现在 profile 的 bundle 列表中。
  • Cordis：dsh 的底层驱动，一棵启动时组合出来的插件树。模型适配器、工具注册表、会话日志、Agent Loop、UI 全都是可替换的插件。
  • 默认权限：新会话默认 workspace-write 预设；bash/文件系统改动限制在会话工作区和平台临时目录内；高风险操作会在界面征求确认。

踩坑记录

  • 端口被占用 → --port 8080 换端口；防火墙需放行本地端口
  • npx 版本过旧/找不到包 → 清 npx 缓存（npm cache clean --force 或删 ~/.npm/_npx）重试；预览版迭代快
  • 预览版会有破坏性兼容变更，配置可能随版本更新要跟着改
  • CLI 目前不支持 --host 0.0.0.0（会直接报用法错误退出）

学习资源

  • 官方 README（中文）：https://github.com/deepseek-ai/deepseek-harness/blob/master/README.zh.md
  • CLI 中文文档：https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.zh.md
  • Web UI 指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/index.md
  • 插件生态精选列表：https://github.com/0xsline/awesome-deepseek-harness
  • 插件生态雷达（awesome-dsh-plugins）：https://github.com/AdamPlatin123/awesome-dsh-plugins
    • 定位：自动发现 + 证据验证的 DSH 插件雷达。自动扫描 2800+ 候选仓库，由专用 K8s 集群在 DSH 最新版下逐个运行级实测，安装前就知道哪个能用、哪个不兼容，不用自己踩坑
    • 当前规模（快照 20260815T151237Z）：收录 1253 个插件仓库；运行实测 ✅379 可用 / ❌155 不兼容 / ⚠️14 待定（共 548）
    • 状态四档口径：✅ 运行级可用（真实加载并完成验证任务）/ ❌ 运行级不兼容（依赖装不上等硬失败）/ ⚠️ 待定（环境故障未判）/ · 未测。收录≠兼容≠安全审计，装插件前仍要自查源码、权限、许可证
    • 常用入口：PLUGINS.md（分类目录）、PLUGINS-ALL.md（全量清单）、reports/<日期>/（兼容矩阵/编译实验/运行实测）、CHANGELOG.md
    • 🔥 Star Top 20 亮点（每 20 分钟自动刷新）：headroom（6.6w⭐，压缩工具输出/日志/上下文）、dsh-web-ui（皮肤合集）、modlens（首个视觉插件）、DSH-better-sidebar（侧边栏工作台：文件/终端/Git/子代理）、dsh-TUI（Claude Code 风 TUI）、TokenTracker（token 用量&费用追踪）、dsh-vision-toolkit（纯文本模型做视觉任务）、Bigfish（第三方桌面端，双击即用）、whale-girl（桌面宠物）
    • 社区：dshfind.com（DSH 原理学习 + 插件市场）
  • 安装实测参考：知乎《DeepSeek Harness 安装，初体验，没有惊喜》 https://zhuanlan.zhihu.com/p/2071375794388186083

插件收藏（2026-08-16 整理）

🛒 市场与商店

名称 链接 说明
DSH Plugin Store https://www.dshplugin.store/ 网页商店，同步 GitHub dsh-plugin topic，3428 仓库索引，按分类浏览/搜索
dsh-market https://github.com/dsh-market/dsh-market DSH 内置可视化插件市场：设置→插件市场→浏览/搜索/一键安装。安装：dsh plugin --profile web add dshmarket
dshfind.com https://dshfind.com/en DSH 学习分享社区 + 插件市场（LobeHub 构建，每日同步 star/贡献者/增长数据）
dshfind 教程《DSH 是什么》 https://dshfind.com/zh/learn/intro/what-is-dsh 三层含义（SDK/dsh工具/生态）+ 四大核心思想（一切皆插件/运行可重建/能力即接缝/自指修改）精讲

📋 精选列表

名称 链接 说明
0xsline/awesome-deepseek-harness https://github.com/0xsline/awesome-deepseek-harness 515 行精选（512⭐），18 大分类（Core/Agents/Context/UI/IDE/Browser/Models/Git/Skills…），数据源 dsh-external/hub + GitHub topic
awesome-dsh-plugin/awesome-dsh-plugin https://github.com/awesome-dsh-plugin/awesome-dsh-plugin 823 行精选（2.8k⭐），12 分类，全部可 dsh plugin add 安装（均声明 dsh.bundle manifest）
AdamPlatin123/awesome-dsh-plugins https://github.com/AdamPlatin123/awesome-dsh-plugins 插件雷达（见上方「学习资源」详细记录）

⭐ 重点插件（关注/待装）

插件 链接 用途
dsh-reverse-skill（重点） https://github.com/dhicoc/dsh-reverse-skill 完整 reverse-skill 85 个 SKILL.md 封装（逆向工程/授权渗透/安全研究），另记于 AI逆向 文档
dsh_workflow https://github.com/omdsh-dev/dsh_workflow workflow 层插件：一次性多 Agent 调度 → 可生成/保存/治理/观察/恢复（能力速记见下）
dsh-learn-everything https://github.com/cendaifeng/dsh-learn-everything 费曼学习法插件：讲解→复述→判定→回讲闭环，富 HTML 教学卡片（待装，先调研）
dsh-vision-toolkit https://github.com/Anionex/dsh-vision-toolkit 纯文本模型做视觉任务：带意图图片问答/长截图 OCR/UI 还原/grounding/pixel diff/Artifacts
DSH-better-sidebar https://github.com/omdsh-dev/DSH-better-sidebar 服务化侧边栏完整工作台：文件管理/编辑器/内嵌浏览器/真实终端/Git 面板/后台任务，开放 ctx.betterSidebar 给第三方插件

dsh_workflow 能力速记（2026-08-16 调研）

把 Claude Code 的 UltraCode 模式带给 DSH——把一次性多 Agent 调度，升级为可生成、可保存、可治理、可观察、可恢复的 Workflow 层（KodaX workflow 对标，@dsh-external/workflow 官方 bundle 形态、零核心 patch）。

  • 发现与复用：workflow 保存为 .dsh/workflows（项目级）/ $DSH_HOME/workflows（个人级），按名字运行；同名项目条目覆盖个人条目；.workflow.json 优先于 .ts/.mjs/.js
  • 生命周期与持久化：每个 run 有 running → paused/completed/failed/denied/stopped 状态；.dsh/workflow-runs/<run-id>/ 落盘：run.json（状态/摘要/成本）、events.jsonl（append-only 事件图）、workflow.workflow.json（不可变快照）、results/（effect cache）、artifacts/（证据）
  • 续跑/重跑：resume-run 用 effect cache 续跑未完成部分，或按 run snapshot 重跑，中断不从头再来
  • 治理与硬限制：manifest + preflight + 运行时硬限制（modelHint: fast|balanced|deep；availableTools/availableMcp/availableSkills 部署能力清单，requirement 不在清单即失败，不偷偷降级）
  • 斜杠命令：/workflow list、/workflow create <request>、/workflow review、/workflow runs、/workflow show、/workflow pause|resume|stop、/workflow rerun|resume-run、/workflow save|revise|prune 等
  • 模型工具：workflow_list / run_workflow / workflow_manage
  • 安全：readOnly/toolFilter/cacheIdentity/审批分级；approvalMode: always；要求 Node ≥ 22.19、DSH 快照与 compatibility.json 一致
  • 与原生 workflow 工具关系：不替换原生 workflow 工具（它适合”这一次并行跑完”），本插件负责更高层的流程产品能力

待学习 / 待记录

  • 体验四种 Agent Preset 模式（含 minimal 极简模式）
  • 尝试安装一个第三方插件 bundle（如上下文增强插件）
  • 体验 headless 模式接进自动化流程
  • 对比 Claude Code / Codex / OpenCode 的取舍
  • 逛 awesome-dsh-plugins 的 Star Top 20，挑 1-2 个插件（如 headroom / dsh-web-ui / TokenTracker）实测安装
  • 安装 dsh-reverse-skill（重点，逆向技能包）并挑常用技能试用
  • 调研 dsh-learn-everything 费曼学习法插件（用户想装一个）
  • 体验 dsh_workflow 的 /workflow 系列命令
  • 逛 DSH Plugin Store / dshfind.com 挖更多好插件