企业官网建设流程全解析

去年年底我在内部跑完一轮 Agent 项目复盘后，把整套方案单独抽出来，起名叫Agent-Reach。名字里的 Agent 不用解释，Reach 才是我想表达的东西——英文里 reach 是“触达、够得着”，但放到 AI Agent 的开发语境里，它其实同时指三件事：工具够得着、记忆够得着、编排够得着。这个项目解决的痛点也很具体：Agent 的 Demo 人人都会跑，但一旦放进真实业务里，它经常“够不着”东西。

先交代一下背景。当时我们手里已经有了不少 Agent 原型：能聊天、能查资料、能调用外部工具，演示时效果相当唬人。可一旦接到真实环境，问题立刻暴露出来——网页抓回来一堆没用的 HTML、上下文被撑爆、工具权限没有边界，甚至 Agent 会自己脑补一个不存在的 API 然后反复重试。这些问题不是模型能力不够，而是外围工程没做好。Agent-Reach 就是围绕“触达能力”做的一整套连接层方案：技能封装、沙箱控制、多 Agent 协作、评测回归。它不训练模型、不重造框架，只解决 Agent 和真实世界之间的“最后一公里”。

这篇内容适合正在做 Agent 开发、被框架选型和 Skill 设计折磨过的朋友。我会把 Agent-Reach 的架构思路、核心实现、选型取舍、踩坑过程从头到尾拆开讲，里面很多细节是跑真实任务时一点点磨出来的，希望能帮你少走点弯路。

1. 为什么叫 Agent-Reach：从“Demo 能跑”到“真正够得着”的差距

1.1 一个让整个项目重写定位的失败案例

先讲一个具体的失败案例。当时我们的任务是做一个“自动整理跨系统信息”的智能体：从内部知识库查资料、从网页抓最新公告、然后汇总成一份周报。演示环境里一切正常——你问它一句，它自己调工具、自己总结，输出一段漂亮的文案。结果放进真实环境后，成功率直接掉到三成左右。

失败的原因拆开看特别有意思，也和“触达”这个词高度相关。第一，网页抓取工具返回的 HTML 原文太长，模型上下文被无关内容占满，跑着跑着就开始“失忆”，忘掉最初的需求；第二，文件权限和网络权限没设计好，它想读的文件读不到，反而偶尔会去尝试调用一个根本不存在的内部接口；第三，多轮任务里缺少结构化的中间状态，子任务做完的结果没有传递到下一步，整个链路就断掉了。

这三个问题都不是模型本身“不够聪明”，而是 Agent 的触达链路太脆弱。当时我也试过换更强的基座模型，但只能缓解，不能根治。后来我想明白一件事：Agent 的能力上限由模型决定，但能力下限由外围工程决定。Agent-Reach 要做的，就是把这条下限稳定地抬上去。

1.2 Reach 的三层含义：工具触达、记忆覆盖、编排纵深

我给 Agent-Reach 定了三层核心语义，整篇文章都围绕这三层展开。

第一层是 Tool Reach，工具触达。Agent 能调用多少外部能力，以及这些能力是否可靠。比如能不能稳定地把网页转成干净的 Markdown、能不能读写指定的文件、能不能调用内部 API。这一层解决的是“手够不够长”的问题。很多 Agent 项目之所以平庸，不是因为模型差，而是工具层太薄、太脆，动不动就返回一堆没解析过的原始数据。

第二层是 Memory Reach，记忆覆盖。任务级的上下文能覆盖多长，关键信息在长任务中会不会丢。这包括短期窗口内的滚动摘要，也包括跨会话的长期记忆。这一层解决的是“脑袋够不够用”的问题。我在实践中发现，很多长任务失败不是模型不会做，而是做到一半把前面的约束条件忘了。

第三层是 Orchestration Reach，编排纵深。多个 Agent 协作时，指令能不能可靠地传递到最末端的执行层。谁拆解任务、谁调用工具、谁汇总结果，这些流程要有一个清晰的协议，而不是把所有上下文广播给所有人。这一层解决的是“团队够不够齐”的问题。

1.3 Agent-Reach 不做什么：拒绝自造 LLM 运行时

定边界和定目标同样重要。Agent-Reach 一开始也走过弯路，差点自己撸一套 Agent 运行时，后来及时刹住了。原因很现实：模型推理、流式输出、函数调用协议这些底层能力，现有框架已经做得很成熟，自己造一轮除了增加维护成本，不会带来额外收益。

所以这个项目的边界很明确：不训练模型，不重写推理引擎，不重复造框架。它专注做连接层——把工具包装成可复用的 Skill，给 Agent 加上沙箱和权限控制，设计多 Agent 之间的协作协议，再配一套评测集来验证“够得着没有”。这样做还有个额外好处：换基座模型的时候，整个外围工程可以原样迁移，不需要重写。

2. Agent-Reach 的整体架构：Skill、Harness 与多 Agent 协作怎么分工

2.1 先厘清一组概念：Agent、Harness、Skill、Tool 分别管什么

在做架构设计之前，必须先厘清社区里经常混着用的几个概念：Agent、Harness、Skill、Tool。

很多人问 harness 和 agent 到底有什么区别，我用自己的话总结：Agent 是“脑子”，负责想；Harness 是“身体”，负责让脑子想的事情能执行下去。没有 harness，Agent 就是一个光会说话不会干活的聊天窗口；没有 Skill，harness 里的工具就是一盘散沙，每次都要在提示词里重新解释一遍怎么用。

2.2 Agent-Reach 的四层架构：模型层、调度层、技能层、执行层

Agent-Reach 的运行时可以简化成四层，每一层只做自己该做的事。

模型层：负责自然语言理解、推理和工具选择判断。这一层是可以替换的，我们内部接入了多个基座模型做对照，发现只要外围工程到位，不同模型之间的差距会被明显拉近。

调度层：也就是 harness 核心。它负责 Agent 主循环、上下文管理、记忆压缩、技能发现与路由。举个例子，模型说“我需要把某个网页存下来”，调度层就去技能注册表里找 description 匹配的 Skill，然后按 Skill 定义的参数格式去调用。

技能层：存放所有 Skill。每个 Skill 是一个独立单元，包含描述文件、脚本、依赖和测试。技能层不关心模型怎么想，只保证“你按我的规则调用，我就给你稳定的结果”。

执行层：真正触碰外部系统的地方，包括沙箱、网络白名单、文件读写网关。这一层也是安全边界，所有工具调用都在这里被审计和约束。

结构上，四层之间是严格向下的依赖关系：模型层不能直接触碰执行层，必须经过调度层和技能层。这样设计的好处是，任何一次工具调用都能被记录、被控制、被回放，出了问题可以直接从审计日志里定位。

2.3 为什么把 Tool 封装成 Skill，而不是直接挂一堆函数

最初版本里，我们把所有能力直接做成 Python 函数列表塞给模型，结果维护起来非常痛苦。每加一个工具，就要改代码、改提示词、重新部署，而且模型经常分不清两个功能相似的工具到底该用哪个。

后来参照社区里 Agent Skills 的思路重构成了 Skill 机制。Claude 最近的 Agent Skills 设计就很典型——把技能拆成 SKILL.md 这样的描述文件，模型按需加载。Agent-Reach 基本沿用了同样的包装方式，原因很简单：让模型自己判断什么时候用哪个工具，而不用开发者在代码里写死调用链。

Skill 封装还有一个关键价值：每个 Skill 可以独立测试。你不用为了验证一个网页抓取功能，就把整个 Agent 跑一遍。改完 Skill A，只跑 Skill A 的测试用例就行。这对后续做评测集回归非常重要。

3. 核心实现：让 Agent 触达网页、文件与下游 API

3.1 Skill 的目录结构与加载机制

Agent-Reach 里的每个 Skill 都长这样：

skill_save_webpage/ ├── SKILL.md ├── src/ │ └── save_webpage.py ├── requirements.txt └── tests/ └── test_save_webpage.py

SKILL.md 是技能的描述文件，也是模型能否正确调用它的关键。我们内部约定这个文件必须包含三块内容：name用来做唯一标识；description用两三句话说明这个技能能做什么、适合什么场景；parameters定义参数名、类型、是否必填。description 写得好不好，直接决定模型在意图识别阶段能不能找到这个技能。

--- name: save_webpage description: 将指定 URL 的网页正文抓取并保存为 Markdown 文件，适用于资料收集、简报生成、网页内容存档 version: 1.2.0 parameters: - name: url description: 目标网页地址 type: string required: true - name: output_dir description: 保存目录，默认为 /data/write/webpages type: string required: false ---

调度层启动时会扫描技能目录，把每个 SKILL.md 的 name、description、version 注册进技能表。模型只需要看到这张“技能菜单”，就知道自己有哪些能力可用；真正执行时才把对应脚本拉起来。这种延迟加载的方式也能省下不少上下文空间。

3.2 实战：把网页保存成 Markdown 的 Skill

这个 Skill 是 Agent-Reach 里最常用的一个，对应的需求也很典型：让 Agent 将网页保存成 Markdown。核心思路是三步：抓取页面 → 提取正文 → 转成 Markdown。为什么要用正文提取而不是直接存 HTML？因为 HTML 里有大量导航、广告、脚本标签，这些东西对模型来说全是噪音，塞进上下文就是灾难。

import argparse from urllib.parse import urlparse import trafilatura from markdownify import markdownify as md def save_webpage(url: str, output_dir: str) -> str: downloaded = trafilatura.fetch_url(url) if not downloaded: return "ERROR: 页面抓取失败，请确认 URL 可访问" content = trafilatura.extract(downloaded, include_links=True) if not content: return "ERROR: 正文提取为空，可能是页面需要渲染或内容被反爬拦截" filename = urlparse(url).netloc + "_" + str(abs(hash(url))) + ".md" md_content = md(content) with open(f"{output_dir}/{filename}", "w", encoding="utf-8") as f: f.write(md_content) return f"OK: 已保存到 {filename}（{len(md_content)} 字符）" if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--url", required=True) parser.add_argument("--output-dir", default="/data/write/webpages") args = parser.parse_args() print(save_webpage(args.url, args.output_dir))

这里有一个非常关键的细节：工具返回给模型的文本必须短。我们只返回“文件路径 + 字符数”，而不是把整篇 Markdown 塞回去。模型知道文件存在、在哪、多大，就已经足够继续决策了；如果后续需要基于全文修改，它可以再调用一个read_file的 Skill 按需读取。这个设计决策避免了 90% 的上下文溢出问题。

3.3 记忆模块：短期缓冲与长期持久化

Agent 的记忆能力是“够不够得着”的第二层。我给 Agent-Reach 设计了短期和长期两级记忆，分工完全不同。

短期记忆负责运行期内的上下文管理。当一个任务跑了很多轮、历史消息快要把上下文窗口占满时，调度层会自动触发压缩：把早期的对话交给一个摘要模型压缩成结构化要点，然后替换掉原始消息。

# 简化后的滚动摘要逻辑 tokens_used = estimate_tokens(messages) if tokens_used / context_limit > 0.8: early_messages = messages[:-20] summary = summarizer.compress(early_messages) messages = [{"role": "system", "content": f"早期对话摘要：{summary}"}] + messages[-20:]

长期记忆则负责跨会话的信息复用。任务结束后，Agent-Reach 会把目标、关键决策、产物路径写入一个本地索引（我们用 JSON 文件加简单向量检索就够用了，没上重型数据库）。下次遇到同类任务时，调度层会先检索历史记录，把相关经验注入系统提示词，让 Agent 不必从零开始摸索。

我记得有个很典型的例子：第一次让 Agent 整理某个内部系统的数据时，它费了好大劲才搞明白字段含义；第二次再跑类似任务，长期记忆里已经有字段映射说明，整个任务的时间缩短了将近一半。这就是记忆覆盖带来的直接收益。

3.4 多 Agent 协作时的共享上下文设计

Agent-Reach 在复杂任务里会拉起多个子 Agent 协作，比如一个负责抓取资料、一个负责分析数据、一个负责生成报告。最开始我们图省事，把完整对话历史复制给每个子 Agent，结果 token 消耗直接翻了三倍，而且子 Agent 经常被不相关的讨论带偏。

后来改成了“任务单”模式：主编 Agent 负责拆解任务，为每个子 Agent 生成一张独立的任务单，里面只包含它需要的输入字段、目标和输出位置。子 Agent 完成后回传结构化的结果摘要，主编 Agent 再把所有摘要汇总成最终输出。

任务单（子 Agent 视角）： - 角色：资料抓取员 - 输入：url 列表 ["https://...", "https://..."] - 目标：将每个 URL 转为 Markdown，存入 /data/write/webpages/ - 输出格式：JSON [{url, file_path, char_count}] - 约束：不修改已存在的文件，不访问外网

这个设计和上下文管理是同一个思路：每个人只需要知道自己该知道的部分。多 Agent 协作的失败，绝大多数不是因为模型能力，而是信息传递方式太粗暴。

4. 框架选型实录：LangChain、Dify、CrewAI 到底怎么选

4.1 三个框架的边界与性格差异

网上关于 LangChain、Dify、CrewAI 哪个好的讨论非常多，我的回答是：它们根本不是同一个层面的东西，硬比没有意义。用我之前一张整理过的对照表来说明：

简单说：LangChain 是“乐高积木”，什么都能拼，但你要自己看说明书；Dify 是“精装房”，拎包入住很方便，但想改承重墙就麻烦；CrewAI 是“剧组管理工具”，帮你把不同角色组织起来拍戏，但剧本太复杂它也头疼。

4.2 Agent-Reach 的最终选型与理由

Agent-Reach 的实际选型可以用一句话概括：工具层完全自研，多 Agent 剧本用 CrewAI，复杂状态流才用 LangGraph，业务前台可以接 Dify。

工具层和沙箱自研，是因为我们需要精确控制权限、审计日志和评测插桩。框架里现成的工具调用机制通常做得比较薄，很难满足安全约束和评测回归的双重需求。与其在框架里打补丁，不如自己维护一层不重的工具网关。

多 Agent 协作层用 CrewAI，是因为我们的需求很契合它的设计理念：几个角色各有分工，按固定剧本协作。CrewAI 的 role、task、process 模型用起来很直观，模型只需要知道自己是什么角色、该完成什么任务。但如果哪天需要跑带条件分支的复杂状态流，我会切到 LangGraph——它是图结构的，能显式表达状态转移，而不是靠提示词硬撑。

至于 LangChain 全家桶，我的态度是“按需引入，不搞全家福”。它在链式调用和工具封装上有成熟的地方，但没必要为了用而用。框架应该是手段，不是信仰。

4.3 Rust Agent 方向：为什么值得持续关注

热词里有一类“基于 Rust 语言 AI Agent”的话题，我也简单说下我的观察。Rust 在 Agent 领域最大的优势是：类型安全、内存安全、性能好，特别适合写工具网关、沙箱管理和高并发请求转发这类对资源隔离和稳定性敏感的组件。Python 里很多要到运行时才暴露的错误，在 Rust 编译期就被挡住了。

但也要客观地说，目前 Agent 编排层的生态仍然是 Python 的天下，大部分现成的 Skill、工具库都长在 Python 生态里。Agent-Reach 的折中方案是：外围用 Python 写编排和技能，工具网关这类高并发组件用 Rust 单独维护。这样既能吃到 Rust 的性能红利，又不会被过早地带进“全量重写”的坑。我建议关注 Rust Agent 方向，但不必一步到位。

5. 沙箱与安全：能力半径越大，约束就要越具体

5.1 为什么每个外部动作都要过一道沙箱

谈到 Agent 安全，很多人第一反应是防“恶意 Agent”。但我在实际项目里最大的体会是：真正的风险不是恶意，而是幻觉加上过度自信。模型可能误以为某个命令是对的，就真的去执行；可能把内部 API 的地址记错了，就反复去请求；可能读到了一个文件，就顺手把它写回了错误的位置。

所以 Agent-Reach 里每一个外部动作都必须经过沙箱。沙箱不是要限制 Agent 的创造力，而是给它一个透明的玻璃房间——在里面怎么折腾都行，但接触外部世界必须走受控的门。没有门，就没有审计；没有审计，出了问题你连从哪查都不知道。

5.2 网络、文件、命令三个维度的权限模型

我们的沙箱权限模型只做三件事：网络白名单、文件读写分区、命令限制。

这三条规则配合起来，基本上能防住我在项目里遇到过的绝大多数问题。比如之前那个“网页转 Markdown”的 Skill，它只允许访问目标网址所在的几个域名，只允许往/data/write/webpages/下写文件，不允许执行任意 shell 命令。这样即便模型抽风想要做点什么出格的事，也会在沙箱这层被拦下。

5.3 一套可复用的沙箱配置示例

Agent-Reach 用的是容器做执行层隔离。下面是一份可以直接抄的 docker-compose 配置示例：

services: agent-exec: image: python:3.11-slim read_only: true tmpfs: - /tmp:size=100m volumes: - ./data_read:/data/read:ro - ./data_write:/data/write:rw cap_drop: - ALL security_opt: - no-new-privileges:true mem_limit: 1g cpus: "1.0" network_mode: none

如果某个任务确实需要访问外部 API，我会把network_mode: none换成自定义网络，并配置统一出口网关，只放行白名单域名的 DNS 解析和连接请求。看起来更复杂，但这就是 Agent 触达外部世界必须要付出的安全成本。

密钥处理上也有一个规矩：所有 API Key、Token 一律通过环境变量注入，容器内代码不要把它们打回日志。工具返回给模型的文本里绝不允许出现密钥内容，这一点要在 Skill 的代码规范里写死，靠提醒不可靠，要靠约定和审查。

6. 评测集与回归测试：怎么证明 Agent-Reach 够得着

6.1 通用知识评测集不能替代业务评测集

很多团队验证 Agent 的方式是跑一遍通用知识类评测集，看个分数就完事。我的看法是：通用评测集测的是模型的知识储备和基础推理能力，它根本测不出 Agent 的“触达能力”。网页抓取成功率高不高、工具调用参数对不对、多轮任务里上下文保持得稳不稳，这些问题在通用评测集里一个都答不了。

所以 Agent-Reach 单独建了一套业务评测集。办法很朴素：从真实业务里挑出 20 到 50 个代表性任务，做成固定用例，每个用例带上期望动作序列和期望产物。这套评测集跑一次，比跑十个通用榜单都有说服力。

6.2 评测维度设计与用例样例

我们内部评测主要看五个维度：

用例的 JSON 格式大概是这样的：

{ "id": "case_007", "task": "把 https://example.com/blog/agent-reach 保存成 Markdown，放到 /data/write/webpages/ 下", "expected_actions": ["save_webpage"], "expected_actions_order": ["save_webpage"], "expected_file": "example.com_xxx.md", "must_not_actions": ["shell_exec", "delete_file", "write_to_read_dir"] }

执行时会记录完整的动作轨迹，和 expected_actions 做比对，同时检查 must_not_actions 里有没有违规。这个设计特别适合防回归——改了一个 Skill 之后，最怕的就是别的用例跟着挂。

6.3 把评测跑进 CI，每次改 Skill 自动回归

评测集如果没有融入开发流程，很快就会变成摆设。Agent-Reach 的规矩是：任何 Skill 改动必须过评测集。我们把评测脚本挂到了 CI 流水线里，每次 push 代码、更新 Skill 版本或调整提示词，就自动触发全量回归。

回归流程分三步：先重新构建沙箱环境，确保依赖干净；然后逐条执行评测用例，记录每个动作日志；最后生成一份报告，列出各维度的得分和失败用例的完整轨迹。失败时可以直接看到是哪个环节出了问题——模型选错工具、参数格式不对、还是沙箱拦截了本不该拦的操作。

这套评测集建好之后，我最大的感受是：Agent 开发终于从“感觉差不多能用”变成了“有数据证明这个改法有效”。也正因为有这套回归，后面几次调整记忆压缩策略时，才敢放心地改代码，不用整天提心吊胆怕弄坏旧功能。

7. 落地过程中踩过的坑与排查思路

7.1 工具返回超长导致上下文漂移：一次完整的排查链路

这个坑几乎是每个 Agent 项目都会踩的。我们的现象很典型：任务跑到三分之一之后，模型开始胡言乱语，甚至引用一些上下文里根本不存在的“事实”。

排查过程是这样的。第一步，我打开审计日志，检查最近一次工具调用的返回体，发现网页正文八万字符被原封不动塞回了上下文。第二步，粗算了一下 token 开销：八万字符大概两万 token，已经把上下文窗口吃掉一大半。第三步，进一步对比正常用例和失败用例，发现失败任务的上下文在工具调用后 token 数出现断崖式上涨，而工具返回内容恰好包含了大量与任务无关的正文。第四步定位根因：Skill 把“全文”当成返回值，而不是只返回“摘要和文件路径”。第五步的修复就是改返回策略——只回传文件名、路径和字符数。第六步验证：同一个用例连续跑五次，上下文保持率从不到五成升到了九成以上。

这个坑的启示是：工具返回给模型的文本本身就是一个信息通道，通道设计不好，模型再聪明也没用。以后所有 Skill 定义返回值时，我都会先问一句：这个返回内容真的需要模型逐字阅读吗？

7.2 模型幻觉式调用工具：它调了一个根本不存在的 API

另一个高频问题是：模型调用了一个根本不存在的工具或 API。日志里显示它用了一个看起来很像那么回事的端点，还带着合理的参数，重试了三次才放弃。我第一反应是代码里有 bug，检查半天发现工具注册表里压根没有这个工具——这些调用完全是模型从上下文里的只言片语“脑补”出来的。

对策有三条。第一，在工具网关层面做 schema 校验，模型调用的端点必须存在于注册表，不认识的一律返回“NO_SUCH_TOOL”，而不是含糊的 404。第二，在系统提示词里明确列出现在不提供哪些能力，让模型知道边界在哪。第三，给重试策略加上限和退避，连续失败三次就强制换思路。这个坑让我意识到，Agent 的“自信”和“幻觉”是双刃剑，工程上必须用一个不依赖模型自觉的校验层兜底。

7.3 多 Agent 协作时的 Token 消耗失控

前面提到过，最初给多个子 Agent 复制完整上下文的方案，让 token 消耗直接翻了三倍。我一开始还以为是哪里配置重复了，后来逐个 Agent 打印消息列表才发现——每个子 Agent 都重新读了一遍完整的历史对话，而它真正需要的只是自己那部分输入。

修复方案就是“任务单”模式，每个子 Agent 只拿自己需要的输入槽位，只回传结构化结果，而不是原始对话。改完之后同样任务的总 token 消耗下降了六成左右，子 Agent 的输出质量反而更高了，因为它不再被无关内容干扰。这个优化对成本的影响非常直观，一个月下来 API 账单的差别很明显。

7.4 Skill 命名与版本管理的冲突

最后一个坑是版本管理。有一次我更新了网页保存 Skill 的行为——调整了输出目录结构——但旧版本 Skill 还在注册表里躺着，模型有时候命中新版、有时候命中旧版，行为表现完全不一致。查了半天才发现是技能缓存的锅。

后来定了一条硬规矩：SKILL.md 里的 name+version 必须在注册表里唯一；版本变更时要清理旧缓存；调度层启动时校验所有 Skill 的描述文件，发现同名的旧版本直接标记为失效。现在每次更新 Skill 都会自动触发一轮评测回归，确认只有新版本在生效。

这些坑单看每一个都不算复杂，但它们组合在一起就是 Agent 从“实验室玩具”变成“生产工具”之间的全部距离。我在实际项目中最大的体会是：Agent-Reach 这个项目的价值不在于某个亮点技术，而在于把工具触达、记忆覆盖、编排纵深、安全边界和评测闭环这些看似琐碎的工程细节全部串了起来。同事后来调侃说，Reach 与其翻译成“触达”，不如翻译成“伸手去够”——我觉得挺好，工程上做 Agent，本来就是在不断把够不着的东西够到手。下一步我打算继续打磨网页转 Markdown 这个 Skill，让它能处理动态渲染的页面，同时把评测集从几十个用例扩展到一百个。