DeepSeek Harness（CLI: dsh) 是 DeepSeek 官方开源的新一代 Agent 运行与治理框架。它基于现代 AI 设计理念：Agent = Model + Harness并以 Cordis 插件化元框架实现“一切皆插件”架构。

快速导航

• 主要架构与设计哲学
• 环境准备与部署模式
• 四大主要运行模式对比
• 说到实战一，Standard Mode 自动化代码重构与测试
• 至于实战二，PTC 模式高性能批量处理编排
• 进阶开发这方面。自定义 Cordis Plugin 插件
• 轨迹追溯与状态管理
• 生产落地检查清单与避坑教程
• 再看进阶阅读，开源橙皮书《从开机到拆开》

主要架构与设计哲学

为什么需要 Agent Harness？

LMM赋予 Agent 推理能力。但真正落地的工具调度、上下文裁切、权限控制、状态恢复和错误自愈，都依赖于 Harness。怎么说呢，

程序架构图

graph TD
User --> DSHCore
subgraph Cordis Plugin Framework
DSHCore --> ModelAdapter
DSHCore --> ToolExec
DSHCore --> SessionLog
DSHCore --> SubAgents
end
ModelAdapter --> DeepSeekAPI
ToolExec --> ShellEnv
ToolExec --> FileEdit
ToolExec --> CustomTools
SessionLog --> TrajectoryView

三大主要设计原则

1. 一切皆插件: 模型适配器、Shell 执行器、文件编辑器、权限拦截器等均为 Cordis 插件。
2. 时空可组合性:
   • 空间 ：No main code change,just profile configuration .
   • 时间追溯：Add‑only logs enable replay & fork.
3. Prefix Caching 高效复用：The built‑in cache keeps prompt prefix deterministic and can reduce token cost by up to ~50% in multi‑turn sessions.

环境准备与部署模式

前置要求检查表

• Node.js：= v18.x

# 环境快速检查脚本

node -v
# 快速体验方法：首次运行会下载 dsh 包体
npx -y @deepseek-ai/dsh --version

四种启动方式

* 每个模式对应官方预置 Preset：`standard`,`code`,`minimal`,`cordis`。你可以随时通过 `dsh plugin add` 与 `cordis.patch.yml` 自由替换或组合。

痛点传统手工重构旧 Node.js 项目耗时且容易出错；老实说，自动化工具缺乏安全审批链。

场景描述

已有旧 Node.js 项目采用 CommonJS，需要全量重构为 ES Module 并确保单元测试通过。

步骤

Step ① 启动 DSH 并绑定项目方法

bash npx @deepseek-ai/dsh web # 启动后在 Web UI 创建工作区 → 指向 ~/projects/legacy-express-app

Step ② 提交 Prompt 指令

text 扫描 src/，将所有 require/module.exports 重写为 import/export。修改 package.json 添加 "type":"module"。执行 pnpm test，如有失败自动分析报错并修复至全部通过。

Step ③ 执行流程 & 安全防护示意图

mermaid flowchart TD A -> B B -> C) C -> D D -> E E -> F) F -> G G --> H

权限防护级别

• 沙箱模式 – 从只读 → 工作区可写 → 完全访问；
• 审批策略 – 默认 ask，可 CI 设置 never；
• 权限预设 – 推荐使用 workspace-write+ask；danger-full-access仅用于一次性容器。

痛点传统多轮 Tool Call 导致 Token 成本飙升；说起来，批量文件更新需要大量模型往返。

原理说明

在 PTC 模式下模型一次生成 TypeScript 脚本。在沙箱中一次性执行，实现 “一次生成、一键执行”，显著降低 Round‑Trip。

示例任务

“扫描 ./docs/*/.md，为没有 Frontmatter 的文件插入统一 YAML 标头。”

Prompt 示例：

text 在 PTC 模式下执行：扫描 ./docs/**/*.md 并为没有 Frontmatter 的文件插入 title/date/status 前缀。

自动生成脚本

ts import { fs。glob,logger } from '@deepseek-ai/dsh-sdk';import path from 'path';

const mdFiles = await glob;let updatedCount = 0;

for { const rawContent = await fs.readFile;if .startsWith) { const fileName = path.basename;const frontmatter = }"。'status: active','---','',].join;await fs.writeFile;updatedCount++;} } logger.success;

性能洞察

• Token 消耗单次生成脚本后无需再多轮调用；相比 Standard Mode 多轮调用显著节省 Token。
• 适用场景操作密集、大批量文件 若仅需几次工具调用，则 Standard 更划算。

痛点团队业务需求需要自研数据库查询或第三方服务集成，但现成插件有限。按理说，

框架概述

Cordis 是 DSH 的底层插件元框架；你可以按标准创建任何业务插件，并通过 /cordis.patch.yml 挂载。

插件项目结构示例

dsh-plugin-mysql/ ├── package.json # "type": "module","main": "./lib/index.js" ├── tsconfig.json └── src/ └── index.ts # 编译产物入口 lib/index.js

MySQL 查询插件实现

ts import type { Context } from '@deepseek-ai/cordis';import z from '@deepseek-ai/schemastery';import { defineTool } from '@deepseek-ai/dsh-tools';

export const name = 'mysql-tool';export const inject =;// 硬依赖声明，缺失则停在 PENDING 状态

export const Config = z.object({ 说到host。z.string.default,user: z.string.required,database: z.string.required,});

export function apply { ctx.tools.register(defineTool({ 从name来看，'sqlquery',description:'执行只读 SELECT 查询',parameters:{ 再看sql，{type:'string'。required:true} },output:{ schema:{ 再看type，'object',properties:{status:{type:'string',required:true},data:{type:'array',required:true}},additionalProperties:false,},render{ return;} },async execute{ if .toLowerCase.startsWith) throw new Error;ctx.logger.info;// 假设返回数据结构： return {status:'success',data:};} }))，ctx.logger.info;}

rm -rf node_modules pnpm-lock.yaml && pnpm install && pnpm run build
If using NPX skip PNPM.
\t\t\t\t
\t\t\t\t
\t\t\t
\t\t
\t
\t
\t
\t
\tt<\/a>
\r\r\r\r\r\r\r\r\r\r\r\r\r\
'\r\
'\r\
'\r\
'\r\
'\r\
'>\r \
\"\r\
\"\r\
\"\r\
\"\r\
\"\r\" \
\"\"\";\\">
"