DeepSeek Harness（DSH）保姆级入门与原理详解：从跑到用再到讲得清

DeepSeek Harness（DSH）保姆级入门与原理详解：从跑到用再到讲得清

本文对应 Datawhale「DeepSeek Harness 技术入门-共学营」投稿任务。

全文约一万字，分为"上手篇"和"原理篇"两大块------只想快速跑通的，看第 1~6 节就够了；想看透"一切皆插件"到底是什么的，第 7~9 节是为你准备的。

你好呀！如果你正在看这篇文章，大概率是听说了 DeepSeek 开源了一个叫 DeepSeek Harness（简称 DSH）的东西，打开 GitHub 一看------packages、Cordis、插件树、事件瀑布......然后就想关掉了。

别关！这篇会带你走完三层台阶：跑起来 → 用明白 → 讲得清。

阅读本文你需要：

• 一台电脑（Windows / macOS / Linux 均可，本文实测环境是 Windows）
• 会打开终端、会复制粘贴命令
• 一个 DeepSeek API Key（第 5 节告诉你去哪拿）
• 一点点好奇心

预计用时：20 分钟跑通，2 小时看懂原理。

目录

• 上手篇
  1. 什么是 DeepSeek Harness
  2. 先把名词认全
  3. 准备工作和国内网络三大坑
  4. 安装与启动
  5. 配好模型，干第一个活
  6. 四种模式，新手最容易懵的地方
• 原理篇
  7. 架构深潜：DSH 到底长什么样
  8. 亲手改造：插件开发三段式（含完整代码）
  9. 进阶玩法一览
• 收尾
  10. 常见问题（含我踩过的坑）
  11. 术语小词典
  12. 下一步学什么

---

上手篇

1. 什么是 DeepSeek Harness

一句话：DSH 是 DeepSeek 官方开源的 Agent（智能体）运行框架 ，命令行叫 dsh，MIT 协议，完全免费。

先理解一个特别重要的公式：

Agent = 模型（Model） + Harness

拆开看是三层的：

层	角色	打比方	负责什么
Model	大脑	只会想和说	理解、推理、生成文字和工具调用请求
Harness	手脚 + 缰绳	把想法安全地干出来	上下文管理、工具装配、权限审批、沙箱、循环、会话记忆
Environment	现实世界	真正会发生事情的地方	文件、终端、数据库、网页

为什么只靠模型不行？ 因为模型只会"生成 Token"，但完成任务需要"动手"：读你的文件、跑一条命令、改一行代码、查一个网页。而且不是随便动------要安全、稳定、可追溯地动。这中间的全部工程，就是 Harness。

所以别把 DSH 当成"又一个 AI 编程助手"。它更像地基 ：官方自己的说法是"一切皆插件"------模型的接口、工具、会话日志、甚至驱动 Agent 干活的那个循环本身，全都能从配置里换掉（第 7、8 节详讲，这是 DSH 最值钱的部分）。

项目	内容
开源仓库	github.com/deepseek-ai/deepseek-harness
npm 包	@deepseek-ai/dsh
最新版本	0.2.0-rc.2（2026 年 8 月发布首个版本，迭代飞快）
许可证	MIT
官方文档	deepseek-harness.github.io/deepseek-harness/
状态	Developer Preview（开发者预览版，官方明说会有破坏性变更）

2. 先把名词认全

不用背，混个脸熟，后面都会遇到：

名词	说人话
Agent（智能体）	会自己规划、调工具、干活的 AI
Agent Loop（智能体循环）	Agent 的"心跳"：想→做→看结果→再想，循环到任务完成
Harness	模型和真实世界之间的全套支撑，本项目主角
Workspace（工作区）	Agent 被允许操作的那个文件夹，它的"现实世界"
Preset（预设模式）	一套能力组合，如"标准/极简/创造"模式
Plugin（插件）	DSH 里的一切组成单元，"一切皆插件"
Profile	一套完整的启动配置（web / headless / sdk ...）
Bundle（组合包）	可安装的插件包分发格式
Patch	给配置"打补丁"的覆写文件，按顺序叠
Seam（接缝）	可替换的能力接口（定义/实现/使用三件套）
Session（会话）	一次完整对话的全部历史记录
Turn / Step	一轮对话 / 一轮里的一次模型请求
Skill	最轻量的扩展：一个说明文档，模型按需加载
Token	计费单位，可以理解成"字数"
Cordis	DSH 底层的插件框架（第 8 节细说）

3. 准备工作和国内网络三大坑

终端 就是那个黑窗口（Windows 叫 PowerShell / CMD，macOS 叫"终端"）。你只需要会：输入命令，按回车。

DSH 要求 Node.js 版本 ^22.19.0 或 >=24.0.0。一句话：装 Node 24 准没错。

node -v     # 看到 v24.x.x 就 ✅

没装的话去 nodejs.org 下载安装。

⚠️ 国内网络三大坑（全是我实测踩过的）：

1. GitHub 克隆超时 ：直连时好时坏。救急办法是在地址前加镜像前缀：
   git clone https://ghproxy.net/https://github.com/deepseek-ai/deepseek-harness.git
2. npm 下载慢到怀疑人生 ：换国内镜像，速度差十倍。命令前加环境变量即可：
   npm_config_registry=https://registry.npmmirror.com npx @deepseek-ai/dsh web
   （我实测：全局安装 538 个依赖包，39 秒装完）
3. Windows 上 corepack enable 报 EPERM ：因为要写入 Node 安装目录（如 D:\nodejs），权限不够。用管理员身份打开终端再执行；或者干脆不走源码路线，用下面第 4 节的 npx / 全局安装。

4. 安装与启动

方式一：npx 直接运行（最省事，官方推荐）

npx @deepseek-ai/dsh web

npx 会自动下载并运行，不用提前安装任何东西。这就是官方 README 里的第一条命令。

方式二：全局安装（长期用选这个）

npm install -g @deepseek-ai/dsh
dsh --version    # 看到 0.2.0-rc.2 就 ✅

以后随时 dsh web 启动。

方式三：从源码运行（折腾党/开发插件需要）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable      # ⚠️ Windows 需要管理员终端
pnpm install
pnpm run build       # ⚠️ 不能省！缺构建产物页面会不完整
pnpm dsh web

启动后会看到什么

终端会打印出这样一行：

dsh web: http://127.0.0.1:3080/?token=一串字符

浏览器通常会自动打开。注意 ?token= 这个尾巴------它是本次启动的临时钥匙：DSH 每次启动都会生成一个一次性启动 token，浏览器用它换取签名的会话 cookie，之后所有请求都靠这个 cookie 认证。

⚠️ 所以直接访问 http://127.0.0.1:3080（不带 token）会得到 401，这不是故障，是安全设计。

打开后你会看到深色界面，左上角 DeepSeek HARNESS + "预览版"小标签。搞定！🎉

5. 配好模型，干第一个活

第一步：配置模型。 首次打开会弹"添加一个 API Key 开始使用"。去 platform.deepseek.com 注册登录，在 API Keys 页创建一个（长得像 sk-xxxxxxxx），填进去保存。

错过了弹窗也不怕：设置 → 模型 → DeepSeek (deepseek-official) → 填密钥 → 保存，看到"已保存 DeepSeek (deepseek-official)"就 ✅。

关于默认模型，几个值得知道的数字：

• 默认是 DeepSeek-V4.1-Flash（界面显示 DeepSeek-V41-Flash），推理等级默认 High；
• 上下文窗口 100 万 Token------这意味着你能让它一口气读进一个中型项目；
• 支持图片；还有一个纯文本的 deepseek-v4-pro 可选；
• 支持接"兼容 Messages API"的其他服务商（Provider 可替换，这正是"一切皆插件"的体现）。

⚠️ 两条安全提醒：

1. API Key 等于你的钱包------不要截图外发、不要提交到 Git、不要写进文章；
2. 设置里有一项「在使用官方模型 API 时上传 Session Log」（默认开启，用于帮助 DeepSeek 改进模型）。介意的话可以关掉。

第二步：选择工作区。 点"选择工作区"，选一个文件夹。

⚠️ 不选行不行？不行，输入框是灰的------因为工作区就是 Agent 的"现实世界"，没选之前它不知道自己能碰哪里的文件。这是一种保护。

第三步：发消息。 比如：

帮我看看这个文件夹里都有什么，用一段话总结。

我实测：一条自我介绍类消息，2 秒回复 ；首轮约 8K token，界面底部实时显示"轮/步、tok/s、缓存命中率、上下文占用"。跑一个真实任务后，切到回复上方的"轨迹"标签页，你能看到它每一步干了什么：调了什么工具、参数是什么、结果是什么。这个面板是学 DSH 最好用的"旁观席"。

（配图位置：素材/dsh-首次对话成功.png ------ 首次对话成功的界面）

如果某个操作需要你批准，界面会弹确认框------这是安全护栏（规则判断 → 单次授权 → 执行隔离三层），不是 bug。

6. 四种模式，新手最容易懵的地方

对话框上方有个"标准模式"按钮，点开有四种。这是 DSH 最有意思的设计之一------它们不是四个不同的产品，而是同一个内核的四种"能力组合"：

模式	官方描述	用一句话理解
标准模式	处理代码、文件和资料，适合大多数任务	什么都会的默认款
PTC 模式	包含标准模式的所有能力，更适合批量调用工具、对结果做筛选整理去重统计的任务	全套工具，但换成"批量+程序化"的干活方式
极简模式	Agent 仅使用终端工具完成任务，适合测试和对比其基础表现	只剩"一张嘴 + 一个终端"，极限瘦身
创造模式	用对话定制 DSH：让 Agent 编写插件、添加功能，也能组合工具和提示词创建自己的模式	连 DSH 自己都能改，玩法最野

（配图位置：素材/dsh-webui-4种模式.png ------ 四种模式的选择菜单）

新手先一直用标准模式。想感受差异，就同一个任务分别用标准模式和极简模式各跑一遍，对比轨迹------极简模式只剩终端还这么能干，第一次看挺震撼的。

📌 如果你在读《DeepSeek Harness 技术入门与架构原理》这本书：书上四套预设叫 Standard / PTC / Minimal / Creative ，当前代码里第四套的 id 叫 cordis、界面名"创造模式"------是同一物的不同命名，别被绕晕。

---

原理篇

7. 架构深潜：DSH 到底长什么样

从这节开始上强度。但放心，我用大白话讲。

7.1 运行中的 DSH = 一棵插件树

不是比喻，是字面意思。你在终端里敲下 dsh web，它做的是：把一层层配置文件按顺序叠起来，长出并挂载一棵插件树。

叠的顺序（从下到上）：

① Profile（启动模板：web / headless / sdk / sdk-minimal / acp）
   └─ 声明自己由哪些「组合包」按什么顺序组成
② Bundle（组合包：如 dsh-base → dsh-web-app）
   └─ 每个组合包带一个 cordis.patch.yml，即"一层配置"
③ 你的 Home Patch（~/.dsh/profiles/web/cordis.patch.yml）
④ 命令行 --patch 叠加层（临时实验用）

Patch（补丁）是理解一切的钥匙 ：一条 patch 按 id 定位插件树里的某个条目，替换它的整个 config，或者插入新条目。层与层的 patch 按优先级生效，所以"官方默认配置"永远可被上层覆盖------包括被你自己覆盖。

不信？亲眼看一下：

dsh --profile web --dump-config

这会把你的完整配置树打印出来。我实测输出 1263 行、183 个插件条目，文件里还有分层注释，长这样：

# == @deepseek-ai/dsh-base
- id: llm
  name: '@deepseek-ai/dsh-llm'
# == @deepseek-ai/dsh-base, patched by @deepseek-ai/dsh-web-app
...
# == @deepseek-ai/dsh-web-app, patched by <你的家目录>/.dsh/profiles/web/cordis.patch.yml

哪一层来自谁、被谁改过，一目了然。它打印出的任何一条，都可以被你写的 patch 替换------这就是"一切皆插件"最直观的证据。

7.2 没有特权内核，但有稳定契约

"一切皆插件"最容易被误解成"插件很多"。准确的含义是两句话：

1. 不存在需要打补丁的特权内核。扩展 DSH 的方式不是去改核心代码，而是"把插件挂载到其他插件旁边"；
2. 没有内核 ≠ 没有规矩 。规矩叫 Seam（接缝）------一项可替换能力由三个角色构成：

角色	干什么	例子
Service Definition	声明接口	ctx.fs 文件系统接口、ctx.llm 模型接口
Service Provider	实现接口	本地文件系统、某个模型适配器
Consumer	使用接口	面向模型的工具，如"读文件"工具

seam 的威力在替换时显现：把文件系统 Provider 换成远程沙箱，你的 Bash、终端、LSP 会整条链路跟着搬过去 ------因为它们消费的是同一个 ctx.fs 契约，不关心背后是谁。想换模型？注册一个 ctx.llm 适配器就行，连"模型能看到什么上下文"这条链路都是可替换的。

打个比方：别的软件像盖好的房子 ，改结构得砸墙；DSH 像乐高，而且说明书（配置文件）直接摆在你面前。

7.3 事件系统：扩展点的五种"分发模式"

插件之间靠类型化事件沟通。事件不是随便发的------每个事件声明了自己的"分发模式"（怎么跑监听器），这是公开契约的一部分：

模式	是否等待	行为	典型用途
emit	否	广播，所有监听器各自执行，返回值忽略	通知："某个会话开始了"
waterfall	否	环绕中间件 ：监听器收到 next，调用它把控制权交给下游	拦截/改写/网关
parallel	是	所有监听器并行执行	并行扇出
serial	是	按注册顺序依次执行，第一个有效返回值终止	顺序决策
bail	否	按顺序问，第一个给出有效答案的胜出（短路）	查找类决策

waterfall（瀑布）是最要理解的 ------它是"环绕中间件"模型：每个监听器可以改写请求对象再 next() 委托给下游，也可以不调 next() 直接返回 ，把整条流水线短路掉。做策略拦截（比如"这个操作我拒绝"）靠的就是故意短路；做观察记录则必须 记得调 next()。这不是坑，是设计意图。

顺带一提，DSH 里的事件分三个域：会话事件 （要持久化的"事实"，如 turn/start）、Agent 事件 （agent/*，观察进行中的工作）、能力事件 （往 ctx.fs、ctx.tools 等接缝上挂策略）。

7.4 一个轮次（Turn）的一生

Agent "干一轮活"到底发生了什么？官方架构文档给了一张流程图，我翻译成人话：

turn/start                     ← 一轮开始：领取输入
  agent/pre-step               ← 决定"这次要处理什么"（可改写、可拒绝）
  step/start                   ← 一个步骤 = 一次模型请求 + 它的工具调用
    agent/request              ← 组装系统提示词 + 工具schema，确定路由
    冻结请求 → 流式请求模型      ← llm/stream 一边流一边推给界面
    工具调用（可能多个）
      tools/pre-execute        ← 策略钩子、权限、沙箱在这里把关
      [守卫检查] [审批弹窗]
      tools/execute            ← 真正执行（超时、重试、计量包在外圈）
      tools/post-execute       ← 结果可被接受/阻断/替换/追加context
      记录 tool/result         ← 工具结果写进会话日志
  step/end                     ← 还有活没干完？进入下一个 step
turn/end                       ← 不欠任何工作了，本轮结束

几个值得记住的细节：

• 轮次是"零个或多个步骤"：如果第一步就被拒绝，就是一个没有步骤的空轮次；
• 工具执行是一条"流水线" ：pre-execute（权限/沙箱）→ 单调守卫（只能更严格，不能放宽）→ execute → post-execute（结果重写）→ finalize。任何插件都能在管线里加一环，但谁都绕不开这条管线；
• 审批与沙箱在不同层：审批是"这次允许吗"（一次性授权），沙箱是"即使允许了，也关在笼子里跑"（执行隔离），两者不能互相替代；
• 而且这一切全程记录------所以界面上你随时能切到"轨迹"看回放。

7.5 会话日志：唯一真相来源

DSH 有一条铁律：模型可见即已记录。

每个模型请求都必须能仅凭会话日志重建------deriveMessages() 从日志投影出"模型看到的对话历史"。这意味着：

• 会话可以 fork（分叉出新对话）、可以恢复、可以导出，全靠重放日志；
• 压缩（Compaction）不能篡改历史事实：上下文满了做摘要时，历史事件仍在日志里，只是模型看到的是压缩视图；
• 连"模型这轮看到了哪个版本的提示词"都有记录（每个 assistant 消息内嵌产生它的精确流）。

为什么要在架构层面较真这个？因为对 Agent 来说，"记忆"就是它的可信度：调试、审计、复现问题、冻结 KV cache 前缀，全都建立在"日志即真相"上。

7.6 Cordis：让"卸载"成为一等公民

DSH 底层的插件框架叫 Cordis，五个核心概念：

概念	含义
插件	导出 apply(ctx) 函数的模块（或 Service 子类）
上下文（ctx）	服务容器：每个服务占一个 ctx.<key>，按 key 查找而非 import
inject	声明依赖：依赖就绪才启动你的插件，加载顺序由依赖表达，不靠手工编排
类型化事件	上面 7.3 的五种分发模式
effect	可逆副作用：注册工具、监听器都是 effect，插件卸载时自动撤销

"自动撤销"这条规则，是"一切皆插件"能成立的地基：如果插件装得上却卸不干净，动态组合就会变成一锅粥。Cordis 用 Fiber（生命周期记录）保证"谁注册的、跟谁一起结束"，逆序清理；连热更新（HMR）都建在这套生命周期上------改完代码，旧实例按序退场、新实例挂载，不残留。

---

8. 亲手改造：插件开发三段式（含完整代码）

看懂原理最好的方式，是亲自动手。DSH 的扩展分三层，从轻到重：

层	是什么	复杂度	适合
Skill	一个 SKILL.md 说明文档，模型按需加载	⭐	教 Agent 一套流程/规范
Tool	写代码注册一个工具，模型可调用	⭐⭐	给它新能力
Hook	监听工具执行管线事件，改变执行规则	⭐⭐⭐	加策略、做审计

下面带你把第二层（Tool）完整走一遍------代码全部来自官方教程，可以直接复制。

8.1 第一步：认识插件的最小形态

一个插件，就是一个导出 apply 函数的 TypeScript/JavaScript 模块：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里通过 ctx 注册能力
  console.log('[my-plugin] plugin loaded!')
}

就这么多。注意两个点：

• 注册皆可逆 ：通过 ctx 注册的任何东西（事件监听、工具、定时器），插件卸载时自动清理，不用你手动 removeListener；
• 有需要手动清理的资源 （如网络连接），用 ctx.effect() 交出销毁函数：

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    return () => clearInterval(timer)   // 卸载时执行
  })
}

8.2 第二步：写一个真工具（官方 greet 示例）

这是官方"开发一个工具"教程的完整代码------注册一个 greet 工具：

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

export const name = 'greet-tool'
export const inject = ['tools']          // 声明依赖：等工具注册表就绪

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },        // execute 的返回形状
      render: (_args, value) => [{ type: 'text', text: value }],  // 怎么呈现给模型
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

逐段拆解：

• inject = ['tools']：告诉 Cordis"我需要工具注册表"，框架等它就绪 再调用 apply------你永远不用操心启动顺序；
• defineTool({...})：声明式定义。参数用 JSON Schema 描述，模型看到的就是这份描述；
• parameters 会自动推导并校验 args 类型；
• output.schema 定义返回值规范形状，output.render 决定模型看到什么（比如把图片渲染成 base64 块）；
• execute 里就是你自己的逻辑。

运行和调用（需要从源码运行的仓库检出）：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开界面输入 Use the greet tool to greet Ada.，模型就会调用你的工具，拿到 Hello, Ada!。🎉

8.3 第三步：让插件可配置

加配置只要导出一个 Config Schema：

import Schema from '@deepseek-ai/schemastery'

export interface Config {
  greeting: string
  maxRetries: number
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
})

export function apply(ctx: Context, config: Config) {
  console.log(config.greeting)   // 用户传入的值，或 schema 默认值
}

用户在你的插件行下写配置即生效：

- insert:
    - id: hello
      name: './src/my-plugin.ts'
      config:
        greeting: 'Hi there'

DSH 有个设计约定：凡是不同部署可能取不同值的参数，都必须做成配置字段，不许硬编码。

8.4 第四步：打包发布（从"本地实验"到"可安装"）

本地实验用 --patch 挂载，要给别人用就得打包成 Bundle（组合包）。两个核心概念别混：

概念	回答的问题	声明位置
Bundle	"这个包贡献什么？" → 一个 patch 文件	package.json 的 dsh.bundle
Profile	"这台机器由哪些包按什么顺序组成？"	package.json 的 dsh.profile

一个 Bundle 的目录结构：

hello-plugin/
├── package.json       # 声明 dsh.bundle
├── cordis.patch.yml   # 本包的配置层
└── index.js           # 插件实现

package.json：

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

cordis.patch.yml（插件行改按包名引用）：

- insert:
    - id: hello
      name: dsh-hello-plugin

安装到某个 profile：

dsh plugin --profile web add <包名或路径>

管理命令（转发给 pnpm）：dsh plugin --profile web add/remove/why <pkg>。

至此，你走完了 本地插件 → 可配置 → 可分发 的完整链路。给插件仓库加上 GitHub 话题 dsh-plugin，全世界都能发现它。

9. 进阶玩法一览

知道有这些就行，用得到再回来查：

玩法	怎么做	适合场景
无头模式（一次性任务）	dsh headless "run the tests" ------答一个任务、打印结果、退出	脚本、CI
CLI / TUI	dsh --profile <name> 选不同表层	终端党
Python SDK / TS SDK	随发行版提供 sdk / sdk-minimal profile	把 DSH 嵌进自己的程序
定时任务	标准模式内置 schedule 服务与提醒工具	自动化（如"每天产出周报"这类工作台）
子 Agent 委派	内置 subagent / subagent_fork 工具	大任务拆小、并行
换 Provider（换执行世界）	把 fs/subprocess 指向远程沙箱	隔离、云端
桌面版	Electron 桌面应用，与 CLI 共享数据	不想开终端
写自己的 Preset	创造模式里让 Agent 帮你组合	定制专属模式
公网部署	反向代理 + --public-url / TLS 参数	团队共享

一个值得抄作业的组合：极简模式 + headless，是官方跑 Benchmark 的配置------因为把 Harness 压到最薄，最能看清"模型本身"的实力。

---

收尾

10. 常见问题（含我踩过的坑）

Q1：浏览器打开 127.0.0.1:3080 显示 401？

A：少带了启动时打印的 ?token=xxx。用完整链接访问，或让它自动打开浏览器。

Q2：dsh 命令提示找不到？

A：你可能只跑过 npx @deepseek-ai/dsh web（临时运行，不安装）。想长期用：npm install -g @deepseek-ai/dsh。

Q3：git clone 一直超时？

A：国内直连 GitHub 不稳。加镜像前缀：git clone https://ghproxy.net/https://github.com/deepseek-ai/deepseek-harness.git。

Q4：npx / npm 慢得离谱？

A：换国内源：npm_config_registry=https://registry.npmmirror.com npx @deepseek-ai/dsh web。我实测全局安装 538 个包从"几分钟卡进度"变成 39 秒。

Q5：Windows 上 corepack enable 报 EPERM（operation not permitted）？

A：它要写 Node 安装目录，权限不够。用管理员身份开终端再执行；不走源码路线的话可以直接跳过这步。

Q6：从源码跑，页面报前端未构建？

A：pnpm run build 那步不能省------这是新手最容易跳过、也最容易翻车的一步。

Q7：端口 3080 被占用？

A：dsh web --port 3081。

Q8：它要改我文件时会弹确认框，能不问吗？

A：那是 Guard → Approval → Sandbox 三层护栏在干活，强烈建议保留。权限模式可以调，但新手期"多点头，少翻车"。

Q9：API Key 泄露了怎么办？

A：第一时间去 platform.deepseek.com 删掉那个 Key，再建一个新的。不要把 Key 写进任何要公开的文件。

Q10：怎么确认它用的哪个模型、花了多少 token？

A：界面底部实时显示（轮次/速度/token/缓存命中/上下文占比）；设置 → 模型 里看当前 Provider 与模型。

11. 术语小词典

术语	一句话解释
Harness	模型与真实世界之间的"手脚"，本项目主角
Agent Loop	想→做→看结果→再想的循环（它本身也是插件）
Turn / Step	一轮对话 / 一轮里的一次模型请求
Profile	启动配置模板（web/headless/sdk/sdk-minimal/acp）
Bundle	可安装的插件包分发格式
Patch	给插件树"打补丁"的覆写层，按优先级叠
Preset	会话级能力组合（标准/PTC/极简/创造）
Workspace	Agent 能碰的文件夹
Seam	可替换能力 = 定义 + 实现 + 使用三件套
Cordis	底层插件框架：注入、事件、可逆副作用
Waterfall	环绕中间件式事件：不调 next() 即短路
Effect	可撤销的注册副作用
Compaction	上下文压缩（不篡改历史事实）
PTC	程序化调用工具的模式（用代码批量调工具）
SKILL.md	最轻量扩展：给模型看的技能说明

12. 下一步学什么

到这里，你已经会：安装 → 启动 → 配密钥 → 选工作区 → 对话 → 看轨迹 → 换模式 → 导出配置树 → 写/打包插件。三个台阶全走完了 🎉

再往上，按这个顺序爬：

1. 读官方文档 （最权威）：仓库 docs/ 目录，重点看 architecture.zh.md（架构总纲）、cordis-primer.zh.md（框架扫盲）、tool-execution-pipeline.zh.md（工具流水线）；
2. 读源码 ：先看 packages/bundle/web-app/presets/ 下四个 preset 的 patch 文件（几百行 YAML，是"一切皆插件"最一目了然的一手材料），再按兴趣读 packages/core/；
3. 看社区长文：社区已经有好几本深度手册，比如《深入理解 DeepSeek Harness》（33 章架构解析）、zoahdev 的《实战手册》（17 章，含从 Hello 到发布插件的全流程）、以及带 mini 实现（约 2655 行 TypeScript）的《一切皆插件》------搜索关键词"DeepSeek Harness 手册"即可；
4. 动手做真东西：写一个自己每天都要用的小插件（比如把某个内部接口包成工具），从"会用"到"会改"。

一篇文章能带你跑通，但真正学会靠的是自己动手乱按------放心，按不坏的。

有问题欢迎评论区交流，祝玩得开心！

---

参考资料

• DeepSeek Harness 官方仓库与文档：github.com/deepseek-ai/deepseek-harness（重点：README、docs/architecture、docs/cordis-primer、docs/tool-execution-pipeline、docs/user/develop/*）
• Cordis 插件框架：github.com/cordiverse/cordis
• 设计论文：A Programming Paradigm for Spatiotemporal Composability（arXiv 2608.25512）
• Datawhale「DeepSeek Harness 技术入门-共学营」及社区手册资料

本文基于作者 2026-10-12 在 Windows + Node 24 环境的真实实测撰写（含配置树导出、首次对话、镜像加速等实测数据），命令均可直接复制使用。文中涉及版本敏感的内容以 0.2.0-rc.2 为准------DSH 迭代很快，请注意核对。