---

📝 本文首发于 栏轩·阁

欢迎访问阅读原文，获取更好的阅读体验。

---

引言：不只是又一个 Agent 框架

如果你已经玩过各类 AI Agent 工具，一定体会过那种"功能很强，但想改点什么却无从下手"的感觉。DeepSeek Harness（简称 dsh）想要解决的，正是这个问题。

它由 DeepSeek AI 开发并开源，是一个 agent harness（智能体框架）。与"开箱即用"的传统 Agent 产品不同，它的核心理念只有一句话：

一切皆插件（Everything is a Plugin）。

整个框架由 Cordis 驱动——一个轻量、模块化的插件容器。这意味着：你看到的界面、模型接入、工具调用、甚至是官方 UI 本身，统统都是插件。想要什么功能，装一个插件；想改什么行为，换一个插件；想造一个新能力，写一个插件。

对开发者而言，这是一块高度可定制、可插拔、可学习的试验田。

⚠️ 用前提示：DeepSeek Harness 目前处于开发者预览阶段，正在快速迭代。未来将出现破坏兼容性的变更（breaking changes），请关注版本更新。

📌 项目地址：deepseek-ai/deepseek-harness: DeepSeek Harness: Everything is a Plugin.

---

安装与启动

环境要求

在开始之前，请确保本机满足以下工具版本：

工具	版本要求
Node.js	v22.19.0（或更高）
npm	>= 9

方式一：通过 npm 快速体验（推荐）

如果你只是想先跑起来看看，一条命令即可：

npx @deepseek-ai/dsh web

npx 会临时拉取并执行 dsh，无需全局安装。

方式二：通过源码运行（适合深入学习）

如果你想阅读源码、参与开发，推荐克隆仓库：

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

源码方式依赖 pnpm，这也是后续插件开发的基础环境，建议提前装好。

启动端口

启动后，dsh 默认监听 3080 端口，自动打开 Web 界面：

如果 3080 被占用，或者你希望换个端口，可以用 --port 参数：

npx @deepseek-ai/dsh web --port 8080

当然，也可以全局安装后直接使用 dsh 命令，体验更顺滑：

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

进入网页

浏览器访问对应端口（如 http://localhost:8080），即可看到 dsh 的主界面：

到这一步，它已经和普通的 Agent 软件一样可以直接使用了：新建对话、提问、让 AI 帮你干活，都能正常工作。

选一个工作区

启动后，第一步是点击选择工作区，把 dsh 启动时所在的目录添加进来并选中。选中工作区之前，会话输入框是不可用的——这也是 dsh 的安全设计：让 Agent 明确知道自己能碰哪些文件。

权限与安全模型

dsh 在权限上做了分层设计，新会话默认使用 workspace-write 权限预设：

• 读写受限：Bash 和文件系统修改仅限会话工作区与平台临时目录
• 读取放开：文件读取、网络访问、进程可见性不受限制
• 需要审批的操作：当某个操作超出当前权限策略时，Web UI 会先询问你，而不是直接执行

如果你有特殊需求，可以通过环境变量 DSH_PERMISSION_MODE 调整进程级的权限预设。这套模型让"让 AI 干活"和"不担心 AI 乱动"得以兼得。

---

四种内置模式

dsh 针对不同使用场景，内置了四种 Agent 模式。理解它们的差异，能帮你选对"起跑姿势"：

模式	定位	特点
standard（标准模式）	日常通用	当前默认使用的模式，覆盖日常对话与通用任务
code（编码模式）	编程开发	内置功能完整的编码 Agent，支持文件编辑；具备标准模式的全部能力，并通过 Code Shell、文件与网页检索、Skills、计划、目标、子代理和工作流完成复杂开发任务
minimal（极简模式）	轻量环境	仅提供持久 bash 与 str_replace_editor 两种工具的极简编码 Agent，适合资源受限或需要纯净环境的场景
cordis（创造模式）	自定义开发	用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验与 preset 创作指导，是插件开发者的主战场

💡 此外，dsh 还提供 ModeSDK：它把各类能力呈现为工具，让模型可以用一个 TypeScript 程序组合多步操作——如果你有"让 Agent 按脚本流程执行"的需求，ModeSDK 正是为此设计的。

---

常用操作

上手之后，这几个高频操作值得第一时间掌握：

导出对话

每个对话右上角都有 Session log 按钮，可以将当前工作目录的完整交互过程及对话内容导出。这对复盘调试、沉淀案例、撰写文档都非常有用。

对话归档

归档（Archive）不会删除数据，只是给对话打上标记。归档后的数据统一存储在 用户名\.dsh\ 目录下，随时可以找回。

在新对话中分支

就像 Git 分支一样，你可以基于某个对话在新对话中继续分支——非常适合"同一个问题，尝试多种解决思路"的场景。

自定义 AI 模型提供商

在设置 → 模型中，除了 DeepSeek 官方模型，还可以配置其他模型提供商：

• 目录提供方：选择 Anthropic、OpenAI 等已内置目录的提供方，填入 API 密钥即可
• 自定义提供方：公司网关或自建服务器，填写 Provider ID、基础 URL、API 协议、凭据和至少一个模型
• 模型发现：支持"获取可用模型"自动查询端点；不提供该端点时手动录入即可

几个细节值得注意：

• 密钥是只写的，保存后页面只显示脱敏描述符，明文存在 $DSH_HOME/.credentials.yaml
• 模型配置即时生效，不需要重启服务器
• 视觉模型需要声明图片模态（input: [text, image]），否则发送图片会在请求前被拒绝
• 选择过的模型会成为新会话的默认值

这让 dsh 可以对接你已有的模型 API，灵活组合使用。

---

插件：dsh 的灵魂

插件是什么

在 dsh 的世界里，一切皆是插件。安装一个插件，本质上就是往 $DSH_HOME/profiles/web/node_modules 里 pnpm add 一个包——就这么朴素。

插件管理命令

# 安装插件（本质是 pnpm add，装到 $DSH_HOME/profiles/web/node_modules）
dsh plugin --profile web add <包名>

# 卸载插件
dsh plugin --profile web remove <包名>

# 更新插件
dsh plugin --profile web update

# 查看已安装的依赖
dsh plugin --profile web list

注意：插件管理依赖 pnpm 环境，请提前安装。

通过插件可以做什么

• 定制 Web UI：包括官方 UI 在内，界面的每一部分都是通过插件注入的——想改界面，改插件即可
• 实现类似其他 Agent 软件的 Skill 效果：让模型在对话时自动调用你定义的工具，扩展 Agent 的能力边界

开发小技巧：把官方插件当教科书

遇到奇怪的报错或不清楚某功能如何实现时，直接去读官方插件的源码。

dsh 的理念是"一切皆插件"，这意味着绝大多数官方功能本身就是插件实现的——它们就摆在仓库里，是现成的、高质量的学习资料。与其瞎猜，不如让 AI 帮你分析官方插件的实现方式，往往能快速定位问题、找到标准做法。

📌 插件的开发细节（如何写一个插件、发布与安装流程等）会单独写一篇介绍，这里不展开。

---

Headless 模式：没有界面的 Agent

除了 Web UI，dsh 还提供了 headless（无头）模式——不需要浏览器，一条命令跑完一个任务：

dsh --profile headless "run the tests"

它适合：

• 脚本化调用：在 CI/CD 或定时任务里跑 Agent
• 批量任务：把任务文本作为参数传入，结果输出到 stdout
• 轻量验证：不想开浏览器时的快速尝试

更进一步的玩法是 Python SDK：官方提供了 deepseek-harness-sdk，可以在自己的 Python 程序里调用同一套 API，程序化地创建会话、运行任务、读取结果。这对想要把 dsh 集成进自己系统的开发者非常友好。

---

配置与调试

dsh 的配置体系是"分层的 patch 叠加"，不过日常使用只需记住几个有用的命令：

# 查看完整配置树（含 profile 层和自定义 overlay）
dsh --profile web --dump-config

# 只看内置默认配置
dsh --profile web --dump-default-config

# 用自定义配置文件叠加启动
dsh web --patch ./extra.cordis.yml

几个实用细节：

• AGENTS.md 支持：dsh 会加载工作区里的 AGENTS.md 或 CLAUDE.md 指令文件，让 Agent 自动了解项目的约定——这在多 Agent 协作时尤其有用
• 环境变量：DSH_PERMISSION_MODE（权限预设）、DSH_TOOLS_MODE（工具模式）、DSH_MODEL（默认模型）等都可以在启动时调整
• 优雅关闭：收到 Ctrl+C（SIGINT）会先优雅排空再退出，不用担心任务跑到一半数据丢失

---

dsh 常用命令速查

命令	作用
dsh web	启动 Web 模式（--port 指定端口）
dsh --profile headless "任务"	无头模式跑任务（适合脚本/CI）
dsh --profile web --dump-config	查看完整配置树
dsh web --patch ./extra.yml	用自定义配置层叠加启动
dsh plugin --profile web add <包名>	安装插件
dsh plugin --profile web remove <包名>	卸载插件
dsh plugin --profile web update	更新插件
dsh plugin --profile web list	查看已安装插件

---

社区与支持

• GitHub Discussions：提交反馈、报告 bug 的首选渠道
• dsh-plugin 话题：在 GitHub 上给你的插件仓库打上 dsh-plugin 话题标签，便于被社区发现
• 官方社群：DeepSeek Harness 官方提供企微群与微信公众号，扫码添加小助手并填写问卷即可入群，第一时间获取版本动态与社区交流

---

结语

DeepSeek Harness 的独特之处，不在于它"又多了一个 Agent 工具"，而在于它把可定制性做到了极致：一切皆插件，意味着框架的每一层都向你开放。

对于想深入 Agent 开发的你来说，它既是开箱即用的工具，也是绝佳的源码教材——装上插件、跑通流程、再打开官方插件源码读一读，一条从"使用者"到"开发者"的路径就自然展开了。

如果你也在折腾 dsh，欢迎交流你的插件想法或踩坑经验。🚀