merge: 吸收 PikaOA Prometheus 平台扩展

docs/reference/observability.md

@@ -2,6 +2,16 @@
 
 UniDesk 的可观测性优先级高于静默成功。CLI、服务日志、Docker 日志和数据库状态都必须能通过短命令查询。
 
+## 共享 Prometheus 指标面
+
+- `config/platform-infra/observability.yaml` 同时拥有 Collector、Tempo 和 Prometheus 的 image、retention、storage、port、目标 `targetIds`、服务发现与查询预算；TypeScript 只校验和渲染。
+- Prometheus 仅作用于 `metricsBackend.targetIds` 选中的 observability target；其他 target 的 plan 显示 `disabled-for-target`，manifest、status probe/capture 和 `metrics-query` 均不访问 Prometheus。
+- Prometheus 使用 Kubernetes 原生 pod 服务发现。YAML 通过结构化 `labelSelector.key/value` 声明稳定 label，并用 `prometheus.io/scrape=true`、`prometheus.io/path`、`prometheus.io/port` annotation 声明抓取；显式 path 优先，仅在 annotation 缺失时使用 `defaultPath`，不允许业务专属分支。
+- `bun scripts/cli.ts platform-infra observability plan --target <NODE>` 展示 Prometheus enabled/disabled、Service、发现选择器和 manifest 摘要。
+- `bun scripts/cli.ts platform-infra observability status --target <NODE>` 与 `validate` 将 Prometheus readiness 单列为 warning；不得改变业务 readiness 或交付成功结论。
+- `bun scripts/cli.ts platform-infra observability metrics-query --target <NODE> --query <promql>` 只执行 YAML 预算约束的瞬时 PromQL 查询；默认有界，`--full` 展开结构，`--raw` 仅用于解析诊断。
+- Collector + Tempo 继续是 trace authority；Prometheus 只承担 metrics，不成为第二业务状态库或交付门禁。
+
 ## Capability Boundary
 
 版本、commit 和微服务契约漂移只属于可观测性信号。OTel、日志、diagnose 和 status 必须把它们投影为非阻塞 warning，并继续以真实业务结果为权威；不得把漂移告警升级为业务失败、admission blocker、readiness failure 或 CI/CD gate。完整边界见 [DevOps Hygiene](devops-hygiene.md#prohibited-deployment-truth)。