Potpie Context Runtime 产品契约解读:Context Engine 与 Potpie 宿主边界的规范化拆分
Potpie Context Runtime 产品契约解读:Context Engine 与 Potpie 宿主边界的规范化拆分
导读
本文深入解析 Potpie 仓库中作为「Context Runtime 产品契约」核心文件的 spec/product.md。该契约在 Potpie 为 AI 原生 SDLC 提供 Context Graph 能力的背景下,明确回答了三个根本性问题:Context Engine 作为可独立导入的库如何保持边界纯净、Potpie 作为托管宿主如何负责上下文选择与资源管理、以及人类用户与自动化调用者如何在同一个类型化操作面上获得不同的呈现体验。读完本文,你将掌握 PROD-001 至 PROD-007 七条规范性行为要求的含义、其背后的六项架构决策(ADR-0001 至 ADR-0006)以及它们在仓库规格树与源码布局中的落地对应关系。
一、契约背景:为什么需要在实现迁移之前先锁定产品边界
Potpie 的规格体系采用"契约先于实现"的治理方式。spec/index.md 中明确指出:"Canonical target behavior lives in contract envelopes and behavior nodes"(目标行为以契约信封与行为节点为准),而现有架构文档与代码只是实现快照,在迁移完成之前可以与目标契约不一致。
产品契约正是在这一前提下诞生的。它的核心使命(Purpose)表述为:
Potpie provides a managed local product experience around an independently usable Context Engine.
即:Potpie 围绕一个可独立使用的 Context Engine,提供一个受管理的本地产品体验。契约定义了迁移期间系统与模块边界必须保持的产品结果(product outcomes)。这一契约的建立对应变更记录 SPEC-CHANGE-0003-initialize-product-contract.md,其状态为 accepted,修订号为 revision 1,接受人为 user:dsantra。
特别值得注意的是,该契约在制定之初就明确:接受契约不代表实现或验证的一致性声明(对应 PROD-007),第一提交只修改规格树本身。
二、三类用户与工作流:契约服务的对象
product.md 将产品的使用者划分为三类,每一类都有截然不同的交互期望:
| 用户类型 | 交互方式 | 关键诉求 |
|---|---|---|
| Library integrator(库集成方) | 兼容的 Python 宿主导入 Context Engine,提供上下文身份与依赖,调用上下文域操作 | 不导入 Potpie daemon 或 CLI 内部实现即可完成全部集成 |
| Human CLI user(人类 CLI 用户) | 使用 Potpie 命令、可读输出、进度、提示与修复引导 | Potpie 代管上下文选择、授权、资源与托管 |
| Automation caller(自动化调用方) | 脚本或编码工具通过非提示式的机器可读 CLI 契约调用同一套类型化操作 | 同一套产品操作,但呈现行为与人类完全不同 |
这"同一套类型化操作、两套呈现行为"的设计,正是契约中 PROD-003 的直接来源,并在 ADR-0005-typed-daemon-and-cli-boundary.md 中被落实为"CLI 拥有呈现(CLI-owned presentation)"的决策。
三、目标与非目标:契约的边界工程
Goals(目标)
- 让 Context Engine 成为连贯、可导入的库边界(coherent importable library boundary);
- 让 Potpie 成为围绕该库的聚焦的产品宿主边界(focused product-host boundary);
- 在直接使用与 daemon 托管使用两种路径下保持上下文域语义一致;
- 让人类与机器的 CLI 体验显式化(explicit);
- 在实现迁移开始之前确立目标契约。
Non-Goals(非目标)
契约同样严格界定了本修订不做的事,防止范围蔓延:
- 解析(parsing)重设计;
- 公共插件、扩展或清单(manifest)模型;
- 外部宿主的传输或部署协议;
- 新的端用户上下文域能力;
- 确切的 daemon 线格式(wire fields)或传输选择;
- 确切的 CLI JSON 字段或数字失败码映射;
- 本提交中的实现或一致性声明。
这些"刻意推迟"的决策细节在 ADR-0006-deferred-runtime-concerns.md 中有完整清单,包括确切的 Context Engine 门面方法分组、授权上下文租约的 Python 表示、daemon 控制器 API 等——它们不阻塞契约接受,但后续实现若触及必须先行修订契约。
四、规范性要求 PROD-001 至 PROD-007 逐条解读
产品契约的规范核心是七条带稳定标识符的行为要求(Normative Requirements),每条都带有 authority(权威方 user:dsantra)与 decision(决策引用)的溯源标注:
PROD-001 [active]:库边界的独立性
兼容宿主必须能够在不导入 Potpie daemon 或 CLI 内部实现的前提下导入、构造并操作 Context Engine。
这条是整个产品契约的基石,对应 ADR-0002-single-importable-context-engine.md 中"单一可导入 Context Engine 发行版"的决策。在该决策中,Potpie 被要求只保留一个 potpie-context-engine 发行版,ContextEngine 是其有限、轻薄的门面,不得暴露通用服务查找、动态分发或产品运行时图。仓库中的门面入口对应 potpie/context-engine/src/potpie_context_engine/api.py。
PROD-002 [active]:宿主的托管职责
Potpie 必须围绕 Context Engine 提供受管理的产品体验,包括上下文选择、授权范围、资源组合、daemon 托管与 CLI 呈现。
对应 ADR-0004-potpie-resource-management-ownership.md:Potpie 拥有一个聚焦的逻辑 Resource Manager,负责解析选择、应用授权、获取宿主托管资源、构造或复用绑定上下文的引擎,并返回带显式所有权与释放语义的授权上下文租约。
PROD-003 [active]:人类与机器呈现分离
人类用户与自动化用户必须在同一套类型化产品操作之上获得不同的呈现行为。
对应 ADR-0005-typed-daemon-and-cli-boundary.md:CLI 拥有全部人类与机器呈现,破坏性确认(destructive confirmation)成为不可信的、类型化的断言(assertion),由 Resource Manager 在 handler 调用破坏性域命令之前校验。
PROD-004 [active]:域语义跨托管模式守恒
Potpie 托管必须在兼容的直接组合与 daemon 托管组合之间保持 Context Engine 域语义。
这条同时引用 PROD-001 与 PROD-002,对应 ADR-0003-explicit-composition-and-context-scoping.md 的显式组合与不可变上下文作用域决策。
PROD-005 [active]:行为变更必须先过契约审查
在有意改变可观察的 Context Engine 行为之前,后续实现变更必须识别该行为并获得接受修订契约的授权。
这是契约对"未来变更"的纪律约束,防止绕过审查的隐性行为漂移。
PROD-006 [active]:提交 1 不得引入新能力
提交 1(Commit 1)不得引入新的端用户上下文域能力。
PROD-007 [active]:接受≠一致性声明
接受这套契约不得被表述为实现或验证的一致性声明。
五、约束、成功标准与理由
Constraints(约束)
契约明确指出:第一提交只修改规格树;现有架构文档仍是实现快照;在后续提交完成迁移之前,当前源码可以与本目标契约相矛盾。这一约束对读者非常重要——在浏览仓库源码时,如果发现代码尚未完全符合本契约,属于预期内的迁移中间态,而非契约失效。
Success Criteria(成功标准)
- 新读者能够区分 Context Engine 与 Potpie 宿主;
- 库集成方能够理解独立可用性;
- 人类与自动化用户拥有显式的呈现边界;
- 直接与 daemon 托管路径收敛到相同的域语义;
- 契约不引入解析、扩展、外部宿主或新特性设计。
Rationale(理由)
将引擎与 Potpie 托管宿主分离,可以让库在其他组合中持续有用,同时保持 Potpie CLI 体验的连贯性与操作安全性;兼容性规则避免宣称未经枚举的基线,同时防止有意的行为变更绕过契约审查。
六、在规格体系中的位置:从产品契约到模块契约
产品契约并非孤立文件,它是整个规格体系的一环。spec/index.md 给出了推荐阅读顺序(Read Order):
process.md -> glossary.md -> product.md -> system.md
-> potpie-capabilities.md -> context-engine.md -> potpie-resource-manager.md
-> daemon.md -> cli.md
以及精确的依赖关系:SPEC-PRODUCT 直接依赖 SPEC-GLOSSARY;SPEC-SYSTEM 依赖 GLOSSARY 与 PRODUCT;后续的模块契约依次向下依赖。运行时层次主线(runtime layering spine)为:
CLI -> daemon -> Resource Manager -> Context Engine
规格树共登记 240 条 accepted 行为节点,其中 SPEC-PRODUCT 贡献 7 条(即 PROD-001~007)。产品契约的产品级承诺被下游模块契约逐层细化:
- spec/modules/context-engine.md 将 PROD-001 落实为 CE-001~CE-034 共 34 条引擎侧行为,例如 CE-005(宿主必须显式提供上下文身份、依赖与所有权模式)、CE-013(Context Engine 不得提示、打印或渲染终端呈现)、CE-014(不得认证调用者或执行 Potpie 授权策略);
- spec/modules/potpie-capabilities.md 将 PROD-002/PROD-004 落实为 PCAP-001~PCAP-012 的按能力(capability)组织的根源码归属;
- spec/modules/potpie-resource-manager.md、spec/modules/daemon.md、spec/modules/cli.md 分别承接授权租约、托管运行时与双态呈现的细化要求。
七、支撑它的六项架构决策(ADR)
产品契约的每条规范性要求都锚定到 ADR。六项决策共同构成了契约的"为什么":
| ADR | 主题 | 对产品契约的贡献 |
|---|---|---|
| ADR-0001 | Git 活规格与显式接受 | 契约可先于实现被接受;PROD-007 的依据 |
| ADR-0002 | 单一可导入引擎发行版 | PROD-001 的直接依据;移除 HostShell |
| ADR-0003 | 显式组合与不可变上下文作用域 | PROD-004;一实例永绑定一上下文身份 |
| ADR-0004 | 资源管理归属 Potpie | PROD-002;授权上下文租约 |
| ADR-0005 | 单一类型化 daemon 边界与 CLI 呈现 | PROD-003;呈现与协议解耦 |
| ADR-0006 | 推迟解析/扩展/外部托管/协议细节 | PROD-005/PROD-006;Non-Goals 的依据 |
八、从契约到实现:仓库中的印证
虽然产品契约明言"不宣称实现一致性",但仓库已能观察到向该目标迁移的痕迹:
- 引擎库边界:potpie/context-engine/src/potpie_context_engine/api.py 与 potpie/context-engine/pyproject.toml 对应 CE-001/CE-003 的单发行版要求;
- 能力化组织:根
potpie/目录已按auth、cli、config、pots、runtime、setup、skills等能力命名空间组织(对应 PCAP-001),potpie/runtime/composition.py是跨能力装配点(PCAP-008),potpie/cli/main.py 提供人类 CLI 入口; - 行为保持验证:仓库提供面向规格边界的刻画测试,例如 tests/characterization/test_product_process_surfaces.py,用于验证产品/流程表面的稳定性;
- 一致性记录:spec/conformance/index.md 按模块维护被固定的(pinned)实现与验证记录,新鲜度由固定标识(commit hash)推导而非存储。
九、结论:一份"先锁定边界、再迁移实现"的工程范本
Potpie 的 Context Runtime 产品契约展示了一种可复制的重构方法论:在动代码之前,先用带稳定标识符、显式权威方与决策溯源的行为契约锁定产品级边界,明确目标与非目标,再将产品承诺逐层细化到系统与模块契约。对于库集成方、CLI 用户与自动化调用者三类角色的显式区分,以及对"接受≠一致"的严格纪律,使得这场大迁移既不会产生隐性行为漂移,也不会让任何一方误读当前实现状态。理解 spec/product.md,就等于掌握了理解整个 Potpie 规格树与后续迁移提交的钥匙。