Agent Zero 消息循环提示词构建链路解析message_loop_prompts_after 扩展点全解【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文深入剖析 Agent ZeroAGENTS.md 所定义的message_loop_prompts_after扩展点在主消息循环提示词prompt构建阶段之后以确定性顺序执行六个后端 Python 扩展统一负责当前时间、相关技能提示、已加载技能历史重挂、Agent 信息、并行任务状态、工作目录结构六大类内容的注入与重挂。读完本文你将掌握该扩展点的文件组织、每个钩子的实现细节与参数语义、提示词模板的装配方式以及如何基于源码验证与调试提示词构建结果。一、扩展点定位它在消息循环中处于什么位置在 Agent Zero 的extensions/python/目录下每个直接子目录对应一个命名的扩展点extension pointPython 扩展按文件名确定性顺序加载执行见 extensions/python/AGENTS.md。与主消息循环提示词构建相关的有两个相邻扩展点message_loop_prompts_before/提示词构建前的门控gating逻辑message_loop_prompts_after/围绕主消息循环提示词构建负责提示词协议prompt protocol、提示词附加内容prompt extras与历史重挂history reattachment。message_loop_prompts_after的职责边界非常清晰摘自 AGENTS.md 的 Purpose 一节Own prompt protocol, prompt extras, and history reattachment around primary message-loop prompt construction.即它拥有主提示词构建周边的一切附加信息注入——不修改系统提示词本身而是在loop_data.extras_temporary中按顺序填充各类附加内容并负责把因历史压缩compaction而丢失的已加载技能正文重新挂回工具结果历史。二、六个钩子的确定性执行顺序该扩展点下的文件以数字前缀命名加载顺序即文件名排序顺序且顺序有严格语义后执行的附加内容可能依赖前面已完成的技能召回或加载结果Local Contracts 中的 Preserve ordering where later prompt extras depend on earlier recall or load results。序号文件类名职责60_60_include_current_datetime.pyIncludeCurrentDatetime注入当前日期时间63_63_recall_relevant_skills.pyRecallRelevantSkills按原始用户消息召回相关技能65_65_include_loaded_skills.pyIncludeLoadedSkills已加载技能清单维护与正文重挂70_70_include_agent_info.pyIncludeAgentInfo注入 Agent 编号、Profile、LLM 与预设72_72_include_parallel_jobs.pyIncludeParallelJobs注入并行任务状态75_75_include_workdir_extras.pyIncludeWorkdirExtras注入工作目录文件结构每个类均继承helpers.extension.Extension基类见 helpers/extension.py实现async def execute(self, loop_data: LoopData LoopData(), **kwargs)方法。钩子通过call_extensions_async在对应扩展点目录下收集全部Extension子类并按模块文件名排序执行同名文件在合并时首次出现者覆盖_get_extension_classes中first ocurrence of file name is the override这为自定义 Agent/Project 层覆盖内置实现提供了机制。下面逐一拆解六个钩子的实现。三、钩子详解六大内容注入的源码级实现3.1_60_include_current_datetime.py注入当前日期时间实现要点current_datetime Localization.get().now().strftime(%Y-%m-%d %H:%M:%S %Z) datetime_prompt self.agent.read_prompt(agent.system.datetime.md, date_timecurrent_datetime) loop_data.extras_temporary[current_datetime] datetime_prompt时间来源是helpers.localization.Localization.get().now()格式化格式为%Y-%m-%d %H:%M:%S %Z如2026-09-13 05:13:51 UTC模板为 prompts/agent.system.datetime.md内容强调依赖此信息始终为最新rely on this info always up to date引导模型以注入时间为准而非训练截止时间结果写入loop_data.extras_temporary[current_datetime]作为临时附加内容参与本次循环的提示词装配。3.2_63_recall_relevant_skills.py基于原始用户消息的技能召回该钩子只会在消息循环的第一轮loop_data.iteration ! 0时直接返回执行其关键契约是召回应检索原始用户消息而非渲染后的历史包装Relevant-skill recall should search the raw user message when available, not the rendered history wrapper。实现要点content loop_data.user_message.content if loop_data.user_message else if isinstance(content, dict): user_instruction str(content.get(user_message) or ).strip() else: user_instruction loop_data.user_message.output_text().strip() if len(user_instruction) 8: return matches skills_helper.search_skills(user_instruction, limit6, agentself.agent)对user_message.content兼容 dict 形态取user_message键与普通文本形态再统一.strip()指令长度少于 8 个字符直接跳过召回避免过短输入产生噪声匹配召回上限 6 条limit6命中后每条技能名截断至 100 字符、描述截断至 220 字符超出以省略号结尾保证注入内容有界bounded模板 prompts/agent.system.skills.relevant.md 的说明引导模型若当前请求依赖其中某个技能应先通过skills_tool的load动作加载再执行结果写入loop_data.extras_temporary[relevant_skills]。注意该钩子只提供技能线索不写入技能正文——这正是 Ownership 中 Skills must not write selected or loaded skill bodies into protocol or extras 的体现。3.3_65_include_loaded_skills.py已加载技能的台账维护与历史重挂这是六个钩子中逻辑最复杂的负责处理显式加载技能正文的持久化与压缩后重挂问题。其设计前提是Explicitly loaded skill bodies belong in tool-result history with metadata so they can survive persistence and be reattached after compaction.即技能正文平时存在于工具结果历史tool-result history中并携带元数据以便在历史压缩后能够被重新挂回。该钩子只负责保持台账干净 恢复被压缩隐藏的正文。核心常量与流程SKILL_REATTACHMENT_TOKEN_BUDGET 12_000 SKILL_REATTACHMENT_HEADER Reattached loaded skill instructions after history compaction.通过skills.get_loaded_skill_names(self.agent)获取当前会话显式加载的技能名清单逐个用skills.find_skill(skill_name, agentself.agent)校验技能仍可找到把仍有效的技能名通过skills.set_loaded_skill_names(self.agent, visible_skill_names)写回台账——由于已加载技能 ID 是聊天级上下文数据chat-wide context data而非 Agent 本地状态因此保存在 Agent 的上下文而非本地配置中调用_reattach_missing_skill_bodies完成重挂。重挂逻辑_reattach_missing_skill_bodiesvisible_skill_names _visible_skill_names(loop_data.history_output) # 扫描历史中已有 skill_instruction 元数据的消息 for skill in reversed(loaded_skills): if skill.name in visible_skill_names: continue # 正文仍在历史中可见跳过 skill_data skills.load_skill_for_agent(skill_nameskill.name, agentself.agent) message f{SKILL_REATTACHMENT_HEADER}\n\n{skill_data} if used_tokens approximate_tokens(message) SKILL_REATTACHMENT_TOKEN_BUDGET: continue # 超预算跳过保护上下文窗口 ... history_message self.agent.hist_add_tool_result( skills_tool, message, skill_instructions{name: skill.name, path: str(skill.path), source: skills_tool:reattach, content_included: True}, ) loop_data.history_output.extend(history_message.output())判定是否可见依据_visible_skill_names遍历loop_data.history_output用skills.skill_instruction_name(message)提取消息携带的skill_instructions元数据中的技能名重挂通过hist_add_tool_result以skills_tool工具结果的形式写回历史并携带skill_instructions元数据name、path、sourceskills_tool:reattach、content_includedTrue确保重挂内容在后续持久化/压缩中依然可被识别与再次重挂Token 预算硬上限 12,000SKILL_REATTACHMENT_TOKEN_BUDGET用helpers.tokens.approximate_tokens近似估算后累加超出即放弃后续技能避免重挂导致上下文溢出逆序遍历reversed(loaded_skills)并再次逆序写回reversed(selected)以保持技能加载顺序的语义稳定性。3.4_70_include_agent_info.py注入 Agent 身份信息from plugins._model_config.helpers.model_config import get_chat_model_config, get_effective_preset_name chat_cfg get_chat_model_config(self.agent) preset_name get_effective_preset_name(self.agent) agent_info_prompt self.agent.read_prompt( agent.extras.agent_info.md, numberself.agent.number, profileself.agent.config.profile or Default, llmchat_cfg.get(provider, ) / chat_cfg.get(name, ), presetpreset_name, ) loop_data.extras_temporary[agent_info] agent_info_prompt模型信息取自_model_config插件的get_chat_model_config/get_effective_preset_nameLLM 字符串格式为provider/name如openrouter/anthropic/claude-3.5-sonnet模板 prompts/agent.extras.agent_info.md 渲染 Agent Number、Profile、LLM且仅当存在有效预设时输出Active Preset行{{if preset}}条件块。3.5_72_include_parallel_jobs.py注入并行任务状态实现极简委托给 helpers 层extras await parallel_tools.build_parallel_jobs_extras(self.agent) if extras: loop_data.extras_temporary[parallel_jobs] extras并行任务状态由helpers.parallel_tools.build_parallel_jobs_extrashelpers/parallel_tools.py统一构建仅当有实际并行任务信息时才写入避免空内容污染提示词。3.6_75_include_workdir_extras.py注入工作目录文件结构该钩子区分项目模式与全局设置模式两条路径项目模式当前上下文处于某个项目内project_name projects.get_context_project_name(self.agent.context) project projects.load_basic_project_data(project_name) enabled project[file_structure][enabled] if not enabled: return max_depth project[file_structure][max_depth] gitignore_raw project[file_structure][gitignore] folder projects.get_project_folder(project_name) file_structure projects.get_file_structure(project_name)全局设置模式无项目上下文set settings.get_settings() if not set[workdir_show]: return max_depth set[workdir_max_depth]; max_files set[workdir_max_files] max_folders set[workdir_max_folders]; max_lines set[workdir_max_lines] gitignore_raw set[workdir_gitignore] folder set[workdir_path] file_structure str(file_tree.file_tree(scan_path, max_depth..., max_files..., max_folders..., max_lines..., ignoregitignore_raw, output_modefile_tree.OUTPUT_MODE_STRING))全局模式下实际扫描由helpers.file_tree.file_tree完成支持max_depth/max_files/max_folders/max_lines四重限制输出模式为字符串OUTPUT_MODE_STRING扫描路径不存在时会先files.create_dir(scan_path)两种模式共用cleanup_gitignore清洗忽略规则逐行去空白、剥离#行内注释、删除空行全部清空时输出占位符nothing ignored模板 prompts/agent.extras.workdir_structure.md 明确告知模型这是过滤后的概览而非全量扫描filtered overview not full scan需要时可自行list结果写入loop_data.extras_temporary[project_file_structure]。四、设计契约四条不可违背的本地约束AGENTS.md 的 Local Contracts 一节的四条约束是整个扩展点的行为红线注入内容有界且来源清晰Keep injected content bounded and clearly attributed每条附加内容都有明确模板、截断策略与 token 预算技能名 100 字符、描述 220 字符、重挂预算 12,000 token、文件树四重限制并写入命名清晰的extras_temporary键。保持执行顺序Preserve ordering后置附加内容可能依赖前置的召回或加载结果因此数字前缀顺序不可随意打乱。不得从工作目录附加内容泄露密钥或私有文件Do not expose secrets or private files from workdir extras文件结构依赖 gitignore 规则过滤且提示词明确标注为过滤概览。技能召回检索原始用户消息Relevant-skill recall should search the raw user message_63钩子直接读取loop_data.user_message.content而非渲染后的历史包装保证检索关键词与用户意图一致。此外extensions/python/AGENTS.md 还补充了扩展点通用约束扩展函数签名必须与钩子点传入参数匹配提示词构建相关顺序变更必须保留数字前缀扩展模块应保持轻量许多钩子运行在热路径上不得记录未脱敏的密钥、原始隐藏提示词段或私有用户数据。五、如何验证与调试渲染检查与测试AGENTS.md 的 Verification 一节给出的验证方式是Inspect rendered prompt protocol/history/extras or run prompt-construction tests after changes.对应到仓库中渲染检查六个钩子的产出都落在loop_data.extras_temporary键current_datetime、relevant_skills、agent_info、parallel_jobs、project_file_structure以及loop_data.history_output技能重挂结果中可通过观察最终发送给模型的消息协议/历史/附加段来核对测试验证提示词构建相关改动应运行对应的提示词/协议测试例如 tests/test_prompt_protocol.py、tests/test_default_prompt_budget.py、tests/test_skills_runtime.py 等若改动涉及系统提示词或启动迁移还需做一次启动冒烟检查对应 extensions/python/AGENTS.md 的建议。六、扩展与覆盖如何定制这套装配逻辑基于 helpers/extension.py 的加载机制message_loop_prompts_after是可以按 Agent / Project 层级覆盖的扩展点目录搜索路径由subagents.get_paths(agent, extensions/python, extension_point)决定覆盖内置extensions/python/、用户usr/extensions/及项目usr/projects/**/extensionshelpers/extension.py 中register_extensions_watchdogs注册的监控范围佐证同名文件模块名合并时首次出现者生效因此在用户层放置同名钩子文件即可覆盖内置行为文件变更由扩展监视器watchdog自动清理缓存extensions_changed清除_EXTENSIONS_CACHE_AREA与_CLASSES_CACHE_AREA改动即时生效无需重启。若需调整提示词文案而非逻辑可修改对应模板prompts/agent.system.datetime.md、prompts/agent.system.skills.relevant.md、prompts/agent.extras.agent_info.md、prompts/agent.extras.workdir_structure.md模板使用{{var}}占位符与{{if preset}}...{{endif}}条件块语法。七、小结message_loop_prompts_after是 Agent Zero 主消息循环提示词装配链路中的附加内容聚合层通过六个按序执行的轻量扩展把时间、技能线索、已加载技能正文、Agent 身份、并行状态与工作目录结构统一注入每次循环并配合 12,000 token 重挂预算与多重截断策略保持上下文有界。其正文进工具结果历史、ID 进聊天级上下文的设计使技能加载能够在持久化与压缩后可靠恢复——这既是理解 Agent Zero 提示词工程的关键入口也是自定义 Agent 行为时最常用的扩展点之一。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考