Potpie Context Runtime 系统契约解析：Context Engine、Resource Manager、Daemon 与 CLI 的边界与调用路径

Potpie Context Runtime 系统契约解析：Context Engine、Resource Manager、Daemon 与 CLI 的边界与调用路径

【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie

导读

本文以 Potpie 仓库 spec/system.md 中已接受的 Context Runtime System Contract（SPEC-SYSTEM，revision 1）为核心骨架，系统拆解 Potpie 目标架构中可导入的 Context Engine 与产品宿主之间的职责边界：谁拥有上下文语义、谁负责资源与授权、谁管理守护进程生命周期、谁承担 CLI 呈现。读完本文，你将掌握 Potpie 的两条规范化调用路径（守护进程生命周期控制路径与托管域执行路径）、23 条系统级规范性要求（SYS-001～SYS-023）的分组语义、10 类跨边界错误的分类法，以及破坏性操作从"人工确认"到"显式域命令"的完整信任链，并能在 potpie/runtime 与 potpie/daemon 的源码中逐一找到契约对应的实现印证。

一、契约的定位：定义"目标边界"而非冻结实现

SPEC-SYSTEM 的 Purpose 非常克制：它定义的是可导入 Context Engine 与 Potpie 产品宿主之间的目标边界，用于"将守护进程生命周期控制与托管域执行分离"，同时"不冻结 deferred 的传输层与公共 API 细节"。

从 spec/index.md 的契约注册表可以看出，SPEC-SYSTEM 是整个运行时规范族的第四环：

整个规范集的简化分层脊柱是CLI -> daemon -> Resource Manager -> Context Engine，但 system.md 明确指出，共享的词汇表与系统级依赖是显式声明的，而不是被这条简化脊柱隐藏的。

Scope 与非目标

本修订版覆盖：当前 Context Engine、Potpie 资源管理、守护进程托管与 CLI 四条边界。明确不在本修订版范围内的事项包括：

• 不改动 parsing 行为（见 SYS-011）；
• 不发布 extension、manifest 或外部宿主协议（见 SYS-015、SYS-016）；
• 精确的 Python façade 方法、controller API、传输层、wire envelope、取消协议、重试键、JSON 字段与数字非零退出码映射全部保持 deferred。

这一定位与 ADR-0006（Deferred runtime concerns）一致：契约先锁定所有权与信任边界，把传输细节留给后续已接受的修订版单独决策。

二、所有权与边界：六方角色的职责表

system.md 用一张所有权表划定了六个边界的"Owns"与"Excludes"，这是理解整个架构的第一把钥匙：

源码印证：capability 化源码布局

这一边界在仓库源码布局中同样可观察。根包 potpie 下按能力拆分：potpie/auth（认证能力）、potpie/cli（CLI 呈现）、potpie/daemon（守护进程）、potpie/pots（pot 与 source 契约与本地持久化）、potpie/runtime（运行时组合与资源管理）、potpie/skills（技能目录与安装策略）、potpie/setup（首次运行编排）。而 Context Engine 是独立可导入的发行版，位于 potpie/context-engine，其源码结构（adapters/inbound、adapters/outbound、application/readers、application/services、application/use_cases、core/ports、domain/ports）与 spec/modules/context-engine.md 中"薄 façade + 聚焦域模块"的目标一一对应。

能力级所有权由 spec/modules/potpie-capabilities.md 进一步细化：配置、Pots、Skills、Setup、Authentication、Agent context composition、Runtime composition 七类能力各自有明确的 Owns/Excludes，并规定"Context Engine 生产代码不得 import 根 Potpie 能力代码"（PCAP-009），最终源码树不得保留potpie.product命名空间（PCAP-010）。

三、参与者与权限：六类边界交互者

关键语义：Context Engine 信任宿主建立调用方身份与权限，但引擎自身仍校验域输入并保持其不可变上下文身份（见 spec/modules/context-engine.md 的 Actors 一节）。

四、两条目标调用路径（Cross-Module Interfaces）

system.md 用两个 ASCII 路径图总结了 SYS-001、SYS-013、SYS-014、SYS-019。这是全契约最核心的实操图景，务必完整掌握：

daemon lifecycle control（守护进程生命周期控制） CLI -> daemon controller -> foreground daemon runtime -> live authenticated readiness via typed client hosted domain execution（托管域执行） CLI -> typed daemon client -> typed daemon operation handler -> handler requests lease from Resource Manager -> Resource Manager issues authorized context lease -> handler invokes explicit ContextEngine operation -> handler releases lease

两条路径的分工在 spec/modules/daemon.md 中被表述为：守护进程运行时只托管一个窄 Resource Manager，每个类型化上下文域 handler 先获取授权 lease，再直接调用 Context Engine；控制类与宿主管理类 handler 不进入这条 lease 路径（DAEMON-045）。

源码印证：controller 与 runtime 的真实拆分

仓库中potpie/daemon/__main__.py（python -m potpie.daemon入口）通过potpie.runtime.composition.build_local_runtime()组装CanonicalDaemonRuntime、通过build_local_resource_manager()构建 Resource Manager，并读取POTPIE_DAEMON_INSTANCE_ID、POTPIE_DAEMON_BEARER_TOKEN、POTPIE_DAEMON_ENDPOINT_*等环境变量——这正是"controller 负责创建进程、runtime 负责就绪与协议"的落地形态。

potpie/runtime/controller.py 中的DaemonController是控制器角色的直接实现：

• start()通过asyncio.create_subprocess_exec创建前台直系子进程（start_new_session=True），随后调用 observer 的wait_ready()等待经过认证的握手，而不是依赖 PID 文件或发现记录；
• attach()允许后续 CLI 调用重新挂接先前启动的长期存活守护进程（明确注释"这不是外部 supervisor 集成"），并置owns_process=False；
• stop()优先走observer.request_stop()的类型化认证关闭；对非自有（attached）进程，若认证关闭不可用则拒绝发送信号并返回ResourceLifecycleError（对应 DAEMON-052/053 与 ADR-0012 的"禁止对运行时记录挂接的进程做信号回退"）；
• ControllerStatus明确区分running（进程存活）与ready（认证握手成功），对应 DAEMON-031"对进程、PID 或发现记录的观察不得被表述为 daemon 就绪"。

potpie/runtime/protocol.py 则定义了协议版本（PROTOCOL_VERSION = 2）、HandshakePayload（携带协议版本区间、期望实例 ID、操作目录指纹）与RuntimeBoundaryError联合类型——这是"live authenticated handshake 作为就绪真相"与"类型化操作目录而非反射"的协议级证据。

五、规范性要求（SYS-001～SYS-023）分组解读

23 条 active 要求均带authority: user:dsantra，并引用 ADR-0001～ADR-0006 作为决策依据。按主题可划分为六个群组：

5.1 规范调用路径（SYS-001、SYS-014、SYS-019、SYS-021）

• SYS-001：Potpie 托管的域调用 canonical 路径必须为CLI -> typed daemon client -> typed daemon operation handler -> authorized context lease -> 对 lease 上 context-bound Context Engine 的显式操作。
• SYS-014：live 端点存在之前的守护进程创建必须经由 controller。
• SYS-019：类型化 handler 必须在获取授权 context lease 后调用显式 Context Engine 操作。
• SYS-021：端点存在后的就绪与 live 守护进程操作必须使用 typed daemon client。

这四条合起来定义了"何时用 controller、何时用 client、何时碰引擎"的唯一正确时序，与 spec/modules/cli.md 的 CLI-004/CLI-023 完全对应。

5.2 Context Engine 的隔离与依赖所有权（SYS-002、SYS-003、SYS-010、SYS-018）

• SYS-002：Context Engine 不得 import 或控制 Potpie 的 daemon、CLI、上下文选择、调用方安全、进程生命周期或呈现关注点。契约引用代码观察potpie/context-engine/src/potpie_context_engine/host/shell.py@a3419788...——即迁移前把域服务与产品生命周期混在一起的 HostShell 正是要消除的对象（对应 CE-027）。
• SYS-003：宿主必须显式提供 Context Engine 的依赖与上下文身份。
• SYS-018：除非类型化构造契约显式转移依赖所有权，宿主必须保留其提供给 Context Engine 的每个依赖的所有权。
• SYS-010：Potpie 托管不得将既有 Context Engine 实例重定向到不同上下文身份。

SYS-018 是 spec/glossary.md 中"Borrowed dependency / Transferred dependency"两词进入规范语义的关键：借用依赖的所有权留在宿主，Context Engine 只使用不关闭；转移依赖则必须经由类型化构造契约显式转移，"绝不能仅凭存在 cleanup 方法就推断转移"。其落地见 Context Engine 契约的 CE-022/CE-023/CE-024 与 Resource Manager 契约的 RM-027/RM-029。

5.3 资源管理与授权归属 Potpie（SYS-004、SYS-008、SYS-022）

• SYS-004：Potpie 必须拥有上下文选择、授权策略、宿主管理资源、依赖组合、context-bound 引擎构造与授权 context lease。
• SYS-008：调用方认证与操作授权必须在受保护域执行之前、且位于 Context Engine 之外完成。
• SYS-022：类型化 handler 不得把域操作分发委托给 Resource Manager。

SYS-004 直接源于 spec/decisions/ADR-0004-potpie-resource-management-ownership.md：Potpie 拥有一个"按职责定义而非按单个类或包定义"的逻辑 Resource Manager。ADR-0004 明确否定了三个备选方案——把设置与资源管理留在引擎内（阻碍引擎被其他宿主独立使用）、让守护进程每次操作直接组合引擎（把引擎构造耦合进传输）、以及创建通用 Potpie 运行时门面（以另一个名字重造 HostShell）。

5.4 Daemon controller 与 runtime 的边界（SYS-005、SYS-013、SYS-023）

• SYS-005：daemon runtime 必须拥有认证 live 进程边界、实例身份、所有权锁、发现、就绪、运行时生命周期与类型化请求处理。
• SYS-013：daemon controller 必须拥有"前台运行时创建 + 进程观察"的 Potpie 控制请求，且位于 daemon runtime 之外。
• SYS-023：controller 可以将物理进程创建委托给其选定的操作系统 supervisor。

5.5 CLI 的呈现职责（SYS-006、SYS-009、SYS-020）

• SYS-006：CLI 必须拥有命令解析、用户交互、人类与机器渲染、标准流策略与进程退出映射。
• SYS-009：人类确认、破坏性意图断言、调用方认证、操作授权与破坏性域执行必须保持为相互独立的步骤。
• SYS-020：CLI 产生的破坏性意图断言在被 Potpie 依据认证 actor、授权操作与已解析上下文身份验证之前，必须视为不可信。

5.6 错误分类与迁移纪律（SYS-007、SYS-011、SYS-012、SYS-015、SYS-016、SYS-017）

• SYS-007：10 类错误必须跨边界保持结构可区分（详见第六节）。
• SYS-011：本修订版下的工作不得重设计 parsing 行为。
• SYS-015 / SYS-016：本修订版不得发布公共扩展/插件注册/manifest 契约，也不得发布外部宿主传输或部署协议。
• SYS-012 / SYS-017：先于实现一致性而提出的目标契约必须指明当前实现差距；未匹配一致性记录时，不得将目标契约表述为已完成实现或已验证一致性。

SYS-012/SYS-017 正是 spec/process.md 所确立的 Git 化规范治理的体现，也是第七节"实现差距快照"存在的原因。

六、数据与状态模型

注意词汇表（spec/glossary.md）的强约束：context identity 不是 pot 显示名、当前 CLI 选择、存储句柄、进程 ID 或 daemon 实例身份（GLOSS-002/GLOSS-008）。"Pot"只是产品层选择与管理上下文的记录，绝不充当引擎身份选择机制。

Lease 的组成（概念模型）

依据 spec/modules/potpie-resource-manager.md，授权 context lease 概念上包含：一个已解析上下文身份、一个绑定该身份的 Context Engine、认证 actor-操作-上下文授权作用域、显式依赖所有权与一个 release 能力。它不包含execute函数、方法转发、任意服务、域结果、传输 DTO 或呈现行为（RM-008、RM-020～RM-023）。

源码印证：resource_manager.py 的 lease 落地

potpie/runtime/resource_manager.py 顶部即定义了SelectionError、AuthenticationError、AuthorizationError、ResourceLifecycleError四个冻结数据类（各自带category字面量与retry_posture），并通过类型别名ResourceManagerError组合为LeaseOutcome = Success[AuthorizedContextLease] | Failure[ResourceManagerError]。文件内ContextSelector（explicit/active/repository三种选择器）与DestructiveIntent的存在，直接对应 RM-001/RM-005"解析到唯一上下文身份"与"破坏性意图断言验证"的契约文本。这也印证了 RM-036 修正（经 ADR-0010）：acquisition 要么返回授权 lease，要么返回 SelectionError、AuthenticationError、AuthorizationError 或 ResourceLifecycleError 之一。

七、失败分类法：10 类跨边界错误

SYS-007 要求以下错误跨边界保持结构可区分，system.md 用一张表汇总了每个类别的 canonical 来源：

这 10 类在 spec/glossary.md 中各有精确语义（GLOSS-007），并在各模块契约中被逐层细化，例如：

• SelectionError必须区分"未知 / 歧义 / 管理不可用"三种变体（RM-004）；已解析上下文后资源获取失败则是ResourceLifecycleError；
• 认证交换本身格式错误是ProtocolTransportError而非AuthenticationError；
• 引擎关闭后仍调用操作返回EngineLifecycleError（CE-025）；
• DaemonInternalError必须是脱敏的运行时缺陷（DAEMON-022），且失败呈现禁止基于异常消息字符串匹配（CLI-026）。

错误翻译顺序在 daemon 契约的 Failure Summary 中完整呈现：ProtocolTransportError（发现缺失/陈旧、非就绪端点）-> AuthenticationError -> AuthorizationError -> 保留 Resource Manager 失败 -> 保留 Context Engine 失败 -> DaemonInternalError；mutating 操作中断返回"结果未知"的ProtocolTransportError，除非另有证明不得自动重放（DAEMON-021、CLI-027）。

八、破坏性操作流程：从确认到执行的信任链

human confirmation or explicit automation flag -> untrusted typed destructive-intent assertion -> daemon authenticates caller -> Potpie resolves context and authorizes actor + operation + context -> Potpie validates the assertion against the resolved authorization -> handler receives validated intent and authorized context lease -> ContextEngine receives an explicit destructive domain command

这条序列是 SYS-009 与 SYS-020 的摘要，它在模块层被强化为：

• CLI 侧：破坏性人类操作必须显式肯定确认或显式非交互确认标志（CLI-009）；机器模式下无显式破坏性意图的破坏性调用必须在分发前失败（CLI-018），且分发前检测到意图断言缺失返回PresentationError（CLI-033）。
• Resource Manager 侧：签发破坏性操作 lease 前必须验证断言与认证 actor、请求操作、选择请求与已解析上下文身份的一致性（RM-005）；验证失败返回AuthorizationError且绝不签发 lease（RM-033、RM-035）。
• Daemon 侧：破坏性 handler 必须先接收经验证的意图与授权 lease，再调用显式破坏性 Context Engine 命令（DAEMON-026），而破坏性引擎操作本身不得通过默认或推断操作可达（CE-034）。

"人类确认不是认证、不是授权"（GLOSS-009/GLOSS-010）这一条被列为整个规范族的验收标准之一：破坏性确认永远不能与认证或授权混淆。

九、兼容性、迁移与验收标准

迁移原则

system.md 的迁移段落只有一句硬性约束：后续提交把当前实现向这些行为迁移，临时兼容不会成为第二个永久架构；有意的可观察行为变更在实现前须遵循 PROD-005。这与 ADR-0007（Context runtime migration path）一致——迁移是有明确删除终态的，而非叠加层。

验收标准（system.md 原文五点）

1. 两条调用路径无需实现代码即可重建；
2. Resource Manager 无法通过分发产品操作来满足契约；
3. 错误与信任边界模型与每个模块契约一致；
4. 破坏性确认不能与认证或授权混淆；
5. 当前实现差距保持为"观察"而非"一致性"。

第五点特别重要：它解释了为什么 spec/conformance 目录下存在独立的 conformance 记录——一致性记录以不可变 artifact 形式钉住绑定契约与实现 ref，逐行为记录验证结果（见 glossary 的 "Conformance record" 词条），新鲜度由钉住的 Git 身份派生，而不是存储在索引元数据中。

十、当前实现差距快照：迁移起点

契约钉在基提交a341978880b9d4c1b403831931279ccedf6184ae，明确列出迁移前的实现现状（这些是"观察"而非"一致性"）：

• potpie/daemon/main.py是当前活跃启动目标，提供反射式/rpc与/attr端点；
• potpie/daemon/client.py动态镜像 HostShell 表面；
• potpie/daemon/rpc.py把 Python 模块与类身份放到 wire 上；
• potpie/daemon/runtime/含一套独立的不完整候选运行时；
• potpie_context_engine/host/shell.py把域服务与产品生命周期、认证、安装、技能、配置、pot 管理混在一起；
• bootstrap/host_wiring.py在引擎包内部组合 Potpie 与 daemon 关注点；
• Context Engine 仍依赖独立发布的 Context Core 包并暴露扩展类型；
• CLI 的人类与机器渲染部分集中化，但破坏性确认尚未端到端一致强制。

上述路径中除potpie_context_engine/...前缀属于旧布局外，当前仓库中可对应观察的还有：potpie/daemon/main.py（新的 canonical 前台入口）与 potpie/runtime 目录（controller、protocol、resource_manager、clients、composition、server、transport 等模块）——它们正是契约目标的进行中实现，而 tests/unit/test_runtime_controller.py（test_operation_coordinator.py、test_runtime_composition.py、test_runtime_transport.py等）提供了这些新边界的行为验证。

十一、与相关契约及 ADR 的关系图

system.md 的每条要求都带有> decision边（ADR-0001～ADR-0006），模块契约再以@引用回系统要求，形成可追溯的规范网络：

总结

SPEC-SYSTEM 的价值不在于规定"怎么实现"，而在于精确划定"谁拥有什么"。它用 23 条 active 要求把六类边界（Context Engine、Resource Manager、Daemon controller、Daemon runtime、Typed daemon client、CLI）的所有权、调用路径、错误分类与破坏性操作信任链固定下来，同时把传输、wire 格式与精确 API 明确 deferred。结合 potpie/runtime 的进行中实现与 potpie/daemon 的新入口，读者既可以把它当作审查 Potpie 架构的目标蓝图，也可以把它当作评估"Context Engine 可独立导入、产品层可独立托管"这一设计是否成立的验收清单——其终态是：Context Engine 是一个只认显式依赖与绑定身份的薄域库，而 Potpie 则集中拥有选择、授权、资源、进程与呈现。

【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie