Potpie source-ingestion 技能面向 Claude 代理的仓库知识八阶段摄取工作流【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiePotpie 的potpie-source-ingestion是内置在 Claude Code 插件模板中的一套代理技能Skill它定义了一套严格的八阶段流程当用户明确要求把某个仓库、PR、issue、文档或网页链接摄取进 Potpie 上下文图时代理harness负责发现、阅读、判定持久性事实并产出带证据的语义图变更而 Potpie 只负责校验与存储。读完本文你将掌握该技能的完整操作规程——从 pot 作用域预检、并行只读发现到证据矩阵构建、身份解析、propose/commit 写入与质量门核验——并理解其背后的 truth class 证据模型在 Potpie 上下文引擎中的源码级实现。技能定位harness 是智能Potpie 是校验器该技能定义在 potpie-source-ingestion/SKILL.md 中是 claude_plugin 插件模板下七个技能之一与 potpie-repo-baseline、potpie-change-timeline 等技能协同工作前者提供基线采集与时间线采集本技能负责整体的摄取编排。技能开篇即确立了职责边界The harness is the intelligence: it gathers source data, reads it, decides what is durable, resolves identity, and writes semantic graph mutations with evidence.Potpie validates and stores; it does not decide what source material means.也就是说源码/文档意味着什么这一语义判断由代理做出Potpie 端只承担契约校验、身份解析辅助与存储。这一分工与 Potpie 上下文引擎的设计一致从源码结构看语义变更在进入图之前必须经过验证层见 semantic_mutation_validator.py而graph bulk apply的 docstring 也明确写着它不扫描源码、不推断事实只是把代理已选定的批量事实走同一套已校验的 workbench 通道写入。不可协商的硬性约束Non-Negotiables技能为每次摄取设定了五条不可协商规则它们共同构成证据驱动写入的底线todo 驱动每个仓库或多源摄取都必须先建 todo/清单禁止从 README 直接跳到图写入本地检查是必须项理解仓库必须实际读文件rg、rg --files、git及结构化工具禁止运行遗留的、确定性的 ingestion/scanner 命令——这类命令会遍历目录树并直接把扫描结果写成图事实子代理只做只读切片主代理独占源选择、身份解析、变更提案、提交与最终综合写入前置条件只有当每条必做的发现 lane 已完成、明确不可用、或被用户显式划出范围之外时才允许写入每条写入必须携带source refs证据引用、source authority来源权威、truth class真实度类别、confidence置信度、compact summary 与检索级描述。这最后一条约束直接对应 Potpie 数据契约中的字段体系。下面各阶段正是围绕先发现、后证据、再写入、终核验展开。Phase 0作用域定义与预检预检的目标是把要摄取什么、写到哪里、读哪些视图在动手前固化下来。技能要求先定义源类型、pot/project、repo/path/URL、时间窗、目标记忆形态baseline、history、docs、infra、debug memory、preferences 或 all然后执行一组结构化检查potpie --json pot info potpie --json source list potpie --json graph status potpie --json graph catalog --task harness-led source ingestion如果仓库尚未注册只注册元数据并在 pot 作用域有歧义时显式传--potpotpie source add repo . --pot pot-id-or-name随后要在撰写任何变更之前描述将要写入/读取的图视图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这里列出的五个subgraph.view组合并非随意示例而是 Potpie 视图契约中真实注册的视图在 graph_views.py 中可以看到feature_context、service_neighborhood、prior_occurrences、preferences_for_scope等视图名均按全限定subgraph.view形式定义。graph describe命令在 CLI 中对应 graph.py 的describe子命令--examples参数返回的示例 JSON 是后续撰写变更的活模板。技能的最后一条预检规则值得注意如果 CLI 不可用或损坏继续发现过程、构建拟议的证据矩阵但在提交图写入之前停下——即发现与计划不依赖写入路径可用写入则强依赖。Phase 1Todo 计划与发现 lane技能要求为仓库摄取至少建立以下发现 lane 并逐一打勾Scope/preflight作用域、pot、源注册与图契约预检产品/文档README、docs、ADR、runbook、公开文档、关联网站本地仓库地图manifest、packages/apps、入口点、路由/API 面、测试、框架配置、主要模块、生成的 API 规格运行时/部署Dockerfile、compose、Kubernetes、Terraform、CI workflow、部署脚本、环境模板、feature flagsAPI/数据/集成服务客户端、适配器、数据存储、模型、队列、认证提供方、外部 APIGitHub/历史仓库元数据、topics、release/tag、近期合并 PR、开放 issue、关联工单/文档、CI/部署记录偏好/工作流显式的编码风格、测试命令、本地开发设置、发布/部署/runbook 工作流综合证据矩阵、候选图事实、身份解析、提案、verified commit 与门驱动的后续检查。lane 完成时更新 todo不确定但可能有价值的发现放入 inbox而不是硬塞进规范图声明——这条宁可进收件箱、不可造近义重复的原则贯穿整个流程Phase 6 再次出现。Phase 2并行只读发现与子代理提示词在工具允许时技能建议将互不重叠的只读切片并行化并给出了五类子代理的推荐提示词。每类提示词都遵循同一结构指定检查范围、指定要返回的结构化发现、并以Do not write mutations收尾。代表性提示词如下文档/产品Read README, docs, ADRs, runbooks, package metadata, and linked product pages. Return product purpose, features, explicit decisions, preferences, workflows, and source refs. Do not write mutations.本地架构Inspect manifests, top-level apps/packages, entrypoints, route/API surfaces, tests, and framework config. Return service/module map, likely features, explicit source files, uncertainty, and no mutations.运行时/部署Inspect Docker/compose/Kubernetes/Terraform/CI/deploy/env templates. Return environments, deploy shape, config variables, workflows, datastores, and source refs. Do not write mutations.API/数据/集成Inspect route specs, client/adapters, models, datastores, queues, auth, and external integrations. Return candidate APIContract/DataStore/Adapter/Dependency facts with evidence. No mutations.GitHub 历史Use GitHub tools/CLI for repo metadata, releases, recent merged PRs, open issues, linked tickets/docs, and CI signal. Return timeline, fixes, decisions, bug patterns, and source refs. No mutations.偏好Find explicit preferences in docs, config, tests, contribution guides, PR templates, and comments. Return only explicit reusable policies with evidence. No mutations.主代理在子代理运行期间应继续处理非重叠的发现切片。从源码结构看子代理只读、主代理写入的约束与 Potpie 的写入通道设计相符所有写操作都收敛到 graph.py 中的propose/commit/bulk apply等受控命令不存在让多个执行者各自扫描即写入的旁路。Phase 3本地仓库检查目标技能强调结构化、有边界的本地检查给出了一组rg范例覆盖 manifest、部署面、路由面、外部依赖与测试命令五个维度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* rg -n FastAPI|APIRouter|express\\(|router\\.|Django|Flask|NextResponse|route\\( . 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并明确两条纪律不要仅凭文件名推断持久事实文件只用来定位真理之源随后要读相关代码片段或已撰写的文档。这正是 Non-Negotiables 中禁止 scanner 驱动写入的正面表述——rg --files找的是证据位置而非证据本身。Phase 4托管源/GitHub 水合对 GitHub 上的仓库技能要求使用代理自身的集成工具/连接器GitHub app/MCP/CLI 工具等而不是 Potpie 的队列摄取命令并列出应采集的清单仓库元数据全名、默认分支、描述、topics、可见性、主页、license、archived/fork 状态文档README、contributing guide、CODEOWNERS、PR/issue 模板、仓库内链接的文档Releases/tags仅当它们描述已交付行为或部署节奏时近期合并 PR标题、正文、作者、合并日期、分支、标签、关联 issue、变更文件名仅在作者文字不足时才拉取补丁开放/高信号 issue标题、正文、标签、状态、作者、可用时的评论issue 可以记录诉求/缺陷但不能证明修复CI/workflowsworkflow 文件以及仅当与持久工作流、发布流程或反复失败相关时的通过/失败运行记录关联系统仓库、PR、issue 中提到的 Linear/Jira/Confluence/Slack/文档在对应工具可用时。同时要求尊重 API 限额与用户作用域优先近期/高信号条目除非用户明确要求全量历史否则不做穷尽式分页。Phase 5证据矩阵——truth class 的源码级实现写入前的核心产物是一张紧凑矩阵CandidateGraph familySource refsAuthorityTruth classConfidenceActionFeature/service/dependency/etc.features/infra/etc.file, PR, doc, issueauthoritative_code, repository_metadata, external_system, user_statement, agent_observationauthoritative_fact, source_observation, agent_claim, preference, timeline_event0.0-1.0commit / inbox / skip技能给出的选择准则authoritative_fact显式的文档/配置/代码所有权事实source_observation观察到的源码材料可能并非策略agent_claim来自多个弱信号的、较低权威度的综合preference仅限显式、可复用的项目偏好timeline_event来自 PR、工单、release 或部署的源时间活动不确定但可能有用的发现 →graph inbox add。这些 truth class 不是技能自造的词汇而是 Potpie 数据契约中的一等字段。在 graph_contract.py 中TruthClass枚举定义了 V1.5 的真实度词汇表authoritative_fact、source_observation、agent_claim、user_decision、preference、timeline_event、quality_finding且默认值是agent_claim——这正呼应了技能低权威综合用agent_claim的准则。两个工程细节直接约束写入行为EVIDENCE_REQUIRED_TRUTH_CLASSES {authoritative_fact, source_observation}断言客观外部/代码事实的声明必须带证据引用LOW_AUTHORITY_TRUTH_CLASSES {agent_claim, quality_finding}这类软声明本身就是非伪装成事实的声明不强制证据。此外每个 truth class 都会通过TRUTH_TO_EVIDENCE_STRENGTH映射到排序器的证据强度如authoritative_fact→deterministic、agent_claim→stated即声明的真实度等级直接决定其在检索排序中的权重。技能矩阵中的Source authority列authoritative_code / repository_metadata / external_system / user_statement / agent_observation与Truth class列的区分正对应契约中来源权威与该事实如何被确知这两个不同维度。Phase 6身份解析——先解析再链接建立实体链接前必须先解析身份技能给出三组带过滤器的检索命令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规则只有一句但很硬复用规范键出现重复候选时停下走 inbox 或需审校的更正流程不要创建近义重复实体。对应的 CLI 入口是 graph.py 中的search-entities子命令后续的清理手段则由graph quality duplicate-candidates等只读质量报告承担见 Phase 8。Phase 7写入——propose、verified commit 与 bulk apply技能规定语义变更 JSON 应基于实时的graph catalog与graph describe示例来撰写graph mutation-template只是骨架辅助工具、不是真理之源。单条写入走两步potpie --json graph propose --file mutation.json然后检查提案状态、diff、warnings、被拒操作、冲突与 review 标志并按状态分流invalid或被拒操作 → 修变更或放弃该弱事实conflict或重复风险 → 解决身份或转 inboxreview_required→ 请求批准或策略允许时仅在携带所需--approved-by值的情况下提交validated/低风险 → 用--verify提交。potpie --json graph commit plan_id --verify potpie --json graph history --plan plan_id从 CLI 源码可以核对这些参数的真实语义graph_propose 支持--file省略则读 stdin、--ttl计划过期如30m/1h/2d默认1h、--pot提案失败以EXIT_VALIDATION退出码返回graph_commit 支持--approved-by中等风险审批的 user-ref、--verify读回已提交的 claim 键并执行提交后质量检查且当--verify读回失败时同样以验证错误码退出。对大批量代理撰写的变更技能建议使用graph bulk apply并强调 dry-run、分块、manifest 与 verify 四件套且bulk apply 只能应用 harness 已经选定的事实。CLI 侧的完整参数在 graph_bulk_apply 中可核对--chunk-size每块语义操作数默认 100、--start-chunk断点续跑的 1 起始块索引、--dry-run只提案不提交、--continue-on-error、--verify、--manifest每块尝试后写 JSON 运行清单、--idempotency-key基础幂等键按需追加块后缀、--ttl、--approved-by、--pot。其 docstring 明确定位This is an orchestration helper for agent-authored semantic mutations. It does not scan sources or infer facts; it keeps high-volume writes on the same validated workbench path as ordinary graph updates.——即批量写入与单条写入共享同一条已校验的 workbench 路径。Phase 8校验与质量门graph 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 20quality子命令组在 CLI 中实际注册的报告面比技能列出的四张更宽——还包括summary、stale-facts、projection-drift、entity-label-drift见 graph.py质量报告均为只读。若 verified commit 漏掉了预期事实技能的处置是修变更或记一条 inbox 条目并且收尾时必须向用户汇报三件事摄入了什么、跳过了什么、什么仍不确定。仓库基线与来源规则技能最后给出两条针对仓库摄取的专项约束。基线优先于历史仓库摄取先跑 baseline 再跑变更历史当用户要求深度摄取/理解一个仓库时用potpie-repo-baseline技能对应 potpie-repo-baseline/SKILL.md的 deep 模式记录有源支撑的用途、应用类型、features、服务/模块地图、API 契约、数据存储、集成、环境、部署形态、所有权与显式项目偏好之后再用potpie-change-timeline处理近期或历史活动。禁止从 PR 标题或 issue 状态推断基线架构。能力表示约定把能力表示为Feature实体仓库/服务与 feature 之间用PROVIDES关联仅当源码能定位实现位置时才用IMPLEMENTED_IN。这两个边类型是 Potpie 本体中的一等词汇在 ontology.py 中PROVIDES与IMPLEMENTED_IN均被定义注册注释也强调这些能力关系是声明出来的via claims而非推断出来的与技能的纪律闭环一致。来源规则划定了不同材料能支撑哪些声明工单/issue 可以记录时间线事件、bug 模式、决策与文档但除非绑定到合并 PR、commit、部署或显式的已交付解决源否则不能证明修复文档只有在显式写明时才能支撑偏好、决策、runbook 笔记、服务笔记与基础设施事实日志/转录可以记录诊断信号、调查、修复与验证原始日志不进描述字段除简短的、有辨识度的错误文本外。小结一条可复现的摄取纪律把potpie-source-ingestion技能与 Potpie CLI 的源码放在一起看可以提炼出这套工作流的核心纪律发现与写入分离并行只读发现子代理 rg本地检查 GitHub 水合在前任何写入都发生在发现 lane 全部收口之后证据先行每条声明在证据矩阵中先回答来源、权威度、真实度类别、置信度其中authoritative_fact/source_observation在契约层被强制要求证据引用写入受控单条走propose → (按状态分流) → commit --verify批量走bulk apply的 dry-run 分块 manifest verify两条路径共享同一套已校验的 workbench 通道不确定进 inbox重复风险与弱信号一律流向graph inbox与质量报告duplicate-candidates、low-confidence、conflicting-claims、orphan-entities而不是被写成规范声明。这套技能本质上是把代理是语义智能、引擎是契约守门的架构翻译成一份可被 Claude Code 直接执行的操作规程其每一条命令都能在 potpie/cli/commands/graph.py 与 graph_contract.py 中找到对应的实现与验证点。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考