企业官网建设流程全解析

1. 为什么智能体基础设施要做选型而不是随便搭一套

1.1 先把问题说清楚：开发智能体真正缺的是什么

最近一年我接触了不少做智能体的团队，结论很一致：写一个能跑通 demo 的智能体不难，难的是让它可上线、可回归、可观测。大家普遍不缺模型调用能力，缺的是中间的这层智能体基础设施——谁能把运行方式、上下文管理、工具调用记录、插件安装、评测回放这些事统一起来，谁的项目就能少走一半弯路。

以“换个模型再跑一遍”为例。没有基础设施的情况下，你要手工改配置文件，重新启动进程，凭感觉看两轮对话，然后拍脑袋说效果变好还是变差。这还是在单机调试，如果引入多路工具调用、浏览器操作、文档解析、视觉校验，问题会成倍放大。本质上，开发智能体时我们缺的不是“写逻辑”的能力，而是“跑得可控、测得可重复、错得可定位”的能力。

这也是我在选型时最看重的东西：一个工具到底能不能把智能体的整个生命周期管起来，而不是只给一个 prompt 模板库。如果只能写 prompt，那它解决不了基础设施问题；如果连 prompt 都管不好，那就更不用谈后面的评测闭环了。

1.2 我对 DSH 的定位：不是框架，是运行壳

我第一次接触 DSH 时的第一反应是：这不就是一个命令行工具吗。真正用下来之后，我把它理解为智能体的“运行壳”。意思是你依然可以用自己熟悉的框架去设计工具的编排逻辑，但 DSH 负责接管我这个智能体怎么启动、怎么跑、怎么观测、怎么重放。

框架解决的是“脑子怎么想”，DSH 解决的是“身体怎么动”。实践证明，把这两层分开会让项目健康很多。比如团队里用 LangGraph 写了一个多步骤工作流，交给 DSH 之后，不需要改内部代码就能获得日志回放、失败恢复、批量评测这些能力。同样，今天想从 DeepSeek 换成一个兼容 API 的第三方模型，也只需要在 profile 里调配置，不用动智能体的逻辑。

DSH 还提供桌面版和命令行两套入口。CLI 适合自动化、适合 CI，桌面版适合盯着看请求链路和插件输出。对一个要落地的项目来说，这个组合很关键——调试阶段看数据、上线阶段跑脚本，两边可以同时用同一套配置，不会出现“本地好好的、线上跑不了”的撕裂感。

1.3 四种运行模式不是炫技，是四个真实场景的映射

选型的时候最容易犯的错误，是把智能体当成“一个进程”去写。单进程跑 demo 没问题，但真实世界的需求是多元的：调试需求、服务需求、批处理需求、编排需求，运行特征完全不一样。DSH 的四种运行模式——交互式、常驻服务、批量任务、编排——我理解就是对应这四个场景的答案。

先把它们放在一起对比，后面逐个拆开细说。

这个表格基本就是我的选型检查表。我会在下面把每一种模式展开讲透，包括命令、配置和实际踩坑。我的建议是不要跳读其中任何一段，因为它们之间是互相配合的，评测闭环恰恰需要把四种模式都用起来。

2. 四种运行模式的详细拆解

2.1 交互式运行模式：调试期最顺手的形态

交互式模式说白了就是 REPL，我一个命令进去，一句一句跟智能体对话，它能显示每一步的 tool call、读到了什么、模型返回了什么。刚接触的时候可能觉得这只是个聊天窗口，但真正调试智能体时才知道它多省时间。因为 LLM 的不确定性导致同样的报告任务，可能在第五步调错工具、在第八步生成错误格式，如果你不做逐步观测，就只能靠猜。

我最常用的命令是：

dsh run --profile debug --interactive

进去之后每一步都可以看到工具输入输出的摘要，还能随时中断重新生成某一段回复。碰到“它连网页内容都没抓到就开始编答案”这类问题，一看就知道是浏览器插件没有正确返回，根本不用翻日志去猜。交互模式还支持在一个会话里同时切换不同模型，我会用一个便宜的小模型先把链路跑通，再切到主力模型看质量，省掉不少 token。

建议给调试单独建一个 profile，参数尽量保守。我的习惯是 temperature 调到 0.2 左右，方便复现，同时把最大 token 数放宽，避免长文档场景下输出被截断。

profiles: debug: model: deepseek-chat mode: interactive temperature: 0.2 max_tokens: 8192

这里要注意一个细节：交互模式的上下文会一直保留，跑久了容易被占满。如果你发现某轮之后智能体表现得越来越迟钝，先看看是不是上下文过长，而不是急着怀疑模型能力。我在实际使用中会定期清理长会话，保留核心摘要，这个习惯让交互模式的稳定性好了很多。

2.2 常驻服务模式：把智能体变成可以被调用的 API

当智能体调试得差不多，下一步就是把它变成一个可以被业务系统调用的服务。DSH 里的常驻服务模式可以这样启动：

dsh serve --profile api-server --port 8080

启动之后，DSH 会在本地暴露一个 HTTP 接口，请求进来之后分配会话、调用模型、执行工具调用、返回结果。生产下我一般把它放在内网，前面再套一层网关做鉴权和限流。

常驻服务模式要重点关注的不是单个请求的效果，而是并发会话之间的隔离。试过把多个用户的请求打到同一个会话池，结果上下文互相串了，已经跑偏了还浑然不觉。正确的做法是按照 profile 或者请求参数明确隔离上下文，每个用户一个会话句柄。DSH 的 profile 机制能做这件事，但需要你自己的业务层把用户 ID 映射进来。

桌面版在这个阶段也很有用。我在桌面上可以直接看到请求链路图、token 消耗、每步耗时，哪个工具调得久一眼就看出来。桌面版还会根据新用户身份送一定的免费额度，我一般建议团队先拿这些额度做小流量验证，别急着充值，等链路跑稳了再扩容。

常驻模式下最容易忽略的是健康检查。不要让网关只做 TCP 探活，要定义一个专门的最小请求做业务级探活，比如让它回答“你正常吗”并校验关键词。我踩过的一次坑是服务进程活着，但模型 API 的 key 过期了，探活接口还在返回 200，用户侧已经全线报错。业务级健康检查是常驻模式里的硬需求，不是可选优化。

2.3 批量任务模式：评测回归和文档处理的主场

批量任务模式是评测闭环的核心执行器。它把一组输入一次性交给智能体去跑，跑完统一输出结果文件。我最常用的命令长这样：

dsh batch --profile eval --input cases/regression.jsonl --output results/regression.jsonl

批量模式和另外几种模式最大的不同，是它追求“确定性归档”。交互模式可以随意尝试，服务模式追求实时响应，而批量模式要求每个用例都能被回放。为了实现这一点，我会把评测集的每个 case 都写好唯一的 case_id 和期望行为，批量跑完直接生成一份带状态的 JSON 文件。

批量任务失败时不要急着重跑。DSH 会记录失败现场，包括当时的输入、输出、工具调用序列。我的流程是：先看失败现场，判断是逻辑问题还是数据问题，修完之后不是全量重跑，而是只重跑失败的那一批。这个思路听着简单，但真能省一半以上的评测时间。

文档处理类的任务也适合批量模式。比如一次性读取 50 份 Word 和 PDF，提取关键字段，生成结构化结果。批量任务模式天然支持这类处理，因为它能记录每个文档的解析路径、解析耗时、以及最终提取结果。我常把一批文档跑完之后，再用评测脚本对照人工标注的期望值算召回率，语义很顺。

2.4 编排模式：多个智能体与工具链的串联

编排模式解决的是最复杂的一类问题：一个智能体搞不定，或者说单个智能体的效率太低，需要把多个角色串成流水线。比如一个写研报的任务，可以先让一个智能体负责检索和整理资料，再让另一个智能体负责生成结论，最后由视觉校验模块检查图表是否完整。这类链路用交互模式或服务模式都不合适，要用编排模式整体调度。

DSH 的编排模式可以理解为一个工作流 runner，把智能体调用、工具调用、条件分支、重试逻辑描述在一个 pipeline 定义文件里。命令大致是：

dsh workflow run pipeline.yaml

插件系统在这个模式里价值最大。插件市场里可以装浏览器插件、文档读取插件、视觉模板校验插件等等，装完以后工作流可以直接调用。我注册 web 评测环境时经常用这样一条命令把市场插件挂到 profile 上：

dsh plugin --profile web add dshmarket

这条命令的意思是：给 web 这个 profile 安装来自 dshmarket 的插件集，之后这个 profile 下的智能体就能看到浏览器操作能力。很多刚上手的读者会忽略这一步，直接拿裸 profile 去跑网页任务，结果智能体只知道有大模型，不知道有浏览器工具，自然什么都做不了。

编排模式里要特别重视插件版本。同一个插件升级之后行为可能变化，对结果影响非常大。我建议把评测记录同时保存当时的插件版本号，否则后面追查“为什么上周通过这周失败”的时候会很痛苦。

2.5 四种模式怎么选：一张快速决策表

很多时候读者会纠结“我应该用哪种模式”，我这里给一个快速决策规则，按任务类型反推即可。

选错模式的代价通常是时间和 token 的浪费。见过一个团队用服务模式做回归，结果并发的高峰把模型接口打爆了，评测结果全是超时，最后还以为是智能体逻辑有问题。看完数据才知道是模式选错。

3. 评测闭环落地：从零开始搭一套可回归的评测体系

3.1 评测闭环到底“闭”在哪里

评测闭环这个词听起来很专业，翻译成大白话就是：把线上遇到的好例子、坏例子全部沉淀成一个固定的测试集，以后每次改 prompt、换模型、加插件，都跑一遍这个测试集，用同一套指标对比结果，不达标就不发版。

我见过太多团队停在“手动验收”阶段。今天改了 prompt，打开几个样例跑一下，感觉对了就发；过两天线上出了问题，又改一版，再手动看几个样例。问题在于，手动验收无法保证覆盖，尤其无法发现“改好了 A 却搞坏了 B”的回归。

真正的闭环有一个反直觉的地方：它不是从“评测脚本”开始的，而是从“数据沉淀”开始的。如果你没有把线上那些失败案例留下来，评测脚本写得再好也是空中楼阁。所以我每次上线前都会把真实请求中效果不好的例子捞出来，人工标注期望回复，放进评测集。这个过程持续不断，评测集才会越来越有代表性和挑战性。

3.2 评测集构造：数据要分层，不能一锅炖

很多首次搭评测体系的人会犯一个错——把几十个用例丢进同一个文件，然后只看一个总分。这个做法没有错，但太粗糙了，一旦总分下降你根本不知道是哪个环节出的问题。我建议把评测集按难度和类型分成三层。

第一层是原子能力题，比如“调用搜索工具后返回正确引用”或者“从一段 PDF 中提取指定字段”。这类题只考单个能力，适合快速定位具体模块的好坏。

第二层是场景题，模拟真实用户的多轮对话，比如“用户先问方案，又追问价格，最后要求生成报价单”。这类题考的是多轮记忆和工具状态的连贯性，最容易暴露上下文管理问题。

第三层是对抗题，专门放一些刁钻输入，比如消息格式错误、字段缺失、超长文本、故意包含干扰信息。这类题的目的不是让智能体完美回答，而是看它在坏输入下能不能优雅降级，而不是一本正经地胡说八道。

堆量的原则也很重要。刚开始 20 到 50 条就能把链路跑通，但做回归至少要到百条以上才有统计意义。我个人习惯是核心评测 80 条，加上线上回流案例后扩展到 200 条左右，这个量级在批量模式下十几分钟就能跑完，成本可控。

3.3 四种模式在评测闭环里各有分工

把 DSH 的四种运行模式引入评测体系之后，我以前面对“评测到底怎么跑”的问题就变得非常清晰。这四种模式不是竞争关系，而是分布在闭环的不同环节。

开发调参阶段，我用交互式模式做冒烟。每改一个 prompt 参数，先跑三条典型案例，快速判断方向对不对。冒烟通过之后才进批量。

每次 commit 或者发版前，我用批量任务模式跑全量评测集，生成 JSON 结果，对比上一次的指标，这个环节是闭环的核心，负责拦截回归。

常驻服务模式在评测闭环里的角色比较特殊，它不是用来跑分数，而是用来做稳定性验证。我会在服务模式下挂一些小流量请求，观察延迟和错误率是否异常。毕竟离线评测全过了，不代表线上并发条件下还能稳定。

编排模式则用来跑跨智能体的端到端链路。比如一个研究任务需要读取文档、调用搜索、生成报告、视觉校验四步，我会在编排模式下定义 pipeline，让每个子环节都有独立的成功率和耗时统计，任何一个环节退步都能马上看到。

3.4 评测指标与判定细则：文本任务和视觉任务要分开定

评测指标不要只盯一个“回答对不对”。智能体任务环节多，我常用的指标有五个：任务完成率、首次正确率、工具调用成功率、额外修正轮数、平均响应延迟和 token 消耗。其中任务完成率是最终结果，工具调用成功率则能帮你定位问题出在哪一步。

批量跑完后，DSH 会输出结果文件，我会在结果文件里给每个 case 附上状态和关键指标，方便后续汇总。下面是一条评测记录的基本结构：

{ "case_id": "doc-report-01", "status": "passed", "task_type": "document_extraction", "metrics": { "task_success": 1, "tool_call_success_rate": 1.0, "extra_fix_rounds": 0, "latency_ms": 5230, "token_usage": 18650 }, "model": "deepseek-chat", "plugin_version": "dshmarket@1.4.2" }

视觉类任务的判定要单独说。很多读者问过一个很具体的问题：视觉模板匹配的运行模式里，怎么把模板匹配的模板显示出来。我的经验是，评测视觉智能体时，如果只给一个 0 到 1 的成功标记，根本没法定位问题。应该把匹配框和相似度分数也输出出来，比如模板匹配的相似度低于 0.85 就认为失败，同时把匹配区域截图保存下来，人工看一眼就知道是模板选错了还是截图截偏了。

相似度阈值不建议拍脑袋定。我会先跑五十个正样本和五十个负样本，画个分布，选一个能把两类明显分开的阈值。那些落在阈值边缘的样本要特别小心，它们是最容易在下次升级后翻转的。

3.5 文档类评测的特殊点：Word/PDF 读写不能只比“有没有读出来”

文档类任务的评测是另一大难点，尤其是 Word 和 PDF 的读取。很多智能体可以靠插件完成解析，但解析质量差异很大。PDF 有文本层和扫描件两种，文本层可以直接提取，扫描件需要 OCR；Word 则要处理表格、分页、批注等结构，解析路径完全不同。

我的评测标准不是“智能体能不能回答跟文档相关的问题”，而是三个层次：内容召回是否完整、关键字段是否准确、引用来源是否可追溯。举个例子，如果文档里某个合同金额在第三页的表格中，智能体能不能定位到那一页并把金额字段提取出来。宁可它明确回答“找不到”，也不要它编一个近似金额出来。在评测集里，我会为此单独设计一条惩罚规则：无中生有比回答失败更严重。

评测文档任务时还要考虑到 token 开销。一页 PDF 转成文本之后可能就有 1500 到 2500 个 token，一个长文档直接塞进上下文，不仅速度慢，还会挤占后续输出的空间。我常用的方案是先在批量任务模式下把文档做切片和摘要，再让智能体基于摘要回答指定问题，评测的重点也从“能读”变成了“会找、会汇总、会引用”。这样评估出来的结果，才是真正对线上有价值的。

4. 常见问题与排查技巧实录

4.1 Windows 商店版 PowerShell 运行 DSH 报错的现场处理

Windows 上使用 DSH 时，最常遇到的报错是 PowerShell 提示“无法加载文件，因为在此系统上禁止运行脚本”。很多团队卡在这一步就以为 DSH 装坏了，其实和 DSH 本身没有关系，是 PowerShell 的执行策略不允许执行第三方脚本。

我的排查顺序是先运行Get-ExecutionPolicy查看当前策略，如果在 Windows 商店版 PowerShell 里默认是 Restricted，那确实会脚本全军覆没。最省事的方案是改用 Git Bash 或 WSL，绕开 PowerShell 的执行策略。如果一定要在 PowerShell 里跑，可以为当前用户放开限制：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

注意加上-Scope CurrentUser，别为了省事直接改机器级策略。用管理员权限全局改策略会带来不可预期的安全影响，我向来不推荐。改完重新打开终端再执行dsh version，正常情况下就能看到了。

这个坑本身不大，但因为它出现在安装第一个环节，劝退了很多人。写在这里给第一次接触的读者提个醒：先确认是环境问题还是工具问题，再决定要不要换安装方式。大部分“第一次启动就报错”的场景都跟这个有关。

4.2 模型 API 接入的配置细节：以 SiliconFlow 为例

智能体终究要调模型。DSH 默认对接了一些常用模型服务，但项目里经常要用第三方兼容 API，比如硅基流动。配置思路不复杂：在 profile 里把模型服务指向一个与 OpenAI 兼容的 base_url，并填上 API key 和模型名。

我的配置大致长这样：

model_providers: siliconflow: base_url: https://api.siliconflow.cn/v1 api_key: ${SILICONFLOW_API_KEY} models: - Qwen/Qwen2.5-7B-Instruct - deepseek-ai/DeepSeek-V3

这里有两个关键细节容易被忽略。第一，base_url 结尾必须带/v1，否则请求路径拼接出来是错的，会一直报 404。第二，不同模型服务商的限速策略不一样，并发拉满很容易触发 429，反而让整体吞吐下降。我会在评测环境里把并发控制在 4 到 8，在线环境根据响应时间和错误率动态调整。

还有一个小技巧：冒烟评测用轻量模型，正式回归再切到主力模型。轻量模型跑得快、成本低，能快速发现链路问题；等链路稳定了再用大模型跑全量，能省不少费用。评测结果一定要记录模型名和参数版本，不然同样一条 case，昨天用小模型跑挂了，今天用大模型跑过了，很容易误判成“今天修复了”。

4.3 插件市场安装、版本锁定与必备插件清单

插件是 DSH 的扩展能力来源，但插件安装没做好，反而会拖垮项目。先记住基础的安装和查看命令：

dsh plugin install <plugin-name> dsh plugin list

我推荐的第一批必装插件有三个：文档读取插件，用来处理 Word、PDF；浏览器插件，让智能体具备真实网页操作能力；视觉模板匹配插件，用于截图比对和模板校验。视觉插件装好后，记得在 profile 里打开可视化输出，否则评测时匹配框不会显示出来，你也就没法判断模板到底匹配在了哪里。

插件市场的注册命令值得单独说明。要给某个运行环境挂上市场插件集时，我会写：

dsh plugin --profile web add dshmarket

这条命令把市场插件集注册到 web 这个 profile 上，之后 web profile 下的智能体才有对应的工具能力。使用时注意它是“给 profile 加集合”，不是“全局安装所有插件”，全局装反而容易造成插件互相抢工具名，调用时都不知道谁在处理。

版本是插件体系里最容易被忽视的环节。每次跑评测，顺手在结果文件里记录插件版本号。别只看“更新到最新版”，最新版不代表最稳。我遇到过浏览器插件从 1.3 升到 1.4 之后，定位元素的策略变了，功能测试几乎全挂。后来我固定了一个已知良好版本，只有在主动验证升级时才切换，再没出现过这种“升级导致全线崩溃”的尴尬。

4.4 评测稳定性与资源开销：三个最容易翻车的点

第一个翻车点是上下文超长。实测下来，一份二十页的文档转成文本后 token 数很容易超过一万，直接塞给模型会拖慢响应。文档任务要做切片或者摘要，不能无脑全量进上下文。评测时我也建议把 max_tokens 放宽到 8192，否则输出到一半被截断，系统会误判为失败。

第二个翻车点是并发过高导致的超时抖动。批量模式跑评测时，如果把并发设置过高，模型服务限流，结果会大面积超时。这些超时记录会和真正的逻辑失败混在一起，给你一个假的低分。解决办法是给评测环境单独设置重试次数和超时上限，并记录每个 case 是“重试后通过”还是“首次通过”，这两个指标含义完全不同。

第三个翻车点是不确定性。同样一条 case，跑十次可能有七次通过三次失败。遇到这种情况，不要急着改逻辑，先把乱数和温度固定下来。评测环境的 temperature 建议设为 0，追求可复现；线上再按业务需求适当调高。固定随机种子之后，那些“时好时坏”的结果通常能暴露出真正的稳定问题，而不是被随机性掩盖过去。

4.5 一套从测试现场学到的快速定位套路

最后分享一个排查漏测问题的流程。因为我几乎每次都能用同一套方法找到根因，所以把它固化成习惯了。当评测发现某个 case 失败，先复制原始输入和当时的输出到一个最小复现 case 里，只保留一句话的 prompt 和一个 mock 工具返回，在交互式模式下逐步走一遍。每走一步看一次工具调用顺序，基本能定位到是哪一步的输入输出不匹配。

如果交互模式看不出来，就去翻批量结果里保存的可选调试现场。很多初学者不知道 DSH 可以在评测时保存截图和完整日志，其实这个开关一开，排查问题的效率能提升一个量级。视觉任务尤其依赖截图，光看文字日志根本不知道页面长什么样。能保存现场，就能在几分钟内复现和确认问题，而不是靠猜测重新搭环境。

5. 说点实际操作中沉淀出来的体会

把 DSH 的四种运行模式和评测闭环配合起来之后，我的项目节奏发生了明显变化。以前是改完 prompt 直接发版，现在变成了：先交互式冒烟，再批量回归，接着用服务模式做稳定性验证，最后编排模式跑一遍完整链路。看似多了几步，实际上返工次数大幅减少，因为每次发版前都有了客观数据兜底，不会因为“我觉得没问题”就上线。

我个人在实际操作中的体会是，评测闭环的价值不在于第一次跑出来多少分，而在于它把项目从一个“靠感觉迭代”的状态，硬生生拽进了“靠数据迭代”的状态。哪怕评测集只从二十条难例开始，只要你能在每次改动后稳定回放，就已经赢过大多数凭经验发版的团队了。

最后再分享一个小技巧。在桌面版里把几种模式的可视化全部打开，第一次跑通某个新任务时不要急着写进自动化，先在交互模式里人工确认一下输出质量，确认之后把它作为一条新的评测 case 固化下来。用这种“人工确认→固化进评测集”的方式，你的评测集才会持续生长，越跑越符合线上真实情况。这个习惯坚持两个月之后回头看，你会发现整个团队对智能体质量的判断力都上了一个台阶。