一、它是什么

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。

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

sh

复制

dsh --profile web --dump-config

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

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

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

五、事件系统（扩展点）

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

  1. 会话事件（Session events）：追加到日志、通过 session/event 广播的持久事实——需要在重载后仍存在时用它。
  2. Agent 事件（agent/*）：携带活跃 Agent（inbox、step、status、request、validation、continuation）——观察/拦截进行中的工作。
  3. 能力事件（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：官方安装包（最简单，推荐新手）

  1. 打开官网 https://nodejs.org
  2. 首页会显示两个版本：
    • LTS（长期支持版）：推荐日常开发使用
    • Current（最新特性版）：尝鲜用
  3. 点击 LTS 版本的 Windows Installer（.msi），下载后双击运行
  4. 一路点击 Next，保持默认设置即可（安装程序会自动把 Node 加入系统 PATH 环境变量）
  5. 安装完成后，重启终端（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 版本之间切换的开发者：

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

powershell

复制

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

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

二、macOS 安装 Node.js

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

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

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 图形界面（推荐）

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

要点：

  • 密钥是只写的，保存后页面只显示脱敏描述符，不会回显明文；
  • 密钥实际存储在 $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 中：

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

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

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

Summarize this repository and identify its main packages.

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

六、其他运行形态

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

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

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

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

八、安装后验证

启动 Web UI 后，确认：

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

九、常见问题

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

# AI
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

AI Agent 对比和选型

avatar AI Agent技术社区

2026企业微信AI Agent实测：7款技术方案对比

会话审计、敏感词管理、聊天质检、敏感行为识别、舆情、属性、词频及竞品分析覆盖服务风险；线索公海、客户、产品、商机、订单、回款、发票和业绩目标则连接销售全过程。快创助手负责快速建运营任务，策略生成把目标拆成方案，智能客服回答系统使用咨询，数据报表处理自然语言查数，AI洞察联合标签、订单和会话分析客户。我们设计了客户筛选、订单关联、销售交接、会话质检和异常恢复任务，配合技术访谈与行业公开资料复核。准备

avatar AI Agent技术社区
cover

如何构建 AI Agent Harness 2.0，让 AI Agent 比 99% 的开发者更工程化

avatar AI Agent技术社区