DeepSeek Harness 深度精读 DeepSeek Harness Deep Read

0.1 DSH 是什么：从 README 说起

打开 @deepseek-ai/dsh 的 README，第一句话就定了调：「dsh 是 DeepSeek Harness 中用于启动 profile 的命令；profile 由多个插件组合包 patch 层按顺序叠加而成，其上再应用用户自己的覆盖配置」。这不是一个 API，不是一组模型权重，而是一个插件编排框架——它定义的是「如何组合插件」，而不是「如何调用模型」。

这个定位很关键。DeepSeek 之前开源的都是模型（V3、R1、V4），这次开源的是如何使用模型的工具链本身。MIT 协议意味着你可以自由地用它、改它、拿它做自己的产品。仓库地址是 deepseek-ai/deepseek-harness。

Profile（Profile）：DSH 的运行单元。一个 profile 目录包含 package.json（插件依赖）和 cordis.patch.yml（用户的配置覆盖层）。dsh web 就是 --profile web 的别名，启动 Web 界面；dsh --profile headless "任务" 则运行一个无头会话，打印结果后退出。

Bundle（Bundle）：一组插件的预组合包。dsh.profile.bundles 列表定义了叠加顺序——先从 dsh 安装目录解析内置 Bundle（dsh-base、dsh-web-app、dsh-headless），再从 profile 自身的 node_modules 解析外部插件。配置树以空根为起点，依次叠加每个 Bundle 的 patch 层。

0.2 为什么默认「空」：Cordis 的设计哲学

如果你第一次启动 dsh web，看到的界面可能远不如预期「丰富」——没有侧边栏文件树、没有一键部署、没有现成插件市场。这不是偷工减料，而是 Cordis 架构的直接后果。

这种设计直接来源于 Cordis 论文的核心思想。论文提出了两个正交维度：时间可组合性（移除组件时能完全回退其副作用）和空间可组合性（能声明并响应式管理组件间依赖）。DSH 的「空根 + 插件层叠」就是这两个维度在工程上的外化：每个插件都是一个 Cordis Fiber（组件实例），可以被加载、卸载和热替换，且卸载时所有副作用（事件注册、服务绑定、状态变更）都会被有序回退。

代价当然也很真实：上手门槛高。你需要理解 YAML 配置、插件依赖、Profile 层叠、Bundle 解析。但这不是「缺陷」——这是把可组合性放在首位时的必然代价。操作系统也有进程粒度的时间可组合性，但代价是每次重启丢弃所有进程本地状态；Cordis 把这个粒度细化到进程内的组件级别，代价则是用户需要自行组合。

0.3 为什么这份精读值得做

目前能找到的 DSH 资料，多数停留在「它开源了、一切皆插件、有四种模式」的复述层。这个页面要做的是把这些概括性表述拆开：插件系统长什么样（Cordis 核心库 + 加载器 + HMR）、配置怎么合并（Profile 层叠机制）、Agent 循环如何运转（dsh-agent-loop 驱动器）、会话日志为什么只能追加（事件溯源架构）、四种模式到底差在哪。这些机制层面的东西，才是你判断「DSH 值不值得用」的素材。

这份精读的素材来源全部是官方原始文档：npm 包内 90+ 个子包的 README、Cordis 学术论文、以及通过 --dump-config 和 --dump-default-config 导出的实际配置树。不依赖任何第三方媒体报道，确保技术判断基于一手材料。

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

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

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

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

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 的插件运行时和容器。根据 Cordis 学术论文《A Programming Paradigm for Spatiotemporal Composibility》，它的核心贡献是提出了两个正交的可组合性维度：时间可组合性（Temporal Composibility）和空间可组合性（Spatial Composibility）。论文指出，传统框架在移除组件时无法完全回退其副作用，导致「一旦安装就难以移除」的问题；而 Cordis 通过将 effect 建模为携带显式逆函数的抽象，在运行时跟踪并通过逆函数精确回退，实现了组件移除时的完全清理。

论文还提出了 VSCode 作为反面案例：VSCode 拥有 87/100 的扩展含可执行代码，但缺乏热卸载机制——移除扩展必须重启编辑器；同时 extensionDependencies 机制几乎无人使用（7/100），说明传统的静态依赖声明在没有运行时响应式管理时形同虚设。Cordis 正是针对这两个问题提出了理论解决方案。

元框架（Meta Framework）：不直接提供业务功能，而是提供「如何组织功能」的框架。Cordis 不帮你写对话、不帮你调模型，它只负责：谁先加载、谁依赖谁、配置怎么合并、事件怎么广播。论文将这种抽象形式化为统一上下文 Γ∞ = μΓ. Γ × (Γ → Γ) × Σ，其中 effect 和 coeffect 被统一为单一类型。

2.2 论文核心理论：Revertible Effects 与 Reactive Coeffects

Revertible Effects（可逆效应）：论文将 effect 建模为 Γ → Γ × (Γ → Γ)，即每个 effect 不仅产生状态变更，还携带一个显式逆函数 Γ → Γ。运行时跟踪所有已执行的 effect，当组件被卸载时，按逆序应用逆函数，精确回退该组件产生的所有副作用。这就是时间可组合性的实现机制——移除组件时，它注册的事件监听器、服务绑定、状态变更全部被回退，系统状态等价于这个组件从未被加载过。

Reactive Coeffects（响应式协效应）：论文将依赖建模为规约（specification）而非静态引用。当 context 发生变更时，变更被分类为 activating（激活新依赖）、deactivating（取消旧依赖）或 neutral（无影响），运行时根据分类决定是否需要重新解析依赖关系。这就是空间可组合性——插件的依赖不是硬编码的 import，而是声明式的规约，当环境变化时自动响应。

在 Cordis 核心库（@deepseek-ai/cordis README）中，这两个理论概念被实现为具体的 API：ctx.effect() 用于注册带逆函数的 effect，ctx.set() 用于声明响应式状态，Fiber 生命周期管理组件的创建与销毁。这些 API 构成了 DSH 插件系统的编程接口。

2.3 DSH 与 Cordis 的版本关系

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

这意味着两件事：第一，DSH 的插件格式就是 Cordis 插件格式，意味着你理论上可以复用 Cordis 生态里已有的插件（如果接口兼容）；第二，Cordis README 明确列出核心 API：ctx.effect()（注册可逆 effect）、ctx.set()（声明响应式状态）、Fiber 生命周期（管理组件创建与销毁）、事件总线（广播与监听）、服务声明与获取。DSH 的 Agent 层能力（Agent 注册表、LLM 适配器、循环驱动器等）全部建立在这些 API 之上。

2.4 为什么复用比自研聪明

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

• 成熟度：论文证明的五个元理论性质（保持、时间可组合性、空间可组合性、进展、汇合）为正确性提供了理论基础，HMR 的事务性保证已在生产中验证。
• 抽象层次：Cordis 抽象的是「插件组合」这一层，与业务领域无关。无论是聊天机器人还是 Agent 编排，核心需求都是组件的加载、依赖管理、配置合并和事件广播。
• 聚焦：团队可以把精力放在「Agent 语义」（循环、工具、轨迹）而非「插件机制」。
• 理论保证：论文的汇合性质（Confluence）意味着「动态历史不留痕迹」——无论插件以什么顺序加载和卸载，最终系统状态一致。这对 Agent 的可重复性至关重要。

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-agent-loop README，DSH 的 Agent 循环由 AgentLoop 驱动器实现。这是整个框架中唯一的具体循环驱动器，负责 Turn（轮次）和 Step（步骤）的生命周期管理。每个 Turn 包含完整的「模型推理→工具调用→结果处理」循环，Step 则是 Turn 内部的细粒度执行单元。README 还描述了 Inbox（收件箱）机制——工具调用请求被放入 Inbox，驱动器按照一定策略（如并行/串行分类）取出执行。

这也解释了为什么「模式」是 profile 级的配置：换模式=换循环插件+换工具集合。PTC 模式本质上是改变了 Step 的执行策略，把多步工具调用从「逐个推理」变成「程序化批量执行」。

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 这份日志里有什么

根据 dsh-session README，会话日志记录以下内容（第 5 章讲过这些是「上下文」的来源，这里更细）：

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

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

7.3 Trajectory 视图：按来源看日志

Trajectory（轨迹）视图是基于 dsh-session README 中 Surface 投影机制的一种视图：把事件流按「来源」（source）分类展示。你想看「模型说了什么」就过滤模型来源；想看「工具执行了什么」就过滤工具来源；想看「子 Agent 干了什么」就过滤调度来源。同一个事件流，换 Surface 投影视角就有不同解读。

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

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

根据 dsh-session README，会话日志的 append-only 性质源于其事件溯源（Event Sourcing）架构。README 将会话定义为一个只追加的事件序列，并在其上定义了 Surface（投影）机制——不同的视图（如 Trajectory 视图、消息列表视图）是对同一事件流的不同投影。SessionStore 负责持久化这些事件，而 Chunk-rows 编解码机制用于高效存储和传输事件数据。

在这个架构上，四个核心操作各对应事件流的一种「读法」：

• 恢复（resume）：会话崩了重启，从事件流重放到中断点。SessionStore 保证事件已持久化，重启后可重建状态。
• 分叉（fork）：从事件流的某个时间点，复制一份继续往下，分出新的分支会话。原会话的事件流不变。
• 检索（search）：从历史事件流里按关键词或语义找到某个事件。Surface 投影机制让检索可以在特定视图上进行。
• 回放（replay）：把事件流按时间重新处理一遍，重建 Agent 的执行路径。README 的「请求头重建」机制保证了回放时模型请求的可复现性。

这四个操作不需要四种数据结构——它们都是对 append-only 事件流的不同「读法」。Surface 投影机制保证了不同视图的数据一致性，因为它们都是从同一事件流实时计算出来的。这是 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 是「一体化」产品——所有层（模型、工具、UI、会话存储）由 Anthropic 统一设计、打包、发布，用户拿到的是经过端到端调试的完整方案。DSH 是「可组合」框架——每层都是独立插件，由不同子包提供，用户或安装时自动组合或手动替换。两者面向的是不同用户群。

8.3 哪个适合你

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

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

9.1 dsh-llm 的 Provider-Neutral 架构

根据 dsh-llm README，DSH 的模型无关性通过 LlmRuntime 适配器注册表实现。README 定义了一套 Provider-Neutral 的 LLM 词汇——所有模型适配器实现统一接口（流式 API、BlockAssembler、错误分类），而不同厂商的差异（如调用格式、流的解析方式、错误码体系）被封装在各自的适配器插件里。这意味着框架核心不需要知道「当前在跟哪个模型对话」，只通过 LlmRuntime 的抽象接口操作。

真正的模型无关需要三个条件：

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

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

Model-agnostic（Model-agnostic）：系统能容纳多种模型，切换成本由配置承担而非代码承担，且切换后保持可用能力上限。这是渐变量，不是二值量。在 dsh-llm README 中，这对应 LlmRuntime 注册表 + 适配器插件的架构——换模型=换适配器插件+改配置，不改框架核心。

9.2 支撑模型无关的架构论据

从 dsh-llm README 和 DSH 架构出发，有三条支撑「模型无关」的论据：

• 模型在快速迭代：今天最好的模型半年后可能被超过。绑定=押宝；无关=可换。dsh-llm 的适配器注册表让换模型的成本仅限于实现一个新适配器。
• 开源权重繁荣：Llama、Qwen 等开源权重让用户可以本地部署，天然倾向模型无关。适配器插件可以封装本地模型的调用逻辑。
• 价格竞争：API 持续降价，用户乐见多家竞价，模型无关让用户切换灵活。

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

但也有三条相反论据：

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

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

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

根据 dsh-llm README 的架构分析：能成立，但需要生态。DSH 的 LlmRuntime 注册表从架构上保证了「模型就是插件」——任何模型只要实现了适配器接口就能接入。DeepSeek 自家模型有旗舰适配器（dsh-llm-deepseek）；其他模型需要社区或用户自己实现适配器。

本地包中已存在 dsh-llm-pi-ai 等适配器子包，说明 DSH 的模型无关不是「纸上承诺」——已有多个适配器实现。但 README 也列出了 Known Limitations：适配器的流式解析和错误分类需要针对不同模型做适配调试，不是写完接口就自动完美支持。这是「能力上限」问题，不是「架构不可能」问题。

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. 打开浏览器：访问提示的地址，看到 Web 界面（对话框+历史记录），发第一句话。

能不能立刻干活？取决于 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 子包全景：90+ 个 @deepseek-ai 包的分类

打开 DSH 的 npm 安装目录（node_modules/@deepseek-ai/），能看到 90 多个子包。每个子包都是一个 Cordis 插件（或插件的支持库），有自己的 README。按功能可以分为以下几大类：

• 核心层：cordis（元框架）、dsh（产品启动器）、dsh-base（共享 Bundle）
• Agent 层：dsh-agent（接口注册表）、dsh-agent-loop（循环驱动器）、dsh-subagent（子代理）
• LLM 层：dsh-llm（适配器运行时）、dsh-llm-deepseek、dsh-llm-pi-ai 等适配器
• 会话层：dsh-session（事件溯源日志）、dsh-goal（目标状态）
• 工具层：dsh-tool-bash、dsh-tool-fs、dsh-tool-web 等 20+ 个工具插件
• 技能层：dsh-skill（技能注册表）
• 运行时：dsh-sandbox（进程沙箱）、dsh-cordis-host-runner（动态包）、dsh-cordis-client-runner
• 编排层：dsh-workflow（工作流引擎）

这个分类不是官方文档给的——官方没有一份「子包目录索引」。上述分类是基于每个子包 README 的自我描述整理的。每个 README 都很简短（15-154 行不等），但它们合在一起构成了 DSH 架构的完整拼图。

11.2 dsh-subagent：子代理体系

根据 dsh-subagent README（154 行，是所有子包中最长的之一），子代理是 DSH 最复杂的扩展点之一。README 定义了子代理 seam（缝隙）机制，支持两种子代理模式：

• one-shot 子代理：发起方创建一个子代理，给它一个任务描述，等它完成后回收结果。适合「分区处理」场景——主 Agent 把一个大任务拆成几个子任务，并行分派。
• continuable 子代理：发起方创建子代理后保持引用，可以多次发送消息、延续对话。适合「专家咨询」场景——主 Agent 遇到特定领域问题时，调用子代理专家。

README 还定义了 Activations（激活）机制——子代理的创建和销毁由 Activation 管理，子代理的生命周期绑定到发起方的作用域。委派策略（delegation strategy）决定了主 Agent 何时创建子代理、如何分配任务、如何回收结果。集合模型（collection model）定义了多个子代理的并发管理方式。

子代理体系的架构意义在于：它让 DSH 不需要外部编排就能实现多 Agent 协作。主 Agent 通过 subagent seam 创建、调用、回收子代理，整套机制封装在 dsh-subagent 包中——这就是「插件化协作」的工程实现。

11.3 dsh-cordis-host-runner：动态包机制

根据 dsh-cordis-host-runner README（72 行），DSH 的动态包机制允许运行时加载和执行 Cordis 插件包，而不需要预装。README 描述了三个核心能力：

• node:vm 沙箱：动态包在 Node.js 的 vm 模块沙箱中执行，与主进程隔离。这提供了安全边界——动态加载的代码不能直接访问主进程的文件系统或网络。
• 浏览器半包往返：README 描述了「半包」（half-package）机制——动态包可以在 Node.js 环境中完整运行，也可以打包后在浏览器环境中部分运行（「半包」），两者之间通过消息传递往返通信。这让 DSH 的插件可以在 Web UI 和 Node 后端之间共享逻辑。
• 动态加载与热替换：配合 Cordis 的 HMR 机制，动态包可以在运行时加载、卸载和替换。这与第 2 章讲的时间可组合性直接对应。

11.4 dsh-workflow：工作流引擎

根据 dsh-workflow README（61 行），DSH 内置了一个工作流引擎 seam。工作流是「模型编写的编排脚本」——与子代理的「主 Agent 动态调用」不同，工作流是预先定义的执行流程，可以被模型或用户创建、执行、复用。

README 定义了工作流的几个关键特性：

• 失败纪律（Failure Discipline）：工作流的每一步执行状态都被记录，失败后可以从特定步骤重试，不需要从头开始。这与 dsh-session 的事件溯源架构天然契合——工作流执行本身就是事件流的一部分。
• seam 接口：dsh-workflow 提供 seam（不提供具体实现），让上层插件可以注册不同的工作流执行策略。这是「定义接口不定义实现」的 Cordis 风格。
• 模型可编写：工作流脚本由模型生成，不是手写。模型根据任务需求生成工作流定义，交给引擎执行。这本质上是 PTC 模式（第 4 章）的编排层升级——PTC 是「一次程序化调用」，工作流是「可复用的程序化编排」。

工作流引擎的架构意义在于：它将「Agent 的执行路径」从代码层面提升到了配置层面。用户不需要写代码来定义 Agent 的执行流程，只需要提供工作流定义。

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 仓库和 npm 包均明确标注了「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 的插件市场经验（有过聊天机器人场景的插件分发验证）是 DSH 的一个隐性优势——团队知道怎么做插件分发。但 Agent 插件和聊天机器人插件的需求维度不同：Agent 插件需要更多的安全审计、版本兼容、沙箱策略说明。这是一套新的工程体系，不是简单复制聊天机器人时代的 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 学术论文和五年工程实战支撑的架构哲学——从 Revertible Effects 到 Reactive Coeffects，每个机制都有形式化定义和元理论性质证明。代码和架构是真实的。

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

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