企业官网建设流程全解析

1. 为什么我要做一轮“只读试点”

1.1 从一次翻车说起

去年年底，我接手了一个内部效率工具的重构。需求很朴素：让一个智能体（Agent）帮团队自动整理每周的会议纪要、拉取相关文档、生成待办清单。听起来是个典型的“规划 + 记忆 + 工具调用”三件套场景，我一开始也确实是这么设计的——给它一个规划器，挂一个向量库当长期记忆，再开放几个工具接口让它自己去查、去写、去发。

结果第一周就出事了。它在一次任务里连续调用了七次文档检索工具，每次都把结果塞进上下文，最后上下文爆了，任务中断；更麻烦的是，它把一份还没定稿的草稿当成正式文档，写进了待办清单里，还自动同步给了相关同事。虽然只是内部工具，但那种“它自己决定要做什么、还真的做了”的失控感，让我意识到一个问题：在把写权限交给 Agent 之前，我根本没搞清楚它的规划边界、记忆边界和工具边界到底在哪。

于是就有了这轮“只读试点”。所谓只读，就是让 Agent 在整条链路上只允许读取和推理，不允许任何写操作、不允许任何对外发送、不允许修改任何持久化状态。目的很明确：在零副作用的沙箱里，把它的规划逻辑、记忆机制、工具调用边界彻底摸清楚，再决定哪些权限可以逐步放开。

1.2 只读试点到底在试什么

很多人一听“只读”就觉得是降级方案，是没办法才做的妥协。我的看法正相反：只读试点是 Agent 上线前性价比最高的一次压力测试。它同时验证三件事。

第一，规划是否收敛。一个任务丢进去，它是三步走完还是绕二十步？会不会陷入“检索—反思—再检索”的死循环？只读环境下没有写操作兜底，规划一旦发散，你立刻就能从日志里看出来。

第二，记忆是否可信。长期记忆里存的东西，到底是它真实观察到的，还是它自己脑补的？只读试点里所有写入记忆的动作都被拦截，你就能对比“它以为它记得的”和“它实际读到的”之间的差距。

第三，工具边界是否清晰。每个工具能做什么、不能做什么、返回什么格式、超时怎么办、被拒绝调用时它怎么反应——这些在只读模式下暴露得最彻底，因为没有写操作去掩盖问题。

这轮试点适合谁参考？我觉得三类人最该看：一是正在设计 Agent 权限体系的工程师，二是被 Agent “自作主张”坑过的产品负责人，三是想给团队引入自动化但不敢放开写权限的技术管理者。哪怕你用的是完全不同的技术栈，这套“先只读、再分级放开”的思路是通用的。

2. 整体设计：把 Agent 拆成三个可观测的边界

2.1 规划、记忆、工具为什么必须分开看

我见过不少 Agent 项目，把规划、记忆、工具揉在一个大循环里，出了问题只能看一坨日志，根本定位不到是哪一层坏了。这次试点我做的第一件事，就是在架构上把三者物理隔离，每一层都有独立的输入输出契约和日志。

规划层只负责“下一步做什么”，它的输出是一个结构化的动作意图，比如{"action": "retrieve", "target": "meeting_notes", "reason": "..."}。它不直接碰工具，也不直接读写记忆。

记忆层只负责“存什么、取什么”，它对外暴露的是读写接口，但在只读试点里，写接口全部被替换成“记录意图但不执行”的桩函数。

工具层只负责“执行一个具体动作并返回结果”，它不关心这个动作是谁要求的、为什么要求。

这么拆的好处是：当 Agent 行为异常时，我能快速判断是规划跑偏了、记忆污染了，还是工具返回了意料之外的东西。举个实际例子，有一次它反复检索同一份文档，我一看日志，规划层给出的 reason 是“上次检索结果不完整”，但工具层返回的其实是完整内容——问题出在记忆层把上一次的结果截断了。如果没有分层，这个 bug 能查一整天。

2.2 只读约束怎么落地才不流于形式

“只读”两个字说起来简单，落地时最容易变成一句口号。我的做法是在工具网关层做硬拦截，而不是靠提示词去“请求” Agent 不要写。

具体来说，所有工具在注册时都要声明自己的能力标签：read、write、external。只读试点期间，网关只放行带read标签的工具，任何write或external调用直接返回一个标准化的拒绝响应，格式统一为{"status": "denied", "reason": "read_only_mode"}。

这里有个关键细节：拒绝响应必须和正常响应一样结构化，否则 Agent 会因为拿到一个非预期格式而崩溃或者胡乱重试。我一开始图省事，直接抛异常，结果 Agent 捕获异常后开始疯狂重试同一个写操作，日志瞬间被刷爆。改成结构化拒绝后，它就能“理解”这个动作被拒绝了，转而走别的路径。

另外，记忆层的写操作我也做了同样的处理：不是禁止它产生“想写”的意图，而是把写意图记录下来但不落库。这样我既能观察它想记什么，又不会被污染。

2.3 观测指标先定好，别等出事再补

只读试点最大的价值是观测，所以指标必须提前定。我这次盯的主要是四类：

这些指标不需要多复杂的监控系统，我一开始就是用日志文件加一个简单的解析脚本跑出来的。关键是先有数据，再谈优化，别一上来就搞大而全的可观测平台。

3. 核心细节：三个边界各自的坑与解法

3.1 规划边界：它到底能想多远

规划层最容易出的问题是发散。我给它设了一个硬上限：单任务最多 15 步，超过就强制终止并记录。为什么是 15？因为我统计了正常任务的步数分布，90% 的任务在 8 步内完成，15 步已经覆盖到 99% 的正常情况，再往上基本都是异常。

但光有步数上限不够，还得有循环检测。我的做法是给每个动作意图算一个指纹（动作类型 + 目标 + 关键参数），如果同一个指纹在最近 5 步内出现过两次，就判定为潜在循环，触发一次“强制反思”——让规划层基于当前已有信息直接给出结论，而不是继续检索。

实测下来，这个机制拦住了大部分“检索—发现不够—再检索”的死循环。有个细节值得说：反思提示词里必须明确告诉它“你已有的信息是什么”，否则它会因为不知道手上有什么而继续要求检索。我一开始的反思提示词只写了“请基于现有信息作答”，结果它回复“我还没有足够信息”，然后继续循环。后来改成把已检索到的内容摘要直接拼进提示词，问题就解决了。

还有一个坑是规划粒度过细。有些任务它会把“打开文档、读取第一段、读取第二段”拆成好几步，导致步数虚高。我的处理方式是在规划提示词里明确要求“每个动作应该是一个有意义的语义单元，而不是机械的操作步骤”。这个调整让平均步数从 11 降到了 7。

3.2 记忆边界：它记住的到底是不是真的

记忆层最危险的不是“记不住”，而是“记错了还坚信”。只读试点里我做了两件事来暴露这个问题。

第一，记忆写入全部拦截但记录意图。每次它想写记忆，我都把写入内容、写入原因、触发时机记下来。试点结束后我人工抽查了 200 条写意图，发现有 30 多条是它把“推测”当成了“事实”。比如它读到一份文档说“项目预计 Q3 上线”，就想记成“项目 Q3 上线”，丢掉了“预计”这个关键限定词。

第二，记忆读取时做来源标注。每条被读取的记忆都带上来源标签：是来自本次任务的观察，还是来自历史记忆，还是来自模型自身的先验。这样在分析时我就能判断，它的某个结论到底是基于真实数据还是基于“它以为它知道”。

这里有个实操心得：记忆的粒度宁粗勿细。我一开始把记忆切得很碎，一句话一条，结果检索时经常拼不出完整语义，Agent 就会去猜。后来改成按“事件”或“结论”为单位存储，每条记忆自带上下文摘要，命中率和准确率都明显提升。

另外，只读试点期间我特意没有清空历史记忆，而是让它带着一份“可能被污染”的记忆去跑。目的就是看它在记忆不可靠时会怎么表现。结果发现，当记忆和当前观察冲突时，它大约有 70% 的概率会优先相信记忆。这个数据直接影响了后续的设计——正式上线时我加了一条规则：当前观察的优先级永远高于历史记忆，冲突时必须重新验证。

3.3 工具边界：它能碰什么、碰不到时怎么办

工具层的核心问题是边界模糊。很多工具接口设计得太“宽容”，比如一个检索工具，既能按关键词搜，又能按时间范围搜，还能返回不同详细程度的结果，Agent 就会在各种参数组合里迷失。

我的做法是把工具做窄。只读试点期间，每个工具只做一件事，参数尽量少，返回格式固定。比如文档检索工具就只接受一个查询字符串，返回固定格式的摘要列表。需要更复杂的能力？那就注册一个新工具，而不是给旧工具加参数。

这样做的好处是 Agent 的选择成本降低了，调用成功率从最初的 68% 提升到了 94%。代价是工具数量变多了，但工具注册是开发期的事，运行期的稳定性更重要。

被拒绝调用时的处理也是重点。前面说过，拒绝响应要结构化。但光结构化还不够，还得在规划提示词里明确告诉它“被拒绝是正常情况，不要重试同一个动作”。我加了这个说明之后，因拒绝导致的重试从平均 3.2 次降到了 0.4 次。

还有一个容易被忽略的点：工具超时。只读试点里我给每个工具设了 5 秒超时，超时后返回一个明确的超时响应。结果发现有些检索工具在数据量大时会频繁超时，Agent 拿到超时响应后有时会换个说法再试一次，有时直接放弃。这个行为本身没有对错，但让我意识到超时阈值需要根据工具的实际性能来定，不能一刀切。后来我按工具类型分别设了 3 秒、5 秒、10 秒三档。

4. 实操过程：一轮完整的只读试点怎么跑

4.1 环境准备与工具注册

先说环境。我用的是一个最小化的本地环境，一个进程跑 Agent 主循环，一个进程跑工具网关，两者通过本地消息队列通信。记忆层用一个轻量的嵌入式数据库，只读模式下所有写操作走桩函数。

工具注册的配置大概长这样：

TOOLS = [ { "name": "search_docs", "capability": "read", "timeout": 5, "params": {"query": "string"}, "returns": "list[doc_summary]" }, { "name": "read_doc", "capability": "read", "timeout": 3, "params": {"doc_id": "string"}, "returns": "doc_content" }, { "name": "write_todo", "capability": "write", "timeout": 3, "params": {"content": "string"}, "returns": "ack" } ]

网关启动时读取这份配置，只放行capability == "read"的工具。write_todo虽然注册了，但调用时直接返回拒绝响应。这样我既能观察 Agent 在需要写的时候会怎么做，又不会真的产生副作用。

注意：工具的能力标签一定要在注册时声明，而不是在调用时判断。调用时判断容易漏，而且日志里看不出来哪些工具本来就不该被调用。

4.2 规划提示词的设计要点

规划提示词是整轮试点的灵魂。我改了很多版，最后稳定下来的结构包含四部分：

第一部分是角色与目标，明确告诉它“你是一个只读环境下的助手，只能读取和推理，不能修改任何东西”。

第二部分是可用工具清单，只列read类工具，并说明每个工具的用途和返回格式。

第三部分是行为约束，包括最大步数、循环检测规则、被拒绝时的处理方式。

第四部分是输出格式，要求它每一步都输出结构化的动作意图，而不是自然语言。

这里有个细节：约束要写在提示词里，但不能只靠提示词。提示词是“软约束”，网关拦截是“硬约束”，两者必须配合。我试过只靠提示词，结果它偶尔会“忘记”约束去调用写工具；也试过只靠网关，结果它被拒绝后不知道该怎么办，反复重试。两者结合才稳。

4.3 跑一轮完整任务的现场记录

我拿一个真实场景来跑：整理某次会议的待办事项。任务描述是“根据会议纪要文档，提取所有待办事项，并标注负责人和截止时间”。

第一轮，它先调用search_docs搜索“会议纪要”，返回了 3 个候选文档。然后它调用read_doc读取了第一个文档，发现内容不完整，又读了第二个。读完第二个后，它尝试调用write_todo写入一条待办，被网关拒绝。拿到拒绝响应后，它没有重试，而是继续读取第三个文档，然后输出了结构化的待办列表。

整个过程 6 步，没有循环，没有越权重试。但我在日志里发现一个问题：它读取第二个文档时，其实第一个文档已经包含了大部分待办，它多读了一个文档。这说明规划层在“信息是否足够”的判断上偏保守。这个观察直接导致我后来在提示词里加了一条“如果已有信息能覆盖任务要求的 80%，可以直接作答”。

第二轮我故意把任务改得更模糊：“看看这次会议有什么要跟进的”。结果它花了 11 步，检索了 5 个文档，最后输出的内容里混入了一些不属于待办的信息。这暴露了任务描述模糊时规划容易发散的问题。正式上线时我加了一个前置步骤：如果任务描述缺少关键要素（对象、动作、范围），先让 Agent 反问澄清，而不是直接开跑。

4.4 数据回收与分析

跑完 50 轮试点任务后，我把日志导出来做了统计。几个关键数字：

• 平均步数 7.3，最大 14，触发循环检测 6 次
• 工具调用成功率 94%，被拒 23 次，其中 19 次是写操作，4 次是未注册工具
• 记忆写意图 156 条，人工抽查 200 条中 30 多条存在“推测当事实”
• 因拒绝导致的重试平均 0.4 次，因超时导致的重试平均 1.1 次

这些数字直接指导了后续的权限放开策略：先放开低风险的写操作（比如写内部草稿），观察一段时间后再放开对外发送。记忆层则加了一道“事实校验”环节，任何写入前先和当前观察比对。

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

5.1 它为什么总是重复调用同一个工具

这是只读试点里最高频的问题。原因通常有三个：一是工具返回格式不固定，Agent 每次拿到的结构不一样，就以为没拿到；二是规划提示词里没有说明“已有信息足够时应该停止”；三是记忆层没有把上一次的调用结果存下来，导致它“忘了自己查过”。

排查顺序建议：先看工具返回是否结构化且稳定，再看提示词是否有停止条件，最后看记忆层是否记录了调用历史。我遇到的那次是第二个原因，加了停止条件后重复调用从平均 4.2 次降到了 0.8 次。

5.2 被拒绝后它为什么反复重试

前面提过，核心原因是拒绝响应不够结构化，或者提示词里没说清楚“被拒绝是正常的”。还有一个隐藏原因是拒绝原因太模糊。如果只返回denied，它可能会猜测“是不是参数不对”然后换个参数重试。我的做法是在拒绝响应里带上明确原因，比如{"status": "denied", "reason": "read_only_mode", "hint": "该操作在只读模式下不可用，请基于已有信息作答"}。加了 hint 之后，重试基本消失了。

5.3 记忆冲突时它为什么偏向旧记忆

这个问题的根源在于记忆的权重设计。如果历史记忆在检索时总是排在前面，Agent 自然会优先相信它。我的解法是给记忆加时间衰减和来源权重：本次任务观察权重最高，近期记忆次之，远期记忆最低。冲突时强制以高权重来源为准。调整后，记忆冲突导致的错误从 30% 降到了 8% 左右。

5.4 任务模糊时怎么防止规划发散

最有效的办法不是让规划器更聪明，而是在规划之前加一道澄清关卡。具体做法是：任务进入规划层之前，先过一个轻量的“完整性检查”，如果缺少关键要素，就生成一个澄清问题返回给用户，而不是硬着头皮往下跑。这个改动让模糊任务的平均步数从 11 降到了 6，输出质量也明显提升。

5.5 常见问题速查表

6. 只读试点之后，权限怎么分级放开

跑完这轮试点，我最大的体会是：Agent 的权限不应该是一次性给的，而应该是根据观测数据逐步放开的。只读试点就是那个“零级”状态，它让你在没有任何风险的情况下看清 Agent 的真实行为。

我的分级放开策略大概是这样：第一级只读，验证规划和记忆；第二级放开低风险写操作，比如写内部草稿、写日志，但所有写操作都要经过人工确认；第三级放开高频低风险写操作，取消人工确认但保留审计日志；第四级才考虑对外发送类操作，而且必须带频率限制和内容审核。

每一级放开之前，都要用上一级的观测数据来证明“它在类似场景下没有出过问题”。这个证明过程不能靠感觉，要靠数据。比如第二级放开前，我要求只读试点里同类任务的规划步数稳定、工具调用成功率高于 95%、没有越权尝试。达不到就继续跑，不急着放开。

还有一个我踩过的坑：不要因为只读试点跑得好就一次性放开所有写权限。只读环境下 Agent 的行为和可写环境下是不一样的，一旦它能写，它的规划策略可能会变——它会开始“规划怎么写”而不仅仅是“规划怎么读”。所以每一级放开后都要重新跑一轮观测，确认行为没有退化。

最后分享一个实用技巧：只读试点期间产生的日志，不要跑完就删。它们是后续权限放开时最好的对照基线。我到现在还保留着那 50 轮试点的完整日志，每次调整权限或提示词，都会拿新日志和基线对比，看行为有没有偏移。这个习惯帮我提前发现了好几次潜在的退化。