解读 Potpie AGENTS.md 模板AI Agent 读写项目记忆图谱的完整契约【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本文以 Potpie 仓库中随包分发的 agent 指令模板 AGENTS.md 为主体逐节拆解它对 AI 编程 Agent 下达的行为契约如何用potpie graphCLI 读取项目记忆图谱、按视图view组织上下文、以语义化变更计划propose/commit写入持久知识以及摄入边界与 nudge 机制的设计。读完后你可以理解 Potpie harness 是智能体、Potpie 只做校验与存储的职责划分并能在自己的仓库中复用这套 Agent 指令模板与技能skills体系。模板的定位安装到仓库根部的 Agent 契约文件agent_bundle是 Potpie 面向通用 Agent 框架Codex、OpenCode 等的指令包。AGENTS.md 全文被!-- potpie-start --与!-- potpie-end --两个标记注释包裹这是为了支持幂等更新安装器在重复安装时只替换标记之间的受管区段保留用户自有的其余内容。从 安装器实现 可以看到各 harness 的落盘布局default/codex写入AGENTS.md.agents/skills/claude写入CLAUDE.md并把技能重映射到.claude/skills/claude-plugin把 Claude Code 插件目录落到.claude/potpie-plugin/cursor/opencode分别落到.cursor/skills/与.opencode/skills/。对应行为有专门测试覆盖如 test_agent_installer.py 中的test_install_agent_bundle_updates_marked_agents_md_without_force带标记的旧 AGENTS.md 可被就地更新、test_install_agent_bundle_does_not_overwrite_agents_md_with_forceforce 不覆盖已有文件等。内置技能目录则由 catalog.py 从agent_bundle模板加载。需要强调这份文件不是给人读的 README而是给 Agent 读的操作手册——它规定了 Agent 在工作前如何取上下文、工作后如何沉淀记忆。设计哲学Harness 是智能体Potpie 只校验与存储模板开篇AGENTS.md 第 2–10 行给出了整个契约的核心分工This project uses Potpie for project memory. Before non-trivial work, read the graph to orient yourself. After work, record durable learnings that should help the next agent.The harness is the intelligence. Potpie validates, lowers, commits, audits, and ranks graph memory. It does not scan the repository or decide what prose means for you.即读源码、判断哪些是持久事实、决定怎么措辞这些智能工作全部由 Agentharness完成Potpie 只负责把 Agent 提交的图谱变更做校验validate、降格lower指把语义操作降低到图存储层、提交commit、审计audit和排序rank。Potpie 不扫仓库、不替你解释文本含义。这条边界在后文的摄入边界一节会再次收紧并在每个核心技能中被测试强制要求复述见文末内容契约校验。Quick Start四条命令建立方位模板给出的入门序列potpie doctor potpie pot list potpie graph status potpie graph catalog --task taskpotpie doctor诊断 CLI 与运行环境potpie pot list列出当前用户可见的 pot项目记忆容器potpie graph status查看当前 pot 的图谱健康/状态potpie graph catalog --task task按当前任务获取目录——即当前适用applicable、需审核review-required与暂缓deferred三类操作的划分以及可用的子图/视图。模板明确要求 Agent信任graph catalog的分区结论而不是自己硬编码操作清单。Surfacesgraph CLI 全量命令面模板要求只要 shell 可用优先用 graph CLI完整命令面如下原文第 25–34 行potpie graph status potpie graph catalog --task task --profile read potpie graph describe subgraph --view view --examples potpie graph read --subgraph subgraph --view view [--query ...] [--scope key:value] [--limit N] potpie graph search-entities text [--type Service] [--predicate DEPENDS_ON] [--environment prod] [--limit N] potpie --json graph propose --file mutation.json potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id参数要点命令作用关键参数graph status图谱状态/健康检查无graph catalog按任务列出可用操作与视图分区--task任务描述、--profile read只读视角graph describe查看某子图/视图的结构说明--examples附带示例graph read表达所有读请求的统一入口--subgraph/--view必填--query语义查询--scope key:value范围限定--limit N截断graph search-entities文本检索实体写前身份解析--type如Service、--predicate如DEPENDS_ON、--environment如prodgraph propose提交变更计划返回plan_id--file mutation.json必须--jsongraph commit按计划提交并校验plan_id--verify是写后门禁graph history查看某计划的审计历史--plan plan_id必须--json模板对输出格式有明确约定日常方位感和上下文读取用文本输出只有当工作流需要精确机器解析、变更计划、提交、历史校验或完整证据/调试负载时才加--json。这条约定不是风格建议而是被测试硬编码的契约test_agent_templates_v15.py 的test_templates_are_text_first_for_agent_reads会扫描所有模板发现potpie --json graph read或--json graph search-entities即判失败——因为让 Agent 用 JSON 做常规读取会浪费 token 且难以利用。同理test_graph_commit_examples_use_verified_gate第 130–141 行要求模板中出现的每一处potpie --json graph commit示例都必须带--verify且至少 8 处防止未来编辑弱化提交门禁。Views八个预置读取视图模板把读请求统一表达为graph read --subgraph subgraph --view view并给出八类视图原文第 42–53 行视图用途decisions.preferences_for_scope面向代码工作的项目/仓库/路径偏好infra_topology.service_neighborhood环境限定env-qualified的依赖关系与爆炸半径recent_changes.timeline全项目 PR、工单、文档、事故、部署时间线debugging.prior_occurrences历史症状、修复方案、失败尝试decisions.active_decisions当前活跃的产品/架构决策code_topology.ownership_by_path某范围的负责人ownersknowledge.document_context某范围的文档与 runbookadmin.inspection_slice用于调试的原始规范化图切片这些视图不是文档层面的口号而是在 context-engine 中以声明式规格注册的。graph_views.py 中每个视图是一个GraphViewSpec携带查询轴契约decisions.preferences_for_scope第 106–121 行接受repo/scope/path/query输入内联POLICY_APPLIES_TO关系排序因子为semantic_similarity、strength、recency、scope_overlap、corroboration——即相关性、强度、新鲜度、范围重叠、多源印证共同决定哪条偏好排前debugging.prior_occurrences第 122–136 行按症状匹配历史 bug内联REPRODUCES/RESOLVED/ATTEMPTED_FIX_FAILED/VERIFIED四类关系——注意ATTEMPTED_FIX_FAILED被显式建模失败过的尝试本身也是可检索的记忆infra_topology.service_neighborhood第 147–164 行深度有界、方向感知的服务邻域遍历内联DEPENDS_ON/USES/USES_ADAPTER/CONFIGURES/DEPLOYED_WITH/DEPLOYED_TO/OWNED_BY/EXPOSES等谓词且边是环境限定的——这正是模板中 env-qualified dependencies and blast radius 一行的底层实现。此外agent_context_port.py 把CONTEXT_RECORD_TYPES直接派生自PUBLIC_RECORD_TYPES并用READER_BACKED_INCLUDES与读取编排器保持相干性检查保证 Agent 面向的词汇与图 schema 不会漂移。graph describe subgraph --view view --examples输出的就是这些 spec 经to_catalog_entry()序列化后的形状加示例。Writing写图谱的两条铁律与变更计划流程模板说两条规则承载了大部分价值原文第 55–68 行先解析身份链接到已存在的 service、repo、bug、decision、person、document 之前先用graph search-entities确认实体是否已存在避免重复建节点写检索级retrieval-grade描述description 不是给人看的展示文本而是给未来的搜索者用的——要包含症状原文、同义词、范围、环境、服务名、文件、命令、来源引用一个未来的搜索者会敲什么词你就写什么词。写入规则方面只用语义操作upsert_entity、link_entities、assert_claim、append_event、end_relation_validity、retract_claim等同族 CLAUDE.md 有显式列举并以graph catalog当前宣告的可用操作为准永不硬删除never hard-delete a claim让声明结束有效期end its validity、撤回retract、被取代supersede或按 catalog 策略合并重复项先计划后提交potpie --json graph propose --file mutation.json potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id模板附了一个完整的 infra 写入示例原文第 80–101 行这是理解变更文件格式的最佳样本{ graph_contract_version: v1.5, pot_id: local/default, idempotency_key: mutation:infra:payments-ledger-prod, created_by: {surface: cli, harness: codex}, operations: [ { op: link_entities, subgraph: infra_topology, subject: {key: service:payments-api, type: Service, properties: {name: payments-api}}, predicate: DEPENDS_ON, object: {key: service:ledger-api, type: Service, properties: {name: ledger-api}}, truth: authoritative_fact, confidence: 0.95, environment: prod, description: payments-api calls ledger-api in prod to post settlements; ledger-api failures surface as refund and settlement timeout incidents., evidence: [{source_ref: github:pr:412, authority: external_system}] } ] }字段解读graph_contract_version: v1.5是图谱契约版本idempotency_key保证同一事实重复提交不会造成重复写入created_by记录写入面surface与 harness 名称形成可审计的写入来源链单条 operation 是link_entitiessubject/object均带key规范化实体键如service:payments-api、type与属性predicate为DEPENDS_ONtruth: authoritative_fact声明该边的真值类别truth-classconfidence: 0.95给置信度environment: prod把边限定在 prod 环境与infra_topology.service_neighborhood视图的环境限定边一致description刻意写入了未来搜索者会用的词refund and settlement timeout incidents正是检索级描述的范例evidence携带source_refgithub:pr:412与authorityexternal_system让每条声明可回溯到外部权威来源。模板第 103 行还列出了记录类型词表AGENTS.md 第 103 行preference|policy|bug_pattern|fix|verification|decision|doc_reference|workflow|runbook_note|incident_summary|investigation|diagnostic_signal|service_note|feature_note|integration_note这 15 个类型与 context-engine 中的PUBLIC_RECORD_TYPES/CONTEXT_RECORD_TYPES同源agent_context_port.py 第 48 行且 test_agent_templates_v15.py 的test_record_type_enums_are_supported会解析模板中所有此类竖线枚举逐个对照真实词表出现未知类型即失败——保证模板与代码词表同步演化。Ingestion Boundary摄入边界是最容易被违反的一条模板明确agent 指令中不存在扫描器驱动的图谱写入路径原文第 105–114 行。边界划得很细允许为理解仓库而对本地做只读检视——rg、rg --files、git、manifests、docs、routes、configs、tests、CI 文件禁止把一次目录树遍历盲目翻译成图谱事实不能仅凭目录名或包文件推断出服务、依赖、功能或偏好。对显式的仓库摄入repository ingestion模板规定 todo 驱动的五阶段工作流原文第 116–130 行预检pot info、source list、graph status、graph catalog --task以及对相关graph describe ... --examples建发现型 tododocs/product、local repo map、runtime/deploy、API/data/integrations、GitHub history、preferences/workflows、synthesis、write、verification 九个切面只读子代理若环境支持用只读 subagent 并行处理独立发现切面子代理只返回候选事实、证据、置信度与不确定性不写图谱变更证据矩阵 → 身份解析 → 写入汇总证据矩阵、解析实体身份后走graph propose/graph commit --verify/graph historygraph commit --verify即写后门禁警告或失败时用受影响的读操作与质量报告重复项、低置信度、冲突声明检查下钻。对 GitHub、Linear、Jira 等托管集成原文第 132–136 行模板要求用Agent 自己的集成工具/连接器拉取 PR、issue、工单、评论、标签/状态与关联文档然后自行通过graph propose/graph commit --verify或graph inbox写图谱不要用 Potpie CLI 的队列摄入路径。这条同样被测试固化test_hosted_integration_ingestion_is_agent_led第 402–419 行检查 AGENTS.md 等文件都包含 agents integration tools/connectors、do not use potpie cli queue ingestion 与 graph plans 路由语句test_templates_do_not_advertise_local_ingest_or_scan_commands第 388–399 行则禁止模板重新出现potpie ingest、--scan等已移除命令。Responding To Nudges被动注入的两类信号钩子hook可能从potpie graph nudge注入上下文或指令原文第 138–146 行Agent 的响应规则分两类inject_context注入的事实直接用于当前任务无需回写instruction这是一个决策提示让 Agent 判断本次工作是否产生了持久学习。若是则解析身份 → propose 计划 → 策略允许时--verify提交 → 检查 history若无持久学习什么都不做。这条决策提示 ≠ 自动写入的语义被test_templates_document_nudge_handling第 240–245 行强制技能文档必须同时出现inject_context、instruction且说明写入指令是 prompt to decide 而非 auto-write。配套的 nudge 通道实现见 Claude Code 插件 README钩子路径是model-free的——适配器只做机械细化如bash_pre仅在部署/infra 命令时解析为pre_deploybash_post仅在测试命令且按成败解析为test_failed/test_passed然后转发一次potpie graph nudge调用并注入结果全程不调模型推理什么是事实、挂到哪个实体、如何措辞发生在 Agent 自己的会话里。适配器是 fail-safe 的potpie缺失或任何错误都静默退出钩子故障永远不会阻塞会话可用POTPIE_HOOK_DEBUG1打开决策日志POTPIE_HOOK_TIMEOUT默认 15 秒限制子进程时长。Skills模板引用的八个仓库本地技能AGENTS.md 末尾原文第 148–167 行声明使用.agents/skills/下的技能并给出职责摘要potpie-project-preferences—— 写码前查错误处理、结构、库、框架、日志、测试与编码规范potpie-infra-architecture—— 环境、适配器、部署拓扑、服务依赖、数据源、API 契约与归属potpie-change-timeline—— 近期/历史 PR、工单、文档、事故、部署及回归关联potpie-debug-memory—— 历史 bug、修复、失败尝试、验证与开发环境排障potpie-repo-baseline—— 仓库定位、服务、环境、API、数据源、集成与持久项目事实potpie-source-ingestion—— harness 主导的摄入repo 链接、文档、PR、issue、工单、runbook、日志、web 链接portpie-graph原文如此实为potpie-graph—— graph CLI 契约status/catalog/describe/read/search、propose/commit/history、inbox、quality 与 nudge 处理potpie-cli—— CLI 安装、pot/source 命令、graph 命令与排障含 pot 作用域与 setup 失败。这些技能在模板树中对应 claude_plugin/skills/ 下的 SKILL.mdagent_bundle 与 claude_plugin 两份副本被 test_claude_plugin_manifest.py 强制保持逐字一致目录约定见 docs/context-graph/skills.md。值得注意的是模板引用的potpie-cli技能测试test_core_skills_state_harness_led_boundary第 268–301 行要求全部八个核心技能的正文都必须声明harness-led边界并显式排除 scanner 驱动的图谱更新——把边界写进了每个技能的正文而不仅是 AGENTS.md。内容契约校验模板为什么能保持不腐化tests/unit/test_agent_templates_v15.py 是理解这份模板工程化程度的一把钥匙它对模板内容做合同式校验test_agents_md_advertises_graph_surface第 102–114 行AGENTS.md 必须逐一包含graph status、graph catalog --task、graph describe、graph read --subgraph、graph search-entities、graph propose、graph commit、graph history八个动词缺一个即失败——保证 graph 命令面不会被编辑意外删掉test_no_stale_include_names_anywhere/test_templates_use_canonical_v2_view_syntax禁止出现 V1 时代的 include 名如feature_map、prior_fixes与旧公共视图名如bugs.prior_occurrences强制使用subgraph.view规范语法test_templates_do_not_advertise_v1_write_workflow禁止graph mutate --file、--dry-run等 V1 写工作流残留test_templates_do_not_recommend_removed_potpie_mcp_tools禁止推荐已移除的 MCP 工具名context_resolve、potpie-mcp等test_templates_require_retrieval_grade_descriptionspotpie-graph技能必须教导 description 是for search, not display。这意味着 AGENTS.md 不是一份静态文档而是被测试套件钉住的契约任何未来修改若弱化--verify门禁、改回 JSON 常规读取、或引入 scanner 写入都会直接打破测试。小结一份模板背后的完整职责模型回顾 AGENTS.md 全文它实际定义了一个闭环取上下文doctor→pot list→graph status→graph catalog --task定位按视图读八类subgraph.view覆盖偏好、拓扑、时间线、调试记忆、决策、归属、文档与调试切片语义写身份解析 → 检索级描述 →propose/commit --verify/history永不硬删守边界本地检视可以扫描器写入不行托管集成走 Agent 连接器而非 CLI 队列响应 nudgeinject_context用事实instruction做决策靠技能分工八个.agents/skills/技能把上述循环落到具体使用场景。配合 安装器 的多 harness 落盘逻辑与 test_agent_templates_v15.py 的内容契约测试这份模板展示了 Potpie 的核心主张项目记忆的质量取决于 Agent 的写入质量而 Potpie 提供的是让这份记忆可校验、可审计、可检索、永不丢失只失效不删除的确定性基座。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 解读 Potpie AGENTS.md 模板：AI Agent 读写项目记忆图谱的完整契约
解读 Potpie AGENTS.md 模板AI Agent 读写项目记忆图谱的完整契约【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本文以 Potpie 仓库中随包分发的 agent 指令模板 AGENTS.md 为主体逐节拆解它对 AI 编程 Agent 下达的行为契约如何用potpie graphCLI 读取项目记忆图谱、按视图view组织上下文、以语义化变更计划propose/commit写入持久知识以及摄入边界与 nudge 机制的设计。读完后你可以理解 Potpie harness 是智能体、Potpie 只做校验与存储的职责划分并能在自己的仓库中复用这套 Agent 指令模板与技能skills体系。模板的定位安装到仓库根部的 Agent 契约文件agent_bundle是 Potpie 面向通用 Agent 框架Codex、OpenCode 等的指令包。AGENTS.md 全文被!-- potpie-start --与!-- potpie-end --两个标记注释包裹这是为了支持幂等更新安装器在重复安装时只替换标记之间的受管区段保留用户自有的其余内容。从 安装器实现 可以看到各 harness 的落盘布局default/codex写入AGENTS.md.agents/skills/claude写入CLAUDE.md并把技能重映射到.claude/skills/claude-plugin把 Claude Code 插件目录落到.claude/potpie-plugin/cursor/opencode分别落到.cursor/skills/与.opencode/skills/。对应行为有专门测试覆盖如 test_agent_installer.py 中的test_install_agent_bundle_updates_marked_agents_md_without_force带标记的旧 AGENTS.md 可被就地更新、test_install_agent_bundle_does_not_overwrite_agents_md_with_forceforce 不覆盖已有文件等。内置技能目录则由 catalog.py 从agent_bundle模板加载。需要强调这份文件不是给人读的 README而是给 Agent 读的操作手册——它规定了 Agent 在工作前如何取上下文、工作后如何沉淀记忆。设计哲学Harness 是智能体Potpie 只校验与存储模板开篇AGENTS.md 第 2–10 行给出了整个契约的核心分工This project uses Potpie for project memory. Before non-trivial work, read the graph to orient yourself. After work, record durable learnings that should help the next agent.The harness is the intelligence. Potpie validates, lowers, commits, audits, and ranks graph memory. It does not scan the repository or decide what prose means for you.即读源码、判断哪些是持久事实、决定怎么措辞这些智能工作全部由 Agentharness完成Potpie 只负责把 Agent 提交的图谱变更做校验validate、降格lower指把语义操作降低到图存储层、提交commit、审计audit和排序rank。Potpie 不扫仓库、不替你解释文本含义。这条边界在后文的摄入边界一节会再次收紧并在每个核心技能中被测试强制要求复述见文末内容契约校验。Quick Start四条命令建立方位模板给出的入门序列potpie doctor potpie pot list potpie graph status potpie graph catalog --task taskpotpie doctor诊断 CLI 与运行环境potpie pot list列出当前用户可见的 pot项目记忆容器potpie graph status查看当前 pot 的图谱健康/状态potpie graph catalog --task task按当前任务获取目录——即当前适用applicable、需审核review-required与暂缓deferred三类操作的划分以及可用的子图/视图。模板明确要求 Agent信任graph catalog的分区结论而不是自己硬编码操作清单。Surfacesgraph CLI 全量命令面模板要求只要 shell 可用优先用 graph CLI完整命令面如下原文第 25–34 行potpie graph status potpie graph catalog --task task --profile read potpie graph describe subgraph --view view --examples potpie graph read --subgraph subgraph --view view [--query ...] [--scope key:value] [--limit N] potpie graph search-entities text [--type Service] [--predicate DEPENDS_ON] [--environment prod] [--limit N] potpie --json graph propose --file mutation.json potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id参数要点命令作用关键参数graph status图谱状态/健康检查无graph catalog按任务列出可用操作与视图分区--task任务描述、--profile read只读视角graph describe查看某子图/视图的结构说明--examples附带示例graph read表达所有读请求的统一入口--subgraph/--view必填--query语义查询--scope key:value范围限定--limit N截断graph search-entities文本检索实体写前身份解析--type如Service、--predicate如DEPENDS_ON、--environment如prodgraph propose提交变更计划返回plan_id--file mutation.json必须--jsongraph commit按计划提交并校验plan_id--verify是写后门禁graph history查看某计划的审计历史--plan plan_id必须--json模板对输出格式有明确约定日常方位感和上下文读取用文本输出只有当工作流需要精确机器解析、变更计划、提交、历史校验或完整证据/调试负载时才加--json。这条约定不是风格建议而是被测试硬编码的契约test_agent_templates_v15.py 的test_templates_are_text_first_for_agent_reads会扫描所有模板发现potpie --json graph read或--json graph search-entities即判失败——因为让 Agent 用 JSON 做常规读取会浪费 token 且难以利用。同理test_graph_commit_examples_use_verified_gate第 130–141 行要求模板中出现的每一处potpie --json graph commit示例都必须带--verify且至少 8 处防止未来编辑弱化提交门禁。Views八个预置读取视图模板把读请求统一表达为graph read --subgraph subgraph --view view并给出八类视图原文第 42–53 行视图用途decisions.preferences_for_scope面向代码工作的项目/仓库/路径偏好infra_topology.service_neighborhood环境限定env-qualified的依赖关系与爆炸半径recent_changes.timeline全项目 PR、工单、文档、事故、部署时间线debugging.prior_occurrences历史症状、修复方案、失败尝试decisions.active_decisions当前活跃的产品/架构决策code_topology.ownership_by_path某范围的负责人ownersknowledge.document_context某范围的文档与 runbookadmin.inspection_slice用于调试的原始规范化图切片这些视图不是文档层面的口号而是在 context-engine 中以声明式规格注册的。graph_views.py 中每个视图是一个GraphViewSpec携带查询轴契约decisions.preferences_for_scope第 106–121 行接受repo/scope/path/query输入内联POLICY_APPLIES_TO关系排序因子为semantic_similarity、strength、recency、scope_overlap、corroboration——即相关性、强度、新鲜度、范围重叠、多源印证共同决定哪条偏好排前debugging.prior_occurrences第 122–136 行按症状匹配历史 bug内联REPRODUCES/RESOLVED/ATTEMPTED_FIX_FAILED/VERIFIED四类关系——注意ATTEMPTED_FIX_FAILED被显式建模失败过的尝试本身也是可检索的记忆infra_topology.service_neighborhood第 147–164 行深度有界、方向感知的服务邻域遍历内联DEPENDS_ON/USES/USES_ADAPTER/CONFIGURES/DEPLOYED_WITH/DEPLOYED_TO/OWNED_BY/EXPOSES等谓词且边是环境限定的——这正是模板中 env-qualified dependencies and blast radius 一行的底层实现。此外agent_context_port.py 把CONTEXT_RECORD_TYPES直接派生自PUBLIC_RECORD_TYPES并用READER_BACKED_INCLUDES与读取编排器保持相干性检查保证 Agent 面向的词汇与图 schema 不会漂移。graph describe subgraph --view view --examples输出的就是这些 spec 经to_catalog_entry()序列化后的形状加示例。Writing写图谱的两条铁律与变更计划流程模板说两条规则承载了大部分价值原文第 55–68 行先解析身份链接到已存在的 service、repo、bug、decision、person、document 之前先用graph search-entities确认实体是否已存在避免重复建节点写检索级retrieval-grade描述description 不是给人看的展示文本而是给未来的搜索者用的——要包含症状原文、同义词、范围、环境、服务名、文件、命令、来源引用一个未来的搜索者会敲什么词你就写什么词。写入规则方面只用语义操作upsert_entity、link_entities、assert_claim、append_event、end_relation_validity、retract_claim等同族 CLAUDE.md 有显式列举并以graph catalog当前宣告的可用操作为准永不硬删除never hard-delete a claim让声明结束有效期end its validity、撤回retract、被取代supersede或按 catalog 策略合并重复项先计划后提交potpie --json graph propose --file mutation.json potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id模板附了一个完整的 infra 写入示例原文第 80–101 行这是理解变更文件格式的最佳样本{ graph_contract_version: v1.5, pot_id: local/default, idempotency_key: mutation:infra:payments-ledger-prod, created_by: {surface: cli, harness: codex}, operations: [ { op: link_entities, subgraph: infra_topology, subject: {key: service:payments-api, type: Service, properties: {name: payments-api}}, predicate: DEPENDS_ON, object: {key: service:ledger-api, type: Service, properties: {name: ledger-api}}, truth: authoritative_fact, confidence: 0.95, environment: prod, description: payments-api calls ledger-api in prod to post settlements; ledger-api failures surface as refund and settlement timeout incidents., evidence: [{source_ref: github:pr:412, authority: external_system}] } ] }字段解读graph_contract_version: v1.5是图谱契约版本idempotency_key保证同一事实重复提交不会造成重复写入created_by记录写入面surface与 harness 名称形成可审计的写入来源链单条 operation 是link_entitiessubject/object均带key规范化实体键如service:payments-api、type与属性predicate为DEPENDS_ONtruth: authoritative_fact声明该边的真值类别truth-classconfidence: 0.95给置信度environment: prod把边限定在 prod 环境与infra_topology.service_neighborhood视图的环境限定边一致description刻意写入了未来搜索者会用的词refund and settlement timeout incidents正是检索级描述的范例evidence携带source_refgithub:pr:412与authorityexternal_system让每条声明可回溯到外部权威来源。模板第 103 行还列出了记录类型词表AGENTS.md 第 103 行preference|policy|bug_pattern|fix|verification|decision|doc_reference|workflow|runbook_note|incident_summary|investigation|diagnostic_signal|service_note|feature_note|integration_note这 15 个类型与 context-engine 中的PUBLIC_RECORD_TYPES/CONTEXT_RECORD_TYPES同源agent_context_port.py 第 48 行且 test_agent_templates_v15.py 的test_record_type_enums_are_supported会解析模板中所有此类竖线枚举逐个对照真实词表出现未知类型即失败——保证模板与代码词表同步演化。Ingestion Boundary摄入边界是最容易被违反的一条模板明确agent 指令中不存在扫描器驱动的图谱写入路径原文第 105–114 行。边界划得很细允许为理解仓库而对本地做只读检视——rg、rg --files、git、manifests、docs、routes、configs、tests、CI 文件禁止把一次目录树遍历盲目翻译成图谱事实不能仅凭目录名或包文件推断出服务、依赖、功能或偏好。对显式的仓库摄入repository ingestion模板规定 todo 驱动的五阶段工作流原文第 116–130 行预检pot info、source list、graph status、graph catalog --task以及对相关graph describe ... --examples建发现型 tododocs/product、local repo map、runtime/deploy、API/data/integrations、GitHub history、preferences/workflows、synthesis、write、verification 九个切面只读子代理若环境支持用只读 subagent 并行处理独立发现切面子代理只返回候选事实、证据、置信度与不确定性不写图谱变更证据矩阵 → 身份解析 → 写入汇总证据矩阵、解析实体身份后走graph propose/graph commit --verify/graph historygraph commit --verify即写后门禁警告或失败时用受影响的读操作与质量报告重复项、低置信度、冲突声明检查下钻。对 GitHub、Linear、Jira 等托管集成原文第 132–136 行模板要求用Agent 自己的集成工具/连接器拉取 PR、issue、工单、评论、标签/状态与关联文档然后自行通过graph propose/graph commit --verify或graph inbox写图谱不要用 Potpie CLI 的队列摄入路径。这条同样被测试固化test_hosted_integration_ingestion_is_agent_led第 402–419 行检查 AGENTS.md 等文件都包含 agents integration tools/connectors、do not use potpie cli queue ingestion 与 graph plans 路由语句test_templates_do_not_advertise_local_ingest_or_scan_commands第 388–399 行则禁止模板重新出现potpie ingest、--scan等已移除命令。Responding To Nudges被动注入的两类信号钩子hook可能从potpie graph nudge注入上下文或指令原文第 138–146 行Agent 的响应规则分两类inject_context注入的事实直接用于当前任务无需回写instruction这是一个决策提示让 Agent 判断本次工作是否产生了持久学习。若是则解析身份 → propose 计划 → 策略允许时--verify提交 → 检查 history若无持久学习什么都不做。这条决策提示 ≠ 自动写入的语义被test_templates_document_nudge_handling第 240–245 行强制技能文档必须同时出现inject_context、instruction且说明写入指令是 prompt to decide 而非 auto-write。配套的 nudge 通道实现见 Claude Code 插件 README钩子路径是model-free的——适配器只做机械细化如bash_pre仅在部署/infra 命令时解析为pre_deploybash_post仅在测试命令且按成败解析为test_failed/test_passed然后转发一次potpie graph nudge调用并注入结果全程不调模型推理什么是事实、挂到哪个实体、如何措辞发生在 Agent 自己的会话里。适配器是 fail-safe 的potpie缺失或任何错误都静默退出钩子故障永远不会阻塞会话可用POTPIE_HOOK_DEBUG1打开决策日志POTPIE_HOOK_TIMEOUT默认 15 秒限制子进程时长。Skills模板引用的八个仓库本地技能AGENTS.md 末尾原文第 148–167 行声明使用.agents/skills/下的技能并给出职责摘要potpie-project-preferences—— 写码前查错误处理、结构、库、框架、日志、测试与编码规范potpie-infra-architecture—— 环境、适配器、部署拓扑、服务依赖、数据源、API 契约与归属potpie-change-timeline—— 近期/历史 PR、工单、文档、事故、部署及回归关联potpie-debug-memory—— 历史 bug、修复、失败尝试、验证与开发环境排障potpie-repo-baseline—— 仓库定位、服务、环境、API、数据源、集成与持久项目事实potpie-source-ingestion—— harness 主导的摄入repo 链接、文档、PR、issue、工单、runbook、日志、web 链接portpie-graph原文如此实为potpie-graph—— graph CLI 契约status/catalog/describe/read/search、propose/commit/history、inbox、quality 与 nudge 处理potpie-cli—— CLI 安装、pot/source 命令、graph 命令与排障含 pot 作用域与 setup 失败。这些技能在模板树中对应 claude_plugin/skills/ 下的 SKILL.mdagent_bundle 与 claude_plugin 两份副本被 test_claude_plugin_manifest.py 强制保持逐字一致目录约定见 docs/context-graph/skills.md。值得注意的是模板引用的potpie-cli技能测试test_core_skills_state_harness_led_boundary第 268–301 行要求全部八个核心技能的正文都必须声明harness-led边界并显式排除 scanner 驱动的图谱更新——把边界写进了每个技能的正文而不仅是 AGENTS.md。内容契约校验模板为什么能保持不腐化tests/unit/test_agent_templates_v15.py 是理解这份模板工程化程度的一把钥匙它对模板内容做合同式校验test_agents_md_advertises_graph_surface第 102–114 行AGENTS.md 必须逐一包含graph status、graph catalog --task、graph describe、graph read --subgraph、graph search-entities、graph propose、graph commit、graph history八个动词缺一个即失败——保证 graph 命令面不会被编辑意外删掉test_no_stale_include_names_anywhere/test_templates_use_canonical_v2_view_syntax禁止出现 V1 时代的 include 名如feature_map、prior_fixes与旧公共视图名如bugs.prior_occurrences强制使用subgraph.view规范语法test_templates_do_not_advertise_v1_write_workflow禁止graph mutate --file、--dry-run等 V1 写工作流残留test_templates_do_not_recommend_removed_potpie_mcp_tools禁止推荐已移除的 MCP 工具名context_resolve、potpie-mcp等test_templates_require_retrieval_grade_descriptionspotpie-graph技能必须教导 description 是for search, not display。这意味着 AGENTS.md 不是一份静态文档而是被测试套件钉住的契约任何未来修改若弱化--verify门禁、改回 JSON 常规读取、或引入 scanner 写入都会直接打破测试。小结一份模板背后的完整职责模型回顾 AGENTS.md 全文它实际定义了一个闭环取上下文doctor→pot list→graph status→graph catalog --task定位按视图读八类subgraph.view覆盖偏好、拓扑、时间线、调试记忆、决策、归属、文档与调试切片语义写身份解析 → 检索级描述 →propose/commit --verify/history永不硬删守边界本地检视可以扫描器写入不行托管集成走 Agent 连接器而非 CLI 队列响应 nudgeinject_context用事实instruction做决策靠技能分工八个.agents/skills/技能把上述循环落到具体使用场景。配合 安装器 的多 harness 落盘逻辑与 test_agent_templates_v15.py 的内容契约测试这份模板展示了 Potpie 的核心主张项目记忆的质量取决于 Agent 的写入质量而 Potpie 提供的是让这份记忆可校验、可审计、可检索、永不丢失只失效不删除的确定性基座。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考