DeepSeek Harness部署和应用

创新境界

690人浏览 · 2026-08-17 10:40:21

创新境界 · 2026-08-17 10:40:21 发布

一、它是什么

DeepSeek Harness（命令行工具名 dsh）是由 DeepSeek AI 开发的开源智能体框架（agent harness），MIT 协议开源。它的作用可以理解为：提供一个可深度定制、可组合的运行时，让智能体（agent）能够调用模型、执行工具、读写文件、跑 shell、委派子代理、与人类协作，并把这些能力组织成一个统一、可替换的系统。

核心仓库地址：github.com/deepseek-ai/deepseek-harness，npm 包前缀为 @deepseek-ai/dsh-*。

关键现状：目前处于「开发者预览（developer preview）」阶段，迭代非常快，官方明确声明会有破坏兼容性的变更，不建议作为稳定依赖使用。

二、核心设计哲学：一切皆插件（Everything is a plugin）

这是理解 DeepSeek Harness 最重要的一句话。

它构建在 Cordis 框架之上（vendored 内嵌在 vendor/ 目录）。Cordis 的设计目标见论文《A Programming Paradigm for Spatiotemporal Composability》。

在这种架构下：

模型适配器、工具注册表、会话日志、甚至 agent loop 本身，全都是插件；
插件向一个共享的 Context 贡献三样东西：服务（services）、类型化事件（typed events）、可逆副作用（reversible effects）；
任何注册都是一个副作用（effect），插件卸载时自动撤销（dispose）；
不存在需要打补丁的特权内核——你要扩展 dsh，就是把一个插件挂载到其他插件旁边，而不是去改核心代码。

这意味着产品的每一部分都可以通过配置替换，扩展性极强。

三、启动时的组装：Profile 与 Bundle

一个正在运行的 dsh，本质上是一棵按顺序叠加出来的「插件树」。

Profile（配置档案）

存放在 Harness home 中的具名组装；
列出自己叠放的 bundle 列表，存放树外插件，并保存用户自己的 cordis.patch.yml；
内置 web 和 headless 两个模板。

Bundle（组合包）

Cordis 配置项 + 其挂载代码的分发格式；
它插入的内容始终可以被上层 patch（补丁）覆盖。

叠加顺序

空条目列表之上，按顺序应用：各 bundle → profile 的 cordis.patch.yml → home 级 patch → 命令行 --patch overlay。

查看你机器实际启动的配置树：

复制

dsh --profile web --dump-config

打印出的任何一条都可以被你自己的 patch 替换。

四、核心包（产品 API 主干）

包	职责	`ctx` 键
`core/session`	仅追加的 `SessionEvent` 日志 + 内存存储	`ctx.sessions`
`core/system-prompt`	提示词片段与工具 schema 组装	`ctx.systemPrompt`
`core/tools`	作用域化工具注册表 + 带把关的执行流水线	`ctx.tools`
`core/agent`	`Agent` 接口、活跃 agent 注册表、`agent/*` 事件	`ctx.agents`
`core/agent-loop`	实现 Agent 接口的默认驱动器	`ctx.agentLoop`
`core/scope`	按 agent 划分作用域的注册原语	库，无键
`llm/llm`	消息/流式词汇表 + 模型适配器 seam	`ctx.llm`

五、事件系统（扩展点）

事件是 dsh 的核心扩展点，分三类：

会话事件（Session events）：追加到日志、通过 session/event 广播的持久事实——需要在重载后仍存在时用它。
Agent 事件（agent/*）：携带活跃 Agent（inbox、step、status、request、validation、continuation）——观察/拦截进行中的工作。
能力事件（fs/*、tools/*、telemetry/*）：给某个 seam 附加策略和适配器，无需导入循环。

事件又有两种语义：waterfall（瀑布式，监听器必须调 next() 才继续委托）和 serial（串行）。

六、轮次流程（Turn flow）

这是智能体运行时的核心节奏：

step（步骤）：一次模型请求 + 它调用的工具。
turn（轮次）：零或多个 step，从领取首条输入开始，到不再欠任何工作时关闭。

复制

turn/start
  → claim 输入 + 排队消息
  → 组装 prompt 片段 + 工具 schema
  → agent/pre-step（可改写或拒绝消息）
     → step/start → 记录 user/message
     → 从日志推导模型历史
     → agent/request → llm/stream → assistant/chunk* → assistant/message
     → tool/call* → tools/pre-execute → execute → post-execute → tool/result*
     → step/end
     → 工具还欠一次请求 / 新输入到达 → claim → 下一步骤
  → agent/turn-stopping
turn/end

七、会话日志（Session log）

会话日志是模型所见上下文的唯一来源：

deriveMessages() 从日志投影出模型历史；
原始 assistant/chunk 事件保证回放和 UI 保真；
fork、恢复、transcript、遥测、持久化全部派生自这条事件流。

核心不变量：「模型可见 ⟺ 已记录」——任何到达模型请求的内容都必须能从日志重建，新增模型可见输入就必须新增一个会话事件。

八、能力 Seam（可替换能力的抽象）

Seam 是一项可替换能力，由三种角色构成：

Service Definition：声明接口；
Service Provider：实现接口；
Consumer：使用接口（通常是面向模型的工具）。

单一角色不构成 seam；添加能力必须三者一起设计。seam 的价值在于：替换一个 provider 就能改变整个产品。例如把文件系统和子进程 provider 指向远程沙箱，Bash、PTY、LSP 会一起搬过去，无需为每个能力写专用分支。

九、扩展点速查（新行为放哪里）

目标	机制
添加模型提供方	在 `ctx.llm` 注册适配器
添加模型能力	在 `ctx.tools` 注册，schema 加入 prompt 组装
添加 shell 执行	注册 `ctx.shell` 后端
添加持久终端	注册 `ctx.terminals` 后端 + 终端工具
添加文件系统访问/策略	注册 `ctx.fs` provider 或监听 `fs/*`
限制进程	用 `ctx.sandbox` 后端（bwrap/Landlock/Seatbelt）
后台工作	注册 `ctx.jobs`，`job_*` 工具控制
委派子代理	subagent capability
添加人类命令	注册 `ctx.commands`
拦截请求/工具/轮次	用 `agent/` / `tools/` 事件
fork 活跃会话	`ctx.sessions.fork(...)`

十、仓库结构一览

仓库是 pnpm monorepo，包放在 packages/<group>/<pkg>/，命名 @deepseek-ai/dsh-<pkg>。主要分组（组 README 负责包↔ctx 键映射）：

core：会话、提示词、工具、agent、agent-loop 主干
api / typert：远程 BFF 装配 + RPC 网关；类型图生成与运行时注册表
llm：模型抽象 + DeepSeek provider 适配器
shell / subprocess / terminal / code-runtime / sandbox / fs / lsp：执行与文件能力
web：Web 搜索/抓取能力 + 工具
subagent / workflow / jobs / goal / plan / todo / schedule：编排与协作
session / session-query / storage / attachment / spill / compaction：持久化与上下文
skill / preset / hooks / extensions / mcp：技能、组装、钩子桥接、运行时自修改
interaction：审批、权限、命令、ask-user
acp / sdk：Agent Client Protocol 自动化服务器 + JSON-RPC SDK
client / host：Web GUI 的浏览器侧与宿主侧
bundle / boot：可安装补丁层 + 启动粘合
examples / test-support / util：示例、测试基础设施、零依赖工具

此外还有 python/（Python SDK）、native/（Landlock 原生插件）、website/（VitePress 文档站）、docs/（架构文档 + 生成目录 + postmortem）、.agents/（Agent 工作流与决策记录）。

十一、技术栈与工程规范（简述）

语言：TypeScript，strict: true + noImplicitAny，全 ESM（"type": "module"）；
构建：tsc 产 lib/types，tsdown 打包运行时；分为 host 与 client 两个编译面（face）；
测试：Vitest 单元测试、e2e（需 DEEPSEEK_API_KEY）、无密钥 snapshot 回放、Web 测试、覆盖率门禁（packages/*/*/src 100%）；
质量门禁：oxlint、knip、publint、jscpd（重复代码检测）、大量 verify-* 脚本（导出 JSDoc、包不变量、文档预算、md 链接等）；
文档：双语（中/英），严格分层（教程 vs 参考），「一个事实一个归属」；
安全：凭据经 credentials seam 管理，沙箱后端支持 bwrap / Landlock / Seatbelt。

十二、一句话总结

DeepSeek Harness 是一个基于 Cordis 的「一切皆插件」智能体运行时：模型、工具、文件、shell、沙箱、持久化、编排乃至 agent loop 本身都是可替换、可组合的插件，通过事件和 seam 暴露扩展点，并以会话日志作为模型上下文的唯一事实来源。它同时提供 Web GUI、headless、ACP 与 Python SDK 多种运行形态，目前处于快速迭代的开发者预览阶段。

十三、AI Agent可观测性：破解多步推理黑盒

1. 引言：为什么AI Agent需要可观测性？

AI Agent从单步问答到多步推理的演进
黑盒推理带来的调试、信任与部署挑战
可观测性在AI系统生命周期中的核心价值

2. AI Agent可观测性的核心维度

执行轨迹（Execution Traces）：完整记录Agent的思考、决策、工具调用序列
内部状态（Internal States）：思维链、中间结果、置信度、注意力分布
资源消耗（Resource Consumption）：Token使用、API调用、计算时间、成本
决策依据（Decision Rationale）：为什么选择这个工具？为什么得出这个结论？
外部交互（External Interactions）：API调用、数据库查询、文件操作、用户反馈

3. 多步推理黑盒的破解技术栈

结构化日志与事件流：从无序日志到语义化事件
思维链（Chain-of-Thought）可视化：将内部推理过程外部化
向量化记忆检索分析：理解Agent如何利用历史上下文
工具调用依赖图：映射复杂任务的工作流
实时监控与告警：异常检测、性能瓶颈、安全风险

4. 可观测性基础设施设计模式

事件溯源（Event Sourcing）模式：不可变事件流作为唯一事实来源
上下文注入（Context Injection）：在Agent生命周期中嵌入观测点
标准化遥测接口：OpenTelemetry、Prometheus、Jaeger集成
分层存储策略：热数据、温数据、冷数据的成本优化
实时流处理管道：Kafka、Flink、Spark Streaming应用

5. 实践案例：在DeepSeek Harness中实现可观测性

利用Cordis插件系统注入观测点
会话日志（Session Log）作为可观测性基础
事件系统（Event System）的扩展：添加自定义遥测事件
Seam模式下的可观测性提供者（Observability Provider）
可视化仪表板与调试工具集成

6. 可观测性驱动的Agent优化循环

数据收集：全面、结构化、低开销的遥测
分析洞察：模式识别、异常检测、性能分析
反馈优化：提示工程改进、工具选择优化、工作流重构
A/B测试与实验：基于观测数据的科学决策
持续部署与监控：闭环优化系统

7. 挑战与前沿方向

隐私与安全：敏感数据的脱敏与合规处理
性能开销：观测系统对Agent响应时间的影响
多模态Agent观测：图像、音频、视频推理的可解释性
联邦学习环境下的可观测性：分布式、隐私保护的观测方案
自动化根因分析（RCA）：AI诊断AI故障

8. 工具与生态系统

开源可观测性工具：LangSmith、Weights & Biases、MLflow、Arize AI
商业平台：Datadog AI Monitoring、New Relic AI Observability
标准化倡议：OpenTelemetry for AI/ML、MLOps可观测性标准
社区最佳实践与案例研究

9. 实施路线图建议

阶段一：基础日志与指标：关键路径埋点、基础仪表板
阶段二：深度推理追踪：思维链可视化、工具调用分析
阶段三：预测性监控：异常预测、性能预警、自动扩缩容
阶段四：自主优化：基于观测数据的自动调优与修复

10. 总结：从黑盒到玻璃盒的演进

可观测性不仅是调试工具，更是AI Agent成熟度的核心指标
透明、可信、可解释的AI系统是规模化部署的前提
可观测性驱动的开发范式：观测优先（Observability-First）设计
未来展望：自我观测、自我诊断、自我优化的自主Agent系统

十四：安装 Node.js 与 pnpm 指南

下面分别说明 Windows 和 macOS 的安装方法。推荐顺序：先装 Node.js（自带 npm），再用 npm 安装 pnpm。

一、Windows 安装 Node.js

方法 1：官方安装包（最简单，推荐新手）

打开官网 https://nodejs.org
首页会显示两个版本：
- LTS（长期支持版）：推荐日常开发使用
- Current（最新特性版）：尝鲜用
点击 LTS 版本的 Windows Installer（.msi），下载后双击运行
一路点击 Next，保持默认设置即可（安装程序会自动把 Node 加入系统 PATH 环境变量）
安装完成后，重启终端（PowerShell / CMD），然后验证：

powershell

复制

node -v
npm -v

方法 2：使用 winget（Windows 包管理器）

Windows 10/11 自带 winget，在 PowerShell 中执行：

powershell

复制

winget install OpenJS.NodeJS.LTS

方法 3：使用 nvm-windows（需要切换多个 Node 版本时）

适合需要在多个 Node 版本之间切换的开发者：

下载 https://github.com/coreybutler/nvm-windows/releases 中的 nvm-setup.exe
安装完成后，重启终端，执行：

powershell

复制

nvm install lts          # 安装最新 LTS 版本
nvm use lts              # 使用该版本
nvm list                 # 查看已安装版本

提示：nvm 和 nvm-windows 是两个不同的项目，Windows 请使用 nvm-windows。

二、macOS 安装 Node.js

方法 1：官方安装包（最简单）

打开 https://nodejs.org
下载 LTS 版本的 macOS Installer（.pkg）
双击 .pkg 文件，按向导完成安装
安装后重新打开终端验证：

bash

复制

node -v
npm -v

方法 2：Homebrew（推荐，方便统一管理）

先确认已安装 Homebrew（https://brew.sh），然后：

bash

复制

brew install node

升级或卸载也很方便：

bash

复制

brew upgrade node   # 升级
brew uninstall node # 卸载

方法 3：nvm（需要切换多个 Node 版本时）

bash

复制

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重启终端后安装并使用 LTS
nvm install --lts
nvm use --lts
nvm alias default node   # 设为默认版本

方法 4：fnm（更快的版本管理器）

bash

复制

brew install fnm
fnm install --lts
fnm use lts

三、安装 pnpm

pnpm 官方提供三种安装方式，任选其一即可（三者选一，不要重复安装）。

方式 1：使用 npm 全局安装（最通用）

bash

复制

# Windows（PowerShell/CMD）与 macOS 通用
npm install -g pnpm

方式 2：使用 Corepack（Node 16.13+ 自带，官方推荐）

Node.js 自带 Corepack，可以直接启用 pnpm：

复制

corepack enable pnpm

说明：Corepack 会根据项目 package.json 里的 packageManager 字段自动使用对应的 pnpm 版本。

方式 3：独立安装脚本

macOS / Linux：

bash

复制

curl -fsSL https://get.pnpm.io/install.sh | sh -

Windows（PowerShell）：

powershell

复制

iwr https://get.pnpm.io/install.ps1 -useb | iex

四、验证安装

安装完成后，在终端执行以下命令，能正确显示版本号即表示安装成功：

bash

复制

node -v     # 例如 v22.x.x
npm -v      # 例如 10.x.x
pnpm -v     # 例如 9.x.x

五、常见问题

问题	解决方法
安装后命令提示「不是内部或外部命令」	重启终端；若仍无效，检查 Node 是否已加入 PATH 环境变量
macOS 提示 `permission denied` 运行脚本	用 Homebrew 或 Corepack 安装，避免权限问题
全局安装 pnpm 报 EACCES 权限错误（macOS）	改用 Corepack，或配置 npm 全局目录
需要切换 Node 版本	Windows 用 nvm-windows，macOS 用 nvm 或 fnm

十五、前置环境要求

依赖	版本要求
Node.js	`^22.19.0` 或 `>=24.0.0`
pnpm（源码安装时需要）	`11.7.0`
包管理器	pnpm workspaces

环境安装可参考上一个问题（Windows / macOS 装 Node 和 pnpm）。注意：Node 版本必须满足 22.19 以上或 24 以上，太旧或太新但不匹配都会出问题。

二、安装方式一：直接通过 npm/npx（最简单，推荐）

这是官方 README 的首选方式，无需克隆仓库、无需构建：

bash

复制

npx @deepseek-ai/dsh web

首次运行会自动下载 @deepseek-ai/dsh 包；
该命令启动 Web UI，默认地址 http://127.0.0.1:3080；
终端会打印实际访问地址，浏览器打开即可。

三、安装方式二：从源码安装（用于开发或定制）

如果你需要改代码、写插件、或跟踪最新改动，从源码跑：

bash

复制

# 1. 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 安装依赖（pnpm workspaces）
pnpm install

# 3. 构建（tsc 产类型 + tsdown 打包运行时，并构建 Web 前端）
pnpm run build

# 4. 启动 Web UI
pnpm dsh web

如果只跑一次性任务（headless），也可以从源码直接执行：

bash

复制

pnpm dsh --profile headless "你的任务描述"

四、配置模型（API Key）

Web UI 启动后，必须先配置模型密钥，否则无法发送请求。

方式 1：Web UI 图形界面（推荐）

打开 http://127.0.0.1:3080；
进入 设置 → 模型；
在 DeepSeek 卡片填入 API 密钥并保存；
模型路由立即生效，无需重启服务器。

要点：

密钥是只写的，保存后页面只显示脱敏描述符，不会回显明文；
密钥实际存储在 $DSH_HOME/.credentials.yaml，settings 只保留凭据引用；
也支持添加 Anthropic / OpenAI 等目录提供方，或「添加自定义提供方」接入公司网关、自建服务器等 OpenAI 兼容端点。

方式 2：环境变量

真实 API 测试和 demo 会读取环境变量：

bash

复制

export DEEPSEEK_API_KEY="sk-你的密钥"
export DEEPSEEK_BASE_URL="https://api.deepseek.com"   # 可选，默认官方地址

也可以在项目根目录放置 .env 文件（切勿提交到 git）。

五、选择工作区

在 Web UI 中：

点击 选择工作区；
添加你启动 dsh 时所在的项目目录（dsh 进程把启动目录作为默认文件系统位置）；
选中该工作区。

注意：选中工作区之前，会话输入框不可用。

选好后就可以发起任务，例如：

Summarize this repository and identify its main packages.

agent 可以读取/编辑工作区文件、运行命令、委派子代理、维护计划；当操作触发权限审批时，Web UI 会先询问你。

六、其他运行形态

DeepSeek Harness 支持多种部署形态，不止 Web UI：

形态	命令	说明
Web UI	`dsh web`	默认 `127.0.0.1:3080`，带图形界面
Headless	`dsh --profile headless "任务"`	一次性运行器，完全不带服务器
ACP 自动化	`pnpm run demo:acp`	Agent Client Protocol 服务器
Python SDK	`python/`	Python 接口调用

七、关键环境变量 / 目录速查

变量 / 目录	作用
`DEEPSEEK_API_KEY`	DeepSeek API 密钥
`DEEPSEEK_BASE_URL`	可选，自定义 API 地址
`$DSH_HOME`	Harness 数据目录（profile、凭据、settings 等）
`$DSH_HOME/.credentials.yaml`	凭据存储位置
`$DSH_HOME/settings.yaml`	用户设置（可手动配置 provider）
`$DSH_HOME/cordis.patch.yml`	用户自定义插件树补丁

八、安装后验证

启动 Web UI 后，确认：

终端打印了访问地址（默认 http://127.0.0.1:3080）；
浏览器能打开页面；
设置 → 模型 已保存 API 密钥；
已选择工作区，输入框可用；
发送一条简单消息能正常得到模型回复。

九、常见问题

问题	原因 / 解决
`MISSING_CREDENTIAL`	未配置密钥：去模型页存密钥，或提供被引用的环境变量
`UNKNOWN_MODEL`	选择已配置的模型，或给自定义 provider 添加缺失模型
获取模型返回 401	密钥错误，检查 API Key
Node 版本报错	确认 Node 满足 `^22.19` 或 `>=24`
图片请求被拒	DeepSeek 自身 chat 路由是纯文本的，不支持图片输入
端口被占用	用 `dsh web` 的帮助参数查看自定义端口选项