Potpie CLI 契约解析类型化客户端边界、双呈现模式与破坏性意图约束【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本篇基于 Potpie 仓库中的规范变更记录 SPEC-CHANGE-0008 及其落地的模块契约 SPEC-CLI、决策记录与一致性记录展开。Potpie 是面向 AI 原生软件开发生命周期Context Graph for AI Native SDLC的工具其 CLI 是产品呈现与用户意图边界。通过本文你将掌握CLI 与 daemon 控制器、类型化 daemon 客户端之间的职责划分33 条规范行为CLI-001 ~ CLI-033约束下的人机双呈现契约破坏性操作不可信断言→下边界校验的安全模型以及这些契约在potpie/cli与potpie/runtime中的实际落地形态。一、契约的由来一份规范变更记录SPEC-CHANGE-0008 是 Potpie 规范流程中第一份关于 CLI 的变更记录spec_id: SPEC-CLIchange_type: normative由user:dsantra发起、agent:codex撰写于2026-08-20接受将 SPEC-CLI 从 revision 0 提升到 revision 1。它的Intent一句话概括了整个契约的目标定义类型化客户端边界以及分离的人类呈现与机器呈现契约包括端到端的破坏性意图与标准流stdout/stderr纪律。这份变更记录一次性新增了 33 条行为操作CLI-001 ~ CLI-033全部为add类型——因为这是 CLI 契约的初始版本不修改任何既有命令名称也不声称当前实现已符合规范。其 Provenance Sources 明确关联了三份决策记录ADR-0004资源管理所有权归 PotpieCLI 只捕获选择器、不负责最终上下文解析ADR-0005采用单一类型化 daemon 边界呈现由 CLI 独占ADR-0006精确 JSON 字段、数字退出码映射等细节延迟到后续版本。Spec 流程要求每个 CLI 行为都必须携带 authority权威来源与 decision决策来源以便溯源spec/modules/cli.md中每条规范行为的 authority、 decision、交叉引用与~相关源码路径标注即为此机制的实现。二、CLI 拥有什么、不拥有什么2.1 所有权与边界Ownership And Boundariesspec/modules/cli.md 的 Purpose 明确了 CLI 的定位产品呈现与用户意图边界。它使用外部 daemon 控制器创建和观察进程然后调用有限集合的类型化 daemon 客户端操作来完成就绪检测、运行时控制与产品行为。CLI拥有命令与选项解析parse显式选择器selectors与允许的环境提示如--pot、仓库推断凭据获取交互credential acquisition但见 CLI-007人类提示、进度、可读输出与补救指引机器模式的非交互性与结构化输出stdout / stderr 纪律将类型化结果映射为进程退出码破坏性请求的显式人工或自动化确认。CLI不拥有排除项最终上下文解析交给 Resource Manager授权强制执行资源或引擎构造daemon 控制器/运行时内部领域语义domain semantics。2.2 角色与权限表Actor交互人类用户提供命令意图、选择器、凭据与确认自动化调用者提供完整的非交互输入并消费结构化输出CLI解析、呈现、选择控制器或客户端、映射类型化结果Daemon 控制器启动并观察外部前台运行时类型化 daemon 客户端执行经过认证的就绪、运行时与产品操作这套 Actor 划分与 spec/modules/daemon.md 中的 DAEMON 契约严格对齐CLI 在端点存在前用控制器端点存在后使用类型化客户端daemon 运行时则只负责认证、就绪、生命周期与传输不拥有终端呈现。三、33 条规范行为的分类解读CLI-001 ~ CLI-033 是整份契约的骨架。为便于理解可将其分为六个维度每条行为的完整规范文本见 spec/modules/cli.md3.1 类型化客户端边界CLI-001 ~ CLI-006、CLI-022、CLI-023CLI-001托管路径中的 CLI 命令必须调用有限集合的类型化 daemon 客户端操作MUST。CLI-002禁止动态制造远程方法、禁止依赖反射 RPC。CLI-003CLI 只捕获显式上下文选择器与允许的环境提示最终上下文解析交给资源管理边界关联源码potpie/cli/commands/_common.py。CLI-004必须使用外部 daemon 控制器进行进程创建与外部进程观察。CLI-005托管路径中禁止直接构造 Context Engine。CLI-006禁止实现或覆盖 Context Engine 领域语义。CLI-022托管路径中禁止调用 daemon 服务端符号、HostShell 或 RemoteHostShell。CLI-023端点候选存在后必须使用类型化 daemon 客户端完成认证就绪与受支持的运行时操作包括类型化操作契约暴露的优雅停止。3.2 选择器与凭据CLI-003、CLI-007、CLI-025CLI-007CLI 的凭据获取不能替代下边界的认证与授权强制执行。CLI-025CLI 的人类输出、机器输出与诊断都必须排除凭据。在实现层面potpie/cli/commands/_common.py 的_context_selector构建ContextSelector显式--pot优先其次当前仓库身份repo_identity_key最后回退activeresolve_pot_id/resolve_pot_scope实现--pot→ 当前仓库 pot → 激活 pot 的解析顺序这正是 CLI-003 只捕获选择器、不解析的呈现侧体现——真正的一次性解析发生在 Resource Manager 的acquire中。3.3 人类呈现模式CLI-008 ~ CLI-013、CLI-030CLI-008人类模式可以提示、显示进度、输出散文或表格、提供补救指引。CLI-009破坏性人类操作必须在请求派发前获得明确肯定确认或显式非交互确认标志。CLI-010破坏性确认或自动化意图必须转换为不可信的类型化破坏性意图断言且绑定到被请求操作与精确上下文选择输入。CLI-011人类取消必须是类型化的非成功结果且与 SYS-007 的每个错误类别不同。CLI-012当下边界报告未知或仍在运行的结果时不得报告为已取消。CLI-013人类错误呈现必须基于类型化结果与错误类别。CLI-030派发前的人类取消必须在本地终止不发送类型化操作。代码中的对应物是 potpie/cli/commands/_common.py 的CliCancellationcategory: cancellation与confirm_destructive_operation非 TTY 或--json下缺少确认直接fail(codedestructive_confirmation_required, ...)TTY 下用typer.confirm(prompt, defaultFalse)未确认则抛出CliCancellation类型的cancel(...)。contract()边界在捕获到CliCancellation时以取消结果渲染并抛CliCancellationExit绝不把取消冒充为成功或系统错误。3.4 机器呈现模式CLI-014 ~ CLI-018、CLI-028、CLI-032、CLI-033CLI-014机器模式禁止提示。CLI-015完成的机器模式调用必须向 stdout 恰好输出一个完整的机器可读 JSON 值。CLI-016机器模式的进度与诊断不得污染 stdout。CLI-017非交互执行不得阻塞等待人类输入。CLI-018无显式破坏性意图的破坏性机器模式调用必须在派发前失败。CLI-028机器模式诊断必须写入 stderr 或抑制。CLI-032一次调用必须恰好选择一种呈现模式。CLI-033派发前检测到缺失破坏性意图断言必须返回PresentationError。实现上potpie/cli/main.py 根回调提供--json与--verbose/-v两个全局开关bootstrap_output_flags_from_argv在 Typer 完成解析前就扫描--json使解析期错误也能走 JSON 错误契约。_common.py的emit(payload, human...)在--json下输出json.dumps(payload)否则走print_human_block——同一结果两种呈现恰好对应 CLI-032 的恰好一种呈现模式。3.5 退出码与失败映射CLI-019 ~ CLI-021、CLI-024、CLI-026、CLI-031CLI-019退出码 0 必须表示成功。CLI-020失败分类与退出映射必须基于类型化结果或错误码。CLI-021本修订不定义精确的机器 JSON 字段延迟。CLI-024本修订不定义完整的数字非零退出码映射延迟。CLI-026失败呈现禁止通过异常消息字符串匹配来分类。CLI-031每个 CLI 失败结果必须使用非零进程退出码。仓库中 potpie/cli/commands/_common.py 定义了当前实现的退出码常量常量值含义EXIT_OK0成功EXIT_VALIDATION1校验/输入失败EXIT_UNAVAILABLE2功能或服务不可用EXIT_DEGRADED3降级EXIT_AUTH4认证/授权失败contract()错误边界把类型化错误码与类别映射到这些退出码not_implemented→ 2类别属于authentication/authorization→ 4selection/domain→ 1其余 → 2。注意这套数字映射是当前实现的事实_common.py顶部注释明确写了 0 ok / 1 validation / 2 unavailable / 3 degraded / 4 auth而 CLI-021 与 CLI-024 则声明契约本身暂不冻结精确 JSON 字段与完整退出码表——这正是规范与实现之间的边界。3.6 取消、重放与遥测CLI-011、CLI-012、CLI-027、CLI-029CLI-027下边界结果为未知的变更操作禁止自动重放。CLI-029CLI 遥测默认排除凭据与敏感结果负载。在运行时层potpie/runtime/clients.py 的_send_protocol_request依据操作的SafetyClass判断outcome_unknown对EXCLUSIVE_CONTEXT_MUTATION、EXCLUSIVE_RESOURCE_MUTATION、DAEMON_LIFECYCLE_CONTROL类操作传输失败且已派发时返回retry_postureunknown的ProtocolTransportError推荐动作变为先检查操作状态再重试——这正是 CLI-012/CLI-027 关于不得谎称取消、不得盲目重放未知结果变更的底层保障。四、调用模型Invocation Model规范给出了目标命令流本文完整保留parse - collect permitted input - confirm destructive intent when applicable - use controller if process creation or observation is required - use typed client for readiness, runtime control, or product operation - receive one typed outcome - render one presentation mode - exit派发前的人类取消保持在本地派发后的取消使用下边界结果绝不凭空捏造成功取消。spec/modules/cli.md的 Failure Summary 用一张表总结了各类失败的处理条件CLI 行为本地解析或输入失败不派发返回PresentationError缺少非交互破坏性意图不派发按 CLI-033 返回PresentationError派发前人类取消不派发返回类型化取消结果下边界错误保留主类别并安全渲染未知变更结果不声称取消、回滚或安全重放五、机器与人类双呈现模式Human And Machine PresentationCLI-032 强制恰好一种模式。两种模式的差异用一张表即可看清维度人类模式机器模式提示/交互允许typer.confirm等禁止CLI-014输出散文、表格、进度恰好一个完整 JSON 值到 stdoutCLI-015诊断可读文本stderr 或抑制CLI-028确认交互式确认必须显式标志CLI-009/CLI-018失败呈现类型化类别驱动结构化 JSON 错误信封关键设计点呈现不改变底层类型化类别Presentation does not change the underlying typed category。也就是说--json只是把同一类型化结果翻译成 JSON而不会把一个AuthorizationError包装成成功或把取消包装成系统错误。_common.py的fail()在 JSON 模式下输出{code, message, detail, recommended_next_action}信封正是这一点的直接体现。六、破坏性意图的不可信断言模型这是本契约最值得注意的安全设计。规范规定CLI-010、CLI-033、关联 RM-005/RM-033/RM-035CLI 收集到的确认无论来自人工输入还是标志只是一个不可信断言绑定操作与精确选择输入真正校验发生在下边界Resource Manager 在签发租约前将断言与认证 actor、请求操作、解析后的上下文身份逐一核对校验失败返回AuthorizationError且不得签发租约。实现链路在 potpie/runtime/clients.py 中完整可见_build_operation_request在收到DestructiveConfirmation且操作为破坏性时构造DestructiveIntent(confirmed..., operation..., selector..., request_id...)随EngineOperationRequest发送TypedEngineOperationHandler.handle调用resource_manager.acquire(AcquisitionRequest(..., destructivespec.destructive, destructive_intent...))把校验完全交给 Resource Manager 与 daemon 下边界对应 ADR-0005 的 Resource Manager validates that assertion and authorization before a handler invokes the explicit destructive domain command。CLI 侧的入口是confirm_destructive_operationconfirmed_by_flagTrue时直接构造DestructiveConfirmation(confirmedTrue)否则在--json或非 TTY 下以destructive_confirmation_required失败TTY 下交互确认。用户拒绝时走destructive_confirmation_declined取消路径——派发前取消本地终止满足 CLI-030。七、与 daemon 契约的衔接控制器与类型化客户端CLI 不是凭空调用远程方法的胖客户端。契约在 CLI 与 daemon 之间划了一条清晰的线见 spec/modules/daemon.md控制器controller负责进程创建与外部观察不声称就绪、不执行领域操作DAEMON-030/031/051运行时runtime负责认证就绪握手、类型化操作注册表、发现、生命周期DAEMON-011/014/027类型化客户端发现 → 认证 → 握手 → 调用类型化操作。对应代码中potpie/runtime/clients.py 定义了三个客户端LocalEngineClient进程内、DaemonEngineClient走 daemon 协议、DaemonControlClient只负责handshake/status/shutdown生命周期控制。DaemonEngineClient.handshake()携带协议版本范围、期望的 instance id、操作目录指纹做协商校验_validate_handshake_result会逐项检查 instance id 匹配、ready 状态、协议版本兼容、操作目录指纹一致、compatibility ticket 存在、能力集完备——任何一个不满足都会返回类型化ProtocolError而不是裸异常。CLI 侧get_engine_clientpotpie/cli/commands/_common.py读取CONTEXT_ENGINE_HOST_MODE环境变量选择路径in_process走本地引擎否则加载 daemon 发现连接load_daemon_connection构造DaemonEngineClient并先执行握手。discovery 不可用时返回带daemon_discovery_unavailable码的ProtocolTransportError推荐动作run potpie daemon restart。这正好呼应 daemon 契约中发现元数据不等于就绪DAEMON-010/013——握手成功才算 ready。daemon 生命周期命令start/status/logs/restart/stop在 potpie/cli/commands/daemon.py 中全部通过Daemon(in_processFalse)这一分离的控制器对象完成正如一致性记录 spec/conformance/cli.md 所言Daemon lifecycle recovery commands compose a detached lifecycle controller directly, so invalid graph-backend configuration cannot block status, logs, stop, or restart——CLI 不会因为图后端配置损坏而失去恢复能力。八、一致性验证从契约到实现契约接受时明确不声称实现一致性但仓库随后以 spec/conformance/cli.md 记录了完整的验证过程。该记录为 final 状态、result: passed逐条给出 33 条行为的实现声明与验证证据CLI2-E1 ~ CLI2-E5CLI2-E1钉定源码评审根命令、格式化、bootstrap、setup 与类型化客户端路径CLI2-E2完整根测试通道uv run pytest tests -m not premerge_journey -q结果1447 passed, 4 skipped, 1 deselectedCLI2-E3架构与进程门禁通道31 passed包括命令清单不变、安装元数据入口点、遗留边界缺失CLI2-E4隔离入口点冒烟测试potpie解析到potpie.cli.main:main并可导入CLI2-E5聚焦 CLI 边界通道reset/import/repair 确认、后端拥有的快照能力、上下文无关的 describe、类型化 reset、daemon stop、未知结果测试。记录还交叉核对了 SPEC-GLOSSARY、SPEC-SYSTEM、SPEC-DAEMON、SPEC-POTPIE-CAPABILITIES 等关联契约均 passed。已知缺口只有两个被刻意延迟的项精确 JSON 字段集与完整非零退出码映射。仓库中的 tests/characterization/test_cli_package_boundary.py 进一步提供了架构级证据它静态断言potpie_context_engine.adapters.inbound.cli这个遗留命名空间不被任何 CLI 代码导入、引擎侧不得反向导入potpie.cli——把CLI 不得构造引擎、引擎不得依赖 CLI的边界锁死在测试里。更多单元测试如tests/unit/test_runtime_clients.py、tests/unit/test_runtime_protocol_codec.py、tests/unit/test_cli_ergonomics.py也覆盖了握手校验、协议编解码与 CLI 呈现路径。九、验收标准与落地对照规范列出的验收标准逐一对应到实现验收标准实现佐证CLI 在正确生命周期点选择控制器 vs 类型化客户端get_engine_client中 daemon discovery 失败 → 推荐potpie daemon restartDaemonControlClient仅做控制操作托管命令不能调用服务端符号、HostShell 或 Context Enginetest_cli_package_boundary.py静态门禁 CLI-005/022人类提示与机器非交互性无歧义--json全局开关 emit/fail双路径 CLI-014/032破坏性意图在未经验证前保持不可信DestructiveIntent构造于 CLI、校验于 Resource ManagerRM-005/033/035机器 stdout 恰好一个完整 JSON 值emit的json.dumps单次输出 CLI-015/016/028类型化类别而非消息匹配决定失败呈现contract()按code/category映射退出码CapabilityNotImplemented/PotNotFound等均有独立分支 CLI-026十、边界与后续演进这份契约是目标契约不是对当前命令树的冻结。规范明确声明不冻结的项包括完整命令树、精确 JSON 字段CLI-021、数字非零退出码表CLI-024、提示措辞、精确破坏性确认标志。兼容性与迁移路径上现有命令名与呈现可以保持不变内部依赖从 RemoteHostShell 换成显式控制器与类型化客户端操作精确 JSON 与退出码兼容性将由后续接受的契约修订先行定义再落地实现见 ADR-0006 的延迟清单。因此若你正在为 Potpie 贡献 CLI 相关代码、接入自动化脚本或阅读其他模块契约请记住三个判断准则一是以 spec/modules/cli.md 的 CLI-xxx 编号为准而非 README 描述二是实现现状如 0/1/2/3/4 退出码与契约条款如暂不定义完整映射是两回事三是破坏性确认的最终裁决在下边界 Resource ManagerCLI 的任何确认都只是不可信断言。参考路径速查规范变更记录spec/changes/SPEC-CHANGE-0008-initialize-cli-contract.mdCLI 模块契约spec/modules/cli.md一致性记录spec/conformance/cli.md决策记录ADR-0004、ADR-0005、ADR-0006CLI 入口potpie/cli/main.py共享 CLI 管道与错误边界potpie/cli/commands/_common.pydaemon 生命周期命令potpie/cli/commands/daemon.py类型化客户端与操作目录potpie/runtime/clients.py、potpie/runtime/operations.py架构边界测试tests/characterization/test_cli_package_boundary.py【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Potpie CLI 契约解析：类型化客户端边界、双呈现模式与破坏性意图约束
Potpie CLI 契约解析类型化客户端边界、双呈现模式与破坏性意图约束【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本篇基于 Potpie 仓库中的规范变更记录 SPEC-CHANGE-0008 及其落地的模块契约 SPEC-CLI、决策记录与一致性记录展开。Potpie 是面向 AI 原生软件开发生命周期Context Graph for AI Native SDLC的工具其 CLI 是产品呈现与用户意图边界。通过本文你将掌握CLI 与 daemon 控制器、类型化 daemon 客户端之间的职责划分33 条规范行为CLI-001 ~ CLI-033约束下的人机双呈现契约破坏性操作不可信断言→下边界校验的安全模型以及这些契约在potpie/cli与potpie/runtime中的实际落地形态。一、契约的由来一份规范变更记录SPEC-CHANGE-0008 是 Potpie 规范流程中第一份关于 CLI 的变更记录spec_id: SPEC-CLIchange_type: normative由user:dsantra发起、agent:codex撰写于2026-08-20接受将 SPEC-CLI 从 revision 0 提升到 revision 1。它的Intent一句话概括了整个契约的目标定义类型化客户端边界以及分离的人类呈现与机器呈现契约包括端到端的破坏性意图与标准流stdout/stderr纪律。这份变更记录一次性新增了 33 条行为操作CLI-001 ~ CLI-033全部为add类型——因为这是 CLI 契约的初始版本不修改任何既有命令名称也不声称当前实现已符合规范。其 Provenance Sources 明确关联了三份决策记录ADR-0004资源管理所有权归 PotpieCLI 只捕获选择器、不负责最终上下文解析ADR-0005采用单一类型化 daemon 边界呈现由 CLI 独占ADR-0006精确 JSON 字段、数字退出码映射等细节延迟到后续版本。Spec 流程要求每个 CLI 行为都必须携带 authority权威来源与 decision决策来源以便溯源spec/modules/cli.md中每条规范行为的 authority、 decision、交叉引用与~相关源码路径标注即为此机制的实现。二、CLI 拥有什么、不拥有什么2.1 所有权与边界Ownership And Boundariesspec/modules/cli.md 的 Purpose 明确了 CLI 的定位产品呈现与用户意图边界。它使用外部 daemon 控制器创建和观察进程然后调用有限集合的类型化 daemon 客户端操作来完成就绪检测、运行时控制与产品行为。CLI拥有命令与选项解析parse显式选择器selectors与允许的环境提示如--pot、仓库推断凭据获取交互credential acquisition但见 CLI-007人类提示、进度、可读输出与补救指引机器模式的非交互性与结构化输出stdout / stderr 纪律将类型化结果映射为进程退出码破坏性请求的显式人工或自动化确认。CLI不拥有排除项最终上下文解析交给 Resource Manager授权强制执行资源或引擎构造daemon 控制器/运行时内部领域语义domain semantics。2.2 角色与权限表Actor交互人类用户提供命令意图、选择器、凭据与确认自动化调用者提供完整的非交互输入并消费结构化输出CLI解析、呈现、选择控制器或客户端、映射类型化结果Daemon 控制器启动并观察外部前台运行时类型化 daemon 客户端执行经过认证的就绪、运行时与产品操作这套 Actor 划分与 spec/modules/daemon.md 中的 DAEMON 契约严格对齐CLI 在端点存在前用控制器端点存在后使用类型化客户端daemon 运行时则只负责认证、就绪、生命周期与传输不拥有终端呈现。三、33 条规范行为的分类解读CLI-001 ~ CLI-033 是整份契约的骨架。为便于理解可将其分为六个维度每条行为的完整规范文本见 spec/modules/cli.md3.1 类型化客户端边界CLI-001 ~ CLI-006、CLI-022、CLI-023CLI-001托管路径中的 CLI 命令必须调用有限集合的类型化 daemon 客户端操作MUST。CLI-002禁止动态制造远程方法、禁止依赖反射 RPC。CLI-003CLI 只捕获显式上下文选择器与允许的环境提示最终上下文解析交给资源管理边界关联源码potpie/cli/commands/_common.py。CLI-004必须使用外部 daemon 控制器进行进程创建与外部进程观察。CLI-005托管路径中禁止直接构造 Context Engine。CLI-006禁止实现或覆盖 Context Engine 领域语义。CLI-022托管路径中禁止调用 daemon 服务端符号、HostShell 或 RemoteHostShell。CLI-023端点候选存在后必须使用类型化 daemon 客户端完成认证就绪与受支持的运行时操作包括类型化操作契约暴露的优雅停止。3.2 选择器与凭据CLI-003、CLI-007、CLI-025CLI-007CLI 的凭据获取不能替代下边界的认证与授权强制执行。CLI-025CLI 的人类输出、机器输出与诊断都必须排除凭据。在实现层面potpie/cli/commands/_common.py 的_context_selector构建ContextSelector显式--pot优先其次当前仓库身份repo_identity_key最后回退activeresolve_pot_id/resolve_pot_scope实现--pot→ 当前仓库 pot → 激活 pot 的解析顺序这正是 CLI-003 只捕获选择器、不解析的呈现侧体现——真正的一次性解析发生在 Resource Manager 的acquire中。3.3 人类呈现模式CLI-008 ~ CLI-013、CLI-030CLI-008人类模式可以提示、显示进度、输出散文或表格、提供补救指引。CLI-009破坏性人类操作必须在请求派发前获得明确肯定确认或显式非交互确认标志。CLI-010破坏性确认或自动化意图必须转换为不可信的类型化破坏性意图断言且绑定到被请求操作与精确上下文选择输入。CLI-011人类取消必须是类型化的非成功结果且与 SYS-007 的每个错误类别不同。CLI-012当下边界报告未知或仍在运行的结果时不得报告为已取消。CLI-013人类错误呈现必须基于类型化结果与错误类别。CLI-030派发前的人类取消必须在本地终止不发送类型化操作。代码中的对应物是 potpie/cli/commands/_common.py 的CliCancellationcategory: cancellation与confirm_destructive_operation非 TTY 或--json下缺少确认直接fail(codedestructive_confirmation_required, ...)TTY 下用typer.confirm(prompt, defaultFalse)未确认则抛出CliCancellation类型的cancel(...)。contract()边界在捕获到CliCancellation时以取消结果渲染并抛CliCancellationExit绝不把取消冒充为成功或系统错误。3.4 机器呈现模式CLI-014 ~ CLI-018、CLI-028、CLI-032、CLI-033CLI-014机器模式禁止提示。CLI-015完成的机器模式调用必须向 stdout 恰好输出一个完整的机器可读 JSON 值。CLI-016机器模式的进度与诊断不得污染 stdout。CLI-017非交互执行不得阻塞等待人类输入。CLI-018无显式破坏性意图的破坏性机器模式调用必须在派发前失败。CLI-028机器模式诊断必须写入 stderr 或抑制。CLI-032一次调用必须恰好选择一种呈现模式。CLI-033派发前检测到缺失破坏性意图断言必须返回PresentationError。实现上potpie/cli/main.py 根回调提供--json与--verbose/-v两个全局开关bootstrap_output_flags_from_argv在 Typer 完成解析前就扫描--json使解析期错误也能走 JSON 错误契约。_common.py的emit(payload, human...)在--json下输出json.dumps(payload)否则走print_human_block——同一结果两种呈现恰好对应 CLI-032 的恰好一种呈现模式。3.5 退出码与失败映射CLI-019 ~ CLI-021、CLI-024、CLI-026、CLI-031CLI-019退出码 0 必须表示成功。CLI-020失败分类与退出映射必须基于类型化结果或错误码。CLI-021本修订不定义精确的机器 JSON 字段延迟。CLI-024本修订不定义完整的数字非零退出码映射延迟。CLI-026失败呈现禁止通过异常消息字符串匹配来分类。CLI-031每个 CLI 失败结果必须使用非零进程退出码。仓库中 potpie/cli/commands/_common.py 定义了当前实现的退出码常量常量值含义EXIT_OK0成功EXIT_VALIDATION1校验/输入失败EXIT_UNAVAILABLE2功能或服务不可用EXIT_DEGRADED3降级EXIT_AUTH4认证/授权失败contract()错误边界把类型化错误码与类别映射到这些退出码not_implemented→ 2类别属于authentication/authorization→ 4selection/domain→ 1其余 → 2。注意这套数字映射是当前实现的事实_common.py顶部注释明确写了 0 ok / 1 validation / 2 unavailable / 3 degraded / 4 auth而 CLI-021 与 CLI-024 则声明契约本身暂不冻结精确 JSON 字段与完整退出码表——这正是规范与实现之间的边界。3.6 取消、重放与遥测CLI-011、CLI-012、CLI-027、CLI-029CLI-027下边界结果为未知的变更操作禁止自动重放。CLI-029CLI 遥测默认排除凭据与敏感结果负载。在运行时层potpie/runtime/clients.py 的_send_protocol_request依据操作的SafetyClass判断outcome_unknown对EXCLUSIVE_CONTEXT_MUTATION、EXCLUSIVE_RESOURCE_MUTATION、DAEMON_LIFECYCLE_CONTROL类操作传输失败且已派发时返回retry_postureunknown的ProtocolTransportError推荐动作变为先检查操作状态再重试——这正是 CLI-012/CLI-027 关于不得谎称取消、不得盲目重放未知结果变更的底层保障。四、调用模型Invocation Model规范给出了目标命令流本文完整保留parse - collect permitted input - confirm destructive intent when applicable - use controller if process creation or observation is required - use typed client for readiness, runtime control, or product operation - receive one typed outcome - render one presentation mode - exit派发前的人类取消保持在本地派发后的取消使用下边界结果绝不凭空捏造成功取消。spec/modules/cli.md的 Failure Summary 用一张表总结了各类失败的处理条件CLI 行为本地解析或输入失败不派发返回PresentationError缺少非交互破坏性意图不派发按 CLI-033 返回PresentationError派发前人类取消不派发返回类型化取消结果下边界错误保留主类别并安全渲染未知变更结果不声称取消、回滚或安全重放五、机器与人类双呈现模式Human And Machine PresentationCLI-032 强制恰好一种模式。两种模式的差异用一张表即可看清维度人类模式机器模式提示/交互允许typer.confirm等禁止CLI-014输出散文、表格、进度恰好一个完整 JSON 值到 stdoutCLI-015诊断可读文本stderr 或抑制CLI-028确认交互式确认必须显式标志CLI-009/CLI-018失败呈现类型化类别驱动结构化 JSON 错误信封关键设计点呈现不改变底层类型化类别Presentation does not change the underlying typed category。也就是说--json只是把同一类型化结果翻译成 JSON而不会把一个AuthorizationError包装成成功或把取消包装成系统错误。_common.py的fail()在 JSON 模式下输出{code, message, detail, recommended_next_action}信封正是这一点的直接体现。六、破坏性意图的不可信断言模型这是本契约最值得注意的安全设计。规范规定CLI-010、CLI-033、关联 RM-005/RM-033/RM-035CLI 收集到的确认无论来自人工输入还是标志只是一个不可信断言绑定操作与精确选择输入真正校验发生在下边界Resource Manager 在签发租约前将断言与认证 actor、请求操作、解析后的上下文身份逐一核对校验失败返回AuthorizationError且不得签发租约。实现链路在 potpie/runtime/clients.py 中完整可见_build_operation_request在收到DestructiveConfirmation且操作为破坏性时构造DestructiveIntent(confirmed..., operation..., selector..., request_id...)随EngineOperationRequest发送TypedEngineOperationHandler.handle调用resource_manager.acquire(AcquisitionRequest(..., destructivespec.destructive, destructive_intent...))把校验完全交给 Resource Manager 与 daemon 下边界对应 ADR-0005 的 Resource Manager validates that assertion and authorization before a handler invokes the explicit destructive domain command。CLI 侧的入口是confirm_destructive_operationconfirmed_by_flagTrue时直接构造DestructiveConfirmation(confirmedTrue)否则在--json或非 TTY 下以destructive_confirmation_required失败TTY 下交互确认。用户拒绝时走destructive_confirmation_declined取消路径——派发前取消本地终止满足 CLI-030。七、与 daemon 契约的衔接控制器与类型化客户端CLI 不是凭空调用远程方法的胖客户端。契约在 CLI 与 daemon 之间划了一条清晰的线见 spec/modules/daemon.md控制器controller负责进程创建与外部观察不声称就绪、不执行领域操作DAEMON-030/031/051运行时runtime负责认证就绪握手、类型化操作注册表、发现、生命周期DAEMON-011/014/027类型化客户端发现 → 认证 → 握手 → 调用类型化操作。对应代码中potpie/runtime/clients.py 定义了三个客户端LocalEngineClient进程内、DaemonEngineClient走 daemon 协议、DaemonControlClient只负责handshake/status/shutdown生命周期控制。DaemonEngineClient.handshake()携带协议版本范围、期望的 instance id、操作目录指纹做协商校验_validate_handshake_result会逐项检查 instance id 匹配、ready 状态、协议版本兼容、操作目录指纹一致、compatibility ticket 存在、能力集完备——任何一个不满足都会返回类型化ProtocolError而不是裸异常。CLI 侧get_engine_clientpotpie/cli/commands/_common.py读取CONTEXT_ENGINE_HOST_MODE环境变量选择路径in_process走本地引擎否则加载 daemon 发现连接load_daemon_connection构造DaemonEngineClient并先执行握手。discovery 不可用时返回带daemon_discovery_unavailable码的ProtocolTransportError推荐动作run potpie daemon restart。这正好呼应 daemon 契约中发现元数据不等于就绪DAEMON-010/013——握手成功才算 ready。daemon 生命周期命令start/status/logs/restart/stop在 potpie/cli/commands/daemon.py 中全部通过Daemon(in_processFalse)这一分离的控制器对象完成正如一致性记录 spec/conformance/cli.md 所言Daemon lifecycle recovery commands compose a detached lifecycle controller directly, so invalid graph-backend configuration cannot block status, logs, stop, or restart——CLI 不会因为图后端配置损坏而失去恢复能力。八、一致性验证从契约到实现契约接受时明确不声称实现一致性但仓库随后以 spec/conformance/cli.md 记录了完整的验证过程。该记录为 final 状态、result: passed逐条给出 33 条行为的实现声明与验证证据CLI2-E1 ~ CLI2-E5CLI2-E1钉定源码评审根命令、格式化、bootstrap、setup 与类型化客户端路径CLI2-E2完整根测试通道uv run pytest tests -m not premerge_journey -q结果1447 passed, 4 skipped, 1 deselectedCLI2-E3架构与进程门禁通道31 passed包括命令清单不变、安装元数据入口点、遗留边界缺失CLI2-E4隔离入口点冒烟测试potpie解析到potpie.cli.main:main并可导入CLI2-E5聚焦 CLI 边界通道reset/import/repair 确认、后端拥有的快照能力、上下文无关的 describe、类型化 reset、daemon stop、未知结果测试。记录还交叉核对了 SPEC-GLOSSARY、SPEC-SYSTEM、SPEC-DAEMON、SPEC-POTPIE-CAPABILITIES 等关联契约均 passed。已知缺口只有两个被刻意延迟的项精确 JSON 字段集与完整非零退出码映射。仓库中的 tests/characterization/test_cli_package_boundary.py 进一步提供了架构级证据它静态断言potpie_context_engine.adapters.inbound.cli这个遗留命名空间不被任何 CLI 代码导入、引擎侧不得反向导入potpie.cli——把CLI 不得构造引擎、引擎不得依赖 CLI的边界锁死在测试里。更多单元测试如tests/unit/test_runtime_clients.py、tests/unit/test_runtime_protocol_codec.py、tests/unit/test_cli_ergonomics.py也覆盖了握手校验、协议编解码与 CLI 呈现路径。九、验收标准与落地对照规范列出的验收标准逐一对应到实现验收标准实现佐证CLI 在正确生命周期点选择控制器 vs 类型化客户端get_engine_client中 daemon discovery 失败 → 推荐potpie daemon restartDaemonControlClient仅做控制操作托管命令不能调用服务端符号、HostShell 或 Context Enginetest_cli_package_boundary.py静态门禁 CLI-005/022人类提示与机器非交互性无歧义--json全局开关 emit/fail双路径 CLI-014/032破坏性意图在未经验证前保持不可信DestructiveIntent构造于 CLI、校验于 Resource ManagerRM-005/033/035机器 stdout 恰好一个完整 JSON 值emit的json.dumps单次输出 CLI-015/016/028类型化类别而非消息匹配决定失败呈现contract()按code/category映射退出码CapabilityNotImplemented/PotNotFound等均有独立分支 CLI-026十、边界与后续演进这份契约是目标契约不是对当前命令树的冻结。规范明确声明不冻结的项包括完整命令树、精确 JSON 字段CLI-021、数字非零退出码表CLI-024、提示措辞、精确破坏性确认标志。兼容性与迁移路径上现有命令名与呈现可以保持不变内部依赖从 RemoteHostShell 换成显式控制器与类型化客户端操作精确 JSON 与退出码兼容性将由后续接受的契约修订先行定义再落地实现见 ADR-0006 的延迟清单。因此若你正在为 Potpie 贡献 CLI 相关代码、接入自动化脚本或阅读其他模块契约请记住三个判断准则一是以 spec/modules/cli.md 的 CLI-xxx 编号为准而非 README 描述二是实现现状如 0/1/2/3/4 退出码与契约条款如暂不定义完整映射是两回事三是破坏性确认的最终裁决在下边界 Resource ManagerCLI 的任何确认都只是不可信断言。参考路径速查规范变更记录spec/changes/SPEC-CHANGE-0008-initialize-cli-contract.mdCLI 模块契约spec/modules/cli.md一致性记录spec/conformance/cli.md决策记录ADR-0004、ADR-0005、ADR-0006CLI 入口potpie/cli/main.py共享 CLI 管道与错误边界potpie/cli/commands/_common.pydaemon 生命周期命令potpie/cli/commands/daemon.py类型化客户端与操作目录potpie/runtime/clients.py、potpie/runtime/operations.py架构边界测试tests/characterization/test_cli_package_boundary.py【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考