DeepSeek Harness Profile 是什么？新手使用指南

如果你前面一直通过下面的命令使用 DeepSeek Harness，其实你已经在使用一个 profile——web。只是新手阶段没有必要先理解这个概念。

$ npx @deepseek-ai/dsh web

当前官方 CLI（Command Line Interface，命令行界面）中，dsh web 就是 dsh --profile web 的硬编码别名。所以 profile 最简单的理解是：一套可以被 DSH 启动的具名组装。它决定这次启动会组合哪些基础能力、组合包和用户配置。

如果你只是做下面这些事，不需要一开始深入 profile：

• 打开 Web UI（浏览器图形界面）
• 配模型
• 选工作区
• 新建会话
• 使用技能

真正开始遇到这些事情时，profile 才变得重要：

• 安装插件
• 配置 MCP Client
• 给某套 DSH 运行环境增加组合包
• 查看当前 Harness 到底组合了哪些能力
• 给某个启动组合增加自己的配置覆盖

DeepSeek Harness 当前官方架构文档定义：profile 是存放在 Harness home 中的具名组装。它主要包含三类东西：

1. 这套 profile 使用哪些组合包
2. 这套 profile 自己安装的树外插件依赖
3. 用户自己的 cordis.patch.yml

官方 profile 目录位于 $DSH_HOME/profiles/<name>，例如 $DSH_HOME/profiles/web。Harness home 即环境变量 $DSH_HOME 指向的目录，默认是用户目录下的 ~/.dsh。可以先把它理解成「这一套 DSH 要怎么组装起来」的启动配置单元。

web profile 和 dsh web 是什么关系？

当前 CLI 直接规定：dsh web 等价于 dsh --profile web。普通用户使用 npx 时，对应 npx @deepseek-ai/dsh web，也就是先启动 web profile，再把后面的 Web 应用参数交给已经启动的组合处理。

所以 Web UI 不是脱离 profile 单独运行的另一套东西。你平时启动 Web UI，本质上就是在启动 web profile。

官方还有哪些 profile？

当前发行版至少提供两个 profile 作为模板：

• web：主要用于浏览器 Web UI。
• headless：当前官方架构描述中，提供一次性运行器，并且不带 Web Server（网页服务）。

新手 Learn 主路径主要围绕 web 展开。其他自定义 profile 可以等进入插件开发或 Architecture（架构）内容后再研究。

这两组概念非常容易混淆，先拆开看。

profile 和工作区有什么区别？

profile 回答的问题是：这套 DeepSeek Harness 怎么组装？例如有哪些组合包、有哪些树外插件、有什么 profile 级配置。工作区回答的问题是：智能体当前围绕哪个文件目录工作？例如 ~/Projects/my-app。

所以 profile 不等于工作区。同一个 web profile，可以服务很多不同工作区。

profile 和 Agent 预设有什么区别？

这也是最容易混淆的一组概念。profile 属于整个 DSH 启动组合，它会承载模型适配、持久化、沙箱、审批、Web 应用、Agent 预设系统以及其他插件能力。Agent 预设则属于某个会话里的智能体能力组合，例如标准模式、PTC 模式、极简模式、创造模式。

profile
→ 启动一整套 DSH

Agent 预设
→ 在这套 DSH 里，为某个会话选择一种 Agent 组合

所以 web profile 里可以运行不同的 Agent 预设。不要把 web profile 和「标准模式」理解成同一级别的模式选择。

安装插件时你经常会看到这样的命令：

$ npx @deepseek-ai/dsh plugin --profile web add <package>

这里的 --profile web 是在告诉 DSH：把这个依赖和组合包加入哪一套 profile。也就是说，插件安装不是一个完全没有目标的全局动作，它需要知道你准备修改哪一套 DSH 组合。例如 web 和另一个自定义 profile，就可以安装不同的树外插件。

什么是组合包？

组合包（bundle）是 Cordis（DSH 底层的插件运行时）配置项及其挂载代码的分发格式，官方中文就叫「组合包」。一个组合包通过 dsh.bundle 声明自己提供的配置层，而 profile 通过 dsh.profile 记录自己按什么顺序包含哪些组合包。

组合包
→ 「我提供一层什么能力」

profile
→ 「我要按什么顺序把哪些组合包拼起来」

@deepseek-ai/dsh-base 是什么？

当前官方架构中，每个 profile 的第一层都是 @deepseek-ai/dsh-base。它提供 DSH 的大量基础能力，例如模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测。在此基础上，web 相关组合再增加浏览器应用能力。

新手不需要记住所有包名，这里只需要知道：profile 不是从空白开始随便拼，它有一套有顺序的组合层。

当前插件安装文档里，profile 主要涉及两个文件：package.json 和 cordis.patch.yml。

package.json

这里会记录三类信息：

1. profile 的树外插件依赖
2. dsh.profile
3. 有序的组合包列表

例如概念上类似这样：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "some-bundle"
      ]
    }
  }
}

对于通过 dsh plugin 管理的 profile，这份 manifest（清单文件）通常由 CLI 负责维护，不建议新手为了装插件直接手改它。

cordis.patch.yml

这是这个 profile 自己的用户配置覆盖层。你可以用它对前面组合包贡献的配置进行覆盖，或者增加新的配置项。

第一次接触时不需要学习完整的 Patch 算法，先记住：组合包提供默认组合，profile 的 cordis.patch.yml 可以在它们之上做用户自己的调整。Patch 的精确覆盖规则放到 Architecture 再讲。

配置到底按什么顺序生效？

Learn 阶段只需要记住这个顺序：

1. profile 列出的组合包
2. profile 自己的 cordis.patch.yml
3. Harness home 级的 cordis.patch.yml
4. 命令行额外传入的 --patch

示意图点击放大

排在后面的层可以覆盖前面的配置。至于具体如何按 id 定位、为什么 config 是整行替换而不是深度合并、Cordis Loader 怎样重新组合，属于 Architecture 内容，这里不展开。

这是 profile 这一页最实用的一条命令。普通 npx 用户可以运行：

$ npx @deepseek-ai/dsh --profile web --dump-config

也可以利用 web 别名简写：

$ npx @deepseek-ai/dsh web --dump-config

它会打印组合后的 profile 配置树然后退出，不会真正启动 Web UI。

--dump-config 有什么用？

• 安装插件以后：确认新的组合包层是否已经进入当前 profile。
• 修改 profile 配置以后：确认最终配置和你的预期是否一致。
• DSH 启动失败时：先看当前 profile 到底组合出了什么。

因此 DSHOPC 后面的插件教程会经常使用 npx @deepseek-ai/dsh --profile web --dump-config，作为「能安装」之后的下一层验证。

--dump-config 会修改配置吗？

不会。它的用途是查看组合后的配置并退出，把它当成只读检查入口更合适。这和编辑 cordis.patch.yml、安装插件、删除插件不是一类操作。

--dump-default-config 又是什么？

当前 CLI 还支持：

$ npx @deepseek-ai/dsh --profile web --dump-default-config

它和 --dump-config 的区别是：只打印 profile 的组合包层，不包含用户自己的 profile patch，也不接受额外的 --patch 参数。它更适合对比「官方 / 组合包默认是什么」和「用户最后改成了什么」。

普通用户第一次理解 profile，先会用 --dump-config 就够了。

当前实现里要区分两类变化，它们的生效方式不同。

profile / home 的用户 patch

当前长时间运行的 DSH 会同时监听 profile 的 cordis.patch.yml 和 Harness home 级 cordis.patch.yml，这些用户配置变化当前支持重新组合。

组合包或插件依赖变化

例如安装一个新插件组合包、移除一个组合包、修改 profile 的 bundle 集合。这类变化是在 profile 启动时读取和组合的。因此插件安装或删除以后，需要重新启动对应 profile，确认新组合真正生效。

后面的插件教程会按「安装 → dump-config → 重启 → 核心能力验证」的顺序走完整流程。

不要把 profile 的隔离理解得太强。可以说不同 profile 能维护不同的组合包、树外插件依赖和 profile 级配置，但 profile 不是虚拟机、容器、安全沙箱，也不是完全隔离的系统。

尤其还有 Harness home 级 cordis.patch.yml 会作用于各个 profile 之上。因此 DSHOPC 不把 profile 描述成「安全隔离环境」，更准确的说法是：一套具名、可分别管理的 DSH 组装。

能不能创建一个 test profile 专门做实验？

可以把独立 profile 用作配置和插件实验的管理边界，例如 web 用于日常 Web UI，test 用于测试某个插件组合。这样可以减少在日常 profile 上同时改变太多变量的风险。

大多数普通使用场景都不需要手工操作 profile。尤其是安装插件时：

$ npx @deepseek-ai/dsh plugin --profile web add <package>

CLI 会帮助初始化和维护 profile manifest。新手最优先掌握的是下面五件事：

1. 知道当前使用的是哪个 profile
2. 知道插件安装目标是哪个 profile
3. 会用 --dump-config 查看组合结果
4. 知道 cordis.patch.yml 是用户配置覆盖层
5. 不把 profile 和工作区、Agent 预设混为一谈

手工设计新的 profile 组合，更适合插件开发和 Architecture 阶段。

一张表区分三个最容易混的概念

一句话记住：工作区对应文件目录，Agent 预设对应会话里的 Agent，profile 对应整套 Harness 启动组合。

一个完整例子

假设你平时运行：

$ npx @deepseek-ai/dsh web

这意味着启动了 web profile。然后在 Web UI 中选择 ~/Projects/dshopc，这一步选的是工作区；再新建一个会话并选择标准模式，这一步选的是 Agent 预设。三个概念各自负责一层：

web profile
↓
启动整套 Web Harness

dshopc 工作区
↓
告诉 Agent 在哪个目录工作

标准模式
↓
决定这个会话的 Agent 工具和能力

安装插件时，profile 为什么突然变重要？

假设你运行：

$ npx @deepseek-ai/dsh plugin --profile web add some-plugin

这条命令告诉 DSH：把这个插件依赖安装进 web profile。如果它还是一个 dsh.bundle 组合包，CLI 还会把它加入该 profile 的组合包列表。之后你再运行 npx @deepseek-ai/dsh web，这套 Web Harness 就会在原有组合上加入新的插件层。这就是 profile 和插件的直接连接点。

MCP 为什么也经常碰到 profile？

当前 DeepSeek Harness 的 MCP Client 本身就是一个插件，MCP Server 的连接配置最终需要进入 DSH 的组合配置。所以学习 MCP 时，你会再次碰到 profile、patch 和 MCP Client 插件这几个概念。

这也是为什么 DSHOPC 的学习路径被安排成「扩展能力选择 → profile → MCP」，而不是一开始就把一大段 Cordis YAML 丢给新手。

不需要为了验证专门创建新 profile，你只需要能够独立完成下面几个判断：

• 知道 dsh web 本质上启动的是 web profile
• 知道 profile 是一套具名 DSH 组装，不是工作区
• 知道 profile 也不是 Agent 预设
• 知道组合包通过有序列表进入 profile
• 知道 cordis.patch.yml 是用户配置覆盖层
• 能运行 --dump-config 查看当前组合
• 知道 profile 不是安全沙箱

可以自己运行一次：

$ npx @deepseek-ai/dsh --profile web --dump-config

如果能够看到当前组合树，profile 的基础使用目标就完成了。

如果你准备安装插件

继续阅读插件教程。下一篇会真正使用 npx @deepseek-ai/dsh plugin --profile web ... 这样的命令，并把验证过程拆成五层：能安装、已进入 profile 组合、profile 能重新启动、插件能力真正出现、最小核心功能真实成功。

示意图点击放大

如果你准备接入 MCP

继续阅读 MCP 教程。读完本篇，你已经理解为什么 MCP 配置会和 profile、插件、patch 发生关系。

如果你只是准备创建技能

可以直接阅读技能教程。本地技能路线不要求先修改 profile。

如果当前步骤没有按预期工作

随时可以进入故障排除教程，按故障层级定位问题。