Agent Zero 扩展机制深度指南从生命周期 Hook 到插件式扩展实战【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的扩展Extensions机制是其高级定制入口允许开发者在不修改核心源码的前提下把自定义行为精准注入到 Agent 生命周期的任意节点。本文以 docs/developer/extensions.md 为骨架结合 helpers/extension.py 的调度内核与 extensions/ 目录下数十个内置 Hook 实现系统讲解扩展点的布局规则、后端/前端两类扩展的编写契约、内置生命周期 Hook 全景以及插件如何携带扩展随装随用。先理解定位扩展 vs 插件何时该用哪一个官方文档的第一条建议非常直白如果你是新用户先使用插件Plugins而不是扩展Extensions。插件更容易创建、测试、禁用和移除而扩展属于“高级定制方式”用于改变 Agent Zero 的底层行为。从仓库结构可以印证这一分层插件是自包含的功能包例如 plugins/_memory/ 内存插件、plugins/_telegram_integration/ 电报集成插件每个插件目录内可以自带extensions/子目录见下文第五节。而 extensions/ 目录下的内置扩展则是框架自身预置的生命周期 Hook 实现。决策入口表目标起点增加一个小型面向用户的功能Create a Small Plugin为某个项目改变 Agent 行为Projects创建专门的 Agent 风格Agent Profiles研究扩展内部机制DeepWiki for Agent Zero在线文档架构细节与源码链接均迁移至此什么时候扩展才真正合适仅在普通插件、项目指令Projects、技能Skills或 Agent 配置Agent Profiles不够用的时候才考虑扩展。官方列出的合适场景包括在特定生命周期节点添加行为例如消息循环开始、工具执行前后、流式输出过程中以可复用的方式塑造提示词Prompt与核心工具紧密集成在任务开始前准备框架持有的状态。应当避免用扩展实现简单的 UI 修改、一次性脚本、或未来容易需要移除的工作——这些场景插件是更干净的家。从 extensions/AGENTS.md 的维护契约中可以看到官方对扩展的约束原则扩展目录名即运行时扩展点名带数字前缀的文件按名称顺序执行扩展必须能在生命周期点多次触发时安全重复运行涉及密钥掩码、认证、安全、持久化的扩展不允许被“便利性改动”绕过。扩展调度内核helpers/extension.py理解扩展机制的最快方式是阅读其调度核心 helpers/extension.py。整个后端扩展体系围绕两个核心概念展开显式扩展点Named Extension Points与隐式扩展点Implicit Extension Points。显式扩展点按目录名调度框架在代码中直接调用call_extensions_async或call_extensions_sync传入一个扩展点名如system_prompt、tool_execute_before调度器随即在所有扩展搜索路径中查找同名目录下的类并执行async def call_extensions_async( extension_point: str, agent: Agent|None None, **kwargs ): classes _get_extension_classes(extension_point, agentagent, **kwargs) for cls in classes: result cls(agentagent).execute(**kwargs) if isinstance(result, Awaitable): await result_get_extension_classes的实现揭示了两个重要事实搜索路径通过subagents.get_paths(agent, extensions/python, extension_point)获得意味着扩展不仅存在于仓库根部的 extensions/python 目录还存在于用户目录usr/extensions以及每个插件、每个 Agent 的extensions/目录中同名文件优先override机制当多个来源出现同名文件时“第一次出现的文件名即覆盖项”最终按文件名排序后依次执行——这就是“数字前缀控制顺序”约定的由来。所有扩展类必须继承helpers.extension.Extension基类并实现execute方法class Extension: def __init__(self, agent: Agent|None, **kwargs): self.agent agent self.kwargs kwargs abstractmethod def execute(self, **kwargs) - None | Awaitable[None]: pass同步模式下若扩展返回了可等待对象会直接抛出ValueError提示“sync 模式下返回了 awaitable”这是对同步/异步契约的强约束。隐式扩展点extensible 装饰器除显式调用外框架通过extensible装饰器为既有函数自动派生出两个扩展点无需修改函数内部的调用代码_functions/模块路径/限定名路径/start_functions/模块路径/限定名路径/end例如模块helpers.something中的函数Outer.Inner.__init__会映射为_functions/helpers/something/Outer/Inner/__init__/start _functions/helpers/something/Outer/Inner/__init__/end被装饰函数执行时装饰器构造一个可变data负载并依次传递给两个扩展点data[args]/data[kwargs]原函数参数扩展可以替换或修改data[result]初始为内部哨兵值扩展可提前赋值以短路原函数data[exception]扩展可设置为异常实例以强制抛出。执行顺序为start扩展先行可修改输入或短路→ 若 result 未被设置则调用原函数 →end扩展最后运行可改写 result 或替换/清除异常。同步函数走call_extensions_sync异步函数走call_extensions_async。仓库内置的隐式扩展实现位于 extensions/python/_functions/例如 Agent/handle_exception/end/_40_handle_intervention_exception.py 等异常处理钩子。压测用例 tests/test_extensions_stress.py 中PerfAgent.perf_hook正是用extensible包装方法并循环 10000 次做性能追踪说明该机制被设计得足够轻量以承受热路径调用。调试辅助EXTENSIONS_LOG调度器内置了一个调用计数调试开关设置环境变量EXTENSIONS_LOG为正整数后每累计到该次数就会打印各扩展点的调用次数便于定位“某扩展点是否被触发、触发频率如何”的问题EXTENSIONS_LOG100 python agent.py热加载与缓存失效Watchdog扩展类被缓存extension_classes(extensions)等缓存区同时 helpers/extension.py 中的register_extensions_watchdogs()注册了多个文件监视器Watchdog监控以下目录的变更并自动清空扩展缓存根extensions/与usr/extensions/usr/projects/**/extensions项目级扩展agents/与usr/agents/下的extensions/目录。这意味着开发扩展时多数情况下无需手动重启——修改扩展文件会触发缓存重建这也是“扩展易于迭代”的设计保障之一。后端扩展extensions/python 全景与内置 Hook 清单extensions/python/ 是框架内置的后端生命周期扩展每个直接子目录就是一个具名扩展点。DOX 索引extensions/python/AGENTS.md列出了全部 26 个扩展点以下是完整清单与职责速查扩展点目录职责_functions/隐式extensibleHook 实现异常处理、日志镜像、断流保护等agent_init/Agent 上下文初始化初始 UI 消息、配置档加载banners/后端横幅与发现卡片贡献如未加密连接警示、系统资源before_main_llm_call/主模型调用前的行为如流式日志准备error_format/错误格式化与掩码hist_add_before/历史插入前的掩码处理hist_add_tool_result/工具结果写入历史的副作用job_loop/周期性后台维护任务如过期 API 会话清理、缓存修剪message_loop_end/消息循环结束时的历史组织与持久化message_loop_prompts_after/提示词协议与附加内容的组装时间、技能、Agent 信息等message_loop_prompts_before/提示词构造前的消息循环门控message_loop_start/消息循环开始的迭代状态monologue_end/独白结束时的 UI 与清理行为monologue_start/独白开始的核心生命周期扩展process_chain_end/处理链完成与排队消息处理reasoning_stream/、reasoning_stream_chunk/、reasoning_stream_end/推理流整体/分块掩码/收尾response_stream/、response_stream_chunk/、response_stream_end/回复流整体/分块掩码/收尾含日志、live responsestartup_migration/启动迁移如自更新管理器system_prompt/核心系统提示词各段构造tool_execute_after/工具执行后处理如密钥掩码tool_execute_before/工具执行前处理如最近工具输出替换、密钥解除掩码、并行递归拦截user_message_ui/用户可见的 UI 消息 Hook如更新检查util_model_call_before/工具模型调用前的密钥掩码webui_ws_connect//webui_ws_disconnect//webui_ws_event/WebUI WebSocket 连接/断开/事件行为如状态同步编号前缀决定执行顺序每个扩展点目录内的 Python 文件按文件名排序后执行因此_10_、_50_、_90_这类数字前缀承担了顺序控制职责。以 extensions/python/system_prompt/ 为例各段系统提示词的构造顺序由前缀固定_10_main_prompt.py主提示词agent.system.main.md_11_tools_prompt.py工具说明_12_mcp_prompt.pyMCP 工具_13_secrets_prompt.py与_13_skills_prompt.py密钥说明与技能说明_14_project_prompt.py项目元数据与稳定项目规则。extensions/python/system_prompt/_10_main_prompt.py 展示了两种扩展点的混合用法——MainPrompt类继承Extension实现显式扩展点把build_prompt()的结果追加进系统提示词列表class MainPrompt(Extension): async def execute(self, system_prompt: list[str] [], loop_data: LoopData LoopData(), **kwargs): if not self.agent: return prompt await build_prompt(self.agent) system_prompt.append(prompt) extensible async def build_prompt(agent: Agent) - str: return agent.read_prompt(agent.system.main.md)build_prompt同时被extensible装饰意味着你可以在_functions/agent/build_prompt/start|end路径下为“主提示词构建”这个函数级节点注入隐式扩展。一个完整的内置扩展示例以 extensions/python/job_loop/_50_trim_cache.py 为例它只有几行却完整演示了“最小可用的显式扩展”长什么样class SaveToolCallFile(Extension): def execute(self, data: dict[str, Any] | None None, **kwargs): cache.trim_cache(*, seconds300)继承Extension实现同步execute无需使用agent即可完成工作调度器始终传入 agent但允许忽略挂载在job_loop周期任务点上每轮修剪超过 300 秒未用的缓存条目。DOX 中的开发约定提醒扩展模块要保持 import 轻量很多 Hook 处于热路径需要改写内容时按 Hook 契约使用可变的ctx或data字典涉及提示词、历史、工具输出、流式、持久化的 Hook 改动都要配套测试。前端扩展extensions/webui 与 WebUI 注入机制后端之外Agent Zero 的 WebUI 同样支持扩展位于 extensions/webui/。DOX 契约extensions/webui/AGENTS.md明确了前端扩展的两种交付形式.html文件作为组件引用通过x-extension注入.js/.mjs文件导出默认函数由callJsExtensions调用。前端扩展点同样按目录组织内置扩展点包括扩展点目录职责fetch_api_call_before//fetch_api_call_after/原生fetchApi()调用前后json_api_call_before//json_api_call_after/callJsonApi()调用前后如缓存重置get_message_handler/消息渲染处理器扩展initFw_end/WebUI 框架初始化完成后如恢复可恢复模态框、自更新全局逻辑right-canvas-panels/内置右侧画布面板 HTML 贡献right_canvas_register_surfaces/右侧画布表面注册文件、远程链接、Space Agentset_messages_before_loop//set_messages_after_loop/消息 DOM 更新前后webui_ws_push/WebUI WebSocket 推送事件行为调度侧helpers/extension.py 的get_webui_extension_manifest()会扫描所有extensions/webui根目录把.html/.htm/.xhtml与.js/.mjs资产按“扩展点 相对目录名”归入 manifest并对结果做缓存get_webui_extensions(agent, extension_point, filters)则按通配符过滤器返回某扩展点下的具体资源路径供前端加载。内置前端扩展的一个直观例子是 extensions/webui/right-canvas-panels/files-panel.html右侧画布的文件面板以及 extensions/webui/right_canvas_register_surfaces/ 下负责注册文件、远程链接、Space Agent 表面的三个 JS 模块。插件如何携带扩展随装随用的真实案例扩展机制的强大之处在于它不限于框架内置——插件的extensions/目录会自动纳入调度器的搜索路径回忆上文_get_extension_classes通过subagents.get_paths收集路径。以内存插件 plugins/_memory/ 为例其扩展文件横跨后端与前端plugins/_memory/extensions/ ├── python/ │ ├── embedding_model_changed/_10_memory_reload.py │ ├── message_loop_prompts_after/_50_recall_memories.py │ ├── message_loop_prompts_after/_91_recall_wait.py │ ├── monologue_end/_50_memorize_fragments.py │ ├── monologue_end/_51_memorize_solutions.py │ ├── monologue_start/_10_memory_init.py │ └── system_prompt/_20_behaviour_prompt.py └── webui/ ├── _sidebar-quick-actions-main-start/memory-entry.html └── sidebar-quick-actions-dropdown-start/memory-entry.html其中 plugins/_memory/extensions/python/message_loop_prompts_after/_50_recall_memories.py 是教科书级的扩展用法完整展示了扩展如何与框架深度协作通过plugins.get_plugin_config(_memory, self.agent)读取自身配置并在memory_recall_enabled关闭时优雅返回每个扩展必须能在未配置/禁用时安全跳过按loop_data.iteration % memory_recall_interval 0决定是否触发记忆召回即“周期性任务”由扩展在消息循环中自行节流使用asyncio.create_taskasyncio.wait_for(..., timeout30)把召回任务异步化并调用self.agent.call_utility_model走工具模型生成搜索查询、再用dirty_json.try_parse解析 AI 过滤结果最终把召回结果写入loop_data.extras_persistent[memories]/[solutions]即扩展通过共享的持久化 extras 把内容注入到后续提示词组装中——这正是message_loop_prompts_after扩展点的设计意图。前端侧plugins/_memory/extensions/webui/_sidebar-quick-actions-main-start/memory-entry.html 展示了 HTML 扩展的写法在x-data容器内声明带x-move-after定位指令的按钮点击后调用openModal打开插件自己的记忆看板页面。这印证了一个事实当你不满足于现有能力时扩展让第三方代码与核心生命周期平起平坐——技能召回、记忆持久化、密钥掩码、流式日志这些框架级能力都可以通过同一套 Hook 机制由插件提供。实践要点与维护规则综合官方文档与仓库契约落地扩展开发时需要遵守以下规则目录名 扩展点名后端放在extensions/python/扩展点/前端放在extensions/webui/扩展点/在插件内则放在插件自己的extensions/下。数字前缀控制顺序同一扩展点内文件按名称排序执行涉及提示词构造、流式掩码、持久化、清理的顺序敏感场景务必保留前缀编号。后端类继承Extension并实现execute注意同步/异步匹配——同步扩展点中返回 awaitable 会被拒绝隐式扩展点则用extensible装饰器按_functions/模块/限定名/start|end/布局。前端.js必须导出默认函数、.html必须是合法组件片段HTML 只在必要时携带 Alpine 状态扩展代码不得假设某插件已安装除非显式守护该依赖。保持幂等与安全生命周期点可能多次触发扩展必须可重复安全运行绝不记录未掩码的密钥、原始隐藏提示词段落或私有用户数据。改动即测试涉及生命周期、提示词、流、WebSocket、WebUI 的改动应运行对应测试修改初始化、迁移、系统提示词类扩展后做一次启动冒烟验证。保持小巧官方维护规则明确要求扩展改动“小而易于解释”如果读者需要完整架构才能理解扩展为何存在就链接到 DeepWiki 相应页面而不要把架构复制进仓库。小结Agent Zero 的扩展机制是一张覆盖后端生命周期、提示词组装、流式输出、工具执行、WebSocket 与 WebUI 前端的完整 Hook 网络显式扩展点让代码可以在任意具名生命周期节点介入extensible隐式扩展点让既有函数无需改动即可获得 start/end 注入能力插件自带的extensions/目录则让第三方能力与框架内置能力遵循完全相同的契约与排序规则。对希望深度定制 Agent 行为的开发者而言把握“目录即扩展点、前缀即顺序、类即处理器”这三条原则就掌握了在 Agent Zero 中安全、优雅地注入自定义行为的方法。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero 扩展机制深度指南：从生命周期 Hook 到插件式扩展实战
Agent Zero 扩展机制深度指南从生命周期 Hook 到插件式扩展实战【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的扩展Extensions机制是其高级定制入口允许开发者在不修改核心源码的前提下把自定义行为精准注入到 Agent 生命周期的任意节点。本文以 docs/developer/extensions.md 为骨架结合 helpers/extension.py 的调度内核与 extensions/ 目录下数十个内置 Hook 实现系统讲解扩展点的布局规则、后端/前端两类扩展的编写契约、内置生命周期 Hook 全景以及插件如何携带扩展随装随用。先理解定位扩展 vs 插件何时该用哪一个官方文档的第一条建议非常直白如果你是新用户先使用插件Plugins而不是扩展Extensions。插件更容易创建、测试、禁用和移除而扩展属于“高级定制方式”用于改变 Agent Zero 的底层行为。从仓库结构可以印证这一分层插件是自包含的功能包例如 plugins/_memory/ 内存插件、plugins/_telegram_integration/ 电报集成插件每个插件目录内可以自带extensions/子目录见下文第五节。而 extensions/ 目录下的内置扩展则是框架自身预置的生命周期 Hook 实现。决策入口表目标起点增加一个小型面向用户的功能Create a Small Plugin为某个项目改变 Agent 行为Projects创建专门的 Agent 风格Agent Profiles研究扩展内部机制DeepWiki for Agent Zero在线文档架构细节与源码链接均迁移至此什么时候扩展才真正合适仅在普通插件、项目指令Projects、技能Skills或 Agent 配置Agent Profiles不够用的时候才考虑扩展。官方列出的合适场景包括在特定生命周期节点添加行为例如消息循环开始、工具执行前后、流式输出过程中以可复用的方式塑造提示词Prompt与核心工具紧密集成在任务开始前准备框架持有的状态。应当避免用扩展实现简单的 UI 修改、一次性脚本、或未来容易需要移除的工作——这些场景插件是更干净的家。从 extensions/AGENTS.md 的维护契约中可以看到官方对扩展的约束原则扩展目录名即运行时扩展点名带数字前缀的文件按名称顺序执行扩展必须能在生命周期点多次触发时安全重复运行涉及密钥掩码、认证、安全、持久化的扩展不允许被“便利性改动”绕过。扩展调度内核helpers/extension.py理解扩展机制的最快方式是阅读其调度核心 helpers/extension.py。整个后端扩展体系围绕两个核心概念展开显式扩展点Named Extension Points与隐式扩展点Implicit Extension Points。显式扩展点按目录名调度框架在代码中直接调用call_extensions_async或call_extensions_sync传入一个扩展点名如system_prompt、tool_execute_before调度器随即在所有扩展搜索路径中查找同名目录下的类并执行async def call_extensions_async( extension_point: str, agent: Agent|None None, **kwargs ): classes _get_extension_classes(extension_point, agentagent, **kwargs) for cls in classes: result cls(agentagent).execute(**kwargs) if isinstance(result, Awaitable): await result_get_extension_classes的实现揭示了两个重要事实搜索路径通过subagents.get_paths(agent, extensions/python, extension_point)获得意味着扩展不仅存在于仓库根部的 extensions/python 目录还存在于用户目录usr/extensions以及每个插件、每个 Agent 的extensions/目录中同名文件优先override机制当多个来源出现同名文件时“第一次出现的文件名即覆盖项”最终按文件名排序后依次执行——这就是“数字前缀控制顺序”约定的由来。所有扩展类必须继承helpers.extension.Extension基类并实现execute方法class Extension: def __init__(self, agent: Agent|None, **kwargs): self.agent agent self.kwargs kwargs abstractmethod def execute(self, **kwargs) - None | Awaitable[None]: pass同步模式下若扩展返回了可等待对象会直接抛出ValueError提示“sync 模式下返回了 awaitable”这是对同步/异步契约的强约束。隐式扩展点extensible 装饰器除显式调用外框架通过extensible装饰器为既有函数自动派生出两个扩展点无需修改函数内部的调用代码_functions/模块路径/限定名路径/start_functions/模块路径/限定名路径/end例如模块helpers.something中的函数Outer.Inner.__init__会映射为_functions/helpers/something/Outer/Inner/__init__/start _functions/helpers/something/Outer/Inner/__init__/end被装饰函数执行时装饰器构造一个可变data负载并依次传递给两个扩展点data[args]/data[kwargs]原函数参数扩展可以替换或修改data[result]初始为内部哨兵值扩展可提前赋值以短路原函数data[exception]扩展可设置为异常实例以强制抛出。执行顺序为start扩展先行可修改输入或短路→ 若 result 未被设置则调用原函数 →end扩展最后运行可改写 result 或替换/清除异常。同步函数走call_extensions_sync异步函数走call_extensions_async。仓库内置的隐式扩展实现位于 extensions/python/_functions/例如 Agent/handle_exception/end/_40_handle_intervention_exception.py 等异常处理钩子。压测用例 tests/test_extensions_stress.py 中PerfAgent.perf_hook正是用extensible包装方法并循环 10000 次做性能追踪说明该机制被设计得足够轻量以承受热路径调用。调试辅助EXTENSIONS_LOG调度器内置了一个调用计数调试开关设置环境变量EXTENSIONS_LOG为正整数后每累计到该次数就会打印各扩展点的调用次数便于定位“某扩展点是否被触发、触发频率如何”的问题EXTENSIONS_LOG100 python agent.py热加载与缓存失效Watchdog扩展类被缓存extension_classes(extensions)等缓存区同时 helpers/extension.py 中的register_extensions_watchdogs()注册了多个文件监视器Watchdog监控以下目录的变更并自动清空扩展缓存根extensions/与usr/extensions/usr/projects/**/extensions项目级扩展agents/与usr/agents/下的extensions/目录。这意味着开发扩展时多数情况下无需手动重启——修改扩展文件会触发缓存重建这也是“扩展易于迭代”的设计保障之一。后端扩展extensions/python 全景与内置 Hook 清单extensions/python/ 是框架内置的后端生命周期扩展每个直接子目录就是一个具名扩展点。DOX 索引extensions/python/AGENTS.md列出了全部 26 个扩展点以下是完整清单与职责速查扩展点目录职责_functions/隐式extensibleHook 实现异常处理、日志镜像、断流保护等agent_init/Agent 上下文初始化初始 UI 消息、配置档加载banners/后端横幅与发现卡片贡献如未加密连接警示、系统资源before_main_llm_call/主模型调用前的行为如流式日志准备error_format/错误格式化与掩码hist_add_before/历史插入前的掩码处理hist_add_tool_result/工具结果写入历史的副作用job_loop/周期性后台维护任务如过期 API 会话清理、缓存修剪message_loop_end/消息循环结束时的历史组织与持久化message_loop_prompts_after/提示词协议与附加内容的组装时间、技能、Agent 信息等message_loop_prompts_before/提示词构造前的消息循环门控message_loop_start/消息循环开始的迭代状态monologue_end/独白结束时的 UI 与清理行为monologue_start/独白开始的核心生命周期扩展process_chain_end/处理链完成与排队消息处理reasoning_stream/、reasoning_stream_chunk/、reasoning_stream_end/推理流整体/分块掩码/收尾response_stream/、response_stream_chunk/、response_stream_end/回复流整体/分块掩码/收尾含日志、live responsestartup_migration/启动迁移如自更新管理器system_prompt/核心系统提示词各段构造tool_execute_after/工具执行后处理如密钥掩码tool_execute_before/工具执行前处理如最近工具输出替换、密钥解除掩码、并行递归拦截user_message_ui/用户可见的 UI 消息 Hook如更新检查util_model_call_before/工具模型调用前的密钥掩码webui_ws_connect//webui_ws_disconnect//webui_ws_event/WebUI WebSocket 连接/断开/事件行为如状态同步编号前缀决定执行顺序每个扩展点目录内的 Python 文件按文件名排序后执行因此_10_、_50_、_90_这类数字前缀承担了顺序控制职责。以 extensions/python/system_prompt/ 为例各段系统提示词的构造顺序由前缀固定_10_main_prompt.py主提示词agent.system.main.md_11_tools_prompt.py工具说明_12_mcp_prompt.pyMCP 工具_13_secrets_prompt.py与_13_skills_prompt.py密钥说明与技能说明_14_project_prompt.py项目元数据与稳定项目规则。extensions/python/system_prompt/_10_main_prompt.py 展示了两种扩展点的混合用法——MainPrompt类继承Extension实现显式扩展点把build_prompt()的结果追加进系统提示词列表class MainPrompt(Extension): async def execute(self, system_prompt: list[str] [], loop_data: LoopData LoopData(), **kwargs): if not self.agent: return prompt await build_prompt(self.agent) system_prompt.append(prompt) extensible async def build_prompt(agent: Agent) - str: return agent.read_prompt(agent.system.main.md)build_prompt同时被extensible装饰意味着你可以在_functions/agent/build_prompt/start|end路径下为“主提示词构建”这个函数级节点注入隐式扩展。一个完整的内置扩展示例以 extensions/python/job_loop/_50_trim_cache.py 为例它只有几行却完整演示了“最小可用的显式扩展”长什么样class SaveToolCallFile(Extension): def execute(self, data: dict[str, Any] | None None, **kwargs): cache.trim_cache(*, seconds300)继承Extension实现同步execute无需使用agent即可完成工作调度器始终传入 agent但允许忽略挂载在job_loop周期任务点上每轮修剪超过 300 秒未用的缓存条目。DOX 中的开发约定提醒扩展模块要保持 import 轻量很多 Hook 处于热路径需要改写内容时按 Hook 契约使用可变的ctx或data字典涉及提示词、历史、工具输出、流式、持久化的 Hook 改动都要配套测试。前端扩展extensions/webui 与 WebUI 注入机制后端之外Agent Zero 的 WebUI 同样支持扩展位于 extensions/webui/。DOX 契约extensions/webui/AGENTS.md明确了前端扩展的两种交付形式.html文件作为组件引用通过x-extension注入.js/.mjs文件导出默认函数由callJsExtensions调用。前端扩展点同样按目录组织内置扩展点包括扩展点目录职责fetch_api_call_before//fetch_api_call_after/原生fetchApi()调用前后json_api_call_before//json_api_call_after/callJsonApi()调用前后如缓存重置get_message_handler/消息渲染处理器扩展initFw_end/WebUI 框架初始化完成后如恢复可恢复模态框、自更新全局逻辑right-canvas-panels/内置右侧画布面板 HTML 贡献right_canvas_register_surfaces/右侧画布表面注册文件、远程链接、Space Agentset_messages_before_loop//set_messages_after_loop/消息 DOM 更新前后webui_ws_push/WebUI WebSocket 推送事件行为调度侧helpers/extension.py 的get_webui_extension_manifest()会扫描所有extensions/webui根目录把.html/.htm/.xhtml与.js/.mjs资产按“扩展点 相对目录名”归入 manifest并对结果做缓存get_webui_extensions(agent, extension_point, filters)则按通配符过滤器返回某扩展点下的具体资源路径供前端加载。内置前端扩展的一个直观例子是 extensions/webui/right-canvas-panels/files-panel.html右侧画布的文件面板以及 extensions/webui/right_canvas_register_surfaces/ 下负责注册文件、远程链接、Space Agent 表面的三个 JS 模块。插件如何携带扩展随装随用的真实案例扩展机制的强大之处在于它不限于框架内置——插件的extensions/目录会自动纳入调度器的搜索路径回忆上文_get_extension_classes通过subagents.get_paths收集路径。以内存插件 plugins/_memory/ 为例其扩展文件横跨后端与前端plugins/_memory/extensions/ ├── python/ │ ├── embedding_model_changed/_10_memory_reload.py │ ├── message_loop_prompts_after/_50_recall_memories.py │ ├── message_loop_prompts_after/_91_recall_wait.py │ ├── monologue_end/_50_memorize_fragments.py │ ├── monologue_end/_51_memorize_solutions.py │ ├── monologue_start/_10_memory_init.py │ └── system_prompt/_20_behaviour_prompt.py └── webui/ ├── _sidebar-quick-actions-main-start/memory-entry.html └── sidebar-quick-actions-dropdown-start/memory-entry.html其中 plugins/_memory/extensions/python/message_loop_prompts_after/_50_recall_memories.py 是教科书级的扩展用法完整展示了扩展如何与框架深度协作通过plugins.get_plugin_config(_memory, self.agent)读取自身配置并在memory_recall_enabled关闭时优雅返回每个扩展必须能在未配置/禁用时安全跳过按loop_data.iteration % memory_recall_interval 0决定是否触发记忆召回即“周期性任务”由扩展在消息循环中自行节流使用asyncio.create_taskasyncio.wait_for(..., timeout30)把召回任务异步化并调用self.agent.call_utility_model走工具模型生成搜索查询、再用dirty_json.try_parse解析 AI 过滤结果最终把召回结果写入loop_data.extras_persistent[memories]/[solutions]即扩展通过共享的持久化 extras 把内容注入到后续提示词组装中——这正是message_loop_prompts_after扩展点的设计意图。前端侧plugins/_memory/extensions/webui/_sidebar-quick-actions-main-start/memory-entry.html 展示了 HTML 扩展的写法在x-data容器内声明带x-move-after定位指令的按钮点击后调用openModal打开插件自己的记忆看板页面。这印证了一个事实当你不满足于现有能力时扩展让第三方代码与核心生命周期平起平坐——技能召回、记忆持久化、密钥掩码、流式日志这些框架级能力都可以通过同一套 Hook 机制由插件提供。实践要点与维护规则综合官方文档与仓库契约落地扩展开发时需要遵守以下规则目录名 扩展点名后端放在extensions/python/扩展点/前端放在extensions/webui/扩展点/在插件内则放在插件自己的extensions/下。数字前缀控制顺序同一扩展点内文件按名称排序执行涉及提示词构造、流式掩码、持久化、清理的顺序敏感场景务必保留前缀编号。后端类继承Extension并实现execute注意同步/异步匹配——同步扩展点中返回 awaitable 会被拒绝隐式扩展点则用extensible装饰器按_functions/模块/限定名/start|end/布局。前端.js必须导出默认函数、.html必须是合法组件片段HTML 只在必要时携带 Alpine 状态扩展代码不得假设某插件已安装除非显式守护该依赖。保持幂等与安全生命周期点可能多次触发扩展必须可重复安全运行绝不记录未掩码的密钥、原始隐藏提示词段落或私有用户数据。改动即测试涉及生命周期、提示词、流、WebSocket、WebUI 的改动应运行对应测试修改初始化、迁移、系统提示词类扩展后做一次启动冒烟验证。保持小巧官方维护规则明确要求扩展改动“小而易于解释”如果读者需要完整架构才能理解扩展为何存在就链接到 DeepWiki 相应页面而不要把架构复制进仓库。小结Agent Zero 的扩展机制是一张覆盖后端生命周期、提示词组装、流式输出、工具执行、WebSocket 与 WebUI 前端的完整 Hook 网络显式扩展点让代码可以在任意具名生命周期节点介入extensible隐式扩展点让既有函数无需改动即可获得 start/end 注入能力插件自带的extensions/目录则让第三方能力与框架内置能力遵循完全相同的契约与排序规则。对希望深度定制 Agent 行为的开发者而言把握“目录即扩展点、前缀即顺序、类即处理器”这三条原则就掌握了在 Agent Zero 中安全、优雅地注入自定义行为的方法。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考