dshbase
EN

教程

DeepSeek Harness 教程

从首次启动到跑第一个 Agent 任务——以及最容易踩坑的报错，还有脚本化的 Python SDK。基于官方指南。

快速开始（所有平台通用）

安装后运行：

npx @deepseek-ai/dsh web
  1. 打开 http://127.0.0.1:3080。
  2. 在 设置 → 模型 填入 DeepSeek API Key 并保存。
  3. 点击选择工作区，添加一个项目目录并选中。
  4. 发送任务——例如 Summarize this repository and identify its main packages.

各平台首次使用

启动方式各平台都一样（安装步骤不同——见安装指南）：

  • Windows——在 PowerShell 里运行命令，用任意浏览器打开 URL。
  • macOS——在终端里运行，Web UI 会在默认浏览器打开。
  • Linux——在终端里运行，3080 被占用的话用 --port 8080。
  • WSL——在 WSL 的 Ubuntu 终端里运行，从 Windows 浏览器打开 URL。

dsh 进程把你启动它的目录当作默认文件系统位置——Web UI 在你添加工作区之前不会选中任何目录。

配置模型（提供方）

DeepSeek Harness 模型配置页

模型变更在下一次请求生效，无需重启。密钥存在 $DSH_HOME/.credentials.yaml，只写不可读。

  • DeepSeek——在模型页填入 API Key。
  • 目录提供方（Anthropic、OpenAI 等）——添加提供方并填密钥。Bedrock/Vertex/Azure/Codex 需要各自的原生凭据（AWS/ADC/api-version/OAuth）。
  • 自定义提供方——小写 Provider ID + 基础 URL + 协议 + 凭据 + 至少一个模型。用获取可用模型查询端点。
  • 视觉模型——在 $DSH_HOME/settings.yaml 给模型加 input: [text, image]。

三种具体接入方案（官方 DeepSeek / OpenCode Go / 免费 Agnes）含 base URL 和邀请链接：见模型接入指南。

安装与管理插件

插件就是 npm 包。用 dsh plugin 命令往 profile 里加——参数会转发给 pnpm（先 npm install -g pnpm）：

dsh plugin --profile web add dsh-claude-marketplace
dsh plugin --profile web list              # 确认装了什么
dsh plugin --profile web remove dsh-claude-marketplace

--profile 必填，指定要改的 profile（默认 profile 是 web）。DSH 会把插件写进该 profile 的 package.json（既是依赖也进 dsh.profile.bundles），下次启动自动加载。npm 上实测可用的：dsh-claude-marketplace（加载你的 .claude skills 与 commands）、dsh-plugin-session-import（导入 Claude Code/Codex 历史会话）、dsh-fail-logger（记录失败的工具调用）、dsh-latex-tools（Web UI 悬停 LaTeX）、dsh-cloudflare-browser-run（浏览器工具）。更多用 npm search dsh-plugin 搜。

常见报错与解决

  • MISSING_CREDENTIAL——在模型页存密钥，或设置引用的环境变量。
  • UNKNOWN_MODEL——选择已配置的模型，或给自定义提供方添加缺失模型。
  • 获取可用模型返回 401——检查密钥；模型发现会调用 OpenAI 兼容的 GET /models 端点。
  • 图片在发送前被拒绝——模型未声明图片模态；加 input: [text, image]。
  • 模型不对 / 连接失败——基础 URL、API Key、模型名三者必须匹配你的提供方。一个用 curl 能通的 Key，在 UI 里若基础 URL 或模型名不对仍会失败。
  • 'pnpm' 不是内部或外部命令——dsh plugin 会转发给 pnpm；先 npm install -g pnpm。
  • 加插件时报 ERR_PNPM_FETCH_404——包没发布（用 npm view <包名> 查），或镜像落后——加 --registry=https://registry.npmjs.org 重试。
  • node: command not found——dsh 启动器需要 Node.js 在 PATH 里；把 Node 目录加进 PATH。

进阶：无头模式

跑单个任务后退出，适合脚本和 CI：

dsh --profile headless "Inspect the repository and fix the failing tests."

进阶：Python SDK

Python SDK 把同一套 agent API 暴露给你的程序。要求：Python 3.10+、Git，以及 Linux x64/arm64 或 macOS 14+（arm64）——注意目前不支持 Windows。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk
export DEEPSEEK_API_KEY=sk-your-key-here
python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  "Inspect the repository and fix the failing tests."

极简示例只给模型两个工具（bash + 文件编辑器）——Bash 超时 300 秒，编辑限制 16,000 字符。

开发插件 → 浏览插件目录 →