1. 为什么“运行模式”才是智能体基础设施的第一性问题智能体项目做多了你会发现一个规律真正让人头疼的从来不是模型能力不够而是运行模式选错了。同一个任务用交互式模式跑得好好的换成批处理模式就各种超时本地开发环境里一切正常部署到服务端就报认证错误。这类问题我在过去一年里至少踩过七八次每次排查都要花掉半天时间。dsh 这个工具之所以值得单独拿出来聊是因为它把智能体的运行模式做成了可切换的基础设施层而不是绑死在某个框架里。它支持四种运行模式分别对应不同的使用场景同时通过插件化机制把评测闭环串起来。换句话说你不需要在项目初期就赌一个架构而是可以根据任务类型灵活切换。这篇文章适合三类人看一是正在做智能体开发、被运行环境问题反复折磨的工程师二是需要给团队搭建智能体评测体系的技术负责人三是刚接触 dsh、想搞清楚它到底能解决什么问题的开发者。我会从运行模式的选型逻辑讲起一直讲到评测闭环怎么落地中间穿插大量实操细节和踩坑记录。核心关键词先摆出来dsh、智能体、运行模式、评测闭环、插件化。这五个词贯穿全文也是理解 dsh 设计哲学的关键线索。2. dsh 四种运行模式的深度拆解与选型逻辑2.1 交互式模式开发调试阶段的主力交互式模式是大多数人接触 dsh 的第一个入口。你敲一条命令它给你一个会话窗口你在里面跟智能体对话、调试提示词、验证工具调用链路。这个模式的核心价值在于反馈周期短——改一行配置立刻能看到效果。但交互式模式有个容易被忽略的坑它的会话状态是有状态的。这意味着你在会话 A 里加载的插件、设置的变量不会自动带到会话 B。我一开始没注意这一点调试一个需要读取 PDF 文档的任务时在会话 A 里装好了文档解析插件新开会话 B 直接报plugin tree failed to load排查了二十分钟才发现是插件没在当前会话注册。实操建议是这样的交互式模式下把常用的插件配置写进 profile 文件用dsh plugin --profile web add dshmarket这种方式预加载而不是每次手动装。profile 机制相当于给不同场景预设了插件组合切换场景时不用重新配一遍。注意交互式模式不适合跑长任务。它的会话超时机制比较激进超过一定时间没有交互就会断开。如果你要跑一个需要十分钟以上的任务直接换批处理模式。2.2 批处理模式生产环境的主力选手批处理模式是我在生产环境里用得最多的。它的逻辑很简单你给它一个任务列表它逐个执行执行完输出结果进程退出。没有会话保持没有交互等待干净利落。这个模式最关键的设计是无状态。每次执行都是全新的上下文插件在启动时一次性加载完毕。这带来的好处是可靠性高——不会因为某个会话的残留状态导致后续任务出错。代价是启动开销比交互式模式大因为每次都要重新初始化插件树。我实测下来的数据一个包含 15 个插件的配置批处理模式冷启动大约需要 3 到 5 秒交互式模式首次启动差不多但后续交互几乎无感。所以如果你的任务是高频短任务批处理模式的启动开销会累积得很明显如果是低频长任务这点开销完全可以忽略。批处理模式的另一个优势是易于集成到 CI/CD 流水线。你可以把它当成一个普通的命令行工具退出码代表执行结果stdout 输出结构化数据直接对接现有的自动化体系。2.3 服务化模式对外提供能力的正确姿势服务化模式是把 dsh 跑成一个常驻服务通过 HTTP 接口对外提供智能体能力。这个模式适合需要被其他系统调用的场景比如你的业务系统需要调用智能体做文档摘要、意图识别、数据抽取。这里有一个高频报错值得单独说dsh web authentication required; reopen the url printed by dsh web.这个提示的意思是服务启动了但你没有完成认证流程。dsh 的服务化模式默认要求认证启动后会在终端打印一个带 token 的 URL你需要用浏览器打开这个 URL 完成认证之后才能正常调用接口。我见过不少人卡在这一步以为是服务没启动成功。其实服务已经跑起来了只是认证没走完。如果你是在无头环境比如服务器里部署需要把认证 URL 转发到有浏览器的机器上打开或者配置免认证模式仅限内网可信环境。服务化模式的资源占用需要提前规划。一个常驻的 dsh 服务基础内存占用在 200MB 到 500MB 之间具体取决于加载的插件数量。如果插件里有模型推理相关的组件内存占用会显著上升。建议在容器里跑设置好内存上限避免单个服务拖垮整台机器。2.4 嵌入式模式把智能体能力塞进现有系统嵌入式模式是四种模式里最灵活但也最复杂的。它允许你把 dsh 作为一个库嵌入到现有的应用程序里而不是作为一个独立进程运行。比如你的 Java 服务需要智能体能力可以通过嵌入式模式在进程内调用避免跨进程通信的开销。这个模式的复杂度在于生命周期管理。你需要自己控制 dsh 的初始化、插件加载、任务执行、资源释放。如果管理不当容易出现内存泄漏或者插件状态污染。我的建议是除非你有明确的性能需求或者架构约束否则优先选服务化模式把复杂度隔离在 dsh 进程内部。四种模式的选型可以总结成一张表运行模式适用场景状态保持启动开销集成难度交互式开发调试、提示词验证有状态低低批处理生产任务、CI/CD 集成无状态中低服务化对外提供 API 能力无状态高常驻中嵌入式进程内集成、低延迟需求可控低高选型的核心判断依据是三个问题任务是一次性的还是持续的需不需要保持会话状态调用方是同进程还是跨进程把这三个问题回答清楚模式自然就定了。3. 插件化机制dsh 评测闭环的基石3.1 插件树加载原理与常见故障dsh 的插件化不是简单的模块加载而是一棵有依赖关系的插件树。每个插件可以声明自己依赖的其他插件dsh 在启动时会解析这棵树按依赖顺序加载。这就是为什么你会看到plugin tree failed to load这种报错——树的结构出了问题。最常见的三种加载失败原因第一种是依赖缺失。插件 A 声明依赖插件 B但 B 没有安装。报错信息里会明确列出plugin(s) failed to load: deep/xxx这样的内容 后面就是缺失的插件名。解决办法很简单把缺失的插件装上就行。第二种是版本冲突。插件 A 依赖插件 B 的 1.x 版本插件 C 依赖插件 B 的 2.x 版本两者不兼容。这种情况 dsh 会在加载时报错但错误信息可能不够直观。我的经验是看加载日志里的版本号手动统一到兼容版本。第三种是循环依赖。插件 A 依赖 BB 依赖 CC 又依赖 A。这种结构 dsh 无法解析直接报错。解决办法是重构插件依赖关系把公共部分抽出来做成独立插件。实操心得遇到插件加载失败先看报错信息里有没有开头的插件名有的话就是依赖缺失直接装。没有的话用dsh plugin list --tree查看完整的依赖树定位冲突点。3.2 评测插件的接入方式评测闭环的核心是可度量。你需要知道智能体在特定任务上的表现如何才能判断改动是变好了还是变差了。dsh 的评测插件就是干这个的。接入评测插件的基本流程是定义评测数据集配置评测指标运行评测任务收集结果。dsh 把这一套做成了插件你只需要在 profile 里启用评测插件然后在任务配置里指定评测数据集和指标。评测数据集的组织方式很关键。我建议按任务类型分目录每个目录下放输入文件和期望输出文件。比如eval/ doc-summary/ input-001.txt expected-001.txt input-002.txt expected-002.txt intent-classify/ input-001.json expected-001.json这种结构的好处是直观加新用例就是加文件不需要改配置。dsh 的评测插件会自动扫描目录把输入喂给智能体拿输出跟期望输出对比计算指标。3.3 插件配置的版本管理插件配置一定要纳入版本管理。我见过太多团队把插件配置放在本地换台机器就跑不起来。dsh 的 profile 文件是纯文本的天然适合放进 Git。我的做法是每个项目一个dsh-profile.yaml里面声明这个项目需要的所有插件和配置。团队成员拉下代码后一条命令就能把环境配好。CI 流水线里也用同一个 profile保证本地和线上的环境一致。profile 文件里有一个细节需要注意插件的版本号最好锁定到具体版本而不是用 latest。智能体生态变化快插件更新可能引入不兼容的改动。锁定版本能避免“昨天还好好的今天突然跑不了”这种情况。4. 评测闭环的完整落地流程4.1 从零搭建一个评测闭环搭建评测闭环的第一步是明确评测目标。你是想评测智能体的回答准确性还是工具调用的成功率还是端到端的任务完成率目标不同评测数据集和指标的设计完全不同。以文档读取任务为例。假设你的智能体需要读取 Word 和 PDF 文档提取关键信息。评测目标可以拆成三层第一层是文档能否成功读取读取成功率第二层是提取的信息是否完整信息召回率第三层是提取的信息是否准确信息准确率。三层指标从粗到细能帮你定位问题出在哪一层。第二步是构造评测数据集。数据集要覆盖典型场景和边界场景。典型场景就是最常见的文档类型和格式边界场景包括加密文档、扫描件、超长文档、格式混乱的文档。我一般会准备 20 到 50 个用例典型场景占七成边界场景占三成。第三步是配置评测任务。在 dsh 里评测任务就是一个特殊的批处理任务输入是评测数据集输出是评测报告。配置里需要指定评测插件、数据集路径、指标计算方式。第四步是运行评测并分析结果。dsh 会输出一份结构化的评测报告包含每个用例的执行结果和汇总指标。重点看失败用例分析失败原因是智能体能力问题还是数据集问题。4.2 指标设计与数据采集指标设计最容易犯的错误是指标太多。我见过一个团队设计了二十多个指标结果每次评测报告几十页没人看得完。指标要少而精三到五个核心指标就够了。对于大多数智能体任务我推荐这几个核心指标任务完成率智能体成功完成任务的比例。这是最顶层的指标直接反映智能体能不能用。工具调用准确率智能体调用工具时参数是否正确、工具选择是否合理。这个指标能定位到工具使用层面的问题。响应延迟从输入到输出的时间。对于交互式场景延迟超过一定阈值用户体验就会明显下降。Token 消耗完成任务消耗的 token 数量。这个指标直接关系到成本。数据采集要自动化。dsh 的评测插件会在执行过程中自动记录这些数据你不需要手动埋点。但要注意评测环境的配置要跟生产环境一致否则采集到的数据没有参考价值。4.3 持续评测与回归检测评测不是一次性的要持续跑。我的做法是每次代码合并到主分支前自动触发一轮评测。评测结果跟基线对比如果核心指标下降超过阈值就阻止合并。这个机制叫回归检测。它的价值在于能及时发现改动引入的问题。智能体系统很复杂改一个提示词可能影响好几个任务的表现。没有回归检测这些问题可能要等到线上出故障才发现。dsh 的评测插件支持基线对比。你可以在配置里指定基线报告评测完成后自动计算指标变化。变化超过阈值时退出码会变成非零CI 流水线就能感知到。实操心得基线不要设得太死。智能体的输出有随机性同样的输入两次运行结果可能不同。指标波动在 5% 以内属于正常范围超过 10% 才需要关注。阈值设得太紧会导致大量误报团队很快就会忽略评测结果。5. 实操过程中踩过的坑与排查技巧5.1 插件加载失败的排查路径插件加载失败是最高频的问题。我总结了一套排查路径按顺序走基本能定位到原因第一步看报错信息。plugin tree failed to load后面通常会跟具体的插件名。如果有开头的名字就是依赖缺失直接装。第二步如果报错信息不明确用dsh plugin list --tree查看依赖树。重点看有没有标红的节点标红的就是加载失败的插件。第三步检查插件版本。用dsh plugin list --versions查看所有插件的版本对比插件文档里的兼容性说明。第四步如果以上都没问题尝试最小化复现。新建一个空的 profile只加载出问题的插件看能否成功。能成功说明是插件冲突逐个加回其他插件定位冲突源。这套路径我用了很多次基本上十分钟内能定位到问题。5.2 服务化模式的认证问题dsh web authentication required这个报错前面提过这里展开说排查方法。首先确认服务是否真的启动了——看终端有没有打印监听地址和端口。如果有说明服务正常问题出在认证环节。认证 URL 通常在服务启动后打印在终端里格式是http://host:port/auth?tokenxxx。你需要用浏览器打开这个 URL完成认证。认证成功后token 会保存在本地后续调用不需要重复认证。如果是在服务器上部署没有浏览器有两种方案一是把 URL 复制到本地浏览器打开前提是服务器地址本地能访问二是配置免认证模式在配置文件里设置auth: none但这只建议在内网可信环境使用。还有一个容易忽略的点认证 token 有有效期。过期后需要重新认证。如果你在 CI 流水线里调用服务化模式的 dsh要么配置长期有效的 token要么在流水线里自动完成认证流程。5.3 文档读取类任务的特殊处理dsh 读取 Word、PDF 等文档内容依赖专门的文档解析插件。这类插件的坑比较多我挑几个典型的说。PDF 解析最常见的问题是扫描件。扫描件本质上是图片没有文字层普通的 PDF 解析插件读出来是空的。解决办法是接入 OCR 插件先做文字识别再解析。但 OCR 的准确率受图片质量影响很大模糊的扫描件识别效果很差。Word 文档的坑主要在格式兼容性。.doc和.docx是两种完全不同的格式解析插件可能只支持其中一种。遇到.doc文件读不了先确认插件是否支持不支持的话需要先转成.docx。还有一个通用问题是文档大小。超长文档比如几百页的 PDF解析时会消耗大量内存和时间。我的做法是设置分页解析每次只解析一部分解析完释放内存再解析下一部分。dsh 的文档解析插件支持配置分页参数具体参数名看插件文档。5.4 常见问题速查表问题现象可能原因排查方法解决方案plugin tree failed to load依赖缺失或版本冲突看报错信息中的插件名安装缺失插件或统一版本web authentication required未完成认证流程检查终端是否打印认证 URL打开 URL 完成认证文档读取为空扫描件无文字层用文本编辑器打开确认接入 OCR 插件批处理任务超时单任务耗时过长查看任务日志中的耗时拆分任务或增加超时时间评测指标波动大智能体输出随机性多次运行取平均值调整阈值或增加评测样本插件配置不生效profile 未正确加载检查 profile 路径和格式确认 profile 文件被正确引用这张表里的问题覆盖了我遇到过的八成故障。遇到新问题先查表查不到再按排查路径走。6. 智能体基础设施选型的经验总结6.1 什么场景该用什么模式选型的核心是匹配场景。我按任务特征给一个参考开发调试阶段交互式模式。反馈快改配置立即生效。定时批量任务批处理模式。无状态可靠易集成。对外提供 API服务化模式。常驻服务接口调用。低延迟进程内调用嵌入式模式。避免跨进程开销。有一个常见的误区是过早优化。项目初期就纠结用哪种模式其实没必要。dsh 的模式切换成本很低改个配置的事。先用交互式模式把功能跑通再根据实际需求切换到合适的模式。6.2 评测闭环的最小可行方案如果你刚开始做智能体评测不要一上来就搞大而全的评测体系。先做一个最小可行方案选一个核心任务准备 10 个评测用例定义一个核心指标跑起来看结果。这个最小方案能帮你验证评测流程是否跑得通指标是否有区分度。跑通之后再逐步扩展用例数量和指标维度。我见过太多团队在评测体系设计上花了几周时间结果一个用例都没跑过。评测闭环的关键是持续跑。哪怕只有 10 个用例每天跑一次也比有 1000 个用例但一个月跑一次强。持续跑才能发现趋势才能及时发现问题。6.3 插件生态的使用建议dsh 的插件生态还在发展中插件质量参差不齐。我的使用建议是优先用官方插件。官方插件经过测试稳定性和兼容性有保障。第三方插件用之前先看更新频率和 issue 情况长期不更新的插件慎用。插件不要装太多。每多一个插件就多一份加载开销和潜在的冲突风险。只装真正需要的插件用不到的及时卸载。插件配置要版本化。前面提过profile 文件放进 Git锁定插件版本。这样能保证环境一致性避免“在我机器上能跑”的问题。6.4 后续扩展方向这套基础设施搭好之后有几个自然的扩展方向。一是接入更多评测指标比如成本指标、安全指标。二是把评测结果可视化做一个简单的看板方便团队查看趋势。三是把评测闭环跟告警系统打通指标异常时自动通知。我个人在实际操作中的体会是智能体基础设施的建设重点不在工具本身而在流程的规范化。工具再好如果团队不按流程走评测不持续跑配置不版本化问题还是会反复出现。把流程定下来工具只是流程的载体。最后分享一个小技巧dsh 的 profile 文件支持环境变量插值。你可以把敏感配置比如 API key放在环境变量里profile 文件里用${VAR_NAME}引用。这样 profile 文件可以安全地提交到代码仓库不用担心泄露密钥。这个技巧在团队协作场景下特别有用。