DeepSeek Harness（命令是 `dsh`）是 DeepSeek 开源的 agent harness，MIT 协议，目前处于开发者预览阶段。它值得看的地方不是功能列表，而是组织方式：整个产品没有一段"核心代码"可以改，所有东西都是插件，包括 agent 主循环本身。
先跑起来
最简单的启动方式不需要克隆仓库：
npx @deepseek-ai/dsh web默认在 `127.0.0.1:3080` 起 Web UI 并打开浏览器。SSH 环境下只打印地址，因为转发端口由 SSH 客户端或编辑器持有。加 `--no-open` 可以只起服务不打开浏览器。
想改代码就从源码跑：
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web
`pnpm run build` 准备构建产物，`pnpm dsh web` 直接用产物启动，不会重新构建。
README 里有句话要当回事：这是开发者预览，**会有兼容性破坏性变更**，跑之前先看 SAFETY.md。
一切都是插件
dsh 底下是 Cordis 这个框架。Cordis 的模型是：插件往共享的 context 里贡献三样东西——服务、类型化事件、可回退的副作用。
dsh 把这条规则贯彻得比较彻底。按官方架构文档的说法，模型适配器、工具注册表、会话日志、以及 agent 主循环本身，全都是插件，每一个都能从配置层面替换。
这跟常见 agent 框架的差别在哪：多数框架有一个核心对象，插件往里注册钩子，核心本身不可替换。dsh 反过来，没有特权核心。你要扩展，就在旁边挂一个插件；注册行为是"副作用"，插件卸载时会自动回退（unwind）。
这个设计带来的直接后果是运行时可控。换模型调用方式不用改框架内部，挂一个适配器插件；某个工具不想要了，卸载它，它注册的东西自动撤掉，不会留下悬挂状态。
profile 与 bundle
一个跑起来的 dsh 是一棵插件树，在启动时按层序拼出来。这里有两个容易混的概念。
**profile** 是一个命名的组合，存在 Harness home 目录里。它列出自己要叠哪些 bundle、装哪些树外插件、以及用户自己的 `cordis.patch.yml`。内置模板有五个：`web`、`headless`、`sdk`、`sdk-minimal`、`acp`。
**bundle** 是一种分发格式，把 Cordis 的配置行和它们挂载的代码打包在一起，好处是它插进去的东西，上面层还能继续 patch。
两者都在自己 `package.json` 的 `dsh` 字段里自我声明，一个 profile 长这样：
{ "name": "my-profile", "dsh": { "profile": ["dsh-base", "dsh-web-app"] } }
（结构示意，字段名取自文档，具体值按需填。）
`dsh-base` 是 `web`、`headless`、`sdk`、`acp` 四个 profile 共享的第一层，负责模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测。在此之上，`dsh-web-app` 加浏览器应用，`dsh-headless` 加一个无服务器的一次性 runner，`dsh-sdk-app` 加 JSON-RPC 服务，`dsh-acp-app` 加只面向自动化的 ACP 服务。
`sdk-minimal` 是刻意的例外：它自己拥有完整的显式 SDK 树，不套 `dsh-base`。
启动时的层序
启动时，层按这个顺序叠到一个空条目列表上：
- profile 里排好序的 bundle
- profile 自己的 `cordis.patch.yml`
- home 目录里的 patch
- 命令行 `--patch` 叠加的覆盖
patch 的作用方式是按 id 命中某一行，整行替换它的配置，或者插入新行。preset 类型的 patch 把同样的操作限制在某个声明的 `config.plugins` 内部，层序优先级一致。
想知道自己机器上到底是什么树，直接打印：
dsh --profile web --dump-config
它打印出来的任何一行，理论上都可以被你自己的 patch 换掉。这一点是"没有特权核心"的验证方式——如果某一行你换不掉，说明架构承诺没有兑现。
HMR 的取舍
一个很小的细节能看出设计取向：base 会启用仅配置层面的 `dsh-hmr`；`headless`、`sdk`、`acp` 都把它关掉；`sdk-minimal` 干脆不带这个插件。
交互式的 Web 应用需要热更新，而给程序调用的一次性 runner 和 SDK 服务不需要——它们没有"开发时反复改配置"的场景。profile 的 patch 可以覆盖这些默认值。
会话日志
架构文档里有一句很硬的话：**Model-visible means logged**——模型能看到的东西，必须是日志里记着的。
具体到实现，每一次模型请求都要能从会话日志重建。`deriveMessages()` 从日志投影出模型历史。每个 `assistant/message` 里嵌着产生它的那段完整流；`assistant/attempt` 保留失败、重试、取消、流错误的尝试，但这些不进模型历史。
fork、resume、transcript、遥测、持久化，全都从这些"结算"记录派生。反过来，如果进程在结算之前硬崩，就没有持久化的 attempt 流留下。
这条规则对插件开发有约束：想加新的模型可见输入，就必须定义新的会话事件；想改已有消息内容，得注册纯消息投影。绕过日志直接往请求里塞东西，等于破坏可重建性。
核心包
从架构文档的包表里挑几个关键的，能看清职责切分：
| 包 | 负责 | context 键 |
|---|---|---|
| `core/session` | 追加式 `SessionEvent` 日志与内存存储 | `ctx.sessions` |
| `core/system-prompt` | 提示词分段与工具 schema 组装 | `ctx.systemPrompt` |
| `core/tools` | 带作用域的工具注册表与受控执行管线 | `ctx.tools` |
| `core/agent` | `Agent` 接口、活注册表、`agent/*` 事件 | `ctx.agents` |
| `core/agent-loop` | 实现该接口的默认驱动器 | `ctx.agentLoop` |
| `llm/llm` | 消息与流的词汇表，以及适配器接缝 | `ctx.llm` |
注意 `agent` 和 `agent-loop` 是分开的两个包：接口和默认实现解耦，所以主循环可以换一个实现，而依赖 `ctx.agents` 的其他插件不用动。
值不值得用
官方明说处于开发者预览、会有破坏性变更。判断标准其实很简单：
适合拿来看的，是想搞清楚 agent 框架怎么组织的人，或者准备基于它做深度二次开发的人。
不适合的，是想找一个稳定生产基座的人——至少在它退出预览之前。
最后说一个取舍。把 agent 主循环做成可替换插件，代价是理解成本：你得同时理解 profile、bundle、patch 三层，才能定位"这个行为是在哪一层被决定的"。收益是任何一层都能被替换，不会被框架锁死。
这个交易划不划算，取决于你到底要不要深度定制。如果只是想调个 prompt、换个模型，那这套架构对你是负担；如果你要改的是主循环里的调度逻辑，那它给的自由度是实打实的。
