DeepSeek Harness 深度精读 DeepSeek Harness Deep Read

0.1 48 小时里发生了什么

先把时间线摆出来。2026 年 8 月 12 日，DeepSeek 把 V4-Pro 从预览版转为正式版，这是模型的动作。8 月 13 日晚，DeepSeek Harness（后面统一叫它 DSH）开发者预览版 v0.1 开启全球公测，同时以 MIT 协议开源到 GitHub（仓库地址：deepseek-ai/deepseek-harness）。这还没完——据腾讯云开发者社区梳理，48 小时内还有第三件事：API 涨价，8 月 16 日生效。模型转正、Agent 框架开源、API 调价，三件事挤在一起，节奏很密。

为什么说这个时间点有意思？因为 DeepSeek 一向以「低调、只发模型」著称。Harness 是它第一次把「工具链」本身拿出来开源，而不是只开源模型权重。开源一个 Agent 框架，意味着它想把「怎么用模型」这件事，也变成开放协作的对象。

开发者预览版（Developer Preview）：正式版之前的公开测试版，功能可用但可能不稳定、接口可能变。DSH 当前是 v0.1，官方措辞是「预览」而不是「正式」，这个定位很重要——它意味着文档可能滞后、插件生态还没起来、很多边界情况没人踩过。

有个细节值得注意：DSH 用的标志是一条黑色鲸鱼，而 DeepSeek 模型产品用的是蓝色鲸鱼。黑色鲸鱼配独立公众号「DeepSeek Harness 团队」——官方特意把「模型品牌」和「Harness 品牌」分开经营。这说明团队把它当独立产品线做，不是模型的一个附件。

0.2 「毛坯房」：第一印象为什么是负面评价

发布当天，社区最常见的反应是「毛坯房」：基础界面只有一个对话框加历史记录，没有侧边栏文件树、没有一键部署、没有现成插件市场。对比 Claude Code 开箱即用的精致体验，DSH 确实显得寒酸。

这也解释了另一个现象：上手门槛的争议。有经验的开发者夸它「乐高积木」「Minecraft 模组」，普通用户则抱怨「文档太少、配置太杂」。这两种评价其实说的是同一件事——DSH 把复杂性从「产品内部」搬到了「用户面前」。你要么自己搭，要么等生态把积木拼好。

0.3 为什么这份精读值得做

市面上写 DSH 的文章，多数停留在「它开源了、一切皆插件、有四种模式」的复述层。这个页面要做的是把「一切皆插件」这五个字拆开：插件系统长什么样（Cordis）、配置怎么合并（层叠）、模型如何被降级成普通插件（Cortex 循环）、日志为什么只能追加（append-only）、四种模式到底差在哪。这些机制层面的东西，才是你判断「DSH 值不值得用」的素材。

另外一个现实原因：DSH 目前是 v0.1，资料稀缺。官方文档不完整，社区经验分散在论坛和社交媒体上。这个页面相当于帮你做了一次「机制考古」——从官方源码（你本地就能 npm 装到的包）、官方公告、多家媒体报道里，把散落的事实拼成一幅可理解的地图。

1.1 「插件」这个词被用滥了，但这里不是比喻

很多产品说自己「支持插件」，实际是「我们做了个主程序，再留几个扩展点」。DSH 不是这种。它把「模型」「工具」「技能」「会话」「沙箱」「存储」「循环」「调度」「UI」全部定义为插件——没有一个是内置的「主程序」，全部可以替换、重排、删除。

这带来一个反直觉的推论：连「Agent 循环」本身（模型思考→调用工具→看结果→再思考）都是插件。官方文档里「循环」出现在插件清单里，意味着你甚至可以把「思考→行动」这个循环替换成别的结构。比如 PTC 模式，就是把「多次工具调用」压缩成「一次程序化调用」——这就是换了一个「循环插件」。

插件（Plugin）：在 DSH 语境里，指任何可以被独立加载、配置、替换、移除的模块化组件。插件由依赖（deps）、配置（config）、服务（service）三要素定义，运行在 Corda 容器内。

1.2 三要素：依赖、配置、服务

在 Cordis 的世界里，一个插件不是一坨「实现功能的代码」，而是由三部分定义的结构：

依赖（deps）：这个插件需要哪些其他插件先就位。比如「文件工具」插件依赖「沙箱」插件，因为文件读写发生在沙箱里。依赖声明让 Cordis 能自动解析加载顺序。

配置（config）：这个插件的可调参数。每个插件声明自己的配置 schema，默认值、类型、校验规则都在这里。多个配置通过「层叠」合并（第 3 章细讲）。

服务（service）：插件对外提供的接口。比如「shell 工具」插件提供 `exec()` 方法，「会话」插件提供 `push()`、`fork()` 方法。别的插件通过服务调用它，而不是直接 import 代码——这是「依赖倒置」的核心：上层不依赖下层实现，只依赖接口。

这三要素的组合逻辑，让「插件」天然具备可替换性——你只需要找一个实现了同样服务接口的插件，就能无缝替换。

1.3 「一切皆插件」的边界在哪

真的「一切」吗？按官方公告和源码，核心的 Cordis 运行时本身不是插件（它是容器）。「一切皆插件」描述的是 Agent 能力层：模型、工具、技能、会话、沙箱、存储、循环、调度、UI。这九类之外的「框架本身」，比如 Cordis 内核、DSH 的 CLI 入口，是固定的地基。

所以准确的说法是：DSH 里「凡是能换的，都用插件实现；框架只保留最小的胶水」。这与 Unix 哲学「做一件事并做好」一脉相承——但比 Unix 更激进：连「你」这个 Agent 的主循环都可以换。

2.1 Cordis 从哪里来

Cordis 不是为 DSH 现写的，它有一段「祖传」历史：2019 年，Shigma 在开发聊天机器人框架 Koishi 时，把插件管理逻辑抽成了独立层；2022 年，这个独立层以 Cordis 的名字开源（MIT 协议），Koishi 本体则缩小到了约 350KB。换句话说，Cordis 是一个在聊天机器人生态里被验证了多年的「插件元框架」，DSH 是把它拿来当 Agent 容器的又一次复用。

这条时间线很重要，因为它解释了 DSH 为什么敢在 v0.1 就开源：Cordis 本身已经有四年的生产经验，插件体系成熟，DSH 只需要在上面「挂 Agent 能力」，不需要从零发明插件系统。这也回应了「毛坯房」批评——地基其实是稳的，只是「Agent 家具」还没摆齐。

元框架（Meta Framework）：不直接提供业务功能，而是提供「如何组织功能」的框架。Cordis 不帮你写对话、不帮你调模型，它只负责：谁先加载、谁依赖谁、配置怎么合并、事件怎么广播。

2.2 五个关键特性

热插拔（Hot Reload）：插件可以运行时增删，不用重启整个进程。这对 Agent 调试很关键——你改一个工具的行为，立刻生效，不用把会话重开。

依赖倒置（Dependency Inversion）：插件之间通过服务接口（service）交互，而不是直接 import。上层插件只依赖「接口」，不依赖「实现」，所以换实现不需要动调用方。

单体仓库（Monorepo）：Cordis 生态用 monorepo 管理所有包，版本一起发，接口同步演进。DSH 的 90 多个 @deepseek-ai 子包也沿用了这个模式，所以你 npm 装 dsh 时能看到几十个依赖包。

复刻/分叉（Fork）：Cordis 生态里「分叉」是核心操作——把已有的 Agent 配置复制一份，改参数，变成新的 Agent。这个思想直接渗透进 DSH 的会话设计（第 7 章）。

配置层叠（Config Cascade）：多个来源的配置按优先级合并，后写覆盖先写。这是 DSH 配置系统的理论基石（第 3 章）。

这五个特性单独看都不稀奇，但组合在一起，就构成了「你可以信任这个容器来跑 Agent」的理由：热插拔让你迭代快，依赖倒置让你换得动，monorepo 让你装得全，分叉让你繁殖快，层叠让你配得省。

2.3 DSH 与 Cordis 的版本关系

打开 DSH 本地安装包（`npm` 全局装 `@deepseek-ai/dsh`）的 package.json，依赖里明确写着 cordis 4.0.1。而 Cordis 4 是 2023 年后大版本，带更完善的 schema 校验、类型系统和异步生命周期。DSH 直接把 Cordis 4 作为运行时依赖，等于站在了成熟版本上。

这意味着两件事：第一，DSH 的插件格式就是 Cordis 插件格式，意味着你理论上可以复用 Cordis 生态里已有的插件（如果接口兼容）；第二，DSH 的「技能」概念（skill）很可能就是 Cordis 插件的一种包装——官方说「技能」是插件，具体技能定义文件（如 SKILL.md）如何被 Cordis 加载执行，是后续值得深入源码的存疑点。

2.4 为什么复用比自研聪明

DeepSeek 完全可以给 Harness 自己写一个插件系统。但复用 Cordis 有四个实打实的好处：

• 成熟度：四年的聊天机器人生态验证，边界情况踩过无数。
• 开发者惯性：Koishi 生态的开发者迁移成本低，DSH 能快速拿到第一批插件贡献者。
• 聚焦：团队可以把精力放在「Agent 语义」（循环、工具、轨迹）而非「插件机制」。
• 政治：开源协议 MIT 且历史悠久，不会被质疑「自造轮子」。

3.1 五层配置：后写的赢了

官方文档里 DSH 的配置层叠结构是这样的（从底层到顶层）：

1. 空根（Empty Root）：什么都没有，纯粹是起跑线。
2. dsh.profile.bundles 各插件包的 patch：每个插件包自带一份「补丁」（patch），声明它往配置里加什么。这是插件声明式配置的一部分。
3. profile 自身的 cordis.patch.yml：当前选中的 profile（如 web/headless/tui）自带的配置文件。
4. $DSH_HOME/cordis.patch.yml：你放在 home 目录下的用户级配置。
5. 命令行 --patch 覆盖层：临时传参，优先级最高，只对本次运行生效。

合并规则一句话：后写的覆盖先写的。插件包说「模型默认是 deepseek-chat」，你的 $DSH_HOME 说「不，用 my-ollama」，最后生效的是你的。

Profile（Profile）：一组配置的命名集合。DSH 内置了 web、headless、tui 三个 profile，分别对应网页版、无界面后台、终端界面三种运行形态。profile 相当于「预设的插件组合方案」。

3.2 Profile 到底是什么

你可以把 profile 理解为「一个已配好的插件组合的快捷方式」。`dsh --profile web` 表示：以 web 形态启动——加载 web 界面插件、会话插件、模型插件、工具插件，组合成一个「跑在网页里的 Agent」。`--profile headless` 表示：只要核心逻辑，不要界面——适合服务端调用、批处理、测试。

内置三个 profile 的区别，主要在「UI 插件的取舍」上，底层的模型、工具、会话都一样（除非 profile 明确改）。这就是为什么官方说「profile 可以自由定义」——你把 web profile 的文件复制一份，改几个插件组合，就成了自己的 profile。

另外注意：`dsh web` 是 `dsh --profile web` 的别名，官方 CLI 里专门做了这个快捷方式。这说明 web 形态是官方最想推的第一个体验入口。

3.3 --dump-config 与 --patch：查配置、改配置的钥匙

--dump-config：把「当前 profile 合并出来的最终配置树」打印出来。注意是「合并后」的，不是某一层。它帮你回答「我现在这套配置到底生效了什么」——排查插件冲突、默认值覆盖、语法错误都靠它。

--patch <文件>：把一份 YAML/JSON 作为最高优先级的覆盖层临时合并。适合「今天跑一个实验，不想动 home 配置」的场景。

这两个命令配合 `dsh plugin --profile <name> <pnpm args>`（在 profile 环境里装插件）基本就能完成日常的「查配置、改配置、装插件」闭环。

3.4 实验室：五层叠一座塔

4.1 一张表看懂四种模式

这四种模式不是四个「产品版本」，而是四个「插件组合方案」——对应第 3 章说的 profile 概念。每种模式本质上是「换了一套工具插件 + 循环插件」。

4.2 标准模式：最像普通 Agent 的形态

标准模式把完整工具集都交给模型：shell、文件读写、网络、代码执行、信息检索……模型在一个循环里反复「思考→选工具→执行→看结果」。这是目前主流 Agent（Claude Code、Codex 等）的形态。

优点：灵活，能处理不可预知的任务。缺点：每一轮都要等模型推理，多步任务延迟高、token 消耗大、还可能跑偏。

4.3 PTC 模式：把「想一步做一步」换成「写一段程序」

PTC（Programmatic Tool Calls，程序化工具调用）是 DSH 的一个亮点。普通循环里，模型每一步「说一句话、调一个工具、等结果」；PTC 模式让模型「生成一段代码」，这段代码可以连续调用多个工具、处理中间结果、做条件分支——相当于把「对话式调度」变成「程序化调度」。

打个比方：标准模式像你一步步指挥同事（每个步骤都要等回复）；PTC 模式像你把整个任务的执行步骤写成一张清单交给同事（中间不用一直请示）。

但 PTC 的代价是：模型生成的「程序」如果写错了（比如工具参数拼错），没有中间的人工校验机会，可能一条路错到底。所以 PTC 适合「任务步骤明确、可预测」的场景；对「探索性、需要中途看结果调整」的任务，标准模式更稳。

4.4 极简模式：给基准测试准备的「裸奔」

极简模式只给两个工具：一个 shell、一个文件编辑。为什么官方要提供这种「少到可怜」的模式？答案：基准测试的公平性。

Agent 评测里，「工具越多 = 能力越强」往往是噪音——一个 Agent 用 30 个工具完成任务，另一个只用 2 个，比的是工具库不是推理能力。极简模式把工具压到最小，逼模型用推理+基础工具完成复杂任务，才能量出「模型本身的 Agent 能力」。

这就是官方说的「用于基准测试」。如果有一天你看到论文用 DSH 做 Agent 评测，大概率跑的是极简模式。

4.5 创造模式：给插件开发者准备的「手术室」

创造模式（Creative Mode）面向插件开发者：你可以直接检查正在运行的 Cordis 运行时，在内存里试验插件、动态组合新的模式，甚至把新组合固化成新的 profile。它本质是一个「活的调试器 + 插件实验室」。

这意味着「创造模式」是四种模式里唯一一个「改自己」的模式——它用 Agent 的能力来改 Agent 的构成。这在传统框架里几乎不可想象：IDE 不能改自己的运行时，但 Agent 可以（在沙箱里）。

4.6 实验室：PTC vs 标准模式的成本对比

5.1 循环的四个阶段

任何一个 Agent 都在跑同一个基本循环，区别只在「谁控制它、怎么控制」：

1. 组装上下文：把系统提示词、历史消息、工具定义、记忆注入到给模型的请求里。
2. 模型推理：模型生成文本或工具调用请求。
3. 执行工具：如果模型要求调用工具，执行并把结果写回。
4. 循环判断：结果是「完成」还是「继续」？继续就回到第 1 步。

5.2 上下文组装：模型「看到」了什么

每次请求，模型看到的不是「你的问题」，而是系统组装好的一整套上下文。DSH 里这套东西的构成大致是：

• 系统提示词：由「技能」「人格设定」等插件提供，定义 Agent 的行为边界。
• 历史消息：之前的对话和工具结果，可能被压缩（compaction 插件）或裁剪。
• 工具列表：当前 profile 加载了哪些工具，它们的 JSON schema 描述。
• 记忆：长期记忆检索出来的相关片段。
• 事件流：子 Agent 的调度记录、最近的操作事件。

这里的「记忆」和「上下文注入」都出现在官方日志设计里（第 7 章会展开），说明 DSH 把「模型看到什么」当成一件可审计、可复现的事，而不是黑箱。

5.3 「循环插件」长什么样

从 DSH 的 package.json 可以看到 dsh-loop、dsh-goal* 这样的子包——它们就是循环相关的实现。一个「循环插件」的职责是：决定「下一步做什么」。标准模式的循环插件实现「模型→工具→模型」；PTC 的循环插件实现「模型→生成程序→执行程序→（可能）再修正」；创造模式的循环插件甚至允许「改循环自己」。

这也解释了为什么「模式」是 profile 级的配置：换模式=换循环插件+换工具集合。

5.4 图解：Agent 循环交互图

6.1 工具插件的全景

打开 DSH 的 package.json，你能看到一长串 `@deepseek-ai/dsh-tool-*` 的子包：dsh-tool-shell、dsh-tool-file（文件）、dsh-tool-web（网页）、dsh-tool-code（代码执行）……目前已经 20 多个。每个工具一个 npm 包，每个包都是一个 Cordis 插件。这就是「工具即插件」在包结构上的体现。

工具插件的职责：定义工具的 schema（参数怎么传）、实现工具的 execute（真正干活）、声明需要的依赖（比如 file 工具依赖沙箱）。模型不直接调用工具实现，而是「看到 schema → 生成 JSON 调用 → Cordis 路由到对应工具插件 → 执行 → 结果写回」。这一整条链路上，模型和实现是完全解耦的。

工具 Schema（Tool Schema）：描述工具「怎么调用」的结构化定义——工具名、参数名、参数类型、必填性、描述。模型靠它知道「这个工具能干嘛、参数怎么填」。schema 写得越清楚，模型越会用对。

6.2 沙箱：工具的安全边界

「沙箱」也是 DSH 的插件（官方清单里有）。它控制工具能在什么环境里执行：文件读写限定在某个目录、网络访问受限、命令执行被白名单过滤。这非常重要，因为 Agent 的本质是「模型拿到你电脑的执行权」——没有沙箱，一个 prompt injection（提示词注入）就可能让模型把文件删了。

沙箱插件与工具插件的关系是「依赖」：工具插件声明依赖沙箱服务，Cordis 保证沙箱先启动，工具才能在沙箱里执行。这就是第 2 章「依赖倒置」的实际应用——工具不直接操作文件系统，而是调用沙箱服务接口。

6.3 图解：工具调用链路

7.1 append-only：一条不会说谎的轨迹

传统 Agent 平台保存的是「对话历史」——一般就是一串 user/assistant 消息。DSH 的会话日志（session log）不只记录对话，它记录「模型在整个会话期间看到的一切」：系统提示词、思维链、工具调用与结果、子 Agent 的调度、上下文注入的事件。更重要的是，它是 append-only（仅追加）——只能往里写，不能改、不能删。

为什么是 append-only？因为可审计性。一旦允许改，就没有人能信任日志。一个 LLM 在「改完一段历史后」说「我刚才没说过 X」，你信还是不信？append-only 直接消除了这种争议空间——日志就是事实，谁也别想改。

Append-only（Append-only）：日志的写入模式。只能追加新条目，不能改老条目、不能删条目。区块链的核心结构、git 的不可变 commit 历史、会计的账本，都是 append-only 思想的实例。

7.2 这份日志里有什么

按官方公告描述，会话日志记录以下内容（第 5 章讲过这些是「上下文」的来源，这里更细）：

• 系统提示词（按时间变化的部分）
• 模型的思维链（CoT，包括未展示给用户的推理步骤）
• 工具调用：工具名、参数、执行结果、执行时长
• 子 Agent 调度：谁创建了谁、传了什么、回收了什么
• 上下文注入：哪条记忆被注入了哪一段、被检索出来的依据
• 压缩（compaction）动作：哪一段被裁了、裁之前是什么

这些都被打上时间戳，按时间顺序追加。所以叫轨迹（trajectory）——你能看到 Agent 从开始到现在的每一步动态。

7.3 Trajectory 视图：按来源看日志

Trajectory（轨迹）视图是官方在 DSH 里提供的一个工具：把日志按「来源」（source）分类展示。你想看「模型说了什么」就过滤模型来源；想看「工具执行了什么」就过滤工具来源；想看「子 Agent 干了什么」就过滤调度来源。同一个事件流，换过滤视角就有不同解读。

这正是日志多维化的体现：它不是单一叙事，而是「同一时间线的多视角投影」。

7.4 恢复、分叉、检索、回放：四个动作，一个事件流

官方说「恢复（resume）、分叉（fork）、检索（search）、回放（replay）共享同一事件流」。这句话信息量很大，拆解一下：

• 恢复：会话崩了重启，从日志重放到中断点。
• 分叉：从日志的某个时间点，复制一份继续往下，分出新的分支会话。
• 检索：从历史日志里按关键词或语义找到某个事件。
• 回放：把日志按时间重新执行一遍，看 Agent 是怎么走过来的。

这四个操作不需要四种数据结构——它们都是对 append-only 日志的不同「读法」。这就是「共享同一事件流」的含义。这是对第 2 章 Cordis「分叉（fork）」特性在 DSH 层面的延展。

7.5 实验室：append-only 分叉模拟

8.1 模型绑定：本质分歧

Claude Code 绑定 Claude 模型。它本质是 Anthropic 为了「让 Claude 更好用」做的工具，模型是中心，工具是配套。DSH 反过来：模型只是众多插件之一，理论上 Claude、GPT、本地 Llama 都能挂。这叫 model-agnostic（模型无关）。

这不只是技术差异，更是商业差异。Claude Code 的目标是「让 Claude 卖得更多」——工具越好，用户越依赖 Claude 模型，Anthropic 越赚钱。DSH 把模型解耦，等于把「模型议价权」还给用户：模型 A 涨价了，你换模型 B，整套工具链不用变。

8.2 开放工坊 vs 精致商业产品

界面新闻的概括很贴切：Claude Code 是「精致商业产品」——开箱即用、打磨精良、体验流畅。DSH 是「开放工坊」——给你零件和工位，自己焊。两者面向的是不同用户群。

8.3 哪个适合你

这不是「谁更好」，是「谁是你的工具」。选 Claude Code 如果：你是个人开发者/终端用户，想立刻上手、不在意模型绑定、希望体验最丝滑。选 DSH 如果：你是企业/团队，要控制模型成本或合规要求（必须用本地模型）、要深度定制工具组合、能接受配置复杂度。

另一个角度：选 Claude Code 如果你信任 Anthropic 的演进节奏；选 DSH 如果你相信 Cordis 社区 + 自家能力能把这个框架养大。后者风险更高、回报也更高。

9.1 定义：什么样的「无关」才算数

「模型无关」不是「能跑任何模型」这么宽泛。真正的模型无关需要三个条件：

1. 接口统一：所有模型走同一套「对话+工具+工具结果」的接口，不依赖任何厂商专有特性。
2. 配置切换：换模型=改配置，不需要改代码或重写工具。
3. 能力无损：切换后 Agent 仍能有可用能力（不要求能力相同，但要求「能用」）。

第三个条件最难。一个模型有「视觉理解」而另一个没有，工具调用格式一个遵循标准 JSON schema、另一个用自定义格式——这时候「无关」就只是「理论装得上」，不是真的能替换。所以模型无关是有光谱的，不是 0 或 1。

Model-agnostic（Model-agnostic）：系统能容纳多种模型，切换成本由配置承担而非代码承担，且切换后保持可用能力上限。这是渐变量，不是二值量。

9.2 趋势论：支持的三条论据

界面新闻说「Model-agnostic 是行业趋势」，有几条支撑论据：

• 模型在快速迭代：今天最好的模型半年后可能被超过。绑定=押宝；无关=可换。
• 开源权重繁荣：Llama、Qwen 等开源权重让用户可以本地部署，天然倾向模型无关。
• 价格竞争：API 持续降价，用户乐见多家竞价，模型无关让用户切换灵活。

9.3 反对论：也可能只是口号

但也有三条相反论据：

• 差异化能力：每个模型都有自己的「独家特性」（多模态、长上下文、function calling 格式），统一接口=削足适履。
• 协同调优：厂商自己能把工具和自己的模型调到最优，无关框架只能做通用适配。
• 成本结构：模型无关要支持多种模型=更多适配代码=更重框架，对单一厂商反而更贵。

所以最严格说法是：模型无关是有上限的好处，不是无条件的优点。适用群体明确：需要多模型/控成本/防锁定的用户；不适合：追求当前最强单一模型体验的用户。

9.4 DSH 的「模型无关」能不能成立

我的评估：能成立，但需要生态。DSH 本身只承诺「模型也是插件」，具体可用与否看插件的成熟度——DeepSeek 自家模型肯定有旗舰支持；Claude、GPT 应该会跟进；但一些小众模型/本地模型能不能用，看社区贡献。这是「能力上限」问题，不是「架构不可能」问题。

Pi-Agent 把自己定位「极简 Agent 底座」，也走模型无关路线，说明至少有共识：「这个方向值得做」。但 Pi-Agent 偏极简、DSH 偏插件化，「无关」的实现路径不同——一个靠减少接口实现统一，一个靠插件实现可挂。哪条路终将胜出，要看生态怎么演进。

10.1 安装：两条路

官方给了两种安装方式。第一种是 npx 临时运行，不用装，直接 `npx @deepseek-ai/dsh` 起服务——适合快速体验；第二种是 全局安装，`npm install -g @deepseek-ai/dsh`，把 dsh 当命令用，适合长期使用。

本机实测装的是 v0.1.0-rc.6（2026-08-13 当天的 npm 包），总共拉了 530 个依赖包——其中 90 多个是 @deepseek-ai 子包。安装目录：`C:\Users\78430\AppData\Roaming\npm\node_modules\@deepseek-ai\dsh\`，里面能看到 lib/bin.js（CLI 入口）、package.json（依赖清单）、README.md 等文件。

10.2 跑第一个 Agent：dsh web 三步

装好之后，三步走起来：

1. 设 API Key：DSH 默认用 DeepSeek 模型，需要 DeepSeek API Key（在 DeepSeek 平台拿）。把它写进 $DSH_HOME/cordis.patch.yml（第 3 章讲过的用户配置层），或者用 --patch 临时传。
2. 启动：`dsh web`（即 `dsh --profile web`）。终端会提示监听端口（通常 localhost:xxxx）。
3. 打开浏览器：访问提示的地址，看到「毛坯房」界面（对话框+历史记录），发第一句话。

能不能立刻干活？取决于 profile 默认加了什么工具。web profile 应该至少有 shell + 文件工具。让 Agent 帮你 `ls` 一下当前目录——如果它做得到，说明工具链通了。

10.3 第一次实验：--dump-config 自检

新手最容易踩的坑是「以为改了配置但没生效」。这时候用 `dsh --profile web --dump-config` 把最终合并树打出来——你想要的那个值，在树里是不是你期望的值？是 = 生效。不是 = 哪一层覆盖了，逐层排查。

这是个值得养成习惯的动作：改完配置 → dump-config 验证 → 跑 Agent。三步缺一不可。DSH 的「毛坯」也体现在这里：它不自动帮你校验，要你自己用工具查。

10.4 图解：dsh CLI 参数全景

11.1 正面反应：「Agent 领域的 Linux？」

DSH 发布后，社区最热的比喻是「可能成为 Agent 领域的 Linux」。这个说法的逻辑链条是这样的：Linux 不限定你用什么 GUI、什么桌面环境、什么包管理器——它只提供内核和模块化接口；同样，DSH 不限定你用什么模型、什么 UI、什么工具——它只提供 Agent 内核和插件接口。两者都把「选择权」交还给用户。

但是，这个类比有一个容易被忽略的断裂点。Linux 之所以成功，不是因为它「模块化」，而是因为它有足够多的模块供选择——GNU 工具链、X11 窗口系统、apt 和 rpm 包管理、各种发行版。如果 Linux 只有一个内核、没有模块，它和 BSD 没区别。同理，DSH 能不能成为「Agent 领域的 Linux」，取决于它的生态能不能长出足够多的插件，而不取决于它的架构设计有多优雅。

11.2 「毛坯房」与「乐高积木」：同一个产品的两种体验

有趣的是，同一些人既说它是「毛坯房」又说它是「乐高积木」。这不是自相矛盾——两个比喻指向 DSH 的不同面向。

「毛坯房」指向的是开箱体验：装完之后没有漂亮的界面、没有预设的模型、没有一键上手向导。你需要自己配 API Key、自己选模型、自己理解配置层叠。对于习惯了 Claude Code 「装完就用」体验的开发者来说，DSH 的第一印象确实像走进了没有装修的房间。

「乐高积木」指向的是上限体验：一旦你理解了插件机制，就能拼出各种组合——换模型、换工具、换 UI、换沙箱策略。这种自由度给人「创造工具的乐趣」，像玩乐高一样。

这两个比喻合在一起揭示了 DSH 的产品定位：建设工具而非成品工具。它不想成为「最好的 Agent 产品」，而是想成为「让你造最好的 Agent 产品的那套工具」。这个定位决定了它的早期用户画像是「愿意折腾的开发者」，而不是「想快速解决问题的用户」。

11.3 主要批评：门槛、文档与稳定性的三重质疑

社区的批评集中在三个方面：

1. 上手门槛高：配置层叠五层、profile 是什么、模型怎么配——这些概念对没有 Koishi/Cordis 经验的开发者完全不透明。有用户在 GitHub Issue 里直言「文档像写给已经会的人看的」。这是 v0.1 的真实代价：架构太灵活，文档来不及把所有路径讲清楚。
2. 文档不足：README 覆盖安装和基本启动，但「怎么自己写一个插件」「profile 的 cordis.patch.yml 到底写什么」这些关键问题没有系统文档。官方在公告里说会逐步补齐，但 v0.1 阶段开发者只能靠读源码来理解。
3. 稳定性未知：开发者预览版意味着 API 可能随时改、插件接口可能不兼容、可能有未发现的 bug。对想认真基于 DSH 做产品的团队来说，「v0.1」这个标签是最大的劝退信号。

这些批评不是否定，而是「先决条件缺失」——架构有潜力，但支撑架构的基础设施（文档、示例、社区模板）还没有跟上。DeepSeek 团队接下来的关键工作不是加功能，而是补文档和养示范项目。

11.4 生态对比：开放工坊 vs 精致商业产品

社区的讨论往往绕回 DSH 和 Claude Code 的对比。我在第 8 章讲过技术层的差异，这里从生态维度来看：

这张表最关键的行是最后一行。Claude Code 的天花板是确定的——你知道 Anthropic 的产品哲学和商业策略，就能预测它不会开放哪些东西。DSH 的天花板是不确定的——它可能变强（如果生态爆发），也可能变弱（如果 DeepSeek 团队失去投入动力或社区没跟上）。「不确定」对保守的企业用户是风险，对乐观的开发者是机会。

11.5 黑色鲸鱼的信号

一个小的但值得注意的细节：DSH 的标志是黑色鲸鱼，和 DeepSeek 模型产品的蓝色鲸鱼做了区分。这不是随意配色——它在视觉上宣告「DSH 和模型是不同的产品线」。模型解决「大脑够不够强」的问题，Harness 解决「大脑怎么和手脚配合」的问题。这种区分暗示 DeepSeek 内部对 Agent 和 Model 的定位是分开的。

从商业角度看，黑色鲸鱼还有一个功能：降低模型绑定的预期。如果标志还是蓝色鲸鱼，用户会默认「这是 DeepSeek 模型的配套工具」。换成黑色，用户更容易把它当作一个独立平台来看待——这对吸引非 DeepSeek 模型用户进生态有帮助。

12.1 文档缺口：架构太灵活，文档追不上

DSH 最直接的局限是文档。这不是小问题——因为架构太灵活（一切皆插件），「怎么用」的路径空间是指数级增长的。文档需要覆盖的不是「一条主路径」，而是「N 条路径的组合」。v0.1 阶段文档主要集中在安装和基本启动，对以下关键问题尚未覆盖：

• 怎么从零写一个插件（需要理解 Cordis 的插件注册机制）
• profile 的 cordis.patch.yml 完整字段参考
• 每种运行模式的内部行为差异（标准模式怎么调用工具 vs PTC 模式怎么传递参数）
• 会话日志的完整事件 schema（用于自定义恢复/分叉逻辑）
• 沙箱插件的配置和扩展（怎么自定义执行策略）

这些问题在 v0.1 阶段只能靠读源码解决。源码是 TypeScript，质量尚可，但「靠读源码理解」和「靠文档理解」的门槛差了一个数量级。

12.2 灵活性税：每个选择都是你的责任

「一切皆插件」听起来是优势，但每多一个插件接口，用户就多一个需要做的决策。在 Claude Code 里你不需要选模型（默认 Claude）、不需要选 UI（就是终端）、不需要选沙箱策略（官方定了）。在 DSH 里，这些全是你的事。

这不是缺陷而是设计代价。Claude Code 把决策成本替你扛了，换来的是灵活性受限。DSH 把决策权交给你，换来的是你必须有足够的判断力。具体来说：

1. 模型选择成本：选哪个模型？DeepSeek-V3 还是别的？不同模型对不同任务的效果差异需要你自己测试。
2. 配置调试成本：五层配置有一层写错，行为就和预期不同。排查时需要理解全部五层的交互。
3. 插件兼容性成本：插件之间可能有隐式依赖或冲突（A 插件依赖 B 插件的某个版本，C 插件和 B 不兼容）。npm 生态的依赖地狱问题在 DSH 上同样存在。
4. 安全审计成本：开源生态意味着任何人都能发布插件。恶意插件可以伪装成有用工具。你需要自己判断哪些插件可信。

这种「灵活性税」对个人玩家是可接受的成本，但对企业团队是实打实的工程负担。团队需要有人专门负责插件选型、配置管理、安全审计——这些岗位在用 Claude Code 时是不需要的。

12.3 性能开销：Cordis 框架的间接层

DSH 基于 Cordis 4.0.1，一个通用插件框架。这意味着每次工具调用、每次模型请求、每次会话操作，都要经过 Cordis 的插件系统间接层——注册、查找、调用、返回。这比直接硬编码的 Agent 框架多了运行时开销。

这个开销在单次交互中可以忽略（毫秒级），但在高频场景（批量处理、大规模并发）会累积。如果你要跑 1000 个并发 Agent，Cordis 的间接层可能是瓶颈之一。

不过，这个判断有一个重要的前提：我没有跑过严格的基准测试。推理依据是「通用框架通常比专用实现在高频路径上有额外开销」这个一般规律。DSH 是否真的存在性能瓶颈，需要用实际负载来测量才能下结论。我在这里只是提出存疑，不作定论。

12.4 安全模型：沙箱好但不是万无一失

DSH 的沙箱插件是一个重要的安全机制（第 6 章过过），但沙箱不是银弹：

• 沙箱逃逸：任何沙箱实现都有边界。如果模型生成的代码利用了运行环境的漏洞（如通过 Node.js 的 child_process 绕过限制），沙箱可能被突破。
• 网络隔离：沙箱默认是否阻止网络访问？如果不阻止，恶意代码可以外传数据。这取决于沙箱插件的配置，而配置又取决于用户理解了风险。
• 文件系统范围：沙箱限制的是文件系统访问范围。如果范围配错了（比如允许访问 $HOME），敏感文件可能泄露。

这些风险不是 DSH 独有的——任何能执行代码的 Agent 都有。但 DSH 的特别在于：沙箱是插件，用户可以选择不用沙箱（为了性能或便利）。这种自由度本身就是风险——人总是倾向于「先关了安全限制跑通再说」，然后忘了开回来。

12.5 版本风险：v0.1 意味着 API 可能随时变

官方公告和 GitHub 都明确标注了「Developer Preview」。这意味着：

1. 插件接口可能不兼容——今天写的插件，下个版本可能要重写。
2. 配置格式可能变——cordis.patch.yml 的字段可能会改。
3. CLI 参数可能变——--profile、--patch 的行为可能调整。
4. 可能有未发现的 bug——核心路径可能有潜在问题。

对于想基于 DSH 认真做产品的团队，v0.1 是一个需要谨慎对待的版本号。建议的策略是：先用它做原型验证，不要把生产系统绑在 v0.1 的 API 上。等 1.0 发布后，API 稳定了，再迁移到生产。

这是不是太保守了？不一定。Agent 框架和 Web 框架不同——Web 框架的 API 变了，顶多重写路由。Agent 框架的 API 变了，你可能要重定义你的 Agent 的行为逻辑，这比路由改动复杂得多。

12.6 适用性判断：现在该不该用

综合以上局限，我的判断是：

注意，这张表是 v0.1 阶段的快照。随着文档补齐、生态成熟、版本迭代，适用性会变化。我的判断基于 2026-08-15 的信息，不保证未来仍然成立。

13.1 推演一：插件市场——决定 DSH 生死的不是框架本身

我判断 DSH 未来 6 个月最关键的工作不是加功能，而是建立插件市场。原因很简单：Agent 框架的价值不是「能跑多少种模型」，而是「生态里有多少现成可用的插件」。用户不想自己写数据库查询插件、不想自己写文件搜索插件、不想自己写 Git 操作插件——他们想从市场里装一个就用。

Cordis 已经有插件市场的经验（Koishi 时期就有 marketplace），这是 DSH 的一个隐性优势——团队知道怎么做插件分发。但 Agent 插件和聊天机器人插件的需求维度不同：Agent 插件需要更多的安全审计、版本兼容、沙箱策略说明。这是一套新的工程体系，不是简单复制 Koishi 的 marketplace 就行的。

我的预测：如果 DSH 在 3 个月内上线插件市场，并在 6 个月内有 50+ 个高质量社区插件，它有机会成为 Agent 开发者的首选框架。如果 6 个月后插件市场还没起来，开发者会转向其他框架——不是因为它不好，而是因为「没有生态的框架」等同于「框架不存在」。

13.2 推演二：模型无关将变成行业标配

第 9 章我讲过「模型无关」是 DSH 的一个设计方向。我的判断是：未来 12-24 个月内，模型无关会从「某些框架的差异化特征」变成「Agent 框架的行业基本要求」。原因有三：

1. 模型成本波动：模型定价在快速变化（降价是趋势），但也可能出现某些模型涨价或限流。不绑死一个模型是应对不确定性的策略。
2. 能力差异化：不同模型在不同任务上表现不同（代码生成用 A、推理用 B、摘要用 C）。多模型组合比单一模型更适合复杂 Agent。
3. 企业合规：不同企业的合规要求不同——有的只能用私有部署模型，有的可以用云端但要符合数据驻留法规。模型无关让 Agent 框架能适配多种合规场景。

如果这个推演成立，DSH 的先发优势在于：它从一开始就按模型无关设计，不像某些框架要「后期改造」。但先发优势不等于胜势——如果竞品能更快做到模型无关 + 更好体验，DSH 的架构优势会被对冲。

13.3 推演三：沙箱安全将成为关键竞争维度

Agent 能执行代码，意味着安全风险是真实的。目前各家框架的沙箱策略差异很大——有的很强（完全容器隔离），有的很弱（只限制目录访问），有的干脆没有。随着 Agent 在企业生产场景的渗透，安全审计会成为采购决策的核心因素。

DSH 的优势是沙箱是插件（可以替换、升级、定制），劣势是没有默认的最强安全配置。如果 DeepSeek 能提供一个「企业安全沙箱插件」（容器级隔离 + 网络白名单 + 操作审计 + 合规报告），这对企业采购者是一个强卖点。

我的预测：到 2027 年，Agent 框架的安全模型会成为比性能更重要的竞争维度。因为性能差异在缩小（模型进步太快），但安全事件是「一票否决」的——一次代码注入导致数据泄露，整个产品可能被禁用。

13.4 三个门槛：DSH 要成功需要跨越什么

综合前面所有章节的分析，我认为 DSH 要从「有潜力的 v0.1」变成「主流 Agent 框架」，需要跨越三个门槛：

1. 文档门槛：从「靠读源码理解」到「靠文档上手」。需要完整的 API 参考、插件开发指南、配置字段清单、至少 5 个端到端示例项目。时间窗口：3-4 个月。
2. 生态门槛：从「官方插件为主」到「社区插件占据半壁江山」。需要上线插件市场、建立审核机制、种子 50+ 个高质量插件。时间窗口：6-12 个月。
3. 信任门槛：从「开发者预览」到「团队敢放生产」。需要发布 1.0、承诺 API 向后兼容、建立安全基线、出几个标杆用户案例。时间窗口：9-12 个月。

三个门槛不是串行的——应该并行推进。但优先级是文档 > 生态 > 信任。因为没有文档，生态长不起来；没有生态，没有标杆案例；没有标杆案例，信任无从建立。

文档门槛 ──→ 生态门槛 ──→ 信任门槛
(3-4月)       (6-12月)      (9-12月)
    │              │              │
    ▼              ▼              ▼
 API参考        插件市场        1.0发布
 开发指南       审核机制        兼容承诺
 示例项目       50+插件        标杆案例
      

13.5 实战建议：现在就开始的 7 天上手计划

如果你看完前 12 章觉得 DSH 值得试试，这里是一份 7 天上手计划。它不追求让你成为专家，只追求让你「跑起来并且理解每一层在做什么」。

1. Day 1：装 DSH（第 10 章），跑通 `dsh web`，发一句话确认整个链路通。读 README.zh.md。
2. Day 2：跑 `--dump-config`，对照第 3 章理解五层配置。试着用 --patch 改一个配置（比如模型默认值），再 dump 确认变化。
3. Day 3：切换 profile（web → headless → tui），体会第 4 章讲的四种模式区别。在 headless 模式下跑一次任务，观察日志输出格式。
4. Day 4：读 lib/ 目录下的源码（重点看 bin.js 和核心 Agent 循环），对照第 5 章理解循环四阶段。不需要看懂全部，能定位「模型调用在哪」「工具调用在哪」就行。
5. Day 5：配置一个非 DeepSeek 模型（比如本地 Ollama 或 OpenAI API），验证第 9 章讲的模型无关。体会「换模型不动框架」是什么感觉。
6. Day 6：尝试理解会话日志格式（第 7 章）。开一个会话，发几句话，关掉重开，验证恢复功能。如果日志是 append-only，尝试找到「分叉点」。
7. Day 7：尝试写一个最简单的自定义插件（比如一个返回当前时间的工具），挂到 Agent 上。如果跑通了，你对 DSH 的理解就超过 90% 的围观者了。

这个计划的核心思路是：每一天碰一层，七天碰完所有核心层。你不需要在第 7 天就写出复杂插件——目标只是「对每一层有手感」。有了手感，后续深入任何一层都有基础。

13.6 结语：一个值得认真对待的实验

DSH 是一个不完美但值得认真对待的项目。它不完美在于 v0.1 的文档缺失、稳定性未验证、生态未建立。它值得认真对待在于：「一切皆插件」不是营销话术，而是从 Cordis/Koishi 五年实战中长出来的工程哲学，有代码和架构支撑。

我无法预测 DSH 是否会成为「Agent 领域的 Linux」。但我可以说：如果你对 Agent 架构感兴趣，不管你最终用不用 DSH，理解它的设计决策对你都有价值。因为 DSH 提出了一组清晰的命题——模型要不要绑、工具要不要固定、UI 要不要内置、安全谁说了算——这些命题是所有 Agent 框架都要回答的。DSH 给了一份答案，你可以认同或不认同，但至少你有了一个参照系。

这，就是深度精读的意义。