DSH = DeepSeek Harness，DeepSeek 官方开源、一切皆插件的 Agent 运行时框架，MIT 协议，基于 Cordis 插件内核；模型适配器、工具、Shell、文件编辑器、会话存储、Agent 循环、WebUI 全部是可替换插件，主打可组装、可二次开发的本地智能代理工作台。 一句话定位：它不是一个聊天网页，而是一套AI Agent 的操作系统底座，让大模型安全读写文件、执行命令、串联工具、自动完成工程任务。

目录

1. 基础认知：DSH 核心概念与架构

2. 入门篇：环境准备 + 一键启动

3. 基础使用：WebUI、模型配置、第一个 Agent 任务

4. 进阶篇：CLI 命令、插件管理、运行模式、多模型接入

5. 精通篇：自定义插件开发、权限沙箱、工作流编排、源码部署

6. 实战场景、排错清单、安全规范

7. 高阶延伸：本地模型接入、生产部署、集成 n8n/Odoo

一、基础认知：DSH 核心概念

1.1 核心设计哲学：Everything is a Plugin（一切皆插件）

传统 Agent 框架：工具、模型、界面写死在代码里； DSH：所有能力拆成独立插件（NPM 包），随时增删、替换、组合：

• 模型插件：DeepSeek、OpenAI、SiliconFlow、Ollama 本地模型适配器

• 工具插件：Shell 命令、文件读写、Git、浏览器、代码解释器

• 内核插件：会话存储、轨迹记录、Agent 循环、权限沙箱

• UI 插件：Web 前端、CLI 交互面板

1.2 四种内置运行模式（Preset）

• Standard（标准模式）：全套工具，日常开发、写代码、工程任务，默认推荐

• Code（代码模式）：模型生成代码编排多轮工具调用，适合复杂自动化

• Minimal（极简模式）：仅保留 Shell + 文件编辑器，跑分、干净基准测试

• Creator（创造者模式）：内存调试插件、实时修改内核、组装自定义模式，插件开发专用

1.3 关键名词

• Workspace（工作区）：Agent 的文件根目录，Agent 只能在选定工作区内读写文件，是安全边界

• Trajectory（轨迹）：完整执行日志，模型思考、工具调用、文件修改、命令输出全部可回放审查

• Sandbox（沙箱）：限制高危命令、网络、文件范围，防止 Agent 误删系统文件

• Cordis：DSH 底层插件内核，负责插件加载、依赖解析、消息总线

⚠️ 重要提醒：当前为开发者预览版，接口、配置文件可能变更，不建议直接裸跑在公网无认证环境。

二、入门篇：环境准备 + 一键启动

2.1 前置依赖

Node.js ≥ 22 LTS（硬性要求，低版本会报错）

# 校验
node --version
npm --version

Windows：PowerShell / Terminal；macOS / Linux：自带终端。

2.2 两种启动方式（新手优先第一种 npx）

方式A：免安装，npx 临时启动（快速体验，推荐入门）

npx @deepseek-ai/dsh web
# 不自动打开浏览器（SSH远程服务器用）
npx @deepseek-ai/dsh web --no-open

启动成功后：[http://127.0.0.1:3080](http://127.0.0.1:3080)

方式B：全局安装（长期高频使用）

npm install -g @deepseek-ai/dsh
# 校验版本
dsh --version
# 启动webui
dsh web

方式C：源码编译（后面精通章节讲解）

2.3 首次打开：配置 API Key

1. 进入 Settings → Models

2. 选择 DeepSeek 模型卡片，填入从 platform.deepseek.com 获取的 API Key

3. 保存，无需重启；默认模型一般为 deepseek-flash / deepseek-v4

4. 也可以添加第三方模型：SiliconFlow、OpenAI、Ollama 本地模型适配器插件

密钥默认存储位置：$DSH_HOME/.credentials.yaml，不会硬编码到会话记录

2.4 跑通你的第一个 Agent 任务

1. 左侧选择 Workspace：新建/选中一个本地文件夹（不要直接选 C盘根目录 / / 系统根目录）

2. 新建 Session，输入任务示例：

   在当前目录创建一个 python 爬虫模板，增加 requirements.txt，写好注释，不要执行网络请求

3. 发送，观察 Agent：读取目录、新建文件、写入代码，所有操作在 Trajectory 面板回看

4. 任务结束后，直接去本地文件夹查看产出文件

✅ 入门阶段记住一条铁律：工作区 = Agent 的权限边界

三、进阶篇：CLI、插件管理、多模型、预设切换

3.1 DSH 常用 CLI 完整命令

# 启动web
dsh web
# 直接在终端跑对话（纯CLI模式，无网页）
dsh chat
# 切换预设模式启动
dsh web --preset code
dsh web --preset minimal
# 插件管理核心命令
dsh plugin add <npm包名>     # 安装插件
dsh plugin list              # 查看已加载插件
dsh plugin remove <包名>     # 卸载插件
dsh plugin info <包名>       # 查看插件详情
# 导出会话轨迹
dsh session export <session-id> ./traj.json
# 查看配置路径
dsh config path

3.2 插件生态怎么玩

插件本质是 NPM 包，社区插件市场覆盖：Git、Docker、浏览器抓取、飞书/企微通知、SQL查询、Ollama 本地模型适配器。 示例：接入 Ollama 本地大模型

dsh plugin add @dsh-plugins/ollama

然后在 Settings → Models 里面选择 Ollama，填写本地 ollama 地址 [http://127.0.0.1:11434](http://127.0.0.1:11434)，选择 qwen、deepseek-r1 等本地模型，零公网API、离线跑Agent。

3.3 环境变量配置（服务器部署常用）

# DeepSeek Key 环境变量，无需在UI手动填
export DEEPSEEK_API_KEY="sk-xxxx"
# 修改web端口
export DSH_WEB_PORT=3081
# 指定工作区默认目录
export DSH_DEFAULT_WORKSPACE="/opt/dsh-workspace"

3.4 权限沙箱配置（进阶安全）

Settings → Sandbox：

• 禁止危险命令：rm -rf、sudo、格式化、系统修改命令

• 网络白名单：限制 Agent 只能访问指定域名

• 文件只读目录、禁止访问目录黑名单

  新手强烈建议开启沙箱，防止 Agent 理解偏差误删文件

四、精通篇：自定义插件开发、源码部署、高级编排

适合全栈/运维开发者，DSH 的核心价值在这里：自己造工具给 Agent 使用

4.1 插件基础规范（Cordis 插件标准）

DSH 插件是标准 Node 包，遵循 Cordis 协议，最小插件结构：

my-dsh-plugin/
├── package.json
├── index.js       # 插件入口
└── manifest.yaml  # DSH插件清单：名称、能力、schema、权限声明

manifest.yaml 声明插件类型：模型适配器 / tool 工具 / storage / ui 组件 工具插件需要定义 tool schema（JSON Schema），告诉大模型这个工具能干什么、入参是什么。

一个极简工具插件骨架（index.js）

import { Plugin } from '@cordisjs/core'

export default class extends Plugin {
  async activate() {
    // 向DSH内核注册一个工具
    this.ctx.tools.register({
      name: "my-file-count",
      description: "统计目录下文件数量",
      schema: { type:"object", properties:{path:{type:"string"}} },
      handler: async (args)=>{
        // 业务逻辑
      }
    })
  }
}

写完本地调试：

# 在插件目录链接到dsh
dsh plugin add ./my-dsh-plugin

Creator 模式下可以热重载插件，不用重启整个 DSH 服务。

4.2 源码编译部署（本地二次开发）

git clone [https://github.com/deepseek-ai/deepseek-harness.git](https://github.com/deepseek-ai/deepseek-harness.git)
cd deepseek-harness
pnpm install
pnpm run build
# 本地启动源码版
pnpm dsh web

适合需要修改内核、定制WebUI、修改Agent循环逻辑的场景；编译产出可以打包私有化部署。

4.3 Agent 高级编排：复合任务、多轮子Agent

DSH 支持在 Creator / Code 模式下写Agent 子任务调度：

1. 任务拆分插件：把大需求拆成子任务

2. 子Agent：每个子任务独立会话、独立工作区、独立模型

3. 结果汇总、校验、重试策略 适合场景：批量代码重构、文档批量解析、运维巡检流水线

4.4 持久化、会话存储后端替换

默认会话存在本地文件；你可以替换存储插件：SQLite、PostgreSQL、Redis，把所有 Agent 轨迹持久入库，用于审计、复盘、批量分析。

五、实战场景（直接复制使用）

场景1：全栈代码工程助手（Standard模式）

需求：在当前项目里，扫描所有JS文件，找出未捕获异常，生成修复方案，写入patch文件，不要自动执行npm install

场景2：运维自动化（Minimal + Shell插件，严格沙箱）

需求：读取服务器监控日志，过滤报错，整理Markdown报告，禁止重启服务、禁止删除日志

场景3：本地离线Agent（Ollama插件接入本地模型）

需求：使用本地DeepSeek-R1，在工作区内阅读技术文档、生成脚本，不走公网

场景4：企业通知联动（飞书/钉钉插件）

Agent任务完成自动推送报告到群聊，适合巡检、数据导出自动化

六、排错清单（高频坑）

1. node版本过低：必须 ≥22，nvm 切换版本解决

2. 插件安装失败：检查npm镜像、网络，源码版优先pnpm

3. Agent 无法读写文件：检查 Workspace 是否选中、沙箱黑名单、文件夹权限

4. API 调用失败：key复制空格、余额不足、模型名称写错、代理网络问题

5. 端口3080占用：DSH_WEB_PORT 换端口

6. Agent 乱执行高危命令：开启Sandbox，添加命令黑名单

七、安全规范（重中之重）

1. 永远不要把工作区设为系统根目录

2. 公网暴露 DSH WebUI 必须开启账号密码认证（Settings → Auth），加反向代理+HTTPS，禁止裸奔

3. 给Agent最小权限原则：只读目录、禁用sudo、限制出站网络

4. 重要生产环境任务，优先开启轨迹审查，人工确认高危操作

5. 不要给Agent配置高权限云API密钥

八、进阶延伸方向

• 搭配 Ollama / Llama.cpp 实现完全离线本地 Agent

• 接入 n8n、GLPI 工单系统，做成运维自动工单Agent

• 二次开发WebUI，嵌入企业内部平台

• 批量跑评测：Minimal模式做模型工具调用能力Benchmark

DeepSeek-DSH-离线部署与系统集成实战.md