夜雨聆风大家好我是郑同学。接下来的 dsh 系列要拆 DeepSeek 开源的 agent 框架。拆源码之前，这篇先当个前奏：把它跑起来、用起来，对它长什么样有个整体印象——带着印象去读拆解，每一刀都知道落在哪。
主角是 DeepSeek 官方开源的 agent 框架 DeepSeek Harness：2026-08-13 上线，到今天 9 天，GitHub 181,583 星，带 dsh-plugin 标签的插件仓库已经 10,395 个。这篇回答三个问题：怎么在十分钟里跑起来、它是什么（包括底座 Cordis 是谁家的）、生态里有什么能直接拿来用的。先上手，后拆解。
● ● ●
一、十分钟跑起来：一行命令，四步配置
上手不需要读源码。装好 Node.js，一行命令：
npx@deepseek-ai/dshweb
命令会启动 Web UI 并打印地址，默认 http://127.0.0.1:3080。想改代码跑源码版，clone 仓库后 pnpm install、pnpm run build，再 pnpm dsh web。
图1：dsh 上手链路
界面起来之后还剩三步：
- 配模型
：Settings → Models，填入 platform.deepseek.com 申请的 DeepSeek API key，保存即生效，不用重启服务。想用别的模型也行，走 providers 配置，这里先不展开。 - 选工作区
：新开的网页要先把你的项目文件夹添加进来并选中，会话输入框才能用。dsh 默认用启动目录当工作目录。 - 发任务
：像派活一样下指令，比如「总结这个仓库、找出主要包」。它能读写文件、跑命令、把活分出去；需要审批的操作先弹窗，你点头才动。
图2：dsh Web UI 实测界面
上面是我本机的实测界面：输入框上方的模型选择器挂的是 GLM-5.3——自定义 provider 走 Anthropic 协议接进来的一次真实会话，headless 模式跑同一条链路也通。界面上每次有会话都会自动起标题、进左侧列表，headless 跑完的会话同样出现在里面，事后可翻。
不开界面也有 headless 模式：给它一句话，它建一个会话、干完、把答案打到终端、退出，适合定时任务和 CI 流水线：
dsh--profileheadless"run the tests"
两个使用细节值得知道：
- 会话都存在盘上
：headless 跑完的会话事后能回去翻，出问题的流水线不至于黑盒。 - 权限策略也能换
：默认危险操作弹确认，团队场景可以换成「白名单内自动放行、白名单外直接拒绝」——和换模型一样，从配置里换。
● ● ●
二、它是什么：模型负责想，剩下全交给插件
跑起来之后，回头看一眼你刚跑起来的到底是什么。
现在用 AI 主要两种用法。一种是聊天窗口：一问一答，它碰不到你的电脑。另一种是 agent（智能体）：让它读文件、改代码、跑命令，干完把结果给你——模型负责想，旁边一圈程序负责把想法变成动作。这圈程序有个名字叫 harness（运行架），dsh 就是 DeepSeek 开源的这一圈。
dsh 的特别之处一句话：这圈里的每样东西都是「插件」。接模型的是插件，管工具的是插件，记会话的是插件，连驱动整个 agent 干活的主循环也是插件。所以想换哪部分就换哪部分：模型从 DeepSeek 换成别家、给危险操作加审批、把界面换成自己的——都是换插件、改配置的事，不改程序本身。
这套插件机制是谁做的：不是 DeepSeek。 底座叫 Cordis，一个 2022 年就开源的插件框架（github.com/cordiverse/cordis），MIT 协议，在聊天机器人框架 Koishi 里已经用了好几年。
DeepSeek 把它拿进来当底座，在上面把 agent 需要的能力一件件做成插件：跑任务的主循环、接各种模型、工具的登记和把关、会话记录、给模型拼提示词。最后用一份 78 行的配置清单（dsh-base）把它们按顺序挂起来——清单里连主循环都只占一行。
这里记一个印象就够：DeepSeek 的功夫花在把 agent 拆成插件，插件机制本身是站在 Cordis 肩膀上。每一块怎么运转，接下来的源码篇逐集拆。
图3：dsh 架构速览
对着图看产品形态：公共插件（dsh-base）打底，官方组合（网页版、命令行版）叠在中间，你的个人配置压在最上面。改配置就是换产品——网页版和命令行版共用同一套底层。想不启动就看最终叠出来的样子，加个 --dump-config 参数就行。这不是宣传话术，启动器自己就这么介绍的，本机实测 npx @deepseek-ai/dsh --help 的第一句：
dsh: boot a DeepSeek Harness profile — an ordered stack of
plugin-bundle patch layers under your own overrides.
直译过来：dsh 启动的是一个 profile——一叠按顺序排好、压在你个人配置底下的插件层。帮助里还有两条后面会用到：--patch 能临时多挂一层配置，plugin 子命令用来装插件。
一个要先说清的状态：dsh 处于开发者预览阶段，官方明示未来会有破坏兼容性的变更。尝鲜随意，生产接入先锁版本。
● ● ●
三、第一个插件：apply 一个函数的事
用别人的 dsh 是使用，给 dsh 挂自己的能力是插件，门槛低到只差一个函数。插件就是一个 TypeScript 模块，导出一个 apply 函数，框架加载时把 ctx 上下文传进来，你往上面注册能力：
importtype { Context } from'@deepseek-ai/cordis'
exportconstname='hello-plugin'
exportfunctionapply(ctx:Context) {
// 依赖就绪后框架才会调 apply
console.log('[hello-plugin] plugin loaded!')
}
加载它不用改任何源码。写一个三行的配置文件，把你的插件登记进去（就是前面说的压在最上面的个人配置层），启动时挂上：
- insert:
- id: hello
name: '/absolute/path/to/scratch-plugin/src/my-plugin.ts'
pnpmdshweb--patch./scratch-plugin/cordis.yml
刷新页面，终端里就会打出那行 loaded。注意路径要写全（绝对路径）：这份登记文件不负责找文件，路径给错就挂不上。
清理是自动的。通过 ctx 注册的东西——事件监听、工具、定时器——插件卸载时框架统一回收，不用手动清；网络连接这类要自己收尾的资源，用 ctx.effect() 把收尾动作登记出去，卸载时框架替你执行。
装别人的插件更简单：dsh plugin 一条命令，后面接平时装包的参数就行。
● ● ●
四、生态：九天长出来的插件宇宙
一个框架上线 9 天攒 18 万星不稀奇，稀奇的是生态跟着一起长起来了：topic:dsh-plugin 标签下 10,395 个仓库，社区还做了插件商店（dsh.deepseek404.com）收录全量。
图4：dsh 生态地图
高星插件按用途看，几类最猛：
两个观察。一是Skill 类和记忆类是高星主力——生态在往「给 agent 加经验和记忆」的方向长，和把做法写成文件、按需加载的思路完全同路。二是大厂进场了：火山引擎的上下文数据库直接以插件形态接入，说明「插件」这个接口正在变成 agent 生态的通用插槽。
一万多个仓库怎么挑，三条筛选标准：
- 看更新时间
：dsh 还在开发者预览阶段、明示会有破坏性变更，三个月没跟版本的插件大概率接不上当前内核。 - 看改得深不深
：只在提示词、工具上做加法的插件最稳；替换主循环、改会话记录这种动筋骨的，dsh 一升级最容易断。 - 看它依赖谁
：只用 Cordis 公开接口的插件活得久，扒着 dsh 内部实现不放的容易跟着升级失效。
学习资源列一下：菜鸟教程有带架构图解的社区插件页，知乎有实现原理解析和 11 个热门插件推荐，CSDN 有保姆级教程，腾讯云开发者有组合方式解读，DEV.to 有配视频的插件开发实操。
官方渠道是 GitHub Discussions，README 里挂着企微群和团队公众号的入群二维码；给插件仓库打上 dsh-plugin 标签，就能被插件商店发现。
● ● ●
五、和 Pi 什么关系：两条路线，一个共识
常被问到 dsh 和 Pi 怎么选。两个都是 TypeScript 写的 agent harness，都信「harness 只做执行设施、让模型专心想」，路线相反：dsh 是什么都能换，代价是概念多、上手要先理解插件这套东西；Pi 是够用就好，只内置 7 个工具、给模型的常驻指令只有几百 token，跑分却进了 Terminal-Bench 2.0 前列，代价是想深度定制得自己写代码。
一句话选型：要做产品形态、每一层都要定制，选 dsh；要轻快贴身的个人终端助手，选 Pi。
图5：dsh vs Pi
● ● ●
入场三步
- 先跑起来
： npx @deepseek-ai/dsh web，配好 key 发一个任务，感受权限确认和工作区边界。 - 再装一个插件
：从插件商店挑记忆类或 Skill 类的高星插件， dsh plugin装进 profile，重启即生效。 - 最后写一个 apply
：三行代码给 agent 挂上自己的能力，体验「一切皆插件」不是口号。
前奏到这里。从下一篇开始拆源码，第一刀就切它最特别的地方：连驱动整个 agent 的主循环都是插件——一份 78 行的清单，怎么拼出一个能干活的 agent。
素材：README.zh.md（运行命令/社区入口）、docs/user/guide/index.md（Web UI 四步）、apps/cli/README.md（profile 组装四层/CLI 模式/dsh plugin）、docs/user/develop/basic/index.md（hello-plugin 与 overlay 全文）、packages/bundle/base/cordis.patch.yml（78 行清单）；实测：本机 npx @deepseek-ai/dsh --help 启动器输出（2026-08-22）+ GitHub API（181,583★/19,879 fork/10,395 个 dsh-plugin 仓库）；Cordis 出身：docs/cordis-primer.md + GitHub API 实测 cordiverse/cordis（2022-05-17 创建 / MIT / 6,995★）；Pi 对照：pi.dev 与 earendil-works/pi 公开资料 + Pi 源码篇已验证锚点。