企业官网建设流程全解析

那个周五晚上之前，我从没想过一个“返回码0”的搜索接口，能把模型的答案带偏到沟里去。日志里明明白白写着search web exit 0，结果却是空结果。模型读到这个结果，非常自信地告诉用户“当前没有相关实时信息”——但我手动打开网页搜索，明明排满了一整页。问题不在搜索引擎，也不在模型，在我自己搭的这套“把联网检索从模型里拆出来”的组件上。也就是标题里的这个bl search web。

这篇文章想把整条链路拆开讲清楚：为什么要拆、拆完后的三层结构怎么分工、退出码怎么设计才能让模型准确读到状态，以及我在真实运行里踩到的两个静默坑——它们有一个共同点：程序本身没报错，退出码是0，但结果已经是错的。这类问题最难排查，也最值得写下来。

1. 先说说为什么要拆：模型内置检索的三个硬伤

我在做检索增强类的Agent项目时，最初图省事，直接让模型自己带联网检索能力。模型厂商标榜的“内置搜索”确实方便，一行配置就能用。但真跑起来，我撞上了三个绕不开的问题。

第一个是输出格式不可控。模型内置搜索返回的是大段自然语言，什么“根据最新报道……”“多个来源显示……”，摘要密度低、废话多，几轮对话下来上下文Token消耗很猛。而且不同的模型厂商返回格式各不相同，接口返回的字段、关键信息的位置都不一样，代码里想统一解析非常痛苦。我们当时的做法是为每家厂商单独写解析逻辑，维护成本直线上升。

第二个是切换模型代价大。只要换一个主流模型，搜索能力就跟大便。之前内置搜索的可用性、返回稳定性全废，得重新适配。项目里的核心逻辑倒是没变，变的全是“模型怎么调用搜索”这一层，架构被模型厂商绑架了。

第三个是无法精细化控制检索策略。模型内置的搜索往往是黑盒：不知道它搜了几个源、用的什么排序、超时多久、有没有重试、有没有反爬兜底。想限定“只搜学术源”“有时间截止”这类业务规则，根本做不到。对于生产系统来说，不可控就是不可用。

所以我决定把这块拆出来，做成一个独立模块，也就是bl search web这个CLI工具。模块只负责一件事：接收“检索词 + 若干选项”，输出“结构化结果或明确的失败状态”。模型不再自己搜索，而是通过工具调用这个模块，就像调用一个普通函数。拆完之后收益很明显：不同模型都能复用它，适配某个新模型时不用重写搜索层；搜索策略集中在一处，调参和排障都能在一处完成；最关键的，搜索成功和失败变成了一种可编程判别的状态，而不是模型自由发挥的自然语言。

2. bl search web 的三层职责：接入层、编排层、执行层

很多人在做这类工具时犯的错误，是只写了一个“搜索函数”，把所有逻辑堆在一起。bl search web能稳健运行，核心是内部逻辑按职责拆成了三层。每一层只干一件事，而且对上层暴露的接口是稳定的。

2.1 接入层：模型只认这份协议

接入层是模型真正接触的地方。它可以是CLI命令、HTTP接口，也可以是函数调用里的一个tool定义。我在项目里用的是CLI方式，因为命令行接口最容易被各种Agent框架包装，也最容易手动调试。

这一层要做的事只有三件：解析参数、调用编排层、按约定格式化输出。输出内容分两路：stdout走干净的结构化字段，这是给模型看的；stderr走详细日志，这是给人排查用的。模型侧永远只读stdout，程序侧永远检查退出码。

2.2 编排层：查询路由、并发与超时策略

编排层是所有策略的聚集地：选哪个搜索源、多个源是串行还是并发、超时多久、结果按什么排序、最多返回几条、失败要不要降级。这一层相当于调度中心，它自己不直接做网络请求。

例如我这里的策略：默认并发请求两个独立搜索源，谁先回来且质量达标就用谁；超过4秒就放弃慢的那一个；如果两个都失败，不自动降级，而是把失败状态原样抛回接入层。这个“失败不降级”的原则，正是后面两个静默坑的关键教训——宁可让上层知道自己失败，也不要伪造一个“空结果”。

2.3 执行层：搜索源适配器如何隔离变化

执行层是最动荡的一层，每个搜索源一个适配器。各家的页面结构、反爬策略、返回格式都可能随时变化，如果没有隔离，任何一个小变动都会炸到上层。我的做法是让每个Provider实现同一个接口：

# provider.py from dataclasses import dataclass, field @dataclass class SearchResult: title: str url: str snippet: str source: str rank: int class BaseProvider: name: str = "base" def search(self, query: str, timeout: float = 5.0, max_results: int = 5) -> list[SearchResult]: raise NotImplementedError def parse(self, raw_html: str) -> list[SearchResult]: raise NotImplementedError

Provider.search负责发起实际请求，Provider.parse负责解析页面。两层拆开，是为了让“网络请求异常”和“页面结构异常”能分别处理。任何一个新搜索源接入时，我只需要实现这两个方法，然后注册到编排层，别的都不用动。这也是整个模块能长期稳定运行的结构基础。

3. 退出码是真正的“模型协议”，stdout才是给人看的

工具拆出来后，我发现最容易被低估的是退出码设计。模型读工具返回值时，通常只看stdout里的自然语言。但问题是，自然语言是有歧义的。

举两个例子。Tool返回“没有找到相关信息”，这到底是正常空结果，还是搜索失败了？模型分不清。Tool返回“发生错误”，模型可能觉得“这是结果不是错误”，然后就拿这句话去回答了。所以必须有一个模型能读懂的程序化信号，这就是退出码。

3.1 一个足够细的退出码表

bl search web的退出码不是标准Unix那种简单的0/1，而是按“模型需要如何应对”来设计的：

设计哲学是：每个非0退出码都对应一类“模型可以执行的决策”。0是成功；1是使用方式问题；2、4是临时的，可以重试或换策略；3是确定性的正常状态；5说明工具该更新了。

退出码表定下来后，模型侧的工具调用代码就非常简单了。伪代码：

import subprocess import json def search_web(query: str) -> str: proc = subprocess.run( ["bl", "search", "web", query, "--format", "json"], capture_output=True, text=True, timeout=10 ) if proc.returncode == 0: return proc.stdout elif proc.returncode == 2: return "[搜索超时，稍后可重试]" elif proc.returncode == 3: return "[确认：无匹配结果，请换关键词]" elif proc.returncode == 4: return "[搜索被拦截，建议换时间或换源]" else: return f"[搜索失败，退出码 {proc.returncode}，请稍后重试]"

3.2 怎么把退出码接进大模型工具调用

主流的Agent框架都支持“工具返回错误信息后，由模型自行决定下一步”。问题在于，框架传给模型的往往是stdout文本，退出码并不直接被模型看见。所以我的做法是：把退出码的语义翻译成一句简短的状态描述，拼在返回内容最前面。模型先看到状态句，再看到真实内容，决策质量高很多。

真实运行中还有一个细节：超时处理。subprocess.run内部的timeout参数必须比所有Provider的总超时预留得多，否则会抛出TimeoutExpired，工具中断，模型拿到的不是任何可识别的状态，而是一段半截输出。我后来统一在接入层捕获这类异常，把它转成“搜索超时”的状态句，才能进得了模型上下文。

4. 静默坑之一：验证页被当成正常结果返回，模型照单全收

4.1 事故重现：返回码0、内容离谱

那是某次凌晨的批量任务，我查看日志看到一大片奇怪的记录。退出码都是0，stdout里确实有title、snippet字段，看起来完全正常。但我点开结果里的url一看，页面标题是“安全验证”，snippet是“请完成以下验证码以继续访问”。显然，这是某个搜索源在深夜触发了反爬拦截，返回了一个验证页面。

问题是：解析器为什么会把它当结果返回？

4.2 排查链路：从现象到根因

我当时的排查路径是这样的。

先看退出码：全0，毫无疑点。再看stdout：有一条结果，字段完整，像是正常结果。然后用命令行单独跑了一次：

bl search web "测试关键词" --source SourceA --format json echo $?

返回依然是0，输出照样是一条“安全验证”的记录。接着抓原始响应。在Provider里临时用一个参数打印前2000字节的HTML，发现响应的HTTP状态码是200，但DOM结构和真正的搜索结果页完全不同——没有搜索结果容器，取而代之的是验证脚本和跳转逻辑。

根因就藏在解析逻辑里。原代码的思路是：先尝试提取搜索结果容器，提取不到时不抛错，而是退化为“用页面标题 + meta description 构造一条兜底结果”。设计这个兜底的初衷是怕某一次搜索结果为空时让模型一无所获，结果却成了静默失败的温床。页面标题和meta description在验证页上一样存在，于是解析器愉快地构造了一条“结果”，而且没有显式标记这是一条低置信度结果。

4.3 修复方案与回归用例

修复分三步走。第一步：删除“构造兜底结果”的逻辑，搜索容器不存在时直接抛出不可解析异常。第二步：在编排层把这类异常映射为退出码4。第三步：增加对典型关键词的过滤，比如snippet或title里出现“验证码”“安全验证”“滑动解锁”等特征时，跳过该来源并让编排层重试其他源。

回归用例是事后必须补的。我给解析器写了三个测试样本：正常搜索页、验证页面、只有空容器的页面。断言分别是：正常页提取到N条结果、验证页抛异常、空容器抛异常。以后再遇上搜索源改版，跑一遍测试就能看出是哪类问题。

这个坑的教训我总结成一句话：与其返回一条“可能不对”的结果，不如明确告诉模型“我没拿到有效结果，原因可能是被拦截”。模型处理“明确失败”的能力，远比处理“看似成功实则垃圾”强。

5. 静默坑之二：超时被默认值吞掉，失败被伪装成“无结果”

5.1 事故重现：搜索有结果，模型却说没有

第二个坑更隐蔽。某天线上反馈，Agent在回答“今天有什么热点的实时消息”时，模型回复“暂无最新相关信息”。我手动检查搜索源，结果正常，内容绝对可以搜到。查日志，bl search web返回的是退出码0、total=0，也就是“正常空结果”。不论怎么看，程序都没有异常。

但我觉得不对劲。于是把搜索引擎的实际请求时间临时打印出来，发现SourceA响应稳定在7到9秒之间，而编排层的并发超时设置是8秒——上游稍微一震，请求就来不及返回了。

5.2 根因：通用的裸捕获把状态抹掉了

顺着代码往下翻，看到了罪魁祸首：

try: future = pool.submit(provider.search, query, timeout=5.0) results = future.result(timeout=8) except Exception: results = [] # 任何异常，一律返回空列表

一行except Exception，把TimeoutError、ConnectionError、ParseError全部吞掉，统一变成空列表。上层看到空列表，就把total记成0，退出码定为0（成功但无结果）。于是“搜索失败”被静默地替换成“没有搜索结果”，模型接收到的是完全错误的语义。

为什么一开始没发现？因为通常在正常网络下，请求2秒内就能返回，超时是小概率事件。只在网络波动或目标站点变慢时才会触发。而这种场景恰恰发生在用户最需要实时信息的时候，影响被放大了。

5.3 修复与验证

修改思路有两条。第一条，不允许“异常变成空列表”这种静默降级，异常处理必须显式区分类型：

try: results = future.result(timeout=8) except TimeoutError: raise SearchTimeoutError(f"source={provider.name} 8s timeout") except Exception as e: raise SearchFailedError(f"source={provider.name} failed: {e}")

TimeoutError统一转成退出码2（可重试），其他网络异常转成退出码5或对应类型。第二条是编排层加了一个“耗时审计”日志，把每个Provider的耗时、状态、结果条数都打出来。事后排障时能一眼看出“是超时了还是真的没结果”。

验证环节，我引入了一个故障注入参数，可以人为给Provider加几秒延迟，触发超时路径，确认退出码确实是2、stderr有耗时信息、模型侧收到的状态句是“搜索超时”，而不是“空结果”。这类故障注入测试现在是我每次改动搜索模块必跑的用例。

这里顺带也暴露了一个容易被忽略的设计倾向：所有上层对象里那些带默认值的空集合（空列表、空字典）都要警惕。默认值本身没有错，错的是异常路径里把“状态”丢掉了，默认值就变成了替罪羊。

6. 沉淀下来的经验与排查通用套路

写完这两个坑，我复盘了整个设计，浓缩出三条对工具调用类项目都适用的经验。

第一，用结构化状态代替自然语言反馈。退出码、错误码、结构化字段，这些程序化信号才是机器之间协作的可靠语言。模型再聪明，也不能靠猜状态来决策。凡是“文本”能表达的状态，都应该有对应的“程序状态”兜底。

第二，对“静默失败”零容忍。我后来给团队立了一条规矩：宁可显式失败、退码非0，也不要返回看起来正常但实际上残缺或错误的结果。因为显式失败模型知道要重试，静默失败模型会用错误信息继续往下推理，污染的是整个回答。

第三，把故障注入纳入日常测试。现在bl search web每次发版，必须跑一遍故障注入用例：超时、验证页、乱码、空容器、半截JSON，全部都要过。这个方法对于任何涉及外部调用的模块都适用，不局限于搜索。

另外再分享一个个人习惯。现在排查工具类问题时，我从来不会只看退出码和结果文本。我会先抓原始响应，看“外部系统给我的到底是什么”，然后才看自己的解析和状态映射。很多问题的根源都出在中间那层映射上，而不是网络本身。

bl search web这个模块拆出来之后，最大的收获其实不是一次搜索快了0.3秒，也不是某个模型换得飞快，而是它把“搜索”从“模型行为”里彻底剥离出来，变成了一块可以独立调试、独立测试、独立排障的组件。对于任何要长期维护的Agent系统，这种边界感比任何优化都值钱。