qinglong/docs/adr/ADR-0388-bounded-unified-cluster-product-cli.md

ADR-0388：有界统一 Cluster Operator 产品 CLI

• 状态：Accepted
• 日期：2026-08-12
• 关联 RFC：QL-RFC-0001 D-300
• 前置决策：ADR-0127、ADR-0249、ADR-0259、ADR-0264、ADR-0271、ADR-0356、ADR-0365、ADR-0383

上下文

Local 部署者已有 ql3 <command> 可发现入口，Cluster operator 却仍需记忆二十多个 ql3-*-client|manage|execute binary。直接把所有 Cluster Admin 命令挂到一个 facade 会模糊远程客户端、常驻管理服务、数据库 migration、recovery、executor 与 key-custody 的 authority；新建 CLI package 又会恢复只有少量转发表文件的微包。

Cluster Admin 已是独立、短生命周期、非路由设备的发布镜像和 package。统一 operator UX 应留在该边界内，并且只能聚合调用方已经持有认证材料的远程客户端，不得借命令名称把服务端或数据库写 authority 交给普通工作站。

决策

1. 在既有 @qinglong/cluster-admin 的 product-cli/ 领域目录增加 ql3-cluster-admin binary，不新增 workspace package、第三方依赖、数据库对象、角色、连接、listener、timer、watcher、cache 或 sidecar。
2. facade 只暴露七个固定远程客户端：package、package-kubernetes、worker-credential、approval、run、automation、model-credential。每项映射到同一安装中已经发布的一个 *-client binary。
3. *-manage 服务进程、migration、Plugin recovery、Worker/Package executor、provider test executor、AI migration、Prompt output rotation/retirement/recovery/GC 不进入 catalog；既有 binary 均保留，Kubernetes operation 继续显式指定精确入口。
4. dispatcher 只使用冻结 catalog、当前 process.execPath 和参数数组，固定 shell=false，不查询 PATH。目标必须是当前 package canonical dist/ 内的 non-symlink regular file；package manifest 必须是 canonical non-symlink、64 KiB 内且 name/version 合法。子命令参数作为 opaque argv 原样转发。
5. facade 只转发 SIGINT|SIGTERM|SIGHUP，保持 child exit code 或 128+signal；未知命令与安装损坏只返回不含用户输入、路径或认证材料的低敏 JSON。
6. Cluster Admin image 默认 ENTRYPOINT 改为 facade，使无参数运行提供可发现帮助。所有生产 Job/Deployment 已显式覆盖 command，因此不改变其 authority 或生命周期。CI 在 amd64/arm64 Admin matrix 中以 non-root、read-only root、network none、capabilities none、128 MiB/32 PIDs 运行真实镜像门。
7. Local/Edge Profile、Local image、Cluster Control image 与 Worker image均不安装或加载该 facade。package boundary 仍为 18，Cluster Admin 根仍只有既有 migration binary；两个新增 source 全部位于 product-cli/。

不采用方案

• 把所有 Cluster binary 暴露为子命令：可发现性不能消除服务、执行和密钥 authority 隔离。
• 删除原 binary：会破坏 Kubernetes manifest、自动化脚本和已有运维协议。
• 通过 shell、PATH 或用户路径查找命令：允许环境劫持、通配符和参数重解释。
• 复用 Local ql3 package：会让 Edge/Standalone 安装 Kubernetes/PostgreSQL 管理依赖，并混合两种部署模型。
• 新建 Cluster CLI package：只有同镜像静态路由职责，不形成新的部署、authority 或重依赖边界。

验收门

• catalog、help/version、opaque argv、unknown/path traversal、symlink target/manifest、真实 7-client help delegation、退出码与有界信号转发；
• package manifest 和 Admin Dockerfile 的正反向部署审计，CI/release audit 必须要求 native image live gate；
• Cluster Admin 完整 package、backend、18-package clean build/test、package/dependency/deployment/image release boundary 全绿；
• 真实 arm64 Admin image 在受限 envelope 下通过，并记录 image bytes；PostgreSQL HA 不回归；
• Local 14 Profile artifact 与默认 Local image 不因 Cluster facade 变化。

当前证据

• facade 6/6、Cluster deployment 49/49、CI/release contract 48/48；部署审计复核全部 24 个 Admin image 引用都显式覆盖 command，并以突变测试锁定。真实 arm64 Admin image 为 330,444,072 bytes，10001:10001、只读根、无网络、无 capabilities、0.25 CPU、128 MiB/32 PIDs 下 7/7 客户端 help 委派成功。
• Cluster Admin 完整 package 为 293 tests、291 pass、2 条件 skip、0 fail；18-package clean build/test 退出 0；backend 为 1,186 tests、1,184 pass、2 skip、0 fail。workspace 保持 18 package；Cluster Admin 为 96 source，其中 95 nested、1 个既有 root binary entry，singleSourcePackages=[]、shallowSourcePackages=[]；package/dependency/deployment/image release/Local image audit 零 finding。
• 14 个 Local Profile artifact 全部 compatible，最小 Edge 为 2,467,343 bytes/295 files/53 modules、最终运行 RSS 11,091,968 bytes；最大 Standalone MCP 为 7,168,978 bytes/778 files/213 modules、RSS 38,420,480 bytes，证明 Cluster facade 不进入路由设备与本机 Profile。
• PostgreSQL 18.4 arm64 physical HA 123 项 gate 全绿、timeline 1→2，报告 SHA-256 f5df5998d505b6d5af552e627bd3f83983bc347d08d94da5a2d73fde46eab0a4；离线证据审计零 finding，测试容器、network 与 volume 零残留。