Potpie Context Runtime 规范体系基于 Git 的活体契约如何锁定 CLI、Daemon、Resource Manager 与 Context Engine 的边界【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie本文是 PotpieContext Graph for AI Native SDLC仓库spec/目录的规范索引spec/index.md导读它是一份契约的契约把 Context Engine 库、Potpie Resource Manager、守护进程Daemon与 CLI 四者的目标边界、验收权威、变更流程与一致性验证组织成一套可由 Git 历史追溯的活体规范体系。读完本文你将掌握该索引的阅读顺序、9 份已接受契约与 240 个行为节点的组织方式、12 份 ADR 与 12 份变更记录的追溯逻辑以及如何通过一致性记录判断规范声称与实现证据之间的新鲜度差距。为什么 Potpie 需要一份规范索引Potpie 正在把 Context Engine 从 Potpie 产品宿主中剥离成独立可导入的库并同时重构 Daemon 与 CLI 的边界。这类迁移面临一个典型困境目标架构必须先于实现被接受而现有的架构文档只是实现快照通过测试也无法说明谁授权了某个行为承诺详见 ADR-0001。spec/index.md正是为回答这个问题而存在的导航入口它不承载具体行为而是告诉你——规范文本contracts是权威决策decisions解释原因变更记录change records描述修订迁移未决问题questions保留被推迟的选择一致性记录conformance则独立描述实现与证据。这种角色分离是理解整个spec/目录的第一把钥匙。目录角色划分与阅读顺序spec/目录下每类文件承担不同职责索引明确给出了推荐阅读顺序Read Order规范流程SPEC-PROCESS术语表SPEC-GLOSSARY产品契约SPEC-PRODUCT系统契约SPEC-SYSTEMPotpie 能力契约Context Engine 契约Potpie Resource Manager 契约Daemon 契约CLI 契约相关的决策与未决问题、变更记录一致性索引这个顺序本身就是一种依赖排序先理解如何制定规范流程再统一术语词汇表然后从产品目标、系统整体边界逐步收敛到每个模块的规范要求最后用决策、变更与一致性证据来验证。索引强调契约信封contract envelopes与行为节点behavior nodes才是规范文本本身索引中的表格只是派生的导航视图。两条目标调用路径索引用两张 ASCII 图定义了迁移的目标形态。第一条是Daemon 生命周期控制daemon lifecycle control human or automation | v Potpie CLI - external daemon controller - foreground daemon runtime | v authenticated readiness through typed client第二条是托管域执行hosted domain executionhosted domain execution Potpie CLI - typed daemon client - explicit typed daemon operation handler - handler requests authorized context lease - Resource Manager issues lease - handler invokes explicit ContextEngine operation - handler releases lease注意两条路径的关键区别控制器controller负责进程创建与观察绝不声称就绪就绪只能通过 typed client 的实时认证握手建立。而托管域执行路径中只有类型化操作处理器能拿到授权上下文租约并直接调用 ContextEngineResource Manager 永远不接收域调用本身或其结果对应 daemon.md 中 DAEMON-006 / DAEMON-028 / DAEMON-045 与 potpie-resource-manager.md 中 RM-022 / RM-023。索引还特别说明直接兼容宿主direct compatible hosts可以在 Context Engine 边界进入但必须携带显式身份、依赖集与所有权声明——这正是 CE-005 的要求。契约注册表9 份契约与 240 个行为节点索引的 Contract Registry 表格列出全部 9 份契约状态为已接受accepted共240 个活跃行为节点ID文件修订成熟度行为数内容摘要SPEC-PROCESSprocess.md2accepted26权威、验收、变更、稳定一致性存储与验证策略SPEC-GLOSSARYglossary.md1accepted12规范运行时、租约、所有权与错误术语SPEC-PRODUCTproduct.md1accepted7产品目标与非目标SPEC-SYSTEMsystem.md1accepted23跨模块所有权、信任、错误与调用路径契约SPEC-POTPIE-CAPABILITIESpotpie-capabilities.md1accepted12面向能力的根源码所有权与行为保持迁移SPEC-CONTEXT-ENGINEcontext-engine.md1accepted34可导入的薄 Context 域库边界SPEC-POTPIE-RESOURCE-MANAGERpotpie-resource-manager.md2accepted37授权上下文租约与资源生命周期边界含独立认证失败SPEC-DAEMONdaemon.md2accepted56控制器、类型化运行时、发现、就绪、生命周期、处理器与信号权威SPEC-CLIcli.md1accepted33人机呈现与控制器/客户端选择各契约的核心主张SPEC-PROCESSrev 2定义了五条独立状态轴——契约成熟度draft/proposed/accepted/retired、行为生命周期active/deprecated/retired、实现声明、验证结果、派生新鲜度process.md 的状态模型表。PROC-001 至 PROC-026 是规范流程自身的行为要求例如每份已接受契约的每次编辑必须分配下一个正整数修订PROC-002仅被流程点名的验收权威可以绑定契约修订PROC-003实现声明与验证结果只能记录在一致性记录中PROC-005已接受修订必须始终可通过 Git 历史寻址PROC-007。SPEC-GLOSSARYrev 1统一了 Context identity、Borrowed/Transferred dependency、Authorized context lease、Discovery record、Authenticated readiness handshake 等术语并固定了十类错误类别glossary.md 的 GLOSS-007。其核心纪律是一个概念不得顶替多个职责——例如 context identity 不得被当作 pot 显示名、当前 CLI 选择、存储句柄、进程标识符或 daemon 实例身份GLOSS-008。SPEC-PRODUCTrev 1明确三类用户与工作流——库集成者library integrator不导入 daemon/CLI 内部即可使用引擎、人工 CLI 用户、自动化调用者automation caller通过非提示的机器可读 CLI 契约调用同一套类型化产品操作见 product.md。SPEC-SYSTEMrev 1给出跨模块所有权矩阵与失败分类学——十类错误的规范来源SelectionError 来自 Potpie 上下文解析、AuthenticationError 来自 Daemon 认证策略、AuthorizationError 来自 Potpie 授权策略、ResourceLifecycleError 来自宿主资源管理、DomainError/DependencyError/EngineLifecycleError 来自 Context Engine、ProtocolTransportError 来自协议边界、DaemonInternalError 来自运行时缺陷、PresentationError 来自 CLI 本地解析/渲染见 system.md。它还定义了破坏性操作流人工确认或显式自动化标志 → 不可信的类型化破坏性意图断言 → daemon 认证调用者 → Potpie 解析上下文并授权 → 校验断言 → 处理器获得校验后的意图与租约 → ContextEngine 收到显式破坏性域命令SYS-009 / SYS-020。SPEC-CONTEXT-ENGINErev 1ContextEngine必须是有限、显式的薄门面CE-001一个实例永久绑定恰好一个逻辑 context identityCE-006操作不得接受覆盖该身份的第二选择器CE-007不同身份的实例可共存且无进程级全局状态CE-009。生命周期为construction - usable - closing - closed构造失败不产生可用实例CE-032。所有操作返回类型化、传输中立的域值或 DomainError/DependencyError/EngineLifecycleErrorCE-012引擎不得提示、打印、渲染终端呈现或选择进程退出码CE-013不得认证调用者或实施产品授权策略CE-014。SPEC-POTPIE-RESOURCE-MANAGERrev 2RM-036/RM-037 定义了边界失败四元组——SelectionError、AuthenticationError、AuthorizationError、ResourceLifecycleError 必须保持结构可区分RM-005 要求破坏性操作在签发租约前校验破坏性意图断言租约概念上包含一个解析后的 context identity、一个绑定该身份的 ContextEngine、认证 actor-操作-上下文授权范围、显式依赖所有权与一个幂等释放能力RM-020/RM-021/RM-030。lease 本身不含execute函数、方法转发、任意服务或域结果RM-022/RM-023。SPEC-DAEMONrev 2强制单一受支持的运行时架构与单一入口DAEMON-001运行时作为前台进程由控制器直接创建DAEMON-002就绪必须由实时认证握手建立发现元数据本身不构成就绪DAEMON-010/011生命周期状态机限定为starting → ready/draining/failed、ready → draining/failed、draining → stopped/failed、failed → stoppedDAEMON-032/033重启创建新 boot 与新实例身份DAEMON-034。修订 2 新增的关键约束DAEMON-052 至 056源自 ADR-0012控制器只能对自己直接创建的前台子进程句柄发送 OS 终止信号禁止对从运行时记录附加的进程使用信号回退对附加进程的认证关闭失败时必须返回 ResourceLifecycleError 且不得声称已停止。SPEC-CLIrev 1人机双模式由 CLI-032 强制一次调用恰好选择一种呈现模式机器模式不得提示、完成时向标准输出发出恰好一个完整 JSON 值CLI-015、诊断走 stderr 或抑制CLI-028退出码 0 代表成功CLI-019失败呈现不得通过异常消息字符串匹配分类CLI-026破坏性意图在派发前缺失时返回 PresentationErrorCLI-033。CLI 不得直接构造 ContextEngineCLI-005不得调用 daemon server 符号、HostShell 或 RemoteHostShellCLI-022。精确契约依赖与运行时分层主线索引用两张表刻画契约之间的关系。第一张是精确依赖表SPEC-PROCESS 与 SPEC-GLOSSARY 无依赖SPEC-PRODUCT 依赖词汇表SPEC-SYSTEM 依赖两者能力契约依赖产品与系统Context Engine 依赖词汇表与系统Resource Manager 进一步依赖 Context EngineDaemon 再依赖 Resource ManagerCLI 依赖 Daemon。由此得到运行时分层主线primary runtime layering spineCLI - daemon - Resource Manager - Context Engine索引特别提醒这张简化主线隐藏了共享的词汇表与系统依赖完整依赖必须以表格为准。这条 spine 与 system.md 的 SYS-001 完全一致Potpie 托管域调用路径必须是CLI → typed daemon client → typed daemon operation handler → authorized context lease → 对租约上 context-bound ContextEngine 的显式操作。决策注册表12 份 ADR索引的 Decision Registry 记录了 12 份已接受决策ID决策状态ADR-0001基于 Git 的规范治理acceptedADR-0002单一可导入的 Context Engine 发行版acceptedADR-0003显式组合与不可变上下文作用域acceptedADR-0004Potpie 资源管理所有权acceptedADR-0005类型化 daemon 与 CLI 边界acceptedADR-0006推迟的运行时关注点acceptedADR-0007Context 运行时迁移路径acceptedADR-0008异步 Context Engine 公共契约acceptedADR-0009类型化本地运行时执行契约acceptedADR-0010修正 Resource Manager 认证结果acceptedADR-0011面向能力的 Potpie 布局acceptedADR-0012限制强制 daemon 终止accepted以 ADR-0001 为例它确立了spec/下的 Markdown 是规范文本、契约使用整数修订与稳定行为标识符、user:dsantra是初始修订-1 契约集的验收权威且team:potpie的所有权、agent:codex的编写、代码与测试都不能独立构成验收。ADR-0010 则解释了为什么 Resource Manager 需要把认证失败从 SelectionError/AuthorizationError 中独立出来形成SelectionError / AuthenticationError / AuthorizationError / ResourceLifecycleError四元组对应 RM-036 与 RM-037修订从 1 → 2。未决问题与变更记录索引的 Open Questions 指出4 个问题被有意推迟且没有已接受的活跃行为依赖于它们另有 9 个实现就绪问题已由 ADR-0007 至 ADR-0009 解决。被推迟的问题包括取消/超时/断开/未知结果语义OQ-DAEMON-CANCEL-001、幂等与重试身份OQ-DAEMON-IDEMPOTENCY-001、机器 JSON 信封与退出码映射OQ-CLI-JSON-001、跨表面身份与能力模型OQ-AUTH-MODEL-001详见 questions/open.md。每个被推迟的问题在实现提交依赖其答案前必须单独形成决策。Change Record Registry 记录了 12 份变更记录完整覆盖从修订 0 → 1 的初始化SPEC-CHANGE-0001 至 0008、0010到修订 1 → 2 的修正0009 Resource Manager 认证结果、0011 稳定一致性记录路径、0012 限制 daemon 信号回退ID契约迁移状态SPEC-CHANGE-0001SPEC-PROCESS0 → 1acceptedSPEC-CHANGE-0002SPEC-GLOSSARY0 → 1acceptedSPEC-CHANGE-0003SPEC-PRODUCT0 → 1acceptedSPEC-CHANGE-0004SPEC-SYSTEM0 → 1acceptedSPEC-CHANGE-0005SPEC-CONTEXT-ENGINE0 → 1acceptedSPEC-CHANGE-0006SPEC-POTPIE-RESOURCE-MANAGER0 → 1acceptedSPEC-CHANGE-0007SPEC-DAEMON0 → 1acceptedSPEC-CHANGE-0008SPEC-CLI0 → 1acceptedSPEC-CHANGE-0009SPEC-POTPIE-RESOURCE-MANAGER1 → 2acceptedSPEC-CHANGE-0010SPEC-POTPIE-CAPABILITIES0 → 1acceptedSPEC-CHANGE-0011SPEC-PROCESS1 → 2acceptedSPEC-CHANGE-0012SPEC-DAEMON1 → 2accepted一致性验证声明、证据与新鲜度一致性conformance是这套体系中最容易被误读的部分。索引的 Conformance Summary 说明继任的 Daemon 与 CLI 记录验证了已接受的 Daemon 修订 2 与实现提交1db96d660b87d5cf50398a37318e1dbbf704610e覆盖DAEMON-052至DAEMON-056其余三份模块记录保留此前已通过的标识cross-system 记录仍为 stale因为实现提交尚未推送、不是当前 PR 的 head其既有结果只能描述其钉住的 PR head 与main基线的组合。新鲜度freshness不是存储在索引或契约元数据中的字段而是通过比较钉住的身份pinned identities与选定当前 ref 派生出来的——这是 process.md 中 PROC-011 / PROC-012 与派生新鲜度状态轴的直接体现。当前一致性记录的实际导航入口是 conformance/index.md6 个稳定路径context-engine.md、potpie-resource-manager.md、daemon.md、cli.md、potpie-capabilities.md、cross-system.md各自钉住契约修订与实现 ref更新记录只有在持久验证身份spec_id/revision/ref、implementation_ref、行为、证据或 PR-head/基线对发生变化时才进行纯日常 CI 结果不会发布为新仓库记录。当前快照迁移尚未完成索引的 Current Snapshot 明确把现状描述为初始实现观察观察钉在基线提交a341978880b9d4c1b403831931279ccedf6184ae用于解释迁移需求。五个被索引的模块记录建立了当前模块范围的验证声明Daemon 与 CLI 钉在1db96d...cross-system PR/base 集成验证在实现成为活 PR head 之前保持 stale。也就是说索引文档与当前代码可能互相矛盾这是迁移未完成时的预期状态而不是缺陷。system.md 的Current Implementation Gap Snapshot具体列出了差距清单potpie/daemon/main.py仍是反射式/rpc与/attr端点的活跃启动目标potpie/daemon/client.py仍动态镜像 HostShell 表面potpie/daemon/rpc.py仍在线上放置 Python 模块与类身份potpie_context_engine/host/shell.py仍把域服务与产品生命周期、认证、安装、技能、配置和 pot 管理混在一起Context Engine 仍依赖独立发布的 Context Core 包并暴露扩展类型CLI 的破坏性确认尚未端到端一致强制。修订 1 的历史可寻址点位于提交047cbe067c9c726e7e14f066675453372d8a8406。源码级佐证规范如何映射到实现虽然规范索引本身不写代码但目标边界的部分要素已经在当前源码中可见ContextEngine 门面potpie/context-engine/src/potpie_context_engine/api.py 导出了ContextEngine、ContextIdentity、ContextOperations、EngineConfig、EngineDependencies、EngineResource、ResourceOwnership、create_engine等符号对应 CE-001 要求的有限、显式的公共门面并明确禁止反射式服务查找。架构负向锁tests/characterization/test_context_runtime_architecture.py 定义了FORBIDDEN_IDENTIFIERSDaemonRpcClient、HostShell、RemoteHostShell、build_host_shell等并断言其不再存在于代码中同时检查potpie/context-core与bootstrap/host_wiring.py等路径已被移除——这正是 CE-027、DAEMON-036/037、PCAP-010 等迁移完成态在测试层的固化。能力导向布局根目录potpie/下的 config、pots、skills、setup、auth、runtime 等目录即 PCAP-001 所要求的按显式拥有的能力组织根源码。结语把索引当作迁移的导航仪spec/index.md的价值不在于它包含多少行为节点而在于它把目标架构组织成了可审查、可追溯、可验证的资产契约锁定期望240 个行为节点、ADR 记录理由、变更记录记录迁移、一致性记录记录证据、未决问题记录取舍。对阅读者而言正确姿势是从 阅读顺序 出发先读 规范流程 理解权威模型再逐层深入各模块契约最后通过 一致性索引 核对当前实现与目标的差距。当spec/文本与potpie/代码出现分歧时记住索引的提示——规范是绑定目标代码是实现快照迁移完成前二者可以合理地不一致。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考