从零到一：在本地部署 DeepSeek Harness，让 AI 智能体真正"上手干活"

本文记录了一次完整的本地部署实践：从环境准备、源码构建，到 Web UI 配置模型、指定工作区，再到让智能体实际执行任务。所有步骤均基于官方文档实测验证。

前言：什么是 DeepSeek Harness？

DeepSeek Harness（简称 dsh）是 DeepSeek AI 开源的智能体框架（Agent Harness），MIT 协议。它和你平时用的"聊天机器人"不同——它不只是对话，而是一个能读写文件、执行命令、调用工具、管理子任务和长期目标的智能体运行环境。

它的核心设计理念是 "一切皆插件"（everything is a plugin）：整个框架由约 220 个小型 npm 包（monorepo，pnpm workspace）拼装而成，底层基于 Cordis 插件框架，通过"配置分层（profile / bundle / patch）"按需组合出不同形态的运行实例：

• web 形态：带浏览器 Web UI 的完整交互环境
• headless 形态：一次性执行任务的命令行智能体
• base 形态：共享核心层，作为所有 profile 的基础

目前项目处于 developer preview（开发者预览） 阶段，版本为 0.1.0-rc.5，迭代很快，官方明确提示"会有破坏性变更"——这既是风险，也是"最早吃到螃蟹"的机会。

环境准备

部署前请确认本机满足以下条件：

小贴士：如果你没有启用 Corepack，先执行 corepack enable；否则 pnpm --version 可能解析不到固定版本。

部署步骤

第 1 步：获取源码

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

第 2 步：安装依赖

pnpm install

这一步不只是装包——postinstall 会自动配置 Lefthook Git 钩子（提交前检查、推送前 typecheck 等）和翻译配对合并驱动。如果你的依赖是从缓存恢复导致钩子缺失，可以手动补一次：

node scripts/install-lefthook.mjs

第 3 步：类型检查（可选但推荐）

新克隆的仓库建议先跑一次：

pnpm run typecheck

通过即说明环境就绪。仓库的 TypeScript 采用 Host / Client 双聚合（tsconfig.host.json + tsconfig.client.json）的 Project Reference 结构，因为宿主端和浏览器端会对 Cordis 的 Context 接口做同名声明合并，拆成两个独立程序才能避免类型冲突——这也是这个仓库一个很有意思的工程细节。

第 4 步：构建

pnpm run build

构建链路为：Host 库（tsc + tsdown）→ Client 库（tsc + tsdown）→ Web 前端（Vite）。生产运行必须先构建出 lib/ 产物和前端 dist/，这一点和"开箱即跑"的脚本项目不同。

第 5 步：启动 Web UI

pnpm dsh web

dsh web 是 dsh --profile web 的别名。首次使用会自动从内置模板初始化 web profile（base + web-app 两个 bundle 的分层组合），然后在默认端口 3080 启动，访问：

http://127.0.0.1:3080

如果端口被占用，可以指定端口：

pnpm dsh --profile web --port 8080

也可以不走源码：直接 npx @deepseek-ai/dsh web，从 npm 安装运行。源码部署的好处是可以随时跟进最新提交、读代码、甚至自己写插件。

首次使用配置

浏览器打开 Web UI 后，只需三步就能让智能体开始工作：

1. 配置模型（LLM 后端）

进入 Settings → Models，在 DeepSeek 卡片中填入你的 API Key 并保存。无需重启服务，配置立即生效。

安全细节值得点赞：密钥是"只写"的——界面回显的是脱敏后的描述符，真实密钥只保存在 $DSH_HOME/.credentials.yaml（Windows 下 $DSH_HOME 默认为 C:\Users\<用户名>\.dsh），设置文件里只留凭据引用。除了 DeepSeek，还支持 Anthropic、OpenAI 等目录内置厂商，以及任意 OpenAI 兼容的自定义端点（自定义 Provider ID 一旦创建即永久，重命名需新建后删除旧的）。

2. 选择工作区

点击 Choose workspace，把启动 dsh 的目录（或你想让智能体操作的任意项目目录）添加并选中。未选择工作区之前，会话输入框是不可用的——智能体默认以启动目录为文件系统根。

3. 开始第一个任务

新建会话，发送一句任务指令，比如：

Summarize this repository and identify its main packages.

你会看到智能体真的在"动手"：读取文件、梳理结构、给出结构化结论。需要审批的操作（按当前权限策略）会弹出确认框，由你拍板。

实际体验：它真的在"干活"

本次部署后我实际执行的任务包括：梳理仓库结构与主要包、核对构建工具链、阅读官方文档等。一个直观的感受是，它具备完整的工具链：

• 文件系统：读、写、编辑、搜索（受沙箱策略约束）
• 命令执行：PowerShell / Bash，可持久化会话
• 外部集成：Web 搜索、MCP 客户端、LSP、子进程管理
• 编排能力：子智能体（subagent）并行委派、工作流（workflow）、长期目标（goal）、任务队列（jobs）
• 上下文管理：会话持久化（JSONL/SQLite）、压缩（compaction）、溢出（spill）

此外，dsh 还支持无 UI 的一次性任务模式：

pnpm dsh --profile headless "summarize this workspace"

适合脚本化调用；以及 ACP（Agent Client Protocol）自动化服务等高级形态，留给后续探索。

架构亮点（为什么值得关注）

1. 一切皆插件：核心、工具、UI 全是 Cordis 插件，通过 dsh.profile 里的 bundles 列表按顺序分层叠加（安装包 bundle → profile 的 cordis.patch.yml → 用户级 $DSH_HOME/cordis.patch.yml → --patch 覆盖），后层覆盖前层，可精确到行级。
2. 开箱可扩展：社区生态用 dsh-plugin 话题发布插件，任何插件包只要在 package.json 里声明 dsh.bundle.patch，pnpm add 后即自动加入分层栈。
3. 工程严谨：200+ 个包的 monorepo 配了完整的 CI 门禁（构建、快照、覆盖率、产物校验、消费者兼容测试），还有大量 scripts/ 生成器与校验器（模块图、工具目录、配置目录、文档图等），防止文档与源码漂移。
4. 安全默认值：文件沙箱、权限审批、凭据脱敏存储、Landlock（Linux）等机制内置。

注意事项与排错

• 开发者预览警告：版本迭代快，升级可能引入破坏性变更，生产使用需谨慎评估。
• 凭据安全：密钥走 UI 或环境变量（DEEPSEEK_API_KEY），永远不要提交真实密钥到仓库。
• 常见报错速查（官方文档）：
  • MISSING_CREDENTIAL：模型页未存密钥，或引用的环境变量未设置
  • UNKNOWN_MODEL：选择已配置的模型，或把缺失模型加到自定义 Provider
  • 拉取模型列表 401：检查密钥；自定义端点若未实现 GET /models，需手动填模型
• 端口冲突：用 --port 指定其他端口。
• 构建先行：改动源码后需重新 pnpm run build，Web UI 才会加载新产物。

结语

从拉取代码到智能体在 Web UI 里跑通第一个任务，整个过程没有遇到文档之外的问题——这本身就是一个好项目的标志。DeepSeek Harness 让我印象最深的是它把"Agent 框架"做成了可组合的乐高积木：不绑定某个模型、不限定某种形态，插件即一切，配置即架构。

对于想深入 Agent 工程、或者想自己写插件扩展能力的开发者来说，这是一个非常值得跟进的项目。开发者预览期正是参与社区、影响方向的好时机——仓库的 Discussions 和 Discord 社区都欢迎反馈。

参考链接：项目主页：https://github.com/deepseek-ai/deepseek-harness 官方文档（Web UI 指南 / 模型配置 / 开发指南）：仓库 docs/ 目录，含中英双语 Cordis 框架：https://github.com/cordiverse/cordis

需要我调整吗？比如：

• 缩短成社交平台推文版（微博/推特风格，300 字以内）
• 改标题风格（更吸引眼球的营销风 / 更技术的严谨风）
• 补充配图占位说明（告诉你在哪个步骤截图）