企业官网建设流程全解析

我刚完成一个 Agent 项目，项目代号叫Agent-Reach。起这个名字的初衷很直接——做完一个 Agent 之后我最大的感受是：现阶段 Agent 缺的已经不是"聪明"，而是"触达"。模型再会推理，如果碰不到文件系统、打不了浏览器、调不起命令行、读不到外部知识源，那它本质上还是被关在聊天框里的鹦鹉。Agent-Reach 想解决的就是这个问题：让 Agent 的能力不被对话边界锁死，能真正抵达它该抵达的地方。

这篇文章会把我在 Agent-Reach 里踩过的坑、做过的技术选型、以及最终沉淀下来的实操方案一次性讲透。适合正在做 Agent 开发、Agent 架构设计，或者单纯想把 Agent 从"聊天机器人"推向"能干活的工作助理"的开发者参考。

1. 为什么我做了 Agent-Reach：先解决"触达"再谈智能

1.1 一次让我崩溃的 Agent 翻车经历

事情得从三个月前说起。当时我给一个内部知识库项目接了个 Agent，用来帮同事做文档问答和摘要。初期效果还不错，模型理解能力在线，问答准确率也能看。直到有人提了一句："能不能让它顺手把网页内容保存成 PDF 发到群里？"

我当时天真地想，这不就是给 Agent 加个工具的事儿吗？结果发现，模型确实"懂"怎么保存网页，但它根本没有能力执行"保存网页"这个动作——它不能自己开浏览器、不能写文件、不能调用群里机器人接口。所有的"动手能力"都靠我在代码里提前写死，换一个场景就要重新写一套胶水代码。更痛苦的是，每加一种新能力，就要改一遍 Prompt、改一遍工具注册逻辑、改一遍参数解析，整个链路又脆又散。

那次之后我意识到一个核心问题：一套 Agent 架构，如果只解决"模型多聪明"，不解决"模型能碰触哪些资源"，那它永远只是个高级玩具。Agent-Reach 就是从这个问题出发的项目，重点不是再造一个模型封装，而是把 Agent 的工具触达、知识触达、执行触达做成一套可插拔、可编排、可隔离的通用体系。

1.2 "触达"这个词在 Agent 体系里到底指什么

我做 Agent-Reach 时把"触达"拆成了三个层次，这三个层次也是整个项目的三个核心设计支柱。

第一层是工具触达。Agent 能不能调用外部 API？能不能操作浏览器？能不能读写文件？能不能跑一段代码？这一层解决的是"手脚"问题。很多 Agent 项目做到最后发现交互还行，但一落到"替用户干点实事"就卡住了，根子几乎都在工具触达层设计得太死板。

第二层是知识触达。Agent 能不能访问长期记忆？能不能检索知识库？能不能把网页保存成结构化文档再喂给自己？这一层解决的是"情报"问题。没有知识触达的 Agent 只能依赖单次对话里塞进去的上下文，稍微涉及历史信息就断片；而一旦能把外部知识变成统一格式输送给模型，Agent 的可用性会立刻上一个台阶。

第三层是执行触达。Agent 的能力不只体现在"给出答案"，更体现在"在受控环境下实际执行动作"。比如让 Agent 去解析一个爬虫任务、跑一轮数据处理脚本、做一次自动化测试。执行触达最大的难点不是执行本身，而是执行的安全性——这也是 Agent-Reach 里我花时间最多的地方，后面会单独开一节细说。

Agent-Reach 的产品定位很清晰：**做一个以"技能"和"编排层"为双核心的 Agent 能力扩展底座。**模型可以用任何主流大模型，但"能做什么、能碰什么、怎么安全地做"全部由 Agent-Reach 统一接管。这样无论底层模型换成 GPT、Claude 还是开源模型，上层能力都不会塌。

2. Skills 模块：可插拔四肢的设计与一个完整示例

2.1 从 function calling 到 Skills：差的不只是叫法

提到给 Agent 加能力，很多人第一反应是 function calling。OpenAI 和 Claude 都支持，概念也简单：把函数定义丢给模型，模型决定调不调、传什么参数。

但实际项目跑起来之后你会发现 function calling 有几个天生短板。第一，它只能解决"调函数"这一步，解决不了"函数的输入怎么来"。比如我想让 Agent 把网页存成 Markdown，函数签名可以是save_webpage(url, output_path)，可模型并不知道应该用哪个抓取引擎、要不要启用 JS 渲染、遇到登录页怎么处理。函数对模型来说是个黑盒，模型只能靠函数名和描述猜测怎么用。

第二，function calling 的粒度太细，导致你每换一个使用场景就要重新注册一堆函数。Agent 项目在起步阶段还行，一旦技能数量超过二十个，函数列表本身就会占用大量上下文，模型的选择准确率还会明显下降。

第三，也是最重要的，function calling 没有"环境"概念。函数一旦被调用，它就跑在 Agent 的进程里，权限、超时、资源消耗全部混在一起，很难隔离。我前几版 Agent 里有一个自动截图的技能，因为底层 Playwright 连接没释放，直接把整个服务的文件描述符耗光了——这就是没有边界管理的典型翻车。

Agent-Reach 做 Skills 模块时，从一开始就把"技能"定义为一个自治的能力单元，核心思路是让技能自己有说明书、有运行环境、有资源边界。模型不再面向一大堆函数做选择，而是面向一个"技能目录"做决策，选择后由编排层接管，技能和 Agent 主进程隔离运行。

2.2 实战：一个"网页转 Markdown"技能从零落地

我以 Agent-Reach 里最常见的一个技能来演示整个链路——把网页保存成 Markdown。这个技能在内部叫web2md，结构是这样的：

skills/ web2md/ SKILL.md # 技能说明文件，给模型看 run.sh # 技能入口 requirements.txt # 依赖声明 handler.py # 核心逻辑 assets/ # 静态资源（模板、配置）

SKILL.md是这个技能的"使用手册"，里面写清楚技能能做什么、需要什么输入、有什么限制。我一开始写技能说明踩过坑——写太简单，模型不知道怎么用；写太复杂，模型选择时容易被误导。最后摸索出来的模板是固定三段式：用途、输入参数、注意事项。

# Skill: web2md ## 用途 抓取一个网页并将正文内容转换为干净的 Markdown 格式， 适合用于知识库采集、文档归档、内容摘要等场景。 ## 输入参数 - url: 目标网页地址，必须包含协议头（http/https） - output_path: 保存路径，可选，默认保存到当前工作目录 - js_render: 是否启用 JS 渲染，布尔值，默认 false ## 注意事项 - 仅支持公开可访问的页面，需要登录的页面请调用 auth 技能 - 页面内容过大时（超过 500KB），只保留正文主区域 - 图片链接保留原 url，不做下载

handler.py里是实际抓取逻辑。选型时我用的是requests+BeautifulSoup做基础抓取，遇到 JS 渲染页面再退化到 Playwright。这里有个非常现实的性能问题：默认技能不能一上来就用重量级渲染引擎，因为 90% 的页面用静态抓取就够了。只有用户显式声明js_render=true，才会走到 Playwright 分支。

# 伪代码示意，实际项目要加超时和重试 def fetch(url: str, js_render: bool = False) -> str: if js_render: return render_with_playwright(url) return fetch_static_html(url)

技能写好之后，还要在 Agent-Reach 的技能注册表里登记。注册时我会为每个技能定义一个能力签名，类似给技能打索引标签。比如web2md的签名是["web", "markdown", "save", "content_extraction"]。当 Agent 收到"把这篇文档存成 Markdown"的请求时，编排层会通过签名检索把候选技能范围缩小到两三个，再连描述一起交给模型做最终选择。这套"先检索再选择"的流程比直接把几十个技能全部塞给模型要稳定得多。

2.3 技能和模型之间到底怎么通信

Skills 模块能跑通，核心是解决了"模型怎么操作技能"的交互协议。我在 Agent-Reach 里没有用自定义格式，而是直接跑在标准函数调用协议之上，只是把"函数"这个粒度替换成了"技能"粒度的注册和调用。这样做的好处很多：任何支持 function calling 的模型都可以直接适配，不需要改模型侧的接口。

整个调用流程是这样的：

1. 模型根据用户请求和技能描述，输出一个结构化动作，比如call_skill(skill="web2md", params={"url": "...", "output_path": "..."})
2. 编排层拦截这个动作，做一次参数合法性校验（必须的——模型幻觉参数的时候真的能把路径写飞）
3. 校验通过后，编排层在沙箱环境里拉起技能进程，传入参数并监控执行状态
4. 技能执行结束后，输出结果（可能是结构化数据，也可能是文件路径）回传给编排层
5. 编排层把返回值压缩成一段摘要，连同执行状态一起填充给模型，模型再接着生成对用户的回复

这里有一个我反复强调给团队的原则：模型不应该直接看到技能的原始输出。比如web2md抓下来 300KB 的网页，如果直接把全文塞回模型上下文，一次对话的 token 预算瞬间就没了一半。Agent-Reach 会在技能输出层做一个"正交压缩"——把抓取结果先转成摘要、结构化大纲，再喂给模型。关于这块踩过的 token 爆炸的坑，后面我会单独作为一节详细说。

3. Harness 编排层：Agent 到底应该怎么"动手干活"

3.1 harness 和 agent 的区别：大脑不能自己长手脚

刚开始接触 Agent 生态的人经常混淆两个概念：Agent 和 Harness。我自己的理解是这样——Agent 是大脑，负责理解、规划、决策；Harness 是身体和感官系统，负责把所有"动手"的过程串起来，包括工具调用、技能路由、记忆处理、上下文管理、沙箱执行和错误恢复。

光有 Agent 没有 Harness，模型就只能"嘴上说说"，什么也执行不了；光有 Harness 没有 Agent，那也就是个流程自动化脚本，没有任何自适应能力。Agent-Reach 的定位里，Harness 层才是真正决定一个 Agent 项目能不能落地的关键，因为大模型能力大家拉不开差距，差距全在"谁能把能力稳定地接出来"。

我见过很多团队一上来就买最好的模型，然后花两个月什么也没做成，最后发现卡在"模型不给力"上。其实不是模型不给力，是他们把模型当成了整个系统，而没有给它配一个可靠的 Harness。Agent-Reach 的 Harness 我做了大半年，中间删了三次重写，其中最核心的设计是"任务生命周期管理"加"上下文预算控制"。这两个东西，少一个，Agent 跑长任务就一定会挂。

3.2 Agent-Reach 的 Harness 工作流详解

Agent-Reach 的 Harness 把一次 Agent 请求拆成了六个阶段，每个阶段都有明确的状态记录和异常处理逻辑：

1. 意图接收：接收用户原始请求，做基础清洗，比如把 "帮我存下这个网页 https://xxx/article/123" 识别为"保存网页"意图
2. 技能检索：通过技能签名和关键词匹配，从技能注册表里筛出候选技能列表
3. 动作决策：把候选技能的描述、参数模板、限制条件打包成模型可读格式，交给模型做出最终选择
4. 参数解析与校验：解析模型返回的动作参数，逐项校验类型、格式、安全边界（最重要的阶段）
5. 沙箱执行：拉起沙箱环境，执行技能，全程监控 CPU、内存、网络、超时
6. 结果回填：把技能输出压缩、提炼后回填给模型，辅助模型生成最终用户回复

这个流程里我踩过的一个大坑是第 2 步和第 3 步的衔接。早期版本我把所有技能描述一次性全塞给模型，数量一多模型就开始犯迷糊，明明用户只是要存网页，模型偏要调用"邮件发送"技能，还一本正经地填了收件人地址。后来改成"先粗筛、后决策"的两阶段路由，准确率才从 60% 出头拉升到 95% 以上。粗筛规则很简单，基于关键词和技能标签做向量匹配就行，不需要太复杂的模型。

3.3 第三方工作台接入实践：我为什么坚持标准协议

Agent-Reach 做到中后期，面临一个很现实的需求：外部工作台怎么接进来？市面上的 Agent 项目，无论是开源社区还是商业产品，很多都有自己的一套工具协议。比如有的用 LangChain tools，有的用 OpenAI 的 function schema，还有的干脆自研一套 JSON-RPC。我需要在 Agent-Reach 的 Harness 层做一个接入层，能把这些不同来源的能力统一纳管。

我最终选择了兼容 MCP（Model Context Protocol）风格的接口规范，同时保留一层薄薄的适配器。这样做的理由有三点。一是 MCP 已经基本成为 Agent 工具生态里的事实标准，社区里大量现成的 server 可以直接拉起来挂载；二是我希望 Agent-Reach 的价值不是绑定在某一个大模型厂商上，而是能和任何"会说话的 Agent"协作；三是适配器层让我能兼容老项目里那些不适合改造的私有协议，不至于为了接一个第三方工作台把整个技能体系推倒重来。

这里以接入 an Agent 工作台 为例说下具体步骤。Agent-Reach 的 Harness 对外暴露一个标准技能服务端口，工作台只需要配置一个 MCP 客户端指向这个端口，就能看到 Agent-Reach 里注册的全部技能。工作台发起调用时，Agent-Reach 会先校验来源身份的认证 token，再进入正常流程执行技能。我实测下来，接一个第三方工作台从 0 到跑通一次技能调用，大约只需要半小时，大部分时间花在调试认证配置上。

必须提醒的是，第三方接入最头疼的不是协议本身，而是超时策略的差异。很多工作台默认请求超时只有 30 秒，但 Agent-Reach 里有的技能（比如复杂页面爬取）动辄要跑 3-5 分钟。如果不在接入层做双向适配——即一方面提高服务端超时阈值，另一方面给工作台客户端配置"长任务轮询模式"——就会出现工作台这边以为调用失败了、但沙箱里技能其实还在跑的尴尬局面。这个问题我在接入早期频繁碰到，后来我在技能服务的响应头里增加了x-agent-task-id字段，配合轮询接口才彻底解决。

4. 框架对比与 Agent-Reach 的架构取舍：LangChain、Dify、CrewAI 之外的选择

4.1 主流 Agent 框架的真实差异：别被社区话术带偏

做 Agent 开发绕不开框架选型。社区里关于 LangChain、Dify、CrewAI 谁更好的争论几乎天天都有，我自己的看法是：没有谁绝对更好，只有谁更契合你的问题域。

我把它们整理成一个横向对比表，方便大家按图索骥：

我的实测体验更直白：LangChain 适合做"过程研究"和快速实验，它的组件拆得很细，方便你理解一个 Agent 的各个环节是怎么组装起来的，但真到了生产环境，你会发现它的抽象层次太多，排查一个问题要在多层 Tape 之间跳来跳去，很费神。Dify 适合做"业务产品化"，特别是非核心研发团队想快速搭一个带知识库的问答应用，用 Dify 几乎不需要写代码，但它把底层逻辑包得太严，想深入定制某个技能执行流程会碰到天花板。CrewAI 的卖点在多 Agent 仿真，适合研究"多个角色怎么协作"这类课题，但实际生产中多数场景其实不需要那么复杂的多角色博弈——两个能干的 Agent 已经能覆盖 90% 的需求，再多就是表演了。

4.2 Agent-Reach 为什么不直接用现成框架

你可能要问：既然有这么多框架，为什么 Agent-Reach 还要自研一套？

我的回答可能会得罪人，但确实是我做完整个项目后的真实体会：现成框架解决的是"从 0 到 1 把 Agent 跑起来"的问题，而 Agent-Reach 解决的是"从 1 到 100 让 Agent 可靠地在业务里落地"的问题。

两者的目标不同，导致架构取舍完全不同。LangChain 之类的框架首先保证的是灵活和覆盖度，所以在追求极致安全边界和资源可控时，它的设计反而成了阻碍。举个例子，Agent-Reach 的沙箱要求技能进程和主进程之间用严格的 IPC 协议隔离，主进程崩溃不能拖垮技能执行，技能执行翻车也不能污染主进程状态。这个需求在 LangChain 里实现起来非常别扭——它的工具执行链路默认就在同一进程里，你要做隔离得先在框架层面开洞。与其在框架的限制下妥协，不如按照自己的核心诉求重新设计执行内核。

另一个原因是上下文预算管理。我前文提到 Agent-Reach 对模型上下文采取"精打细算"的策略。现成框架基本没有提供细粒度的 token 使用控制，它们更倾向于"把上下文喂饱"。而 Agent-Reach 几乎每个环节都在做压缩和取舍——技能输出要提炼、历史对话要裁剪、长文档要分片。这些逻辑如果寄生在别人的框架里，侵入性太强，维护成本太高。

4.3 底层为什么选 Rust：不是跟风，是这几个痛点逼的

Agent-Reach 的性能敏感模块和沙箱模块用 Rust 实现，上层业务逻辑用 Python 快速迭代。这个组合不是一开始就定下来的，是被性能和安全问题逼出来的方案。

最直接的动机是并发执行。Agent 项目跑起来之后，同一时刻往往有多个技能在并发执行，有的在抓网页，有的在跑数据处理，有的在调外部 API。负责人体线程、子进程和资源监控的部分，如果全部用 Python，GIL 会卡住整条执行链，而且子进程管理在 Python 里稍不注意就会出僵尸进程或 fd 泄漏。Rust 的并发能力刚好补齐这个短板——技术栈上我只需要专注内存安全和高吞吐的事件循环，就可以把多任务的资源隔离做成可靠底座。同时，沙箱的安全边界也需要底层语言级别的保障。Rust 的所有权系统提供了"无 GC 但内存安全"的强约束，对构建可信边界有天然优势——不过这属于我个人技术偏好，如果你的团队不熟 Rust，用 Go 或 Python + 容器隔离也有可行路径，"什么语言"不是唯一解，"边界模型"才是。

还有一个现实考虑是体积和可移植性。Agent-Reach 希望技能环境能跑在服务器、容器甚至边缘设备上。Rust 编译出来是单文件二进制，不依赖运行时，部署成本极低。配合容器镜像反而比"纯 Python + 虚拟环境"的方案更容易在资源受限场景里分发。

4.4 多 Agent 协作时我在 Agent-Reach 里怎么设计

热搜词里"多 agent"出现频率很高，说明很多人对多 Agent 协作感兴趣，但我要泼一盆冷水：多 Agent 系统 90% 的性能问题出在"通信协议"和"任务同步"上，而不是出在"角色设计"上。

Agent-Reach 的多 Agent 协作机制走的是"群聊式消息总线"路线。每个 Agent 是一个独立的执行单元，有自己的技能集和上下文，通过 App-Reach 的消息总线发布/订阅消息。比如任务发起者 Agent A 发现网页转储需要知识库辅助，就发一条消息到knowledge-agent的订阅队列，等待响应；知识 Agent 处理完后再把结果发回main-agent的响应主题。

这种设计的优点是模块解耦，任何一个 Agent 挂了不会影响整个任务链。但坏处是消息乱序和任务超时管理非常考验编排层。我踩过的最典型的一个坑是：两个 Agent 同时往总线里发消息，主 Agent 这边的回调函数没有做好幂等处理，结果一个文档被重复处理了三次，知识库里一下子多了三份内容近似的条目。后来我统一给所有消息加了request_id和unique_key，在处理端做去重，问题才彻底解决。

在这一点上，Agent-Reach 的编排层有一个"任务协调器"，专门负责监控跨 Agent 任务的完成状态，包括超时兜底、失败重试、以及结果校验。没有这个协调器，多 Agent 系统很容易陷入鸡生蛋蛋生鸡的互相等待僵局。这个设计也是我整个项目里认为最有复用价值的组件之一。

5. 沙箱与安全：能力越大，越需要边界

5.1 隔离等级的比较：别把"安全"当成一个按钮

给 Agent 加技能，最让人担心的就是安全。一个能执行命令、能访问网络、能写文件的 Agent，如果没有任何边界约束，本质上就是给黑客递了一把装了自动瞄准的枪。

Agent-Reach 里我把隔离分成了四个等级，不同的技能匹配不同等级，宁严勿松。

Agent-Reach 默认把所有技能放到 L2 沙箱里运行，除非技能开发者明确声明"我这个技能不需要网络、不需要写文件"才能降级到 L1。这里的逻辑很简单：安全策略默认从严，放开权限必须经过显式审批。很多 Agent 生产事故都是因为开发者觉得"跑在本机临时跑一下没关系"，最后把漏洞带到了生产环境。

5.2 Agent-Reach 沙箱的具体配置策略

沙箱的核心不是创建一个隔离环境就完事，而是要把"最小权限"原则落实到系统层面。Agent-Reach 的沙箱配置我总结成五条硬规则，每条都是踩出来的经验——理论上通用容器技术就能满足，但下面这几点是排坑后我最终强化的关键项：

1. 只读文件系统：技能运行的根目录是只读的，只有设计好的临时目录和输出目录可写
2. 网络白名单：默认禁止所有网络访问，只有技能声明了明确的外部域名才放行；放行列表必须写到沙箱配置里
3. 细粒度的系统调用过滤：拦截掉危险的系统调用，比如reboot、mount、ptrace
4. 资源限额：CPU 时间、内存上限、文件大小、子进程数量，逐项设置，超额则直接杀掉任务
5. 临时文件自动清理：沙箱进程退出后，所有写入的临时文件统一回收，不留残留

我举一个具体的配置例子。web2md技能需要的权限是"能访问任意公开网页"和"能写输出文件"，那它在 Agent-Reach 里的沙箱配置大致长这样：

sandbox: level: L2 read_only_root: true network: egress_enabled: true allow_domains: ["*"] block_domains: ["10.0.0.0/8", "169.254.169.254"] resources: cpu_time_sec: 120 memory_mb: 512 max_file_size_mb: 20 max_processes: 4 cleanup: temp_dir: true cache_dir: true

注意这里的网络配置，我特意加了block_domains，用来拦最臭名昭著的元数据 IP（云环境里的169.254.169.254）。如果沙箱能任意访问内网，那 Agent 一旦被提示注入攻击，整个内网都将暴露给攻击者。这个细节也是 Agent-Reach 评估时内部测试人员最早发现的漏洞之一。

5.3 沙箱环境变量泄漏：一次完整的排查链路

在沙箱上线第一周，我就碰到一个意外：技能在沙箱里执行时，能读到宿主环境的数据库密码。用户只是让 Agent 把网页存成 Markdown，不该碰到这些机密。

排查过程是这样的。首先我怀疑是不是沙箱配置没生效，检查 namespace 隔离参数后确认网络和挂载确实独立。接着我做了一个小实验：在宿主机设置一个特殊环境变量，然后在沙箱里执行printenv，发现这个变量依然存在。问题锁定在环境变量传递链路上。

继续追查，发现 Agent-Reach 在启动沙箱进程时，为方便技能定位一些基础配置（如语言、时区），把宿主机的部分环境变量透传了进去。我本意是只传几个白名单变量，结果当时为了图省事直接用 Python 的os.environ全量复制了一份。修复方案分两步：第一步，重构沙箱启动逻辑，切断所有环境变量继承，改成显式传入一个白名单环境变量字典；第二步，把宿主机上的敏感信息全部迁移到独立的密钥管理系统，只在 Agent-Reach 主进程内部解密，沙箱内永远不出现真实的数据库密码。

这个坑的根因其实不是沙箱的技术不行，而是我在边界设计时留了一条"方便之门"。教训很深刻：安全边界最怕的不是敌人太强，而是开发者图方便。现在 Agent-Reach 的所有沙箱配置都必须在代码评审时过一遍"最小权限清单"，我也把这个清单做成了一套自动检查工具，每次上线前自动跑一遍。

5.4 给 Agent 提权之前，先过这张自检清单

我在 Agent-Reach 里沉淀了一份"技能权限评审清单"，每次新技能上线前都按它逐条打勾：

• 该技能是否明确需要访问网络？如果不需要，是否已经设为egress_enabled: false
• 该技能是否只需读取固定路径？如果是，文件系统是否已设为只读
• 技能运行时最长可能跑多久？是否已设定充裕却不至于导致僵尸进程的超时时间
• 技能代码里有没有硬编码走特殊渠道逃逸沙箱的写法
• 技能依赖的第三方库是否存在已知的高危漏洞（上线前跑一次依赖安全扫描）
• 技能是否输出敏感信息？如果输出结果会回传给大模型，是否需要做失敏过滤

这套清单看起来简单，但每次执行都能拦住几个潜在问题。最常拦下的其实是"技能描述和实际行为不一致"——开发者把技能包装成了一个"只读网页"的角色，实际代码里却偷偷写了文件。这不一定是有意的，更多是代码迭代时顺手加的调试逻辑忘删了。清单机制配合代码审查，双保险。

6. 开发过程中最典型的三个坑与完整排查链路

6.1 坑一：技能输出把上下文窗口直接撑爆，"execution terminated due to error"

我最早在 Agent-Reach 里跑一个"整站抓取"技能，准备把某个网站的文档全站保存下来。结果技能没跑完就报错过一次，报错信息是典型的agent execution terminated due to error.。一开始我以为是脚本崩了，去日志里排查却发现脚本正常结束，问题出在模型侧——技能把整站抓到的内容全部回填给了模型，导致多轮调用后上下文超出了模型的 token 上限。

这个坑的本质是上下文预算失衡。技能执行结果动辄几万 token，而模型能接受的上下文总量是有硬边界的。你让模型看到的东西越多，后面的新信息能进来的空间就越小，甚至会直接把请求顶爆。修复思路也很直接：Agent-Reach 里所有技能的输出都不直接进上下文，而是经过三层处理。

第一层是最大长度截断：超过 6000 字符的输出强制截断，截断时优先保留开头部分（通常包含文档标题和核心摘要）。第二层是结构化提取：如果输出本身是网页或文档，先让规则引擎抽取出标题、段落、链接列表，比把原文全量丢进去轻量得多；如果规则不够用，再用一个小型模型做一次离线摘要。第三层是引用保留：我始终把原始输出保存到一个可寻址位置（比如临时文件或对象存储），回填给主模型的只是一段"摘要 + 详细内容存储路径"，如果用户后续追问细节，再按需读取原文。

这套链路下来，单次技能调用的 token 开销从"可能吃掉几十万"压缩到"平均两千以内"，整体稳定性和响应速度都肉眼可见地提升了。

6.2 坑二：多技能并发时的资源竞争与僵尸进程

Agent-Reach 上线没多久，运维同事反馈服务偶发卡死，重启后恢复，但过一阵又复现。我第一反应是看日志里的慢查询和锁竞争，排查半天没发现异常。后来在一次卡死期间强行 dump 了进程堆栈，才发现大量僵尸子进程堆积，把进程表给占满了。

根因出在技能执行的并发管理逻辑上。我最初封装技能调用时，用subprocess.Popen拉起子进程，但缺少两层保障：第一，子进程的退出状态没有在主循环里定期回收（waitpid没接干净）；第二，技能执行超时后只杀了子进程本身，没有杀完整的进程组——技能里如果再拉孙进程，就容易留下孤儿进程继续跑。

修复分三步。第一步，把所有子进程的启动改成进程组模式，超时杀任务时执行killpg，保证整棵进程树不残留。第二步，在沙箱的资源配置里显式限制max_processes: 4，阻断任何"进程无限繁殖"的路径。第三步，写了一个定时调度任务，每三十秒巡检一次子进程回收队列，发现僵尸立即清理。这三步下去之后，Agent-Reach 连续跑了一周没再出同样的卡死问题。

这个坑给了一个重要经验：Agent 的技能执行本质上是不可信代码在跑，必须假设它可能拉出任意数量的子进程，所以一切资源都要在沙箱配置里显式封顶。

6.3 坑三：技能结果被大模型"二次创作"后失真

有一次用户要求 Agent 把一份 JSON 格式的统计数据转成自然语言报告。技能端的输出是一段精确的数字，比如{"sales_total": 1234567.89, "growth_rate": 12.5}。结果模型在生成报告时，把数字"脑补"成了 1230000 和 12%。用户一眼看出对不上，整个任务的信任度瞬间崩了。

问题出在回填机制上。我把技能输出和用户提示词一起喂给模型，模型在生成自然语言时对数字做了"合理化近似"——它觉得 1234567.89 看起来不够整齐，于是自作主张做了四舍五入。这类"无意识失真"在 Agent 场景里特别危险，因为它不像明显的错误那样容易被发现，而是悄悄地把数据精度抹掉了。

修复方案是给技能输出加上一层"数据保真协议"。在 Agent-Reach 里，凡是技能输出中标记为critical_fidelity的字段（如金额、数量、日期），回填给模型时都用强格式包裹，比如用DATA_LOCK[1234567.89]END这种不可被改写的方式标记，同时在系统提示词里明确写死规则："所有 DATA_LOCK 内的内容必须原样呈现，禁止改写、近似或重述。" 这一招虽然笨，但在实测中非常有效，模型对这类强约束的遵循率几乎达到百分之百。

另外，我在技能描述里也加了一条约束：输出结构化数据时，尽量返回"表格 + 原始数值"双通道，而不是只有一段自然语言。这样既方便模型理解语境，又保留了最终核对的锚点。

6.4 这三个坑的共同根源

回头总结这三个典型的坑，它们其实指向同一个根源：Agent 系统中的边界没有设计清楚。技能输出与模型上下文的边界、技能进程与宿主资源的边界、模型生成与事实数据的边界，只要有一条模糊，系统就会从"偶尔出错"滑向"频繁翻车"。

这也是我从 Agent-Reach 这个项目里得到的最大的经验：做 Agent，最关键的不是模型多聪明，而是把每一层边界都做成显式的、可配置的、可测试的。模型负责聪明的部分，工程负责可靠的部分，两边都要在线。

最后分享一个自己常用的质量保障技巧：技能探针

整个 Agent-Reach 做完之后，我沉淀了一个特别想分享的实操技巧——技能探针（Skill Probe）。

所谓技能探针，就是为每一个上线的技能准备一组"最小探测用例"，每次环境变更或技能升级后，自动跑一遍探针来验证技能是否仍然可用。比如web2md的探针就是三组固定 URL：第一组是一个纯静态页面，测基础抓取是否正常；第二组是带 JS 渲染的单页应用，测 Playwright 分支是否正常；第三组是一个故意设置超时的请求，测超时兜底逻辑是否符合预期。

探针的价值在于它把"技能合格"从感觉变成了一套标准。以前新技能上线，大家全凭"应该没什么问题"就放行，之后出事才追悔莫及。现在每个技能必须过探针才允许注册到技能目录里，模型才能看到它。这既保护了业务稳定性，也省掉了后面大量救火时间。

Agent-Reach 这个项目做到现在，给我最大的感受就是：Agent 的名字里带了个"智能"，但真正让它有价值的从来都是背后的工程体系。技能、编排、沙箱、上下文预算、数据保真——这些词单独拿出来都不算性感，但拼在一起，才有可能让一个模型真正变成"能干活"的 Agent。

如果你也在做 Agent 项目，尤其是正准备给 Agent 接技能和工具，我建议你先停下来想想：你的 Agent 有多大的触达范围？这个范围的边界是清晰的还是模糊的？边界一旦模糊，后面所有的问题都会从这个裂缝里钻出来。先把触达做清楚，再谈智能，才是 Agent 工程的正路。