企业官网建设流程全解析

解读 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_force（force 不覆盖已有文件）等。内置技能目录则由 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.

即："读源码、判断哪些是持久事实、决定怎么措辞"这些智能工作全部由 Agent（harness）完成；Potpie 只负责把 Agent 提交的图谱变更做校验（validate）、降格（lower，指把语义操作降低到图存储层）、提交（commit）、审计（audit）和排序（rank）。Potpie 不扫仓库、不替你解释文本含义。这条边界在后文的"摄入边界"一节会再次收紧，并在每个核心技能中被测试强制要求复述（见文末"内容契约校验"）。

Quick Start：四条命令建立方位

模板给出的入门序列：

potpie doctor potpie pot list potpie graph status potpie graph catalog --task "<task>"

• potpie doctor：诊断 CLI 与运行环境；
• potpie pot list：列出当前用户可见的 pot（项目记忆容器）；
• potpie graph status：查看当前 pot 的图谱健康/状态；
• potpie graph catalog --task "<task>"：按当前任务获取"目录"——即当前适用（applicable）、需审核（review-required）与暂缓（deferred）三类操作的划分，以及可用的子图/视图。模板明确要求 Agent信任graph catalog的分区结论，而不是自己硬编码操作清单。

Surfaces：graph 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>

参数要点：

模板对输出格式有明确约定：日常方位感和上下文读取用文本输出；只有当工作流需要精确机器解析、变更计划、提交、历史校验或完整证据/调试负载时才加--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 行）：

这些视图不是文档层面的口号，而是在 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 行）：

1. 先解析身份：链接到已存在的 service、repo、bug、decision、person、document 之前，先用graph search-entities确认实体是否已存在，避免重复建节点；
2. 写"检索级"（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_entities：subject/object均带key（规范化实体键，如service:payments-api）、type与属性；predicate为DEPENDS_ON；
• truth: "authoritative_fact"声明该边的真值类别（truth-class），confidence: 0.95给置信度；
• environment: "prod"把边限定在 prod 环境，与infra_topology.service_neighborhood视图的"环境限定边"一致；
• description刻意写入了未来搜索者会用的词（"refund and settlement timeout incidents"），正是"检索级描述"的范例；
• evidence携带source_ref（github:pr:412）与authority（external_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 行）：

1. 预检：pot info、source list、graph status、graph catalog --task，以及对相关graph describe ... --examples；
2. 建发现型 todo：docs/product、local repo map、runtime/deploy、API/data/integrations、GitHub history、preferences/workflows、synthesis、write、verification 九个切面；
3. 只读子代理：若环境支持，用只读 subagent 并行处理独立发现切面；子代理只返回候选事实、证据、置信度与不确定性，不写图谱变更；
4. 证据矩阵 → 身份解析 → 写入：汇总证据矩阵、解析实体身份后，走graph propose/graph commit --verify/graph history；
5. graph 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 等文件都包含 "agent's 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_deploy，bash_post仅在测试命令且按成败解析为test_failed/test_passed），然后转发一次potpie graph nudge调用并注入结果，全程不调模型；推理（什么是事实、挂到哪个实体、如何措辞）发生在 Agent 自己的会话里。适配器是 fail-safe 的：potpie缺失或任何错误都静默退出，钩子故障永远不会阻塞会话；可用POTPIE_HOOK_DEBUG=1打开决策日志，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.md（agent_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_descriptions：potpie-graph技能必须教导 description 是"for search, not display"。

这意味着 AGENTS.md 不是一份静态文档，而是被测试套件钉住的契约：任何未来修改若弱化--verify门禁、改回 JSON 常规读取、或引入 scanner 写入，都会直接打破测试。

小结：一份模板背后的完整职责模型

回顾 AGENTS.md 全文，它实际定义了一个闭环：

1. 取上下文：doctor→pot list→graph status→graph catalog --task定位；
2. 按视图读：八类subgraph.view覆盖偏好、拓扑、时间线、调试记忆、决策、归属、文档与调试切片；
3. 语义写：身份解析 → 检索级描述 →propose/commit --verify/history，永不硬删；
4. 守边界：本地检视可以，扫描器写入不行；托管集成走 Agent 连接器而非 CLI 队列；
5. 响应 nudge：inject_context用事实，instruction做决策；
6. 靠技能分工：八个.agents/skills/技能把上述循环落到具体使用场景。

配合 安装器 的多 harness 落盘逻辑与 test_agent_templates_v15.py 的内容契约测试，这份模板展示了 Potpie 的核心主张：项目记忆的质量取决于 Agent 的写入质量，而 Potpie 提供的是让这份记忆可校验、可审计、可检索、永不丢失（只失效不删除）的确定性基座。

【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie