Agent Zero System Prompt 分段构建架构有序扩展点、所有权契约与源码实现解析【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文围绕 Agent Zero 仓库中 extensions/python/system_prompt/AGENTS.md 这一开发文档展开深入剖析该项目如何通过一个名为system_prompt的 Python 扩展点把核心系统提示词System Prompt拆分为 main、tools、MCP、secrets、skills、project 六个独立分段并交由六个有序构建器文件组装渲染。读完本文你将理解 Agent Zero 系统提示词的完整生成链路、各分段的职责边界与底层实现、密钥掩码与顺序性等本地契约以及如何在现有架构上新增或覆盖一个提示词分段。一、System Prompt 扩展点的定位核心分段的所有权划分在 Agent Zero 中system_prompt扩展点位于 extensions/python/system_prompt/其 DOX 文档AGENTS.md明确了两条核心所有权约定Purpose目的该扩展点Own construction of core system prompt sections即全权负责核心系统提示词各分段的构建是整个 Agent 提示词工程的组装核心。Ownership所有权目录内一组按数字前缀排序的 Python 文件分别拥有 main、tools、MCP、secrets、skills、project 六大提示词分段同时活跃项目的指令正文instruction bodies与活跃项目 AGENTS.md 的路径链指引被移入 prompt protocol系统提示词只保留项目元数据与稳定的项目规则。这一所有权分离设计值得注意属于每个具体项目的动态指令如项目 AGENTS.md 中按路径链下发的指导不再写死进系统提示词而是进入loop_data.protocol_persistent维护的 prompt protocol系统提示词内只保留相对稳定的项目元数据与规则从而让提示词结构在项目切换时保持稳定、可预测。从 extensions/python/AGENTS.md 的扩展点索引表可以看到system_prompt只是该项目众多生命周期扩展点agent_init、message_loop_prompts_after、tool_execute_before、response_stream等之一它专门负责Core system prompt section construction。二、渲染入口get_system_prompt与system_prompt扩展点的调用链系统提示词的组装入口在 Agent 主类中。在 agent.py 中可以看到extension.extensible async def get_system_prompt(self, loop_data: LoopData) - list[str]: system_prompt: list[str] [] await extension.call_extensions_async( system_prompt, self, system_promptsystem_prompt, loop_dataloop_data ) return system_prompt调用链分三层get_system_prompt先初始化一个空的system_prompt: list[str]通过 helpers/extension.py 的call_extensions_async以system_prompt为扩展点名称找出所有符合条件的扩展类并按文件名顺序执行其execute每个扩展类的execute拿到同一个system_prompt列表把自己构建的分段文本append 进去最终按序拼成完整系统提示词。helpers/extension.py中Extension基类只要求实现一个execute方法而扩展类通过subagents.get_paths从多个候选目录如extensions/python/、usr/extensions/、agents/*/extensions/、项目级extensions/聚合再按文件名排序去重执行首个出现的同名文件即为覆盖版本。这意味着开发者可以通过在用户级或 Agent 级扩展目录放置同名文件来覆盖内置分段构建器。三、六大构建器逐段解析extensions/python/system_prompt/目录下共有六个 Python 文件对应文档所言的六个分段所有权。下面结合每个文件的源码逐一展开。3.1_10_main_prompt.py主提示骨架extensions/python/system_prompt/_10_main_prompt.py 是所有分段中最先执行的构建器负责注入系统提示词的主体骨架extensible async def build_prompt(agent: Agent) - str: return agent.read_prompt(agent.system.main.md)其核心动作是调用agent.read_prompt(agent.system.main.md)把 prompts/agent.system.main.md 模板渲染为文本。该模板是 Agent 的角色与行为总纲配套的还有agent.system.main.role.md、agent.system.main.specifics.md、agent.system.main.tips.md等细化模板均在 prompts/ 目录。值得注意build_prompt被extensible装饰helpers/extension.py 中该装饰器会为被包裹函数自动生成_functions/module/qualname/start与_functions/module/qualname/end两个隐式扩展点允许在函数执行前后改写参数或结果。也就是说主提示的生成既可以被显式的system_prompt扩展点追加分段也可以被隐式的函数级扩展点在build_prompt前后进行细粒度干预。3.2_11_tools_prompt.py工具清单聚合器extensions/python/system_prompt/_11_tools_prompt.py 负责把当前 Agent 可见的所有工具说明聚合成 tools 分段其逻辑最能体现该扩展点文件系统驱动的风格prompt_dirs subagents.get_paths(agent, prompts) tool_files files.get_unique_filenames_in_dirs( prompt_dirs, agent.system.tool.*.md )先从所有 Agent 的prompts目录收集模板路径subagents.get_paths再用files.get_unique_filenames_in_dirs按agent.system.tool.*.md模式去重收集工具说明模板——这正是 prompts/agent.system.tool.behaviour.md、agent.system.tool.wait.md、agent.system.tool.response.md等一系列模板被逐一载入的机制随后通过agent.read_prompt(agent.system.tools.md, toolstools_str)把所有工具文本注入 prompts/agent.system.tools.md 外壳形成完整 tools 分段。该文件还实现了**按文件注册的模板参数per-file kwargs**机制插件可以通过配置扩展向TOOL_KWARGS_KEY_tool_prompt_kwargs写入{模板文件名: 参数}加载对应工具模板时会把这些参数传入read_prompt实现对单个工具提示的定制源码注释举例为_09_text_editor_config。此外它还处理视觉模型支持通过plugins._model_config.helpers.model_config的get_chat_model_config(agent)获取当前模型配置若chat_cfg.get(vision, False)为真则在工具分段后追加 prompts/agent.system.tools_vision.md为具备视觉能力的模型补充图像理解相关指引。3.3_12_mcp_prompt.pyMCP 服务器工具清单extensions/python/system_prompt/_12_mcp_prompt.py 负责把已配置的 MCPModel Context Protocol服务器暴露的工具并入提示词mcp_config MCPConfig.get_for_agent(agent) if not mcp_config.servers: return 通过 helpers/mcp_handler.py 的MCPConfig.get_for_agent获取当前 Agent 的 MCP 配置如果没有配置任何服务器直接返回空字符串execute中if prompt:的守卫使其不会向system_prompt列表追加内容避免污染提示词存在服务器时会在日志进度区短暂显示Collecting MCP tools随后调用mcp_config.get_tools_prompt()收集工具清单文本。这一无配置即零成本的模式与 secrets、skills 分段一致保证提示词只包含当前运行时真正可用的能力描述。3.4_13_secrets_prompt.py密钥的掩码与范围化注入extensions/python/system_prompt/_13_secrets_prompt.py 体现了 DOX 文档Local Contracts中Keep secret-related prompt sections masked and scoped密钥相关提示分段必须掩码且范围受限的约束secrets_manager get_secrets_manager(agent.context) secrets secrets_manager.get_secrets_for_prompt() variables get_settings()[variables] return agent.read_prompt( agent.system.secrets.md, secretssecrets, varsvariables )通过 helpers/secrets.py 的get_secrets_manager取得密钥管理器再调用get_secrets_for_prompt()只取允许进入提示词的那部分密钥而非全部凭据同时注入 helpers/settings.py 中的全局变量variables与密钥一起渲染 prompts/agent.system.secrets.md整个过程被try/except包裹任何异常都静默返回空串避免因密钥系统故障导致提示词构建崩溃。与该分段配套的是整套运行时掩码机制项目在 extensions/python/tool_execute_before/ 与 extensions/python/tool_execute_after/、extensions/python/util_model_call_before/ 等扩展点中实现执行前解掩码、执行后重新掩码确保密钥只在必要的调用瞬间以明文出现。3.5_13_skills_prompt.py可用技能目录extensions/python/system_prompt/_13_skills_prompt.py 与 secrets 构建器共享_13_前缀负责把当前 Agent 可用的技能清单注入提示词available skills_helper.list_skills(agentagent) for skill in available: name skill.name.strip().replace(\n, )[:100] descr skill.description.replace(\n, ).strip() if len(descr) 100: descr descr[:100].rstrip() ... result.append(f- {name}: {descr} if descr else f- {name})通过 helpers/skills.py 的list_skills(agentagent)枚举技能对每个技能的名称与描述做了有界截断名称与描述各截取 100 字符多行折叠为单行——这正是 DOX 契约中Prompt additions must be bounded提示词添加必须有界的直接体现防止过长技能描述撑爆上下文渲染到 prompts/agent.system.skills.md 模板若无任何可用技能则返回空串。注意它与另一条技能注入路径的区别message_loop_prompts_after扩展点下的_63_recall_relevant_skills.py、_65_include_loaded_skills.py负责按当前消息召回相关技能与注入已加载技能属于消息循环内的动态内容而本分段提供的是静态的技能总目录二者互补。3.6_14_project_prompt.py项目元数据与稳定规则extensions/python/system_prompt/_14_project_prompt.py 是六个构建器中逻辑最复杂的一个直接对应 DOX 中Active project instruction bodies ... are moved into prompt protocol; the system prompt keeps project metadata and stable project rules的描述result agent.read_prompt(agent.system.projects.main.md) project_name agent.context.get_data(projects.CONTEXT_DATA_KEY_PROJECT) if loop_data: loop_data.protocol_persistent.pop(agents_md_instructions, None) loop_data.protocol_persistent.pop(project_instructions, None) if project_name: project_vars projects.build_system_prompt_vars(project_name) if loop_data and project_vars.get(include_agents_md, True): agents_md_protocol projects.build_agents_md_protocol(project_name) if agents_md_protocol: loop_data.protocol_persistent[agents_md_instructions] agents_md_protocol if loop_data and project_vars.get(project_instructions): loop_data.protocol_persistent[project_instructions] agent.read_prompt( agent.protocol.projects.instructions.md, **project_vars ) result \n\n agent.read_prompt(agent.system.projects.active.md, **project_vars) else: result \n\n agent.read_prompt(agent.system.projects.inactive.md)其行为可拆解为四步先渲染 prompts/agent.system.projects.main.md 作为 project 分段的骨架从上下文取当前项目名CONTEXT_DATA_KEY_PROJECT并在每轮先清空protocol_persistent中上一轮遗留的agents_md_instructions与project_instructions保证提示词协议不跨轮残留若处于活跃项目通过 helpers/projects.py 的build_system_prompt_vars构造项目变量把项目 AGENTS.md 的路径链指引build_agents_md_protocol受include_agents_md开关控制与项目指令正文渲染 prompts/agent.protocol.projects.instructions.md写入loop_data.protocol_persistent成为prompt protocol的一部分系统提示词本身只追加渲染 prompts/agent.system.projects.active.md 得到的项目元数据与稳定规则无活跃项目时追加 prompts/agent.system.projects.inactive.md 的非活跃项目占位提示。这一设计正是文档所述系统提示词保留项目元数据与稳定项目规则、动态指令走 protocol的落地实现。四、本地契约顺序性、密钥掩码与有界性DOX 文档的Local Contracts定义了三条必须遵守的本地契约它们都有对应的源码机制支撑1. 保持顺序Preserve orderingPreserve ordering where sections depend on earlier context.系统提示词分段之间存在上下文依赖例如 tools 分段引用agent.system.tool.*.md模板时依赖 main 分段确立的角色上下文secrets 分段依赖 settings 变量。六个构建器通过数字文件名前缀_10_、_11_、_12_、_13_、_14_保证确定性加载顺序这一点与 extensions/python/AGENTS.md 中Preserve numeric prefixes when ordering affects prompt construction的约定一致helpers/extension.py的_get_extension_classes也按文件名排序后执行从机制上保证顺序稳定。因此新增分段时必须依据其在提示词中的逻辑位置选择合适的数字前缀。2. 密钥相关分段必须掩码且范围化Keep secret-related prompt sections masked and scoped.正如 3.4 节所述secrets 分段只注入get_secrets_for_prompt()返回的白名单子集并在渲染 prompts/agent.system.secrets.md 后配合tool_execute_before/after、util_model_call_before等扩展点实现用前解掩、用后回掩避免密钥常驻提示词与历史记录。3. 提示词添加必须有界且兼容工具调用契约Prompt additions must be bounded and compatible with tool-call contracts.skills 分段对技能名与描述做 100 字符截断、MCP 无配置即跳过、工具模板按agent.system.tool.*.md统一模式收集都是有界的体现而所有工具说明最终统一渲染进 prompts/agent.system.tools.md保证与fw.tool_result、fw.tool_not_found等工具调用反馈框架见 prompts/ 下的fw.*.md模板格式兼容。五、工作指引与验证方式DOX 文档的Work Guidance要求协调系统提示词的跨模块变更——由于 system prompt 影响面广任何改动都要与 profilesAgent 配置、skills、tools、plugins 以及提示词相关测试保持同步避免出现提示词变了但工具契约没跟上的撕裂。Verification则给出了两条验证路径人工检查在运行中查看渲染后的完整系统提示词确认各分段顺序、内容与掩码状态正确自动化测试运行提示词构建相关测试。仓库 tests/test_prompt_protocol.py 即针对 prompt protocol含 project 指令注入的专项测试类似的还有 tests/test_default_prompt_budget.py、tests/test_response_tool_validation.py 等对提示词与工具契约的校验。另外helpers/extension.py 的register_extensions_watchdogs会为extensions/python、usr/extensions、agents/*/extensions及项目级扩展目录注册文件系统 watchdog扩展文件变更即自动清空扩展类缓存并重新加载因此调试提示词分段时可以热更新无需重启进程。六、如何新增或覆盖一个提示词分段基于上述架构在 Agent Zero 中扩展系统提示词有三种途径追加新分段在extensions/python/system_prompt/或用户级usr/extensions/system_prompt/、Agent 级agents/name/extensions/system_prompt/新建一个带数字前缀的 Python 文件定义一个继承Extension的类在execute中调用agent.read_prompt(模板名.md, **kwargs)构造文本并system_prompt.append(...)。数字前缀决定其在提示词中的位置。覆盖内置分段在优先级更高的扩展目录放置同名文件helpers/extension.py的合并逻辑会以首个出现的文件名为准实现分段级替换也可以直接通过extensible的隐式_functions/module/qualname/start|end扩展点在既有build_prompt前后改写结果。新增模板把提示模板放入某个 Agent 的prompts目录或放入项目级 prompt 目录subagents.get_paths会自动覆盖聚合路径tools 分段会通过agent.system.tool.*.md模式自动发现新工具模板。结语extensions/python/system_prompt/是 Agent Zero 系统提示词工程的组装车间入口 agent.py 的get_system_prompt触发system_prompt扩展点六个按数字前缀排序的构建器_10_main_prompt.py、_11_tools_prompt.py、_12_mcp_prompt.py、_13_secrets_prompt.py、_13_skills_prompt.py、_14_project_prompt.py分别负责 main、tools、MCP、secrets、skills、project 六大分段。其设计精髓在于以文件系统布局表达所有权、以数字前缀保证顺序、以空串返回实现按需注入、以 protocol_persistent 分离稳定规则与动态指令、以掩码与截断守住安全与上下文预算。理解这套架构后无论是排查提示词异常、定制 Agent 行为还是为项目新增能力分段都能在清晰的契约框架内高效完成。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero System Prompt 分段构建架构：有序扩展点、所有权契约与源码实现解析
Agent Zero System Prompt 分段构建架构有序扩展点、所有权契约与源码实现解析【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文围绕 Agent Zero 仓库中 extensions/python/system_prompt/AGENTS.md 这一开发文档展开深入剖析该项目如何通过一个名为system_prompt的 Python 扩展点把核心系统提示词System Prompt拆分为 main、tools、MCP、secrets、skills、project 六个独立分段并交由六个有序构建器文件组装渲染。读完本文你将理解 Agent Zero 系统提示词的完整生成链路、各分段的职责边界与底层实现、密钥掩码与顺序性等本地契约以及如何在现有架构上新增或覆盖一个提示词分段。一、System Prompt 扩展点的定位核心分段的所有权划分在 Agent Zero 中system_prompt扩展点位于 extensions/python/system_prompt/其 DOX 文档AGENTS.md明确了两条核心所有权约定Purpose目的该扩展点Own construction of core system prompt sections即全权负责核心系统提示词各分段的构建是整个 Agent 提示词工程的组装核心。Ownership所有权目录内一组按数字前缀排序的 Python 文件分别拥有 main、tools、MCP、secrets、skills、project 六大提示词分段同时活跃项目的指令正文instruction bodies与活跃项目 AGENTS.md 的路径链指引被移入 prompt protocol系统提示词只保留项目元数据与稳定的项目规则。这一所有权分离设计值得注意属于每个具体项目的动态指令如项目 AGENTS.md 中按路径链下发的指导不再写死进系统提示词而是进入loop_data.protocol_persistent维护的 prompt protocol系统提示词内只保留相对稳定的项目元数据与规则从而让提示词结构在项目切换时保持稳定、可预测。从 extensions/python/AGENTS.md 的扩展点索引表可以看到system_prompt只是该项目众多生命周期扩展点agent_init、message_loop_prompts_after、tool_execute_before、response_stream等之一它专门负责Core system prompt section construction。二、渲染入口get_system_prompt与system_prompt扩展点的调用链系统提示词的组装入口在 Agent 主类中。在 agent.py 中可以看到extension.extensible async def get_system_prompt(self, loop_data: LoopData) - list[str]: system_prompt: list[str] [] await extension.call_extensions_async( system_prompt, self, system_promptsystem_prompt, loop_dataloop_data ) return system_prompt调用链分三层get_system_prompt先初始化一个空的system_prompt: list[str]通过 helpers/extension.py 的call_extensions_async以system_prompt为扩展点名称找出所有符合条件的扩展类并按文件名顺序执行其execute每个扩展类的execute拿到同一个system_prompt列表把自己构建的分段文本append 进去最终按序拼成完整系统提示词。helpers/extension.py中Extension基类只要求实现一个execute方法而扩展类通过subagents.get_paths从多个候选目录如extensions/python/、usr/extensions/、agents/*/extensions/、项目级extensions/聚合再按文件名排序去重执行首个出现的同名文件即为覆盖版本。这意味着开发者可以通过在用户级或 Agent 级扩展目录放置同名文件来覆盖内置分段构建器。三、六大构建器逐段解析extensions/python/system_prompt/目录下共有六个 Python 文件对应文档所言的六个分段所有权。下面结合每个文件的源码逐一展开。3.1_10_main_prompt.py主提示骨架extensions/python/system_prompt/_10_main_prompt.py 是所有分段中最先执行的构建器负责注入系统提示词的主体骨架extensible async def build_prompt(agent: Agent) - str: return agent.read_prompt(agent.system.main.md)其核心动作是调用agent.read_prompt(agent.system.main.md)把 prompts/agent.system.main.md 模板渲染为文本。该模板是 Agent 的角色与行为总纲配套的还有agent.system.main.role.md、agent.system.main.specifics.md、agent.system.main.tips.md等细化模板均在 prompts/ 目录。值得注意build_prompt被extensible装饰helpers/extension.py 中该装饰器会为被包裹函数自动生成_functions/module/qualname/start与_functions/module/qualname/end两个隐式扩展点允许在函数执行前后改写参数或结果。也就是说主提示的生成既可以被显式的system_prompt扩展点追加分段也可以被隐式的函数级扩展点在build_prompt前后进行细粒度干预。3.2_11_tools_prompt.py工具清单聚合器extensions/python/system_prompt/_11_tools_prompt.py 负责把当前 Agent 可见的所有工具说明聚合成 tools 分段其逻辑最能体现该扩展点文件系统驱动的风格prompt_dirs subagents.get_paths(agent, prompts) tool_files files.get_unique_filenames_in_dirs( prompt_dirs, agent.system.tool.*.md )先从所有 Agent 的prompts目录收集模板路径subagents.get_paths再用files.get_unique_filenames_in_dirs按agent.system.tool.*.md模式去重收集工具说明模板——这正是 prompts/agent.system.tool.behaviour.md、agent.system.tool.wait.md、agent.system.tool.response.md等一系列模板被逐一载入的机制随后通过agent.read_prompt(agent.system.tools.md, toolstools_str)把所有工具文本注入 prompts/agent.system.tools.md 外壳形成完整 tools 分段。该文件还实现了**按文件注册的模板参数per-file kwargs**机制插件可以通过配置扩展向TOOL_KWARGS_KEY_tool_prompt_kwargs写入{模板文件名: 参数}加载对应工具模板时会把这些参数传入read_prompt实现对单个工具提示的定制源码注释举例为_09_text_editor_config。此外它还处理视觉模型支持通过plugins._model_config.helpers.model_config的get_chat_model_config(agent)获取当前模型配置若chat_cfg.get(vision, False)为真则在工具分段后追加 prompts/agent.system.tools_vision.md为具备视觉能力的模型补充图像理解相关指引。3.3_12_mcp_prompt.pyMCP 服务器工具清单extensions/python/system_prompt/_12_mcp_prompt.py 负责把已配置的 MCPModel Context Protocol服务器暴露的工具并入提示词mcp_config MCPConfig.get_for_agent(agent) if not mcp_config.servers: return 通过 helpers/mcp_handler.py 的MCPConfig.get_for_agent获取当前 Agent 的 MCP 配置如果没有配置任何服务器直接返回空字符串execute中if prompt:的守卫使其不会向system_prompt列表追加内容避免污染提示词存在服务器时会在日志进度区短暂显示Collecting MCP tools随后调用mcp_config.get_tools_prompt()收集工具清单文本。这一无配置即零成本的模式与 secrets、skills 分段一致保证提示词只包含当前运行时真正可用的能力描述。3.4_13_secrets_prompt.py密钥的掩码与范围化注入extensions/python/system_prompt/_13_secrets_prompt.py 体现了 DOX 文档Local Contracts中Keep secret-related prompt sections masked and scoped密钥相关提示分段必须掩码且范围受限的约束secrets_manager get_secrets_manager(agent.context) secrets secrets_manager.get_secrets_for_prompt() variables get_settings()[variables] return agent.read_prompt( agent.system.secrets.md, secretssecrets, varsvariables )通过 helpers/secrets.py 的get_secrets_manager取得密钥管理器再调用get_secrets_for_prompt()只取允许进入提示词的那部分密钥而非全部凭据同时注入 helpers/settings.py 中的全局变量variables与密钥一起渲染 prompts/agent.system.secrets.md整个过程被try/except包裹任何异常都静默返回空串避免因密钥系统故障导致提示词构建崩溃。与该分段配套的是整套运行时掩码机制项目在 extensions/python/tool_execute_before/ 与 extensions/python/tool_execute_after/、extensions/python/util_model_call_before/ 等扩展点中实现执行前解掩码、执行后重新掩码确保密钥只在必要的调用瞬间以明文出现。3.5_13_skills_prompt.py可用技能目录extensions/python/system_prompt/_13_skills_prompt.py 与 secrets 构建器共享_13_前缀负责把当前 Agent 可用的技能清单注入提示词available skills_helper.list_skills(agentagent) for skill in available: name skill.name.strip().replace(\n, )[:100] descr skill.description.replace(\n, ).strip() if len(descr) 100: descr descr[:100].rstrip() ... result.append(f- {name}: {descr} if descr else f- {name})通过 helpers/skills.py 的list_skills(agentagent)枚举技能对每个技能的名称与描述做了有界截断名称与描述各截取 100 字符多行折叠为单行——这正是 DOX 契约中Prompt additions must be bounded提示词添加必须有界的直接体现防止过长技能描述撑爆上下文渲染到 prompts/agent.system.skills.md 模板若无任何可用技能则返回空串。注意它与另一条技能注入路径的区别message_loop_prompts_after扩展点下的_63_recall_relevant_skills.py、_65_include_loaded_skills.py负责按当前消息召回相关技能与注入已加载技能属于消息循环内的动态内容而本分段提供的是静态的技能总目录二者互补。3.6_14_project_prompt.py项目元数据与稳定规则extensions/python/system_prompt/_14_project_prompt.py 是六个构建器中逻辑最复杂的一个直接对应 DOX 中Active project instruction bodies ... are moved into prompt protocol; the system prompt keeps project metadata and stable project rules的描述result agent.read_prompt(agent.system.projects.main.md) project_name agent.context.get_data(projects.CONTEXT_DATA_KEY_PROJECT) if loop_data: loop_data.protocol_persistent.pop(agents_md_instructions, None) loop_data.protocol_persistent.pop(project_instructions, None) if project_name: project_vars projects.build_system_prompt_vars(project_name) if loop_data and project_vars.get(include_agents_md, True): agents_md_protocol projects.build_agents_md_protocol(project_name) if agents_md_protocol: loop_data.protocol_persistent[agents_md_instructions] agents_md_protocol if loop_data and project_vars.get(project_instructions): loop_data.protocol_persistent[project_instructions] agent.read_prompt( agent.protocol.projects.instructions.md, **project_vars ) result \n\n agent.read_prompt(agent.system.projects.active.md, **project_vars) else: result \n\n agent.read_prompt(agent.system.projects.inactive.md)其行为可拆解为四步先渲染 prompts/agent.system.projects.main.md 作为 project 分段的骨架从上下文取当前项目名CONTEXT_DATA_KEY_PROJECT并在每轮先清空protocol_persistent中上一轮遗留的agents_md_instructions与project_instructions保证提示词协议不跨轮残留若处于活跃项目通过 helpers/projects.py 的build_system_prompt_vars构造项目变量把项目 AGENTS.md 的路径链指引build_agents_md_protocol受include_agents_md开关控制与项目指令正文渲染 prompts/agent.protocol.projects.instructions.md写入loop_data.protocol_persistent成为prompt protocol的一部分系统提示词本身只追加渲染 prompts/agent.system.projects.active.md 得到的项目元数据与稳定规则无活跃项目时追加 prompts/agent.system.projects.inactive.md 的非活跃项目占位提示。这一设计正是文档所述系统提示词保留项目元数据与稳定项目规则、动态指令走 protocol的落地实现。四、本地契约顺序性、密钥掩码与有界性DOX 文档的Local Contracts定义了三条必须遵守的本地契约它们都有对应的源码机制支撑1. 保持顺序Preserve orderingPreserve ordering where sections depend on earlier context.系统提示词分段之间存在上下文依赖例如 tools 分段引用agent.system.tool.*.md模板时依赖 main 分段确立的角色上下文secrets 分段依赖 settings 变量。六个构建器通过数字文件名前缀_10_、_11_、_12_、_13_、_14_保证确定性加载顺序这一点与 extensions/python/AGENTS.md 中Preserve numeric prefixes when ordering affects prompt construction的约定一致helpers/extension.py的_get_extension_classes也按文件名排序后执行从机制上保证顺序稳定。因此新增分段时必须依据其在提示词中的逻辑位置选择合适的数字前缀。2. 密钥相关分段必须掩码且范围化Keep secret-related prompt sections masked and scoped.正如 3.4 节所述secrets 分段只注入get_secrets_for_prompt()返回的白名单子集并在渲染 prompts/agent.system.secrets.md 后配合tool_execute_before/after、util_model_call_before等扩展点实现用前解掩、用后回掩避免密钥常驻提示词与历史记录。3. 提示词添加必须有界且兼容工具调用契约Prompt additions must be bounded and compatible with tool-call contracts.skills 分段对技能名与描述做 100 字符截断、MCP 无配置即跳过、工具模板按agent.system.tool.*.md统一模式收集都是有界的体现而所有工具说明最终统一渲染进 prompts/agent.system.tools.md保证与fw.tool_result、fw.tool_not_found等工具调用反馈框架见 prompts/ 下的fw.*.md模板格式兼容。五、工作指引与验证方式DOX 文档的Work Guidance要求协调系统提示词的跨模块变更——由于 system prompt 影响面广任何改动都要与 profilesAgent 配置、skills、tools、plugins 以及提示词相关测试保持同步避免出现提示词变了但工具契约没跟上的撕裂。Verification则给出了两条验证路径人工检查在运行中查看渲染后的完整系统提示词确认各分段顺序、内容与掩码状态正确自动化测试运行提示词构建相关测试。仓库 tests/test_prompt_protocol.py 即针对 prompt protocol含 project 指令注入的专项测试类似的还有 tests/test_default_prompt_budget.py、tests/test_response_tool_validation.py 等对提示词与工具契约的校验。另外helpers/extension.py 的register_extensions_watchdogs会为extensions/python、usr/extensions、agents/*/extensions及项目级扩展目录注册文件系统 watchdog扩展文件变更即自动清空扩展类缓存并重新加载因此调试提示词分段时可以热更新无需重启进程。六、如何新增或覆盖一个提示词分段基于上述架构在 Agent Zero 中扩展系统提示词有三种途径追加新分段在extensions/python/system_prompt/或用户级usr/extensions/system_prompt/、Agent 级agents/name/extensions/system_prompt/新建一个带数字前缀的 Python 文件定义一个继承Extension的类在execute中调用agent.read_prompt(模板名.md, **kwargs)构造文本并system_prompt.append(...)。数字前缀决定其在提示词中的位置。覆盖内置分段在优先级更高的扩展目录放置同名文件helpers/extension.py的合并逻辑会以首个出现的文件名为准实现分段级替换也可以直接通过extensible的隐式_functions/module/qualname/start|end扩展点在既有build_prompt前后改写结果。新增模板把提示模板放入某个 Agent 的prompts目录或放入项目级 prompt 目录subagents.get_paths会自动覆盖聚合路径tools 分段会通过agent.system.tool.*.md模式自动发现新工具模板。结语extensions/python/system_prompt/是 Agent Zero 系统提示词工程的组装车间入口 agent.py 的get_system_prompt触发system_prompt扩展点六个按数字前缀排序的构建器_10_main_prompt.py、_11_tools_prompt.py、_12_mcp_prompt.py、_13_secrets_prompt.py、_13_skills_prompt.py、_14_project_prompt.py分别负责 main、tools、MCP、secrets、skills、project 六大分段。其设计精髓在于以文件系统布局表达所有权、以数字前缀保证顺序、以空串返回实现按需注入、以 protocol_persistent 分离稳定规则与动态指令、以掩码与截断守住安全与上下文预算。理解这套架构后无论是排查提示词异常、定制 Agent 行为还是为项目新增能力分段都能在清晰的契约框架内高效完成。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考