Potpie 源码摄取实战基于 potpie-source-ingestion 技能的证据驱动仓库入库工作流【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本文基于 Potpie 仓库中随 agent 模板分发的potpie-source-ingestion技能文档完整拆解一套“由 Agent 作为智能主体、Potpie 负责校验与存储”的源码摄取source ingestion流程从范围界定、todo 驱动的并行发现、本地结构化检查、GitHub 侧数据补充到证据矩阵、实体身份消解、propose/commit 写入与质量门禁。读完后你可以掌握如何在 Potpie 上下文图中把仓库、PR、Issue、文档与外部系统转化为带证据链的语义图变更semantic graph mutations并理解每一阶段背后的 CLI 实现与视图契约。技能定位Harness 是智能Potpie 是存储该技能定义在 SKILL.md随agent_bundle模板一起分发claude_plugin模板下也有一份同内容拷贝见 potpie-source-ingestion当用户明确要求“摄取、刷新或深度理解某个仓库、PR、Issue、工单、Runbook、事故报告、文档或网页链接”时触发。其职责划分是整个工作流的基石Harness主 Agent负责智能采集源数据、阅读内容、判断什么信息是持久性的durable、完成身份消解identity resolution、生成带证据的语义图变更Potpie 负责校验与存储它不决定源材料的含义只做验证validate和落库store。技能开头明确给出了五条“不可协商”Non-Negotiables规则它们约束了后续所有阶段每个仓库或多源摄取都必须使用 todo/checklist禁止从 README 直接跳到图写入本地检查是仓库理解的必选项基于扫描器scanner的图更新被明令禁止——要用rg、rg --files、git和结构化工具检查文件不要运行遍历目录树并直接写图事实的遗留/确定性摄取命令子代理subagent只用于只读发现切片主 Agent 保留源选择、身份消解、变更提案、提交与最终综合的所有权所有必需发现车道discovery lane完成、明确不可用或被用户主动排除之前不得写入每次写入都必须携带source refs来源引用、source authority来源权威级别、truth class真相类别、confidence置信度 0.0–1.0、compact summary紧凑摘要和 retrieval-grade description检索级描述。Phase 0范围界定与预检Scope And Preflight在写任何东西之前先回答五个问题源类型是什么目标 pot/project 是哪个repo/path/URL 是什么时间窗口多大目标记忆形态baseline、history、docs、infra、debug memory、preferences 还是全部随后验证 Potpie 作用域与图可用性全部使用--json以便 Agent 机械解析potpie --json pot info potpie --json source list potpie --json graph status potpie --json graph catalog --task harness-led source ingestion其中graph catalog是整个摄取流程的“合同发现”入口——从源码看graph_catalog 命令会经引擎返回版本、视图、变更操作与本体ontology信息Agent 后续编写 mutation 时以此为准而非凭记忆。如果仓库尚未注册只注册元数据此时不触发任何内容摄取pot 作用域模糊时使用显式--potpotpie source add repo . --pot pot-id-or-name接下来在动手编写 mutation 之前先描述预期要读写的视图potpie --json graph describe features --view feature_context --examples potpie --json graph describe infra_topology --view service_neighborhood --examples potpie --json graph describe recent_changes --view timeline --examples potpie --json graph describe decisions --view preferences_for_scope --examples potpie --json graph describe debugging --view prior_occurrences --examples这五个视图名在 Potpie 中都是受版本管理的正式契约定义在 graph_views.py 的_VIEW_LIST中每个视图声明了自己的输入、内联关系inline relations与排序输入。具体到技能用到的五个视图视图subgraph.view回答的问题内联关系features.feature_context“这个仓库提供什么能力、实现在哪”PROVIDES、IMPLEMENTED_INinfra_topology.service_neighborhood服务邻域深度/方向可控带环境限定的依赖与绑定边DEPENDS_ON、USES、DEPLOYED_TO、OWNED_BY等 9 种recent_changes.timeline某作用域近期的 PR/工单/部署活动TOUCHED、PERFORMED、MENTIONSdecisions.preferences_for_scope适用于该作用域的编码偏好/策略POLICY_APPLIES_TOdebugging.prior_occurrences症状匹配的既往缺陷及修复/验证关系REPRODUCES、RESOLVED、ATTEMPTED_FIX_FAILED、VERIFIED值得注意的工程细节backed属性是派生而非手设的——视图路由到的内部 include 家族只有在注册了对应 reader 时才视为有后端支撑否则解析为诚实的not_implemented而非静默返回空结果见 graph_views.py 的模块文档与_check_views_coherent()导入期守卫。这意味着 Agent 在 Phase 0 描述视图时得到的信息是可信的。最后一条预检规则如果 CLI 不可用或损坏继续完成发现、构建提议的证据矩阵但停在图写入提交之前——宁可少写不可瞎写。Phase 1Todo 计划与发现车道仓库摄取至少需要维护以下 8 条 todo 车道Scopepot、源注册、图合同预检Product/docsREADME、docs、ADR、Runbook、公开文档、关联网站Local repo mapmanifests、packages/apps、入口、路由/API 表面、测试、框架配置、主要模块、生成物/API 规格Runtime/deployDockerfile、compose、Kubernetes、Terraform、CI 工作流、部署脚本、环境模板、feature flagsAPI/data/integrations服务客户端、适配器、数据存储、模型、队列、认证提供方、外部 APIGitHub/history仓库元数据、topics、releases/tags、近期合并 PR、开放 Issue、关联工单/文档、CI/部署记录Preferences/workflows显式编码风格、测试命令、本地开发环境、发布/部署/Runbook 工作流Synthesis证据矩阵、候选图事实、身份消解、提案、经校验的提交、门禁驱动的后续检查。更新纪律随车道完成更新 todo不确定的发现应保留进 inbox待审箱而不是硬塞进规范化canonical的图断言——这是贯穿全流程的“低置信度隔离”原则。Phase 2并行只读发现Parallel Discovery工具允许时并行派发独立的只读切片技能给出了六段可直接复用的子代理提示词模板Docs/product读 README、docs、ADR、Runbook、包元数据与关联产品页返回产品目的、特性、显式决策、偏好、工作流与来源引用。“Do not write mutations.”Local architecture检查 manifests、顶层 apps/packages、入口、路由/API 表面、测试与框架配置返回服务/模块地图、可能的特性、显式源文件与不确定项。“No mutations.”Runtime/deploy检查 Docker/compose/K8s/Terraform/CI/部署/环境模板返回环境、部署形态、配置变量、工作流、数据存储与来源引用。“Do not write mutations.”API/data/integrations检查路由规格、客户端/适配器、模型、数据存储、队列、认证与外部集成返回候选APIContract/DataStore/Adapter/Dependency事实与证据。“No mutations.”GitHub history用 GitHub 工具/CLI 获取仓库元数据、releases、近期合并 PR、开放 Issue、关联工单/文档与 CI 信号返回时间线、修复、决策、bug 模式与来源引用。“No mutations.”Preferences在文档、配置、测试、贡献指南、PR 模板与评论中找显式偏好只返回带证据的可复用策略。“No mutations.”所有子代理提示词都以“不得写 mutation”结尾呼应“子代理只做只读发现”的硬约束主 Agent 在子代理运行期间继续处理不重叠的发现工作。Phase 3本地结构化检查的目标与命令技能强调“结构化、有边界”的本地检查给出了一组可直接复制的rg命令按其目的分为四组# 文档/元数据面 rg --files -g README* -g docs/** -g *ADR* -g package.json -g pyproject.toml -g Cargo.toml -g go.mod # 运行时/部署面 rg --files -g Dockerfile* -g docker-compose* -g .github/workflows/** -g *.tf -g k8s/** -g .env* # 路由/API 框架指纹 rg -n FastAPI|APIRouter|express\\(|router\\.|Django|Flask|NextResponse|route\\( . # 依赖/集成指纹数据库、队列、认证、外部 SaaS rg -n postgres|mysql|redis|mongo|s3|kafka|rabbit|queue|oauth|stripe|slack|github|linear|jira . # 测试/命令约定限定在文档与构建配置中搜索 rg -n pytest|vitest|jest|playwright|make test|npm test|uv run|cargo test README* docs .github pyproject.toml package.json Makefile配套纪律不得仅凭文件名推断持久事实。文件只用于定位“真相来源”之后要读相关代码片段或作者文档本身。这也解释了为什么前文禁止 scanner 式摄取——模式匹配得到的是候选不是事实。Phase 4GitHub/托管侧数据补充HydrationGitHub 支撑的仓库摄取应使用 Agent 自己的集成工具/连接器GitHub app/MCP/CLI 工具而不是 Potpie 的队列摄取命令。需要采集的清单仓库元数据全名、默认分支、描述、topics、可见性、主页、许可证、archived/fork 状态文档README、贡献指南、CODEOWNERS、PR/Issue 模板、仓库内链接的 docsReleases/tags当其描述已交付行为或部署节奏时近期合并 PR标题、正文、作者、合并日期、分支、labels、关联 Issue、变更文件名仅当作者文本不足时才拉取 patch开放/高信号 Issue标题、正文、labels、状态、作者、评论可用时CI/工作流工作流文件与失败/通过运行仅在关乎持久工作流、发布流程或反复失败时关联系统仓库、PR、Issue 中提到的 Linear/Jira/Confluence/Slack/docs且对应工具可用时。节奏控制原则尊重 API 限额与用户作用域优先近期/高信号条目而非穷尽式分页除非用户明确要求完整历史。Phase 5证据矩阵Evidence Matrix写入前必须构建一张紧凑的证据矩阵列定义如下候选图家族来源引用权威级别真相类别置信度动作Feature/service/dependency 等features/infra 等文件、PR、文档、Issueauthoritative_code、repository_metadata、external_system、user_statement、agent_observationauthoritative_fact、source_observation、agent_claim、preference、timeline_event0.0–1.0commit / inbox / skip真相类别truth class的判定准则authoritative_fact文档/配置/代码中明确的归属类事实source_observation观察到的源材料但不一定是策略agent_claim多个弱信号合成的低权威结论preference仅限显式的可复用项目偏好timeline_event来自 PR、工单、release 或部署的源时间点活动不确定但有价值的发现 → 进graph inbox add。这些 truth class 不是技能文档的杜撰词汇而是 Potpie 语义变更层的正式词汇从源码结构看authoritative_fact、agent_claim、timeline_event等类别出现在语义变更降低与校验的 core 实现中如 semantic_mutation_validator.py 与 graph_contract.py写入时会经过真实的策略校验。Phase 6身份消解Identity Resolution原则先消解后链接resolve before linking。用 search-entities 做窄化查询已知条件就用具体过滤potpie graph search-entities repo service feature dependency --limit 10 potpie graph search-entities service --type Service --environment prod --limit 10 potpie graph search-entities github-or-ticket-id --source-ref github-or-ticket-ref --limit 10该命令在 CLI 层还支持--predicate、--subgraph、--scope key:value、--truth、--source-system、--since/--until、--external-id、--supporting-claims等过滤项默认 limit 为 10。消解纪律复用规范化键canonical keys若出现重复候选实体立即停下走 inbox 或需评审的修正流程绝不创建近似重复实体。这正是 Phase 8 中quality duplicate-candidates报告要兜底的东西——写入前防重与写入后查重形成闭环。Phase 7写入Propose / Verified Commitmutation JSON 以实时的graph catalog与graph describe示例为编写依据graph mutation-template只是骨架辅助不是事实来源。potpie --json graph propose --file mutation.json从 graph_propose 的实现可以看到两个细节--file可省略改读 stdin便于 Agent 管道化--ttl控制 plan 过期时间如30m、1h、2d默认1h提案是有时效性的待提交计划而非永久对象。检查提案状态后按状态分流提案状态处置invalid或有被拒绝的操作修正 mutation或放弃该弱事实conflict或重复风险回到 Phase 6 消解身份或进 inboxreview_required请求人工批准或仅在策略允许时携带所需--approved-by值提交validated/ 低风险以--verify提交potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_idgraph_commit 中--verify的语义是“读回已提交的 claim 键并执行提交后质量检查”且验证不通过时 CLI 以非零码退出EXIT_VALIDATION这对 Agent 的机械重试很友好。对大批量 Agent 生成的 mutation技能要求使用graph bulk apply并配齐 dry-run、分块chunking、manifest 与 verify。graph_bulk_apply 的实现与这一要求逐条对应--chunk-size默认 100 个语义操作/块、--start-chunk断点续跑、--dry-run只提案不提交、--continue-on-error、--verify运行后附数据平面状态、--manifest每尝试一块写一次 JSON 运行清单、--idempotency-key。其 docstring 特别强调bulk apply 是编排辅助不扫描源、不推断事实只把已选定的事实保持在与普通图更新相同的受校验工作台上——这再次印证“智能在 harness校验在 Potpie”的分工。Phase 8验证与质量门禁Quality Gategraph commit --verify会读回提交断言并做质量检查。告警或失败时按技能给定的下钻路径核查potpie graph read --subgraph features --view feature_context --scope anchor_entity_key:repo-key --limit 50 potpie graph read --subgraph infra_topology --view service_neighborhood --scope service:service --depth 2 --direction both --limit 50 potpie graph read --subgraph recent_changes --view timeline --scope repo:repo --limit 50 --format table potpie --json graph quality duplicate-candidates --limit 20 potpie --json graph quality low-confidence --limit 20 potpie --json graph quality conflicting-claims --limit 20 potpie --json graph quality orphan-entities --limit 20从 graph_read 的签名可以看到这些参数的默认行为--limit默认 12、--query-threshold默认 0.70语义相似度下限、--sort/--dedupe有auto模式timeline 视图默认按occurred_at排序与events格式输出--scope key:value[,key:value]支持anchor_entity_key:、service:、repo:等前缀化的锚定读取这正是把“我刚摄取了什么”读回来验证的机制。质量报告命令在 quality_app 中是一组只读报告除技能列出的四项外还包括stale-facts、projection-drift、entity-label-drift与summary可作为更完整的巡检清单。收尾动作若 verified commit 漏掉预期事实修正 mutation 或记录 inbox 项最终汇报三件事——摄入了什么、跳过了什么、还有什么不确定。仓库基线Repository Baseline的专门约定针对“摄取或深度理解一个仓库”这一最常见场景技能给出两条编排约定先基线、后历史基线完成前不做变更历史。用户要求深度摄取时使用 potpie-repo-baseline 技能的 deep 模式记录来源支撑的 purpose、应用类型、特性、服务/模块地图、API 契约、数据存储、集成、环境、部署形态、归属与显式项目偏好随后才用 potpie-change-timeline 处理近期或历史活动。不得从 PR 标题或 Issue 状态反推基线架构能力实体化能力表示为Feature实体仓库/服务通过PROVIDES链接到 feature仅当源材料定位到了实现位置时才使用IMPLEMENTED_IN——这与feature_context视图声明的内联关系见 graph_views.py严格一致保证写进图的关系恰好是后续读取契约要暴露的关系。来源规则Source Rules什么可以写什么只是线索技能末尾的三条来源规则是区分“线索”与“事实”的最终判据工单/Issue可以记录时间线事件、bug 模式、决策与文档但不能证明修复——除非能关联到已合并 PR、commit、部署或明确的“已交付解决”来源文档只有显式陈述时才可记录偏好、决策、Runbook 笔记、服务笔记与基础设施事实日志/转录可以记录诊断信号、调查、修复与验证原始日志不得进入描述除简短而具辨识度的错误文本外。结语这套工作流的可复现要点把整套流程压缩成可检查的清单核心是三层约束过程约束todo 车道全覆盖、子代理只读、CLI 不可用时停在提交前——保证 Agent 不会“跳步”证据约束每条断言都带来源引用、权威级别、真相类别、置信度与检索级描述truth class 与 Potpie 语义变更层的校验契约对齐闭环约束写入前search-entities防重 →propose状态分流 →commit --verify读回 →quality四报告下钻 → inbox 收容不确定项。所有命令均可在当前仓库中逐条对照视图契约见 graph_views.pyCLI 命令实现见 graph.py技能原文见 SKILL.md。这套“harness 决策 Potpie 校验”的摄取模式本质上是把 Agent 的不确定性显式地编码进了图的元数据truth class/confidence让低置信度内容可以进入 inbox 而非污染规范图从而使得机器可校验、可追溯、可回查。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考