dsh插件安全吗?工作原理与安装前检查
dsh插件会在代理权限下运行第三方Node代码,并可访问Shell、文件、凭据等扩展点。了解加载时机、工具提示注入,以及安装前如何审查插件。
什么是 dsh 插件?它能做什么?
dsh 插件是 DeepSeek Harness 加载到自身进程中的 Node 软件包。插件加载后,会在代理已有权限下,在代理能够访问的机器上运行其他人的代码。不过,安装步骤本身受到更多限制。pnpm 会在您批准前阻止依赖项构建脚本运行,CLI 参考文档也要求“添加、删除或更新 Bundle 后重启该 Profile”,因此,使用 dsh plugin 添加的插件会在下次重启时加载。通过 Web Plugins 页面安装的插件则可能立即生效。加载的插件与 Harness 的其他部分之间没有额外隔离。因此,安装插件前应先确认该代码能够访问哪些内容,以及如何将访问范围控制在最小程度。
dsh(DeepSeek Harness)是 DeepSeek AI 的开源代理 Harness,构建于名为 Cordis 的插件框架之上。中间这一点很重要,因为代理 Harness是包裹在模型外部、负责控制循环、工具和权限的程序,而插件正是在这一层加入其中。项目自己的 README 声明,一切都是插件。模型适配器是插件。您输入内容的 Web 界面也是插件。从项目外部安装的任何内容,都会进入同一棵组件树,并与项目自带组件处于同等信任级别。如果您还没有部署 dsh,请先按照在 VPS 上部署 DeepSeek Harness,然后再回来添加其他内容。
在 2026 年 8 月,代码仓库的 AGENTS.md 列出了插件可以访问的扩展点,包括:
- LLM(大语言模型):您的 API key 所使用的提供商
- Shell:bash 能力,提供 local 和 pwsh 提供商
- Filesystem:受策略控制的文件访问
- Web:搜索和获取内容的提供商
- Subprocess:进程树提供商
- Workflow:工作线程
- Subagent:委派给其他代理
- Settings and credentials:已保存的配置和环境变量
此后,该列表已从 AGENTS.md 移除。截至 2026 年 11 月 17 日,项目的 docs/architecture.md 改为列出扩展点,并在 model、tool、shell、filesystem 和 subagent 接口之外,增加了沙箱后端、持久终端、后台任务、人工命令以及由 webhook 触发的会话。
插件还会在 ctx.tools 上注册工具。文档明确说明,已注册工具的 schema 会参与提示组装。第二部分经常被忽略。插件无需在自身代码中执行异常操作,也能改变代理的决策,因为插件提供的描述会成为模型读取的文本。这与针对编码代理的提示注入属于同一类问题,但有一个区别:这些文本会在安装插件时加入,并持续存在,直到您删除插件。
dsh 如何查找和加载插件?
不存在全局插件目录。运行中的 dsh 是在启动时由多个有序层组合而成的插件树,保存这些选择的单元称为配置档。$DSH_HOME 默认为 ~/.dsh,每个配置档都位于 $DSH_HOME/profiles/<name>。web 和 headless 配置档会在首次使用时根据随软件发布的模板自动创建。
配置档目录包含两个决定全部内容的文件:
package.json,其中包含树外插件依赖项,以及一个dsh.profile清单;该清单记录有序的bundles列表cordis.patch.yml,您在这些软件包之上添加的自定义补丁层
ls ~/.dsh
ls ~/.dsh/profiles/web启动时按以下顺序应用各层,后应用的层优先:
- 空根层
- 配置档中的软件包,顺序以清单中的列表为准
- 配置档的
cordis.patch.yml $DSH_HOME/cordis.patch.yml- 命令行传入的所有
--patch <path>覆盖层
以下两个标志可以在不启动任何内容的情况下打印组合结果:
dsh --profile web --dump-default-config
dsh --profile web --dump-config--dump-default-config 只打印软件包层。--dump-config 会加入配置档层、主目录补丁层以及所有 --patch 覆盖层,因此它最接近对下一次启动将加载内容的完整清单。在信任一台继承来的机器之前,请先查看它。
关于这些补丁文件,还需注意一点。这里的配置并非静态数据,因为其格式允许在插件的 config 块中使用带 !!js 标记的值。论坛帖子中复制的 cordis.patch.yml 片段就是代码,因此应像对待同一来源中的 shell 脚本一样谨慎。
dsh plugin add 实际运行什么?
dsh plugin --profile <name> <args> 会将参数转发给该配置文件目录中的 pnpm,因此 PATH 中必须包含 pnpm。这里使用的是 pnpm 的命令:
dsh plugin --profile web add '<package-or-git-spec>'
dsh plugin --profile web remove '<package-name>'
dsh plugin --profile web why '<package-name>'
dsh plugin --profile web update因此,安装 dsh 插件的安全模型,就是安装任何 npm 风格依赖项的安全模型,另外还多一步:安装结果会被加载到您的代理程序中。该软件包会携带自己的依赖树,依赖树中的每个软件包最终都会运行在同一进程中。npm 供应链攻击如何到达服务器中介绍的内容在这里同样适用,无需修改。
pnpm 10 及更高版本默认不会运行依赖项的构建脚本。您可以通过 pnpm approve-builds 或 allowBuilds 设置按软件包批准执行。pnpm 11 用 allowBuilds 替换了旧的 onlyBuiltDependencies 设置,因此在当前 pnpm 中,仍使用 onlyBuiltDependencies 的指南或旧配置不会批准任何内容。检查您安装的 pnpm 版本:
pnpm --version您会首先在托管于 Git 的插件中遇到这种情况。CLI 参考文档说明,发布源代码的 Git 插件会在安装期间通过其 prepare 脚本进行构建,因此第一次 add 会失败,并显示 pnpm 的 allowBuilds 提示。将输出的密钥复制到配置文件的 pnpm-workspace.yaml 中,然后重新运行。批准该密钥后,代码仓库的构建过程就会以您的用户权限运行。已构建的软件包和本地检出不需要批准。
保留这一默认设置是有价值的,但它也是生态系统中最容易被过度解读的安全功能。被阻止的构建脚本会阻止代码在安装期间运行,但无法阻止插件本身运行,因为插件的作用就是在配置文件重启后由运行框架导入并调用;如果您使用 Web Plugins 页面,安装应用后也会立即调用。插件不需要 postinstall 钩子。您已经主动允许它加载。
安装 dsh 插件前应阅读的内容
下载已发布的 tarball 并阅读其内容。解压归档文件不会执行任何操作。
npm pack '<package-name>@<version>'
tar -tzf '<package-name>-<version>.tgz'
tar -xzf '<package-name>-<version>.tgz'
less package/package.jsonpackage.json 中的 4 个字段可以提供大部分必要信息。阅读 scripts,了解 preinstall、install 和 postinstall 条目。对于不认识的名称,或与已知名称仅相差 1 个字符的名称,阅读 dependencies。对于软件包希望添加到 PATH 的内容,阅读 bin。阅读 main 或 exports 查找入口文件,然后打开该文件并继续检查。
接着阅读实际会被加载的代码。一个声明提供通知工具的插件,没有理由读取 ~/.ssh、调用你从未听说过的主机,或启动 shell。如果软件包只提供捆绑或压缩后的 JavaScript,而公共代码仓库中没有对应的源代码,那么这已经说明了问题。优先选择可以阅读源代码的插件,并优先选择规模较小的插件。
你也可以在不安装任何内容的情况下查询注册表:
pnpm view '<package-name>' dependencies
pnpm view '<package-name>' versions一个上周发布、只有 1 个版本、没有 repository 字段,且名称仿冒热门软件包的包,是任何注册表中最常见的老把戏。使用校验和验证下载内容是紧密相关的做法:在允许运行之前,明确知道你下载的内容。
固定版本并保留 lockfile
浮动版本范围意味着,agent 进程中的代码可能在任何一次安装或更新时发生变化,而无需经过您的决定。请固定版本。
dsh plugin --profile web add --save-exact '<package-name>@<version>'不同 pnpm 版本的参数位置可能不同,因此请检查结果,不要盲目信任命令。随后打开 profile 的 package.json,确认依赖项显示为不带 ^ 或 ~ 前缀的纯版本号。该文件决定实际安装的内容。
然后保留 lockfile。它固定整个传递依赖树,而不只是顶层名称:
find ~/.dsh -maxdepth 3 -name 'pnpm-lock.yaml'将其与 profile 的 package.json 一起复制到备份位置。这两个文件可以在新服务器上重建相同的依赖树。只有在决定切换版本时才运行 dsh plugin --profile web update,不要把它作为例行清理操作;运行后请检查 lockfile 的差异。
对于从 git 而不是 registry 安装的插件,请固定 commit,而不是分支。github:owner/repo#<full commit sha> 形式的规范会提供固定的依赖树。分支名称会让 pnpm 在下次解析时采用该分支当时包含的内容,这相当于把决定交给了其他人。harness 本身也要求采用相同的规范,因为 npm latest release 是候选版本;未固定的安装可能在任意一天解析到不同版本,这正是大多数 dsh 安装和版本错误 的来源。
插件市场,以及“精选”到底有什么价值
dsh 提供插件市场,并将其作为插件安装。这说明了它的架构设计:
dsh plugin --profile web add dshmarket重启后,在 dsh 0.2.1 及更高版本中,插件市场会作为 Plugins 页面上的一个选项卡显示在 Installed 旁边;较旧的主机则需依次进入 Settings 和 Plugin Market。其 README 明确说明了限制条件。插件只能从精选注册表列出的来源安装,其他来源都会被拒绝。默认情况下会阻止构建脚本;启用构建脚本时,必须逐个软件包批准。终端插件在加入 Web 配置文件前会被标记。最重要的一点是,列出插件并不表示认可,因为这些插件由第三方提供。该 README 还说明,通过插件市场安装的大多数插件在刷新页面后即可生效,无需重启。因此,一键安装的插件可能在几秒后就在您的代理中运行。
精选列表可以提高最低安全标准,但不会替您审查代码,也无法判断维护者账号易主后,插件下一个版本会执行什么操作。请像对待同一作者提供的 curl | bash 一样对待一键安装。README 中还有一句值得重复:导出的备份可能包含您个人配置中的凭据,因此绝不要将其附加到公开 issue 或粘贴网站。如果您需要的是起始列表,而不是方法,请参阅 值得安装的 dsh 插件;这是本文的配套文章。
该框架现在也有自己的路由。Plugins 页面提供一个可切换的实验性 Custom 插件,该插件会为您自行添加的索引文件建立 bundle 索引,并增加一个由这些索引文件提供内容的 Discover 选项卡。dsh 不附带任何索引源,其文档说明索引属于第三方内容;dsh 会检查文件格式,但不会验证索引对插件标题、作者或来源的声明。
将 dsh 作为独立用户运行,而不是 root
审查可以降低恶意内容进入系统的频率。最小权限决定恶意内容进入后能访问什么。在 VPS 上,配置这一层防护的成本很低。
为该工具创建独立的 Unix 账户和独立的 home 目录,绝不要以 root 身份运行:
sudo adduser --disabled-password --gecos "" dshrun
sudo -iu dshrun在该会话中启动该工具,使其将 home 目录写入该账户下:
npx @deepseek-ai/dsh webWeb UI 默认监听 http://127.0.0.1:3080。保持此配置不变。如果您曾在另一台机器上点击输出的链接,却没有收到任何响应,请参阅dsh 输出该地址的含义了解原因。随附的 Web 组合会检查 Host 和 Origin 请求头,并要求经过身份验证的浏览器或 API Peer 才能调用每个 Host RPC 方法和 WebSocket 流;dsh web 会拒绝 --host 0.0.0.0。API 调用方通过 /connect 完成身份验证,并获得签名的 API cookie。应将此登录视为第二道锁,而不是公开 3080 端口的理由。其后运行的是一个拥有 shell 的代理,因此会话令牌泄露,或公共端口上的登录漏洞,都会向陌生人提供一个带有友好界面的无 root 远程 shell。请通过 SSH 隧道从笔记本电脑访问它:
ssh -L 3080:127.0.0.1:3080 you@your-vps然后确认没有进程监听公共地址:
ss -lnt | grep 3080本地地址应显示为 127.0.0.1:3080。如果显示为 0.0.0.0:3080,说明是随附的 dsh web 默认配置以外的设置将其绑定到该地址,例如使用了不同的组合或修改了配置;该组合负责自己的身份验证。项目文档说明,底层 Web 服务器本身不提供身份验证或 Origin 策略。因此,在确认该端口受到什么保护之前,应假设防火墙是陌生人与代理之间唯一的隔离措施,并将其移回回环地址。在 VPS 上安全运行 Claude Code的原理同样适用于 dsh。为代理提供一个允许其破坏的独立工作区目录,并将所有无法重建的数据保留在该机器之外。更稳妥的做法是将该主机视为用于代码代理的一次性 VM,因为重建 VPS 只需 1 小时,而审计一台 VPS 可能需要 1 周。
密钥存放位置,以及文件权限的局限性
dsh 将 API 密钥保存在 $DSH_HOME/.credentials.yaml 中,将环境变量值保存在 $DSH_HOME/.env 中,并将模型设置保存在当前活动配置文件的 cordis.patch.yml 中。本指南于 October 2026 首次提交时,早期版本的 $DSH_HOME/settings.yaml 曾被导入一次,并重命名为 settings.yaml.imported。哪些密钥应放入这些文件中的哪一个,以及每种模式下哪些内容会实际离开本机,是配置 dsh 的 API 密钥、模型和端点所要说明的内容。在添加插件前,应先确定这些设置,因为接入的每个密钥都可能被插件读取。请先锁定这两个敏感文件:
chmod 600 ~/.dsh/.credentials.yaml ~/.dsh/.env
ls -l ~/.dsh模式 600 允许所有者读取和写入,其他用户无任何权限。在这两种表示法中都应了解这一点(chmod 的数字模式与符号模式)。但应明确它的实际作用。文件权限可防止本机上的其他账户访问这些文件,但无法防止插件访问,因为插件以文件所有者的身份运行,并且运行在读取这些文件的进程中。因此,让 AI 代理无法接触机密信息意味着根本不要将机密信息放在本机上。运行 dsh 的主机应只保存它所需的那个模型密钥。云凭据和签名密钥应存放在其他位置。
为什么读取网页的插件会改变威胁模型
Web 接口为插件提供搜索和抓取服务。插件将网页加载到会话中时,加载的是攻击者可以写入的文本。模型提示不会区分指令和数据,因此抓取的网页可能包含一行直接写给代理的指令;而持有 shell 能力的执行框架只需代理执行一步,就可能运行该指令。
执行框架中已经提供了控制机制。dsh-base 是 web、headless、sdk 和 acp 配置的共享首个组件包,其中包含沙箱和审批策略(sdk-minimal 配置明确不包含这些内容)。请使用它。能够抓取不受信任网页的会话,应要求对所有写入或执行操作进行审批,这样抓取到的指令就无法自行变成操作。通过审批限制代理操作介绍了如何确定这条边界的位置。这种关系也是双向的,因为您自己的服务器也是其他代理会抓取的网页;相关内容请参阅在您的服务器上阻止 AI 爬虫。
如何检查插件更改了哪些内容?
先创建快照,安装插件,再创建快照,然后查看差异。
dsh --profile web --dump-config > /tmp/dsh-before.txt
dsh plugin --profile web add '<package-name>@<version>'
dsh --profile web --dump-config > /tmp/dsh-after.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after.txt差异会显示安装过程向组合树中添加了哪些插件条目。只有声明了 bundle patch 的软件包才会加入该树;普通依赖不会在此处添加任何内容,dsh 会对此发出一次警告。如果你为某个小功能安装的插件添加了多个无法说明用途的条目,应先停止操作并阅读源代码,再启动该插件。dsh plugin --profile web why <package-name>回答了另一个问题:哪些直接依赖拉取了指定软件包。
已安装的软件包位于配置文件自己的 node_modules 中,路径为 $DSH_HOME/profiles/<name>/node_modules,因此也可以直接查看磁盘上的树:
ls ~/.dsh/profiles/web/node_modules保留一个从不进行实验的第二配置文件。当某次安装破坏测试工具时,启动 dsh --profile <clean-name> 即可在几秒内判断是否由该插件导致。
如何移除 dsh 插件?
dsh plugin --profile web remove '<package-name>'
dsh --profile web --dump-config > /tmp/dsh-after-removal.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after-removal.txt移除依赖项并不总会删除配置。写入配置文件中 cordis.patch.yml 的条目会保留,因为该文件属于您,运行框架不会替您重写。打开该文件,删除其中所有列出已移除软件包的代码块。
less ~/.dsh/profiles/web/cordis.patch.yml然后处理任何卸载命令都无法解决的问题。如果您因为不再信任某个插件而将其移除,那么它能够读取的内容已经被读取。请在提供商控制台中轮换 DeepSeek API 密钥,并轮换 $DSH_HOME 中存放的其他所有密钥。然后确认该插件运行所使用的 Unix 账户能够访问您网络其他位置的哪些内容。
简明版
- 安装前阅读已发布的 tarball,从
scripts和入口文件开始 - 固定确切版本;对于 git 规范,固定确切提交,并保留 lockfile
- 安装到一个 profile 中,并保留一个干净的 profile,以便出现问题时启动
- 每次安装前后都对比
--dump-config - 使用独立的 Unix 用户运行 harness,仅监听 loopback,并通过 SSH 访问
- 在服务器上只保留一个 API key;移除不再信任的插件当天轮换该密钥
这些都不是避免使用插件的理由。插件模型正是 dsh 有用的原因,而无法扩展的 harness 终究需要替换。这样做是为了明确安装了什么、来自谁、使用哪个版本,并将整个系统运行在可以重建的环境中。
FAQ
dsh 会将插件彼此隔离吗?
不会。Cordis 会将插件加载到 harness 进程中。插件可以访问文档规定的能力接口,包括 shell、文件系统、Web、subprocess、subagent 和凭据。dsh-base 是 web、headless、sdk 和 acp 配置的共享首个 bundle,其中包含用于规定 agent 工具可执行操作的 sandbox 和审批策略。您的保护措施来自这项策略。插件之间没有独立的权限边界。因此,准确的安全模型是:安装插件就意味着您需要信任其作者,以及其依赖树中的每个 package。
可以在不运行安装脚本的情况下安装 dsh 插件吗?
pnpm 10 及更高版本默认会阻止依赖项的构建脚本。dsh plugin ... add 会转发到 pnpm,因此在当前版本的 pnpm 中,除非您批准相应 package,否则安装不会运行 package 脚本。使用 pnpm --version 确认版本。未读取的插件仍然不安全。harness 加载插件后,插件自身的代码就会运行:对于通过 dsh plugin 安装的插件,这通常发生在下一次 profile 重启时;对于从 Web Plugins 页面安装的插件,则通常会立即运行。安装时的限制不会影响这一点。
dsh 插件及其配置实际存放在哪里?
$DSH_HOME 默认使用 ~/.dsh。Profile 存放在 $DSH_HOME/profiles/<name> 中。每个 profile 都包含一个 package.json,其中有该 profile 的插件依赖;还包含按顺序排列的 bundle 清单 dsh.profile,以及补丁层 cordis.patch.yml。已安装的 package 存放在各 profile 自己的 node_modules 中,具体路径为 $DSH_HOME/profiles/<name>/node_modules。密钥存放在 $DSH_HOME/.credentials.yaml,环境值存放在 $DSH_HOME/.env,而用户主目录级别的 $DSH_HOME/cordis.patch.yml 会应用于所有 profile。运行 dsh --profile web --dump-config 可查看组合后的结果,无需启动。
从 dsh 插件市场安装是否安全?
该市场只允许从经过筛选的 registry 安装,并且除非您逐个 package 批准,否则会阻止构建脚本。这比从聊天窗口粘贴 package 名称已有实际改进。不过,市场自己的 README 仍明确说明,列出插件不代表认可,因为这些插件是其他人编写的第三方代码。请阅读源代码并固定版本。将 harness 运行在您能够承受其被攻破损失的用户账户上;理想情况下,也应运行在您能够承受其被攻破损失的机器上。