DeepSeek Harness完全入门指南

引言

DeepSeek Harness是一个强大的AI Agent框架，它支持一种独特的"即写即跑、无需重启"的工作流来创建、运行和管理插件。本指南将带你完成安装、配置和创建第一个插件。

前置要求

开始之前，请确保你的系统已安装Node.js 22+。用以下命令验证安装：

node -v

安装

有两种安装方式：

1. 快速试用（临时使用）

单次测试用npx命令：

npx @deepseek-ai/dsh web

这会临时启动Harness，并在浏览器中打开http://127.0.0.1:3030。

2. 永久安装（推荐）

长期使用请全局安装：

npm install -g @deepseek-ai/dsh

安装后，用以下命令启动Harness：

dsh web

高级安装选项

无头模式（用于服务器）

要在没有图形界面的服务器上运行Harness，请使用无头模式：

# 先设置你的API Key
export DEEPSEEK_API_KEY=your_api_key

# 以无头模式运行任务
dsh --profile headless "你的任务描述"

源码构建（适用于开发者）

如果你想修改源代码：

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 运行Web界面
pnpm run web

# 或以无头模式运行
pnpm dsh --profile headless "你的任务"

配置

设置你的API Key

1. 打开Harness设置面板
2. 进入"Model"（模型）部分
3. 输入你的DeepSeek API Key
4. 保存配置

你的API Key会存储在权限为0600的安全凭据文件中，确保其他用户无法访问。

添加模型供应商

Harness支持多种模型供应商，不只是DeepSeek。要添加新供应商：

1. 进入设置 > Model Providers（模型供应商）
2. 点击"Add Provider"（添加供应商）
3. 输入供应商信息和API Key
4. 保存配置

工作模式

Harness提供四种工作模式：

1. 标准模式

• 全功能Agent
• 支持文件、终端、浏览器和技能
• 90%的工作都在此模式完成

2. 极简模式

• 只有两个工具：终端和文件编辑器
• 提示词最短
• 用于基准测试和测试

3. PTC模式

• 针对token效率优化
• 把多个操作合并到单个脚本中
• 适合关注成本的进阶用户

4. 创意模式

• 为插件开发添加额外工具
• 允许读取和修改运行时状态
• 用于即时编写和测试插件

权限级别

Harness提供三个权限级别来控制文件访问：

1. 只读（Read Only）：最安全选项，不允许任何文件修改
2. 工作区写入（Workspace Write）（默认）：只修改你指定工作区目录中的文件
3. 完全访问（Full Access）：完整系统访问权限（请谨慎使用）

插件管理

查找插件

在GitHub上搜索"dsh plugin"标签，浏览数千个社区插件。

安装插件

用命令行安装插件：

dsh plugin --profile demo add ./path/to/plugin

或者通过聊天界面让Harness帮你安装插件。

重要提示

• v0.1生态还很年轻，部分插件可能未经测试
• 安装前务必查看插件文档
• 卸载插件是干净且可逆的

创建你的第一个插件

Harness独特的"即写即跑"工作流让你能实时创建和测试插件：

1. 切换到创意模式
2. 用自然语言描述你的插件想法
3. Harness会生成插件代码
4. 无需重启即可立即测试插件
5. 按需优化和迭代

对于要长期使用的插件，请遵循官方开发流程来打包和分发。

结语

DeepSeek Harness为AI Agent开发提供了一个独特而强大的平台。凭借其直观的界面、灵活的插件系统和创新的"即写即跑"工作流，无论新手还是经验丰富的开发者，它都是绝佳选择。先从标准模式熟悉界面，再逐步探索高级特性和插件开发能力。

常见问题

DeepSeek Harness免费吗？

是的，DeepSeek Harness本身免费且开源（MIT协议），你可以用本文中的npx或npm install命令在本地运行。需要付费的是模型使用——你需要一个DeepSeek API Key来驱动Agent，这些API费用由DeepSeek收取。框架本身不收取任何费用。

快速试用和永久安装有什么区别？

快速试用（npx @deepseek-ai/dsh web）从npm缓存临时运行Harness，适合在决定长期使用前先测试它是否适合你的工作流。它会在http://127.0.0.1:3030启动一个本地Web界面。永久安装（npm install -g @deepseek-ai/dsh）会把dsh命令全局加入PATH，之后随时用dsh web启动。日常使用请永久安装。

我应该先使用哪种工作模式？

先用标准模式——它是支持文件、终端、浏览器和技能的全功能Agent，能处理约90%的真实工作。做基准测试或测试时切换到极简模式。如果你在意成本，用针对token效率优化的PTC模式。只有在想即时编写和测试插件时，才切换到创意模式。

权限级别安全吗？

安全，这正是它的设计目的。只读（Read Only）最安全——完全不允许修改文件。工作区写入（默认）把更改限制在你指定的工作区目录内，Agent无法触碰项目之外的东西。完全访问（Full Access）给予完整系统权限，必须谨慎使用——只有当你完全信任任务和Agent时才启用它。