pz-cli 5.0.0__py3-none-any.whl

pz_foundation/db/tortoise_psycopg.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from typing import Any
+
+_CLIENT_CLASS: type | None = None
+
+
+def get_client_class(db_info: dict[str, Any] | None = None) -> type:
+    del db_info
+    global _CLIENT_CLASS
+    if _CLIENT_CLASS is None:
+        _CLIENT_CLASS = _build_client_class()
+    return _CLIENT_CLASS
+
+
+def _build_client_class() -> type:
+    from ssl import SSLContext
+
+    from tortoise.backends.base_postgres import client as postgres_client
+    from tortoise.backends.psycopg.client import (
+        AsyncConnectionPool as TortoiseAsyncConnectionPool,
+        PsycopgClient,
+        exceptions,
+        psycopg,
+        psycopg_pool,
+    )
+
+    class FoundationPsycopgClient(PsycopgClient):
+        foundation_pool_class = TortoiseAsyncConnectionPool
+
+        def __init__(
+            self,
+            *args: Any,
+            conninfo: str = "",
+            connect_timeout: float | int | None = None,
+            server_options: str = "",
+            sslmode: str = "",
+            sslrootcert: str = "",
+            sslcert: str = "",
+            sslkey: str = "",
+            sslpassword: str = "",
+            target_session_attrs: str = "",
+            **kwargs: Any,
+        ) -> None:
+            self._foundation_conninfo = str(conninfo or "").strip()
+            self._foundation_connect_timeout = float(connect_timeout or 0)
+            self._foundation_server_options = str(server_options or "").strip()
+            self._foundation_conninfo_settings = {
+                key: value
+                for key, value in {
+                    "sslmode": sslmode,
+                    "sslrootcert": sslrootcert,
+                    "sslcert": sslcert,
+                    "sslkey": sslkey,
+                    "sslpassword": sslpassword,
+                    "target_session_attrs": target_session_attrs,
+                }.items()
+                if str(value or "").strip()
+            }
+            super().__init__(*args, **kwargs)
+
+        async def create_pool(self, **kwargs: Any) -> TortoiseAsyncConnectionPool:
+            pool = self.foundation_pool_class(open=False, **kwargs)
+            await pool.open()
+            return pool
+
+        @postgres_client.translate_exceptions
+        async def create_connection(self, with_db: bool) -> None:
+            if self._pool is not None:
+                raise RuntimeError("Connection pool already created")
+
+            server_settings = {
+                key: value
+                for key, value in dict(self.server_settings or {}).items()
+                if value not in (None, "")
+            }
+            server_options = _join_server_options(
+                str(server_settings.pop("options", "") or ""),
+                self._foundation_server_options,
+                f"-c search_path={self.schema}" if self.schema else "",
+            )
+            if server_options:
+                server_settings["options"] = server_options
+            if self.application_name:
+                server_settings["application_name"] = self.application_name
+
+            extra = self.extra.copy()
+            extra.setdefault("timeout", self.default_timeout)
+            ssl: SSLContext | None = extra.pop("ssl", None)
+            if ssl:
+                if isinstance(ssl, SSLContext) and ssl.check_hostname:
+                    server_settings["sslmode"] = "verify-full"
+                else:
+                    server_settings["sslmode"] = "require"
+            for key, value in self._foundation_conninfo_settings.items():
+                server_settings.setdefault(key, value)
+
+            if self._foundation_conninfo:
+                conninfo = psycopg.conninfo.make_conninfo(self._foundation_conninfo, **server_settings)
+            else:
+                conninfo = psycopg.conninfo.make_conninfo(
+                    host=self.host,
+                    port=self.port,
+                    user=self.user,
+                    password=self.password,
+                    dbname=self.database if with_db else None,
+                    **server_settings,
+                )
+
+            connection_kwargs: dict[str, Any] = {
+                "autocommit": True,
+                "row_factory": psycopg.rows.dict_row,
+            }
+            if self._foundation_connect_timeout > 0:
+                connection_kwargs["connect_timeout"] = int(max(1, self._foundation_connect_timeout))
+
+            self._template = {
+                "conninfo": conninfo,
+                "min_size": self.pool_minsize,
+                "max_size": self.pool_maxsize,
+                "kwargs": connection_kwargs,
+                "connection_class": psycopg.AsyncConnection,
+                **extra,
+            }
+
+            try:
+                self._pool = await self.create_pool(**self._template)
+                await self._pool.open(wait=True, timeout=extra["timeout"])
+                self.log.debug("Created connection pool %s with params: %s", self._pool, self._template)
+            except (psycopg.errors.InvalidCatalogName, psycopg_pool.PoolTimeout):
+                raise exceptions.DBConnectionError(
+                    f"Can't establish connection to database {self.database}"
+                )
+
+    return FoundationPsycopgClient
+
+
+def _join_server_options(*values: str) -> str:
+    return " ".join(part.strip() for part in values if str(part or "").strip())
+
+
+def __getattr__(name: str) -> Any:
+    if name == "FoundationPsycopgClient":
+        return get_client_class()
+    raise AttributeError(name)
+
+
+__all__ = ["FoundationPsycopgClient", "get_client_class"]

pz_foundation/docs/README.md

@@ -0,0 +1,18 @@
+# Docs Index
+
+这是 `pz_foundation` 的正式文档入口。
+
+阅读顺序：
+- `设计文档.md`
+- `路由与URL处理规范.md`
+- `公开免费接口防滥用与人机校验.md`
+- `../README.md`
+- `pz_foundation/public.py`
+- `pz_foundation/urls.py`（如果存在）
+- `pz_foundation/settings.py`
+- `configs/default.jsonc`
+- `tests/`
+
+说明：
+- `docs/设计文档.md` 是当前包的冻结设计入口。
+- `README.md`、正式公开面与契约测试用于补充设计文档未展开的实现细节。

pz_foundation/docs/distribution-README.md

@@ -0,0 +1,319 @@
+# pz_foundation
+
+`pz_foundation` 是 `pz_contrib` 下的官方基础设施最小子包。
+
+按 `pz` 设计文档口径，它是 `pz-cli==5.0.0` wheel 内的正式叶子 app：
+
+- distribution: `pz-cli`（`pz-foundation` 独立 distribution 已退出发布图）
+- 目录名: `pz_foundation`
+- import 包名: `pz_foundation`
+- `app_id`: `pz_foundation`
+
+## 设计依据
+
+本 README 按 `pz` 正式设计文档口径编写，回链如下：
+
+如果本 README 与 `pz` 设计文档、正式 contract 或正式装配约定冲突，以 `pz` 设计文档为准。
+
+- [`03-App最小子包规范`](../../../../pz_core/pz_core/docs/pz规范与使用/03-App最小子包规范.md)
+- [`10-测试与契约规范`](../../../../pz_core/pz_core/docs/pz规范与使用/10-测试与契约规范.md)
+- [`14-分层与扩展规范`](../../../../pz_core/pz_core/docs/pz规范与使用/14-分层与扩展规范.md)
+- [`15-子包开发使用手册`](../../../../pz_core/pz_core/docs/pz规范与使用/15-子包开发使用手册.md)
+
+## 负责什么
+
+- database、cache、storage、mail、health、observability 等基础设施 runtime。
+- 事务、连接生命周期、idempotency 与基础资源装配。
+- 通用资源 merge/build、图片响应式派生与资源构建缓存。
+- 通用中间件、provider 与 infra facade。
+- 官方基础设施启动与关闭协议。
+- 项目级 detached managed worker supervisor，以及 `worker.role` 的统一拉起 / 停止 / 状态编排。
+
+## 不负责什么
+
+- 业务数据模型与业务状态机真相。
+- 页面、SEO、账户、认证与后台控制面真相。
+- 宿主项目专用 bootstrap hack。
+
+## 正式入口与真相源
+
+- `pz_foundation/apps.py`
+  - 唯一正式 app 入口；声明 lifecycle、provider 与 middleware 装配。
+- `pz_foundation/urls.py`
+  - 唯一正式 URL 真相源。
+- `pz_foundation/public.py`
+  - 唯一稳定公开面；对外暴露 `FoundationFacade`、DB facade、idempotency helper 与 infra startup/shutdown contract。
+- `pz_foundation/settings.py`
+  - 正式 settings schema 声明入口。
+- `pz_foundation/configs/default.jsonc`
+  - 静态默认值真相源。
+
+## 功能拆分
+
+- `db/`
+  - 连接管理、session、事务与 ORM 绑定。
+- `host/`
+  - host 级 cache / db / lifespan runtime。
+- `storage/`
+  - storage facade 与存储访问公开面。
+- `observability/`
+  - logger、business event、bot message 等观测能力。
+- `notifications/`
+  - mail 与通知相关能力。
+- `managed_workers.py`
+  - `worker.role` 的发现、目标副本数展开、状态聚合、supervisor 生命周期与强制停止协议。
+- `cli/workers.py`
+  - 项目级 worker 管理 CLI；提供 `list/status/stop/restart/run`，并负责 detached supervisor 的签名比对与重启策略。
+- `resources/`
+  - 通用资源构建 provider、`resources.post_build` 扩展执行、图片响应式派生策略与资源构建缓存。
+
+## 扩展点与公开面
+
+本包的 app 入口会统一挂载 foundation middlewares 与 providers；其它 app 不应再重复建立第二套 infra runtime。
+
+### Routing 与 Lazy Helper
+
+`pz_foundation` 承担官方通用 routing helper 的落地职责；这类 helper 不属于 `pz` core。
+
+正式约定：
+
+- 每个 app 的正式 URL 入口固定为 `<pkg>.urls`
+- 简单 app 使用 `urls.py`
+- 复杂 app 使用 `urls/`，但正式入口仍然是 `urls/__init__.py`
+- 子包只声明自己的 URL 模块与 include 关系
+- prefix 由上层统一挂载
+- 业务包不负责最终装配、排序与清理
+
+foundation 当前提供两层 API：
+
+- `urls/include` 声明式 API
+  - `DeclaredUrlSpec(...)`
+  - `path(...)`
+  - `include(...)`
+  - `mount(...)`
+  - `compile_urlpatterns(...)`
+
+正式合同：
+
+- `<pkg>.urls` 只允许导出 `urlpatterns`
+- `urlpatterns` 必须是 `path(...)`、`include(...)`、`mount(...)` 或 `DeclaredUrlSpec(...)` 的声明序列
+- `<pkg>.urls` 使用 `path(...)` 时必须声明 `app_name`
+- `path(...)` 必须直接传入函数对象；不再支持字符串 handler 名
+- `path(...)` 的路径字符串使用 FastAPI / Starlette 原生 path 参数语法；既支持 `/{lang}/{module}/{slug}`，也支持 `/{lang:locale}/{slug}` 这类 convertor 形式
+- `path(...)` 声明的路径字符串会原样进入 FastAPI 路由表；foundation 不会在运行时再次重写业务声明层的 path 参数语法
+- `path(..., enabled_when="runtime_flag")` 表示这条路径只会在 `runtime.runtime_flag` 为真时注册
+- 目录型页面 canonical URL 统一以 `/` 结尾；文件型 URL 不以 `/` 结尾
+- `urlpatterns` 只声明 canonical 版本；不要在业务包里同时手工注册两套尾斜杠路径
+- 全站 trailing-slash 规范只有一套正式方案：由 route manifest 持有 slash policy，由 host 统一执行 normalization
+- 业务包不得在 handler、middleware 或局部 helper 里重复实现第二套 slash redirect 逻辑
+- UI href 生成统一使用 `pz_foundation.routing.public_canonical_href(...)`，模板层使用 `pz_site_ui` 暴露的 `canonical_public_href(...)`
+- 子包模板不要手动拼接 `/{lang}/...`、`/en/...` 或尾斜杠；语言前缀、alias、query、fragment 与 API/static 跳过规则由 foundation 统一处理
+- `DeclaredUrlSpec.namespace` 必须是稳定、非空、可审计的 dotted identifier
+- `DeclaredUrlSpec.path_prefix` 只能是空字符串或以 `/` 开头的非根 prefix
+- `DeclaredUrlSpec.replace_target` 若存在，必须指向已声明 namespace，用于显式替换
+- `DeclaredUrlSpec.route_hints` 必须在声明期固化
+- `DeclaredUrlSpec.conflict_policy` 的正式默认值固定为 `fail`
+- `include(...)` 负责子模块 include；上层 prefix 会与子模块 prefix 叠加；上层 namespace 会作为子模块 namespace 前缀继续下沉
+- `mount(...)` / `include(...)` 遵循 Django 风格父子 URLconf 语义：父级消费公共 prefix，子 app / 子 router 只声明相对路径，不得重复声明 mount prefix；例如挂载到 `/api/v1/payments` 时，子路由写 `/create-checkout-session`，不能写 `/api/v1/payments/create-checkout-session`
+- foundation 会先编译 `route_manifest`，再进入 FastAPI 挂载；同一路径/方法冲突必须在真实挂载前失败
+- `host.route` / `admin.panel` 这类 host 扩展路由也会先转成 `DeclaredUrlSpec`，再进入同一条 registry 编译链
+- host 挂载后会把 mounted route namespace 记录到 `app.state.pz_route_registry`
+- host 也会保留已编译的 `app.state.pz_route_manifest`
+
+推荐示例：
+
+```python
+from __future__ import annotations
+
+from pz_foundation.routing import include, path
+
+from .views import demo_page
+
+
+app_name = "pz_demo"
+
+urlpatterns = (
+    path("/demo", demo_page, name="pz_demo:demo-page"),
+    include("pz_demo.api", path_prefix="/api/v1", namespace="pz_demo.api"),
+)
+```
+
+URL 处理细则见 [`docs/路由与URL处理规范.md`](docs/路由与URL处理规范.md)。
+
+`public.py` 当前稳定导出聚焦：
+
+- `FoundationFacade`
+- `FoundationDbFacade`
+- `get_foundation_facade()`
+- `get_db_facade()`
+- `setup_infra()`
+- `shutdown_infra()`
+- `ensure_db()`
+- `in_transaction()`
+- `run_in_transaction()`
+- `claim_idempotency()`
+- `clear_idempotency_claim()`
+
+`COMPAT_EXPORTS` 当前为空。
+
+## 配置约定
+
+本包默认配置位于 `pz_foundation/configs/default.jsonc`，运行时正式读取路径为：
+
+- `settings_center.settings.pz_foundation.cache`
+- `settings_center.settings.pz_foundation.health`
+- `settings_center.settings.pz_foundation.mail`
+- `settings_center.settings.pz_foundation.observability`
+- `settings_center.settings.pz_foundation.resources.images`
+- `settings_center.settings.pz_foundation.storage`
+
+database 的唯一正式真相源位于 `settings_center.settings.pz_foundation.database` /
+`pz.jsonc -> apps.pz_foundation.database`；
+`pz_foundation` 不再维护第二套 app 级 database namespace。
+
+database runtime 还正式承载生产连接参数：`connect_timeout`、`pool_acquire_timeout`、
+`statement_timeout_ms`、`idle_in_transaction_session_timeout_ms`、`pool_max_lifetime`、
+`pool_max_idle`、`reconnect_timeout`、`health_check_interval`。这些参数由 settings center 编译后传入
+foundation Tortoise backend，不允许子包在业务路径直接拼接第二套数据库连接配置。
+
+PostgreSQL HA 的正式 surface 是 `database.urls`。单节点数据库也写成一个元素的 URL 列表；当解析出多个
+writer 候选节点时，foundation 必须把 `default` 编译成一个 psycopg/libpq multi-host conninfo，并用
+`target_session_attrs=read-write` 在新建连接时选择当前可写节点；不得把第一个 URL 或第一个 host 固定成长期主库。
+集群切换后，已有连接不会自动迁移，只有明确的连接失效或写连接命中只读节点等角色失效信号才触发受控重建 pool。
+
+数据库探活分为两类：启动/请求路径只检查 manager 与 pool lifecycle 状态，不执行 SQL；
+周期性 readiness probe 可以执行 `SELECT 1`，但只允许由 foundation 后台任务执行，且必须先证明连接
+处于 autocommit 模式。无法证明 autocommit 时必须拒绝探测，不能用隐式事务加 rollback 作为兜底，
+也不能留下 `idle in transaction`。请求路径只读取 lifecycle，default pool 不 ready 时 fail fast，
+不在请求里执行 `ensure_ready()`、`reconnect()` 或 SQL 探活。
+
+生产健康检查按职责分层：`/health` / `/live` 只表示进程存活，不碰数据库；`/ready` 只读取 manager / pool
+lifecycle 状态，不执行 SQL、不借业务连接；后台 readiness probe 是唯一允许常规执行 SQL 的探活路径。
+`PoolTimeout` 被视为池容量耗尽、连接泄漏或补连接失败风险，不属于断连重建信号。记录该错误时必须带
+pool size、可用连接数、等待队列、连接错误、请求错误等池快照；必要时可以带冷却窗口额外执行一次独立短连接
+诊断来区分“数据库不可达”和“业务池耗尽”。独立诊断不得复用业务池、不得进入业务事务、不得访问业务表。
+`PoolTimeout` 日志必须输出 `diagnosis.category`，用于直接区分数据库不可达、应用池耗尽、pool 补连接停滞和普通容量压力。
+连接池轮换只能作为受控恢复动作，必须有冷却窗口，不能在单次容量超时、锁等待或未知错误时自动重建。
+
+`settings.py` 只负责 `AppSettings` schema、默认值与 runtime override 声明。
+
+资源图片派生的正式配置位于 `pz_foundation.resources.images`。常规 `pz run` 只补齐缺失派生；合并 static 内已有同名派生文件且未显式 force 时会跳过。
+默认配置中 `pz_foundation.resources.images.force=true`，因此 `pz resources images` 不传 `--force` 也会强制覆盖同名派生；如果宿主显式改为 false，则可继续通过 CLI 参数强制：
+
+```bash
+pz resources images --force -d .
+```
+
+图片派生输出只进入当前 `ResourceManifest` 的合并 static 产物，不写回业务包源码目录；站点业务包不得再提供第二套图片派生命令或配置 namespace。
+
+环境变量覆盖示例由本包维护，不再由 `pz` core 项目模板托管。需要写入宿主 `.env` 时，使用本包 settings namespace：
+
+- `pz_foundation__database__password`
+- `pz_foundation__database__ssl_root_cert`
+- `pz_foundation__mail__password`
+- `pz_foundation__cache__password`
+- `pz_foundation__storage__access_key_id`
+- `pz_foundation__storage__secret_access_key`
+
+observability logger 的可选通知通道也属于 `pz_foundation.observability.logger`，运行时只消费 settings center；项目按需显式声明，不进入默认托管模板：
+
+- `feishu.webhook_error_event` / `feishu.secret_error_event`
+- `feishu.webhook_warning_event` / `feishu.secret_warning_event`
+- `feishu.webhook_custom_event` / `feishu.secret_custom_event`
+- `feishu.webhook` / `feishu.secret`
+- `telegram.bot_token` / `telegram.chat_id`
+- `telegram.bot_token_custom_event` / `telegram.chat_id_custom_event`
+
+managed worker 补充约定：
+
+- `pz_foundation` 不保存业务 worker 的数量真相；目标副本数仍由声明该 `worker.role` 的 owner app settings 提供。
+- `pz_foundation.managed_workers.force_restart_on_host_start` 是 `pz run` 自动托管入口是否强制收口旧 supervisor / worker 的唯一配置真相源，默认值为 `true`。
+- `pz_foundation.managed_workers.default_replica_count` 是 worker 声明了 `replica_count_setting` 但 owner app settings 缺失 / 非正数时的全局兜底副本数，默认值为 `1`。
+- `WorkerRoleSpec.replica_count_setting` 是副本数量的正式绑定字段；正常每个 worker 都应显式声明自己的 count setting。supervisor 运行时只从 `plan.settings.app_settings(<owner_app>)` 读取对应值，不读取子包 `configs/default.jsonc`。
+- 未声明 `replica_count_setting` 的 worker 视为冻结 / legacy singleton，目标副本数固定为 `1`，不受全局 fallback 扩容。
+- `WorkerReplicaCountResolver` 是 managed worker 副本数解析的唯一对象；其它代码不得手工拼接 owner settings、Task Center settings 或默认值。
+- `WorkerRoleSpec.auto_start_setting` 是自动拉起开关的正式绑定字段；声明阶段只给默认值，supervisor 运行时从 owner app settings 读取最终值。
+- `WorkerRoleSpec.worker_kind` 是 worker 进程职责分类；foundation 只在 status、worker_targets 和 CLI projection 中透出，不据此替业务 owner 判断任务、角色或成功真相。
+- 新增 worker count 默认键时，owner app 必须同时更新 settings schema 与 `configs/default.jsonc` 模板，并通过 `pz settings update --project-dir <project>` 同步到项目根配置；运行时真相仍是 settings center 编译后的 `SettingsSnapshot`。
+- detached supervisor 的状态真相位于项目 runtime 目录下的 `managed_workers/supervisor.state.json`，其中包含：
+  - `pz_env`
+  - `worker_targets`
+  - 当前 supervisor pid 与 phase
+- managed worker 的日志与副本状态文件统一收口到 `managed_workers/` 目录下：
+  - `managed_workers/logs/*.log`
+  - `managed_workers/workers/<app>/<tool>/`
+- worker 管理 CLI 集中在 `pz_foundation.cli.workers`：
+  - `pz workers list [name ...]`
+  - `pz workers status [name ...]`
+  - `pz workers stop [name ...]`
+  - `pz workers restart [name ...]`
+  - `pz workers run [name ...]`
+- `workers restart --start-timeout <seconds>` 控制启动后等待状态刷新的时间，超时后继续用 `workers status` 读取最终状态。
+- `pz pz_foundation workers ...` 是同一实现的 app CLI 入口；root 入口与 app 入口不得分叉。
+
+## 运行边界
+
+- 其它官方子包如需 DB、cache、storage、observability，应统一复用 `pz_foundation.public`，不要在包内各自复制基础设施实现。
+- `pz_foundation` 只提供通用 infra，不拥有业务成功真相。
+- 若某项能力需要业务扩展，应优先通过正式 provider / facade 方式扩展，而不是修改宿主 bootstrap。
+- cache / redis 的正式语义是“能力可降级，但不能把整个宿主默认拖死”：
+  - redis 未启用或未配置时，宿主仍应正常启动，cache capability 标记为 `disabled` / `unavailable`
+  - redis 已配置但连接失败时，宿主仍应启动，并把 cache capability 标记为 `degraded` / `unavailable`
+- `settings_center.settings.pz_foundation.cache` 还正式承载 redis 快失败参数：`connect_timeout_seconds`、`socket_timeout_seconds`、`operation_max_attempts`、`connection_retry_attempts`、`retry_base_delay_seconds`、`retry_max_delay_seconds`、`acquire_failure_cooldown_seconds`、`health_failure_cooldown_seconds`
+- foundation 的 async cache facade 会把 redis 操作错误向上抛出，由上层子包决定记录 error、继续当前状态、回退 DB 或返回 `503`
+  - 依赖 cache 的上层能力（例如 `pz_auth` 的 session control）在请求期继续按各自 contract fail-closed，不得静默放行
+- managed worker 由拥有 worker 的子包通过正式 app CLI 暴露启动入口，由 `pz_foundation` detached supervisor 统一托管；`pz run` 是宿主启动时自动托管入口。
+- `pz run` 自动托管看到的基础设施或外部入口 worker，不代表 Agent actor / role 实例都被系统默认启动；actor 常驻与任务驱动边界由 Agent 支持包自己的设计文档约束。
+- `pz run` 触发 worker 自动托管前必须先做 Web host/port 绑定预检；地址不可用时直接失败，不得先停止旧 supervisor / worker。
+- worker supervisor 的正式行为由 `pz_foundation` 实现：
+  - `force_restart_on_host_start = true` 或命令显式 `--force-restart` 时，先 stop 再按当前 `RuntimePlan` / settings 重启 supervisor；
+  - `--no-force-restart` 或配置显式关闭时，当前健康 worker 数量已达到 `worker_targets` 时不重复拉起；
+  - 当前数量不足时补齐到目标数量；
+  - `pz_env` 或 `worker_targets` 签名变化时，先 stop 再重启 supervisor；
+- detached supervisor 和它托管的 worker 子进程统一通过正式 `pz` 启动；`PZ_ENV` 优先继承当前宿主 `pz run`，缺失时才回退到当前 `RuntimePlan` 的 `pz_env`，并显式携带 `PZ_PROJECT_DIR`。
+- `stop_managed_workers(...)` 属于强制收口入口，会停止 supervisor 与匹配 worker 副本并重写 stopped state；不传选择条件时作用于自动托管 worker 集合。
+- `workers restart` 是人工运维的一键重启入口，会先执行正式 stop，再拉起新的 detached supervisor。
+- `workers run --detach --force-restart` 仍是底层 supervisor 入口；`--no-force-restart` 可为本次命令显式关闭该行为。
+
+## 验证方式
+
+子包级 import smoke：
+
+```bash
+cd <pz_contrib_root>/pz_foundation
+.venv/bin/python -c 'import pz_foundation, pz_foundation.public'
+```
+
+稳定 import surface smoke：
+
+```bash
+cd <pz_contrib_root>/pz_foundation
+.venv/bin/python - <<'PY'
+import importlib
+
+modules = [
+    "pz_foundation.public",
+    "pz_foundation.db",
+    "pz_foundation.kv",
+    "pz_foundation.observability",
+    "pz_foundation.notifications",
+    "pz_foundation.middlewares",
+]
+failed = []
+for module in modules:
+    try:
+        importlib.import_module(module)
+        print("OK", module)
+    except Exception as exc:
+        failed.append((module, repr(exc)))
+        print("FAIL", module, repr(exc))
+if failed:
+    raise SystemExit(1)
+PY
+```
+
+共享 surface 改动后的最终验证：
+
+```bash
+pz env sync --project-dir /path/to/project
+```

pz_foundation/docs/infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/350/257/264/346/230/216.md

@@ -0,0 +1,39 @@
+# infra 裁剪与落位说明
+
+`pz_foundation` 是官方基础设施 owner。旧 core / infra 中携带具体实现语义的内容，必须下沉到本包或对应 owning 子包，不能回流到 `pz` core。
+
+## foundation 接管的能力
+
+`pz_foundation` 负责以下官方通用基础设施实现：
+
+- DB 连接、事务、迁移执行与 ORM 绑定。
+- cache / Redis facade 与降级状态。
+- storage facade 与本地 / 对象存储 adapter。
+- mail / notifications。
+- observability logger、业务事件、bot message 与 exporter 绑定。
+- 通用 infra middleware，例如 request logging、cache control、security headers、CSRF、analytics、geo country。
+- host 级 infra startup / shutdown lifecycle。
+
+## 不属于 foundation 的能力
+
+以下内容必须继续由自己的 owner 维护：
+
+- 模板、Jinja、i18n、站点 UI、共享前端 runtime：`pz_site_ui`。
+- auth resolver、admin checker、登录跳转、route policy 消费：`pz_auth`。
+- redirect rules cache 与 redirect runtime：redirect owner。
+- API key、额度、billing、worker、task dispatch 等业务域能力：对应业务 / platform owner。
+
+## 迁移落位规则
+
+- 具体第三方 SDK、adapter、exporter、middleware 实现不得留在 `pz` core。
+- foundation 对外只暴露 `public.py` 中的稳定 facade；其它子包不得依赖 foundation 内部 manager / adapter 路径。
+- 所有运行态状态必须绑定 `ProjectContext` / app context，不能通过 import-time 全局单例跨项目复用。
+- local storage 未显式配置 `base_dir` 时，默认根必须来自 `ProjectContext.asset_dir`，再追加 `storage.subdir`；不得回退到历史 `data_dir` 或 `.runtime`。
+- middleware 必须消费编译后的 middleware config / transport config，不得构造期直接读取全局 settings。
+- request logging、security headers、CSRF、geo、analytics 等实现需要明确 owner、scope、reset、shutdown 与敏感信息脱敏规则。
+
+## 验证要求
+
+- foundation 自己维护稳定 import surface smoke，不由 `pz` core 发布门禁硬编码。
+- foundation 的 DB/cache/storage/observability/middleware 契约测试归本包测试集。
+- core 侧只验证 provider / manifest / lifecycle 协议，不验证 foundation 内部模块清单。