DeepSeek Harness（dsh）特点与优点

DeepSeek Harness（dsh） 是由 DeepSeek AI 开发的开源 agent harness（智能体框架）。它是驱动 AI 智能体运行的「引擎」：负责大模型调用、工具调用、会话管理、多智能体协作、权限沙箱等底层能力，让开发者可以专注在上层业务逻辑上。

一、总体定位

它不只是「聊天接口的封装」，而是把智能体运行所需的全部能力抽象为可替换的组件，上层无论是 Web 应用、CLI 还是嵌入式 SDK，都通过同一套服务接口运作。

二、核心特点

1. 一切皆插件（Everything is a Plugin）

dsh 最本质的设计：产品中的每一个部分都是插件，包括：

• 模型适配器（ctx.llm）
• 工具注册表（ctx.tools）
• 会话日志（ctx.sessions）
• 智能体循环本身（ctx.agentLoop）
• 文件系统、沙箱、审批、设置、凭据、遥测……

没有需要打补丁的特权核心。开发者要扩展 dsh，只需在旁边挂载一个插件；插件的注册是「可逆副作用」，插件卸载时注册自动回滚。这让整个框架天然可组合、可替换、可热更新。

2. 事件驱动 + 会话日志为单一事实源

• 智能体的每一步（step）和每一轮（turn）都以事件形式记录在**会话日志（Session Log）**里。
• 会话日志是只追加（append-only）的 SessionEvent 流，是会话的单一事实源。
• 模型看到的上下文（LLM message 历史）是从日志派生的（deriveMessages()），而不是另外存一份。
• 好处：fork 会话、恢复会话、生成转写、遥测、持久化全部从同一份日志推导，保证一致性与可重放性。

3. 抽象「能力接缝」（Capability Seams）

dsh 把「可替换能力」建模为接缝（seam），每种接缝由三部分组成：

• 服务定义（Service Definition）：声明接口
• 服务提供方（Service Provider）：实现接口（往往有多个可选实现）
• 消费者（Consumer）：使用接口（通常是对模型暴露的工具）

这种设计使得"换一个提供方就改变整个产品行为"。例如：

• 文件系统 / 子进程提供方共享同一执行世界，把沙箱指向远端，Bash、PTY、LSP 一起迁移，无需为每个功能分别适配。
• Subagent 提供方可以是一个全新子智能体、也可以是委托到另一个产品的会话。

4. 完善的工具调用流水线

工具不是简单的"函数调用"，而是经过一条受保护的执行管线：

tools/pre-execute（允许/拒绝/询问）
  → 单调 guard（只能进一步缩减权限）
  → tools/execute（调度包装：超时、重试、指标）
  → tools/post-execute（审查/替换/补充结果）
  → finalizeContent
  → tools/result（不可变结果）

• 工具参数是无损 JSON、执行前冻结，保证历史、审计、UI、执行看到同一份参数。
• 区分并行调用与独占调用的执行模式。
• 提供类型完善的 defineTool DSL，统一参数与输出 schema。

5. LLM 流式与适配器抽象

• 统一 StreamChunk 流式协议（文本/推理/工具调用分块）。
• 定义严格的 adapter contract（适配器契约），任何模型提供方（OpenAI 兼容、DeepSeek、pi-ai 等）都能接入。
• 统一错误归一化（LlmFailure）、重试策略（ResolvedRetryPolicy）、Token 用量统计、上下文窗口溢出识别。

6. 子智能体（Subagent）与委托

dsh 支持把任务委托给子智能体：

• 一次性（one-shot）委托：启动一个子智能体运行并返回结果。
• 可继续（continuable）委托：子智能体是有持久会话的，可后续追问、中断、回报。
• 多提供方：spawn / fork / ACP / 某厂商 CLI / SDK 等多种后端，同一接口。
• 支持结构化输出 schema、委托深度限制、工具过滤、个性化 persona 等能力开关。

7. 安全与权限体系

• 沙箱（sandbox）：每会话策略解析与进程约束。
• 审批（approval）：需要审批的操作进入一次性审批流程。
• 工具 guard：单调缩减权限，一旦拒绝无法被后置监听器撤销。
• 隔离 realm：服务/能力可按作用域隔离，agent 预设可组合不同能力集。

8. 后台任务 / 工作流 / 计划

• ctx.jobs：后台任务运行时（job_* 工具收集或停止任务）。
• workflow：支持大规模多智能体编排脚本。
• plan mode：计划模式，先规划后执行。

9. 丰富的周边子系统

内置的周边能力覆盖工程化所需：

• Web UI / Web 访问（web search & fetch）
• 文件系统编辑、Bash / 终端 / 子进程 / LSP / Code Runtime
• 技能（skills）、跨会话引用（session reference）、结构化检索（session query）
• 凭据管理（凭据引用，值不进配置）、设置分层、遥测脱敏
• 压缩（compaction）、token 计量、持久化（JSONL / SQLite）

三、主要优点

1. 高度可扩展，无痛点打补丁
   没有特权核心需要改源码，扩展方式统一为"挂载插件"，注册可逆、可回滚，扩展即配置。

2. 可组合、可替换
   所有能力都是接缝（seam），换一个提供方即可整体改变行为，例如切换模型、切换沙箱、切换子智能体后端，改动都在配置层完成。

3. 一致的会话模型，可重放、可恢复
   单一事实源（append-only 会话日志）+ 派生上下文，保证 fork / resume / 转写 / 遥测的一致性，故障后可从日志恢复。

4. 工程化程度高、质量意识强

   • 运行时不变式（invariants）检查。
   • 类型安全：品牌化 ID、…Map → 派生联合 模式，扩展通过声明合并完成且不破坏编译期检查。
   • 文档详细、API 自动化生成并校验漂移。

5. 面向真实工程任务的完整工具链
   不只是"会说话"，Agent 能读写文件、跑命令、开终端、做代码导航、委托子智能体、管理后台任务、规划执行，接近一个真正的"编程代理"环境。

6. 安全与可控性优先
   沙箱、审批、权限 guard、作用域隔离、realm 隔离层层把关，适合运行有一定风险的操作。

四、注意事项 / 局限

• 当前处于开发者预览阶段，API 在快速迭代，不保证向后兼容（THERE WILL BE BREAKING CHANGES）。
• 架构和学习曲线较陡：深入定制需理解 Cordis 运行时与事件模型。
• 特性集中在 framework/TypeScript 生态，若要二次开发需具备 TS 与源码基础。

五、快速上手

# 最简单的运行方式（需已安装 Node.js）
npx @deepseek-ai/dsh web

# 或从源码构建运行
git clone deepseek-harness 仓库
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

启动后打开 Web UI（默认地址为本地 3080 端口），在 Settings → Models 填入 DeepSeek API Key，选择工作区即可开始对话或执行任务。

参考

• 官方仓库：DeepSeek Harness GitHub 仓库（deepseek-ai/deepseek-harness）
• Cordis：Cordis 项目（cordiverse/cordis）
• 论文：A Programming Paradigm for Spatiotemporal Composability