Agent Zero Prompt Include 插件实战用 *.promptinclude.md 文件把持久行为规则自动注入系统提示词【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文以 Agent Zero 内置的Prompt Include插件文档为主体完整讲清它如何从工作区扫描*.promptinclude.md文件、应用 gitignore 风格过滤与 token 预算裁剪并把收集到的规则自动注入系统提示词结合仓库源码逐参数剖析扫描器 scanner.py 的预算分配逻辑、注入扩展 _16_promptinclude.py 的调用链以及默认配置 default_config.yaml 的全部字段帮助读者掌握“文件即提示词”这一持久化偏好管理机制的落地与调优方法。插件定位从项目文件自动注入持久行为规则Prompt Include 的核心价值只有一句话自动从项目文件中把持久性的行为规则与偏好注入系统提示词。它扫描工作区中所有*.promptinclude.md文件应用 gitignore 感知的过滤与 token 预算并将收集到的内容交给提示词注入环节从而让用户手工维护的规则文件能够跨会话持久生效——创建、编辑或删除这些文件即可改变 Agent 的持久行为无需每次对话重复说明。插件的元信息定义在 plugin.yaml 中Name:_promptinclude下划线前缀表示框架内置插件Title:Prompt IncludeDescription: Persistent behavioral rules and preferences auto-injected into system promptSettings section:agent设置页归属于 agent 分区Per-project config:true支持按项目覆盖配置Per-agent config:true支持按 Agent 覆盖配置工作流程从目录遍历到结构化扫描结果插件的主行为可拆为四个环节工作区扫描、忽略过滤、预算裁剪、结构化输出。它们全部实现在 scanner.py 的公共函数scan_promptinclude_files中该函数刻意不依赖任何 agent/tool便于单测与复用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 , ) - ScanResult1. 工作区扫描深度受限的递归匹配内部辅助函数_find_matching_files用os.walk自顶向下遍历目录树对每一层计算相对根目录的深度一旦depth max_depth就清空子目录不再深入对文件名用fnmatch.fnmatch与name_pattern默认*.promptinclude.md做 glob 匹配。匹配完成后会先matched.sort()再逐个处理因此注入顺序是“按完整路径的字母序”的确定性顺序——这一点也被提示词模板显式声明为 recursive search alphabetical by full path。2. 忽略支持gitignore 风格的路径过滤_build_ignore_spec接收一段 gitignore 风格文本剔除空行与#注释行后交给pathspec库的PathSpec.from_lines(gitwildmatch, lines)构建匹配器。过滤在遍历过程中就地生效目录级别被忽略的目录直接从dirnames中剔除整个子树不再被访问文件级别相对路径统一转为 POSIX 分隔符匹配忽略规则则跳过。默认配置中的忽略清单覆盖了常见噪声目录见 default_config.yamlgitignore: | venv/** **/__pycache__/** **/node_modules/** **/.npm/** **/.git/** **/.conda/** **/.cache/** **/dist/** **/build/** **/.tox/** **/.eggs/** **/*.egg-info/**3. 预算化纳入单文件上限、总预算与“部分装入”裁剪扫描器对每个候选文件依次执行三段预算判断这是它区别于普通文件收集器的关键设计a总预算预检。每个文件先估算“路径行自身”的 token 成本tokens.count_tokens(path) 5的格式化开销。若加上它就已超出max_total_tokens后续文件不再处理budget_exhausted被置位其余全部计入skipped_count。b单文件上限。每个文件的计入 token 数被截断为min(file_tokens, max_file_tokens)。若超出上限用 helpers/tokens.py 的trim_to_tokens(raw, max_file_tokens, directionstart)从文件开头保留前段并追加省略号状态标记为cropped。c部分装入partial fit。若完整文件装不进剩余总预算扫描器会计算剩余配额remaining max_total_tokens - total_tokens_used - path_tokens只要remaining 50就把文件裁到该配额内纳入状态cropped否则记为一个 0 token 的skipped条目。无论哪种情况装入部分文件后即触发budget_exhausted保证总预算永不击穿。trim_to_tokens的实现见 helpers/tokens.py采用“字符数按 token 比例换算并乘 0.8 安全系数”的近似裁剪directionstart表示保留开头部分——即被裁掉的永远是文件尾部内容。token 计数本身基于 tiktoken 的cl100k_base编码count_tokens与实际模型精确用量存在偏差因此才有 0.8 的TRIM_BUFFER兜底。d文件数量上限。已纳入文件数达到max_file_count默认 50后剩余文件同样计入跳过。此外读取失败OSError/IOError或内容为空raw.strip()为空的文件会被静默跳过不占用预算。4. 结构化扫描结果函数返回ScanResult即“文件列表 跳过计数”class FileEntry(TypedDict): path: str content: str token_count: int status: Literal[ok, cropped, skipped] class ScanResult(TypedDict): files: list[FileEntry] skipped_count: intok文件完整纳入cropped被单文件上限或总预算部分裁剪skipped预算内连该文件都装不下content为空、token_count为 0。循环结束后还有一段兜底matched列表中未被显式处理既不在result_files也不在skipped_count内的文件也会被补计进skipped_count保证“纳入数 跳过数 匹配数”的账目一致。注入链路扩展点如何把扫描结果写进系统提示词扫描只是第一步真正把内容写进提示词的是系统提示词扩展 _16_promptinclude.py 中的PromptInclude.execute。其调用链为通过plugins.get_plugin_config(_promptinclude, agentself.agent)读取插件配置受 per-project / per-agent 覆盖影响通过_resolve_workdir确定扫描根目录若当前上下文存在激活项目则以项目文件夹为根开发模式下先做normalize_a0_path归一化否则回退到全局设置的workdir_path——这意味着“项目内规则跟项目走”通过runtime.call_development_function在受控环境中执行scan_promptinclude_files六个配置参数逐一从插件配置读取缺省值与 default_config.yaml 一致将结果渲染进提示词模板并追加到system_prompt。两种提示词模板与注入文本形态插件自带两个模板位于 plugins/_promptinclude/prompts/agent.system.promptinclude.md系统提示词的主体段落。除声明“{{name_pattern}}文件自动注入、跨会话持久”外它还内嵌了使用守则值得注意用户变更偏好、指令文件、项目笔记时Agent 应用 text_editor 持久化到文件而非口头应承明确的记忆类请求remember this、forget this应走 memory 工具除非用户明确要求编辑文件明确的持久行为/人格/风格/精确回复规则应走behaviour_adjustment仅当有includes时才渲染### includes小节并附 !!! obey all rules preferences instructions below 的服从声明。fw.promptinclude.includes.md单个文件的渲染块形态为路径 可选后缀 代码围栏包裹的正文{{path}}{{suffix}}{{content}}在 _format_includes 中skipped 条目渲染为 路径 !!! skipped to fitcropped 条目路径后追加 !!! cropped to fit若还有 skipped_count 个文件因预算被丢弃末尾追加一行 !!! N more files skipped to fit。因此最终系统提示词里**每条规则都清晰归属于它的源文件裁剪与丢弃都有显式标记**模型可以据此理解自己看到的规则是否完整。 ## 配置参考六个参数及其取值范围 | 参数 | 默认值 | Web UI 允许范围 | 作用 | |---|---|---|---| | name_pattern | *.promptinclude.md | 文本输入 | 参与扫描的文件 glob 模式 | | max_depth | 10 | 1–50 | 递归搜索的最大目录深度 | | max_file_tokens | 2000 | 100–20000 | 单文件 token 上限超出部分裁剪 | | max_file_count | 50 | 1–200 | 纳入文件数量上限 | | max_total_tokens | 8000 | 500–50000 | 所有文件合计的总 token 预算 | | gitignore | 见上文默认清单 | 多行文本 | gitignore 风格过滤模式 | 以上默认值同时出现在三处且保持一致[default_config.yaml](https://link.gitcode.com/i/bac42b1c0d0654e72f22093af5e75bc0)、[scanner.py](https://link.gitcode.com/i/b7ea23dc71fe20b9e1731537e22a73e3) 的函数签名默认值、以及 [\_16\_promptinclude.py](https://link.gitcode.com/i/a0aab49a47e4cae4985dcaed7106f9de) 中 config.get 的兜底值。设置界面定义在 [config.html](https://link.gitcode.com/i/f24ff530ae1e0380b6748cf1641aa0e5)在 Settings 的 agent 分区提供六个字段的编辑表单由于 plugin.yaml 声明了 per_project_config: true 与 per_agent_config: true每个项目和每个 Agent 都可以各自覆盖这些默认值。 ## 实战用法让规则跨会话生效 基于源码行为可以给出可复现的使用方式 1. **放置规则文件**在当前项目目录或全局 workdir任意层级创建如 conventions.promptinclude.md用自然语言写明希望 Agent 始终遵守的规则编码约定、回复风格、项目背景等。只要文件名匹配 name_pattern 且不在忽略清单内下次会话启动构建系统提示词时即被自动纳入。 2. **组织多项目**规则文件跟随项目根目录走。例如每个子项目放一份项目专属规则深度不超过 max_depth 即可被发现注意排序按完整路径字母序重要规则可放靠前的目录/文件名以保证在预算紧张时优先装入。 3. **控制膨胀**单文件超过 2000 token 会从尾部裁剪全部文件合计超过 8000 token 时靠后的文件会先被“部分装入”、再被整体跳过且提示词中会留下 skipped to fit 标记。若你的规则较多可通过项目级配置调大 max_total_tokens上限 50000。 4. **验证注入结果**观察系统提示词中 ### includes 小节——每个文件路径后应跟随其内容围栏块出现 !!! cropped to fit 说明该文件被裁剪可据此精简文件。 5. **与记忆机制的分工**按模板内嵌的守则一次性“记住 X”类请求走 memory 工具可复用、可版本化的项目规则才写入 *.promptinclude.mdAgent 自身在用户要求变更持久偏好时应使用 text_editor 落盘到文件而非仅口头确认。 ## 小结 Prompt Include 插件用一条清晰的文件契约——*.promptinclude.md——把“持久行为规则”从对话记忆变成了工作区中的普通文本文件扫描器以 gitignore 过滤 单文件/总量 token 双预算保证注入成本可控且账目可审计注入扩展以路径归属 裁剪/跳过显式标记保证模型对规则完整性的感知。配置集中在 [default_config.yaml](https://link.gitcode.com/i/bac42b1c0d0654e72f22093af5e75bc0)默认值、[plugin.yaml](https://link.gitcode.com/i/f15affeb260f1371991d722cc2f175cc)元数据与配置作用域和 [webui/config.html](https://link.gitcode.com/i/f24ff530ae1e0380b6748cf1641aa0e5)设置界面三处核心算法全部收敛在 [scanner.py](https://link.gitcode.com/i/b7ea23dc71fe20b9e1731537e22a73e3) 一个无外部依赖的函数里适合作为理解 Agent Zero 插件机制插件配置 → 扩展点 → 提示词模板的一个完整样本。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
