PentestGPT V2工具层设计解析：从抽象基类到subagent即工具

PentestGPT 这个项目在 AI 辅助渗透测试这个细分赛道上算是绕不开的一个参考系。V1 版本刚出来的时候很多人包括我第一反应是“这不就是个套了 GPT 外壳的自动化脚本集合吗”但实际把源码翻下来你会发现它在任务编排和上下文管理上做了不少扎实的设计。而到了 V2架构层面有一个很明显的转向工具层不再是简单的函数注册表而是被抽象成了一等公民整个系统的能力边界几乎都是靠工具层来定义的。最近我在重新梳理 V2 的源码正好也看到社区里有人在讨论多 agent 设计里的主从模式以及“把 subagent 当作另一种 tool 来调用”的观点。这个思路其实和 PentestGPT V2 工具层的设计哲学高度吻合。这篇文章我就结合源码阅读的笔记重点聊聊 V2 工具层的设计模式包括它怎么抽象工具、怎么管理上下文、怎么处理权限边界以及我们在自己的项目里可以怎么借鉴这套设计。1. 工具层在 PentestGPT V2 中的定位与整体设计思路1.1 为什么 V2 要把工具层单独拎出来设计先说结论V1 的问题不在于功能不够而在于所有操作几乎都揉在推理循环里。V1 的架构里GPT 生成一段文本代码里去解析这段文本里的命令关键字然后匹配到对应的 Python 函数去执行。这种方式在 demo 场景下没问题但一旦工具数量增加解析逻辑会变得极其脆弱而且每加一个新工具都要改动核心循环代码耦合度非常高。V2 的源码里工具层被设计成了一个独立的模块所有工具都通过统一的接口暴露给上层 agent。核心目录结构大概是这样的pentestgpt/ ├── tools/ │ ├── __init__.py │ ├── base.py │ ├── registry.py │ ├── permission.py │ ├── tool_io.py │ ├── web/ │ ├── code/ │ └── pentest/这个结构一眼就能看出设计意图base.py 定义抽象基类registry.py 负责工具注册与发现permission.py 处理权限控制tool_io.py 统一输入输出格式。真正具体的工具实现Web 扫描、代码分析、渗透测试辅助等被放在子目录里互相独立。这种分层带来的直接好处是工具与推理逻辑解耦。GPT 模型只需要知道“有哪些工具可用、每个工具接受什么参数、返回什么格式”完全不需要关心工具内部是怎么实现的。这其实是在模仿 OpenAI function calling 的设计模型负责决策工具层负责执行中间通过一个结构化的协议来通信。1.2 工具层要解决的四个核心问题通读 V2 源码之后我梳理出工具层设计时需要面对的四个核心问题这四个问题基本决定了工具层的整体架构第一个是工具发现。agent 怎么知道当前有哪些工具可用V2 的做法是注册表模式所有工具在初始化时注册到全局 registry 中agent 启动时拉取一次工具清单动态构建 prompts。第二个是工具调用协议。模型输出的内容怎么映射到具体的工具调用V2 没有采用自然语言解析而是采用了结构化的 JSON 输出格式模型输出一个工具调用请求包含工具名和参数列表然后由 dispatcher 去分发。这个设计大幅提升了调用准确率。第三个是安全边界。工具层执行的操作往往是敏感的文件读写、命令执行、网络请求如果完全不设防agent 一旦被提示词注入攻击后果不堪设想。V2 里专门设计了权限模块每个工具都可以声明自己的权限等级执行前会经过 permission manager 的校验。第四个是执行反馈。工具执行完之后的结果要能回到模型上下文里而且是能被模型理解的格式。V2 统一用 ToolOutput 数据结构封装无论底层是执行了一个 shell 命令还是调了一个 API返回给上层都是格式化的文本和元数据。这四个问题环环相扣前面的设计决策会影响后面的实现。V2 的处理方式虽然不是唯一解但在工程上确实比较优雅值得拿出来单独拆解。2. 工具抽象与注册机制的核心实现2.1 基于 ABC 的抽象基类设计V2 的工具层在 base.py 里定义了一个抽象基类所有具体工具都继承自这个基类。核心定义大概是这个思路from abc import ABC, abstractmethod from typing import Any, Dict, Optional class BaseTool(ABC): 所有工具类的抽象基类 # 工具的唯一标识用于 registry 注册和 agent 调用 name: str # 工具的功能描述会被注入到 system prompt 中 description: str # 参数定义遵循 JSON Schema 格式便于模型理解 parameters: Dict[str, Any] {} # 权限等级决定是否需要用户确认 permission_level: str normal # normal, elevated, dangerous abstractmethod def execute(self, **kwargs) - ToolOutput: 执行工具的核心逻辑 pass def validate_parameters(self, **kwargs) - bool: 参数校验基类提供默认实现子类可覆盖 return True def to_function_schema(self) - Dict[str, Any]: 转成 function calling 所需的 schema 格式 return { type: function, function: { name: self.name, description: self.description, parameters: self.parameters, }, }这个设计有几个细节很值得注意。首先是name和description作为类属性而不是实例属性这是一个刻意的选择。因为工具是全局共享的不需要为每个实例单独维护一套元数据。类属性天然适合这种场景而且可以通过cls.name直接访问不用实例化。其次是parameters字段遵循 JSON Schema 格式。这不是拍脑袋定的而是为了方便对接 LLM 的 function calling 接口。V2 同时支持 OpenAI 格式和 Anthropic 格式的工具描述底层都是通过to_function_schema()这个方法来做适配的。这个设计保证了未来换模型厂商时工具层代码基本不用动。还有一个容易被忽略的细节execute方法接收的是**kwargs而不是固定参数。这意味着不同工具的参数数量、名称可以完全不一样由各工具内部的validate_parameters来检查。这是一个典型的策略模式变体每个工具自己负责参数校验逻辑基类只管调用约定。2.2 注册表工具发现的统一入口registry.py 的实现是 V2 工具层里最值得反复看的部分。它本质上是一个全局的工具管理器维护着一个工具名到工具实例的映射关系。核心实现逻辑大概是from typing import Dict, Type, Optional class ToolRegistry: 全局工具注册表 def __init__(self): self._tools: Dict[str, BaseTool] {} def register(self, tool_cls: Type[BaseTool]) - Type[BaseTool]: 注册工具类装饰器风格 instance tool_cls() self._tools[instance.name] instance return tool_cls def unregister(self, tool_name: str) - None: 注销工具 self._tools.pop(tool_name, None) def get_tool(self, tool_name: str) - Optional[BaseTool]: 根据名称获取工具实例 return self._tools.get(tool_name) def list_tools(self) - list: 列出所有已注册工具 return list(self._tools.values()) def get_function_schemas(self) - list: 获取所有工具的 function schema用于注入 prompt return [tool.to_function_schema() for tool in self._tools.values()] # 全局唯一的注册表实例 tool_registry ToolRegistry() def register_tool(cls): 模块级别的便利装饰器 tool_registry.register(cls) return cls模块级别的tool_registry单例和register_tool装饰器配合使用时添加新工具只需要两件事新建一个继承 BaseTool 的类然后加上register_tool装饰器。比如register_tool class NmapScanner(BaseTool): name nmap_scanner description 使用 Nmap 对目标主机进行端口扫描 parameters { type: object, properties: { target: {type: string, description: 目标 IP 或域名}, ports: {type: string, description: 端口范围如 1-1000}, }, required: [target], } def execute(self, **kwargs): target kwargs.get(target) ports kwargs.get(ports, 1-1000) # 实际执行 nmap 命令... result ... return ToolOutput(outputresult)这种注册机制的优雅之处在于新增一个工具不需要改动任何已有的核心代码。你想加一个新工具就新建一个文件定义一个类加上装饰器完事。这完全符合开闭原则——对扩展开放对修改关闭。不过这个设计也有一个需要特别注意的点因为是模块级别的全局单例如果多个测试用例并行运行工具注册表会共享状态。V2 源码里针对这个问题做了处理提供了reset()方法在测试环境的 setup 和 teardown 中调用。2.3 工具加载静态注册还是动态发现V2 的工具加载方式默认是静态导入也就是所有工具模块在系统初始化时被 import然后各自的register_tool装饰器就会执行完成注册。这种方式简单可靠但对于超大型项目可能会导致启动速度变慢。V2 也提供了一种折中方案按需加载。核心思路是把工具模块名配置在外部文件里启动时根据配置动态 importimport importlib def load_tools_from_config(config_list: list): 根据配置动态加载工具模块 for module_path in config_list: module importlib.import_module(module_path) # import 模块后模块内的 register_tool 装饰器会自动执行这种动态导入的方式灵活性更高但也有问题如果模块里有 import 错误错误信息会比较隐蔽不好排查。而且 IDE 的静态分析对动态导入基本无能为力代码跳转、类型检查都会失效。V2 默认还是采用静态导入只有在自己扩展工具时才建议用动态加载。我自己的经验是对于工具数量在 20 以内的项目静态导入完全够用别为了“优雅”引入不必要的复杂度。工具数量超过这个量级再考虑拆分插件系统。3. 权限控制与安全边界的工程实践3.1 分级权限模型的设计思路安全这块是 PentestGPT 作为渗透测试工具必须认真对待的部分。V2 的权限模型参考了安卓的权限机制将工具执行操作划分为三个等级权限等级说明典型操作处理方式normal低风险几乎无副作用查询信息、格式转换、调用公开 API自动执行无需用户确认elevated中风险可能有副作用文件写入、发送请求、修改配置执行前向用户确认dangerous高风险可能造成破坏执行系统命令、删除文件、修改目标系统必须用户显式授权且记录完整审计日志这个分级不是拍脑袋定的而是跟模型上下文管理紧密结合。V2 在构造 system prompt 时会明确告诉模型哪些工具是 automatically approved 的哪些工具执行前会询问用户。模型的决策行为会随之调整——它知道某个操作会触发确认流程就不会轻易在非必要场景下调用这个工具。权限校验的核心代码在 permission.py 里逻辑大概是这样class PermissionManager: def __init__(self): self._confirm_callbacks [] self._audit_log [] def check_permission(self, tool: BaseTool, args: dict) - PermissionDecision: level tool.permission_level if level normal: return PermissionDecision(allowTrue, need_confirmFalse) if level elevated: # 弹窗确认逻辑由上层 UI 实现 confirmed self._request_user_confirmation(tool.name, args) self._log_decision(tool.name, args, confirmed) return PermissionDecision(allowconfirmed, need_confirmTrue) if level dangerous: # 强制要求确认并且记录完整上下文 confirmed self._request_user_confirmation( tool.name, args, require_strong_confirmTrue ) self._log_decision(tool.name, args, confirmed, leveldangerous) return PermissionDecision(allowconfirmed, need_confirmTrue) def _log_decision(self, tool_name, args, decision, levelnormal): self._audit_log.append({ timestamp: time.time(), tool: tool_name, args: args, decision: decision, level: level, })注意这里有个细节PermissionManager本身不直接弹窗而是通过回调函数_request_user_confirmation请求上层界面进行确认。这个设计保证了核心逻辑的跨平台复用——命令行版可以用 input() 确认Web 版可以用对话框确认GUI 版可以用弹窗确认互不干扰。3.2 上下文管理工具执行结果的封装与裁剪工具层设计里最容易被忽略但实际最影响效果的是工具执行完之后的输出怎么回到模型上下文。V2 里的ToolOutput类就是干这个的。class ToolOutput: def __init__( self, output: str, error: Optional[str] None, metadata: Optional[Dict] None ): self.output output self.error error self.metadata metadata or {} def to_context_string(self, max_length: int 3000) - str: 将结果转为注入上下文的字符串超长自动裁剪 if self.error: return f[工具执行失败] {self.error} content self.output if len(content) max_length: content content[:max_length] ...[输出已被截断] return content这个to_context_string是上下文管理的关键。做过 LLM 应用的人都知道一次工具调用的输出如果完全塞进上下文几千甚至上万 token 很快就烧没了。V2 的做法是默认限制每次工具输出最多 3000 字符超出部分截断。但截断是有代价的如果工具返回的关键信息正好在截断部分里模型就看不到。V2 针对这个问题做了一些补充设计比如对于结构化输出在 metadata 里保留了完整结果的文件路径模型需要时可以请求查看完整文件。这个思路挺聪明的——把上下文窗口当成“摘要层”完整数据放在“存储层”必要时再按需加载。从使用者的角度我建议在扩展自定义工具时都要实现to_context_string的个性化逻辑。默认截断方式对日志类输出够用但如果你的工具返回的是 JSON 数据更好的做法是在输出前先做 JSON 压缩把无关字段剔除而不是简单截断。3.3 Prompt 层面的工具描述优化工具层的设计不只影响代码架构还直接影响模型的选择行为。V2 在构造 tools 描述时除了使用 function schema还会在 system prompt 中补充一段工具使用策略。这段策略的原文大概意思是优先使用最特化的工具完成目标如果一个工具返回结果不完整考虑链式调用其他工具补充信息执行危险操作前必须等待用户确认。这段描述的存在相当于对模型做了一层行为引导。没有这段引导时模型可能会拿着一个 nmap_scanner 工具去扫所有目标即使有些目标是内网地址、有些目标只需要做 HTTP 探测。加了引导之后模型会更明智地选择工具组合。如果你在自己的项目里套用这套设计我强烈建议保留“工具选择策略”这一段。它看起来像是不起眼的提示词实际对工具调用准确率的影响可能比工具本身实现还重要。4. Agent 与工具层的交互模式主从架构与“即插即用”的 subagent4.1 PentestGPT V2 的 agent 结构演变PentestGPT V2 在 agent 层的设计上有一个重要变化从一个 monolithic 的推理引擎重构为“主 agent 多个子 agent”的架构。主 agent 负责整体规划、任务拆解、搜索结果汇总子 agent 负责具体领域的深度分析比如 Web 漏洞分析、代码审计、网络枚举等。社区里有人把这种架构称为“主从模式”这个说法很准确。但我要补充一个视角在这类多 agent 系统里subagent 和 tool 之间的边界其实是模糊的。你在源码里会发现主 agent 调用 subagent 的方式和调用普通工具的方式高度一致——都是传一组参数等待返回结果然后把这个结果合并进上下文。PentestGPT V2 的工具注册表设计恰好为这种模式提供了无缝支持。你可以把任何一个 subagent 封装成一个工具注册到 registry 里主 agent 根本感知不到它在跟另一个 agent 对话。这种“将 subagent 视作另类的 tool 进行调用”的做法在多 agent 系统的工程实现里非常实用因为它让整个系统的调度模型变得异常简洁。4.2 把 subagent 封装成工具的实操模式如果要在自己的项目里实现“subagent 即 tool”的封装PentestGPT V2 的 BaseTool 接口可以直接照搬。我给出一个实战中验证过的封装模式register_tool class VulnAnalyzerAgent(BaseTool): 把漏洞分析子 agent 封装成工具 name vuln_analyzer description ( 对已发现的漏洞进行深入分析判断可利用性和危害等级。 适合在端口扫描发现开放服务后调用。 ) parameters { type: object, properties: { service: {type: string, description: 目标服务名称}, version: {type: string, description: 服务版本号}, scan_results: {type: object, description: 扫描结果摘要}, }, required: [service, scan_results], } # 标记为危险等级因为可能触发后续利用操作 permission_level elevated def execute(self, **kwargs): # 这里不是直接执行命令而是启动一个子 agent 会话 sub_agent self._create_sub_agent( system_prompt你是漏洞分析专家..., max_iterations5, ) result sub_agent.run( taskf分析服务 {kwargs[service]} 的漏洞情况, contextkwargs[scan_results], ) return ToolOutput(outputresult.summary)这个封装模式的好处非常明显第一主 agent 不需要知道 subagent 的存在。它只需要像调用 nmap_scanner 一样调用 vuln_analyzer 就行了。这样的设计让主 agent 的上下文消耗降到最低不用为每个 subagent 的任务单独配置 system prompt。第二subagent 可以有独立的上下文窗口。一个复杂的漏洞分析任务可能需要大量来回对话如果这些内容全塞在主 agent 的上下文里很快就会超出 token 限制。封装成工具后整个分析过程的信息都在子 agent 的上下文里流动主 agent 只拿到最终摘要。第三权限控制自动继承。如果某个 subagent 执行的操作有风险只要在工具类里声明permission_level dangerous整个链路就会在运行前停下来请求用户确认。我在自己的项目里用这套模式封装了三个 subagent漏洞分析 agent、代码审计 agent、报告生成 agent。整体代码量没有显著增加但主 agent 的系统提示词从原来的两千多字缩减到了八百字上下文占用大幅下降响应速度也有明显提升。4.3 主从模式下的工具调度策略在“subagent 即 tool”的架构下主 agent 的工具调度策略也值得设计。PentestGPT V2 源码里可以观察到两种典型的调度路径一种是顺序调度。主 agent 先调用信息收集工具拿到结果后再调用分析工具最后调用报告工具。每个工具的输出作为下一个工具的输入。这种模式适合线性流程实现简单可预期性强。另一种是条件调度。主 agent 根据前一步的结果决定下一步调用哪个工具。比如 nmap 扫描发现 443 端口开放则调用 Web 指纹识别工具如果发现 3306 端口开放则调用数据库枚举工具。这要求工具返回的结果足够结构化能让模型轻松判断下一步动作。V2 源码里没有强制规定必须使用哪种调度方式而是在 system prompt 中描述了一般的调度原则先全面侦察再重点突破最后总结报告。这背后的思路是LLM 本身已经具备足够的推理能力不需要用工程代码去硬编码流程只要把工具定义清楚、权限控制好模型的调度行为自然就是合理的。这种“少干预”的设计理念跟传统软件工程的想法很不一样。传统系统里流程是必须写死的因为系统没有任何“智能”。但 LLM 应用不一样——模型就是一个非常强的决策器你只要给它正确的工具和正确的目标它自己能推导出合理的路径。工程代码的重心应该放在确保工具安全可靠、输出一致、权限可控上而不是试图去控制每一步动作。5. 工具层扩展从源码阅读到自定义工具落地5.1 如何快速定位工具层源码的关键路径如果你打算自己阅读 PentestGPT V2 的源码或者在自己的项目里参考它的工具层设计我建议你按照下面的路径来阅读不要一开始就扎进细节里先从base.py开始看理解BaseTool的抽象设计重点看execute的签名、to_function_schema的返回格式。这是整个工具层的地基。然后看registry.py理解注册和发现机制重点放在get_function_schemas和register_tool装饰器上。看完这两个文件你已经掌握了工具层的骨架。接着选一个简单的工具实现来读比如tools/web/下面的某个请求工具。看它的execute方法是怎么工作的怎么解析参数怎么处理错误怎么构造ToolOutput。通过具体例子来理解抽象类比看十遍文档都有效。最后回到permission.py看权限控制怎么接入工具执行链路确认是在哪个环节进行拦截的。这是安全的最后一道防线。这样一趟读下来你基本上就掌握了工具层的全貌。剩下的细节每个具体工具的实现、上下文裁剪策略、日志记录格式可以按需深入。5.2 新增一个安全工具的完整步骤我以“新增一个 HTTP headers 分析工具”为例演示在 PentestGPT V2 框架下扩展工具的标准步骤。第一步在tools/pentest/目录下新建一个文件命名为http_header_analyzer.py。第二步定义工具类from typing import Dict from ..base import BaseTool from ..registry import register_tool from ..tool_io import ToolOutput register_tool class HttpHeaderAnalyzer(BaseTool): 分析 HTTP 响应头中的安全配置 name http_header_analyzer description ( 获取并分析目标 URL 的 HTTP 响应头 检查是否存在 X-Frame-Options、CSP 等安全头配置。 ) parameters { type: object, properties: { url: {type: string, description: 目标 URL}, timeout: {type: integer, description: 请求超时时间默认 10}, }, required: [url], } permission_level normal def validate_parameters(self, **kwargs) - bool: url kwargs.get(url, ) return url.startswith((http://, https://)) def execute(self, **kwargs): url kwargs.get(url) timeout kwargs.get(timeout, 10) try: # 使用 requests 发起请求仅获取响应头 import requests resp requests.head(url, timeouttimeout, allow_redirectsTrue) headers resp.headers # 检查关键安全头 checks { X-Frame-Options: clickjacking 防护, Content-Security-Policy: XSS 与注入防护, Strict-Transport-Security: HTTPS 强制, } missing [name for name, desc in checks.items() if name not in headers] present [name for name in checks if name in headers] output ( fURL: {url}\n f状态码: {resp.status_code}\n f已设置的安全头: {, .join(present) if present else 无}\n f缺失的安全头: {, .join(missing) if missing else 无} ) return ToolOutput(outputoutput, metadata{status_code: resp.status_code}) except Exception as e: return ToolOutput(output, errorf请求失败: {str(e)})第三步在工具层的__init__.py中导入这个新模块确保装饰器执行。第四步启动系统用tool_registry.list_tools()验证工具是否注册成功。这个流程最大的优点就是整个过程中你不需要修改任何核心框架代码。从定义到上线加一个工具通常不需要超过十分钟。5.3 工具层扩展的常见误区和瓶颈工具层设计模式看着简单实际落地时经常遇到几个坑我逐个说下。第一个误区是过度抽象。很多人看到 BaseTool 就想着把工具分成“信息收集型”、“漏洞利用型”、“报告生成型”多个子类再搞一套继承体系。这完全没必要。真的直接继承 BaseTool 就够了。工具层最重要的是统一接口不是统一分类。过度继承只会让新增工具时需要到处找该继承哪个父类反而拖慢开发速度。第二个误区是忽略输出格式的一致性。你的工具返回的ToolOutput.output应该是一段结构化、对模型友好的文本。很多工具开发者只关心执行结果不关心返回文本的格式结果模型看不懂工具输出调度效果大打折扣。好的做法是输出文本里明确标注关键信息、使用统一的命名约定、避免含糊的自然语言。上面那个 http_header_analyzer 的输出就是参考模板。第三个瓶颈是工具的并行调用。V2 源码里工具默认是串行执行的一个工具跑完才能调用下一个。但在实际渗透测试场景里端口扫描和 Web 指纹识别互不依赖完全可以并行执行。PentestGPT V2 对这个问题的处理是靠多轮对话实现的——每轮调一个工具下轮再调一个。这个方案保证兼容性但带来更多 token 消耗和更长的执行时间。如果你要做一个高并发的版本可以考虑在工具层加一个调度器检测无依赖的工具组合然后并发执行。不过这样会增加复杂度而且 LLM 的推理过程本身是串行的并发收益要在工具执行耗时足够长时才明显。6. 实操中的问题排查与性能调优经验6.1 工具调用失败的常见场景与定位方法工具层设计好了使用起来也不会一帆风顺。我整理了实际使用中最高频的几个问题按出现频率排序问题现象底层原因排查方法解决方案模型不调用某个工具工具描述不够清晰或该工具在当前上下文中不可见查看 tool_registry.list_tools() 确认工具已注册检查 system prompt 中的工具策略描述优化 description 的描述方式多举例说明该工具适合什么场景工具参数频繁报错参数 schema 定义不严格缺少枚举约束查看日志中的参数校验失败记录在参数 schema 里增加 enum、minLength 等约束validate_parameters 里做严格校验工具返回内容过长被截断3K 字符的限制对某些场景过小查看 metadata 里是否记录了完整结果文件路径调整 max_length或让工具输出更结构化的摘要工具执行非常慢底层操作涉及超时或大规模扫描查看工具执行耗时日志给工具调用加超时限制超时后返回部分结果权限确认频繁打断流程permission_level 设置偏高检查各工具的权限等级是否合理把只读操作降级为 normal写操作保留 elevated这里我特别提醒一点模型不调用工具这个问题的排查方向常常被人搞错。很多人第一反应是“工具注册有问题”但实际上大部分情况是“工具描述不够有引导性”。LLM 在决定要不要调用工具时几乎完全依赖 prompt 里的描述文字。你写“获取并分析目标 URL 的 HTTP 响应头检查安全配置”模型就知道这个是探测安全配置的。但如果你写“HTTP header checker”模型可能根本不知道这个工具在什么场景下用。描述里一定要写清楚适合在什么情况下调用这比代码逻辑本身的正确性更能影响工具效果。6.2 上下文 token 消耗的优化策略工具层对 token 的消耗主要体现在三个方面工具 schema 描述占用的系统 prompt 空间、工具执行结果占用的上下文空间、以及多轮工具调用带来的历史累积。PentestGPT V2 针对第三点的做法是引入了“工具调用历史压缩”。当工具调用次数超过阈值时系统会将之前的工具调用记录做一层 summarization只保留原始请求的参数摘要和执行结果的前几行把压缩后的内容放回上下文。这个机制实现的复杂度不低但在长会话场景下收益很大。我自己做了几个改进尝试可以分享给大家第一是按需裁剪工具 schema。不是所有工具在每轮对话中都需要暴露给模型。会话前期主要做信息收集就只暴露侦察类工具进入利用阶段再动态加载漏洞利用工具。这样能把 system prompt 的 token 占用砍掉一半以上。第二是结果缓存。同一个工具对同一个目标执行多次结果往往是一样的。比如 nmap 扫同一个 IP短时间内不会变。可以在工具层加一个简单的缓存用 target tool_name parameters_hash 作为 key命中缓存就直接返回结果省去重复执行的时间和 token 开销。第三是避免“工具链爆炸”。当模型连续调用多个工具时每个工具的中间输出都会留在上下文里。可以设计一层代码逻辑只把最终汇总结论放回上下文中间过程的详细输出写到临时文件。这个思路跟前面提到的 metadata 文件路径方案是一致的。6.3 工具层的测试与回归保障代码写多了你会发现工具层最容易出的问题不是“某个工具单独运行出错”而是“某个工具的改动影响了其他工具的注册或调用”。比如工具 A 的模块 import 出错导致整个tools包 import 失败结果所有工具都注册不了。PentestGPT V2 的源码里考虑了这点测试用例里有一个很基础的回归测试启动时检查工具注册数量确保环境初始化时没有工具丢失。我建议任何基于这个模式开发的系统都必须有这个层面的测试。更进一步的测试方案包括对每个工具单独执行一次“注册 调用”的冒烟测试确保工具能跑通输出格式符合预期对权限系统做测试确认 normal、elevated、dangerous 三个等级的拦截逻辑正确做一轮纯 mock 的调度测试模拟模型的 tool call 输出验证调度链路是否正确匹配和执行这些测试不需要覆盖每个工具的内部逻辑只需要保证工具层的骨架和接口稳定。我在实际项目中维护过二十多个工具靠这套测试方案基本能做到改动工具实现后一键跑完所有回归测试半小时内就能确认没有破坏其他功能。写在最后工具层设计里的几个理念再聊聊前阵子我一直在看多 agent 架构的各类实现有一个越来越强烈的感受最近这些主流的多 agent 编排框架里agent 和 tool 的边界正在变得越来越模糊。早期大家觉得 tool 就是一个具体的功能函数agent 才是有推理能力的执行体。但现在看subagent 本质上就是一个可以通过接口调用、有输入有输出、有着自己独立执行逻辑的功能单元——这不就是一个更复杂的 tool 吗PentestGPT V2 工具层设计的高明之处恰恰在于它提前拥抱了这个趋势。它的BaseTool抽象足够通用让“把 subagent 包装成工具”变成了一件顺理成章的事情而不是后期硬塞进去的 hack。这个设计模式不仅适用于安全领域在文档分析、数据分析、自动化运维这些需要 agent 协作的场景里都一样适用。我自己在实际操作中体会最深的一点是工具层设计的前期投入会在 agent 编排阶段几十倍地回报给你。因为只要工具的接口统一了、权限控制了、输出格式一致了上层再复杂的主从逻辑都可以用同一种方式去调用每一个能力单元。不需要为某个 subagent 单独写一套 adapter不需要担心某个工具的异常输出会污染上下文这些都是工具层已经帮你解决好的问题。最后再分享一个小技巧在给工具写 description 的时候试着站在模型的视角去审一遍。如果这段描述能让你自己判断出“这个工具在什么阶段、什么场景下该被用到”那模型大概率也能判断准。如果描述写得含糊其辞那无论底层执行逻辑多完美表现在 agent 行为上的效果都会大打折扣。工具层这件事细节全在于打磨接口和描述而不是堆叠功能。