Potpie 全局 Agent 指令块解析global_agent_bundle 如何让 Codex 与 Claude 在任意仓库中复用项目记忆【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 通过一套打包的模板文件把“持久项目记忆”的使用纪律注入到各种 AI 编码 AgentCodex、Claude Code 等中其中 global_agent_bundle/AGENTS.md 是面向“文件型全局指令”机制的极简版全局指令块它会被合并进用户主目录下的~/.codex/AGENTS.md与~/.claude/CLAUDE.md让 Agent 在每个仓库、每次会话中都知道何时使用 Potpie、如何以最低开销检查 Context Graph 健康状态、以及只记录“可持久化”的学习。读完后你能理解这段 8 行指令的设计意图为何如此克制、它在源码中如何被合并进用户已有的指令文件而不覆盖用户内容以及它所引用的potpie --json source list与potpie --json graph status两条健康检查命令在 CLI 契约中的真实含义。一、它是什么一个“受管区块”而非独立文档先完整看一遍这个模板的全部内容potpie/cli/templates/global_agent_bundle/AGENTS.md!-- potpie-start -- Potpie is durable project memory: repo/source mappings, decisions, infra, changes, bugs, docs, and preferences for agents. Use it when it can materially help with repo context, prior decisions, architecture, bugs, or durable history. Do not run Potpie checks for simple QA or trivial edits. When useful, check mapping/graph health once per session (potpie --json source list, potpie --json graph status; skip if unavailable). Record only durable learnings. !-- potpie-end --它有三个关键特征首尾有受管标记整个正文被!-- potpie-start --与!-- potpie-end --包裹。这对标记是 Potpie 安装器识别“哪些内容是 Potpie 写入、可安全替换”的依据——用户自己在文件其他位置写的任何内容都不会被动到。极度精简全文只有 6 行实质指令与同目录下的姊妹模板如项目级的 agent_bundle/AGENTS.md形成鲜明对比。它是“全局”而非“项目”指令同一模板目录下还有 global_agent_bundle/CLAUDE.md内容与 AGENTS.md 逐字相同仅目标文件名不同。安装器源码中有一句注释直接说明了“为什么这么短”potpie/skills/installer.py#L442-L451def install_global_agent_instructions( root: str | Path, *, agent: str default, force: bool True, ) - InstallResult: Install compact global instructions for harnesses with file-based rules. The project bundle is intentionally detailed. This global bundle stays tiny because it can be loaded into every prompt across repositories. 也就是说项目级 bundleagent_bundle/AGENTS.md、claude_bundle/CLAUDE.md会被放进单个仓库可以详细地写 Views 表格、mutation JSON 示例、todo 驱动摄入流程而全局 bundle 会被放进用户主目录理论上随每个仓库的每次 prompt 一起被加载——因此必须小到“几乎不占上下文”只保留跨仓库通用的行为纪律。CLI 的 README 也把这一层定位为 “compact global instruction blocks inglobal_agent_bundle/”见 potpie/cli/README.md。二、安装目标哪些 harness 会收到这个文件全局指令块的安装入口是install_global_agent_instructions()potpie/skills/installer.py#L442-L471它按agent参数决定使用 bundle 中的哪个文件agent 取值落盘文件是否安装全局指令claudeCLAUDE.md是合并进~/.claude/CLAUDE.mddefault/codexAGENTS.md是合并进~/.codex/AGENTS.md其他—直接返回空结果不写入各 harness 的具体路径由 potpie/skills/targets.py 中的目标类定义ClaudeAgentTargetinstructions_root~/下的.claudeinstructions_agentclaudetargets.py#L152-L161CodexAgentTargetinstructions_root为.codexinstructions_agentcodexskills 根目录为~/.agents/skillstargets.py#L174-L183。这两个目标在install_support_files()中调用install_global_agent_instructions(self.instructions_root, agent..., forceTrue)targets.py#L70-L78完成受管区块的写入或刷新。CursorAgentTarget与OpenCodeAgentTarget没有instructions_root因此它们只安装 skills 目录下的SKILL.md不安装全局指令文件。这与 potpie/cli/README.md 中的说明一致“For harnesses with documented file-backed global instructions, install/update also refreshes a compact Potpie managed block in~/.claude/CLAUDE.mdand~/.codex/AGENTS.md. Existing user-authored content is preserved; Potpie only appends or updates the!-- potpie-start --/!-- potpie-end --managed section.”三、合并机制marker 正则如何做到“只更新自己的区块”全局指令块不是覆盖式写入而是走_merge_managed_markdown()potpie/skills/installer.py#L81-L104。它依赖的正则在 installer.py#L15-L18 定义_MANAGED_MARKER_RE re.compile( r!-- (?:context-engine|potpie)-start --.*?!-- (?:context-engine|potpie)-end --, re.DOTALL, )合并逻辑分三种情况返回动作unchanged/updated/created文件里已有受管标记用模板内容整体替换旧区块若替换后无变化则记unchanged否则记updated。这是最常见的“升级刷新”路径——升级 Potpie 后~/.codex/AGENTS.md里的 Potpie 区块会被换成本仓库最新的措辞而区块外的用户内容原样保留。文件里已有无标记的旧版内容比如历史上以context-engine-start命名、或标记被手工删掉的同文内容先剥掉首尾标记行_strip_managed_markers()installer.py#L107-L113若用户文件内容等于剥标记后的模板文本则把带标记的新版本整体补上若旧文本只是文件中的一部分则做一次性replace。完全找不到受管区块在文件末尾追加模板区块existing.rstrip() \n\n section \n空文件时动作记为created。在_install_bundle()中命中merge_files默认包含AGENTS.md、CLAUDE.md的模板文件走上述合并路径其余文件如 skills 下的SKILL.md才走普通覆盖/跳过逻辑installer.py#L350-L387。还有一个值得注意的前置校验安装/更新前validate_packaged_skill_command_snippets()会对打包 SKILL 文件里所有 bash 围栏中以potpie开头的命令逐条对照 Typer 注册表命令名 每个选项是否真实存在做静态验证installer.py#L162-L252。虽然 global bundle 本身只有 8 行且不含代码围栏但同一套机制保证了整个模板树里写给 Agent 的命令示例不会随 CLI 演进而悄悄失效。四、指令内容逐句拆解给 Agent 的三条行为纪律回到模板正文6 行指令实际上压缩了三条可验证的纪律1. 定位Potpie 是“持久项目记忆”不是必选步骤Potpie is durable project memory: repo/source mappings, decisions, infra, changes, bugs, docs, and preferences for agents.这六个名词——repo/source mappings、decisions、infra、changes、bugs、docs、preferences——与项目级 bundle 中的 Views 一一对应decisions、infra_topology、recent_changes、debugging、knowledge等子图说明全局块虽然精简但语义上与 agent_bundle/AGENTS.md 的 Views 表是同一套本体。Use it when it can materially help with repo context, prior decisions, architecture, bugs, or durable history.这是一个“触发条件”而非“必选动作”只有当查询类信息实质有助于当前任务时才使用 Potpie。2. 成本纪律简单问答不查图健康检查每会话一次且可跳过Do not run Potpie checks for simple QA or trivial edits. When useful, check mapping/graph health once per session (potpie --json source list,potpie --json graph status; skip if unavailable).这里约束了两件事何时不查简单问答和琐碎编辑直接跳过避免 Agent 为每个小改动都发起 CLI 调用何时查、查几次once per session——映射/图的健康检查mapping/graph health每个会话只做一次且明确允许skip if unavailableCLI 不可用时静默跳过不阻塞任务。两条命令的含义可以直接对照权威命令参考 docs/context-graph/cli-flow.md命令契约位置用途potpie source list [--pot ref]cli-flow.md#L199列出当前 pot 下的 source 映射验证“repo/source mappings”是否就位potpie graph status [--pot ref]cli-flow.md#L326报告 Context Graph 的可用性/健康决定本会话是否值得走图读取路径--json前缀的作用在 potpie/cli/README.md 中有通用说明commands/_common.py统一负责--json输出形态、退出码约定0 正常 / 1 校验失败 / 2 不可用 / 3 降级 / 4 鉴权以及结构化错误体code/message/detail/recommended_next_action。模板选择让 Agent 用--json形式跑健康检查正是为了让 Agent 能按机器可解析的字段判断“可用/不可用”而不是解析人类可读的文本“skip if unavailable” 对应的就是退出码 2unavailable这一档。3. 写入纪律只记录可持久化的学习Record only durable learnings.这一句是全局块里唯一关于写路径的指令它和项目级 bundle 中 “After work, record durable learnings that should help the next agent” 的完整写入流程先graph search-entities解析身份、再graph propose/graph commit --verify见 agent_bundle/AGENTS.md 的 Writing 与 Ingestion Boundary 章节保持一致只是在全局层面不做展开。全局块只负责“别把一次性噪音写进图”具体怎么写的操作细节留给项目级 bundle 和 skills 承担——这正是“全局极简 项目详尽”两层模板分工的体现。五、与同族模板的分工对照把potpie/cli/templates/下的模板放在一起看全局块的位置就很清楚了模板安装位置篇幅与内容角色global_agent_bundle/AGENTS.md~/.codex/AGENTS.md受管区块6 行跨仓库的最低行为纪律global_agent_bundle/CLAUDE.md~/.claude/CLAUDE.md受管区块6 行内容与 AGENTS.md 相同同上Claude Code 版文件名agent_bundle/AGENTS.md仓库根AGENTS.mddefault/codex完整 Quick Start、Views 表、Writing 规则、mutation JSON 示例、todo 驱动摄入流程、Nudge 响应、Skills 清单单仓库的完整使用手册claude_bundle/CLAUDE.md仓库根CLAUDE.mdclaude与 agent_bundle 同构的详尽版同上Claude 版从源码结构看这条分工链由两个函数分别执行install_agent_bundle()负责仓库级 bundle含 skills 目录 remapinstaller.py#L474-L548install_global_agent_instructions()负责全局受管区块installer.py#L442-L471。用户侧的典型路径是potpie skills install --agent claude默认 global scopeskills 装进 harness 的用户级 skills 目录同时刷新全局指令区块--scope project --path .则做仓库级安装potpie/cli/README.md卸载用potpie skills remove id --agent claude或--all。六、小结一个 8 行模板背后的设计约束global_agent_bundle/AGENTS.md的技术价值不在于内容量而在于它示范了一种多 Agent 时代的指令分发策略上下文成本敏感全局指令会被加载进每个仓库的每次 prompt因此模板被刻意压缩到 6 行行为纪律源码注释明确承认 “This global bundle stays tiny because it can be loaded into every prompt across repositories”installer.py#L448-L451幂等且非破坏性的更新靠!-- potpie-start/end --受管区块 正则替换实现升级刷新用户手写内容、甚至历史context-engine命名的旧区块都能被正确迁移installer.py#L81-L104命令示例与 CLI 契约绑定块内引用的source list、graph status均有 docs/context-graph/cli-flow.md 中的契约条目且模板树的命令示例在安装前会经过 Typer 注册表的静态校验installer.py#L162-L252两级分工全局块只回答“要不要用、多频繁地健康检查、只记持久内容”而“怎么用图读写”的完整操作手册放在项目级 agent_bundle/AGENTS.md 与 Claude 插件 skills 中由--scope project安装到具体仓库。对维护 Agent 指令体系的开发者而言这个模板提供了三个可复用的实践受管标记区块做增量更新、按加载频率分级控制指令篇幅、对模板内命令示例做 CI 级静态校验。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考