企业官网建设流程全解析

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 进程内部。

四种模式的选型可以总结成一张表：

选型的核心判断依据是三个问题：任务是一次性的还是持续的？需不需要保持会话状态？调用方是同进程还是跨进程？把这三个问题回答清楚，模式自然就定了。

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 依赖 B，B 依赖 C，C 又依赖 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?token=xxx。你需要用浏览器打开这个 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 常见问题速查表

这张表里的问题覆盖了我遇到过的八成故障。遇到新问题先查表，查不到再按排查路径走。

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 文件可以安全地提交到代码仓库，不用担心泄露密钥。这个技巧在团队协作场景下特别有用。