企业官网建设流程全解析

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 Include
• Description: Persistent behavioral rules and preferences auto-injected into system prompt
• Settings 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 = "", ) -> ScanResult

1. 工作区扫描：深度受限的递归匹配

内部辅助函数_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.yaml）：

gitignore: | 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, direction="start")从文件开头保留前段并追加省略号，状态标记为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 安全系数”的近似裁剪，direction="start"表示保留开头部分——即被裁掉的永远是文件尾部内容。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: int

• ok：文件完整纳入；
• cropped：被单文件上限或总预算部分裁剪；
• skipped：预算内连该文件都装不下（content为空、token_count为 0）。

循环结束后还有一段兜底：matched列表中未被显式处理（既不在result_files也不在skipped_count内）的文件也会被补计进skipped_count，保证“纳入数 + 跳过数 = 匹配数”的账目一致。

注入链路：扩展点如何把扫描结果写进系统提示词

扫描只是第一步，真正把内容写进提示词的是系统提示词扩展 _16_promptinclude.py 中的PromptInclude.execute。其调用链为：

1. 通过plugins.get_plugin_config("_promptinclude", agent=self.agent)读取插件配置（受 per-project / per-agent 覆盖影响）；
2. 通过_resolve_workdir确定扫描根目录：若当前上下文存在激活项目，则以项目文件夹为根（开发模式下先做normalize_a0_path归一化）；否则回退到全局设置的workdir_path——这意味着“项目内规则跟项目走”；
3. 通过runtime.call_development_function在受控环境中执行scan_promptinclude_files，六个配置参数逐一从插件配置读取（缺省值与 default_config.yaml 一致）；
4. 将结果渲染进提示词模板并追加到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 fit`，`cropped` 条目路径后追加 ` !!! 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.md`；Agent 自身在用户要求变更持久偏好时，应使用 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