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

1.1 从一次失控的Agent任务说起

去年年底我接手了一个内部工具链的改造需求，核心目标是把几个重复性很高的运维巡检动作交给一个Agent去自动完成。当时团队里几个人都很兴奋，觉得终于可以摆脱每天手动敲命令、翻日志、写巡检报告的日子了。我们花了两周时间把规划模块、记忆模块和工具调用层拼起来，跑通了第一个端到端流程。结果第一次放到真实环境里跑，它就给了我一个结结实实的教训。

那个Agent在规划阶段把“检查磁盘使用率”和“清理临时文件”两个动作合并成了一个步骤，然后在工具调用时直接对生产环境的一台机器执行了删除操作。虽然删的是临时目录，但那个目录里恰好有另一个服务正在使用的缓存文件，导致下游一个任务队列堵了将近四十分钟。事后复盘，问题出在三个地方：规划层没有区分“只读检查”和“写操作”的边界，记忆层没有把上一次类似操作的上下文带进来，工具层没有对危险动作做二次确认。这三个问题单独看都不致命，但叠在一起就变成了事故。

这次经历让我意识到一件事：Agent的能力上限不取决于它能不能调用工具，而取决于我们有没有把它的行为边界说清楚。于是就有了这一轮“只读试点”——在一个完全隔离的环境里，只允许Agent执行读取类操作，把规划、记忆、工具边界这三个核心模块的行为彻底摸一遍。

1.2 只读试点的核心目标与适用人群

所谓“只读试点”，就是给Agent划定一个最小权限的运行域：它可以看到环境状态、可以读取配置和日志、可以查询接口返回，但绝对不能执行任何写入、删除、修改、重启类的动作。这个试点的目标不是验证Agent有多聪明，而是验证它在受限条件下能不能稳定地完成规划、记忆和工具调用这三件事。

具体来说，这一轮试点要回答四个问题。第一，Agent的规划模块在只读约束下会不会产生“越界意图”，也就是它会不会试图规划一个包含写操作的步骤。第二，记忆模块能不能正确区分“历史只读操作”和“历史写操作”，避免把写操作的上下文错误地应用到只读场景。第三，工具边界怎么定义才能既让Agent有足够的感知能力，又不给它任何破坏机会。第四，当Agent遇到权限拒绝时，它的降级策略是什么，是直接报错还是能自动切换到替代方案。

这套方法适合几类人参考。一是正在做Agent落地但还没找到合适切入点的开发者，只读试点是一个风险极低的起步方式。二是已经跑通了Agent基本流程但担心线上安全的团队，可以把只读试点当作上线前的强制关卡。三是对Agent规划、记忆、工具调用这三个模块的协作机制感兴趣的技术人员，这篇文章会把每个模块在只读约束下的行为细节拆开讲。

1.3 试点环境的整体设计思路

环境设计上我遵循了一个原则：把Agent当成一个“只能看不能碰”的实习生。它有自己的工作台，工作台上放着各种只读工具，比如日志查询接口、配置读取接口、状态监控接口、文件内容查看接口。它看不到任何写操作的入口，即使它在规划阶段产生了写操作的意图，工具层也会直接拒绝并返回一个明确的错误码。

整个环境分成三层。最上层是Agent核心，包含规划器和记忆库。中间层是工具网关，负责权限校验和请求转发。最下层是模拟环境，里面跑着几个假服务，有正常的日志输出、有模拟的配置变更记录、有周期性的状态上报。工具网关的权限表是白名单机制，只有明确列出的只读接口才能被调用，其他一律返回403。

这个设计的好处是，我可以在不碰任何真实资源的前提下，观察Agent在遇到权限边界时的完整行为链。它规划了什么、记忆了什么、调用了什么、被拒绝后做了什么，每一步都有日志可查。下面几个章节我会把规划、记忆、工具边界这三个模块在只读试点中的表现逐一拆开讲。

2. 规划模块在只读约束下的行为拆解

2.1 规划器的基本工作方式与只读适配

规划模块是整个Agent的“大脑”，它负责把用户输入的目标拆解成一系列可执行的步骤。在常规场景下，规划器会同时考虑读操作和写操作，比如“检查服务状态”后面可能跟着“重启异常服务”。但在只读试点里，规划器必须学会一件事：只生成读取类步骤，遇到需要写操作才能完成的目标时，要么降级为只读检查，要么明确报告“当前权限不足以完成该目标”。

我用的规划器是基于任务分解树的，根节点是用户目标，子节点是具体步骤，每个步骤带一个操作类型标签。在只读试点中，我给操作类型加了一个约束：只有标签为“read”的步骤才能进入执行队列，标签为“write”的步骤会被标记为“待授权”并挂起。这个约束不是写在规划器内部的，而是写在规划器和执行器之间的一个过滤器里。这样做的好处是，规划器仍然可以自由地生成完整步骤链，但执行器只会执行只读部分，写操作部分会被拦截并记录。

实测下来，这个设计暴露了一个很有意思的现象：规划器在生成步骤时，会倾向于把“检查”和“修复”捆绑在一起。比如用户说“看看磁盘是不是满了”，规划器生成的步骤链是“读取磁盘使用率 -> 如果超过阈值则清理临时文件”。在只读约束下，第二步被拦截了，但第一步正常执行。Agent拿到磁盘使用率后，会在最终输出里附上一句“检测到使用率超过阈值，但当前为只读模式，无法执行清理操作”。这个行为是符合预期的，也是只读试点想要达到的效果。

2.2 只读约束下规划器的降级策略

降级策略是只读试点里最值得关注的部分。当规划器发现某个步骤需要写权限但当前不可用时，它有三种选择：一是直接跳过该步骤，继续执行后续只读步骤；二是把该步骤替换为一个只读的替代方案；三是终止整个任务并报告权限不足。这三种策略没有绝对的好坏，取决于具体场景。

我在这轮试点里给规划器配置的默认策略是“优先替代，其次跳过，最后终止”。举个例子，用户目标是“确认数据库连接是否正常”。常规规划会生成“测试连接 -> 如果失败则重启连接池”。在只读模式下，重启连接池被拦截，规划器会自动把第二步替换为“读取连接池状态和最近错误日志”。这样既完成了诊断目标，又没有触发任何写操作。

替代策略的实现依赖于一个“只读替代方案库”。这个库里预定义了一些常见写操作的只读替代方案，比如“重启服务”对应“读取服务状态和最近重启记录”，“清理日志”对应“读取日志大小和最早记录时间”，“修改配置”对应“读取当前配置和变更历史”。规划器在遇到被拦截的写操作时，会先查这个库，如果有替代方案就自动替换，没有就跳过或终止。

注意：替代方案库需要人工维护，不能指望规划器自己发明替代方案。我试过让规划器自由发挥，结果它把“删除临时文件”替代成了“列出临时文件内容”，虽然也是只读操作，但完全偏离了用户意图。所以这个库必须由开发者根据实际场景预先定义好。

2.3 规划粒度的控制与实操建议

规划粒度是另一个在只读试点中暴露出来的关键问题。粒度太粗，一个步骤里可能混着读和写，过滤器很难精确拦截；粒度太细，步骤数量爆炸，执行效率直线下降。我试过三种粒度：粗粒度（按目标分）、中粒度（按操作类型分）、细粒度（按具体命令分）。

粗粒度的问题是，一个步骤里可能同时包含读取和写入，比如“检查并修复配置”。过滤器只能整个步骤拦截，导致只读部分也被跳过了。细粒度的问题是，一个简单的“查看日志”被拆成了“打开文件 -> 读取前100行 -> 关闭文件”三个步骤，执行开销太大。最后我选的是中粒度：每个步骤只包含一种操作类型，要么纯读要么纯写，步骤内部不再拆分。这样过滤器可以精确拦截写操作，同时步骤数量控制在合理范围内。

实操建议是，在定义步骤时给每个步骤加一个明确的“操作类型”字段，不要依赖规划器自己判断。我一开始让规划器自己标注操作类型，结果它把“读取配置并缓存”标成了只读，但“缓存”这个动作实际上写入了本地存储。后来我改成在步骤模板里硬编码操作类型，规划器只能选择模板，不能自定义类型，问题就解决了。

2.4 规划模块的日志与可观测性设计

只读试点的一个核心产出是规划模块的完整日志。我需要知道Agent在每一步规划时看到了什么、想了什么、决定了什么。日志里我记录了四类信息：输入目标、生成的步骤链、每个步骤的操作类型、被拦截的步骤及拦截原因。

这些日志后来成了排查问题的关键依据。有一次Agent在只读模式下反复尝试执行一个被拦截的写操作，日志显示它在规划阶段生成了“读取状态 -> 重启服务 -> 再次读取状态”的步骤链，重启被拦截后，它没有走替代方案，而是重新规划了一遍，又生成了同样的步骤链。这说明替代方案库没有覆盖这个场景，规划器在找不到替代方案时陷入了循环。后来我在规划器里加了一个“最大重规划次数”限制，超过三次就终止并报告，避免了无限循环。

可观测性设计上，我建议至少记录三个维度的数据：规划耗时、步骤数量、拦截率。规划耗时突然变长通常意味着规划器在反复尝试；步骤数量异常增多可能是粒度失控；拦截率过高说明只读约束太严或者替代方案库覆盖不足。这三个指标在试点期间帮我定位了好几个隐藏问题。

3. 记忆模块在只读场景中的关键作用

3.1 记忆模块的读写分离设计

记忆模块在只读试点里扮演了一个容易被忽视但极其重要的角色。常规Agent的记忆模块通常只区分“短期记忆”和“长期记忆”，但在只读场景下，我加了一个新的维度：操作类型记忆。也就是说，记忆库里不仅存“发生了什么”，还存“这个操作是读还是写”。

这个设计的目的是防止一种危险情况：Agent把上一次写操作的上下文错误地应用到当前只读场景中。举个例子，上一次Agent在完整权限下执行了“清理日志”操作，记忆里存了“日志目录已清理，当前为空”。这一次在只读模式下，Agent读取记忆后可能会认为日志目录是空的，从而跳过日志检查步骤。但实际上只读模式下并没有执行清理，日志目录里还有内容。这种记忆污染在只读试点中必须避免。

我的做法是在记忆条目里加一个“权限上下文”字段，记录该条目是在什么权限模式下产生的。只读模式下，Agent只能读取“只读上下文”的记忆条目，写操作产生的记忆条目会被标记为“不可用于只读推理”。这样虽然牺牲了一些记忆复用率，但避免了错误推理。

3.2 只读记忆的存储结构与检索策略

只读记忆的存储结构我设计得比较简单，每条记忆包含六个字段：时间戳、操作类型、目标对象、操作结果、权限上下文、关联任务ID。检索时，Agent会根据当前任务ID和权限上下文做过滤，只取出匹配的条目。

检索策略上我试过两种：一种是按时间倒序取最近N条，一种是按相关性评分取TopN。在只读试点里，按时间倒序的效果反而更好，因为只读操作通常是对当前状态的快照，最近一次读取的结果最能反映现状。相关性评分在写操作场景下更有用，因为写操作之间可能存在复杂的依赖关系，但在只读场景下，依赖关系简单得多。

实操心得：只读记忆的过期时间可以设得比写操作记忆短一些。我设的是只读记忆保留24小时，写操作记忆保留7天。因为只读操作的结果时效性很强，超过24小时的磁盘使用率数据基本没有参考价值，而写操作的历史记录可能需要保留更久用于审计。

3.3 记忆污染与错误传播的防范

记忆污染是只读试点中最隐蔽的风险。它不会导致直接报错，但会让Agent做出看似合理实则错误的决策。我遇到过三次典型的记忆污染场景。

第一次是“状态覆盖”。Agent在只读模式下读取了服务A的状态，记忆里存了“服务A运行中”。然后用户手动重启了服务A，但Agent的记忆没有更新。下一次Agent读取记忆时，仍然认为服务A在运行，但实际上它可能已经挂了。防范方法是给只读记忆加一个“可信度衰减”机制，超过一定时间的只读记忆会被标记为“可能过期”，Agent在使用时会附带一个“该信息可能已过期，建议重新读取”的提示。

第二次是“上下文串扰”。Agent在处理任务B时，错误地引用了任务A的只读记忆。原因是两个任务的检索关键词有重叠。防范方法是给每个任务分配独立的记忆命名空间，检索时严格限定在当前任务的命名空间内。

第三次是“否定记忆丢失”。Agent读取某个文件时发现文件不存在，记忆里存了“文件不存在”。但后来文件被创建了，Agent的记忆没有更新，仍然认为文件不存在。防范方法是对于“不存在”“为空”“未配置”这类否定性结论，设置更短的过期时间，或者强制在每次使用前重新验证。

3.4 记忆模块与规划模块的联动机制

记忆模块和规划模块的联动是只读试点中我花时间最多的地方。规划器在生成步骤时，需要查询记忆库来判断哪些步骤已经执行过、哪些结果可以复用。但在只读模式下，这个联动必须非常小心，因为记忆里的写操作记录不能用来指导只读规划。

我的做法是在规划器和记忆库之间加了一个“记忆适配层”。规划器不直接查记忆库，而是通过适配层查询。适配层会根据当前权限模式过滤记忆条目，只返回与当前模式匹配的记录。同时，适配层还会对返回的记忆做一次“只读化”处理，把写操作相关的字段剥离掉，只保留只读部分。

这个适配层还负责一件事：当规划器生成的步骤与记忆中的只读记录重复时，适配层会提示规划器“该步骤最近已执行，结果可复用”。规划器可以选择复用结果，也可以选择重新执行。在只读试点里，我默认让规划器复用结果，以减少不必要的读取操作。但复用有一个前提：记忆条目没有过期。适配层会检查时间戳，超过过期时间的记忆不会被复用。

4. 工具边界的定义与权限控制

4.1 工具网关的白名单机制

工具边界是只读试点的最后一道防线，也是最关键的一道。我用的方案是工具网关加白名单。所有工具调用都必须经过网关，网关维护一张权限表，表里列出了当前模式下允许调用的工具和参数范围。只读模式下，只有读取类工具在白名单里，写操作工具即使被调用也会被网关直接拒绝。

白名单的粒度我控制到了“工具+参数”级别。比如“读取文件”这个工具是允许的，但参数里的文件路径必须匹配预设的安全路径模式，不能读取任意路径。“查询日志”是允许的，但查询时间范围不能超过最近7天，防止Agent拉取海量日志导致性能问题。这种细粒度控制虽然配置起来麻烦，但能有效防止Agent在只读模式下做出“擦边”行为。

网关的拒绝响应也很重要。我一开始只返回一个简单的403错误，结果Agent收到403后不知道该怎么办，有时候会反复重试同一个被拒绝的调用。后来我改成返回结构化的拒绝信息，包含拒绝原因、建议的替代工具、以及当前模式下允许的操作列表。Agent收到这个信息后，就能自动切换到替代方案，而不是傻傻地重试。

4.2 只读工具的分类与能力边界

只读工具我分成了四类。第一类是状态查询类，比如查询服务状态、查询磁盘使用率、查询内存占用。这类工具返回的是当前快照，时效性很强。第二类是日志读取类，比如读取应用日志、读取系统日志、读取审计日志。这类工具返回的是历史记录，需要注意时间范围。第三类是配置读取类，比如读取应用配置、读取环境变量、读取启动参数。这类工具返回的是静态信息，变化频率低。第四类是元数据查询类，比如查询文件属性、查询目录结构、查询进程列表。这类工具返回的是结构化信息，适合做进一步分析。

每类工具的能力边界不同，在只读试点中的表现也不同。状态查询类工具最容易被滥用，因为Agent会频繁调用它来“确认状态”，导致大量重复查询。我后来加了一个缓存层，同一个状态在30秒内只查询一次，后续调用直接返回缓存结果。日志读取类工具的风险在于数据量，Agent可能会拉取大量日志导致内存溢出。我加了分页限制，每次最多返回1000行，并且强制要求指定时间范围。配置读取类工具相对安全，但要注意敏感信息脱敏，比如密码字段必须被过滤掉。元数据查询类工具的风险最低，但也要防止Agent通过目录遍历获取不该看的信息。

4.3 权限拒绝后的降级与重试策略

权限拒绝后的处理策略直接决定了Agent在只读模式下的用户体验。我试过三种策略：直接失败、自动降级、人工确认。直接失败最简单，但用户体验差，Agent遇到拒绝就终止任务。自动降级体验好，但需要替代方案库覆盖足够全。人工确认最安全，但在自动化场景下不实用。

最后我采用的是“自动降级为主，人工确认为辅”的混合策略。对于常见的写操作，比如重启服务、清理文件、修改配置，自动降级到对应的只读替代方案。对于不常见的写操作，或者替代方案库没有覆盖的操作，Agent会暂停任务并生成一个“待确认”事件，等待人工介入。人工可以选择“跳过该步骤”“提供替代方案”或“终止任务”。

重试策略上，我设置了一个简单的规则：同一个被拒绝的调用最多重试两次，两次都失败就放弃并记录。重试间隔是递增的，第一次立即重试，第二次等5秒。这个规则避免了Agent在权限拒绝上浪费太多时间。实测下来，大部分权限拒绝在第一次重试后就会走降级路径，只有少数边缘场景会触发第二次重试。

4.4 工具调用日志与审计追踪

工具调用日志是只读试点的“黑匣子”。我记录了每次调用的完整信息：调用时间、调用工具、调用参数、返回结果摘要、是否被拒绝、拒绝原因、后续动作。这些日志不仅用于排查问题，还用于审计Agent的行为是否符合只读约束。

日志分析帮我发现了一个有趣的现象：Agent在只读模式下会“试探”边界。它有时候会故意调用一个写操作工具，看看会不会被拒绝。如果被拒绝，它就知道了边界在哪里；如果没有被拒绝（说明白名单配置有漏洞），它就会继续执行。这个行为说明Agent的规划器在探索环境，虽然最终没有造成破坏，但提醒我必须定期审查白名单，确保没有遗漏。

审计追踪上，我建议至少保留30天的工具调用日志。对于被拒绝的调用，保留时间可以更长，因为这些记录反映了Agent的边界探索行为，对后续优化规划器和替代方案库很有价值。日志存储我用的是一种简单的追加写入方式，每条日志一行JSON，方便后续用脚本分析。

5. 只读试点的完整实操流程

5.1 环境准备与隔离措施

实操的第一步是准备一个完全隔离的环境。我用的是一台独立的虚拟机，里面跑着几个模拟服务，这些服务只产生日志和状态数据，不连接任何真实业务。虚拟机的网络是隔离的，只能被Agent所在的容器访问，不能访问外部网络。这样即使Agent出了什么问题，影响范围也仅限于这台虚拟机。

隔离措施还包括文件系统隔离。Agent只能访问一个特定的工作目录，这个目录里放着模拟的配置文件和日志文件。工作目录之外的路径，Agent即使尝试读取也会被网关拒绝。我试过用容器挂载的方式实现文件系统隔离，把工作目录挂载到容器里，其他路径不挂载。这样Agent在容器内看到的文件系统就是受限的，不需要额外配置路径白名单。

环境准备阶段还要做一件事：预置模拟数据。我在模拟服务里预置了7天的日志、几份配置文件、以及一些状态快照。这些数据要足够真实，能让Agent的规划器产生有意义的步骤链，但又不能太复杂，否则排查问题时会很困难。我建议模拟数据的规模控制在“一个中等复杂度的微服务”水平，大概三到五个服务，每个服务有基本的日志和配置。

5.2 只读工具集的配置与验证

工具集的配置是实操的核心环节。我先把所有只读工具注册到工具网关，然后在白名单里逐个启用。每个工具启用后，我都会手动调用一次，验证它返回的数据格式和内容是否符合预期。这个验证步骤不能省，因为工具返回格式不一致会导致Agent解析失败，进而影响规划器的决策。

验证时我重点关注三个点：返回数据的结构是否稳定、返回数据的大小是否可控、返回数据里是否包含敏感信息。结构不稳定会导致Agent解析出错，我遇到过某个工具在数据为空时返回null，在数据非空时返回数组，Agent的解析器没有处理null的情况，直接报错了。数据大小不可控会导致内存问题，我遇到过日志查询工具在没有限制时返回了十几万行数据，直接把Agent的内存撑爆了。敏感信息泄露是安全问题，配置读取工具返回的配置里包含了数据库密码，虽然是在隔离环境里，但养成脱敏习惯很重要。

工具集配置完成后，我跑了一轮“空转测试”：让Agent执行一个简单的只读任务，比如“检查所有服务的状态”，观察它调用了哪些工具、返回了什么结果、最终输出是什么。空转测试的目的是验证工具链的连通性，确保没有配置错误。我在这轮测试里发现了一个网关配置问题：某个工具的路径白名单写错了，导致Agent调用时被误拒绝。修正后重新测试，工具链就通了。

5.3 试点任务的选取与执行记录

试点任务我选了五个，覆盖不同的复杂度。第一个是“检查所有服务的运行状态”，这是最简单的只读任务，主要验证状态查询类工具。第二个是“分析最近24小时的错误日志”，验证日志读取类工具和Agent的日志分析能力。第三个是“对比当前配置与基线配置的差异”，验证配置读取类工具和Agent的对比分析能力。第四个是“检查磁盘使用率并识别异常增长”，验证元数据查询类工具和Agent的趋势分析能力。第五个是“综合诊断：服务状态+日志+配置+磁盘”，这是最复杂的任务，验证Agent在多工具协作下的规划能力。

每个任务我都记录了完整的执行日志，包括规划步骤、工具调用、记忆读写、最终输出。执行记录里我特别关注三个指标：任务完成率、工具调用次数、权限拒绝次数。任务完成率反映Agent能不能在只读约束下达成目标；工具调用次数反映Agent的规划效率；权限拒绝次数反映Agent的边界探索行为。

五个任务跑下来，完成率是100%，但工具调用次数差异很大。最简单的状态检查任务调用了3次工具，最复杂的综合诊断任务调用了23次工具。权限拒绝次数总共出现了7次，其中5次是Agent尝试调用写操作工具被拒绝，2次是调用只读工具但参数超出白名单范围被拒绝。这些拒绝记录后来成了优化替代方案库的重要依据。

5.4 试点结果的分析与迭代方向

试点结果分析我分成了三个维度：规划质量、记忆准确性、工具边界合理性。规划质量上，Agent在简单任务上的规划很直接，步骤链清晰；在复杂任务上，规划器有时会生成冗余步骤，比如重复读取同一个状态。记忆准确性上，只读记忆的复用率大约在40%左右，大部分复用发生在同一个任务内的连续步骤之间，跨任务的复用很少。工具边界上，白名单机制有效拦截了所有写操作尝试，没有出现漏网之鱼。

迭代方向我定了三个。第一，优化规划器的冗余步骤检测，在生成步骤链后做一次去重，把重复的只读步骤合并。第二，扩展替代方案库，把试点中出现的7次权限拒绝场景都补上替代方案，减少人工确认的次数。第三，调整记忆过期策略，把状态查询类记忆的过期时间从24小时缩短到1小时，因为状态变化频率比预期高。

这轮只读试点最大的收获不是技术上的，而是认知上的。我以前总觉得Agent的能力越强越好，工具越多越好，权限越大越好。但试点跑下来发现，受限环境反而让Agent的行为更可预测、更可控。只读约束不是限制Agent的能力，而是帮它划清边界，让它在边界内把该做的事做好。这个思路后来被我应用到了其他Agent项目里，效果都很好。

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

6.1 规划器反复生成被拒绝的步骤

这是只读试点中最常见的问题。Agent的规划器在生成步骤链时，没有考虑当前权限模式，生成了包含写操作的步骤。执行器拦截后，规划器重新规划，又生成了同样的步骤链，陷入循环。

排查思路是看规划日志里的“重规划次数”。如果同一个任务的重规划次数超过3次，基本可以确定是替代方案库覆盖不足。解决方法是找到被拒绝的写操作类型，在替代方案库里补上对应的只读替代方案。如果替代方案确实不存在，就在规划器里加一个“该操作在当前模式下不可用”的标记，让规划器直接跳过，不再重试。

避坑技巧：替代方案库的键值对要写得足够具体。我一开始用“重启服务”作为键，结果Agent遇到“重启数据库服务”和“重启缓存服务”时都匹配到了同一个替代方案，但这两个场景的只读替代方案其实不一样。后来我把键改成了“重启服务:数据库”和“重启服务:缓存”，匹配就准确了。

6.2 记忆条目在只读模式下被错误复用

记忆错误复用通常表现为Agent跳过了某个只读步骤，因为它认为“上次已经读过了”。但上次读取的结果可能已经过期，或者上次是在不同权限模式下读取的。

排查方法是检查记忆条目的“权限上下文”字段。如果Agent在只读模式下复用了写操作产生的记忆条目，说明记忆适配层的过滤逻辑有问题。解决方法是加强适配层的过滤规则，确保只读模式只能读取只读上下文的记忆。同时检查记忆的过期时间，对于状态类记忆，过期时间要设得短一些。

我遇到过一次比较隐蔽的错误复用：Agent在任务A中读取了服务状态，记忆里存了“服务正常”。任务B中Agent直接复用了这个记忆，没有重新读取。但任务A和任务B之间隔了6个小时，服务状态可能已经变了。后来我给记忆加了一个“最大复用间隔”限制，超过这个间隔的记忆必须重新验证。

6.3 工具网关误拦截正常只读调用

网关误拦截通常是因为白名单配置太严格或者路径匹配规则写错了。我遇到过两次：一次是文件路径白名单用了绝对路径，但Agent传入的是相对路径，导致匹配失败；另一次是日志查询的时间范围白名单设成了“最近1小时”，但Agent查询的是“最近2小时”，被拒绝了。

排查方法是看网关的拒绝日志，里面会记录被拒绝的调用参数和匹配失败的原因。解决方法是调整白名单规则，把路径匹配改成前缀匹配而不是完全匹配，把时间范围限制放宽到合理值。同时，网关的拒绝响应里要包含“当前允许的参数范围”，这样Agent收到拒绝后可以自动调整参数重试。

实操心得：白名单规则建议用配置文件管理，不要硬编码在代码里。我一开始把规则写在代码里，每次调整都要重新部署。后来改成YAML配置文件，改完重启网关就行，效率高很多。配置文件里还可以加注释，说明每条规则的用途和调整原因。

6.4 Agent在只读模式下输出不完整

输出不完整通常是因为Agent在规划阶段跳过了某些步骤，或者在执行阶段遇到了权限拒绝但没有走降级路径。表现是最终输出里缺少某些检查项的结果，或者只有部分服务的状态。

排查方法是对比规划步骤链和实际执行步骤链，找出被跳过的步骤。如果跳过是因为权限拒绝，检查替代方案库是否有对应方案。如果跳过是因为规划器主动省略，检查规划器的步骤生成逻辑，看是不是有“如果上一步成功则跳过下一步”之类的条件判断导致了遗漏。

我遇到过一次输出不完整的情况：Agent在检查服务状态时，有一个服务返回了超时错误，Agent把这个服务标记为“未知”后继续执行后续步骤，但最终输出里没有包含这个“未知”状态。原因是输出格式化模块只处理了“正常”和“异常”两种状态，没有处理“未知”。后来我在输出模块里加了“未知”状态的处理逻辑，问题就解决了。

6.5 常见问题速查表

6.6 试点后的经验沉淀与推广建议

只读试点跑完一轮后，我沉淀了三份文档：一份是工具白名单配置指南，一份是替代方案库维护手册，一份是记忆管理规范。这三份文档后来成了团队里其他Agent项目的标准参考。

推广建议上，我建议任何Agent项目在上线前都先跑一轮只读试点。试点的成本很低，一台隔离虚拟机加几个模拟服务就够了，但收益很大。它能在不碰真实资源的前提下，把规划、记忆、工具边界这三个核心模块的行为摸清楚，提前发现潜在问题。我后来在三个不同的Agent项目里都用了这个方法，每次都能发现一些在开发阶段没注意到的问题。

只读试点还有一个隐性收益：它帮团队建立了一种“边界优先”的设计思维。以前大家做Agent，第一反应是“它能做什么”，现在第一反应是“它不能做什么”。这个思维转变比任何技术方案都重要。