企业官网建设流程全解析

解析 Potpie ADR-0006：以「刻意延期」换取稳定的 Context Runtime 迁移边界

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

导读

ADR-0006（Deferred Runtime Concerns）是 Potpie 面向 AI Native SDLC 的 Context Graph 产品在架构迁移期做出的一项关键决策：在第一个迁移提交（commit 1）中，刻意搁置解析器重构、插件与扩展契约、外部托管协议、Context Engine 门面方法分组、授权上下文租约的 Python 表示、守护进程控制器 API、传输与线协议细节、机器 JSON 与退出码映射、以及旧组件移除顺序等九类尚未成熟的问题，从而让「所有权、身份、类型化边界、发现、就绪、并发、呈现、破坏性意图、删除终态」这些已被接受的架构不变量先行绑定。读完本文，你将理解 Potpie 的契约治理体系中「绑定什么、延期什么、如何延期」三者之间的分工逻辑，并能在仓库源码中看到这些延期项随后如何被 ADR-0007～ADR-0009 逐个收敛、最终落入potpie/runtime/的真实实现。

决策背景：为什么第一个迁移提交需要「稳定的所有权边界」

ADR-0006 的 Context 部分给出了延期的核心动机：Context Engine、Potpie Resource Manager、daemon、CLI 四者边界的大迁移需要一个可先行绑定的所有权边界。如果解析器重构、扩展系统、外部托管部署、精确的公开方法与每一条线协议细节在同一时间被设计，那么验收就会依赖与主线无关的旁支选择，并让投机性抽象（speculative abstractions）被保留下来。

换句话说，一份契约如果同时回答「架构往哪走」和「某个字段叫什么」两类问题，前者往往会被后者的争论拖住。ADR-0006 的做法是把两者拆开：架构问题立即绑定，实现细节问题记录在案、明确延期，且每个延期项都必须在后续实现提交依赖它之前，先形成一份独立的决策。

从规范治理层面看，这一做法与 ADR-0001（Git-Based Living Specifications） 一脉相承：spec/下的 Markdown 是权威行为契约，契约成熟度、行为生命周期、实现声明、验证结果与派生新鲜度是五个独立状态轴；ADR 只负责解释「为什么存在某个契约」，实现展示「软件在选定 ref 上如何表现」，一致性记录保存「被固定的声明与证据」。ADR-0006 正是这套体系里「延期也是一种决策」的标准化表达。

决策核心：被刻意延期的九类事项

ADR-0006 明确列出本修订版刻意延期（deliberately defers）的完整清单，这是全文最需要逐项保留的骨架：

1. 解析器重构（Parsing redesign）——不在此轮定义解析架构。
2. 公开插件、扩展注册与 manifest 契约（Public plugin, extension-registration, and manifest contracts）。
3. 外部托管传输与部署协议（External-host transport and deployment protocols）。
4. Context Engine 门面的精确方法分组与同步/异步暴露方式（Exact Context Engine façade method grouping and sync/async exposure）。
5. 授权上下文租约（authorized-context-lease）的精确 Python 表示。
6. 守护进程控制器 API 与操作系统 supervisor 集成的精确形态。
7. 守护进程传输选型、线协议字段、取消、超时传播、幂等键、操作并发矩阵。
8. 机器可读 JSON 的精确字段与完整的非零退出码映射。
9. Context Core、HostShell、现行反射型守护进程与未完成候选运行时的兼容与移除顺序。

值得注意的是，清单第 9 项包含一个微妙的区分：删除顺序（order of deletion）被延期，但最终必须删除（required final removal）没有被延期。也就是说，迁移终态是硬约束，先删谁后删谁才是可以后续决策的弹性问题。

同时 ADR-0006 强调：上述细节被延期，并不影响已接受契约中所有权、身份、类型化边界、发现、就绪、并发、呈现、破坏性意图与删除终态这些不变量立即生效——「细节没定」不等于「边界没绑」。

延期与绑定的边界：什么立即生效，什么后续决策

为了说清「延期不削弱契约」，ADR-0006 依赖的是 Potpie 规范体系中一套严谨的状态机制。在 open questions 日志 里可以看到与 ADR-0006 直接关联的原始问题记录：每个延期项都带decision [active]: decision:ADR-0006引用，并配有明确的 decision-trigger（触发条件）。例如：

• OQ-DAEMON-CANCEL-001（取消/超时/断连语义）——触发条件：在类型化协议中暴露取消或超时之前；
• OQ-DAEMON-IDEMPOTENCY-001（幂等键与重试身份）——触发条件：实现客户端或守护进程变更重试之前；
• OQ-CLI-JSON-001（机器 JSON 信封与退出码映射）——触发条件：改变现有机器输出或退出映射之前；
• OQ-AUTH-MODEL-001（跨本地 IPC、登录、托管、集成、浏览器客户端的统一身份模型）——触发条件：实现浏览器认证、托管客户端认证或最终本地 IPC 身份契约之前。

这些被延期问题的共同特征是：当前没有已接受的活跃行为依赖它们。按 Specification Process 中PROC-008的规定，「已接受的活跃或已弃用行为不得包含未解决的问题边」，因此延期项被严格挡在活跃行为之外；一旦后续实现提交需要答案，就必须先形成独立的 ADR 解决对应问题（process.md 中OQ问题的 resolution 字段正是用来记录这种「问题→决策」的闭合关系）。

后续如何逐个收敛：ADR-0007 与 ADR-0009 的衔接

ADR-0006 的「延期」不是无限期搁置，而是给后续决策留出节奏。仓库中 12 条 ADR 的演进清晰地展示了收敛路径：

• ADR-0007（Replace Both Daemon Stacks Through A Same-PR Migration）解决了第 9 项中的「移除顺序」问题：先移除未上线、无生产调用路径的候选运行时，再保留反射型旧栈仅用于完成调用方迁移，最后在同一 PR 内删除全部临时 shim；同时它显式声明不触碰第 4、6、7、8 项等其余延期内容。
• ADR-0009（Typed Local Runtime Execution Contract）一次性解决了第 5、6、7 项的大部分：定义了AuthorizedContextLease的异步表示、DaemonController直接启动前台子进程、Unix-domain socket（POSIX）与认证回环 TCP 的传输选型、POST /v1/operations的版本化操作信封、四类操作安全级别与冲突键、以及未签名但绑定请求上下文的破坏性意图断言。
• ADR-0008（Async Context Engine Public Contract）解决了第 4 项中 Context Engine 门面的同步/异步形态问题。

截至 决策注册表，ADR-0006 的九个延期方向中，第 4、5、6、7 项已经由 ADR-0008/ADR-0009 覆盖，第 9 项的顺序问题由 ADR-0007 覆盖；而第 1、2、3、8 项（解析器重构、插件契约、外部托管协议、机器 JSON 与退出码映射）目前仍然没有可与之对应的新决策，属于「有意保持延期」的领域——这正是 ADR-0006 被标注为 accepted 后仍然持续生效的原因。

仓库落地证据：从延期决策到potpie/runtime/实现

ADR 是「为什么」，实现是「怎么样」。在 potpie/runtime/ 下可以看到 ADR-0009 决策（即 ADR-0006 延期项的收敛结果）的落地形态：

类型化协议（protocol.py）：文件头定义了PROTOCOL_VERSION = 2与最小/最大协议版本，随后用冻结 dataclass 表达了完整的请求/响应信封——EngineOperationRequest（协议版本、request_id、有限operation判别器、精确的ContextSelector、操作专属payload、可选的destructive_intent）、HandshakeRequest、ShutdownRequest、DaemonStatusRequest；响应统一为SuccessResponse[T] | FailureResponse，且错误载荷携带category、稳定code、安全message、结构化details、recommended_next_action与retry_posture。response_validation_error还专门校验响应与请求的request_id与协议版本一致性——这正是 ADR-0009 中「响应重复协议版本与请求 ID」约束的实现。

认证传输（transport.py）：RuntimeEndpoint校验 UDS 路径必须为绝对路径、TCP 地址必须是回环 IP（address.is_loopback）；HttpDaemonTransport将请求 POST 到/v1/operations，携带Authorization: Bearer <token>，并把连接类失败与已投递后的传输失败区分编码为TransportFailure(dispatched=...)——对应 ADR-0009「变更后传输失败返回 unknown-outcome 重试姿态、不自动重放」的约束。

外部控制器（controller.py）：DaemonController通过DaemonLaunchSpec（command/cwd/environment/log_path）直接启动并观察前台子进程，ControllerStatus区分running与ready，StopResult区分typed_shutdown/terminated/killed等停止模式——实现 ADR-0009「控制器拥有启动、停止、重启、状态、日志、失败上报与陈旧进程清理，但不声称就绪、不执行领域操作」的边界。

这些文件对应的行为语义，最终由 Potpie Daemon 契约（DAEMON-001起）与 CLI 契约 约束，形成「决策 → 契约 → 实现 → 一致性记录」的完整闭环。

决策后果：五条可验证的演进规则

ADR-0006 的 Consequences 部分给出了延期决策带来的五条直接后果，它们是理解整个迁移策略的钥匙：

1. Commit 1 可以在没有投机 API 的情况下绑定持久架构——第一提交只固化所有权与类型化边界，不为未来可能性预留接口。
2. 后续实现提交在遇到被延期问题时必须停下，先接受必要的契约修订再继续——实现不能擅自替决策者回答延期问题（对应 process.md 的PROC-009：代码、测试、事故、文档与运行时观测不得在缺少已接受契约修订的情况下覆盖已接受行为）。
3. Context Engine 保持与未来宿主兼容，却无需现在发布外部宿主协议——兼容性来自边界稳定而非协议公开。
4. 现有扩展与运行时代码的存在本身不构成公开承诺——「代码存在」只是观察（observation），不是权威（authority）；这一点与 ADR-0001「已合并代码或通过测试不构成契约」的立场完全一致。
5. 并发决策会在实现替代协调机制之前先选择类型化安全类别与冲突范围——为 ADR-0009 的四类操作安全级别（shared context read / exclusive context mutation / exclusive resource mutation / daemon lifecycle control）埋下伏笔。

备选方案分析：为什么其他三条路都被拒绝

ADR-0006 记录了三个被否定的备选方案，每个都对应一类常见的架构治理陷阱：

• 在 commit 1 中设计每一个 API 与协议：会把边界验收与需要实现 spike、兼容性分析和独立用户决策的细节混在一起，导致主线验收被旁支绑架——这是本决策要避免的核心问题。
• 把现有扩展与运行时代码视为已接受：现有代码是「观察」而非「权威」，且包含相互竞争、彼此不完整的方案（例如反射型 daemon 与未完成候选运行时并存），不能仅因存在就获得契约地位。
• 直接移除延期主题而不做记录：会让后来的实现者无法区分「刻意延期」与「意外遗漏」。延期本身必须留下可审计的痕迹——这正是 open questions 日志和每条> decision [active]: decision:ADR-0006引用存在的意义。

影响面与后续变更记录

ADR-0006 的 Affected Behavior IDs 一节明确说明：受影响的规范行为视图由活跃的> decision:ADR-0006边派生，不在文档内重复维护，这样后续行为拆分不会留下过期的反向列表——这与 ADR-0001 的「反向影响从规范正向依赖、出处、问题与仓库引用派生」原则一致，也解释了为什么查看该 ADR 的影响面需要去各契约的行为节点（如 context-engine 契约、daemon 契约）而非 ADR 本身。

其后续变更记录指向四条初始契约的建立：

• SPEC-CHANGE-0003（产品契约）
• SPEC-CHANGE-0004（系统契约）
• SPEC-CHANGE-0005（Context Engine 契约）
• SPEC-CHANGE-0008（CLI 契约）

这四条变更记录与 spec/index.md 中的契约注册表相互印证：修订 1 的产品、系统、Context Engine、CLI 契约在2026-08-20同日被接受，构成了 commit 1 绑定的「无投机 API」基础面，而 ADR-0006 负责在这些契约之外圈出「本轮不决策」的安全区。

小结：延期是一种需要纪律的架构决策

Potpie 的 ADR-0006 展示了一个值得借鉴的工程方法论：架构迁移的第一步不是设计一切，而是定义「哪些现在必须绑定、哪些可以晚点决定、以及如何让延期可被追踪」。它通过三件事保证纪律——被延期事项逐条列出并给出触发条件（open questions）、延期不解除删除终态等硬约束（final removal not deferred）、任何实现提交不得越过延期问题擅自作答（PROC-009 + 「先接受契约修订」规则）。对于正在做大规模边界重构的读者，ADR-0006 提供了一份可直接套用的清单模板：把「解析器、插件、外部托管、门面形态、租约表示、控制器 API、传输协议、机器输出、移除顺序」这类高风险未决项，与「所有权、身份、类型化边界、发现、就绪、并发、呈现、破坏性意图、删除终态」这类立即可绑定的不变量分开管理，迁移才能既快又不失控。

后续阅读建议按 spec/index.md 的阅读顺序 展开：先读 ADR-0001 理解契约治理，再读 ADR-0007 与 ADR-0009 看延期项如何被收敛，最后对照 protocol.py、transport.py、controller.py 验证实现的落地形态。

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