47thtechcorner/RayCodes_DeepSeek_Harness

📺 在 YouTube 上观看完整教程

🤖 DeepSeek Harness (dsh) — 快速上手与提供商指南

DeepSeek Harness (dsh) 是一个开源、以可组合性为核心的 AI 智能体框架，由 Cordis 微内核 驱动。每一项智能体能力——模型、沙箱化 shell 工具、文件编辑、子智能体以及 Web UI——都是一个挂载的插件。

📸 可视化概览

* 🎨 可视化编辑演示： assets/deepseek_harness_overview.html
* 📄 概览 Markdown 报告： assets/deepseek_harness_overview.md

⚡ 快速开始

🪟 面向 Windows 用户（PowerShell）

第 1 步：检查或安装 Node.js（需要 Node.js >= 22）

打开 PowerShell 并检查你的 Node.js 版本：

node -v

* 如果返回 v22.x.x 或更高版本（例如 v24.x.x），那就准备好了！跳到第 2 步。
* 如果 Node.js 未安装或版本过旧，请在 PowerShell 中运行以下命令安装最新的 LTS 版本：

winget install OpenJS.NodeJS.LTS

（安装完成后重启你的 PowerShell 窗口）。

第 2 步：启动 DeepSeek Harness Web UI

在 PowerShell 中粘贴并运行以下命令：

npx @deepseek-ai/dsh web

运行后，在浏览器中打开 http://127.0.0.1:3080。

🐧 🍎 面向 Linux / macOS 用户（终端 / Bash）

第 1 步：通过 nvm 安装 Node.js v22

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

第 2 步：启动 Web UI

npx @deepseek-ai/dsh web

🛠️ 备选方案：从源码运行

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

🛠️ 提供商设置说明

DeepSeek Harness 支持多个 LLM 提供商：DeepSeek 原生 API、OpenRouter 和 本地 Ollama。

┌─────────────────────────────────┐
│       DeepSeek Harness Web UI   │
└────────────────┬────────────────┘
│
┌───────────────────────┼───────────────────────┐
▼                       ▼                       ▼
┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
│   DeepSeek API     │  │     OpenRouter     │  │    Ollama Local    │
│ Native Provider    │  │  Catalog Provider  │  │  Custom Provider   │
│ api.deepseek.com   │  │   openrouter.ai    │  │  localhost:11434   │
└────────────────────┘  └────────────────────┘  └────────────────────┘

方法 1：DeepSeek 原生 API（官方）

1. 在 http://127.0.0.1:3080 打开 Web UI。
2. 进入 设置 ➔ 模型。
3. 找到 DeepSeek 卡片。
4. 输入你从 platform.deepseek.com 获取的 API Key。
5. 点击 应用 / 保存。（存储在 $DSH_HOME/.credentials.yaml 中）。

方法 2：OpenRouter（多模型云网关）

OpenRouter 通过单个 API Key 即可访问数十个顶级模型，包括免费层模型。

1. 进入 设置 ➔ 模型。
2. 滚动到 添加提供商，并从目录列表中选择 openrouter。
3. 粘贴你的 OpenRouter API Key（可从 openrouter.ai/keys 获取）。
4. 选择你偏好的默认模型：
* liquid/lfm-2.5-2.6b:free （免费推理模型）
* nvidia/nemotron-3-5-lightning:free （免费快速推理）
* deepseek/deepseek-r1:free （免费推理模型）
* anthropic/claude-3.5-sonnet （付费，顶级基准模型）
5. 点击 应用。
6. 切换到 聊天 标签页，点击顶部的模型下拉菜单，然后选择你的 OpenRouter 模型。

方法 3：本地 Ollama（100% 离线且免费）

Ollama 允许在你的 GPU/CPU 上本地运行开放权重模型（如 DeepSeek-R1、Qwen2.5-Coder、Liquid AI），且零 API 成本。

步骤 3.1：启动 Ollama 并拉取模型

确保 Ollama 已安装并在你的机器上运行：
bash
启动 Ollama 服务（如果未运行）
ollama serve

拉取你偏好的编码或推理模型
ollama pull qwen2.5-coder:7b
或者
ollama pull lfm2.5-vl-3b

步骤 3.2：在 DSH Web UI 中配置自定义提供商

1. 在 DeepSeek Harness 中打开 设置 ➔ 模型。
2. 滚动到页面底部，点击 添加自定义提供商。
3. 填写自定义提供商表单中显示的准确字段：
* 提供商 ID： ollama （必须是小写标识符）
* 显示名称： Ollama Local （或 ollama）
* 基础 URL： http://localhost:11434/v1
* API 协议： 从下拉菜单中选择 openai-completions
* API Key： 输入任意虚拟 API Key（例如 ollama）
4. 在 模型 下添加你已安装的本地模型：
* 自动获取： 点击模型卡片右上角的 获取可用模型，以查询 Ollama 的 http://localhost:11434/v1 端点并导入你已安装的模型。
* 手动输入： 点击卡片底部的 添加模型，然后输入你的模型 ID（例如 qwen2.5-coder:7b）。
5. 点击 保存提供商。
6. 返回 聊天 标签页，在模型选择器的 ollama 提供商标题下选择你的模型。

步骤 3.3：（可选）为 Ollama 配置视觉模型

如果使用本地视觉模型（例如 llama3.2-vision:11b），请配置 $DSH_HOME/settings.yaml：
yaml
llm-pi-ai:
providers:
ollama:
api: openai-completions
baseURL: http://localhost:11434/v1
defaultInput: [text, image]
models:
- id: llama3.2-vision:11b
input: [text, image]

🚀 可直接测试的提示词

配置完成后，使用以下单文件 Python（.py）和单文件 HTML（.html）开发者提示词来测试 DeepSeek Harness：

🧪 测试提示词 1 — Python API 抓取器与数据报告（app.py）
Create a single-file Python script app.py using urllib.request and json to fetch public data from a JSON API, parse top items, and save the result into a clean formatted markdown report data_summary.md. Run the script to verify output.

🧪 测试提示词 2 — 单文件交互式 HTML 仪表盘（dashboard.html）
Create a standalone, single-file HTML dashboard dashboard.html with inline CSS and inline JavaScript. Include a responsive dark-mode layout with visual KPI metric cards, a formatted data table, and smooth hover micro-animations.

🧪 测试提示词 3 — Python 工作区代码分析器（analyzer.py）
Create a single-file Python script analyzer.py that scans the current project directory, calculates total lines of code and file size metrics grouped by file extension, and prints a formatted summary table in the terminal.

🧪 测试提示词 4 — Python Web 实用服务器（server.py）
Write a single-file Python script server.py using Python's built-in http.server module that provides a lightweight JSON HTTP server with endpoints for health checks and text string processing. Run the server and test it using a python command.

🔍 轨迹视图与调试

DeepSeek Harness 包含一个仅追加的轨迹视图：
* 点击 Chat 旁边的 Trajectory 标签页，即可实时查看 AI 的内部思维链、工具调用（str_replace_editor、bash 调用）以及子代理执行过程。
* 你可以在任意步骤回退、分叉或重放任何会话状态。

❓ 故障排除

| 错误代码 / 症状 | 原因 | 解决方案 |
| :--- | :--- | :--- |
| MISSING_CREDENTIAL | 目标提供商缺少 API 密钥。 | 在 Settings ➔ Models 中输入密钥，或导出环境变量。 |
| UNKNOWN_MODEL | 无法识别的模型字符串。 | 将模型 ID 添加到自定义提供商设置中，或获取目录。 |
| 401 Unauthorized | 密钥无效或目标端点无法访问。 | 检查 API 密钥，或验证 Ollama 是否在 http://localhost:11434 上处于活动状态。 |
| Image refused before sending | 模型模态输入未标记为支持视觉。 | 将 input: [text, image] 添加到 $DSH_HOME/settings.yaml。 |

📜 许可证与社区

* 许可证： 基于 MIT 许可证的开源项目。
* GitHub 仓库： deepseek-ai/deepseek-harness
* Discord 社区： DeepSeek Harness Discord

🏷️ 关键词与 SEO 标签

DeepSeek Harness DeepSeek AI Local Ollama Setup OpenRouter Free Models Cordis Micro-Kernel AI Agent Harness AI Coding Assistant Qwen2.5-Coder DeepSeek R1 100% Free AI Pair Programmer