dshbase

教程

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]。

常见报错与解决

  • MISSING_CREDENTIAL——在模型页存密钥，或设置引用的环境变量。
  • UNKNOWN_MODEL——选择已配置的模型，或给自定义提供方添加缺失模型。
  • 获取可用模型返回 401——检查密钥；模型发现会调用 OpenAI 兼容的 GET /models 端点。
  • 图片在发送前被拒绝——模型未声明图片模态；加 input: [text, image]。
  • 模型不对 / 连接失败——基础 URL、API Key、模型名三者必须匹配你的提供方。一个用 curl 能通的 Key，在 UI 里若基础 URL 或模型名不对仍会失败。

进阶：无头模式

跑单个任务后退出，适合脚本和 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 字符。

下一步：开发插件 →

🌐 English