pz-cli 5.0.0__py3-none-any.whl

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/11-/344/273/223/345/272/223/347/234/237/347/233/270/346/272/220/345/234/260/345/233/276.md

@@ -0,0 +1,102 @@
+# 仓库真相源地图
+
+本文只描述 pz v5 的最终仓库与源码真相源，不保留旧三仓结构的运行时兼容。
+
+## 1. 只有两个 Git 仓库
+
+| 逻辑仓名 | 物理远端 | 默认分支 | 职责 |
+| --- | --- | --- | --- |
+| `pz` | `git@github.com:JiXiangTools/pyzza.git` | `develop` | 单一 `pz-cli` distribution 及 wheel 内的 `pz_core`、`pz_foundation`、`pz_settings_center` Python 包 |
+| `pz_apps` | `git@github.com:JiXiangTools/pyzza_platform.git` | `develop` | 除最小基础能力外的全部正式最小子包 |
+
+原站点运行时仓的代码与历史已经并入逻辑仓 `pz_apps`。它不再是独立 checkout、独立依赖根或独立运行时分组。
+
+## 2. `pz` 仓职责
+
+`pz` 仓根固定包含：
+
+- 根 `pyproject.toml` / `uv.lock`：`pz-cli==5.0.0` 的唯一构建、版本与依赖真相源；console script 入口为 `pz_core.pz_launcher:main`
+- `pz_core/`：稳定合同、发现协议、编译、authoring 与统一启动协议
+- `pz_contrib/`：同一个 `pz-cli` wheel 内的官方最小完整基础能力源码容器；容器本身不提供运行时 namespace 或独立 wheel
+- `pz_contrib/pz_foundation/`：通用基础设施最小子包
+- `pz_contrib/pz_settings_center/`：settings 最小子包
+
+`pz run` 是最小完整能力。`pz` 是唯一可独立启动的基础仓，不再创建第二套 core、CLI 或宿主壳。
+
+## 3. `pz_apps` 仓职责
+
+`pz_apps/<app_id>/` 是其他正式最小子包的唯一源码位置。每个叶子项目统一满足：
+
+- 目录名与 import 包名：`pz_<name>`
+- distribution：`pz-<name>`
+- `app_id`：`pz_<name>`
+- 一个叶子目录对应一个可独立声明、安装和绑定的最小子包
+
+单仓不等于统一 release：
+
+- 每个叶子 `pyproject.toml [project].version` 独立决定该 distribution 的发布版本
+- `pz pub <app_id>` 只提交目标叶子路径，并创建 `<distribution-name>@<version>` package tag
+- `pz pub` 优先把精确匹配目标 distribution 的当前 Git 仓库根作为发布源，否则从宿主 `apps/.sources` 枚举 Git source-root 并复用正式 workspace 子包发现程序；只有精确根匹配或唯一叶子命中可以进入发布链
+- 同一个 Git 仓库允许在不同 commit 上形成不同子包 release，也允许同一 commit 被多个精确 package tag 引用
+- 其他子包的未提交修改不得进入目标 release commit；未归属任何叶子的 shared-root 未提交修改必须先人工收敛
+- `pz pub` 不执行 `git push`，远端 commit/tag 同步属于显式 Git 或 CI 工作流
+
+平台能力、站点能力和业务能力不再按旧仓名分组；它们都使用同一最小子包装配模型。
+
+## 4. 宿主项目源码所有权与 checkout
+
+宿主项目只使用以下正式布局：
+
+```text
+<project>/
+├── apps/
+│   ├── <business-owned-app>/   # 业务仓拥有的真实最小子包
+│   ├── .sources/
+│   │   ├── manifest.json
+│   │   ├── pz/                 # pz Git checkout
+│   │   └── pz_apps/            # pz_apps Git checkout
+│   └── <binding> -> .sources/<repo>/<subpath>
+├── .idea/                         # 已存在时由 PyCharm 拥有
+│   └── pz.generated.sources.iml   # PZ 可重建 IDE 影子投影
+├── .vscode/                       # 已存在时由 VS Code/用户拥有
+│   ├── settings.json              # PZ 只拥有其插入的 analysis extraPaths
+│   └── pz.generated.sources.json  # PZ-owned entry 状态账本
+└── pz.jsonc
+```
+
+- `pz dev add <子包>` 把一个正式最小子包导入 `apps/<app_id>`，不保留嵌套 `.git`；导入后的源码由业务仓统一管理
+- Git 输入默认读取 `develop` 分支；`pz dev source cache` 在当前用户隔离的 `<system-temp>/pz/users/<user-key>/git/` 维护可丢弃 checkout，cache root、lock、checkout 与 owner marker 必须验证 owner、权限和非符号链接。cache 命中时先 fetch，未命中时 staged clone，再以 canonical `repo_key`、full commit 与不可变 resolution ref 交给 `dev source import`；import 不得读取可移动 branch 或 `HEAD`
+- 系统临时 Git cache 只用于减少网络与 clone 成本，不是项目源码、版本或运行时真相源；导入完成后 `apps/<app_id>` 才是业务代码的唯一真相源
+- 默认 `pz dev init` 通过系统临时 Git cache 导入官方 `pz_apps` 的全部正式最小叶子，由业务仓管理；只有 `pz dev init --link --clone-sources` 或 `--link --source-dir <path>` 保留原 bootstrap linked scope
+- `pz dev link <目录>` 在 `apps/` 创建目录 binding
+- `pz dev link <子包>` 在 `apps/` 创建该子包 binding
+- linked Git checkout 的项目入口永远位于 `apps/.sources/`；该入口可以是真实目录，也可以是指向项目外共享 Git checkout 的符号链接；`apps/` 只暴露宿主需要扫描的 binding
+- `manifest.json` 是 linked repo checkout 与 binding 的唯一 authoring 真相源；它不登记业务仓拥有的真实本地 app
+- 共享 checkout 的目标由外部所有；PZ 运行、同步和构建可以读取，authoring 命令不得修改其分支、refs 或工作区内容
+- 发布发现可以读取共享 checkout；`pub commit` / `pub tag` 仍受上述只读所有权约束，必须在任何 Git mutation 前失败
+- 同一个 `app_id` 不得同时存在业务仓真实目录与 linked binding；本地源码与已安装 distribution 同名时仍由本地源码优先
+- `apps/.sources/repos/`、额外 wrapper、旧三仓 alias 都不是正式结构
+- `.idea/pz.generated.sources.iml` 只把当前可见最小子包投影成 PyCharm source roots；它不复制源码、不参与运行时发现，也不是 repo、binding 或版本真相源
+- `.vscode/settings.json` 中的 PZ entries 只把项目可见叶子路径加入 `python.analysis.extraPaths`；`pz.generated.sources.json` 只记录 PZ-owned entries，不是源码或装配真相源
+- `pz dev ide sync` 是全部 IDE 投影的唯一原子 owner；它复用同一可见 app 投影并委托 PyCharm/VS Code provider，`dev add/link/unlink/branch/update` 作为编排命令在源码、settings 与环境原子阶段之后调用它
+
+## 5. 分支安全合同
+
+`pz dev link` 在写入 binding 前必须原子地确保受管 checkout 位于当前业务分支：
+
+- 业务分支名默认取宿主项目目录名，也可显式指定
+- 基线分支默认是 `develop`
+- 调用方可显式指定从 `main` 创建业务分支
+- 不允许在 `develop` 或 `main` 上直接承载当前业务修改
+- checkout、切分支、manifest 更新与 `apps/` 快捷方式更新必须作为一个可回滚事务完成
+
+`pz dev add` 的业务接管流程不保留上游 checkout：Git 来源默认从 `develop` 分支解析；`dev source cache` 先更新或创建系统临时 cache 并固定 full commit，`dev source import` 再从该 commit 导出源码。导出的源码先在 `apps/` 同文件系统隐藏目录完成校验，再原子落位到 `apps/<app_id>`。cache 更新失败不得静默使用陈旧 revision，导入失败不得留下半成品目录或项目装配残留。
+
+## 6. 运行时边界
+
+- 运行时只识别最小子包，不识别 Git 仓名或旧 platform/site-runtime namespace
+- `installed_apps` 是装配顺序的唯一真相源
+- 项目源码优先于环境 distribution，同一个 `app_id` 在项目源码范围内只能有一个正式来源
+- 业务仓拥有的真实本地 app 与 linked binding 在运行时平权；差别只在作者面所有权和更新协议
+- `.runtime/`、cache、merged resources、构建目录都是派生产物，不是源码修改入口
+- 新实现只能落在对应最小子包、`pz_core` 稳定合同边界或明确的 `pz_contrib` 基础能力中

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/12-/346/236/204/345/273/272/344/270/216/345/217/221/345/270/203/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,171 @@
+# 构建与发布检查清单
+
+本文档用于固定当前 `pz` 基础包构建、测试与发布前检查流程，避免后续误用环境导致“本地可跑但分发失败”。
+
+适用范围：
+
+- 根包构建与 wheel 分发
+- 最小子包 `<app_id>` 的发布前 smoke 验证原则
+
+补充边界：
+
+- 本文只定义 `pz` 基础包发布门禁与最小子包 smoke 原则
+- 官方最小子包 `<app_id>` 不属于 `pz` 基础包本体
+- 若采用并列源码组织根布局，官方维护最小子包真相源位于 `pz/pz_contrib/<app_id>/`
+- 因此 `pz` 基础包 wheel 的发布门禁，与各最小子包自己的发布门禁必须分开执行，不能误把官方 `pz_*` 子包当成基础包内建内容
+
+## 1. 标准执行顺序
+
+发布前固定按下面顺序执行，不要跳步：
+
+1. 版本与 scope 检查：目标子包 `project.version` 明确，Git index clean，release scope 只包含目标最小子包
+2. 依赖锁检查：`uv lock --check`
+3. 测试回归：运行当前关键 pytest 集合
+4. release commit：`pz pub commit <app_id>`
+5. package tag：`pz pub tag <app_id>`
+6. 从 tag commit 构建、校验 wheel metadata、执行干净 venv 安装/导入 smoke，最后上传：`pz pub upload <app_id>`
+7. 从目标 index 安装已发布版本并完成远端闭环 smoke
+
+日常正式入口仍是 `pz pub <app_id>`，由它按固定顺序编排第 4 至第 6 步。原子命令用于单步验证、失败续跑和自动化测试。
+
+## 2. 标准命令
+
+在仓库根执行：
+
+```bash
+uv lock --check
+```
+
+关键测试集：
+
+```bash
+python -m pytest tests
+```
+
+构建 wheel：
+
+```bash
+uv build
+```
+
+当前正式口径不再依赖外部 `verify_install_chain.sh`；完成 `uv build` 后，继续执行下文的干净 venv 安装与导入 smoke。
+
+### 2.1 `pz` core wheel smoke
+
+`pz` 核心仓只验证 core wheel 自身：
+
+```bash
+repo_root="$(pwd)"
+wheel_path="$(ls dist/pz-*.whl | tail -n 1)"
+rm -rf /tmp/pz-wheel-smoke-verify
+python3 -m venv /tmp/pz-wheel-smoke-verify
+/tmp/pz-wheel-smoke-verify/bin/python -m pip install --upgrade pip
+/tmp/pz-wheel-smoke-verify/bin/pip install "$repo_root/$wheel_path"
+
+cd /tmp
+/tmp/pz-wheel-smoke-verify/bin/python - <<'PY'
+import importlib
+modules = [
+    "pz",
+    "pz.app",
+    "pz.runtime",
+    "pz.runtime.http",
+    "pz.runtime.facades",
+    "pz.runtime.cli.main",
+]
+failed = []
+for m in modules:
+    try:
+        importlib.import_module(m)
+        print("OK", m)
+    except Exception as e:
+        failed.append((m, repr(e)))
+        print("FAIL", m, repr(e))
+print(f"TOTAL_OK={len(modules)-len(failed)} TOTAL_FAIL={len(failed)}")
+if failed:
+    raise SystemExit(1)
+PY
+```
+
+### 2.2 最小子包 smoke
+
+最小子包的导入 smoke 不属于 core wheel 本体，而属于对应子包发布链。若当前工作区采用分仓布局，则应在对应子包 wheel 安装后，按当前发布 manifest / `installed_apps` 枚举验证：
+
+- `<apps_workspace>/apps`
+
+对应 app 构建产物安装后验证：
+
+```bash
+# 该检查在最小子包 wheel 安装后执行，而不是要求 pz core wheel 内建这些模块。
+cd /tmp
+/tmp/pz-wheel-smoke-verify/bin/python - <<'PY'
+import importlib
+modules = [line.strip() for line in open("/tmp/pz-app-imports.txt") if line.strip()]
+failed = []
+for m in modules:
+    try:
+        importlib.import_module(m)
+        print("OK", m)
+    except Exception as e:
+        failed.append((m, repr(e)))
+        print("FAIL", m, repr(e))
+print(f"TOTAL_OK={len(modules)-len(failed)} TOTAL_FAIL={len(failed)}")
+if failed:
+    raise SystemExit(1)
+PY
+```
+
+## 3. 发布前必须检查项
+
+- 当前目录可作为发布源的前提是它本身为 Git root 且根 distribution 精确匹配目标；否则 `apps/.sources` 必须存在可用 Git source-root 并唯一找到目标子包；业务复制目录不能替代发布源
+- Git HEAD 必须附着在分支上，Git author identity 必须已配置
+- Git index 必须 clean；目标子包之外的 staged 内容直接阻止发布
+- 根 distribution 的 release commit 使用显式 `.` 整仓 scope；嵌套子包只能包含目标路径，其他最小子包 unstaged 修改必须保持不变
+- 未归属任何正式最小子包的 shared-root 未提交文件属于歧义 scope，必须先人工收敛
+- tag、tagged tree 的 `project.version`、wheel distribution/version metadata 必须完全一致
+- build/upload 必须要求当前 checkout clean 且 HEAD 精确等于 package tag commit，并从当前 package root 直接执行；不得创建临时 worktree
+- package wheel 的干净 venv 安装/import smoke 必须在远端 upload 前通过
+- `uv lock --check` 必须通过
+- 关键测试集必须全绿（允许已知非阻塞 warning）
+- `uv build` 必须成功
+- `pz` core wheel 的干净 venv smoke 必须 `TOTAL_FAIL=0`
+- 最小子包若声明额外稳定 import surface，必须在该子包自己的发布文档与测试中验证；core 发布门禁不得硬编码具体子包模块清单
+- `pz pub` 不执行 `git push`；release commit 与 tag 的远端推送属于显式 Git/CI 步骤
+- upload 失败后保留 release commit 与 tag；重跑通过精确匹配续跑，不 reset、amend 或删除 tag
+
+## 4. 常见误区与规避
+
+### 4.1 repo root `cwd/PYTHONPATH` 遮蔽
+
+问题现象：
+
+- 在 `cwd=<repo_root>` 或 `PYTHONPATH=<repo_root>` 下，可能命中源码树中的旧目录，导致导入行为与 wheel 安装后不一致。
+
+规避方式：
+
+- wheel smoke 一律在干净 venv + `/tmp` 下执行
+- 导入 smoke 时不要把 repo root 放进 `PYTHONPATH`
+
+### 4.2 误把非正式目录当真相源
+
+问题现象：
+
+- 直接在基础包内部薄绑定层或其它非正式目录增加业务逻辑，会重新引入双真相源。
+
+规避方式：
+
+- 真相源优先写到对应 `<app_id>/` 最小子包或 `pz/` 基础包主链必要边界
+- `pz/infra/*` 与其它非正式目录不作为业务实现真相源
+
+### 4.3 修改 `pyproject.toml` 后漏更新锁文件
+
+规避方式：
+
+- 任何依赖变更后都执行并提交 `uv lock` 结果
+- 发布前必须再次运行 `uv lock --check`
+
+## 5. 失败定位建议
+
+- `wheel 构建失败`：先看 `pyproject.toml` 打包规则与 `force-include` 映射
+- `venv 导入失败但本地源码可导入`：优先怀疑 `cwd/PYTHONPATH` 遮蔽，不要先改业务代码
+- `最小子包稳定 import surface 导入失败`：先检查 wheel zip 中对应路径是否存在，再检查安装后 `site-packages` 布局

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/13-/346/255/243/345/274/217Facade/346/200/273/350/241/250.md

@@ -0,0 +1,402 @@
+# 正式 Facade 总表
+
+## 1. 目的
+
+本文件用于把新架构中的正式 `Facade` 名称、职责和边界统一收口。
+
+原则：
+
+- 同一类公共运行能力，只允许一个正式 `Facade`
+- `Facade` 是外部调用面，不是内部实现目录名
+- app 的正式运行时依赖面是 facade 或其它 app 的 `public.py`，不是 runtime registry 本身
+
+## 2. 正式 Facade 命名规则
+
+统一规则：
+
+- 对外公共能力统一命名为 `XxxFacade`
+
+禁止作为正式公共边界的名称：
+
+- `manager`
+- `service`
+- `helper`
+- `sdk`
+
+## 3. 正式 Facade 总表
+
+### 3.1 `ObservabilityFacade`
+
+职责：
+
+- 暴露 logger / metrics / tracing 的统一访问面
+
+最小稳定方法面：
+
+- `status()`
+- `logger(name: str)`
+- `counter(name: str, *, unit: str | None = None, description: str | None = None)`
+- `histogram(name: str, *, unit: str | None = None, description: str | None = None)`
+- `span(name: str, *, attributes: dict[str, object] | None = None)`
+
+不负责：
+
+- Prometheus server 部署
+- Bot handler 部署
+- 监控平台拓扑
+
+返回语义约束：
+
+- `logger(name)` 只返回当前 runtime 作用域内的 logger 句柄，不得隐式重配 root logger、monkey patch `logging.Logger` 或创建文件输出目录
+- `counter()` / `histogram()` 在 metrics disabled 场景下返回可审计的 noop handle，而不是偷偷绑定默认全局 registry
+- observability facade 若暴露 bot/告警能力，其发送失败、丢弃与降级语义必须可区分
+
+### 3.2 `DatabaseFacade`
+
+职责：
+
+- 暴露 DB capability 的统一访问面
+
+最小稳定方法面：
+
+- `status()`
+- `connection()`
+- `session()`
+- `transaction()`
+
+不负责：
+
+- 迁移归属裁决
+- Web startup 隐式建表
+
+### 3.3 `CacheFacade`
+
+职责：
+
+- 暴露 Redis/cache/L2 相关 capability 的统一访问面
+
+最小稳定方法面：
+
+- `status()`
+- `get(key: str)`
+- `set(key: str, value: object, *, ttl: int | None = None)`
+- `delete(key: str)`
+- `lock(key: str, *, ttl: int | None = None)`
+
+不负责：
+
+- 默认回落本机 Redis
+- 把测试替身混入正式运行模型
+
+### 3.4 `StorageFacade`
+
+职责：
+
+- 暴露对象存储/本地存储的统一访问面
+
+最小稳定方法面：
+
+- `status()`
+- `open(key: str, *, mode: str = "rb")`
+- `save(key: str, payload: object, *, content_type: str | None = None, metadata: dict[str, str] | None = None)`
+- `delete(key: str)`
+- `url(key: str, *, expires_in: int | None = None, download_name: str | None = None)`
+- `presign(key: str, *, method: str = "GET", expires_in: int | None = None)`
+
+不负责：
+
+- 具体云厂商实现内建
+- 业务 object key 命名规则
+
+返回语义约束：
+
+- `url()` 只有在当前 backend 具备正式公共访问语义时才返回可公开消费的 URL
+- 无公共访问入口时，`url()` 必须返回 `None` 或显式能力错误
+- 不得把宿主机绝对路径、相对路径或 `file://` 暴露成正式公共 URL 契约
+- `presign()` 只表达上传/下载授权，不隐含“对象可被公开访问”的语义
+
+### 3.5 `MailFacade`
+
+职责：
+
+- 暴露 mail/notification 的统一访问面
+
+最小稳定方法面：
+
+- `status()`
+- `render(template: str, context: dict[str, object], *, locale: str | None = None)`
+- `send(message: object)`
+- `enqueue(message: object)`
+
+不负责：
+
+- 具体 SMTP/custom provider 的内建实现
+- 把邮件能力伪装成 core 必选项
+
+返回语义约束：
+
+- `send()` / `enqueue()` 的结果必须能区分：
+  - 已提交给正式 provider
+  - provider 不可用
+  - 仅做本地日志降级
+- 若允许备用 provider，备用链必须是显式配置，而不是隐式多级尝试
+- 不得把“仅记录日志”伪装成正式投递成功
+
+### 3.6 `I18nFacade`
+
+职责：
+
+- 暴露展示层翻译、语言元数据、语言解析能力
+
+不负责：
+
+- 作为基础设施 capability 常驻在 `infra`
+
+### 3.7 `ResourceFacade`
+
+职责：
+
+- 暴露资源读取的统一访问面
+
+不负责：
+
+- 运行期再次 merge 资源
+- repo-root/path 猜测
+
+### 3.8 `HealthFacade`
+
+职责：
+
+- 暴露 liveness / readiness 的统一聚合面
+
+最小稳定方法面：
+
+- `liveness()`
+- `readiness()`
+- `capabilities()`
+
+不负责：
+
+- 隐式初始化 DB/Redis
+- 混入 debug/dev surface
+
+### 3.9 平台 app Facade
+
+以下能力不属于 core/infra 默认 facade，但必须由对应平台 app 提供正式 facade：
+
+- `SiteUiFacade`
+- `ConfigFacade`
+- `TaskFacade`
+- `AuthFacade`
+- `RedirectsFacade`
+
+原则：
+
+- 这些 facade 统一放在对应 app 的 `public.py`
+- 外部 app 只能通过 `public.py` 依赖
+
+### 3.10 Official infra owner public surface
+
+official infra owner 的 `public.py` 只允许导出以下 facade：
+
+- `DatabaseFacade`
+- `CacheFacade`
+- `StorageFacade`
+- `MailFacade`
+- `ObservabilityFacade`
+- `HealthFacade`
+
+补充约束：
+
+- `I18nFacade` 不放在 infra owner `public.py`，仍归 shared site UI owner 或展示层平台 app
+- infra owner `public.py` 只暴露稳定 facade，不暴露内部 `db/kv/storage/...` 目录
+- 若未来某项基础能力从 infra owner 拆出独立子包，应先保持 facade 名称不变，再调整实现归属
+
+## 4. Facade 与其它构件的关系
+
+- `Compiler` 负责裁决与产出计划；`Facade` 不负责裁决
+- `Registry` 负责索引与查找；`Facade` 负责对外暴露稳定调用面
+- `Provider` 负责具体绑定实现；`Facade` 屏蔽 provider 差异
+- `Adapter` 负责翻译第三方库细节；`Facade` 不直接暴露底层第三方库对象
+
+## 5. 正式 Capability 总表
+
+### 5.1 capability 的正式定义
+
+capability 表示：
+
+- 当前运行图中某类能力是否存在
+- 是否启用
+- 是否已经 ready
+- 若不可用，为什么不可用
+
+capability 不是：
+
+- 某个具体模块路径
+- 某个默认单例对象
+- 某个具体官方 app / 独立子包名称
+
+补充裁决：
+
+- `CapabilityRegistry` 是 capability 的内部承载容器，不是 app 稳定公共 API
+- app 消费 capability 时，应通过 facade 暴露的状态语义或稳定 capability contract，而不是直接依赖 registry 内部结构
+
+### 5.2 capability 的统一状态语义
+
+所有正式 capability 统一使用以下状态：
+
+- `disabled`
+- `enabled`
+- `ready`
+- `unavailable`
+
+语义固定为：
+
+- `disabled`
+  - 配置明确关闭，或当前运行图未声明该能力
+- `enabled`
+  - 能力已被声明启用，但底层 provider/client 尚未进入 ready
+- `ready`
+  - 能力可被正式消费
+- `unavailable`
+  - 能力按配置需要存在，但由于缺驱动、缺 provider、连接失败、初始化失败而当前不可用
+
+禁止：
+
+- 用空对象、默认 localhost、静默 no-op 伪装成 `ready`
+- 把不同失败原因都吞成同一个“best effort 成功”
+
+补充约束：
+
+- 除 `HealthFacade` 外，基础能力 facade 的最小稳定方法面都必须包含 `status()`
+- `status()` 只能返回上述正式状态语义，不能返回 provider 私有枚举或底层 client 对象
+
+### 5.3 capability 生命周期
+
+统一固定为：
+
+1. `SettingsSnapshot` 编译 capability 配置
+2. `InfraSettings` / app 声明编译 capability 状态
+3. `CapabilityRegistry` 挂入运行图
+4. 执行阶段创建 provider/client
+5. 状态推进到 `ready` 或 `unavailable`
+6. shutdown 阶段对称清理
+
+### 5.4 capability 总表
+
+边界：
+
+- `observability` 是 facade 组，不是单独 capability 名称；底层正式 capability 仍是 `metrics` / `tracing` 及对应 logging provider 绑定
+- `i18n` 不单列为 core/infra capability；展示层语言与翻译能力归属 shared site UI owner 或正式 site/runtime bundle
+
+`database`
+
+- 来源：`InfraContext`
+- 编译输入：owner app 的 `infra.provider` 输出；例如 `settings_center.settings.<infra_owner>.database`
+- 消费方：`DatabaseFacade`、readiness、DB CLI、ORM adapter
+- 正式要求：支持 SQLite / MySQL / PostgreSQL；未启用时状态必须是 `disabled`；缺驱动或连通失败时是 `unavailable`
+
+`cache`
+
+- 来源：`InfraContext`
+- 编译输入：owner app 的 `infra.provider` 输出；例如 `settings_center.settings.<infra_owner>.cache`
+- 消费方：`CacheFacade`、锁/版本/L2 逻辑、readiness
+- 正式要求：不再默认回落本机 Redis；local-only 与 unavailable 语义必须可区分
+
+`mail`
+
+- 来源：`InfraContext`
+- 编译输入：owner app 的 `infra.provider` 输出；例如 `settings_center.settings.<infra_owner>.mail`
+- 消费方：`MailFacade`、auth/task 等需要邮件能力的 app
+- 正式要求：mail 是可选 capability；SMTP/custom mail provider 只是 provider 实现，不是 capability 本身
+
+`metrics`
+
+- 来源：`InfraContext`
+- 编译输入：owner app 的 `infra.provider` 输出；例如 `settings_center.settings.<infra_owner>.observability.metrics`
+- 消费方：`ObservabilityFacade`、exporter route、readiness 诊断
+- 正式要求：当前唯一正式 exporter 是 Prometheus；exporter 关闭时 capability 可 `disabled`；exporter 不可用时不应拖垮主请求路径
+
+`tracing`
+
+- 来源：`InfraContext`
+- 编译输入：owner app 的 `infra.provider` 输出；例如 `settings_center.settings.<infra_owner>.observability.tracing`
+- 消费方：`ObservabilityFacade`
+- 正式要求：tracing 必须低侵入；exporter 不可用时应落到 `unavailable` 或 graceful no-op
+
+`storage`
+
+- 来源：provider binding + app/project 声明
+- 编译输入：owner app 的 `infra.provider` 输出；例如 `settings_center.settings.<infra_owner>.storage`
+- 消费方：`StorageFacade`、file/asset/media 相关 app
+- 正式要求：`StoragePort` 是稳定抽象；local/s3/gcs 只是 provider 差异
+
+`resources`
+
+- 来源：`ResourceManifest`
+- 编译输入：installed apps、`resources.items`、`ProjectContext`
+- 消费方：`ResourceFacade`、template/static/locales/migrations 读取方
+- 正式要求：编译结果唯一真相源是 manifest；运行期不再二次 merge
+- 正式结果：`ResourceManifest.items` 统一承载每个资源项的 `name / source_dirs / output_dir`
+
+`health`
+
+- 来源：`RuntimePlan`、`CapabilityRegistry`
+- 消费方：`HealthFacade`、liveness/readiness route
+- 正式要求：health 是 capability 聚合视图；不再自己维护第二套 infra 判定逻辑
+
+`shared_site_ui`
+
+- 来源：shared site UI owner 声明
+- 消费方：模板渲染、i18n 展示能力、站点上下文能力
+- 正式要求：这是平台 capability，不是 core 内建事实；若缺失，应明确报 capability 缺失；i18n 展示能力、语言元数据、模板语言解析都归属该平台 capability 或对应 site/runtime bundle
+
+`config`
+
+- 来源：settings runtime owner 或替代平台 app
+- 消费方：模块配置读取、settings overrides/L2
+- 正式要求：provider/loader 必须有 owner/scope/reset；不能继续通过全局 setter 写进 `infra.ports`
+
+`task`
+
+- 来源：task dispatch / worker owner 或替代平台 app
+- 消费方：worker SDK、scheduler/reclaimer、task dispatch
+- 正式要求：任务能力不是 core 必选项；若依赖 Redis，应显式体现在 capability 状态里
+
+`auth`
+
+- 来源：auth owner 或替代平台 app
+- 消费方：当前用户解析、admin checker、auth middleware/pages
+- 正式要求：user resolver / admin checker 通过正式 facade 暴露；不能继续通过 `infra.ports` 全局 setter 暴露
+
+### 5.5 capability 的唯一编译与消费路径
+
+正式路径固定为：
+
+1. 配置编译出 typed snapshot
+2. 运行图编译出 capability 状态
+3. `CapabilityRegistry` 统一暴露 capability
+4. facade 统一消费 capability
+5. Web / CLI / worker / checks 复用同一份 capability 状态
+
+不允许：
+
+- readiness 再自己判断一次
+
+## 6. 正式要求
+
+- app 不得直接 import `pz.infra.*` 私有实现获取能力
+- app 统一通过 facade、request/runtime helper、或其它 app 的 `public.py` 获取能力
+- 同一类能力不能同时出现 `manager`、`service`、`facade` 三套公共入口
+
+补充约束：
+
+- `CapabilityRegistry` 是 `RuntimePlan` 的内部运行图对象，不是 app 稳定公共依赖面
+- app 判断某能力是否存在时，应通过 facade 暴露的状态语义或稳定 capability contract，而不是直接抓取 registry 内部结构
+- 只有 runtime / entrypoint / facade 组装层可以直接持有并遍历 `CapabilityRegistry`
+
+## 7. 公开入口原则
+
+`Facade` 是新架构的唯一公共运行能力入口。
+
+如果某个能力还需要调用方直接 import 内部 `manager`、默认单例、或直接依赖 `CapabilityRegistry` 的内部结构，说明该能力的 facade 还没有真正建立完成。