环境搭建与 CLI/Web 运行时验证

约 30 分钟

完成 Node.js、pnpm 及 @deepseek-ai/dsh 的安装与 API 密钥配置，成功启动本地 Harness 服务。

核心概念

DeepSeek Harness 插件式架构与 Cordis 内核

想象你拥有一台模块化组装电脑，机箱和主板只提供电力总线和插槽，而 CPU、显卡、声卡和屏幕都是外插模块。如果你想升级图形性能或换用不同的扬声器，只需拔插对应板卡，无需重构整台机器的电气回路。

技术定义上，DeepSeek Harness (dsh) 是由深度求索官方开源的模块化智能体框架，其底层由 Cordis 依赖注入与微内核插件系统驱动。在 Harness 的体系中践行“一切皆插件”（Everything is a plugin）的设计理念：大模型适配器（LLM Provider）、工具注册表（Tools）、会话日志流（Sessions）、调度循环（Loop）以及 Web/CLI 交互界面均以插件形态挂载在统一的 Context 容器上。系统运行时不存在特权核心，所有能力均通过声明服务依赖与事件总线进行协同，开发者无需侵入框架源码即可通过配置实现能力的自由拔插与重组。

1. 运行环境与依赖要求

DeepSeek Harness 运行时基于 TypeScript 与现代 JavaScript 运行时构建。为了保证 Cordis 微内核与各类 Agent 插件的正常加载与解析，开发环境需要满足明确的运行时基线。

  • Node.js 版本基线：仓库与底层服务要求 Node.js 版本满足 ^22.19.0 || >=24.0.0。Node.js 20 及更早版本缺乏部分新语法与内置 API 支持，会导致模块加载阶段发生未知解析错误。推荐使用当前活跃的 LTS 版本（如 Node.js 22.x 或 24.x）。
  • 包管理器工具：Harness 在管理插件生命周期、增删外部依赖以及 Monorepo 构建时深度集成 pnpm，需全局安装 pnpm 工具。
  • 核心 CLI 包：DeepSeek 官方通过 npm 仓库分发 @deepseek-ai/dsh 命令行工具。全局安装后即可直接使用 dsh 命令调度运行时、管理插件及启动本地服务。
  • API 凭据要求：智能体执行多步推理与内置搜索等能力需要连接模型后端。Harness 默认读取环境变量 DEEPSEEK_API_KEY，用于初始化官方模型连接与内置网络搜索服务。

安装 Harness 运行时与启动验证

  1. 1

    检查本地 Node.js 与 npm 版本，确认 Node.js 大于等于 22.19.0 或 24.x。

    bash
    node -v
npm -v
  2. 2

    全局安装 pnpm 包管理器与 DeepSeek Harness 命令行运行时 @deepseek-ai/dsh。

    bash
    npm install -g pnpm @deepseek-ai/dsh
  3. 3

    验证 dsh 命令行工具是否成功安装并输出版本号信息。

    bash
    dsh --version
  4. 4

    配置 DeepSeek API 密钥环境变量（根据操作系统选择对应命令）。

    bash
    # Linux / macOS
export DEEPSEEK_API_KEY="your_deepseek_api_key_here"

# Windows PowerShell
# $env:DEEPSEEK_API_KEY="your_deepseek_api_key_here"
  5. 5

    启动本地 Harness Web 运行时服务，加载预设插件并监听本地端口。

    bash
    dsh web

你应该看到

执行 dsh --version 时终端打印正确的版本号（如 0.1.0-rc.7）；执行 dsh web 后控制台输出启动日志，并在浏览器访问 http://127.0.0.1:3080 时能成功打开 Harness Web 管理界面。

遇到问题：运行 dsh web 报错“port in use”端口被占用，或启动时出现语法/模块解析异常立即崩溃

可能原因

  • Node.js 版本低于 22.19.0（如使用了 Node 20），导致框架运行所需的高级 ECMAScript 特性或内部 API 不可用
  • 此前运行的 dsh web 进程在终端关闭后残留为孤儿进程，持续占用 3080 端口
  • 未正确注入 DEEPSEEK_API_KEY 导致会话与模型插件初始化失败

排查步骤

  1. 执行 node -v 检查版本，若版本过低，使用 nvm 或包管理器升级至 Node.js 22.19.0+ 或 24.x LTS：nvm install 24 && nvm use 24
  2. 在 Linux/macOS 下排查并释放 3080 端口占用：lsof -i :3080 查看 PID 并通过 kill <PID> 终止残留进程
  3. 检查终端环境变量：执行 echo $DEEPSEEK_API_KEY（PowerShell 下执行 echo $env:DEEPSEEK_API_KEY），确认密钥已注入且非空
  4. 重新在终端执行 dsh web 启动服务并访问 http://127.0.0.1:3080
自检：DeepSeek Harness 的架构中，“一切皆插件”的核心含义是什么？框架自身是如何管理各插件的？

“一切皆插件”意味着 Harness 自身没有特权核心，模型连接、工具调用、UI 界面、会话日志等能力全部作为插件存在。框架底层通过 Cordis 微内核容器进行统一调度，插件通过 Context 注册与获取服务，并通过声明式依赖（inject）自动解析加载拓扑，使得任何功能都可以在配置层直接替换或扩展。