1. 智能体基础设施选型的核心矛盾与 dsh 的定位
智能体项目做到一定阶段，几乎都会撞上同一堵墙：原型跑通很快，但要把它变成每天能稳定运行、能持续迭代的东西，基础设施的选型就变成了绕不开的坎。我前后经手过几个不同规模的智能体项目，从最早用脚本硬拼，到后来引入各种框架，踩的坑基本集中在三件事上——运行模式怎么定、插件体系怎么管、评测闭环怎么落。dsh 这个工具之所以值得单独拿出来聊，就是因为它在设计上把这三件事捏在了一起，而不是让你自己去缝。
先把 dsh 是什么说清楚。它本质上是一个智能体的运行与编排基础设施，核心能力是提供多种运行模式来适配不同场景，同时用插件化的方式扩展能力边界，再配一套评测闭环来保证迭代质量。你可以把它理解成一个“智能体的操作系统层”——上面跑的是你的业务逻辑和模型调用，下面管的是进程、插件、会话、评测这些脏活累活。它解决的不是“怎么让模型更聪明”，而是“怎么让一个已经能跑的智能体稳定、可扩展、可度量地跑下去”。
适合谁来参考这篇内容？如果你正在做智能体开发，尤其是已经过了“hello world”阶段、开始考虑工程化落地的团队，那 dsh 的这套思路对你直接有用。如果你还在选型阶段，纠结用哪个框架搭智能体，那这篇可以帮你理清“运行模式”和“评测闭环”这两个维度该怎么评估。哪怕你最后不用 dsh，它背后的设计逻辑也能迁移到别的智能体平台上。
热词里出现的dsh: plugin tree failed to load、dsh web authentication required这类报错，其实恰恰说明 dsh 的插件体系和运行模式是有一定复杂度的，不是装完就能无脑用。我后面会专门拆这些坑。另外像dsh harness、dsh plugin --profile web add dshmarket这些命令层面的东西，也会结合实际操作讲清楚。
2. dsh 四种运行模式的拆解与选型逻辑
2.1 为什么运行模式是选型的第一决策点
很多人选智能体基础设施，第一眼看的是“支持多少模型”“插件多不多”，但真正决定你后期维护成本的，是运行模式。运行模式决定了你的智能体是跑在本地进程里、跑在浏览器里、跑在桌面端，还是跑在一个常驻的服务里。这四种形态对应的资源占用、调试方式、部署路径、安全边界完全不同。
dsh 把运行模式拆成四种，不是为了凑数，而是因为智能体的使用场景本身就分四类：开发调试、交互式使用、桌面常驻、服务化部署。你如果拿服务化部署的模式去跑开发调试，会发现自己每次改代码都要重启服务，效率极低；反过来，你拿本地进程模式去跑生产，又会发现进程管理、日志、并发全是问题。所以选型的第一步，是先想清楚你的智能体主要跑在哪个场景。
2.2 四种运行模式逐一拆解
本地进程模式是 dsh 最基础的运行形态。智能体作为一个本地进程启动，直接读写本地文件、调用本地命令。这个模式的优势是启动快、调试直接、没有网络层开销。适合开发阶段和单机任务。热词里dsh实现读取world、pdf等文档内容该如何实现这类需求，在本地进程模式下是最容易做的，因为文件系统就在手边，不需要额外的传输层。
但本地进程模式的短板也很明显：它没有天然的隔离，插件加载失败会直接拖垮整个进程。dsh: plugin tree failed to load这个报错在本地模式下尤其常见，因为插件依赖的本地环境变量、路径、权限一旦对不上，整个插件树就挂了。我的经验是，本地模式下一定要把插件加载做成“可降级”的，某个插件失败不应该让主进程起不来。
Web 模式是 dsh 通过浏览器提供交互界面的运行形态。热词里dsh web authentication required; reopen the url printed by dsh web说的就是这个模式。它启动后会打印一个带认证信息的 URL，你需要用这个 URL 打开浏览器才能访问。这个认证机制不是多余的，因为 Web 模式默认会暴露一个本地端口，如果没有认证，同网络下的其他设备就能直接访问你的智能体会话，风险很大。
Web 模式适合需要图形界面交互的场景，比如你在调试一个多轮对话智能体，想直观看到每轮的工具调用和中间状态。它的坑在于认证 URL 有时效性，而且如果你在容器或远程环境里跑，打印出来的 URL 里的 host 可能不对，需要手动改。我一般会在启动时显式指定绑定地址，避免拿到一个127.0.0.1但在另一台机器上打不开的情况。
桌面端模式是 dsh 提供的常驻桌面应用形态。热词里dsh桌面端和dsh浏览器插件经常一起出现，因为桌面端往往和浏览器插件配合使用，做网页内容的抓取和交互。桌面端的优势是它可以常驻后台，有系统级的快捷键和通知，适合把智能体当成一个日常工具来用，而不是每次都要开终端。
桌面端模式的选型逻辑是：如果你的智能体需要频繁和本地应用、剪贴板、文件管理器打交道，桌面端比 Web 模式更顺手。但它的部署和更新比服务化模式麻烦，因为你要考虑不同操作系统的打包和签名问题。我个人的做法是，桌面端只用来做个人效率类智能体，团队协作类的还是走服务化。
服务化模式是把 dsh 作为一个常驻服务跑起来，通过 API 对外提供能力。这个模式适合生产环境和多用户场景。它的核心优势是解耦：智能体逻辑和调用方分离，可以独立扩缩容、独立部署、独立监控。热词里智能体平台 架构和dsh本地部署放在一起，其实就是在讨论这个模式下的架构问题。
服务化模式的坑主要在资源隔离和并发控制上。多个请求同时进来，如果插件是有状态的，很容易互相污染。dsh 在服务化模式下会要求你明确插件的生命周期，是无状态还是有状态，是单例还是每请求一份。这个设计我觉得很务实，因为很多智能体框架在这块是模糊的，导致你上线后才发现并发一高就出诡异 bug。
2.3 四种模式的选型对照
| 运行模式 | 适用场景 | 启动速度 | 调试便利性 | 部署复杂度 | 典型坑点 |
|---|---|---|---|---|---|
| 本地进程 | 开发调试、单机任务 | 快 | 高 | 低 | 插件失败拖垮主进程 |
| Web | 交互调试、图形界面 | 中 | 高 | 中 | 认证 URL 时效与 host 问题 |
| 桌面端 | 个人效率、常驻工具 | 中 | 中 | 高 | 跨平台打包与签名 |
| 服务化 | 生产环境、多用户 | 慢 | 低 | 高 | 并发下的插件状态污染 |
这张表不是让你死记，而是让你在选型时有个对照。我的实际经验是，一个项目往往不是只用一种模式，而是开发用本地进程、调试用 Web、个人用桌面端、上线用服务化。dsh 把这四种模式都内置了，好处是你不用换工具，坏处是你得理解每种模式的边界，不然很容易在错误的模式上浪费时间。
3. 插件化体系：dsh 扩展能力的核心机制
3.1 插件树的设计意图与加载流程
dsh 的插件化不是简单的“加载一个模块”，而是一棵插件树。热词里dsh: plugin tree failed to load: dsh: plugin(s) failed to load: @deep这个报错，关键词是“tree”和“failed to load”。插件树意味着插件之间有依赖关系，父插件加载失败，子插件也不会被加载。这个设计的好处是依赖清晰，坏处是单点故障会扩散。
插件加载的流程大致是：dsh 启动时读取插件配置，解析出插件树，然后按拓扑顺序逐个加载。每个插件在加载时会声明自己的依赖、暴露的能力、需要的配置。如果某个插件的依赖没满足，或者配置缺失，加载就会失败，并且失败会沿着树向上报。
我踩过的一个典型坑是：某个插件依赖一个环境变量，但我在服务化模式下没有把这个变量传进去，结果插件树在启动时就挂了，而且报错信息只说了“failed to load”，没说是哪个变量。后来我养成了一个习惯，就是在插件配置里显式声明所有必需的环境变量，并且在启动脚本里做一次预检查，缺什么直接报清楚，而不是等 dsh 去加载时才炸。
3.2 插件安装与 profile 管理
热词里dsh plugin --profile web add dshmarket这条命令，涉及两个概念：profile 和插件市场。profile 是 dsh 用来区分不同运行环境的配置集。你可以有一个webprofile，一个desktopprofile，一个serviceprofile，每个 profile 下装的插件可以不同。这个设计很实用，因为 Web 模式下你可能只需要 UI 相关插件，服务化模式下你需要的是监控和日志插件。
add dshmarket是从插件市场安装插件。这里要注意的是，插件市场里的插件质量参差不齐，有些插件在本地进程模式下能用，在服务化模式下就有并发问题。我的做法是，任何从市场装的插件，先在本地进程模式下跑一遍基本功能，再在目标模式下做一次压力测试，确认没问题才正式用。
另外，dsh plugin --profile web add这种命令是有副作用的，它会修改 profile 的插件配置。如果你在 CI 环境里跑，要注意这个配置是否会被持久化，以及是否需要版本控制。我一般会把 profile 配置纳入 git 管理，这样换机器或者回滚时不会抓瞎。
3.3 插件开发的关键约束
如果你要自己写 dsh 插件，有几个约束必须遵守。第一，插件必须声明生命周期，是无状态还是有状态。无状态插件可以在多个请求间共享，有状态插件必须每请求一份。第二，插件必须处理加载失败的情况，不能假设依赖一定存在。第三，插件的配置必须可验证，不能等到运行时才发现配置错了。
我写过一个读取 PDF 内容的插件，热词里dsh实现读取world、pdf等文档内容该如何实现正好对应这个场景。实现思路是：插件在加载时注册一个文档读取能力，运行时根据文件类型选择解析器。PDF 用本地库解析，Word 用另一种解析器。关键点是解析要在独立的线程或进程里做，不能阻塞主进程，否则一个大的 PDF 就能把整个智能体卡住。
这个插件的坑在于，不同 PDF 的编码和结构差异很大，有些扫描版 PDF 根本没有文本层，需要走 OCR。我的处理方式是，插件先尝试文本提取，如果提取不到文本，再降级到 OCR，并且把 OCR 做成可选依赖，没装 OCR 库时给出明确提示，而不是直接报错。
4. 评测闭环：从“能跑”到“跑得好”的关键
4.1 为什么智能体需要评测闭环
智能体和传统软件最大的区别是，它的输出是不确定的。同样的输入，模型可能给出不同的结果。这就导致一个严重问题：你改了一个提示词，或者换了一个插件，怎么知道是变好了还是变坏了？如果没有评测闭环，你只能靠感觉，而感觉在智能体开发里是最不可靠的。
dsh 的评测闭环设计，核心是把“运行”和“评测”绑在一起。每次智能体运行，都会产生一份运行记录，包括输入、输出、工具调用、耗时、token 消耗。评测模块可以基于这些记录做自动评分，也可以做人工标注。评分结果会反馈到下一次迭代，形成一个闭环。
热词里【实战评测】华为云码道检视修复智能体：召回率91.3%这个例子，虽然说的是另一个产品，但评测思路是一样的：用召回率这样的量化指标来衡量智能体的效果。dsh 的评测闭环也是这个逻辑，只不过它更通用，不绑定特定任务。
4.2 评测闭环的落地步骤
落地评测闭环，我一般分四步走。第一步是定义评测指标。不同任务的指标不一样，代码生成看通过率，文档问答看准确率，工具调用看成功率。指标一定要可量化，不能是“感觉还行”。
第二步是构建评测集。评测集要覆盖典型场景和边界场景。典型场景保证基本能力，边界场景暴露潜在问题。我的经验是，评测集不要一次做太大，先做 20 到 50 条，跑通流程后再逐步扩充。一开始就搞几百条，维护成本太高，反而坚持不下去。
第三步是自动化评测。dsh 的评测模块可以对接自动化脚本，每次运行后自动打分。这里要注意的是，自动打分只能覆盖可量化的部分，主观质量还是需要人工抽检。我的做法是，自动打分做全量，人工抽检做抽样，两者结合。
第四步是反馈迭代。评测结果要能追溯到具体的运行记录，这样才能定位问题。比如某个评测集条目得分低，你要能看到那次运行的完整输入输出和工具调用，才能判断是提示词问题、插件问题还是模型问题。
4.3 评测闭环中的常见陷阱
第一个陷阱是指标太单一。只看准确率，可能会忽略延迟和成本。一个准确率很高但每次要跑 30 秒的智能体，在生产环境里可能不可用。所以指标要成组，准确率、延迟、成本一起看。
第二个陷阱是评测集过拟合。你针对评测集调提示词，调到最后评测集得分很高，但实际使用效果没提升。避免方法是定期更新评测集，并且保留一部分“隐藏集”不参与日常调优，只在版本发布时跑。
第三个陷阱是评测和运行脱节。评测在单独的环境里跑，运行在生产环境里跑，两边数据对不上。dsh 的评测闭环强调运行记录和评测记录同源，就是为了避免这个问题。我的做法是，评测环境尽量和生产环境一致，包括插件版本、模型版本、配置参数。
5. 实操：从零搭一个带评测闭环的 dsh 智能体
5.1 环境准备与安装
先装 dsh。安装方式根据你的运行模式不同而不同。本地进程模式最简单，直接按官方文档装就行。服务化模式要考虑依赖和权限，建议用独立的用户跑，不要用 root。
装完后先跑一次dsh --version确认安装成功。然后初始化一个 profile，比如dsh profile init dev。profile 初始化后会生成一个配置文件，里面包含插件路径、运行模式、评测配置等。这个文件要纳入版本控制。
热词里卸载dsh,重新安装这个组合，说明有人遇到过装坏了要重装的情况。我的建议是，重装前先把 profile 配置备份出来，因为重装可能会覆盖配置。另外，插件目录也要备份，不然重装后插件要重新装。
5.2 配置运行模式
以 Web 模式为例，启动命令是dsh web。启动后会打印一个带认证的 URL。如果你在远程机器上跑，要确保 URL 里的 host 是可达的。我一般会加参数指定绑定地址，比如dsh web --host 0.0.0.0 --port 8080，然后用实际 IP 访问。
如果遇到dsh web authentication required，说明你没有用打印出来的 URL 访问，或者 URL 过期了。重新跑一次dsh web拿新 URL 就行。这个认证机制不要绕过，绕过等于把你的智能体会话暴露出去。
服务化模式的启动命令类似，但会多一个守护进程的管理。我一般用 systemd 或者 supervisor 来管，确保进程挂了能自动拉起。日志要单独配置，不要和系统日志混在一起，不然排查问题时很难找。
5.3 安装与配置插件
装插件用dsh plugin --profile <profile> add <plugin>。比如dsh plugin --profile web add dshmarket。装完后用dsh plugin --profile web list确认插件在列表里。
如果遇到plugin tree failed to load，先看报错里提到的插件名，然后检查这个插件的依赖是否满足。常见原因是环境变量缺失、路径不对、版本不兼容。我的排查顺序是：先单独加载这个插件，看具体报错；再检查依赖；最后检查配置。
插件配置一般在 profile 配置文件里，每个插件有一段自己的配置。配置项要写清楚，不要留空。有些插件对配置项有默认值，但默认值不一定适合你的场景，最好显式写出来。
5.4 配置评测闭环
评测配置包括评测集路径、评测脚本、评分规则。评测集我一般用 JSON 或 YAML，每条包含输入和期望输出。评测脚本负责调用智能体、收集输出、计算得分。
评分规则要可配置，不同任务用不同规则。比如文档问答用精确匹配或语义相似度，工具调用用成功率。dsh 的评测模块支持自定义评分函数，你可以用 Python 写一个评分脚本，注册进去。
跑评测的命令一般是dsh eval --profile <profile> --suite <suite>。跑完后会生成评测报告，包含每条评测集的得分和总体得分。报告要存档，方便对比不同版本的效果。
5.5 运行与迭代
日常运行用dsh run或者对应的模式启动命令。每次运行都会产生运行记录，记录存在 profile 配置的目录里。评测时直接读这些记录，不需要重新跑。
迭代流程是：改提示词或插件 -> 跑评测 -> 看报告 -> 决定是否保留改动。如果评测得分提升，保留；如果下降，回滚。这个流程看起来简单，但坚持下来不容易。我的经验是，把评测跑成 CI 的一部分，每次提交代码自动跑评测，这样就不会偷懒。
6. 常见问题与排查技巧实录
6.1 插件加载失败排查表
| 报错信息 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| plugin tree failed to load | 插件依赖缺失 | 单独加载插件看详细报错 | 补依赖或调整插件顺序 |
| plugin(s) failed to load: @deep | 特定插件加载失败 | 检查该插件配置和环境变量 | 补配置或降级该插件 |
| web authentication required | 未用认证 URL 访问 | 重新启动 web 模式拿新 URL | 用打印的 URL 访问 |
| 插件运行时无响应 | 插件阻塞主进程 | 检查插件是否同步执行耗时操作 | 改为异步或独立进程 |
这张表是我实际遇到过的几个典型问题。插件加载失败最常见的原因是环境变量，尤其是服务化模式下，环境变量不会自动继承，需要显式传递。我的做法是在启动脚本里把所有需要的环境变量列出来，缺一个就报错退出，而不是让 dsh 去猜。
6.2 运行模式相关的坑
Web 模式下，如果你在容器里跑，打印的 URL 可能是127.0.0.1，在宿主机上打不开。解决方法是启动时指定--host 0.0.0.0，然后用宿主机的 IP 访问。但要注意，0.0.0.0意味着监听所有网卡，如果机器暴露在公网，一定要配合认证和防火墙。
桌面端模式下，插件可能依赖系统级的权限，比如读取剪贴板、访问文件系统。这些权限在不同操作系统上表现不一样，macOS 和 Windows 的权限模型差异很大。我的建议是，桌面端插件尽量用跨平台的库，避免直接调系统 API。
服务化模式下，并发是最大的坑。如果插件是有状态的，多个请求同时进来会互相干扰。dsh 要求插件声明生命周期，就是为了解决这个问题。但声明归声明，实现的时候还是要小心，共享的可变状态一定要加锁或者用线程安全的数据结构。
6.3 评测闭环的实操心得
评测集不要一次做太大，先做小规模跑通流程。我见过太多团队一开始搞几百条评测集，结果维护不过来，最后评测集过期了还在用。
评测指标要成组，不要只看一个。准确率、延迟、成本、稳定性，至少看四个。不同任务权重不同，但都要有。
评测结果要能追溯到运行记录。dsh 的评测模块支持这个，但你要确保运行记录保存完整。我一般会把运行记录存到独立的存储里，不要只存在本地，不然换机器就丢了。
评测要自动化，但不要全自动。自动打分覆盖可量化部分，主观质量人工抽检。抽检比例不用太高，10% 到 20% 就够，但要坚持。
6.4 插件开发的避坑清单
- 插件必须声明生命周期，无状态还是有状态，不能含糊。
- 插件加载失败不能拖垮主进程，要有降级机制。
- 插件配置必须可验证，启动时检查，不要等运行时。
- 插件里的耗时操作必须异步或独立进程，不能阻塞主进程。
- 插件依赖要显式声明，不要假设环境里有。
- 插件版本要锁定，不要用浮动版本，不然今天能跑明天就挂。
这些坑我基本都踩过，尤其是最后一条。有一次一个插件依赖的库自动升级了，接口变了，插件直接挂掉。后来我把所有依赖都锁死版本，升级时手动升，升完跑评测，确认没问题才发布。
7. 智能体基础设施选型的个人体会
dsh 这套东西，我用了大概半年多，最大的感受是它把“运行模式”和“评测闭环”这两个容易被忽视的维度做成了基础设施的一部分，而不是让你自己去拼。很多智能体框架只关心“怎么调模型”，但真正落地的时候，模型调用只是很小一部分，大头在运行管理、插件扩展、效果度量上。
四种运行模式的设计，我觉得最实用的是它让你可以在同一个工具里切换开发、调试、部署三种状态，不用换工具链。插件树的设计，好处是依赖清晰，坏处是单点故障，所以插件开发要格外小心。评测闭环的设计，是 dsh 区别于普通框架的关键，它让智能体迭代从“凭感觉”变成“看数据”。
如果你正在选智能体基础设施，我的建议是，先想清楚你的运行场景，再评估插件体系是否够用，最后看评测闭环是否完整。这三件事想清楚了，选型就不会太偏。至于 dsh 本身，它不一定适合所有场景，但它的设计思路值得借鉴，哪怕你最后用别的框架，也可以按这个思路去搭自己的基础设施。
最后分享一个小技巧：不管用什么框架，先把评测集建起来，哪怕只有 10 条。有了评测集，你后面所有的改动都有参照，不会越改越乱。这个习惯我坚持了两年，受益很大。
