DeepSeek Harness (DSH) 实战：架构、模式与插件化开发

canber2026-08-17 10:29

概要说明

DeepSeek Harness (CLI: dsh) 是 DeepSeek 官方开源的新一代 Agent 运行与治理框架。它立足于 Agent = Model + Harness 的现代 AI 设计逻辑，底层基于 Cordis 插件化元框架，实现了全面解耦的"一切皆插件"（Everything is a Plugin）架构。

📌 快速导航

  • [1. 核心架构与设计哲学](#1. 核心架构与设计哲学 "#1.%20%E6%A0%B8%E5%BF%83%E6%9E%B6%E6%9E%84%E4%B8%8E%E8%AE%BE%E8%AE%A1%E5%93%B2%E5%AD%A6")
  • [2. 环境准备与部署模式](#2. 环境准备与部署模式 "#2.%20%E7%8E%AF%E5%A2%83%E5%87%86%E5%A4%87%E4%B8%8E%E9%83%A8%E7%BD%B2%E6%A8%A1%E5%BC%8F")
  • [3. 四大核心运行模式对比](#3. 四大核心运行模式对比 "#3.%20%E5%9B%9B%E5%A4%A7%E6%A0%B8%E5%BF%83%E8%BF%90%E8%A1%8C%E6%A8%A1%E5%BC%8F%E5%AF%B9%E6%AF%94")
  • [4. 实战一：Standard Mode 自动化代码重构与测试](#4. 实战一：Standard Mode 自动化代码重构与测试 "#4.%20%E5%AE%9E%E6%88%98%E4%B8%80%EF%BC%9AStandard%20Mode%20%E8%87%AA%E5%8A%A8%E5%8C%96%E4%BB%A3%E7%A0%81%E9%87%8D%E6%9E%84%E4%B8%8E%E6%B5%8B%E8%AF%95")
  • [5. 实战二：PTC 模式（Code Mode）高性能批量处理编排](#5. 实战二：PTC 模式（Code Mode）高性能批量处理编排 "#5.%20%E5%AE%9E%E6%88%98%E4%BA%8C%EF%BC%9APTC%20%E6%A8%A1%E5%BC%8F%EF%BC%88Code%20Mode%EF%BC%89%E9%AB%98%E6%80%A7%E8%83%BD%E6%89%B9%E9%87%8F%E5%A4%84%E7%90%86%E7%BC%96%E6%8E%92")
  • [6. 进阶开发：自定义 Cordis Plugin 插件扩展](#6. 进阶开发：自定义 Cordis Plugin 插件扩展 "#6.%20%E8%BF%9B%E9%98%B6%E5%BC%80%E5%8F%91%EF%BC%9A%E8%87%AA%E5%AE%9A%E4%B9%89%20Cordis%20Plugin%20%E6%8F%92%E4%BB%B6%E6%89%A9%E5%B1%95")
  • [7. 轨迹追溯（Trajectory）与状态管理](#7. 轨迹追溯（Trajectory）与状态管理 "#7.%20%E8%BD%A8%E8%BF%B9%E8%BF%BD%E6%BA%AF%EF%BC%88Trajectory%EF%BC%89%E4%B8%8E%E7%8A%B6%E6%80%81%E7%AE%A1%E7%90%86")
  • [8. 生产落地检查清单与避坑指南](#8. 生产落地检查清单与避坑指南 "#8.%20%E7%94%9F%E4%BA%A7%E8%90%BD%E5%9C%B0%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95%E4%B8%8E%E9%81%BF%E5%9D%91%E6%8C%87%E5%8D%97")
  • [9. 进阶阅读：开源橙皮书《从开机到拆开》](#9. 进阶阅读：开源橙皮书《从开机到拆开》 "#9.%20%E8%BF%9B%E9%98%B6%E9%98%85%E8%AF%BB%EF%BC%9A%E5%BC%80%E6%BA%90%E6%A9%99%E7%9A%AE%E4%B9%A6%E3%80%8A%E4%BB%8E%E5%BC%80%E6%9C%BA%E5%88%B0%E6%8B%86%E5%BC%80%E3%80%8B")

1. 核心架构与设计哲学

为什么需要 Agent Harness？

LLM（如 DeepSeek-V3/V4）赋予 Agent 逻辑推理与大脑能力，但工具调度、上下文裁切、权限控制、状态恢复与错误自愈 等工程化落地的重任，必须靠 Harness 支撑。

1.1 系统架构图

graph TD User([用户 / CLI / Web UI]) --> DSHCore[DeepSeek Harness Core] subgraph Cordis Plugin Framework DSHCore --> ModelAdapter[Model Adapter Plugin] DSHCore --> ToolExec[Tools & Sandbox Plugin] DSHCore --> SessionLog[Append-only Session Log] DSHCore --> SubAgents[Sub-Agent Dispatcher] end ModelAdapter --> DeepSeekAPI[DeepSeek API / Local LLM] ToolExec --> ShellEnv[Bash / Terminal] ToolExec --> FileEdit[Str Replace Editor] ToolExec --> CustomTools[Custom Plugins] SessionLog --> TrajectoryView[Trajectory / Fork / Replay]

开发者预览状态

DSH 当前处于 v0.1 开发者预览（0.1.0-rc.x） 阶段，官方明确表示会持续快速迭代并存在 破坏性兼容变更（Compatibility-breaking Changes） 。生产环境请锁定版本并跟进官方 Release 说明。

1.2 三大核心设计原则

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

    模型适配器、Shell 执行器、文件编辑器、权限拦截器乃至前端界面，均作为 Cordis 插件无缝挂载。

  2. 时空可组合性（Spatiotemporal Composability）

    • 空间扩展 ：无需改动主干源码，通过 profile 组合配置（cordis.patch.yml）灵活拼装能力。
    • 时间追溯 ：基于追加式日志（Append-only Event Stream），实现任意 Step 的重放 (Replay) 与 分叉 (Fork) 。

  3. Prefix Caching 高效复用

    针对 DeepSeek API 的上下文缓存（Context Caching / Prefix Cache）特性设计，严格保证 Prompt 前缀确定性。官方内置缓存优化在常规多轮会话中命中率即可达 95% - 98% （社区实测无需插件即达此水平），命中部分按磁盘缓存计费，成本约为全新计算的 1/50 - 1/120，可大幅降低多轮 Agent 交互的 Token 成本。

2. 环境准备与部署模式

2.1 前置要求检查表

  • Node.js : >= 22.19（22.x 最新版，或直接使用 24.x）
  • API 密钥 : 获得有效 DEEPSEEK_API_KEY（也可在 Web UI 设置界面中配置）
  • 包管理器 : pnpm（仅源码安装 需要；npx 快速体验不需要）

环境快速检查脚本

bash 复制代码 
node -v                    # 需要 >= 22.19
npx -y @deepseek-ai/dsh --version   # 快速体验路径：首次运行会下载 dsh 包体（约 1-3 分钟）

2.2 四种启动方式（NPX 免安装）

启动方式 命令 说明
Web UI（推荐） npx @deepseek-ai/dsh web 默认地址 http://127.0.0.1:3080；工作区/会话在界面内选择
TUI dsh --profile tui 终端交互界面（需安装 tui profile）
Headless dsh --profile headless <任务文本> 一次性任务模式，适合 CI
Python SDK pip install deepseek-harness 程序化接入，内置运行时
perl 复制代码 
# 启动 Web 交互界面（默认端口 3080）
npx @deepseek-ai/dsh web

# 指定端口（--host / --port / --trusted-host 属于 web 应用参数）
npx @deepseek-ai/dsh web --port 8080
# 等价写法：dsh --profile web --port 8080（dsh web 是 --profile web 的别名）

# 排查"改了配置没生效"第一步：查看最终配置树
npx @deepseek-ai/dsh --profile web --dump-config

2.3 源码安装（适合二次开发与插件扩展）

bash 复制代码 
# 1. 克隆官方仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 安装依赖并编译
pnpm install
pnpm run build

# 3. 配置环境变量
cp .env.example .env
# 在 .env 中写入 DEEPSEEK_API_KEY=sk-xxxxxx（也可在 Web UI 设置中配置）

# 4. 启动 DSH
pnpm dsh web

3. 四大核心运行模式对比

模式选择建议

DSH 提供了 4 种预设模式，针对不同任务类型优化了上下文与工具集配置：

模式 适用场景 内置工具集 特性与优势 Token 消耗
Standard 模式 综合开发、代码重构、全流程工程 完整工具组合（Shell、File Editor、Search、Sub-Agents 等） 能力最全面，交互最直观 中 ~ 高
PTC 模式（Code Mode） 批量文件改写、数据管道、高吞吐操作 Code Mode SDK（TypeScript In-sandbox） 模型生成一段 TS 程序编排多轮工具调用，无多轮 Round-trip 低
Minimal 模式 基准测试 (Benchmarking)、极简 Bug 修复 bash, str_replace_editor 仅保留 Shell + 文件编辑工具，排除冗余上下文干扰 极低
Creator 模式 自定义 Preset 编写、插件调试、Agent 架构分析 全量工具 + Inspector 调试面板 可检查/组合运行时插件，最接近自我演进实验 中

模式与 Preset

四种模式对应官方预置 Preset：standard、code（PTC）、minimal、cordis（创造模式）。每种模式默认加载不同插件集合，全部可在配置层自由替换（详见第 6 节）。

4. 实战一：Standard Mode 自动化代码重构与测试

实战场景

现有旧 Node.js 项目（CommonJS 规范），需全量重构为 ES Module (import/export)，修改 package.json 并确保测试通过。

Step 1: 启动 DSH 并绑定项目路径

typescript 复制代码 
npx @deepseek-ai/dsh web
# 启动后在 Web UI 中选择/创建工作区（workspace），再指向 ~/projects/legacy-express-app

Step 2: 提交 Prompt 指令

在 Web 界面选择 Standard Mode，粘贴以下指令：

markdown 复制代码 
请帮我完成以下重构流程：
1. 扫描 `src/` 目录，找出所有使用 `require()` / `module.exports` 的文件。
2. 将其重构为标准 ES Module 语法 (`import` / `export`)。
3. 修改 `package.json` 添加 `"type": "module"`。
4. 执行 `pnpm test`，若有失败项自动分析报错并修复，直至测试全过。

Step 3: 执行流程与安全防护

scss 复制代码 
[User Prompt]
     │
     ▼
[DSH Agent Loop] ───► 1. file_search("src/") 找到目标文件
     │
     ├───────────────► 2. 触发系统安全弹窗 [Approval Guard]: "写入 package.json" -> 点击 [Approve]
     │
     ├───────────────► 3. str_replace_editor 精准替换语法
     │
     ├───────────────► 4. bash("pnpm test") 执行测试套件
     │
     ▼
[Task Finished] ───► 生成修改 Git Diff 摘要与测试报告

权限防护级别 (Permission Tiers)

DSH 把"能力边界"与"决策授权"拆成两个独立旋钮，且默认失败关闭（Failure-Closed） ：

  • 沙箱模式（Sandbox Mode） : read-only（只读，拒绝一切写入）→ workspace-write（仅工作区根目录及后端承诺的临时区域可写）→ danger-full-access（绕过沙箱，直接 spawn 原始命令）。
  • 审批策略（Approval Policy） : ask（默认，交由应答者链 / 人工确认）→ never（确定性拒绝，适合 CI 无人值守）。
  • 权限预设（Permission Presets） : workspace-write = 工作区可写 + ask（推荐日常使用 ）；danger-full-access = 绕过沙箱 + never，只能在一次性可丢弃环境（如临时容器）中使用 。
    关键安全性质：审批链无应答者、应答者抛异常或返回值不合规时，结果为 unavailable，一律按拒绝处理，绝不静默放行。

5. 实战二：PTC 模式（Code Mode）高性能批量处理编排

为什么 Code Mode Token 消耗极低？

常规 Agent 修改 100 个文件需要 100+ 次 LLM 大模型对话。而在 PTC 模式（程序化工具调用 Programmatic Tool Calling / Code Mode SDK） 下，模型只需生成一段 TypeScript 批处理脚本，在 DSH 的沙箱中一次性执行，由代码自行编排多轮工具调用，极大减少模型与工具之间的往返。

橙皮书实测补充：PTC 并非总是省钱

花叔《DeepSeek Harness：从开机到拆开》实测：PTC 下 5 次开口编排了 15 次操作 ，但"固定开销"（上下文与工具装载成本）反而上涨约 9% 。结论：PTC 适合操作密集、Round-trip 多的批量任务；任务只需一两次工具调用时，Standard 模式可能更划算。

提示词范例：

"在 PTC 模式（Code Mode）下执行：扫描 ./docs 目录所有 .md 文件，为没有 Frontmatter 的文件统一插入包含 title、date、status 的 YAML 标头。"

模型在沙箱中生成的脚本 (auto_header.ts)：

javascript 复制代码 
// 以下导入为演示性示意：官方 SDK 包为 @deepseek-ai/dsh-sdk-*（如 dsh-sdk-client），具体 API 以官方文档为准
import { fs, glob, logger } from '@deepseek-ai/dsh-sdk';
import path from 'path';

async function processMarkdownFiles() {
  const mdFiles = await glob('./docs/**/*.md');
  logger.info(`扫描到 ${mdFiles.length} 个 Markdown 文件`);

  let updatedCount = 0;
  for (const filePath of mdFiles) {
    const rawContent = await fs.readFile(filePath, 'utf-8');
    
    // 检查是否已有 Frontmatter
    if (!rawContent.trim().startsWith('---')) {
      const fileName = path.basename(filePath, '.md');
      const frontmatter = [
        '---',
        `title: "${fileName}"`,
        `date: "${new Date().toISOString().split('T')[0]}"`,
        'status: active',
        '---',
        '',
        ''
      ].join('\n');

      await fs.writeFile(filePath, frontmatter + rawContent);
      updatedCount++;
    }
  }

  logger.success(`处理完成！共更新 ${updatedCount} 个文件。`);
}

processMarkdownFiles().catch(logger.error);

6. 进阶开发：自定义 Cordis Plugin 插件扩展

DSH 的底层框架为 Cordis。你可以轻松开发符合标准的第三方插件，为 Agent 提供专属业务工具。

6.1 插件项目结构

DSH 全线使用 ESM（package.json 必须声明 "type": "module"）。最小结构是 package.json + 一个编译产物入口（TypeScript 源文件放 src/，产物指向 lib/）：

vbnet 复制代码 
dsh-plugin-mysql/
├── package.json
│   # "type": "module"、main 指向 lib/index.js
├── tsconfig.json
└── src/
    └── index.ts          # 编译到 lib/index.js

6.2 编写 MySQL 查询插件

php 复制代码 
// src/index.ts
import type { Context } from '@deepseek-ai/cordis';
import z from '@deepseek-ai/schemastery';
import { defineTool } from '@deepseek-ai/dsh-tools';

// 1. 插件元信息：四个具名导出（name / inject / Config / apply），绝对不要用 export default
export const name = 'mysql-tool';

// 2. 硬依赖声明：'tools' 服务缺失时插件停在 PENDING，不会半初始化
export const inject = ['tools'];

// 3. 配置 Schema（schemastery）：框架据此校验组合里的 config
export const Config = z.object({
  host: z.string().default('localhost').description('数据库地址'),
  user: z.string().required().description('数据库用户名'),
  database: z.string().required().description('目标数据库名'),
});

// 4. 唯一入口：在这里注册一切副作用（禁止模块级副作用）
export function apply(ctx: Context, config: { host: string; user: string; database: string }) {
  ctx.tools.register(defineTool({
    name: 'sql_query',
    // description 是模型判断"何时调用"的唯一依据，务必写清场景与边界
    description: '执行只读 SQL 查询命令，获取结构化结果',
    parameters: {
      sql: { type: 'string', required: true, description: '待执行的 SELECT 查询语句' },
    },
    output: {
      schema: {
        type: 'object',
        additionalProperties: false, // 对象节点必填，openness 必须显式
        properties: {
          status: { type: 'string', required: true },
          data: { type: 'array', required: true },
        },
      },
      // render 必须是纯函数：结果会以文本形式进入模型上下文
      render(_args, value) {
        return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
      },
    },
    async execute(args, exec) {
      if (!args.sql.trim().toLowerCase().startsWith('select')) {
        throw new Error('安全拦截：仅允许执行只读 SELECT 查询！');
      }

      ctx.logger('mysql-plugin').info(`执行 SQL: ${args.sql}`);

      // 模拟返回数据库数据
      return {
        status: 'success',
        data: [
          { id: 101, name: 'Order_A', status: 'PAID' },
          { id: 102, name: 'Order_B', status: 'PENDING' }
        ]
      };
    }
  }));

  ctx.logger('mysql-plugin').info('MySQL 插件注册成功！');
}

6.3 挂载插件至 DSH（profile + cordis.patch.yml）

DSH 没有自定义的 dsh.config.yaml 插件列表；插件的安装与组合分别由 dsh plugin add（安装进 profile） 与 cordis.patch.yml（组合配置） 完成：

bash 复制代码 
# 1. 安装插件（注册进 web profile，让 preset 行能用裸包名引用）
dsh plugin --profile web add ./dsh-plugin-mysql
yaml 复制代码 
# 2. 在 profile 组合配置 ~/.dsh/profiles/web/cordis.patch.yml（或自定义 preset 的 agent.cordis.yml）中挂载：
- id: mysql
  name: dsh-plugin-mysql
  config:
    host: "127.0.0.1"
    user: "root"
    database: "production_db"

"仓库里有 ≠ 装上就有"

橙皮书实测：约 35 个扩展包在 npm 上存在，但不在默认安装闭包内 。想用某个插件必须先 dsh plugin --profile <profile> add <包名> 显式安装，再在组合配置中挂载。

组合配置三条铁律

  • Preset 在会话创建时锁定 ：新装的工具只对之后新建的会话生效，host 会拒绝给已存在的会话换 preset。
  • 覆盖是浅层赋值，不是深合并 ：patch 里写 config 会整体替换原 config，要保留的字段必须一并写全；新增行必须用 insert。
  • 改配置没生效，先跑 dsh --profile web --dump-config 看最终配置树（layering：profile bundles → profile 的 cordis.patch.yml → home 级 patch → --patch 覆盖层），而不是猜。

7. 轨迹追溯（Trajectory）与状态管理

调试利器：Append-only Event Log

DSH 会实时记录 Agent 执行的每一步：系统提示词、User/Assistant 消息、推理（Reasoning）、工具调用（Tool Calls）与返回结果（Tool Outputs）、上下文注入（Context Injections）、子 Agent 调度（Sub-agent Scheduling）。

7.1 Trajectory 核心功能表

yaml 复制代码 
Session Events (Append-Only)
  ├── Step 01: System Prompt + Context
  ├── Step 02: User Instruction
  ├── Step 03: Agent CoT Reasoning
  ├── Step 04: Tool Exec [bash: npm test]
  └── Step 05: [FORK POINT] ───► Branch A: 重构语法 (Selected)
                          └──► Branch B: 升阶依赖
  • 恢复（Resume） : 在 Web UI Trajectory 面板搜索并恢复中断或崩溃的历史 Session；CLI 示例为 dsh --profile tui --resume <session-id>（需安装 tui profile）。
  • 搜索（Search） : 在同一条事件流上按来源/关键词检索任意 Step。
  • Fork Session : 在 Web UI Trajectory 面板中选择任意历史 Step 点击 Fork，从该起点切出新分支实验不同解决方案。
  • Replay Protocol: 一键重新跑一遍整个 Session 轨迹，用于验证基准模型性能及 Bug 复现。

Fork 边界

Fork 只能在"稳定边界"上切分（所选前缀必须结束在一个完整的 Turn 之外），确保新分支从完整、可回放的历史起点开始。

8. 生产落地检查清单与避坑指南

8.1 生产落地 Checklist

  • 版本锁定: 当前为 v0.1 开发者预览，官方会引入破坏性变更；生产环境锁定版本并跟进 Release 说明。
  • Prefix Cache 保护: 避免在 System Prompt 中放置全局时间戳或动态变量，将动态信息移至 User Prompt 末尾。
  • 沙箱隔离: 生产环境中务必开启 Docker / Containerized Sandbox 隔离 Shell 执行权限。
  • 权限最小化 : 日常使用 workspace-write + ask 预设；danger-full-access 仅在一次性可丢弃环境使用。
  • 审批策略 : CI / 无人值守使用 approval/policy: never（确定性拒绝），绝不允许静默放行。
  • 超时与 Turn 限制: 设置单次 Agent Loop 最大 Turn 数（如 30）防止卡死循环。
  • 日志持久化: 配置 Session Log 定期同步至对象存储。

8.2 常见问题排查 (Troubleshooting)

问题 1: npx @deepseek-ai/dsh 启动报错或 pnpm install 失败

解决思路 : 确认 Node.js >= 22.19（22.x 或 24.x）；npx 快速体验路径不需要 pnpm。源码安装路径运行以下清理命令后重新构建：

arduino 复制代码 
rm -rf node_modules pnpm-lock.yaml && pnpm install && pnpm run build

问题 2: Agent 陷入无线死循环 (Tool Loop)

解决思路 : 在组合配置（如 profile 的 cordis.patch.yml 或对应 preset）中配置循环与超时约束。以下为示例字段，实际字段名以官方文档为准：

yaml 复制代码 
agent:
  max_turns: 30
  tool_timeout_ms: 60000

问题 3: 新插件/新配置"没生效"

解决思路 : ① 先跑 dsh --profile web --dump-config 看最终组合树；② 确认 preset 行 id / name 匹配（非 insert 的 patch 中 name 是守卫，不匹配会被跳过并警告）；③ 新工具只对新创建的会话生效，旧会话不会加载新 preset。

9. 📘 进阶阅读：开源橙皮书《DeepSeek Harness：从开机到拆开》

定位

"官方发布稿的主语是「它」------它怎么造的、它是什么架构。这本书把主语换回「我」：我装上之后第一件事干什么、会不会花我的钱、会不会动我硬盘上别的文件。"

花叔（HuaShu）在 DeepSeek Harness 开源 24 小时内 完成的免费开源实测书（v260814，约 120 页），仓库：alchaincyf/deepseek-harness-orange-book。协议 CC BY-NC-SA 4.0（可自由分享/改编，需署名、非商用）。

🔗 相关链接与参考

相关推荐
OpenTiny社区2 小时前
GenUI SDK v1.3.0 开发者深度解读：当生成式 UI 开始"长出"工程化骨架
前端·ai编程
全栈弄潮儿2 小时前
4 个新手就能直接套用的 AI 编程提示词模板
chatgpt·openai·ai编程
晚安code2 小时前
Agent Harness 从原理到实战：大模型不干活，全靠智能体运行框架在撑
ai编程
刘立军2 小时前
依赖注入：禁止 AI 硬编码实例化，提升可测试性与扩展性
架构·ai编程
晚安code3 小时前
上下文工程是什么？从提示词工程到上下文，一文讲透 AI 不跑偏
ai编程
晓得迷路了3 小时前
栗子前端技术周刊第 142 期 - DeepSeek Harness、pnpm 12 RC、crypto‑js...
前端·javascript·ai编程
必须会一定会4 小时前
Node.js Agent Handoff 仓库扫描 MVP：忽略规则、include 通配与稳定输出实现
人工智能·node.js·ai编程
AINative软件工程4 小时前
Agent 上下文账本工程：别让工具结果把 128K 窗口塞成垃圾场
后端·架构·ai编程
程序员黑豆4 小时前
Java正则表达式详解
java·前端·ai编程
热门推荐
01GitHub 镜像站点02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费06历年考研数学一、数学二、数学三真题试卷及答案PDF07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路08VSCode+CodeX扩展，无法启动092026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片10如何新建文件夹？ 电脑新建文件夹的4种方法