sandbaseai/deepseek-harness-handbook · 上手攻略

仓库：sandbaseai/deepseek-harness-handbook
链接：https://github.com/sandbaseai/deepseek-harness-handbook
分类：AI 工具 / Agent 运行时 / DeepSeek 生态
作者：Tom
更新：2026-08-21

这是什么

DeepSeek Harness Handbook 是一个独立维护的权威实战手册，面向在生产环境或日常工作中使用 DeepSeek Harness（DSH）的开发者、运维和 AI 爱好者。它不是命令列表，而是一部覆盖完整 Agent 边界的操作指南——从模型路由、工具调用、权限审批、沙盒隔离、持久化 Session、插件体系、MCP（Model Context Protocol）到 ACP，114 篇经过源码核验的指南，全部带原始链接与 commit SHA。

[!IMPORTANT] DeepSeek Harness 本身是 DeepSeek AI 推出的开源 Agent 运行时（类 Claude Code/Codex 定位），而本手册是由 SandBase 维护的独立社区手册，非官方项目。

核心定位： - 114 篇canonical guides，rc.8 源码级覆盖 - 主-source 优先：每篇指南都链接到原始 commit/PR/issue，版本敏感页面标注核验日期 - 三语内容：英文原文，附简体中文、日语、韩语、西班牙语参考

解决什么问题

DeepSeek Harness 是一个复杂的 Agent 运行时，普通用户和开发者常遇到以下问题却找不到可靠答案：

痛点场景	本手册对应方案
`/compact` 手动压缩后报 `DeepSeek request aborted by caller`	Manual compaction cancellation runbook
插件更新遇到 `ERR_PNPM_UNEXPECTED_STORE`	pnpm store-identity recovery
Node 版本看似正确但报 `AbortSignal.any is not a function`	Runtime identity and offline recovery runbook
Web 界面卡在 Loading plugins（pnpm 源码 checkout）	pnpm symlink boot guide
Responses API 重复流量、SSE 泄漏	Responses overload runbook
上下文窗口 / token 预算溢出	Classify and recover context overflow
Session 历史损坏 / 重复提交序列	Duplicate committed seq runbook
API Key 被工具/备份泄露	Credential storage threat model
Windows 文件选择器崩溃 / Unicode 路径截断	Windows folder-picker crash guide
想要自定义 MCP server 或排查 MCP 工具缺失	MCP preset and connection guide

手册把这些场景全部收敛到一套可执行的 runbook，开发者遇到具体错误可以直接检索，不需要在论坛里大海捞针。

快速安装

DeepSeek Harness Handbook 本身是纯文档项目，无需安装。使用前需先安装 DeepSeek Harness 运行时，以下为最小安装路径：

# 方式一：npm 一键安装（rc.8+）
npm install -g @deepseek-ai/deepseek-harness

# 方式二：npx 免安装（测试用，不污染全局）
npx @deepseek-ai/deepseek-harness --version

# 方式三：pnpm 源码构建（rc.8，开发者向）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness && pnpm install && pnpm build

# 安装后验证
dsh --version    # 期望输出 rc.8.x

⚠️ 硬件/CUDA 要求（运行 DeepSeek 模型 provider 时）： - 若连接 DeepSeek API：无需本地 GPU，直接使用 API Key - 若本地部署模型 provider：需 NVIDIA GPU（建议 24GB+ VRAM），CUDA 12.1+，cuDNN 8+ - 手册 rc.8 Field Status 页面：https://sandbaseai.github.io/deepseek-harness-handbook/field-status.html

核心用法

1. 启动 Web 界面（五分钟上手）

# 安装后直接运行，默认 localhost:3000
dsh web

# 指定端口
dsh web --port 8080

# 带 API Key（DeepSeek API 为例）
DEEPSEEK_API_KEY=sk-xxxx dsh web

启动后访问 http://localhost:3000，按引导完成模型 provider 配置。

2. CLI 自动化任务（Headless）

# 单次任务（无交互）
dsh run "用 Python 实现一个快速排序" --model deepseek-chat --no-browser

# 读取当前目录代码并分析
dsh run --task analyze --path . --model deepseek-coder

# 通过 STDIN 传入任务
echo "解释这段代码的逻辑" | dsh run --model deepseek-chat

3. 配置模型 Provider（Provider 路由）

# 添加 DeepSeek 官方 API
dsh config add-provider --name deepseek \
  --api-base https://api.deepseek.com \
  --api-key $DEEPSEEK_API_KEY \
  --models deepseek-chat,deepseek-coder

# 添加 OpenAI 兼容 Provider（如硅基流动等）
dsh config add-provider --name siliconflow \
  --api-base https://api.siliconflow.cn/v1 \
  --api-key $SILICONFLOW_API_KEY \
  --models gpt-4o,claude-3-5-sonnet

# 查看当前 Provider 列表
dsh config list-providers

4. 安装社区插件（Plugin Store）

# 搜索插件
dsh plugin search code-interpreter

# 安装插件（以官方 plugin store 为例）
dsh plugin install @deepseek-ai/plugin-code-interpreter

# 手动加载本地插件（开发场景）
dsh plugin add --path ./my-plugin --name my-plugin

# 查看已加载插件
dsh plugin list

⚠️ 插件安装遇到 ERR_PNPM_UNEXPECTING_STORE 时，参考：https://sandbaseai.github.io/deepseek-harness-handbook/pnpm-unexpected-store.html

5. MCP Server 配置

# 添加一个 MCP Server（以 Filesystem 为例）
dsh mcp add filesystem --type filesystem --root .

# 查看已配置的 MCP Servers
dsh mcp list

# 验证 MCP 连接（无报错即正常）
dsh mcp check

6. Session 管理（持久化对话）

# 查看所有 Session
dsh session list

# 恢复指定 Session
dsh session resume <session-id>

# 导出 Session 日志（调试用）
dsh session export <session-id> --format json > session.json

⚠️ Session 数据默认保存在 ~/.deepseek-harness/sessions/，迁移机器时可整体备份。

7. Token 计量查询

# 查看当前 Provider 使用量
dsh usage

# 解读 token 估算（防止上下文溢出）
# 参考：https://sandbaseai.github.io/deepseek-harness-handbook/token-meter-accounting.html

典型适用场景

1. 作为 DeepSeek API 的高级客户端 不想只用 API 调用，而希望有 Agent 记忆、工具调用、多轮对话管理时，DSH 比 raw API 更适合。

2. 团队统一 AI 编程环境 通过 Plugin Store 预装团队统一插件集（代码审查、文档生成、CI 集成），Session 持久化让上下文不丢失。

3. 自动化流水线（Headless/CI） 在 CI 环境中用 dsh run 执行代码审查、文档生成等重复任务，结合 GitHub Actions 使用。

4. MCP 工具接入 已有 MCP Server（如文件系统、数据库、API），通过 DSH 统一接入多个 Agent provider，统一管理权限和 Session。

5. 跨 provider 路由与对比 同时配置 DeepSeek、OpenAI、Claude 等多个 provider，通过 DSH 切换对比不同模型能力，降低厂商锁定风险。

坑与注意

坑点	说明	解决方案
rc.7 → rc.8 兼容破坏	rc.8 引入了一些不兼容变更，旧配置可能失效	参考 Field Status 页面：https://sandbaseai.github.io/deepseek-harness-handbook/field-status.html
pnpm 安装卡在 `npx install-boundary`	pnpm 缓存与 root 冲突	参考 runbook：pnpm-adding-to-root.html
Windows 中文路径导致工具调用失败	PTY 与 locale/readline 冲突	参考：macos-bash-nonascii.html（含 Windows 方案）
上下文窗口溢出（Context overflow）	长对话后 token 超限，Agent 停止响应	参考：context-window-overflow.html，含压缩策略
插件加载报 `missing @deepseek-ai/dsh-client-schema-form`	插件 distribution-closure 不完整	参考：missing-client-schema-form.html
重复安装导致 `Duplicate core runtime`	多份 dsh-core 包同时存在	参考：duplicate-core-runtime.html
Session 历史损坏（Poisoned Session）	JSON 解析失败或工具返回异常	参考：poisoned-session-invalid-tool-json.html
CJK 命令在 Bash 中卡死 300 秒	PTY 损坏与 locale trap 共同作用	参考：separate-locale-readline-trap.html

与同类对比

维度	DeepSeek Harness	Claude Code	OpenAI Codex
定位	Agent 运行时 + 插件生态	官方 CLI 编程工具	官方 SaaS/API 编程工具
Provider 灵活性	多 provider（MCP/Agent）	主要 OpenAI/Anthropic	主要 OpenAI
插件生态	Plugin Store + MCP 扩展	有限插件	极有限插件
Session 持久化	✅ 完整	✅ 有限	❌ 无（API 调用）
Headless/CI 支持	✅ 完善	✅	✅
中文文档	英文原版 + 本手册中文参考	有限	有限
维护活跃度	rc.8 开发中（社区手册 114 篇）	官方稳定	官方稳定
上手门槛	中等（手册齐全）	低	低

结论：如果你使用 DeepSeek 系列模型或需要高度可定制的 Agent 运行时，DSH + 本手册是最佳组合；如果只用 Claude/OpenAI 的官方能力，直接用 Claude Code 或 Codex 更省心。

一句话推荐

DeepSeek Harness 是目前最接近 Claude Code 体验的多 provider 开源 Agent 运行时，配合 SandBase 这部 114 篇源码级手册，遇到任何问题都能快速找到有原始链接的可靠答案。

最小可跑命令清单

# 硬件：NVIDIA GPU（24GB+ VRAM）或纯 API 模式（无需 GPU）
# 系统：macOS/Linux/Windows 10+
# CUDA：12.1+（仅本地模型 provider 场景）
# Node：20+（rc.8 要求）

# ① 安装（无需 clone，npm 一行）
npm install -g @deepseek-ai/deepseek-harness

# ② 验证安装
dsh --version

# ③ 启动 Web UI
DEEPSEEK_API_KEY=sk-xxxx dsh web
# → 访问 http://localhost:3000

# ④ CLI 单次任务
dsh run "解释什么是 RAG" --model deepseek-chat

# ⑤ 查看 Provider 配置
dsh config list-providers

# ⑥ 遇到问题查手册（交互式路由）
# https://sandbaseai.github.io/deepseek-harness-handbook/diagnose.html

来源：DeepSeek Harness Handbook · DSH GitHub · Field Status · Install Doctor