Potpie Context Engine 契约详解：单一发行版、上下文绑定的公共门面与显式宿主组合

Potpie Context Engine 契约详解单一发行版、上下文绑定的公共门面与显式宿主组合【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本文以 Potpie 仓库的规格变更记录 SPEC-CHANGE-0005 及其绑定的模块契约 Context Engine Contract 为核心系统讲解 Context Engine 作为可导入的上下文领域库应具备的边界一个发行版、一个绑定单一上下文身份的有限门面、显式宿主组合、类型化且传输中立的返回结果以及明确的迁移终点。读完本文你将掌握 CE-001 至 CE-034 这 34 条规范性要求的完整语义与分组逻辑理解其背后的 ADR 决策脉络并能结合potpie-context-engine源码定位每一类约束的实际实现。一、契约要解决的问题为什么需要一份Context Engine 契约在引入本契约之前Potpie 的产品布局存在三类结构性隐患Context Core 与 Context Engine 拆分造成的公共边界混乱。Context Core 被独立发布Context Engine 既依赖它又暴露了一个混入产品关注点的宽泛 HostShell导致库的公共边界难以理解Potpie 宿主的职责容易伪装成引擎能力见 ADR-0002。隐式环境发现、进程全局选择与按调用传上下文选择器。这让引擎到底使用哪些资源、哪个身份变得不可判定也使多个隔离引擎无法在同一进程内安全共存见 ADR-0003。引擎侧宿主接线与设置编排混入产品关注点。pot 选择、凭据、资源供给、安装、daemon 生命周期与领域服务纠缠在一起见 ADR-0004。SPEC-CHANGE-0005 正是为回答这些问题而提出建立唯一可导入的 Context Engine 发行版以及一个上下文绑定的公共门面配以显式宿主组合和传输中立的领域边界。它被标记为change_type: normative、change_status: accepted于2026-08-20由user:dsantra接受绑定 revision 1 作为目标契约。二、核心意图与四个锚点契约的 Intent 一句话可概括为Establish one importable Context Engine distribution and one context-bound public façade with explicit host composition and a transport-neutral domain boundary.它由四个相互咬合的锚点构成锚点含义对应决策一个可导入发行版公共契约所需的类型与行为全部归属potpie-context-engineADR-0002上下文绑定门面ContextEngine永久绑定一个不可变逻辑身份ADR-0003显式宿主组合身份、依赖、所有权模式由宿主在构造时显式提供ADR-0003传输中立领域边界操作返回类型化领域值或类型化错误与传输层无关ADR-0005该变更属于初始契约from_revision: 0、to_revision: 1不替换任何已接受契约也不声明当前 HostShell 或包布局已符合该边界——这是后续迁移的目标态。三、职责边界Context Engine 拥有什么、排除什么契约的 Ownership And Boundaries 用拥有与排除双向划定边界。Context Engine 拥有上下文领域的操作、值、错误与不变量公共门面背后聚焦的领域模块已声明的引擎所有端口engine-owned ports及这些端口的包内适配器引擎内部状态以及显式转移给它的依赖适合直接使用或宿主使用的传输中立引擎结果。它明确排除Potpie 选择selection调用者安全策略宿主资源供给provisioningdaemon 行为CLI 展示安装与产品生命周期。这一拥有/排除结构直接落实为 CE-011领域语义唯一所有者、CE-013禁止终端展示、CE-014禁止认证与产品授权、CE-015禁止隐式资源发现与供给。对应实现可见 context_engine.py 中门面只依赖EngineDependencies中显式注入的操作组而 pyproject.toml 的基础依赖仅声明pydantic2.0交付面与存储后端全部放在 extras 之后保证导入即轻量。3.1 参与者模型契约定义了四种参与方详见模块契约的 Actors And Permissions 表参与者交互方式Compatible host兼容宿主提供上下文身份、依赖、所有权模式与允许调用的操作集合Potpie Resource Manager作为 Potpie 宿主组合或获取放入授权上下文租约authorized context lease中的引擎Domain caller领域调用方在宿主授权后对门面调用有限的操作Context Engine为绑定的身份强制实施领域不变量关键设计在于Context Engine 信任宿主建立调用者身份与权限但自身仍会校验领域输入并保持其不可变的上下文身份。也就是说安全边界在宿主领域正确性在引擎。四、34 条规范性要求的完整解读CE-001 ~ CE-034模块契约 context-engine.md 是这些行为的权威定义。SPEC-CHANGE-0005 的行为操作表Behavior Operations以add操作一次性建立了 CE-001 至 CE-034 共 34 条行为。按主题可将它们归为十组便于记忆与实施。4.1 单一发行版与有限门面CE-001 ~ CE-004CE-001Context Engine 必须把ContextEngine暴露为有限、薄的公共门面显式命名的方法即上下文领域操作。CE-002兼容宿主必须能在不导入 Potpie daemon 或 CLI 内部实现的前提下使用该门面。CE-003公共契约所需的类型与行为必须归属唯一的potpie-context-engine发行版。CE-004迁移终点不得保留potpie-context-core作为独立的架构或公共发行边界。源码印证当前仓库已不存在potpie/context-core目录conformance 记录 也明确记录Context Core remains absentCE-004 passed发行版名称potpie-context-engine定义于 pyproject.toml 的[project] name字段。公共门面导出集中在 api.py而potpie_context_engine包自身__init__.py只导出工厂、生命周期、outcomes 与默认图定义保持依赖轻量。4.2 上下文身份绑定与实例隔离CE-005 ~ CE-009CE-005宿主必须在构造时显式提供上下文身份、每个必需依赖以及每个携带资源依赖的所有权模式。CE-006一个引擎实例在其整个生命周期内永久绑定恰好一个逻辑上下文身份。CE-007引擎操作不得接受覆盖实例绑定身份的第二选择器。CE-008宿主需要不同身份时必须构造或获取另一个引擎实例。CE-009不同身份的实例必须能无进程全局上下文状态地共存。源码印证ContextIdentity是冻结数据类只含value字段且构造时校验非空context_engine.pyContextEngine.__init__仅接受context、config、dependencies三个关键字参数构造后context属性只读。请求模型层面契约要求操作请求不接受上下文选择器conformance 记录中 CE-007 的验证结果为Request models reject context selectors。4.3 依赖所有权与生命周期CE-010、CE-022 ~ CE-025、CE-032这是显式组合原则在资源管理上的落点CE-010引擎所有资源的清理必须可安全重复请求且不产生重复的破坏性效果。CE-022宿主提供的资源型依赖默认视为借用borrowed除非类型化构造契约显式转移所有权。CE-023引擎不得关闭或释放借用依赖。CE-024对于转移transferred或引擎创建的依赖引擎关闭时必须按声明的生命周期释放。CE-025终态关闭后尝试操作必须返回EngineLifecycleError。CE-032失败的构造不得产出可用引擎实例。源码印证均为 context_engine.py 的真实行为ResourceOwnership Literal[borrowed, transferred]EngineResource冻结数据类在ownership transferred且缺少close回调时直接抛ValueErrorCE-032 的构造期校验ContextEngine.close()用_close_lock保证并发安全已关闭且无待清理资源时幂等返回Success(None)清理失败会保留在_pending_close_resources中并在下次 close 重试返回retry_posturesafe的EngineLifecycleErrorCE-010close()只遍历ownership transferred的资源CE-023且按reversed(dependencies.resources)逆序关闭CE-024 的按序释放_invoke()在操作执行前检查_closed关闭后直接返回engine_closed的EngineLifecycleErrorCE-025close()会先置_closed True并等待_active_operations 0实现排水后释放资源create_engine()是唯一的公开构造入口异步函数构造前校验五个必需操作组是否缺失缺失则返回FailureCE-032。4.4 领域所有权与类型化结果CE-011、CE-012、CE-028 ~ CE-031CE-011Context Engine 必须是本系统中上下文领域语义与不变量的唯一所有者。CE-012每个操作必须返回类型化、传输中立的领域值或类型化的DomainError/DependencyError/EngineLifecycleError。CE-028公共操作请求、结果与错误必须使用引擎所有类型而非 Potpie 选择记录、daemon 协议 DTO 或 CLI 展示类型。CE-029上下文领域语义失败必须返回DomainError。CE-030履行声明的引擎所有端口时的依赖失败必须返回DependencyError。CE-031引擎错误与可观测性输出默认排除秘密。源码印证outcomes 定义于 outcomes.py三类错误均为冻结数据类带code、message、details、recommended_next_action、retry_posture与category字面量字段domain/dependency/engine_lifecycleSuccess[T]/Failure[E]构成Outcome联合类型。_invoke()把依赖抛出的任意异常统一包装为engine_dependency_failed的DependencyError把领域语义拒绝留给领域模块返回DomainError——这正是 CE-029 与 CE-030 的执行点。4.5 边界排除终端、认证、资源供给与产品关注点CE-013 ~ CE-015、CE-026CE-013引擎不得提示、打印、渲染终端展示或选择进程退出码。CE-014引擎不得认证调用者或强制 Potpie 产品授权策略。CE-015引擎不得静默发现或供给宿主管理的资源。CE-026包内适配器不得实现或依赖 Potpie 的选择、产品授权、资源供给、安装、daemon、CLI 或产品生命周期模块。这四条共同保证引擎可作为纯库被任意兼容宿主复用。conformance 记录的 CE2-E4 引用了反向导入门禁测试test_cli_package_boundary.py、test_potpie_capability_ownership.py来验证引擎生产代码不导入根potpie命名空间。4.6 适配器约束只实现引擎所有端口由宿主显式选择CE-016、CE-033CE-016包内适配器只能实现已声明的引擎所有端口。CE-033包内适配器必须由宿主显式选择与组合。组合示例见 composition.py 的build_graph_service()它接受GraphBackend、GraphDefinition、GraphMutationPolicy与可选的ReconciliationConfig全部由调用方显式传入后端选择在宿主侧并支持从环境读取 reconcile 配置reconciliation_config_from_env作为显式策略的一部分。4.7 破坏性操作显式、非默认CE-017、CE-034CE-017破坏性操作必须表示为显式的破坏性领域命令。CE-034破坏性操作不得通过默认或推断操作触达。在门面方法中破坏性语义如reset_context是独立命名的方法位于 context_engine.py调用方必须显式构造ResetContextRequest并显式调用不存在默认即破坏的推断路径。这与 ADR-0005 中CLI 的人类确认成为不受信任的类型化断言由 Resource Manager 验证后再调用显式破坏性领域命令的产品级安全链相衔接。4.8 延期范围插件与解析CE-018、CE-019CE-018本修订不得暴露公共插件、扩展注册或清单契约。CE-019本边界下的工作不得重新设计解析行为。这是 ADR-0006 的直接体现第一份迁移提交只绑定稳定的所有权边界插件体系、外部宿主传输协议、精确方法编组、同步/异步暴露等全部显式延期。potpie_context_engine包的公开导出__init__.py中不存在任何扩展注册入口印证 CE-018。4.9 门面形态拒绝服务定位器与万能宿主CE-020、CE-021CE-020门面不得暴露动态分发、任意服务查找、服务容器图或内部服务的透传镜像。CE-021门面必须委托给聚焦的上下文领域模块而不是累积成万能宿主或服务实现。源码印证ContextEngine内部只有_invoke()一个统一执行通道将每个显式命名的方法委托给EngineDependencies中对应的操作组context/graph/workbench/ingestion/nudge五个Protocol没有任何反射、服务定位器或容器图。EngineDependencies的每个字段类型均为具名Protocol如GraphOperations、WorkbenchOperations方法签名固定天然阻止动态分发。4.10 迁移终点移除而非重命名 HostShellCE-027CE-027Context Engine 边界迁移完成时必须移除HostShell 与 Potpie 所有的宿主接线而不是在ContextEngine后面保留或重命名它们。契约在 CE-027 中引用的迁移证据路径为potpie/context-engine/src/potpie_context_engine/host/shell.py与potpie/context-engine/src/potpie_context_engine/bootstrap/host_wiring.py。从当前仓库目录结构看potpie_context_engine下只有adapters/application/benchmarks/bootstrap/core/domain/testing已不存在host/目录——可以推断 HostShell 相关文件已被移除而非改名与契约要求的迁移方向一致。这也与 conformance 记录中 CE-027HostShell and engine-owned root wiring remain absent的验证结论吻合。五、生命周期状态机construction → usable → closing → closed模块契约用一段状态草图总结了 CE-010、CE-023、CE-024、CE-025 与 CE-032construction - usable - closing - closed | - construction failure, with no usable instanceconstructioncreate_engine()校验显式组合任一必需操作组缺失即返回Failure不产出可用实例CE-032。usableContextEngine可执行有限操作操作前检查_closed借用依赖可被使用但不会被关闭。closingclose()置_closed True、等待活跃操作归零排水然后逆序关闭 transferred 资源失败的资源保留待重试close 可安全重复调用CE-010。closed任何操作返回engine_closed的EngineLifecycleErrorCE-025。特别注意改变上下文身份不是生命周期转换。身份在构造时绑定之后不可重定向CE-006/CE-007。六、类型化结果模型Outcome Summary模块契约的结果汇总表是全契约最实用的速查表原文完整如下条件类型化结果领域输入、状态、能力或不变量拒绝操作DomainError引擎所有端口在正常操作期间失败DependencyError终态关闭后尝试操作EngineLifecycleErrorPotpie 选择、认证、授权、资源、协议或展示失败不由 Context Engine 产生该表概括了 CE-012、CE-025、CE-029 与 CE-030。最后一行尤其关键它把引擎边界之外的错误类型明确划给宿主侧。配套的 glossarySPEC-GLOSSARY进一步规定十类错误必须保持互异——SelectionError、AuthenticationError、AuthorizationError、ResourceLifecycleError、DomainError、DependencyError、EngineLifecycleError、ProtocolTransportError、DaemonInternalError、PresentationError——其中前三类与ResourceLifecycleError属于 Potpie 边界中间三类属于 Context Engine 边界。在 outcomes.py 中Outcome被定义为Success[T] | Failure[EngineError]联合类型EngineError DomainError | DependencyError | EngineLifecycleError与契约的三类引擎错误严格一一对应。七、对宿主系统的计算影响Computed Impact ReviewSPEC-CHANGE-0005 还明确了三个关联契约的必改项摘自文档的 Computed Impact Review 表关联契约要求的变化评审方SPEC-POTPIE-RESOURCE-MANAGER负责显式引擎组合与宿主资源生命周期agent:codexSPEC-DAEMON类型化上下文域处理器在调用显式引擎操作前必须先获取授权上下文租约agent:codexSPEC-CLI托管路径避免直接构造引擎agent:codex也就是说引擎构造从 CLI 与 daemon 侧上移到 Potpie Resource ManagerResource Manager 解析选择、应用授权、获取宿主资源、构造或复用上下文绑定引擎并返回带显式所有权与释放语义的授权上下文租约。这正对应 ADR-0004 的决策——Resource Manager 是职责而非某个强制类或包。同时文档的 Compatibility, Security, And Failure Impact 指出该边界在保持直接库可用性的同时把产品认证、选择、安装、供给、进程与展示关注点外移要求显式依赖所有权并移除 HostShell 而非改名精确的兼容性垫片compatibility shims仍被延期。八、验证、一致性记录与实现状态SPEC-CHANGE-0005 的 Validation 区块记录了结构、语义、权威/溯源、依赖/一致性四类评审全部通过并注明Current implementation characterization: passed11 tests非目标一致性与Implementation conformance: unclaimed——即该变更本身只绑定目标契约不声称当前实现已符合。后续的 Context Engine Conformance Record 则提供了实现侧的最终验证在选定实现 ref 上CE-001 至 CE-034 全部标记complete且验证结果为passed其中CE2-E1对potpie/context-engine/src/potpie_context_engine下的公共门面、组合、请求、结果与导出做固定源码评审CE2-E2在potpie/context-engine下运行uv run --project . pytest tests -m not premerge_journey结果为1153 passed, 32 skipped32 个跳过项依赖外部集成服务CE2-E3构建根包与 Context Engine 的 wheel/sdist将引擎 wheel 装入全新环境后成功导入公共包与ContextEngine同时find_spec(potpie)返回None——证明引擎发行版完全独立于根potpie命名空间CE-002/CE-026 的强证据CE2-E4反向导入门禁test_cli_package_boundary.py、test_potpie_capability_ownership.py所在的特征化测试车道报告31 passed。九、发行版边界与安装视角从使用者视角契约的单一发行版体现在 pyproject.toml[project] name potpie-context-engine version 0.2.0 requires-python 3.12,3.15 dependencies [pydantic2.0]基础依赖只有pydantic保证公共 API 面导入轻量存储后端与交付面全部作为 extras 提供localFalkorDB / FalkorDBLite 本地图后端Python 3.12 默认 FalkorDBLite并带hiredis加速 RESP 解析httpFastAPI / httpx / uvicorn 交付面neo4j、postgres可选图/关系后端embeddings、github、reconciliation-agent、hatchet、observability能力扩展all本地 potpie 体验所需的完整集合不含基准测试与开发工具。这从包结构上落实了 CE-003公共类型与行为归属单一发行版与交付面与存储后端延迟加载的设计意图引擎核心不因某个后端而变重。十、迁移路径与验收标准模块契约的 Compatibility, Migration, And Rollout 明确后续提交将把 Context Core 所需类型并入 Context Engine并移除 Potpie 所有的组合代码临时导入垫片只能作为迁移机制存在不构成最终边界。验收标准Acceptance Criteria原文要点公共门面不能变成服务定位器或改名后的 HostShell一个实例不能被重定向借用与转移所有权不能混淆包内适配器只能实现引擎所有端口引擎结果保持类型化且传输中立产品认证、供给、daemon 与展示保持在发行版之外。模块契约的 Implementation Notes 也特别提醒当前的 HostShell、宿主接线、独立的 Context Core 包、CLI 认证、安装器、设置与技能相关端口都是迁移证据而非目标架构——这些说明不产生任何一致性声明。结语SPEC-CHANGE-0005 是一次典型的先定边界、再谈实现的架构治理用 34 条规范性要求把一个原本混入产品关注点的运行时收敛为单一发行版 上下文绑定门面 显式宿主组合 类型化传输中立结果的可导入库并为其定义了移除 HostShell、废弃 Context Core 的迁移终点。对库的集成者而言它意味着清晰的构造契约create_engineContextIdentityEngineConfigEngineDependencies与可预期的三类错误对 Potpie 产品侧而言它把选择、授权、资源供给与展示责任明确交给 Resource Manager、daemon 与 CLI。当前仓库的 conformance 记录已证明这 34 条行为在实现侧全部落地是理解 Potpie 上下文图架构的最佳起点。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考