在实际 AI 应用开发中将大语言模型LLM的能力与具体业务逻辑、工具调用和自动化流程结合起来是构建智能助手Agent的核心挑战。开发者往往需要处理复杂的提示词工程、工具集成、状态管理和部署运维这些工作不仅繁琐而且对全栈能力要求很高。DeepSeek Harness简称 DSH正是为了解决这一问题而生的开源框架它旨在提供一个低代码、可扩展的平台让开发者能快速构建、测试和部署基于 LLM 的智能体应用。本文面向希望快速上手 AI Agent 开发的工程师、对低代码 AI 应用构建感兴趣的产品经理以及任何想将 DeepSeek 等模型能力融入现有工作流的实践者。我们将从零开始完成 DSH 桌面套件的安装、核心概念的理解、一个简单 Agent 的创建与配置并最终实现一键部署和运行。整个过程将聚焦于实践解释每一步背后的设计逻辑并涵盖从环境准备到问题排查的完整路径。1. 理解 DeepSeek Harness 的核心概念与架构在开始安装和编码之前必须理解 DSH 试图解决什么问题以及它是如何组织工作的。这将帮助你在后续配置和开发中做出正确的决策而不是盲目地跟随步骤。1.1 Agent、Harness 与 SkillsDSH 的核心组件DSH 框架的核心是三个概念Agent、Harness 和 Skills。它们的关系类似于一个舞台剧Agent是演员具备思考和执行能力Harness是舞台和导演系统提供运行环境和编排逻辑而Skills是演员可以使用的道具或剧本即具体的工具和能力。Agent智能体这是你构建的 AI 应用主体。一个 Agent 通常由一个 LLM如 DeepSeek驱动并配备了一系列 Skills。它接收用户的输入自然语言或结构化数据理解意图决定调用哪个 Skill处理 Skill 返回的结果并最终生成回复。在 DSH 中你可以通过配置文件来定义 Agent 的模型、提示词、记忆能力和可用 Skills。Harness框架/套件这是 DSH 框架本身它提供了运行 Agent 所需的一切基础设施。这包括运行时环境执行 Agent 逻辑的引擎。Skill 管理加载、注册和管理各种 Skills。状态管理维护 Agent 与用户对话的上下文和历史。部署工具提供 CLI 和桌面端方便本地开发和生产部署。插件市场一个集中发现和安装 Skills插件的生态系统。Skill技能/插件这是 Agent 能力的扩展。一个 Skill 就是一个独立的功能模块可以是一个简单的计算器一个查询数据库的工具一个调用外部 API 的接口或者一个控制智能家居的指令集。DSH 社区提供了丰富的预置 Skills你也可以开发自己的 Skill。Skill 是 DSH 实现“低代码”的关键因为很多通用能力无需重复开发。1.2 DSH 桌面套件与 CLI 工具的关系DSH 提供了两种主要的交互方式命令行界面CLI和桌面图形界面Desktop Suite。它们底层共享相同的核心框架但面向不同场景。deepseek-ai/dsh(CLI)这是一个通过 npm 全局安装的命令行工具。它提供了创建项目、管理插件、运行 Agent 等所有功能适合喜欢终端操作、需要自动化脚本或进行服务器部署的开发者。安装后你可以使用dsh命令来执行各种操作。DSH Desktop桌面套件这是一个独立的桌面应用程序如dshdesktop-deepseekharness桌面套件安装包v0.7.0.exe。它集成了图形化的项目管理、插件市场、Agent 配置界面和运行监控大大降低了使用门槛特别适合初学者或偏好可视化操作的用户。桌面套件内部也封装了 CLI 工具。对于初学者从桌面套件开始是最佳选择它能直观地展示项目结构和配置。但理解 CLI 命令对于深入定制和排查问题至关重要。1.3 典型工作流从想法到运行的 Agent在 DSH 中构建一个 Agent 的典型流程如下环境准备安装 Node.js 和 DSH 桌面套件或 CLI。项目创建使用工具初始化一个新的 DSH 项目这会生成标准的目录结构和配置文件。配置 Agent编辑 Agent 的配置文件通常是 YAML 或 JSON指定使用的模型如 DeepSeek、系统提示词、记忆设置等。集成 Skills从插件市场安装或自己开发所需的 Skills并在 Agent 配置中启用它们。本地运行与测试在开发环境中启动 Agent通过聊天界面或 API 进行测试和调试。部署将配置好的 Agent 项目打包部署到服务器或云平台提供稳定的服务。2. 环境准备与 DSH 桌面套件安装一个稳定、版本匹配的开发环境是成功的第一步。本节将详细说明如何准备基础环境并安装 DSH 桌面套件。2.1 基础环境Node.js 与包管理器DSH 基于 Node.js 运行时因此首先需要安装 Node.js。同时我们推荐使用pnpm作为包管理器它在依赖安装速度和磁盘空间占用上优于传统的npm。安装 Node.js访问 Node.js 官网下载 LTS长期支持版本。目前推荐版本为18.x或20.x。安装完成后打开终端Windows 为 CMD 或 PowerShellmacOS/Linux 为 Terminal验证安装node --version npm --version应输出类似v20.11.0和10.2.4的版本信息。安装 pnpm使用 npm 全局安装 pnpmnpm install -g pnpm验证安装pnpm --version2.2 安装 DSH 桌面套件对于初学者图形化的桌面套件能极大简化操作。请根据你的操作系统下载对应的安装包。获取安装包访问 DeepSeek Harness 的官方 GitHub Releases 页面或官网查找最新的桌面套件安装程序。例如对于 Windows文件可能名为dshdesktop-deepseekharness桌面套件安装包v0.7.0.exe。重要务必从官方渠道下载以确保安全。执行安装Windows: 双击下载的.exe文件按照安装向导提示完成安装。通常只需选择安装路径并点击“下一步”即可。macOS: 如果是.dmg文件双击打开后将应用程序拖入“应用程序”文件夹。Linux: 如果是.AppImage文件赋予可执行权限后直接运行chmod x filename.AppImage ./filename.AppImage。验证安装安装完成后在开始菜单或应用程序列表中找到 “DeepSeek Harness Desktop” 并启动。首次启动可能会进行初始化等待片刻即可看到主界面。2.3 可选安装 DSH CLI 工具如果你需要或更喜欢使用命令行或者桌面套件遇到问题可以安装 CLI 工具作为备用或补充。全局安装 CLI在终端中执行以下命令npm install -g deepseek-ai/dsh这个命令会从 npm 官方仓库下载并安装dsh命令行工具。验证 CLI 安装安装完成后运行dsh --version如果成功将输出 DSH 的版本号例如0.7.0。常见问题如果系统提示‘dsh’ 不是内部或外部命令也不是可运行的程序或批处理文件。这通常是因为 Node.js 的全局安装目录没有添加到系统的 PATH 环境变量中。解决方案找到 npm 的全局安装路径。通常可以通过npm config get prefix命令查看。将该路径下的bin目录例如C:\Users\YourName\AppData\Roaming\npm添加到系统的 PATH 环境变量中。添加后重新启动终端再次尝试dsh --version。3. 创建你的第一个 DSH Agent 项目安装完成后我们将通过桌面套件创建一个新的 Agent 项目。这是将概念落地的第一步。3.1 使用桌面套件初始化项目启动 DSH Desktop。创建新项目在主界面你应该能看到“新建项目”或类似的按钮。点击它。填写项目信息项目名称例如my-first-agent。项目路径选择你希望存放项目代码的本地目录。模板选择DSH 可能会提供一些入门模板如basic-agent。选择最简单的模板即可。确认创建点击创建按钮。桌面套件会在后台执行dsh init等命令生成项目骨架。3.2 理解项目结构创建成功后用你喜欢的代码编辑器如 VS Code打开项目目录。你会看到类似以下的结构my-first-agent/ ├── .dsh/ # DSH 框架运行时配置和缓存 ├── agents/ # Agent 配置目录 │ └── default/ # 默认的 Agent │ ├── agent.yaml # Agent 的核心配置文件 │ └── prompts/ # 提示词模板目录 ├── skills/ # 本地自定义 Skills 存放目录 ├── plugins/ # 从市场安装的插件存放目录 ├── package.json # Node.js 项目依赖定义 ├── dsh.config.yaml # 项目的全局配置文件 └── README.md关键文件解释agents/default/agent.yaml: 这是 Agent 的“大脑”配置文件。你需要在这里定义使用哪个模型、系统指令、记忆长度以及启用哪些 Skills。dsh.config.yaml: 项目级配置可以定义默认 Agent、模型 API 的基础 URL 和密钥等。package.json: 定义了项目的 Node.js 依赖DSH 本身和其插件都会在这里声明。3.3 配置你的第一个 Agent现在我们来编辑agent.yaml文件定义一个能进行简单对话的 Agent。打开agents/default/agent.yaml。基础配置文件内容可能已经有一个基础模板。我们将其修改为使用 DeepSeek 模型# agents/default/agent.yaml name: 我的助手 description: 一个基于 DeepSeek 的简单对话助手 # 模型配置 model: provider: openai # 注意DeepSeek 的 API 兼容 OpenAI 格式 name: deepseek-chat # 模型名称 # API 密钥和基础 URL 通常在项目级的 dsh.config.yaml 或环境变量中配置这里可以留空 # apiKey: ${DEEPSEEK_API_KEY} # baseURL: https://api.deepseek.com # 系统提示词定义 Agent 的角色和行为 systemPrompt: | 你是一个乐于助人的 AI 助手。请用中文友好、清晰地回答用户的问题。 如果你不知道答案就诚实地告知不要编造信息。 # 记忆配置决定 Agent 能记住多少上下文 memory: type: buffer # 使用缓冲区记忆 maxTokens: 2000 # 最大记忆 token 数 # 初始启用的 Skills 列表目前为空 skills: []配置模型 API 访问为了让 Agent 能调用 DeepSeek你需要提供 API 密钥。最佳实践是将密钥放在环境变量或项目配置中而不是硬编码在 agent.yaml 里。打开dsh.config.yaml添加或修改模型配置# dsh.config.yaml defaultAgent: default # 模型提供商配置 modelProviders: openai: # 这里配置全局的 OpenAI 兼容 API 设置DeepSeek 可用 apiKey: ${DEEPSEEK_API_KEY} # 从环境变量读取 baseURL: https://api.deepseek.com # DeepSeek API 端点在你的系统或终端中设置环境变量DEEPSEEK_API_KEYWindows (PowerShell):$env:DEEPSEEK_API_KEY你的实际deepseek-api-keymacOS/Linux (bash/zsh):export DEEPSEEK_API_KEY你的实际deepseek-api-key注意上述方法仅在当前终端会话有效。永久设置请参考操作系统配置环境变量的方法。4. 运行、测试与集成 Skills配置好基础的 Agent 后我们可以在本地运行它并进行测试。之后我们将通过插件市场为它添加实际的能力Skills。4.1 在桌面套件中运行 Agent在 DSH Desktop 中打开你刚创建的项目。找到“运行”或“启动 Agent”的按钮通常很醒目。点击运行。桌面套件会在后台启动一个本地服务器并打开一个内置的聊天界面窗口。在聊天界面中尝试输入一些问题例如“你好介绍一下你自己”。你应该能收到 Agent 基于 DeepSeek 模型生成的回复。4.2 使用 CLI 运行 Agent替代方案如果你安装了 CLI也可以在项目根目录下通过命令运行dsh start此命令会启动开发服务器并通常在http://localhost:3333提供一个 Web 界面供你交互。4.3 从插件市场安装 Skills一个只能聊天的 Agent 能力有限。DSH 的强大之处在于其插件Skills生态系统。让我们为助手添加一个“天气查询”技能。打开插件市场在 DSH Desktop 中找到“插件市场”或 “Plugin Store” 标签页。搜索 Skill在搜索框中输入 “weather”。你会看到社区贡献的天气查询插件例如dsh-plugin-weather。安装插件点击插件卡片上的“安装”按钮。桌面套件会自动执行dsh plugin add dsh-plugin-weather命令将插件下载到项目的plugins/目录并更新package.json中的依赖。在 Agent 中启用 Skill安装后需要修改agent.yaml文件将这个 Skill 添加到skills列表中。# agents/default/agent.yaml skills: - name: weather # 插件的名称通常在其文档中说明 enabled: true # 某些插件可能需要额外的配置如 API 密钥 # config: # apiKey: ${WEATHER_API_KEY}配置 Skill如果需要像天气插件通常需要第三方 API 密钥如 OpenWeatherMap。你需要按照该插件的 README 说明获取密钥并在环境变量或插件配置中设置。重启 Agent在桌面套件中停止并重新运行 Agent使新 Skill 生效。测试 Skill在聊天界面中尝试提问“北京今天的天气怎么样”。Agent 应该能理解你的意图调用天气插件并返回查询结果。如果失败请查看运行日志。4.4 开发一个简单的自定义 Skill除了使用市场插件你也可以创建自己的 Skill。这是一个简单的“计算器” Skill 示例创建 Skill 目录在skills/目录下新建一个文件夹例如calculator/。创建 Skill 定义文件在calculator/目录下创建skill.yaml# skills/calculator/skill.yaml name: calculator description: 一个简单的计算器可以执行基础算术运算。 version: 0.1.0 actions: - name: calculate description: 计算一个数学表达式的结果。 parameters: - name: expression description: 数学表达式例如 ‘2 3 * 4‘ required: true schema: type: string创建 Skill 实现文件在calculator/目录下创建index.js// skills/calculator/index.js module.exports { async calculate({ expression }) { // 警告在生产环境中直接使用 eval 是极其危险的 // 这里仅作演示实际应用应使用安全的数学表达式解析库如 mathjs。 try { // 简单演示移除危险字符非常基础的过滤不适用于生产 const sanitizedExpr expression.replace(/[^0-9\-*/().\s]/g, ); const result eval(sanitizedExpr); return { success: true, result: ${expression} ${result} }; } catch (error) { return { success: false, error: 计算失败: ${error.message} }; } } };重要安全提示上述代码使用eval仅为演示存在严重安全漏洞。真实技能必须使用安全的解析库如mathjs并严格验证输入。在 Agent 中启用自定义 Skill在agent.yaml的skills列表中添加skills: - name: weather enabled: true - name: calculator # 与你 skill.yaml 中的 name 一致 enabled: true source: local # 指明是本地技能重启并测试重启 Agent然后尝试提问“请计算一下 15 乘以 28 加上 7 等于多少” Agent 应该能识别出计算意图调用你的 calculator skill 并返回结果。5. 部署配置与一键部署实践本地测试成功后你可能希望将 Agent 部署到服务器提供持续稳定的服务。DSH 支持多种部署方式。5.1 理解部署包DSH 项目本质上是一个 Node.js 应用。部署时你需要将整个项目目录排除node_modules和开发配置文件打包然后在目标服务器上安装依赖并启动。生产环境依赖确保package.json中的依赖都是生产环境必需的。dependencies里应包含deepseek-ai/dsh和你安装的所有插件。devDependencies中的内容不会被打包到生产环境。环境变量分离所有敏感信息API 密钥、数据库连接串等必须通过环境变量或安全的配置管理服务提供。检查dsh.config.yaml和各个 Skill 的配置确保没有硬编码的密钥。5.2 创建一键部署脚本你可以编写一个简单的 Shell 脚本或批处理文件来标准化部署流程。以下是一个 Linux/macOS 下的deploy.sh脚本示例#!/bin/bash # deploy.sh - 简易 DSH Agent 部署脚本 set -e # 遇到错误则退出 SERVER_USERyour_username SERVER_IPyour.server.ip PROJECT_DIR/opt/dsh-agents/my-first-agent DEPLOY_TAGv$(date %Y%m%d%H%M%S) # 使用时间戳作为版本标签 echo 开始部署版本: $DEPLOY_TAG # 1. 本地打包排除不需要的文件 echo 正在本地打包项目... tar --excludenode_modules \ --exclude.git \ --exclude.dsh \ --exclude*.log \ -czf /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz . # 2. 上传到服务器 echo 正在上传包到服务器... scp /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz $SERVER_USER$SERVER_IP:/tmp/ # 3. 在服务器上执行部署 echo 正在远程执行部署命令... ssh $SERVER_USER$SERVER_IP set -e DEPLOY_PATH$PROJECT_DIR/$DEPLOY_TAG mkdir -p \$DEPLOY_PATH echo 解压部署包... tar -xzf /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz -C \$DEPLOY_PATH echo 安装依赖... cd \$DEPLOY_PATH npm ci --onlyproduction # 使用 clean install只安装生产依赖 echo 重启服务... # 假设使用 systemd 管理服务服务名为 dsh-my-first-agent sudo systemctl restart dsh-my-first-agent echo 清理旧版本保留最近3个版本... cd $PROJECT_DIR ls -dt */ | tail -n 4 | xargs rm -rf echo 部署完成 echo 本地清理... rm /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz echo 全部完成Agent 已更新至版本: $DEPLOY_TAG使用前需要修改SERVER_USER,SERVER_IP: 你的服务器用户名和 IP。PROJECT_DIR: 服务器上项目部署的根目录。脚本中假设你使用systemd来管理 DSH 服务。你需要先在服务器上创建对应的 service 文件。5.3 配置生产环境服务以 systemd 为例在目标服务器上创建一个 systemd 服务文件来管理 DSH Agent确保其开机自启和崩溃重启。创建服务文件sudo vim /etc/systemd/system/dsh-my-first-agent.service编辑内容[Unit] DescriptionMy First DSH Agent Service Afternetwork.target [Service] Typesimple Useryour_linux_user # 运行服务的用户 WorkingDirectory/opt/dsh-agents/my-first-agent/current # 指向当前版本的软链接 EnvironmentDEEPSEEK_API_KEYyour_api_key_here # 在此设置环境变量或使用 EnvironmentFile # EnvironmentFile/etc/default/dsh-agent # 也可以从文件加载环境变量 ExecStart/usr/bin/npm start # 假设 package.json 中定义了 start 脚本 Restarton-failure RestartSec10 [Install] WantedBymulti-user.target设置与启动sudo systemctl daemon-reload sudo systemctl enable dsh-my-first-agent.service sudo systemctl start dsh-my-first-agent.service sudo systemctl status dsh-my-first-agent.service # 检查状态配置 Nginx/Apache 反向代理可选如果你希望通过域名和 HTTPS 访问 DSH 的 Web 界面需要配置 Web 服务器反向代理到 DSH 服务运行的端口默认如3333。6. 常见问题排查与最佳实践在开发和部署过程中你可能会遇到各种问题。本节汇总了常见问题的排查路径和一些重要的实践建议。6.1 安装与启动问题排查问题现象可能原因检查方式处理建议‘dsh’ 不是内部或外部命令1. CLI 未全局安装。2. Node.js 全局 bin 目录未加入 PATH。1. 运行npm list -g deepseek-ai/dsh。2. 运行npm config get prefix检查对应bin目录是否在 PATH 中。1. 重新运行npm install -g deepseek-ai/dsh。2. 将 Node.js 全局安装目录的bin文件夹路径添加到系统环境变量 PATH 中并重启终端。桌面套件启动失败或卡住1. 端口被占用。2. 依赖安装不完整常见于pnpm dsh web阶段。3. 系统兼容性问题。1. 查看套件日志或系统任务管理器。2. 尝试在项目目录下手动运行pnpm install或npm install。3. 检查官方文档的系统要求。1. 关闭占用端口的程序。2. 清理项目node_modules和锁文件重新安装依赖。3. 以管理员/兼容模式运行或查看 GitHub Issues。Agent 启动失败提示模型连接错误1. API 密钥未设置或错误。2.baseURL配置错误。3. 网络问题。1. 检查dsh.config.yaml和环境变量DEEPSEEK_API_KEY。2. 确认baseURL是否为https://api.deepseek.com。3. 尝试用curl测试 API 连通性。1. 确保密钥正确且已导出到当前 shell 环境。2. 核对配置文件的缩进和语法。3. 检查防火墙和代理设置。6.2 Agent 运行问题排查问题现象可能原因检查方式处理建议Agent 不调用 Skill1. Skill 未在agent.yaml中启用。2. Skill 配置错误或依赖缺失。3. 用户提问未触发 Skill 的意图识别。1. 检查agent.yaml中skills列表。2. 查看 Agent 运行日志看是否有 Skill 加载错误。3. 检查 Skill 的description和parameters定义是否清晰。1. 确保enabled: true。2. 根据日志安装缺失依赖或修正配置。3. 优化系统提示词明确说明 Agent 具备哪些能力。Skill 执行报错1. Skill 代码逻辑错误。2. 第三方 API 调用失败密钥、配额、网络。3. 输入参数格式不符合预期。1. 查看详细的错误堆栈日志。2. 单独测试 Skill 的 API 调用。3. 打印 Skill 接收到的参数。1. 调试本地 Skill 代码。2. 验证 API 密钥和配额添加重试和降级逻辑。3. 在 Skill 中增加参数验证和格式化。Agent 响应慢1. LLM API 调用延迟高。2. Skill 执行耗时久。3. 上下文记忆过长。1. 测量各阶段耗时可使用日志打点。2. 检查网络延迟。3. 观察memory.maxTokens设置。1. 考虑使用更快的模型或优化提示词。2. 对慢 Skill 做异步处理或缓存。3. 适当限制记忆长度或使用更高效的记忆类型。6.3 生产环境最佳实践清单将 DSH Agent 用于生产环境时请务必考虑以下几点安全第一绝不硬编码密钥所有 API 密钥、数据库密码等必须通过环境变量或专业的密钥管理服务如 HashiCorp Vault, AWS Secrets Manager注入。验证用户输入自定义 Skill 必须对输入进行严格的验证、清理和转义防止注入攻击。权限最小化确保运行 DSH 进程的操作系统用户拥有最小必要权限。启用 HTTPS如果对外提供 Web 服务务必通过反向代理如 Nginx配置 HTTPS。配置管理环境分离为开发、测试、生产环境准备不同的配置文件如dsh.config.dev.yaml,dsh.config.prod.yaml通过环境变量NODE_ENV切换。版本化配置将配置文件纳入版本控制但排除敏感信息便于回滚和审计。可观测性结构化日志配置 DSH 输出结构化的 JSON 日志便于被 ELK、Loki 等日志系统收集和分析。添加监控指标在关键位置如模型调用、Skill 执行添加指标集成到 Prometheus 等监控系统。健康检查为 Agent 服务实现/health端点供负载均衡器或编排系统检查。可靠性设置超时与重试对 LLM API 和外部服务调用配置合理的超时和重试策略。实现熔断降级对于非核心 Skill在其不可用时提供友好的降级回复避免单点故障导致整个 Agent 不可用。进程管理使用systemd,supervisor或容器编排如 Docker Compose, Kubernetes来管理进程确保崩溃后自动重启。性能与成本缓存策略对频繁且结果稳定的查询如天气、百科实施缓存减少不必要的 LLM 调用和 API 开销。优化提示词精炼系统提示词和上下文减少无效 token 消耗降低成本和延迟。异步处理对于耗时较长的 Skill考虑采用异步调用先给用户即时反馈再后台处理。通过遵循上述步骤和最佳实践你可以从零开始系统地构建、配置、测试并部署一个功能丰富的 DeepSeek Harness Agent。这个过程的重点不在于避免写代码而在于通过框架提供的抽象和工具将你的精力集中在定义 Agent 的行为和集成有价值的 Skills 上从而更高效地实现 AI 驱动的应用逻辑。 DeepSeek Harness 实战：从零构建 AI Agent 应用
在实际 AI 应用开发中将大语言模型LLM的能力与具体业务逻辑、工具调用和自动化流程结合起来是构建智能助手Agent的核心挑战。开发者往往需要处理复杂的提示词工程、工具集成、状态管理和部署运维这些工作不仅繁琐而且对全栈能力要求很高。DeepSeek Harness简称 DSH正是为了解决这一问题而生的开源框架它旨在提供一个低代码、可扩展的平台让开发者能快速构建、测试和部署基于 LLM 的智能体应用。本文面向希望快速上手 AI Agent 开发的工程师、对低代码 AI 应用构建感兴趣的产品经理以及任何想将 DeepSeek 等模型能力融入现有工作流的实践者。我们将从零开始完成 DSH 桌面套件的安装、核心概念的理解、一个简单 Agent 的创建与配置并最终实现一键部署和运行。整个过程将聚焦于实践解释每一步背后的设计逻辑并涵盖从环境准备到问题排查的完整路径。1. 理解 DeepSeek Harness 的核心概念与架构在开始安装和编码之前必须理解 DSH 试图解决什么问题以及它是如何组织工作的。这将帮助你在后续配置和开发中做出正确的决策而不是盲目地跟随步骤。1.1 Agent、Harness 与 SkillsDSH 的核心组件DSH 框架的核心是三个概念Agent、Harness 和 Skills。它们的关系类似于一个舞台剧Agent是演员具备思考和执行能力Harness是舞台和导演系统提供运行环境和编排逻辑而Skills是演员可以使用的道具或剧本即具体的工具和能力。Agent智能体这是你构建的 AI 应用主体。一个 Agent 通常由一个 LLM如 DeepSeek驱动并配备了一系列 Skills。它接收用户的输入自然语言或结构化数据理解意图决定调用哪个 Skill处理 Skill 返回的结果并最终生成回复。在 DSH 中你可以通过配置文件来定义 Agent 的模型、提示词、记忆能力和可用 Skills。Harness框架/套件这是 DSH 框架本身它提供了运行 Agent 所需的一切基础设施。这包括运行时环境执行 Agent 逻辑的引擎。Skill 管理加载、注册和管理各种 Skills。状态管理维护 Agent 与用户对话的上下文和历史。部署工具提供 CLI 和桌面端方便本地开发和生产部署。插件市场一个集中发现和安装 Skills插件的生态系统。Skill技能/插件这是 Agent 能力的扩展。一个 Skill 就是一个独立的功能模块可以是一个简单的计算器一个查询数据库的工具一个调用外部 API 的接口或者一个控制智能家居的指令集。DSH 社区提供了丰富的预置 Skills你也可以开发自己的 Skill。Skill 是 DSH 实现“低代码”的关键因为很多通用能力无需重复开发。1.2 DSH 桌面套件与 CLI 工具的关系DSH 提供了两种主要的交互方式命令行界面CLI和桌面图形界面Desktop Suite。它们底层共享相同的核心框架但面向不同场景。deepseek-ai/dsh(CLI)这是一个通过 npm 全局安装的命令行工具。它提供了创建项目、管理插件、运行 Agent 等所有功能适合喜欢终端操作、需要自动化脚本或进行服务器部署的开发者。安装后你可以使用dsh命令来执行各种操作。DSH Desktop桌面套件这是一个独立的桌面应用程序如dshdesktop-deepseekharness桌面套件安装包v0.7.0.exe。它集成了图形化的项目管理、插件市场、Agent 配置界面和运行监控大大降低了使用门槛特别适合初学者或偏好可视化操作的用户。桌面套件内部也封装了 CLI 工具。对于初学者从桌面套件开始是最佳选择它能直观地展示项目结构和配置。但理解 CLI 命令对于深入定制和排查问题至关重要。1.3 典型工作流从想法到运行的 Agent在 DSH 中构建一个 Agent 的典型流程如下环境准备安装 Node.js 和 DSH 桌面套件或 CLI。项目创建使用工具初始化一个新的 DSH 项目这会生成标准的目录结构和配置文件。配置 Agent编辑 Agent 的配置文件通常是 YAML 或 JSON指定使用的模型如 DeepSeek、系统提示词、记忆设置等。集成 Skills从插件市场安装或自己开发所需的 Skills并在 Agent 配置中启用它们。本地运行与测试在开发环境中启动 Agent通过聊天界面或 API 进行测试和调试。部署将配置好的 Agent 项目打包部署到服务器或云平台提供稳定的服务。2. 环境准备与 DSH 桌面套件安装一个稳定、版本匹配的开发环境是成功的第一步。本节将详细说明如何准备基础环境并安装 DSH 桌面套件。2.1 基础环境Node.js 与包管理器DSH 基于 Node.js 运行时因此首先需要安装 Node.js。同时我们推荐使用pnpm作为包管理器它在依赖安装速度和磁盘空间占用上优于传统的npm。安装 Node.js访问 Node.js 官网下载 LTS长期支持版本。目前推荐版本为18.x或20.x。安装完成后打开终端Windows 为 CMD 或 PowerShellmacOS/Linux 为 Terminal验证安装node --version npm --version应输出类似v20.11.0和10.2.4的版本信息。安装 pnpm使用 npm 全局安装 pnpmnpm install -g pnpm验证安装pnpm --version2.2 安装 DSH 桌面套件对于初学者图形化的桌面套件能极大简化操作。请根据你的操作系统下载对应的安装包。获取安装包访问 DeepSeek Harness 的官方 GitHub Releases 页面或官网查找最新的桌面套件安装程序。例如对于 Windows文件可能名为dshdesktop-deepseekharness桌面套件安装包v0.7.0.exe。重要务必从官方渠道下载以确保安全。执行安装Windows: 双击下载的.exe文件按照安装向导提示完成安装。通常只需选择安装路径并点击“下一步”即可。macOS: 如果是.dmg文件双击打开后将应用程序拖入“应用程序”文件夹。Linux: 如果是.AppImage文件赋予可执行权限后直接运行chmod x filename.AppImage ./filename.AppImage。验证安装安装完成后在开始菜单或应用程序列表中找到 “DeepSeek Harness Desktop” 并启动。首次启动可能会进行初始化等待片刻即可看到主界面。2.3 可选安装 DSH CLI 工具如果你需要或更喜欢使用命令行或者桌面套件遇到问题可以安装 CLI 工具作为备用或补充。全局安装 CLI在终端中执行以下命令npm install -g deepseek-ai/dsh这个命令会从 npm 官方仓库下载并安装dsh命令行工具。验证 CLI 安装安装完成后运行dsh --version如果成功将输出 DSH 的版本号例如0.7.0。常见问题如果系统提示‘dsh’ 不是内部或外部命令也不是可运行的程序或批处理文件。这通常是因为 Node.js 的全局安装目录没有添加到系统的 PATH 环境变量中。解决方案找到 npm 的全局安装路径。通常可以通过npm config get prefix命令查看。将该路径下的bin目录例如C:\Users\YourName\AppData\Roaming\npm添加到系统的 PATH 环境变量中。添加后重新启动终端再次尝试dsh --version。3. 创建你的第一个 DSH Agent 项目安装完成后我们将通过桌面套件创建一个新的 Agent 项目。这是将概念落地的第一步。3.1 使用桌面套件初始化项目启动 DSH Desktop。创建新项目在主界面你应该能看到“新建项目”或类似的按钮。点击它。填写项目信息项目名称例如my-first-agent。项目路径选择你希望存放项目代码的本地目录。模板选择DSH 可能会提供一些入门模板如basic-agent。选择最简单的模板即可。确认创建点击创建按钮。桌面套件会在后台执行dsh init等命令生成项目骨架。3.2 理解项目结构创建成功后用你喜欢的代码编辑器如 VS Code打开项目目录。你会看到类似以下的结构my-first-agent/ ├── .dsh/ # DSH 框架运行时配置和缓存 ├── agents/ # Agent 配置目录 │ └── default/ # 默认的 Agent │ ├── agent.yaml # Agent 的核心配置文件 │ └── prompts/ # 提示词模板目录 ├── skills/ # 本地自定义 Skills 存放目录 ├── plugins/ # 从市场安装的插件存放目录 ├── package.json # Node.js 项目依赖定义 ├── dsh.config.yaml # 项目的全局配置文件 └── README.md关键文件解释agents/default/agent.yaml: 这是 Agent 的“大脑”配置文件。你需要在这里定义使用哪个模型、系统指令、记忆长度以及启用哪些 Skills。dsh.config.yaml: 项目级配置可以定义默认 Agent、模型 API 的基础 URL 和密钥等。package.json: 定义了项目的 Node.js 依赖DSH 本身和其插件都会在这里声明。3.3 配置你的第一个 Agent现在我们来编辑agent.yaml文件定义一个能进行简单对话的 Agent。打开agents/default/agent.yaml。基础配置文件内容可能已经有一个基础模板。我们将其修改为使用 DeepSeek 模型# agents/default/agent.yaml name: 我的助手 description: 一个基于 DeepSeek 的简单对话助手 # 模型配置 model: provider: openai # 注意DeepSeek 的 API 兼容 OpenAI 格式 name: deepseek-chat # 模型名称 # API 密钥和基础 URL 通常在项目级的 dsh.config.yaml 或环境变量中配置这里可以留空 # apiKey: ${DEEPSEEK_API_KEY} # baseURL: https://api.deepseek.com # 系统提示词定义 Agent 的角色和行为 systemPrompt: | 你是一个乐于助人的 AI 助手。请用中文友好、清晰地回答用户的问题。 如果你不知道答案就诚实地告知不要编造信息。 # 记忆配置决定 Agent 能记住多少上下文 memory: type: buffer # 使用缓冲区记忆 maxTokens: 2000 # 最大记忆 token 数 # 初始启用的 Skills 列表目前为空 skills: []配置模型 API 访问为了让 Agent 能调用 DeepSeek你需要提供 API 密钥。最佳实践是将密钥放在环境变量或项目配置中而不是硬编码在 agent.yaml 里。打开dsh.config.yaml添加或修改模型配置# dsh.config.yaml defaultAgent: default # 模型提供商配置 modelProviders: openai: # 这里配置全局的 OpenAI 兼容 API 设置DeepSeek 可用 apiKey: ${DEEPSEEK_API_KEY} # 从环境变量读取 baseURL: https://api.deepseek.com # DeepSeek API 端点在你的系统或终端中设置环境变量DEEPSEEK_API_KEYWindows (PowerShell):$env:DEEPSEEK_API_KEY你的实际deepseek-api-keymacOS/Linux (bash/zsh):export DEEPSEEK_API_KEY你的实际deepseek-api-key注意上述方法仅在当前终端会话有效。永久设置请参考操作系统配置环境变量的方法。4. 运行、测试与集成 Skills配置好基础的 Agent 后我们可以在本地运行它并进行测试。之后我们将通过插件市场为它添加实际的能力Skills。4.1 在桌面套件中运行 Agent在 DSH Desktop 中打开你刚创建的项目。找到“运行”或“启动 Agent”的按钮通常很醒目。点击运行。桌面套件会在后台启动一个本地服务器并打开一个内置的聊天界面窗口。在聊天界面中尝试输入一些问题例如“你好介绍一下你自己”。你应该能收到 Agent 基于 DeepSeek 模型生成的回复。4.2 使用 CLI 运行 Agent替代方案如果你安装了 CLI也可以在项目根目录下通过命令运行dsh start此命令会启动开发服务器并通常在http://localhost:3333提供一个 Web 界面供你交互。4.3 从插件市场安装 Skills一个只能聊天的 Agent 能力有限。DSH 的强大之处在于其插件Skills生态系统。让我们为助手添加一个“天气查询”技能。打开插件市场在 DSH Desktop 中找到“插件市场”或 “Plugin Store” 标签页。搜索 Skill在搜索框中输入 “weather”。你会看到社区贡献的天气查询插件例如dsh-plugin-weather。安装插件点击插件卡片上的“安装”按钮。桌面套件会自动执行dsh plugin add dsh-plugin-weather命令将插件下载到项目的plugins/目录并更新package.json中的依赖。在 Agent 中启用 Skill安装后需要修改agent.yaml文件将这个 Skill 添加到skills列表中。# agents/default/agent.yaml skills: - name: weather # 插件的名称通常在其文档中说明 enabled: true # 某些插件可能需要额外的配置如 API 密钥 # config: # apiKey: ${WEATHER_API_KEY}配置 Skill如果需要像天气插件通常需要第三方 API 密钥如 OpenWeatherMap。你需要按照该插件的 README 说明获取密钥并在环境变量或插件配置中设置。重启 Agent在桌面套件中停止并重新运行 Agent使新 Skill 生效。测试 Skill在聊天界面中尝试提问“北京今天的天气怎么样”。Agent 应该能理解你的意图调用天气插件并返回查询结果。如果失败请查看运行日志。4.4 开发一个简单的自定义 Skill除了使用市场插件你也可以创建自己的 Skill。这是一个简单的“计算器” Skill 示例创建 Skill 目录在skills/目录下新建一个文件夹例如calculator/。创建 Skill 定义文件在calculator/目录下创建skill.yaml# skills/calculator/skill.yaml name: calculator description: 一个简单的计算器可以执行基础算术运算。 version: 0.1.0 actions: - name: calculate description: 计算一个数学表达式的结果。 parameters: - name: expression description: 数学表达式例如 ‘2 3 * 4‘ required: true schema: type: string创建 Skill 实现文件在calculator/目录下创建index.js// skills/calculator/index.js module.exports { async calculate({ expression }) { // 警告在生产环境中直接使用 eval 是极其危险的 // 这里仅作演示实际应用应使用安全的数学表达式解析库如 mathjs。 try { // 简单演示移除危险字符非常基础的过滤不适用于生产 const sanitizedExpr expression.replace(/[^0-9\-*/().\s]/g, ); const result eval(sanitizedExpr); return { success: true, result: ${expression} ${result} }; } catch (error) { return { success: false, error: 计算失败: ${error.message} }; } } };重要安全提示上述代码使用eval仅为演示存在严重安全漏洞。真实技能必须使用安全的解析库如mathjs并严格验证输入。在 Agent 中启用自定义 Skill在agent.yaml的skills列表中添加skills: - name: weather enabled: true - name: calculator # 与你 skill.yaml 中的 name 一致 enabled: true source: local # 指明是本地技能重启并测试重启 Agent然后尝试提问“请计算一下 15 乘以 28 加上 7 等于多少” Agent 应该能识别出计算意图调用你的 calculator skill 并返回结果。5. 部署配置与一键部署实践本地测试成功后你可能希望将 Agent 部署到服务器提供持续稳定的服务。DSH 支持多种部署方式。5.1 理解部署包DSH 项目本质上是一个 Node.js 应用。部署时你需要将整个项目目录排除node_modules和开发配置文件打包然后在目标服务器上安装依赖并启动。生产环境依赖确保package.json中的依赖都是生产环境必需的。dependencies里应包含deepseek-ai/dsh和你安装的所有插件。devDependencies中的内容不会被打包到生产环境。环境变量分离所有敏感信息API 密钥、数据库连接串等必须通过环境变量或安全的配置管理服务提供。检查dsh.config.yaml和各个 Skill 的配置确保没有硬编码的密钥。5.2 创建一键部署脚本你可以编写一个简单的 Shell 脚本或批处理文件来标准化部署流程。以下是一个 Linux/macOS 下的deploy.sh脚本示例#!/bin/bash # deploy.sh - 简易 DSH Agent 部署脚本 set -e # 遇到错误则退出 SERVER_USERyour_username SERVER_IPyour.server.ip PROJECT_DIR/opt/dsh-agents/my-first-agent DEPLOY_TAGv$(date %Y%m%d%H%M%S) # 使用时间戳作为版本标签 echo 开始部署版本: $DEPLOY_TAG # 1. 本地打包排除不需要的文件 echo 正在本地打包项目... tar --excludenode_modules \ --exclude.git \ --exclude.dsh \ --exclude*.log \ -czf /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz . # 2. 上传到服务器 echo 正在上传包到服务器... scp /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz $SERVER_USER$SERVER_IP:/tmp/ # 3. 在服务器上执行部署 echo 正在远程执行部署命令... ssh $SERVER_USER$SERVER_IP set -e DEPLOY_PATH$PROJECT_DIR/$DEPLOY_TAG mkdir -p \$DEPLOY_PATH echo 解压部署包... tar -xzf /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz -C \$DEPLOY_PATH echo 安装依赖... cd \$DEPLOY_PATH npm ci --onlyproduction # 使用 clean install只安装生产依赖 echo 重启服务... # 假设使用 systemd 管理服务服务名为 dsh-my-first-agent sudo systemctl restart dsh-my-first-agent echo 清理旧版本保留最近3个版本... cd $PROJECT_DIR ls -dt */ | tail -n 4 | xargs rm -rf echo 部署完成 echo 本地清理... rm /tmp/dsh-deploy-$DEPLOY_TAG.tar.gz echo 全部完成Agent 已更新至版本: $DEPLOY_TAG使用前需要修改SERVER_USER,SERVER_IP: 你的服务器用户名和 IP。PROJECT_DIR: 服务器上项目部署的根目录。脚本中假设你使用systemd来管理 DSH 服务。你需要先在服务器上创建对应的 service 文件。5.3 配置生产环境服务以 systemd 为例在目标服务器上创建一个 systemd 服务文件来管理 DSH Agent确保其开机自启和崩溃重启。创建服务文件sudo vim /etc/systemd/system/dsh-my-first-agent.service编辑内容[Unit] DescriptionMy First DSH Agent Service Afternetwork.target [Service] Typesimple Useryour_linux_user # 运行服务的用户 WorkingDirectory/opt/dsh-agents/my-first-agent/current # 指向当前版本的软链接 EnvironmentDEEPSEEK_API_KEYyour_api_key_here # 在此设置环境变量或使用 EnvironmentFile # EnvironmentFile/etc/default/dsh-agent # 也可以从文件加载环境变量 ExecStart/usr/bin/npm start # 假设 package.json 中定义了 start 脚本 Restarton-failure RestartSec10 [Install] WantedBymulti-user.target设置与启动sudo systemctl daemon-reload sudo systemctl enable dsh-my-first-agent.service sudo systemctl start dsh-my-first-agent.service sudo systemctl status dsh-my-first-agent.service # 检查状态配置 Nginx/Apache 反向代理可选如果你希望通过域名和 HTTPS 访问 DSH 的 Web 界面需要配置 Web 服务器反向代理到 DSH 服务运行的端口默认如3333。6. 常见问题排查与最佳实践在开发和部署过程中你可能会遇到各种问题。本节汇总了常见问题的排查路径和一些重要的实践建议。6.1 安装与启动问题排查问题现象可能原因检查方式处理建议‘dsh’ 不是内部或外部命令1. CLI 未全局安装。2. Node.js 全局 bin 目录未加入 PATH。1. 运行npm list -g deepseek-ai/dsh。2. 运行npm config get prefix检查对应bin目录是否在 PATH 中。1. 重新运行npm install -g deepseek-ai/dsh。2. 将 Node.js 全局安装目录的bin文件夹路径添加到系统环境变量 PATH 中并重启终端。桌面套件启动失败或卡住1. 端口被占用。2. 依赖安装不完整常见于pnpm dsh web阶段。3. 系统兼容性问题。1. 查看套件日志或系统任务管理器。2. 尝试在项目目录下手动运行pnpm install或npm install。3. 检查官方文档的系统要求。1. 关闭占用端口的程序。2. 清理项目node_modules和锁文件重新安装依赖。3. 以管理员/兼容模式运行或查看 GitHub Issues。Agent 启动失败提示模型连接错误1. API 密钥未设置或错误。2.baseURL配置错误。3. 网络问题。1. 检查dsh.config.yaml和环境变量DEEPSEEK_API_KEY。2. 确认baseURL是否为https://api.deepseek.com。3. 尝试用curl测试 API 连通性。1. 确保密钥正确且已导出到当前 shell 环境。2. 核对配置文件的缩进和语法。3. 检查防火墙和代理设置。6.2 Agent 运行问题排查问题现象可能原因检查方式处理建议Agent 不调用 Skill1. Skill 未在agent.yaml中启用。2. Skill 配置错误或依赖缺失。3. 用户提问未触发 Skill 的意图识别。1. 检查agent.yaml中skills列表。2. 查看 Agent 运行日志看是否有 Skill 加载错误。3. 检查 Skill 的description和parameters定义是否清晰。1. 确保enabled: true。2. 根据日志安装缺失依赖或修正配置。3. 优化系统提示词明确说明 Agent 具备哪些能力。Skill 执行报错1. Skill 代码逻辑错误。2. 第三方 API 调用失败密钥、配额、网络。3. 输入参数格式不符合预期。1. 查看详细的错误堆栈日志。2. 单独测试 Skill 的 API 调用。3. 打印 Skill 接收到的参数。1. 调试本地 Skill 代码。2. 验证 API 密钥和配额添加重试和降级逻辑。3. 在 Skill 中增加参数验证和格式化。Agent 响应慢1. LLM API 调用延迟高。2. Skill 执行耗时久。3. 上下文记忆过长。1. 测量各阶段耗时可使用日志打点。2. 检查网络延迟。3. 观察memory.maxTokens设置。1. 考虑使用更快的模型或优化提示词。2. 对慢 Skill 做异步处理或缓存。3. 适当限制记忆长度或使用更高效的记忆类型。6.3 生产环境最佳实践清单将 DSH Agent 用于生产环境时请务必考虑以下几点安全第一绝不硬编码密钥所有 API 密钥、数据库密码等必须通过环境变量或专业的密钥管理服务如 HashiCorp Vault, AWS Secrets Manager注入。验证用户输入自定义 Skill 必须对输入进行严格的验证、清理和转义防止注入攻击。权限最小化确保运行 DSH 进程的操作系统用户拥有最小必要权限。启用 HTTPS如果对外提供 Web 服务务必通过反向代理如 Nginx配置 HTTPS。配置管理环境分离为开发、测试、生产环境准备不同的配置文件如dsh.config.dev.yaml,dsh.config.prod.yaml通过环境变量NODE_ENV切换。版本化配置将配置文件纳入版本控制但排除敏感信息便于回滚和审计。可观测性结构化日志配置 DSH 输出结构化的 JSON 日志便于被 ELK、Loki 等日志系统收集和分析。添加监控指标在关键位置如模型调用、Skill 执行添加指标集成到 Prometheus 等监控系统。健康检查为 Agent 服务实现/health端点供负载均衡器或编排系统检查。可靠性设置超时与重试对 LLM API 和外部服务调用配置合理的超时和重试策略。实现熔断降级对于非核心 Skill在其不可用时提供友好的降级回复避免单点故障导致整个 Agent 不可用。进程管理使用systemd,supervisor或容器编排如 Docker Compose, Kubernetes来管理进程确保崩溃后自动重启。性能与成本缓存策略对频繁且结果稳定的查询如天气、百科实施缓存减少不必要的 LLM 调用和 API 开销。优化提示词精炼系统提示词和上下文减少无效 token 消耗降低成本和延迟。异步处理对于耗时较长的 Skill考虑采用异步调用先给用户即时反馈再后台处理。通过遵循上述步骤和最佳实践你可以从零开始系统地构建、配置、测试并部署一个功能丰富的 DeepSeek Harness Agent。这个过程的重点不在于避免写代码而在于通过框架提供的抽象和工具将你的精力集中在定义 Agent 的行为和集成有价值的 Skills 上从而更高效地实现 AI 驱动的应用逻辑。