解析 Potpie ADR-0006以「刻意延期」换取稳定的 Context Runtime 迁移边界【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读ADR-0006Deferred Runtime Concerns是 Potpie 面向 AI Native SDLC 的 Context Graph 产品在架构迁移期做出的一项关键决策在第一个迁移提交commit 1中刻意搁置解析器重构、插件与扩展契约、外部托管协议、Context Engine 门面方法分组、授权上下文租约的 Python 表示、守护进程控制器 API、传输与线协议细节、机器 JSON 与退出码映射、以及旧组件移除顺序等九类尚未成熟的问题从而让「所有权、身份、类型化边界、发现、就绪、并发、呈现、破坏性意图、删除终态」这些已被接受的架构不变量先行绑定。读完本文你将理解 Potpie 的契约治理体系中「绑定什么、延期什么、如何延期」三者之间的分工逻辑并能在仓库源码中看到这些延期项随后如何被 ADR-0007ADR-0009 逐个收敛、最终落入potpie/runtime/的真实实现。决策背景为什么第一个迁移提交需要「稳定的所有权边界」ADR-0006 的 Context 部分给出了延期的核心动机Context Engine、Potpie Resource Manager、daemon、CLI 四者边界的大迁移需要一个可先行绑定的所有权边界。如果解析器重构、扩展系统、外部托管部署、精确的公开方法与每一条线协议细节在同一时间被设计那么验收就会依赖与主线无关的旁支选择并让投机性抽象speculative abstractions被保留下来。换句话说一份契约如果同时回答「架构往哪走」和「某个字段叫什么」两类问题前者往往会被后者的争论拖住。ADR-0006 的做法是把两者拆开架构问题立即绑定实现细节问题记录在案、明确延期且每个延期项都必须在后续实现提交依赖它之前先形成一份独立的决策。从规范治理层面看这一做法与 ADR-0001Git-Based Living Specifications 一脉相承spec/下的 Markdown 是权威行为契约契约成熟度、行为生命周期、实现声明、验证结果与派生新鲜度是五个独立状态轴ADR 只负责解释「为什么存在某个契约」实现展示「软件在选定 ref 上如何表现」一致性记录保存「被固定的声明与证据」。ADR-0006 正是这套体系里「延期也是一种决策」的标准化表达。决策核心被刻意延期的九类事项ADR-0006 明确列出本修订版刻意延期deliberately defers的完整清单这是全文最需要逐项保留的骨架解析器重构Parsing redesign——不在此轮定义解析架构。公开插件、扩展注册与 manifest 契约Public plugin, extension-registration, and manifest contracts。外部托管传输与部署协议External-host transport and deployment protocols。Context Engine 门面的精确方法分组与同步/异步暴露方式Exact Context Engine façade method grouping and sync/async exposure。授权上下文租约authorized-context-lease的精确 Python 表示。守护进程控制器 API 与操作系统 supervisor 集成的精确形态。守护进程传输选型、线协议字段、取消、超时传播、幂等键、操作并发矩阵。机器可读 JSON 的精确字段与完整的非零退出码映射。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-0007Replace Both Daemon Stacks Through A Same-PR Migration解决了第 9 项中的「移除顺序」问题先移除未上线、无生产调用路径的候选运行时再保留反射型旧栈仅用于完成调用方迁移最后在同一 PR 内删除全部临时 shim同时它显式声明不触碰第 4、6、7、8 项等其余延期内容。ADR-0009Typed Local Runtime Execution Contract一次性解决了第 5、6、7 项的大部分定义了AuthorizedContextLease的异步表示、DaemonController直接启动前台子进程、Unix-domain socketPOSIX与认证回环 TCP 的传输选型、POST /v1/operations的版本化操作信封、四类操作安全级别与冲突键、以及未签名但绑定请求上下文的破坏性意图断言。ADR-0008Async 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.pyRuntimeEndpoint校验 UDS 路径必须为绝对路径、TCP 地址必须是回环 IPaddress.is_loopbackHttpDaemonTransport将请求 POST 到/v1/operations携带Authorization: Bearer token并把连接类失败与已投递后的传输失败区分编码为TransportFailure(dispatched...)——对应 ADR-0009「变更后传输失败返回 unknown-outcome 重试姿态、不自动重放」的约束。外部控制器controller.pyDaemonController通过DaemonLaunchSpeccommand/cwd/environment/log_path直接启动并观察前台子进程ControllerStatus区分running与readyStopResult区分typed_shutdown/terminated/killed等停止模式——实现 ADR-0009「控制器拥有启动、停止、重启、状态、日志、失败上报与陈旧进程清理但不声称就绪、不执行领域操作」的边界。这些文件对应的行为语义最终由 Potpie Daemon 契约DAEMON-001起与 CLI 契约 约束形成「决策 → 契约 → 实现 → 一致性记录」的完整闭环。决策后果五条可验证的演进规则ADR-0006 的 Consequences 部分给出了延期决策带来的五条直接后果它们是理解整个迁移策略的钥匙Commit 1 可以在没有投机 API 的情况下绑定持久架构——第一提交只固化所有权与类型化边界不为未来可能性预留接口。后续实现提交在遇到被延期问题时必须停下先接受必要的契约修订再继续——实现不能擅自替决策者回答延期问题对应 process.md 的PROC-009代码、测试、事故、文档与运行时观测不得在缺少已接受契约修订的情况下覆盖已接受行为。Context Engine 保持与未来宿主兼容却无需现在发布外部宿主协议——兼容性来自边界稳定而非协议公开。现有扩展与运行时代码的存在本身不构成公开承诺——「代码存在」只是观察observation不是权威authority这一点与 ADR-0001「已合并代码或通过测试不构成契约」的立场完全一致。并发决策会在实现替代协调机制之前先选择类型化安全类别与冲突范围——为 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-0005Context Engine 契约SPEC-CHANGE-0008CLI 契约这四条变更记录与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考