ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Agent Zero 的 Prompt Include 机制:把持久化行为规则自动注入系统提示词的完整实现解析

Agent Zero 的 Prompt Include 机制:把持久化行为规则自动注入系统提示词的完整实现解析 Agent Zero 的 Prompt Include 机制把持久化行为规则自动注入系统提示词的完整实现解析【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文围绕 Agent Zero 中_promptinclude插件的行为提示模板 agent.system.promptinclude.md 展开完整解读这份模板向 Agent 下发的持久化记忆行为规范并结合 scanner.py 的扫描实现与 default_config.yaml 的默认配置讲清*.promptinclude.md文件是如何被递归发现、预算裁剪并最终拼装进系统提示词的。读完本文你可以掌握该机制的完整数据流、全部配置参数及其源码级行为并能正确区分 promptinclude、memory 工具与 behaviour_adjustment 三者的适用边界。一、Prompt Include 解决什么问题在 Agent Zero 这类框架中模型每轮对话都依赖系统提示词system prompt来约束行为。用户经常会提出“以后这个项目都要用中文注释”“记住我偏好的代码风格”这类跨会话持久化的要求。Agent Zero 用三条互补的通道处理它们而 promptinclude 插件正是其中最贴近“文件系统”的一条promptinclude 文件工作目录workdir下匹配*.promptinclude.md的 Markdown 文件在每次组装系统提示词时被自动扫描、注入天然跨会话持久memory 工具处理用户显式的“记住这个 / 忘了那个”类请求behaviour_adjustment处理用户显式提出的持久化行为、人格、风格、问候语或精确响应规则。这个分工不是文档里的口头约定而是被直接写进提示模板中下发给模型的“元规则”下文第三节将逐条解读。二、整体架构插件、扫描器与提示模板的协作从插件元数据 plugin.yaml 看_promptinclude的核心定位一句话概括即“Persistent behavioral rules and preferences auto-injected into system prompt.”持久化行为规则与偏好自动注入系统提示词。它声明settings_sections: [agent]并支持per_project_config: true与per_agent_config: true也就是说该插件的配置既可以按项目、也可以按 Agent 分别覆盖。插件内部职责划分清晰参见 AGENTS.md 的 DOX 说明helpers/scanner.py负责工作区扫描、gitignore 过滤、token 预算与裁剪prompts/负责提示片段本身包括本文的核心模板extensions/负责把扫描结果注入系统提示词的钩子default_config.yaml、plugin.yaml、webui/负责默认值、元数据与设置界面。数据流可以概括为四步解析扫描根目录extensions/python/system_prompt/_16_promptinclude.py 中的_resolve_workdir先判断当前是否处于项目上下文——若是项目则取该项目的文件夹开发模式下还会经files.normalize_a0_path归一化路径否则回退到全局设置中的workdir_path读取插件配置通过plugins.get_plugin_config(_promptinclude, agentself.agent)取得当前作用域的配置缺省时逐项回退到默认值默认值与 default_config.yaml 完全一致执行扫描在 scanner.py 的scan_promptinclude_files中完成文件发现与预算裁剪该调用经runtime.call_development_function发起见 扩展钩子渲染提示模板把扫描结果格式化后连同name_pattern一起填入本文核心的行为提示模板追加到system_prompt列表中。三、核心模板逐条解读行为提示片段的内容agent.system.promptinclude.md 全文不长但每一行都是对模型行为的硬性约束等价于给模型下达的“关于持久化文件的操作手册”。按原文顺序完整解读如下模板原文规则含义{{name_pattern}} files in workdir auto-injected into system prompt告知模型工作目录中匹配{{name_pattern}}默认*.promptinclude.md的文件会被自动注入系统提示词。{{name_pattern}}是模板变量由扩展钩子在渲染时注入因此模型看到的永远是当前生效的实际 patterncreate/edit/delete persist across conversations这些文件的创建、编辑、删除都会跨会话持久生效——这是选择“文件通道”而非口头承诺的核心理由preference changes, instruction files, project notes, and prompt includes persist via text_editor before responding当用户要求变更偏好、指令文件、项目笔记或提示包含内容时Agent必须先通过 text_editor 工具把变更落盘然后再回复用户explicit memory requests like remember this, what did I ask you to remember, or forget this use memory tools, not promptinclude files, unless the user asks to edit a file显式记忆请求“记住这个”“我之前让你记了什么”“忘掉这个”应走 memory 工具而不是 promptinclude 文件除非用户明确要求编辑文件explicit durable behavior, personality, style, greeting, or exact-response rule requests use behaviour_adjustment, not promptinclude files, unless the user asks to edit a file显式的持久化行为、人格、风格、问候语或精确响应规则请求应走 behaviour_adjustment 通道同样除非用户点名要改文件never just acknowledge durable project/instruction changes verbally; persist them to file when the user asks for a file/instruction/preference change禁止“嘴上答应”用户提出文件/指令/偏好变更时绝不能只做口头确认必须真正持久化到文件use promptinclude files for persistent project context, reference instructions, and user-authored prompt include files明确 promptinclude 文件的正当用途持久化项目上下文、参考性指令、用户亲笔编写的提示包含文件recursive search alphabetical by full path告知模型扫描语义递归搜索、按完整路径字母序排列——这与 scanner.py 中matched.sort()的实现一一对应{{if includes}} ... {{endif}}条件块仅当存在被包含文件时才渲染### includes小节及其内容这套规则的设计意图值得注意它同时回答了“什么情况下该用什么通道”和“如何避免虚假承诺”两个问题。前者是路由规则memory vs behaviour_adjustment vs 文件后者是执行规则persist before responding、never just acknowledge。把这两类约束前置到系统提示词中可以显著减少 Agent“口头答应记住、实际什么都没做”的失败模式。条件渲染includes 小节模板尾部的条件块{{if includes}} ### includes !!! obey all rules preferences instructions below {{includes}} {{endif}}意味着只要扫描到一个或多于一个有效文件系统提示词中就会出现一个### includes小节并以!!! obey all rules preferences instructions below强制模型把下方内容视为必须遵守的规则、偏好与指令。若工作目录中不存在任何匹配文件且没有因预算被跳过的文件扩展钩子会以空includes渲染该模板见 无结果分支此时条件块不展开提示词只保留规则说明部分。四、扫描器实现发现、过滤与三级预算scan_promptinclude_files 是整个机制的执行核心其签名与默认值即为该功能的“参数契约”def scan_promptinclude_files( root: str, *, name_pattern: str *.promptinclude.md, max_depth: int 10, max_file_tokens: int 2000, max_file_count: int 50, max_total_tokens: int 8000, gitignore: str , ) - ScanResult返回的ScanResult包含两部分filesFileEntry列表每项含path、content、token_count、status与skipped_count。status是ok/cropped/skipped三态之一用于在提示词中向模型如实标注每个文件的注入状态。4.1 递归搜索与字母序_find_matching_files 用os.walk自顶向下遍历逐层检查depth max_depth时清空dirnames停止深入文件名通过fnmatch.fnmatch(fname, name_pattern)匹配这也是name_pattern可以是任意 glob 而非固定后缀的原因。匹配结果经matched.sort()排序即模板中“recursive search alphabetical by full path”承诺的按完整路径字母序。4.2 gitignore 感知过滤gitignore 内容经 _build_ignore_spec 转换为pathspec.PathSpecgitwildmatch 语法。过滤发生在两个层面目录级原地剪枝遍历时对dirnames就地过滤被忽略的目录整个子树不再进入避免无谓 I/O文件级检查单个文件若命中忽略模式也被跳过。默认配置 default_config.yaml 内置了一份面向 Python/Node 项目的忽略清单venv/**、**/__pycache__/**、**/node_modules/**、**/.npm/**、**/.git/**、**/.conda/**、**/.cache/**、**/dist/**、**/build/**、**/.tox/**、**/.eggs/**、**/*.egg-info/**保证虚拟环境、依赖目录、构建产物中的误命名文件不会污染提示词。4.3 三级 token 预算与裁剪策略预算控制是该实现最有工程价值的部分共三层防线文件数量上限max_file_count默认 50达到上限后剩余文件计入skipped_count单文件上限max_file_tokens默认 2000超长文件用tokens.trim_to_tokens(raw, max_file_tokens, directionstart)截断状态记为cropped总预算max_total_tokens默认 8000这是最精细的一层。扫描器逐文件累计total_tokens_used每次先估算“路径行本身”的开销path_tokens tokens.count_tokens(path) 55 为格式化开销预留。若加入当前文件会超总预算则尝试部分装入当剩余空间remaining 50token 时按剩余空间从头部截断装入该文件状态cropped剩余空间不足 50 token 时该文件记为skipped且内容留空。一旦总预算耗尽即置budget_exhausted True后续文件全部跳过。这种“能塞一半也塞一半、但要留痕”的策略配合状态字段让模型能明确知道哪些内容被裁过、哪些文件因预算没进来——提示词注入对模型是透明的。4.4 渲染为提示词块扫描完成后_format_includes 把每个FileEntry渲染为一个块。ok/cropped状态的文件经模板 fw.promptinclude.includes.md 包装{{path}}{{suffix}}三反引号包裹的{{content}}其中裁剪文件的路径行带!!! cropped to fit后缀被跳过文件直接渲染为{path} !!! skipped to fit。若skipped_count 0末尾追加一行!!! {skipped_count} more files skipped to fit把“还有 N 个文件没装进来”这一事实也如实告知模型。五、配置参数全表默认值、UI 取值范围与源码行为所有参数都可在 Web 设置界面webui/config.html中调整且支持按项目/按 Agent 覆盖per_project_config/per_agent_config均为 true。下表汇总参数全貌参数默认值UI 取值范围源码中的行为name_pattern*.promptinclude.md任意 glob 文本fnmatch.fnmatch匹配文件名同时作为模板变量注入行为提示模型会看到当前 patternmax_depth101–50os.walk中depth max_depth即停止下探max_file_tokens2000100–20000单文件 token 上限超出部分按directionstart截断状态croppedmax_file_count501–200最多注入的文件数其余计入skipped_countmax_total_tokens8000500–50000全部文件的总预算耗尽前会尝试部分装入剩余 50 token 时截断装入gitignore内置 Python/Node 忽略清单见上文多行文本编译为pathspecgitwildmatch 规格目录级剪枝 文件级过滤扩展钩子在 execute 中对每个参数都做了config.get(key, default)兜底因此即使项目级配置缺省某个键扫描仍会以默认值运行行为可预测。六、注入时机与边界条件从 execute 的实现看还有几个值得注意的边界行为无扫描根目录即静默退出_resolve_workdir返回空时不做任何注入扫描结果是纯函数、无 Agent 依赖scanner.py 头部注释明确“No agent/tool dependencies”意味着扫描逻辑可以脱离运行时独立调用与测试——这也解释了插件 DOX 中“scanner changes after: smoke-test include, ignore, crop, and over-budget cases”的验证要求项目上下文优先处于项目会话中时扫描项目文件夹而非全局 workdir因此同一个 promptinclude 文件的“生效范围”取决于它放在哪里——放在项目目录内的文件只在该项目会话中被注入模板渲染走agent.read_prompt提示文本不是硬编码在 Python 里而是经模板引擎渲染name_pattern与includes两个变量动态填充这保证了行为规则与实际扫描语义永远一致。七、实践建议什么时候该写 promptinclude 文件依据模板下发的路由规则可归纳为如下决策表用户诉求正确通道“这个项目以后都用 pytest 而不是 unittest写进项目规则”创建/编辑*.promptinclude.mdtext_editor 落盘后再回复“记住我的邮箱是 xy.com” / “忘掉我刚才说的”memory 工具“以后回复都要先说‘好的’” / 人格、问候语调整behaviour_adjustment用户明说“把这个写进那个提示文件里”即便形似记忆/行为请求也照用户要求编辑文件一条经验法则凡是“应该长期存在、可被版本管理、随项目走”的上下文就是 promptinclude 文件的用武之地而它 8000 token 的总预算和 2000 token 的单文件上限也提醒使用者把文件写得精炼——超预算的内容会被裁剪甚至丢弃且模型会看到裁剪标注。八、小结Agent Zero 的_promptinclude机制用一个 15 行的行为模板agent.system.promptinclude.md加一个无依赖的纯函数扫描器scanner.py实现了一条“文件系统即提示词”的持久化通道*.promptinclude.md文件经 gitignore 过滤、字母序排序、三级 token 预算裁剪后以带路径溯源的状态化块注入系统提示词并由模板中的元规则约束模型正确路由 memory、behaviour_adjustment 与文件三条通道。对使用者而言理解了配置参数的预算语义与三条通道的边界就能可靠地让 Agent 的偏好与项目指令跨会话生效。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表