DeepSeek Harness

一、DeepSeek Harness 的核心设计理念“一切皆插件”具体指什么？

1. 理念内涵

“一切皆插件”是 DeepSeek Harness 最醒目的设计原则，指 Agent 的各项能力——模型、工具、技能（Skill）、会话、沙箱、存储、执行循环、调度乃至用户界面——都被拆分为可独立安装、卸载和组合的模块，而非写死在某个不可改动的核心程序里。开发者无需改动框架源码，仅通过配置文件即可选择、替换或扩展任一能力。

2. 无特权内核

官方架构文档明确表达：框架中不存在一个需要被反复打补丁的“特权核心”。扩展系统的正常方式，是在已有插件旁边挂载新的插件。模型、工具、存储、界面等所有能力都由插件提供，并通过 Cordis 的服务与事件机制彼此协同。

3. 与 MCP、Skill 的分工

这一理念与 MCP、Skill 解决的是不同层面的问题：MCP 负责统一外部工具的连接方式，Skill 提供某类任务的操作方法，而 Harness 负责把模型、工具、Skill、会话、存储、循环、沙箱和界面组织起来，推动任务持续运行。可以理解为 Prompt 说明“这次要做什么”、Skill 说明“这类事通常怎么做”、MCP 说明“可以连接哪些外部工具”、Harness 则让以上部分在一段完整任务中协同运作。

二、DeepSeek Harness 底层依赖的 Cordis 内核是什么？

1. 来源与定位

Cordis 是 Harness 底层的开源 JavaScript 插件框架（元框架），其内核源自聊天机器人框架 Koishi，由北京大学与 DeepSeek-AI 的研究者就其编程范式发表了正式论文。Cordis 内核本身不负责搜索网页或修改文件，它主要管理插件如何加载、卸载、声明依赖，以及通过服务与事件彼此沟通。

2. 核心机制

Cordis 的设计围绕若干关键概念展开：

• 插件（Plugin）：实现服务的对象，其生命周期由 Cordis 统一管理
• 上下文（Context）：服务的容器，每个服务占据稳定的 ctx.xxx 键位，其他插件通过键名查找服务而非导入具体实现
• 依赖注入（inject）：插件通过 inject 声明自身依赖，加载顺序由服务依赖关系自动决定
• 类型化事件（Typed Events）：支持 emit、waterfall、parallel、serial 四种分发模式
• 可逆副作用（Reversible Effects）：插件对系统所做的修改可被追踪并在卸载时自动撤销

3. 对框架的意义

正是这套机制，让 Harness 成为真正的“可插拔”平台——开发者可以随时通过替换一个插件来改变整个产品的行为，而无需修改核心代码。例如更换模型适配器，只需在配置中调整对应键位，其他插件无需感知底层模型是否变化。

三、DeepSeek Harness 的插件是如何实现加载、卸载与彼此通信的？

1. 服务发现而非直接导入

在 Harness 中，每个插件实现一个 Service 接口，并在上下文对象上占据一个稳定的键位（如 ctx.tools、ctx.llm、ctx.sessions）。其他插件通过键名查找所需服务，而不是直接导入某个具体实现。这使得替换模型适配器就像修改一个配置值一样简单。

2. 能力接缝（Capability Seam）

Harness 的灵活性集中体现在“能力接缝”设计上。一个接缝包含三个角色：

• Service Definition：声明接口
• Service Provider：提供一个或多个实现
• Consumer：面向模型的工具（消费方）

以 Shell 能力为例，dsh-shell 定义接口，dsh-bash-local 与 dsh-bash-sandbox 提供不同实现，dsh-tool-bash 则是模型可见的消费方。由于文件系统与进程提供方共享同一执行世界，把它们指向远程沙箱，Bash、PTY 与 LSP 便会一并迁移，从而实现“替换一个提供方即可改变整个产品行为”。

3. 热插拔与热重载

得益于“可逆副作用”特性，Cordis 能够追踪并自动回收插件注册时产生的副作用，因此安装或卸载插件无需重启整个系统。开发者修改某个插件的代码后，系统可自行重新加载，避免了“改一行代码就要重启整个框架”的等待成本。

四、DeepSeek Harness 的“可逆副作用”机制解决了什么问题？

1. 传统插件框架的清理难题

在传统插件框架中，插件对系统做的修改（如注册工具、修改模型 Prompt、向存储写入数据）往往需要插件自己在卸载时“清理”。但许多插件作者并不编写清理逻辑，导致系统随着插件反复装卸而越来越“脏”，甚至出现状态残留引发的难以排查的问题。

2. 框架层面的自动回滚

Cordis 在框架层面解决了这一问题：所有插件的效果都是“可逆的”，当插件被卸载时，系统会自动回滚它曾经做过的全部改动。这种“可逆副作用”让插件的装卸变得安全、干净，开发者不必为每个插件手写卸载逻辑。

3. 支撑真正的热插拔

可逆副作用是 Harness 实现“安装/卸载插件无需重启”的关键前提。它让插件化不只是口号，而是具备了可靠的工程基础——开发者可以放心地在运行时增删能力，而不用担心系统状态无法恢复。

五、DeepSeek Harness 的 Agent Loop 是如何推动任务执行的？

1. Session、Turn 与 Step

Harness 中有一套具体的执行循环，负责推动任务的生命周期，可先按三个层次理解：

• Session（会话）：一段连续工作的会话，承载从开始到结束的完整上下文
• Turn（轮次）：用户交给 Agent 的一轮任务，在收到首条输入时开启，在不再欠下任何工作时关闭
• Step（步骤）：Agent 为完成这一轮任务采取的一次具体行动，通常包含一次模型请求和它调用的所有工具

2. 轮次与步骤的流转

一次完整的“思考与行动”流程大致如下：用户输入进入后，经过 agent/pre-step 前置把关（可改写或拒绝），随后进入步骤循环——准备请求、流式推理、接收助手消息、工具执行前拦截、执行工具、执行后处理；若工具仍有“欠账”（如需要继续行动），则循环执行下一步骤，直到轮次关闭。Harness 管理的不是一次回答，而是一段持续执行的过程。

3. 事件类型

轮次控制层涉及三类事件：会话事件（持久化）、Agent 事件（实时）与能力事件（接缝）。工具执行层则覆盖工具调用、执行前把关、执行工具与返回结果等环节，可调用文件读写、命令执行、网络搜索、子智能体等约 40 个工具。

六、DeepSeek Harness 提供了哪几种运行模式？

1. 标准模式（Standard）

提供较完整的 Coding Agent 能力，包括文件编辑、Shell 执行、文件与网页搜索、技能（Skill）、计划与目标、Subagent 调度与工作流等，是日常写代码、做文档、跑自动化任务的默认选择。

2. 代码 / PTC 模式（Code / Programmatic Tool Calling）

模型可以用一段 TypeScript 程序组合多次工具操作，把多轮工具调用编排进同一段生成代码中，中间数据保留在执行环境里，从而减少模型与工具之间反复来回的次数，在处理超长复杂任务时有助于节省 Token 消耗。

3. 极简模式（Minimal）

只保留持久 Bash 和文件编辑工具，适合在较少环境干扰下测试模型，或构建精简的“双工具”编码 Agent，常用于模型性能基准测试。

4. 创造模式（Creator）

用于检查当前运行时、试验插件、在内存中测试 Cordis 插件，并把它们组合成自定义的 Agent 预设（preset）。它甚至允许通过自然语言让 Agent 为应用增添新插件，是面向高阶玩家与框架二次开发的模式。

七、DeepSeek Harness 的会话日志记录了哪些内容？

1. 追加式记录原则

Harness 的一个设计原则是“凡是抵达模型的内容，都必须能从日志重建”。会话日志采用仅追加（append-only）设计，是模型所见上下文的唯一来源，deriveMessages() 从中投影出完整的模型历史，保证回放与界面保真。

2. 记录的具体内容

日志会按来源记录以下信息：

• 系统提示词（System Prompt）
• 用户消息
• 上下文注入
• 模型的思维链与输出
• 工具调用及其返回结果
• Subagent 调度事件
• 每一次上下文注入与其他运行事件

3. 派生能力

会话的恢复（resume）、分叉（fork）、transcript 导出、遥测与持久化都派生自这同一份事件流。持久化支持 jsonl 和 sqlite 两种后端，可支持断点续跑、会话投影缓存与查询。原始 assistant/chunk 事件则保证回放与 UI 的一致性。

八、DeepSeek Harness 如何管理上下文与会话记忆？

1. 上下文即日志投影

Harness 的上下文并非临时拼接，而是从会话日志中投影而来。模型每一轮看到的系统提示、历史消息、工具结果与注入信息，都由日志统一派生，确保“模型可见即可记录”，避免上下文与日志两套口径不一致。

2. 会话的恢复、分叉与回放

基于同一份事件流，用户可以对会话进行恢复、分叉与回放：当 Agent 在某一步走错时，可以回到较早的节点检查它当时看见了什么、调用了什么工具，并从该节点分叉出另一条执行路线，而不必只看最终失败结果。

3. 工作区与凭据隔离

工作区（Workspace）机制将智能体的可写范围限制在用户手动注册的目录内；API Key 等凭据通过 ~/.dsh/.credentials.yaml 等独立位置存储，Web UI 的设置界面只显示“已配置”占位符而不回显密钥，避免凭据进入对话上下文或泄露到日志中。

九、DeepSeek Harness 的沙箱机制如何保障执行安全？

1. 分档沙箱策略

Harness 的沙箱按文件影响范围分为三档：

• 只读：所有文件可见，但无法修改任何内容
• 工作区可写（出厂默认）：只能修改用户注册的工作区文件夹及系统临时区，无法触及工作区之外的内容
• 完全放开：不设文件限制，切换时会弹出二次确认

2. 系统级隔离实现

底层提供原生沙箱组件，在不同操作系统上采用各自的隔离方案：Linux 使用 bubblewrap / Landlock 路径，macOS 使用 Seatbelt，Windows 通过受限令牌（restricted-token）与 ACL 实现与 POSIX 一致的权限模型。

3. 沙箱的能力边界

需要客观看待的是，当前沙箱模式主要描述的是“文件系统效果”，并不等同于完整的网络隔离或进程可见性隔离。官方文档明确列出其限制：沙箱策略接口尚未完整覆盖网络、系统调用、设备与凭据。若要获得容器、微型虚拟机或远程执行级别的隔离，需要额外替换或增加相应实现。

十、DeepSeek Harness 的权限控制是如何设计的？

1. 权限预设与审批策略

Harness 提供可组合的权限预设（permission-presets）与审批策略。以高层预设为例，workspace-write 在工作区内执行、升级操作需审批，是常规默认档；danger-full-access 则不做限制、从不询问，提供最大自主性也意味着最大的本地影响范围。

2. 一次性审批与失败关闭

审批服务围绕狭窄的决策设计，如“允许一次”“拒绝”“取消”或“不可用”。当需要审批却不存在审批处理器时，设计会“失败关闭”（fail closed），而不是默认放行——这优于“请求审批、因此默认为同意”的架构。

3. 已知限制与安全边界

官方对若干仍在演进的安全边界保持坦诚： shipped 预设中 web_fetch 默认被禁用（其 SSRF 防护尚未完善，不阻断私有、回环、链路本地等地址）；Web UI 刻意仅限本地访问，CLI 会拒绝 --host 0.0.0.0，避免把具备 Shell 执行能力的本地 Agent 暴露为网络可达的远程代码执行入口。因此，文件隔离、审批策略与网络 containment 应被视为相互独立的控制项，需分别评估。

十一、DeepSeek Harness 如何部署与启动？

1. 环境与一键启动

运行依赖 Node.js（建议 v22.19 及以上）与 pnpm。最简单的启动方式是一条命令：

npx @deepseek-ai/dsh web

启动后浏览器访问 http://127.0.0.1:3080 即可打开 Web 工作台，选择工作区目录、在“设置 → 模型”中配置 API Key 后即可交互。

2. 源码部署

如需深度自定义或研究运行时，可克隆完整源码后本地构建：

git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

3. 无头模式与容器化

对于自动化场景，可使用 headless 配置一次性运行任务，例如 dsh --profile headless "run the tests and explain the failures"，该组合不启动 HTTP 服务或浏览器客户端，适合本地脚本、批量仓库分析与可控自动化作业。在企业环境中，也可通过容器化方式部署，配合只读根文件系统、no-new-privileges、HTTPS 与用户名密码认证等边界，把端口、访问地址与登录凭据收敛为受控入口。

十二、DeepSeek Harness 适合哪些开发场景？

1. 自建智能体执行环境

需要在本地可控、可扩展的运行时之上搭建自有 Agent，且希望模型与执行环境解耦的团队——同一套工具、会话管理与沙箱，可以替换不同的“发动机”（DeepSeek、Anthropic、OpenAI 或自建兼容端点）。

2. 模型与工具环境基准测试

适合评估不同模型在真实工具调用场景下的表现。借助极简模式与可替换的模型适配器，可以在同一套工具与沙箱下对比多个模型的实际任务完成能力，而无需为每个模型重建环境。

3. 二次开发与插件扩展

有定制需求的开发团队可以基于 Cordis 插件体系开发自有工具、模型适配器、存储后端或界面组件，并把已有 Prompt、工作流与插件逻辑平移到不绑定特定模型厂商的执行底座上。

4. 数据隐私敏感场景

本地执行与工作区隔离机制，使文件始终留在本地（进程在本地运行），适合对数据主权与隐私有较高要求的场景。需要注意的是，负责思考的模型仍在远端服务器运行，用户让模型读取的文件内容会离开本机，因此心智上应区分“文件躺在本地”与“被读取的部分会离机”。

十三、DeepSeek Harness 与 Claude Code、Cursor 等工具有什么区别？

1. 定位差异：平台与产品

Claude Code、Cursor 等本质上是面向终端用户的“产品”——把大模型包装成一个开箱即用的编程助手或 AI IDE，功能相对固定。DeepSeek Harness 则是一套“平台”或“框架”，提供的是可组合的 Agent 运行时，开发者需要自行装配所需能力。

2. 扩展与模型绑定

在扩展性上，Harness 以“一切皆插件”实现全能力可替换，并原生支持 MCP 协议；而 Claude Code、Cursor 的扩展能力相对有限、功能较为固定。在模型绑定上，Harness 可替换为任意兼容 LLM（DeepSeek、Anthropic、OpenAI、Bedrock 及自定义端点），Claude Code 绑定 Claude，Cursor 则支持多模型。

3. 上手门槛与适用人群

Harness 需要理解插件与配置装配的概念，上手门槛中等；Claude Code、Cursor 开箱即用、上手简单。因此，只想用 AI 辅助写代码的用户更适合直接使用成品工具，而想做自有 Agent 产品、深度定制行为或研究 Agent 运行时的开发者，更能发挥 Harness 的价值。

十四、DeepSeek Harness 与传统 Agent 框架相比有何不同？

1. 架构范式：插件化而非中心化

传统 Agent 框架往往是在一个核心程序上不断叠加功能，扩展方式各异、技能与记忆策略难以复用。Harness 的核心押注是“扩展面本身就是宿主 API”——核心只负责组织，能力尽量留在插件里，开发者不应修改中央核心，而应通过可装载、可卸载的能力扩展系统。

2. 竞争维度的转变

Harness 释放的信号在于：Agent 的竞争正从单纯的“模型竞争”扩展为“模型 + Harness 的系统竞争”。同一个模型放进不同 Harness，可能因上下文、工具暴露、重试方式、权限与验证机制不同而表现差异显著。因此评价一个 Agent，不能只问“它用了什么模型”，还要问“是谁、用什么方式让模型把事情做完了”。

3. 当前阶段的客观局限

作为开发者预览版，Harness 的接口与插件 API 仍可能出现破坏性变更，性能与 Token 成本需在实际环境中自行测试，文档与产品化细节仍在打磨。它更适合作为研究、实验与二次开发的底座，尚未到可“闭眼上生产”的成熟阶段。