potpie 能力所有权契约(Potpie Capability Ownership Contract)深度解析:从 Capability 视角理解 Root Potpie 与 Context Engine 的边界
potpie 能力所有权契约(Potpie Capability Ownership Contract)深度解析:从 Capability 视角理解 Root Potpie 与 Context Engine 的边界
导读
本篇文章围绕仓库 spec/modules/potpie-capabilities.md 中定义的 Potpie Capability Ownership Contract(SPEC-POTPIE-CAPABILITIES) 展开,系统讲解 Root Potpie(根发行版)如何按“能力(Capability)”而非按“产品层/控制面”组织源码,并在此基础上梳理配置、Pots、Skills、Setup、认证、Agent 上下文组合、运行时组合七大能力的归属边界,以及 potpie.product 命名空间的删除与行为保持迁移纪律。读完本文,你将掌握:能力所有权契约的 12 条规范性要求(PCAP-001~PCAP-012)、仓库中真实的模块落位(见 ADR-0011)、永久性架构测试的验证手段(见 test_potpie_capability_ownership.py),以及 Root Potpie 与 Context Engine 之间“单向依赖、独立可导入”的分层原则。
为什么需要一份“能力所有权契约”
Potpie 项目的定位是 “Context Graph for AI Native SDLC”,其代码被组织为两个可独立使用的部分:Root Potpie(围绕并组装 Context Engine 的根发行版)和 Context Engine(可独立导入的上下文领域库)。在引入该契约之前,根源码被归入一个按架构分层命名的通用命名空间 potpie.product,这种“通用架构桶(generic architectural bucket)”带来的问题是:源码位置无法回答“这段代码属于哪个能力、由谁负责”。
SPEC-POTPIE-CAPABILITIES 修订版 1 的核心目标(对应 SPEC-CHANGE-0010):
- 要求 Root Potpie 源码按显式拥有的能力组织,而不是按
product、control plane之类的通用层组织(PCAP-001); - 明确每个能力的拥有范围与排除范围;
- 规定跨能力组合(cross-capability composition)的显式接缝;
- 最终删除
potpie.product命名空间,且不提供转发别名或兼容性再导出(PCAP-010); - 迁移全程保持 CLI、daemon、setup、配置、pot/source、skill、持久化与 Context Engine 的可观察行为不变(PCAP-011)。
该契约被 spec/index.md 收录为七个修订版 1 运行时契约之一,阅读顺序位于 Product 契约与 System 契约之后(第 5 位),其直接依赖为 SPEC-PRODUCT 与 SPEC-SYSTEM。
能力所有权与边界总览
契约用一张所有权表定义了七大能力的“拥有(Owns)”与“排除(Excludes)”边界,这是理解整个仓库组织方式的钥匙:
| 能力(Capability) | 拥有(Owns) | 排除(Excludes) |
|---|---|---|
| Configuration(配置) | Potpie home 解析、持久化本地配置、公开值脱敏(public-value redaction) | Pot/source 状态、技能安装、Context Engine 配置所有权 |
| Pots | Pot 与 source 契约、生命周期策略、仓库默认值、本地持久化 | Graph 领域语义、setup 编排、Agent 呈现 |
| Skills | 内置目录(catalog)、校验、安装/更新/移除策略、Agent 专属目标 | Setup 编排、graph 领域行为、运行时组装 |
| Setup | 首次运行编排、安装接缝、状态预置(state provisioning)、迁移 | Setup 之外的能力实现选择、CLI 呈现 |
| Authentication(认证) | 与既有凭据契约和适配器并存的本地身份生命周期 | Context Engine 授权策略、重复的认证所有权 |
| Agent context composition(Agent 上下文组合) | Graph、pot、skill 状态的面向产品组合 | 底层能力的归属权或 graph 领域语义 |
| Runtime composition(运行时组合) | 根能力具体实现的选择与装配 | 能力策略、动态服务查找、Context Engine 领域语义 |
契约同时明确:Context Engine 是独立可导入的发行版,不拥有任何 Root Potpie 能力。这一句话奠定了整份契约的依赖方向。
术语:Capability 与 Generic Bucket 的边界
- Capability(能力):一个具名的 Root Potpie 关注点,其契约、策略与具体本地机制可通过其源码命名空间被发现。
- Root Potpie:围绕、组合并交付独立可用的 Context Engine 的
potpie发行版。 - Cross-capability composition(跨能力组合):组合两个及以上能力契约的根服务或组合根(composition root),但不转移它们的归属权。
- Generic architectural bucket(通用架构桶):以宽泛层命名的源码命名空间(如
product、control plane),而非以所拥有的能力命名。
术语设计的关键判断是:“能力”是命名空间的命名轴,而“架构角色(ports/services/adapters)”是能力内部的次级组织轴。ADR-0011 的备选方案分析中明确否定了“保留 potpie.product”“改名为 app/application/control_plane/capabilities”以及“把 ports/services/adapters 提升为根层”等做法——它们要么保留通用桶的歧义,要么让一个能力横跨多个互不相邻的目录。
参与者与权限
| 参与者(Actor) | 交互方式 |
|---|---|
| Potpie 维护者 | 变更能力内部实现,同时保持已接受的归属权与行为边界 |
| Runtime composition | 选择具体实现,并装配跨能力依赖 |
| Context Engine 集成者 | 不导入 Root Potpie 即可导入并运行 Context Engine |
| CLI / daemon 调用者 | 在内部搬迁前后观察到完全相同的受支持行为 |
这四类参与者对应契约的四条验收线:可发现性(维护者/新读者)、装配唯一性(运行时组合)、独立导入性(引擎集成者)、行为保持(CLI/daemon 调用者)。
规范性要求详解:PCAP-001 至 PCAP-012
12 条行为义务是契约的主体,每条都带有 authority(user:dsantra)与迁移前的 observation(如 code:potpie/product@930632fb…)。逐条解读如下:
| 行为 ID | 规范性要求 |
|---|---|
| PCAP-001 | Root Potpie 应用源码必须按显式拥有的能力组织,而非按通用产品层/控制面命名空间组织 |
| PCAP-002 | 配置能力必须拥有 Root Potpie home 解析与持久化本地配置行为 |
| PCAP-003 | pots 能力必须拥有 pot/source 契约、生命周期策略、仓库默认值与本地持久化 |
| PCAP-004 | skills 能力必须拥有其目录、命令片段校验、安装/更新/移除策略与 Agent 专属目标 |
| PCAP-005 | setup 能力必须拥有首次运行编排及其安装、状态预置与迁移接缝 |
| PCAP-006 | Root Potpie 本地身份生命周期必须扩展既有认证能力,而非创建第二个认证所有者 |
| PCAP-007 | 组合 graph 行为与多个根能力的服务必须位于每个独立能力命名空间之外 |
| PCAP-008 | 根运行时组合必须是跨 Potpie 能力选择具体实现的生产装配点 |
| PCAP-009 | Context Engine 生产代码不得导入 Root Potpie 能力代码 |
| PCAP-010 | 最终根源码树不得包含 potpie.product 命名空间、其转发别名或兼容性再导出 |
| PCAP-011 | 搬迁根能力必须保持受支持的 CLI、daemon、setup、配置、pot、source、skill、持久化与 Context Engine 行为 |
| PCAP-012 | 分支本地的 potpie.product.* 实现导入不得被视为受支持的公开 Python 兼容契约 |
其中 PCAP-009 与 PCAP-011 还引用其他契约:PCAP-009 关联 SYS-002、CE-026,PCAP-011 关联 PROD-004、SYS-011,说明该契约与系统级、引擎级契约共享依赖方向与行为保持义务。
从契约到落地:ADR-0011 选定的源码布局
契约本身“不做实现或验证声明”,具体文件布局由 ADR-0011 单独决策。ADR-0011 选定如下布局(与当前仓库 potpie/ 目录结构一致):
potpie/
agent_context.py # 跨能力组合:AgentContextService(PCAP-007)
auth/ # 认证能力(PCAP-006)
ports/
identity.py # AuthIdentity / AuthService
adapters/
local_identity.py # LocalAuthService
config/ # 配置能力(PCAP-002)
contracts.py # ConfigService 协议
local.py # LocalConfigService
local_paths.py # default_home():$CONTEXT_ENGINE_HOME / ~/.potpie
pots/ # Pots 能力(PCAP-003)
contracts.py # PotInfo / SourceInfo / PotManagementService ...
local_service.py # LocalPotManagementService
local_store.py # LocalPotStore
setup/ # Setup 能力(PCAP-005)
contracts.py # SetupOrchestrator / SetupObserver ...
orchestrator.py # DefaultSetupOrchestrator
installation.py # Installer
local_installer.py # LocalInstaller
state.py # StateStorePort / MigrationPort
flat_file_state.py # FlatFileStateStore / FlatFileMigrator
skills/ # Skills 能力(PCAP-004)
contracts.py # SkillManager / SkillInfo / AgentTargetPort ...
manager.py # DefaultSkillManager
catalog.py # catalog_by_id / load_bundle_skills
targets.py # ClaudeAgentTarget / CodexAgentTarget / ...
installer.py # install_agent_bundle / validate_packaged_skill_command_snippets
几个关键落位原则:
-
包初始化文件只放文档。
potpie/config/__init__.py、potpie/pots/__init__.py、potpie/setup/__init__.py、potpie/skills/__init__.py均不得聚合契约、暴露宽泛再导出 API、选择实现或以别名重建potpie.product(由测试test_capability_initializers_are_documentation_only强制:初始化文件 AST 中仅允许一个字符串表达式)。 -
配置能力负责 root home 解析。真实实现见 potpie/config/local_paths.py:
default_home()优先读取环境变量CONTEXT_ENGINE_HOME(并expanduser),否则回落到~/.potpie。契约要求 Context Engine 保留其独立的等价本地路径辅助函数——两个发行版可以实现相同的环境优先级与文件系统默认值,但 Context Engine 生产代码不得导入 root 辅助函数,root 能力代码也不得借助 Context Engine 适配器获取 home(ADR-0011 将此列为“刻意的小型重复”,以保持两个 wheel 相互独立)。 -
认证能力被扩展而非复制。
AuthIdentity/AuthService进入 potpie/auth/ports/identity.py,LocalAuthService进入 potpie/auth/adapters/local_identity.py。本地身份生命周期与集成凭据存储、提供方认证保持分离——共享potpie.auth能力不会合并其持久化、生命周期或策略。 -
Agent 上下文组合是顶层门面。potpie/agent_context.py 中的
AgentContextService是一个 dataclass 门面,组合了GraphService(引擎侧)、PotManagementService(pots 能力)与SkillManager(skills 能力),对外暴露resolve/search/record/status四个工具方法。它不属于 pots、skills 或 Context Engine 中的任何一个——这正是 PCAP-007 要求的“位于每个独立能力命名空间之外”。
运行时组合:唯一的生产装配点
PCAP-008 与 ADR-0011 均强调:potpie.runtime.composition 是唯一的生产装配点。真实实现见 potpie/runtime/composition.py 的 build_local_runtime():
- 通过
build_backend(default_backend_profile(), ...)选择图后端(默认falkordb_lite,可用CONTEXT_ENGINE_BACKEND或GRAPH_DB_BACKEND覆盖); - 构造能力实现:
LocalPotStore→LocalPotManagementService、DefaultSkillManager(注入claude/codex/cursor/opencode四个AgentTarget)、LocalConfigService、LocalInstaller、LocalAuthService、DefaultSetupOrchestrator(注入 config/installer/backend/pots/state_store/migrator/daemon/auth/skills); - 将根服务组与引擎服务组分离:
RootRuntimeServices与LocalEngineServices是两个不同的 dataclass 字段集合,见 potpie/runtime/root_services.py。
服务组分离由测试 test_root_and_engine_service_groups_remain_separated 强制:RootRuntimeServices 的字段(auth、backend、config、daemon、installer、ledger、pots、profile、setup、skills)与 LocalEngineServices 的字段(agent_context、backend、graph、graph_workbench、ingestion、ingestion_events、nudge、pots)必须两两不相交,防止根与引擎服务组被意外合并。
数据模型、状态机与不变量
- Data And State Model:该契约不引入任何新的数据或持久化状态模型。既有的
config.json、pots.json、仓库默认值、技能安装、daemon 与 Context Engine 状态,仍由各自当前的行为与适配器管辖。 - State Machines:不适用——源码归属没有运行时生命周期状态机;setup、daemon、认证与 Context Engine 的状态迁移仍由各自既有契约管辖。
- Interfaces:能力契约与实现通过显式模块路径导入;能力包初始化文件不建立聚合服务定位器(aggregate service locator)或宽泛再导出 API;运行时组合为既有 root 服务组与引擎服务组提供具体依赖。
- Invariants(不变量):依赖方向是 Root Potpie → Context Engine。能力搬迁不允许反向依赖、不允许合并 root 与引擎服务组、不允许把 graph 领域行为转移进根能力。
一致性、幂等与失败模式
- Consistency/Ordering/Idempotency:搬迁只改变源码归属。既有 setup 顺序、配置写入替换、pot/source 持久化、技能操作幂等性、daemon/运行时协调在 PCAP-011 下保持原样。
- Failure Modes:缺失包数据、陈旧导入、Context Engine 反向导入、部分搬迁的能力归属都是一致性失败。恢复方式是完成或回滚受影响的搬迁切片;通过
potpie.product做兼容转发被 PCAP-010 明令禁止。 - Security/Privacy:密钥脱敏、凭据持久化、本地身份行为、daemon 认证、授权与 Context Engine 信任边界全部保持不变。把身份生命周期移入既有认证能力不会合并凭据存储或削弱其归属接缝。
- Observability:不引入任何新的运行时遥测或审计事件;变更证据来自 Git 历史、已接受的契约身份、架构测试、包清单与一致性记录。
- Performance/Limits:不新增性能或容量行为;搬迁不得引入运行时兼容路由器、动态服务查找或替代装配路径。
兼容、迁移与回滚纪律
迁移遵循“绿提交、按能力逐一切片”的纪律(ADR-0011 给出四片顺序):
- 配置与 pots(含 root 拥有的 home 解析);
- skills;
- setup 与本地身份;
- agent-context 组合,随后完整删除
potpie.product。
每个被移动的旧路径必须在与其直接调用方相同的提交中消失,不引入转发模块、兼容再导出、sys.modules 注册或动态别名;若某切片需要扩大才能保持绿色,只允许纳入直接导入依赖方。repository 调用方按“能力对能力”迁移:一条 potpie.product.* 导入被迁移到拥有它的能力,而不是通过别名保留下来。
ADR-0011 的后果部分还点明了该纪律的代价与收益:源码路径直接陈述能力归属,避免 product 那样的模糊伞形命名空间;仓库导入与包清单必须同步变更,使迁移规模大于一次命名空间重命名,但可机械审查;无转发的删除意味着未受契约保护的分支本地 Python 导入在其所属切片移动时会立即断开。
永久性架构测试:如何把契约锁进 CI
契约的落地点是 tests/characterization/test_potpie_capability_ownership.py,该文件被一致性记录 spec/conformance/potpie-capabilities.md 标记为 “PCAP-E2 — permanent ownership gates”,合并边界结果 18 passed。值得关注的高价值断言:
test_product_namespace_has_no_source_imports_aliases_or_reexports:对potpie/product进行 AST 扫描,断言无残留源码、无导入者、无sys.modules别名写入、无命名空间字面量;test_no_replacement_source_umbrella_exists:禁止app/application/capabilities/control_plane/product五个伞形命名空间出现在根源码树;test_capability_modules_exist_and_own_their_expected_symbols:逐文件断言期望符号(如potpie/config/local_paths.py拥有default_home,potpie/pots/local_store.py拥有LocalPotStore);test_runtime_composition_is_the_only_concrete_cross_capability_assembly:把 14 个具体装配类型(LocalConfigService、DefaultSetupOrchestrator、LocalPotManagementService等)的所有调用点收敛到唯一文件potpie/runtime/composition.py;test_root_distribution_metadata_owns_capability_packages:解析 pyproject.toml 的 hatch 构建配置,断言 wheel 打包potpie包、sdist 包含全部能力目录且不含product,并锁定入口点potpie = potpie.cli.main:main与potpie-daemon = potpie.daemon.__main__:main;test_independent_package_installation_lane_remains_enforced:检查 CI workflow 中“构建 Context Engine wheel/sdist 并做隔离安装验证”的步骤,以及 scripts/verify_context_package_isolation.py 通过find_spec("potpie_context_engine")/find_spec("potpie")验证两个发行版可独立安装。
一致性记录与行为保持证据
spec/conformance/potpie-capabilities.md(CONF-POTPIE-CAPABILITIES,result: passed)给出 12 条行为全部“complete + passed”的追踪证据:
- PCAP-E1(所有权审查):
potpie/{agent_context.py,config,pots,skills,setup,auth,runtime}与根包元数据在实现 ref 下逐项核对; - PCAP-E2(永久所有权门):上述架构测试,
18 passed; - PCAP-E3(行为保持):根套件
1447 passed, 4 skipped, 1 deselected;独立 Context Engine 套件1153 passed, 32 skipped, 6 warnings; - PCAP-E4(打包与隔离导入):两个 wheel 与 sdist 均构建成功;root 产物含能力包且不含
potpie/product;全新引擎隔离环境与 root 隔离环境均通过验证;已安装 CLI 与 daemon 入口点保持不变。
记录还特别注明:不把新的内部能力路径确立为受支持的公开 Python API(与 PCAP-012 呼应),且 Known Gaps: None for PCAP-001 through PCAP-012。
实战要点总结
- 给维护者:新增根能力逻辑时,先问“这属于哪个已命名能力”,再落位到 potpie/ 对应目录;跨能力的编排要么进
potpie/agent_context.py(面向 Agent 的门面),要么进potpie/runtime/composition.py(装配),不要新建伞形目录。 - 给集成者:Context Engine 是可独立导入的发行版(包名
potpie_context_engine),其生产代码不得出现import potpie.*;需要 root home 时在根侧使用potpie.config.local_paths.default_home(),在引擎侧使用引擎自带的等价辅助函数。 - 给调用者:
potpie.product.*已是历史命名空间,迁移后不存在任何转发别名,任何基于该路径的导入都会立即失败;应改用对应能力的公开模块路径。 - 给测试读者:行为保持的验证闭环由“契约(potpie-capabilities.md)→ 决策(ADR-0011)→ 永久架构测试(test_potpie_capability_ownership.py)→ 一致性记录(potpie-capabilities.md)”四层组成,任何一层缺失都意味着契约目标尚未闭环。
结语
SPEC-POTPIE-CAPABILITIES 回答了一个大型仓库普遍面临的架构问题:当“做什么”和“谁拥有”都可以从目录结构直接读出时,代码的组织方式本身就是可验证的架构决策。它没有重新设计任何运行时行为,却通过 12 条规范性要求、一份显式布局决策和一组永久架构测试,把“能力导向的源码归属”变成了可被 CI 强制、可被一致性记录引用的项目事实——同时保住了 Root Potpie 与 Context Engine 之间不可逆转的单向依赖方向。