Potpie 能力归属合规记录全解读PCAP-001 至 PCAP-012 如何锁定「能力导向」源码布局【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本文围绕仓库中的最终版合规记录 spec/conformance/potpie-capabilities.md记录 IDCONF-POTPIE-CAPABILITIES展开完整解读 Potpie 项目如何以 12 条行为契约PCAP-001PCAP-012验证「能力优先capability-first」的源码布局根级源码按显式能力组织、跨能力组合集中、旧potpie.product命名空间彻底删除、且搬迁过程不改变任何受支持的 CLI / 守护进程 / 配置 / pot / 技能行为。读完本文你将掌握该合规记录的结构化证据链PCAP-E1E4、12 条行为的逐项含义、对应能力包的源码落地形态以及仓库中永久架构测试tests/characterization/test_potpie_capability_ownership.py如何防止布局在未来发生漂移。这份记录在验证什么CONF-POTPIE-CAPABILITIES 是一份record_status: final的合规记录针对能力契约 SPEC-POTPIE-CAPABILITIESrevision 1spec refb23b6cb9…与实现提交ecf37757561166f94a66a7375483cb48b6b5ef58逐项核验。其 Scope 明确说明本次验证覆盖12 个活动能力行为PCAP-001PCAP-012在完成后的能力优先源码布局中的实现与行为保持证据进程安全process-safe的配置与 pot 持久化以及元数据级 pot 服务Ledger 游标持久化通过 Context Engine 本地 JSON 存储的锁与原子替换机制在多个 CLI 进程之间串行化。从规范层面看这份记录要回答的根本问题是源码目录应该按「它属于哪一层」如 product/control-plane组织还是按「它拥有什么能力」组织。契约选择了后者并明确把可独立导入的 Context Engine 分发potpie_context_engine排除在根能力之外。行为追踪表12 条能力行为逐项解读记录正文以一张行为追踪表给出全部 12 条行为的实现声明implementation claim、验证结果、证据引用与备注。下表完整复刻记录内容Behavior IDImplementation claimVerification resultEvidenceNotesPCAP-001completepassedPCAP-E1, PCAP-E2根源码按能力归属不存在通用伞形命名空间。PCAP-002completepassedPCAP-E1, PCAP-E3配置能力拥有根级 home 解析与进程安全持久化。PCAP-003completepassedPCAP-E1, PCAP-E3pot 拥有元数据、策略、默认值与进程安全持久化图重置仍归引擎所有。PCAP-004completepassedPCAP-E1, PCAP-E3技能拥有目录、校验、策略与目标targets。PCAP-005completepassedPCAP-E1, PCAP-E3setup 拥有编排与生命周期接缝。PCAP-006completepassedPCAP-E1, PCAP-E3本地身份扩展既有认证能力。PCAP-007completepassedPCAP-E1, PCAP-E3Agent 上下文组合是顶层门面。PCAP-008completepassedPCAP-E1, PCAP-E2运行时组合是唯一的具体装配点。PCAP-009completepassedPCAP-E2, PCAP-E4引擎生产代码不导入根 Potpie 命名空间。PCAP-010completepassedPCAP-E2, PCAP-E4potpie.product及其别名均不存在。PCAP-011completepassedPCAP-E3, PCAP-E4受支持的运行时与进程安全持久化行为保持不变。PCAP-012completepassedPCAP-E2, PCAP-E4不存在重建旧内部导入的兼容 API。各行为在契约中的规范表述根据 spec/modules/potpie-capabilities.md 的 Normative Requirements 小节这 12 条行为各有明确的 MUST 语义且带有 authorityuser:dsantra与 observation搬迁前的code:potpie/product930632fb…路径作为「搬迁前基线」的证据锚点PCAP-001根 Potpie 应用源码必须按显式拥有的能力组织而非按通用产品层/控制平面命名空间组织PCAP-002配置能力必须拥有根级 home 解析与持久化本地配置行为PCAP-003pots 能力必须拥有 pot 与 source 契约、生命周期策略、仓库默认值与本地持久化PCAP-004skills 能力必须拥有目录、命令片段校验、安装/更新/移除策略与 Agent 特定目标PCAP-005setup 能力必须拥有首次运行编排及其安装、状态供给、迁移接缝PCAP-006本地身份生命周期必须扩展既有认证能力而不是再造第二个认证所有者PCAP-007组合图行为与多个根能力的服务必须位于所有单个能力命名空间之外即顶层potpie.agent_contextPCAP-008根运行时组合必须是跨能力选择具体实现的生产装配点potpie.runtime.compositionPCAP-009Context Engine 生产代码不得导入根能力代码依赖方向为「根 → 引擎」禁止反向PCAP-010最终根源码树不得包含potpie.product命名空间、其转发别名或其兼容性再导出PCAP-011搬迁必须保持 CLI、守护进程、setup、配置、pot、source、技能、持久化与 Context Engine 行为不变PCAP-012分支本地的potpie.product.*实现导入不得被视为受支持的公开 Python 兼容契约。值得注意的是记录把「行为已通过」作为结论输出而规范的正文spec 文件刻意不做实现声明——「This contract makes no implementation or verification claim」实现与验证证据全部沉淀在合规记录与架构测试中这正是本记录的价值所在。能力归属与边界谁拥有什么契约中的 Ownership And Boundaries 表界定了每个能力「拥有」与「明确排除」的范围这是判断搬迁是否正确、是否越界的唯一依据CapabilityOwns拥有Excludes排除ConfigurationPotpie home 解析、持久化本地配置、公共值脱敏pot/source 状态、技能安装、Context Engine 设置归属Potspot 与 source 契约、生命周期策略、仓库默认值、本地持久化图域语义、setup 编排、Agent 呈现Skills内置目录、校验、安装/更新/移除策略、Agent 特定目标setup 编排、图域行为、运行时装配Setup首次运行编排、安装接缝、状态供给、迁移setup 之外的能力实现选择、CLI 呈现Authentication本地身份生命周期叠加既有凭据契约与适配器Context Engine 授权策略、重复认证归属Agent context composition面向产品的 graph/pot/skill 状态组合底层能力归属或图域语义Runtime composition具体根能力实现的选择与接线能力策略、动态服务查找、Context Engine 域语义契约同时强调Context Engine 仍是独立可导入的分发且不拥有任何根 Potpie 能力。从依赖不变量看依赖方向只能是「根 Potpie → Context Engine」能力搬迁不允许产生反向依赖、不允许合并根/引擎服务组、不允许把图域行为搬进根能力。源码级佐证能力包的落地形态当前仓库根目录potpie/下的布局与记录描述完全一致顶层为agent_context.py与auth/、config/、pots/、setup/、skills/、runtime/、daemon/、cli/等能力包。下面按能力逐一给出源码证据所有路径均可在仓库中直接打开核验。配置能力potpie/configpotpie/config/local_paths.py 中的default_home()是根级 home 解析的唯一入口优先读取环境变量CONTEXT_ENGINE_HOME否则回退到~/.potpie。这正是 PCAP-002「根级 home 解析归配置能力」的实现事实——根能力不再通过 Context Engine 适配器获取 home。potpie/config/contracts.py 定义ConfigService协议ensure_home、write_defaults(plan)从 setup 计划写入默认值且保留用户已设值、get/set、list_public对密钥类键脱敏、probe。potpie/config/local.py 中的LocalConfigService把状态落在home/config.json写入时使用setdefault保证幂等重跑is_secret_config_keyL82-L87与public_config_valueL90-L95实现「公共值脱敏」——按token/secret/password/api_key/credential等标记词整词匹配避免tokenizer、max_tokens误伤命中后输出redacted。potpie/config/local_state.py 的local_json_transaction上下文管理器实现进程安全持久化线程锁 文件锁POSIX 用fcntl.flockWindows 用msvcrt.locking 临时文件fsync后os.replace原子替换。这条链路正是记录 Scope 中「process-safe configuration」以及「Ledger 游标跨进程串行化」的技术底座。pots 能力potpie/potspotpie/pots/contracts.py 定义PotManagementService协议pot 生命周期init/list_pots/create_pot/use_pot/rename_pot/archive_pot、source 注册表、仓库默认路由repo_default/set_repo_default等与aggregate_status汇总。potpie/pots/local_store.py 的LocalPotStore把状态落在home/pots.json结构为{pots: {}, active: None, sources: {}, repo_defaults: {}}所有变更同样走local_json_transaction事务create按名称幂等复用 pot_repo_identity_key统一规范化本地路径、git与://形式的仓库身份。文件头注释还明确点出这是 flat-file POC真实控制平面将演进为本地状态数据库SQLite 迁移但接口归属不变。skills 能力potpie/skillspotpie/skills/contracts.py 定义SkillManager协议list/install/update/remove/status/nudge/add。注释明确了能力边界——技能是「教会 Agent harness 使用 potpie CLI 与四个上下文工具的配方」不是图事实也不是新的 Agent 工具Agent 只会在context_status里看到建议性SkillNudge块缺失/过期技能及精确安装命令安装是人工/CLI 动作。AgentTargetPort是支持新 harness 的扩展接缝实现该端口并注册给SkillManager管理器持有目录/漂移逻辑目标端持有「文件落在哪里」的机制。当前 targets 包括ClaudeAgentTarget、CodexAgentTarget、CursorAgentTarget、OpenCodeAgentTarget等见架构测试的EXPECTED_CAPABILITY_SYMBOLS。setup 能力potpie/setuppotpie/setup/orchestrator.py 中的_SEAM_PLAN是唯一事实来源按依赖顺序列出 12 个 setup 步骤config → installer → embeddings.model → backend.provision → pot.init → state_store.provision → migrator.migrate → pot.default → daemon → auth → source → skills并标注每步 owner 与动作模板。previewdry-run、plan与run全部由它派生hardness 由_SOFT_STEPSauth/source/skills/embeddings.model 永不阻塞与_HOST_GATEDinstaller/daemon 仅在 detached daemon 模式下为 hard推导L98-L107。runL191-L241逐步骤把CapabilityNotImplemented折叠为not_implemented、其他异常折叠为failed——setup 永远不因单个组件崩溃而整体失败。这就是契约中「setup 拥有编排与生命周期接缝」的具体呈现。认证能力potpie/authpotpie/auth/ports/identity.py 的AuthService协议与AuthIdentityL17-L24把本地身份生命周期收纳进既有认证能力potpie/auth/adapters/local_identity.py中的LocalAuthService是其本地实现。契约特意强调与集成凭据存储、Provider 认证共享potpie.auth能力不合并其持久化、生命周期或策略——这正是 PCAP-006「扩展而非再造」的落地。Agent 上下文组合potpie/agent_context.pypotpie/agent_context.py 中的AgentContextService是顶层门面四个工具里resolve/search/record直接委托GraphService只有status是组合操作——把 pot/source 状态、图数据平面状态与SkillManager的建议 nudge 汇入一个StatusReport并按状态生成recommended_next_action提示运行potpie setup、potpie backend doctor或potpie resolve。它不属于 pots、skills 或 Context Engine 任何一方验证了 PCAP-007。运行时组合potpie/runtime/composition.pypotpie/runtime/composition.py 的build_local_runtime是唯一的具体装配点PCAP-008它同时构造独立的根服务组RootRuntimeServicesauth/config/daemon/installer/ledger/pots/setup/skills/backend/profile与引擎服务组LocalEngineServicespots/agent_context/graph/graph_workbench/backend/nudge把LocalPotStore、LocalConfigService、DefaultSkillManager、DefaultSetupOrchestrator、AgentContextService等具体实现显式接线。所有能力模块采用显式构造器依赖与模块导入没有动态注册表、全局服务定位器或第二条生产装配路径。可复现证据链PCAP-E1E4记录将证据分为四组均可独立复现PCAP-E1 — 固定提交的所有权审查pinned ownership review在实现提交ecf37757…上审查potpie/{agent_context.py,config,pots,skills,setup,auth,runtime}与根包元数据。PCAP-E2 — 永久所有权门禁permanent ownership gatestests/characterization/test_potpie_capability_ownership.py 验证精确所有者、仅文档的包初始化器、无替代伞形、无旧命名空间/导入/别名/再导出、唯一的具体运行时装配、分离的服务组、包元数据与独立包通道组合边界结果18 passed。PCAP-E3 — 行为保持behavior preservation完整根测试套件报告1447 passed, 4 skipped, 1 deselected独立 Context Engine 套件报告1153 passed, 32 skipped, 6 warnings。PCAP-E4 — 打包与隔离导入packaging and isolated importswheel 与 sdist 均构建成功根产物包含能力包且不含potpie/product全新引擎专用环境与根环境均通过隔离验证已安装的 CLI 与守护进程入口点保持不变。这些数字是记录作者在执行时采集的固定事实引用时以 spec/conformance/potpie-capabilities.md 为准。永久所有权门禁架构测试如何锁定布局test_potpie_capability_ownership.py是 PCAP-E2 的实现载体也是未来任何布局漂移的第一道防线。其关键断言包括FORBIDDEN_NAMESPACE potpie. productL17test_product_namespace_has_no_source_imports_aliases_or_reexports通过 AST 全量扫描要求残留源码、imports、sys.modules别名写入与字符串字面量全部为空集FORBIDDEN_SOURCE_UMBRELLAS (app, application, capabilities, control_plane, product)L90-L96test_no_replacement_source_umbrella_exists拒绝任何「换名不换本质」的通用伞形EXPECTED_CAPABILITY_SYMBOLSL31-L81把 20 个文件与 60 余个符号逐一绑定如potpie/config/local_paths.py→default_home、potpie/agent_context.py→AgentContextService任何符号搬家都会使test_capability_modules_exist_and_own_their_expected_symbols失败DOCUMENTATION_ONLY_INITIALIZERSL83-L88要求config/pots/setup/skills的__init__.py仅含一条文档字符串——禁止把包初始化器变成服务定位器或再导出面CONCRETE_ASSEMBLY_TYPESL98-L115列出 14 个具体装配类型test_runtime_composition_is_the_only_concrete_cross_capability_assembly断言它们只允许被potpie/runtime/composition.py实例化test_root_and_engine_service_groups_remain_separated通过RootRuntimeServices与LocalEngineServices的 dataclass 字段断言两组服务互不重叠test_root_distribution_metadata_owns_capability_packages读取pyproject.toml断言 wheel 包为[potpie]、sdist 包含全部能力路径且不含product、入口点严格为potpie potpie.cli.main:main与potpie-daemon potpie.daemon.__main__:maintest_independent_package_installation_lane_remains_enforced检查 CI 工作流与 scripts/verify_context_package_isolation.py 中的find_spec(potpie_context_engine)/find_spec(potpie)隔离验证。这套测试与 ADR-0011 的 Consequences 相呼应架构测试负责在搬迁后持续守住「归属、分发独立、组合方向」三条红线。关联契约检查与聚合结果记录同时核验了六份关联契约全部 passedSpec IDRevisionSpec refResultSPEC-PRODUCT1047cbe06…passedSPEC-SYSTEM1047cbe06…passedSPEC-CONTEXT-ENGINE1047cbe06…passedSPEC-POTPIE-RESOURCE-MANAGER2a8c03337…passedSPEC-DAEMON2e73ebdbd…passedSPEC-CLI1047cbe06…passed聚合结果为passed全部 12 个活动 Potpie 能力行为均有 complete 实现声明并通过验证。Known Gaps 一节明确PCAP-001PCAP-012 无已知缺口但本记录不将新的内部能力路径确立为受支持的公开 Python API——这是 PCAP-012 的纪律性边界避免把「搬迁后的模块路径」误读为「公开兼容契约」。新鲜度、记录更新约定与历史谱系记录的 Freshness 一节说明新鲜度通过比较固定的规范、实现、依赖与证据身份与所选当前目标推导而来绝不是由作者随意标注的契约或索引状态。在 spec/conformance/index.md 中还能看到配套的更新约定仅当持久验证身份变化接受的spec_id/spec_revision/spec_ref、选定的implementation_ref、范围内行为或依赖、可复现证据或聚合结论、以及 PR-head 与 base-commit 组合时才更新稳定记录新记录以previous_record_id/previous_record_ref/previous_record_path指向紧邻的前一版本旧 Git 对象不被改动若持久身份未变则把常规结果留在 CI 而不是发布新记录。本记录自身的历史谱系即从CONF-POTPIE-CAPABILITIES-2026-08-24-01基线提交3e5edfd5…处的potpie-capabilities-2026-08-24.md迁移而来符合「稳定路径 Git 历史承载旧版本」的约定。小结CONF-POTPIE-CAPABILITIES 这份记录的价值在于把「架构决策」转化为「可机器验证的契约」决策层由 ADR-0011 选定能力布局与四阶段搬迁次序契约层由 SPEC-POTPIE-CAPABILITIES 固化 12 条 MUST验证层由本记录与永久架构测试锁定实现。对想要深入代码的读者建议按「测试 → 契约 → 实现」的顺序阅读tests/characterization/test_potpie_capability_ownership.py 给出所有符号级断言potpie/runtime/composition.py 展示装配全貌再沿potpie/{config,pots,skills,setup,auth}逐一对照能力实现。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Potpie 能力归属合规记录全解读：PCAP-001 至 PCAP-012 如何锁定「能力导向」源码布局
Potpie 能力归属合规记录全解读PCAP-001 至 PCAP-012 如何锁定「能力导向」源码布局【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本文围绕仓库中的最终版合规记录 spec/conformance/potpie-capabilities.md记录 IDCONF-POTPIE-CAPABILITIES展开完整解读 Potpie 项目如何以 12 条行为契约PCAP-001PCAP-012验证「能力优先capability-first」的源码布局根级源码按显式能力组织、跨能力组合集中、旧potpie.product命名空间彻底删除、且搬迁过程不改变任何受支持的 CLI / 守护进程 / 配置 / pot / 技能行为。读完本文你将掌握该合规记录的结构化证据链PCAP-E1E4、12 条行为的逐项含义、对应能力包的源码落地形态以及仓库中永久架构测试tests/characterization/test_potpie_capability_ownership.py如何防止布局在未来发生漂移。这份记录在验证什么CONF-POTPIE-CAPABILITIES 是一份record_status: final的合规记录针对能力契约 SPEC-POTPIE-CAPABILITIESrevision 1spec refb23b6cb9…与实现提交ecf37757561166f94a66a7375483cb48b6b5ef58逐项核验。其 Scope 明确说明本次验证覆盖12 个活动能力行为PCAP-001PCAP-012在完成后的能力优先源码布局中的实现与行为保持证据进程安全process-safe的配置与 pot 持久化以及元数据级 pot 服务Ledger 游标持久化通过 Context Engine 本地 JSON 存储的锁与原子替换机制在多个 CLI 进程之间串行化。从规范层面看这份记录要回答的根本问题是源码目录应该按「它属于哪一层」如 product/control-plane组织还是按「它拥有什么能力」组织。契约选择了后者并明确把可独立导入的 Context Engine 分发potpie_context_engine排除在根能力之外。行为追踪表12 条能力行为逐项解读记录正文以一张行为追踪表给出全部 12 条行为的实现声明implementation claim、验证结果、证据引用与备注。下表完整复刻记录内容Behavior IDImplementation claimVerification resultEvidenceNotesPCAP-001completepassedPCAP-E1, PCAP-E2根源码按能力归属不存在通用伞形命名空间。PCAP-002completepassedPCAP-E1, PCAP-E3配置能力拥有根级 home 解析与进程安全持久化。PCAP-003completepassedPCAP-E1, PCAP-E3pot 拥有元数据、策略、默认值与进程安全持久化图重置仍归引擎所有。PCAP-004completepassedPCAP-E1, PCAP-E3技能拥有目录、校验、策略与目标targets。PCAP-005completepassedPCAP-E1, PCAP-E3setup 拥有编排与生命周期接缝。PCAP-006completepassedPCAP-E1, PCAP-E3本地身份扩展既有认证能力。PCAP-007completepassedPCAP-E1, PCAP-E3Agent 上下文组合是顶层门面。PCAP-008completepassedPCAP-E1, PCAP-E2运行时组合是唯一的具体装配点。PCAP-009completepassedPCAP-E2, PCAP-E4引擎生产代码不导入根 Potpie 命名空间。PCAP-010completepassedPCAP-E2, PCAP-E4potpie.product及其别名均不存在。PCAP-011completepassedPCAP-E3, PCAP-E4受支持的运行时与进程安全持久化行为保持不变。PCAP-012completepassedPCAP-E2, PCAP-E4不存在重建旧内部导入的兼容 API。各行为在契约中的规范表述根据 spec/modules/potpie-capabilities.md 的 Normative Requirements 小节这 12 条行为各有明确的 MUST 语义且带有 authorityuser:dsantra与 observation搬迁前的code:potpie/product930632fb…路径作为「搬迁前基线」的证据锚点PCAP-001根 Potpie 应用源码必须按显式拥有的能力组织而非按通用产品层/控制平面命名空间组织PCAP-002配置能力必须拥有根级 home 解析与持久化本地配置行为PCAP-003pots 能力必须拥有 pot 与 source 契约、生命周期策略、仓库默认值与本地持久化PCAP-004skills 能力必须拥有目录、命令片段校验、安装/更新/移除策略与 Agent 特定目标PCAP-005setup 能力必须拥有首次运行编排及其安装、状态供给、迁移接缝PCAP-006本地身份生命周期必须扩展既有认证能力而不是再造第二个认证所有者PCAP-007组合图行为与多个根能力的服务必须位于所有单个能力命名空间之外即顶层potpie.agent_contextPCAP-008根运行时组合必须是跨能力选择具体实现的生产装配点potpie.runtime.compositionPCAP-009Context Engine 生产代码不得导入根能力代码依赖方向为「根 → 引擎」禁止反向PCAP-010最终根源码树不得包含potpie.product命名空间、其转发别名或其兼容性再导出PCAP-011搬迁必须保持 CLI、守护进程、setup、配置、pot、source、技能、持久化与 Context Engine 行为不变PCAP-012分支本地的potpie.product.*实现导入不得被视为受支持的公开 Python 兼容契约。值得注意的是记录把「行为已通过」作为结论输出而规范的正文spec 文件刻意不做实现声明——「This contract makes no implementation or verification claim」实现与验证证据全部沉淀在合规记录与架构测试中这正是本记录的价值所在。能力归属与边界谁拥有什么契约中的 Ownership And Boundaries 表界定了每个能力「拥有」与「明确排除」的范围这是判断搬迁是否正确、是否越界的唯一依据CapabilityOwns拥有Excludes排除ConfigurationPotpie home 解析、持久化本地配置、公共值脱敏pot/source 状态、技能安装、Context Engine 设置归属Potspot 与 source 契约、生命周期策略、仓库默认值、本地持久化图域语义、setup 编排、Agent 呈现Skills内置目录、校验、安装/更新/移除策略、Agent 特定目标setup 编排、图域行为、运行时装配Setup首次运行编排、安装接缝、状态供给、迁移setup 之外的能力实现选择、CLI 呈现Authentication本地身份生命周期叠加既有凭据契约与适配器Context Engine 授权策略、重复认证归属Agent context composition面向产品的 graph/pot/skill 状态组合底层能力归属或图域语义Runtime composition具体根能力实现的选择与接线能力策略、动态服务查找、Context Engine 域语义契约同时强调Context Engine 仍是独立可导入的分发且不拥有任何根 Potpie 能力。从依赖不变量看依赖方向只能是「根 Potpie → Context Engine」能力搬迁不允许产生反向依赖、不允许合并根/引擎服务组、不允许把图域行为搬进根能力。源码级佐证能力包的落地形态当前仓库根目录potpie/下的布局与记录描述完全一致顶层为agent_context.py与auth/、config/、pots/、setup/、skills/、runtime/、daemon/、cli/等能力包。下面按能力逐一给出源码证据所有路径均可在仓库中直接打开核验。配置能力potpie/configpotpie/config/local_paths.py 中的default_home()是根级 home 解析的唯一入口优先读取环境变量CONTEXT_ENGINE_HOME否则回退到~/.potpie。这正是 PCAP-002「根级 home 解析归配置能力」的实现事实——根能力不再通过 Context Engine 适配器获取 home。potpie/config/contracts.py 定义ConfigService协议ensure_home、write_defaults(plan)从 setup 计划写入默认值且保留用户已设值、get/set、list_public对密钥类键脱敏、probe。potpie/config/local.py 中的LocalConfigService把状态落在home/config.json写入时使用setdefault保证幂等重跑is_secret_config_keyL82-L87与public_config_valueL90-L95实现「公共值脱敏」——按token/secret/password/api_key/credential等标记词整词匹配避免tokenizer、max_tokens误伤命中后输出redacted。potpie/config/local_state.py 的local_json_transaction上下文管理器实现进程安全持久化线程锁 文件锁POSIX 用fcntl.flockWindows 用msvcrt.locking 临时文件fsync后os.replace原子替换。这条链路正是记录 Scope 中「process-safe configuration」以及「Ledger 游标跨进程串行化」的技术底座。pots 能力potpie/potspotpie/pots/contracts.py 定义PotManagementService协议pot 生命周期init/list_pots/create_pot/use_pot/rename_pot/archive_pot、source 注册表、仓库默认路由repo_default/set_repo_default等与aggregate_status汇总。potpie/pots/local_store.py 的LocalPotStore把状态落在home/pots.json结构为{pots: {}, active: None, sources: {}, repo_defaults: {}}所有变更同样走local_json_transaction事务create按名称幂等复用 pot_repo_identity_key统一规范化本地路径、git与://形式的仓库身份。文件头注释还明确点出这是 flat-file POC真实控制平面将演进为本地状态数据库SQLite 迁移但接口归属不变。skills 能力potpie/skillspotpie/skills/contracts.py 定义SkillManager协议list/install/update/remove/status/nudge/add。注释明确了能力边界——技能是「教会 Agent harness 使用 potpie CLI 与四个上下文工具的配方」不是图事实也不是新的 Agent 工具Agent 只会在context_status里看到建议性SkillNudge块缺失/过期技能及精确安装命令安装是人工/CLI 动作。AgentTargetPort是支持新 harness 的扩展接缝实现该端口并注册给SkillManager管理器持有目录/漂移逻辑目标端持有「文件落在哪里」的机制。当前 targets 包括ClaudeAgentTarget、CodexAgentTarget、CursorAgentTarget、OpenCodeAgentTarget等见架构测试的EXPECTED_CAPABILITY_SYMBOLS。setup 能力potpie/setuppotpie/setup/orchestrator.py 中的_SEAM_PLAN是唯一事实来源按依赖顺序列出 12 个 setup 步骤config → installer → embeddings.model → backend.provision → pot.init → state_store.provision → migrator.migrate → pot.default → daemon → auth → source → skills并标注每步 owner 与动作模板。previewdry-run、plan与run全部由它派生hardness 由_SOFT_STEPSauth/source/skills/embeddings.model 永不阻塞与_HOST_GATEDinstaller/daemon 仅在 detached daemon 模式下为 hard推导L98-L107。runL191-L241逐步骤把CapabilityNotImplemented折叠为not_implemented、其他异常折叠为failed——setup 永远不因单个组件崩溃而整体失败。这就是契约中「setup 拥有编排与生命周期接缝」的具体呈现。认证能力potpie/authpotpie/auth/ports/identity.py 的AuthService协议与AuthIdentityL17-L24把本地身份生命周期收纳进既有认证能力potpie/auth/adapters/local_identity.py中的LocalAuthService是其本地实现。契约特意强调与集成凭据存储、Provider 认证共享potpie.auth能力不合并其持久化、生命周期或策略——这正是 PCAP-006「扩展而非再造」的落地。Agent 上下文组合potpie/agent_context.pypotpie/agent_context.py 中的AgentContextService是顶层门面四个工具里resolve/search/record直接委托GraphService只有status是组合操作——把 pot/source 状态、图数据平面状态与SkillManager的建议 nudge 汇入一个StatusReport并按状态生成recommended_next_action提示运行potpie setup、potpie backend doctor或potpie resolve。它不属于 pots、skills 或 Context Engine 任何一方验证了 PCAP-007。运行时组合potpie/runtime/composition.pypotpie/runtime/composition.py 的build_local_runtime是唯一的具体装配点PCAP-008它同时构造独立的根服务组RootRuntimeServicesauth/config/daemon/installer/ledger/pots/setup/skills/backend/profile与引擎服务组LocalEngineServicespots/agent_context/graph/graph_workbench/backend/nudge把LocalPotStore、LocalConfigService、DefaultSkillManager、DefaultSetupOrchestrator、AgentContextService等具体实现显式接线。所有能力模块采用显式构造器依赖与模块导入没有动态注册表、全局服务定位器或第二条生产装配路径。可复现证据链PCAP-E1E4记录将证据分为四组均可独立复现PCAP-E1 — 固定提交的所有权审查pinned ownership review在实现提交ecf37757…上审查potpie/{agent_context.py,config,pots,skills,setup,auth,runtime}与根包元数据。PCAP-E2 — 永久所有权门禁permanent ownership gatestests/characterization/test_potpie_capability_ownership.py 验证精确所有者、仅文档的包初始化器、无替代伞形、无旧命名空间/导入/别名/再导出、唯一的具体运行时装配、分离的服务组、包元数据与独立包通道组合边界结果18 passed。PCAP-E3 — 行为保持behavior preservation完整根测试套件报告1447 passed, 4 skipped, 1 deselected独立 Context Engine 套件报告1153 passed, 32 skipped, 6 warnings。PCAP-E4 — 打包与隔离导入packaging and isolated importswheel 与 sdist 均构建成功根产物包含能力包且不含potpie/product全新引擎专用环境与根环境均通过隔离验证已安装的 CLI 与守护进程入口点保持不变。这些数字是记录作者在执行时采集的固定事实引用时以 spec/conformance/potpie-capabilities.md 为准。永久所有权门禁架构测试如何锁定布局test_potpie_capability_ownership.py是 PCAP-E2 的实现载体也是未来任何布局漂移的第一道防线。其关键断言包括FORBIDDEN_NAMESPACE potpie. productL17test_product_namespace_has_no_source_imports_aliases_or_reexports通过 AST 全量扫描要求残留源码、imports、sys.modules别名写入与字符串字面量全部为空集FORBIDDEN_SOURCE_UMBRELLAS (app, application, capabilities, control_plane, product)L90-L96test_no_replacement_source_umbrella_exists拒绝任何「换名不换本质」的通用伞形EXPECTED_CAPABILITY_SYMBOLSL31-L81把 20 个文件与 60 余个符号逐一绑定如potpie/config/local_paths.py→default_home、potpie/agent_context.py→AgentContextService任何符号搬家都会使test_capability_modules_exist_and_own_their_expected_symbols失败DOCUMENTATION_ONLY_INITIALIZERSL83-L88要求config/pots/setup/skills的__init__.py仅含一条文档字符串——禁止把包初始化器变成服务定位器或再导出面CONCRETE_ASSEMBLY_TYPESL98-L115列出 14 个具体装配类型test_runtime_composition_is_the_only_concrete_cross_capability_assembly断言它们只允许被potpie/runtime/composition.py实例化test_root_and_engine_service_groups_remain_separated通过RootRuntimeServices与LocalEngineServices的 dataclass 字段断言两组服务互不重叠test_root_distribution_metadata_owns_capability_packages读取pyproject.toml断言 wheel 包为[potpie]、sdist 包含全部能力路径且不含product、入口点严格为potpie potpie.cli.main:main与potpie-daemon potpie.daemon.__main__:maintest_independent_package_installation_lane_remains_enforced检查 CI 工作流与 scripts/verify_context_package_isolation.py 中的find_spec(potpie_context_engine)/find_spec(potpie)隔离验证。这套测试与 ADR-0011 的 Consequences 相呼应架构测试负责在搬迁后持续守住「归属、分发独立、组合方向」三条红线。关联契约检查与聚合结果记录同时核验了六份关联契约全部 passedSpec IDRevisionSpec refResultSPEC-PRODUCT1047cbe06…passedSPEC-SYSTEM1047cbe06…passedSPEC-CONTEXT-ENGINE1047cbe06…passedSPEC-POTPIE-RESOURCE-MANAGER2a8c03337…passedSPEC-DAEMON2e73ebdbd…passedSPEC-CLI1047cbe06…passed聚合结果为passed全部 12 个活动 Potpie 能力行为均有 complete 实现声明并通过验证。Known Gaps 一节明确PCAP-001PCAP-012 无已知缺口但本记录不将新的内部能力路径确立为受支持的公开 Python API——这是 PCAP-012 的纪律性边界避免把「搬迁后的模块路径」误读为「公开兼容契约」。新鲜度、记录更新约定与历史谱系记录的 Freshness 一节说明新鲜度通过比较固定的规范、实现、依赖与证据身份与所选当前目标推导而来绝不是由作者随意标注的契约或索引状态。在 spec/conformance/index.md 中还能看到配套的更新约定仅当持久验证身份变化接受的spec_id/spec_revision/spec_ref、选定的implementation_ref、范围内行为或依赖、可复现证据或聚合结论、以及 PR-head 与 base-commit 组合时才更新稳定记录新记录以previous_record_id/previous_record_ref/previous_record_path指向紧邻的前一版本旧 Git 对象不被改动若持久身份未变则把常规结果留在 CI 而不是发布新记录。本记录自身的历史谱系即从CONF-POTPIE-CAPABILITIES-2026-08-24-01基线提交3e5edfd5…处的potpie-capabilities-2026-08-24.md迁移而来符合「稳定路径 Git 历史承载旧版本」的约定。小结CONF-POTPIE-CAPABILITIES 这份记录的价值在于把「架构决策」转化为「可机器验证的契约」决策层由 ADR-0011 选定能力布局与四阶段搬迁次序契约层由 SPEC-POTPIE-CAPABILITIES 固化 12 条 MUST验证层由本记录与永久架构测试锁定实现。对想要深入代码的读者建议按「测试 → 契约 → 实现」的顺序阅读tests/characterization/test_potpie_capability_ownership.py 给出所有符号级断言potpie/runtime/composition.py 展示装配全貌再沿potpie/{config,pots,skills,setup,auth}逐一对照能力实现。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考