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/archive//344/270/255/351/227/264/346/200/201/00-legacy_core/346/240/207/345/207/206pip/345/214/205/345/214/226/351/207/215/346/236/204/346/200/273/347/272/262.md

@@ -0,0 +1,1073 @@
+# legacy_core 标准 pip 包化重构总纲
+
+> 历史说明：本文保留 `legacy_core` 字样，仅用于记录 `legacy_core -> pz` 的迁移背景、旧方案与治理禁区；当前正式基础包统一为 `pz`。
+
+> settings 统一口径：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取；`settings.py` / `settings/` 只负责声明。
+> namespace 统一口径：每个正式最小子包都必须有稳定唯一的 `app.id`；新建子包默认让目录名、import 包名与 `app.id` 对齐，distribution 使用对应的 Python 分发名；不强制特定技术前缀；没有叶子 app 身份的内部模块不得自定义 namespace。
+
+## 0. 资源覆盖正式结论
+
+- PZ 资源层是 Django 式同名覆盖：资源覆盖是文件级覆盖，顺序只看 `installed_apps`，后出现 app 覆盖前者同相对路径。
+
+## 0. 架构公约
+
+本次及后续所有 `pz` 架构设计，统一服从下面这条最高优先级公约：
+
+- 系统里真正存在的正式单位，只有最小子包。
+- `pz` 是职责特殊的基础包：它只负责稳定合同、发现、编译、组装与启动其他最小子包。
+- settings surface owner 是职责专门的最小子包：它只负责应用层 settings surface、project/app settings 读取面与相关正式注册入口；其物理源码落位由 owning 子包文档和仓库真相源地图维护。
+- `pz_framework`、`pz_apps`、`pz_apps`、`customerhub` 这类顶层源码组织根只用于 Git 与源码组织，不再是正式架构层，不再进入运行时 namespace。
+- 正式运行时身份必须收敛到最小子包本身，不允许再通过集合层目录表达正式依赖关系。
+- `installed_apps` 的唯一正式语法固定为“写目录名”，不写文件系统路径、不写 distribution 名、不写 `<pkg>.apps:app`。
+- 每个最小子包统一采用一套命名规则：
+  - `app_id = <app_id>`
+  - 目录名 = `<app_id>`
+  - import 包名 = `<app_id>`
+  - distribution = `<app_id with _ replaced by ->`
+- 新建子包默认让目录名、import 包名与 `app_id` 对齐；历史稳定 `app_id` 以已声明值为准，不因文档命名口径变化迁移。
+- 正式命名不强制 `pz`、`pz` 或其它特定技术前缀；不得再保留“什么时候加前缀、什么时候不加”的第二套规则。
+- 集合层 import 路径例如 `platform.*`、`site_runtime.*`、`contrib.*` 都不是长期正式方案；长期正式导入面只能是最小子包自己的包名。
+
+## 1. 背景
+
+当前 `legacy_core` 已具备独立框架包雏形，但实现上仍大量保留“仓库内 vendored 子系统”的运行假设，例如：
+- CLI 入口优先照顾 `python legacy_core` 与 wrapper 模式
+- settings 默认强依赖仓库根 `.env`
+- 资源与迁移合并输出写回 `legacy_core/merged/*`
+- 默认安装清单中直接内置大量官方 app 与业务 `app`
+- 运行期路径推断较多依赖 `Path.cwd()`、仓库根和包目录可写
+
+这些假设会阻碍 `legacy_core` 成为标准的 `pip` 安装包，也会模糊“框架内核”和“具体业务项目”的边界。
+
+## 2. 本次重构目标
+
+本次重构的直接目标不是“仅补齐一个 `pyproject.toml`”，而是将 `legacy_core` 收敛为一套标准、清晰、可替换的 Python app 框架约定：
+
+- `legacy_core` 作为一个标准 Python 包建设，开发、依赖锁定、命令执行、构建与测试统一使用 `uv` 管理
+- 让 `legacy_core` 可以作为标准框架包安装与运行
+- 让官方 app 与独立 app 在装配模型上完全一致
+- 让资源合并、迁移合并、运行时锁与临时文件都落到外部 `cache/runtime dir`
+- 让数据库、Redis 变成按需启用的可选能力
+- 让 Prometheus/metrics 以显式集成边界存在，而不是变成 import-time 全局副作用
+- 为后续将独立子包与部分官方 app 独立维护提供稳定契约
+- 让“最小子包是唯一正式单位，外层目录只是 Git 管理容器”成为文档、代码与发布层面的单一事实
+
+补充约束：
+
+- 本次按全新架构设计推进，运行时只保留新主链
+- 对历史子包的改造，主要通过明确的适配改造文档完成，而不是在 core 中长期保留两套主链
+- 旧 `legacy_core` 代码是外部可观察行为的回归基线，不是目录结构、全局状态与历史脏实现的复制模板
+- 重构允许重写结构、分层、生命周期与全局状态模型，但不得无文档声明地改变外部 API、路由、配置、资源覆盖、worker 协议与关键错误语义
+
+## 3. 设计原则
+
+- Django 风格：一切功能以 app 为最小装配单元
+- 最小子包唯一化：系统只承认最小子包，不承认集合层 namespace
+- 自顶向下设计：先定义边界、契约、真相源，再落实现细节
+- 自底向上开发：先落稳定 schema/manifest/registry，再接 facade/capability，最后接入口与 app 集成
+- 单一职责：每个核心构件只解决一个问题，不混入第二条主职责
+- 依赖倒置：上层只依赖契约、facade、capability，不依赖具体实现模块
+- 单一路径原则：一个问题只保留一种正式解决方案
+- 不重复造轮子：不得在不同层各自重写同类扫描、聚合、推导、注册逻辑
+- 单一顺序源：`installed_apps` 是唯一 app 装载顺序来源
+- 文件夹声明装配：`installed_apps` 可以声明最小子包，也可以声明文件夹/容器目录；框架负责自动递归发现其中嵌套的最小子包，并以展开结果作为正式装配单位
+- 目录名语法固定：`installed_apps` 中每个条目只能是正式最小子包目录名或正式容器目录名
+- 发现算法固定：命中最小子包后立即停止继续向下递归；容器目录按目录名字典序做深度优先展开；重复 `app_id` 直接报错，不做静默跳过
+- 命名统一：每个最小子包必须有稳定唯一的 `app_id`；新建子包默认让目录名、import 包名与 `app_id` 对齐，distribution 使用对应的 Python 分发名，不强制特定技术前缀
+- 无特权 app：官方维护最小子包与其它最小子包统一为普通 app；装配层面平权，公开交互面分层
+- 显式优于隐式：替换、覆盖、装配、资源输出路径必须显式声明
+- 可安装优先：所有路径与入口设计默认面向 `pip install` 场景
+- 工具链统一：新版包的开发、依赖锁定、构建与命令执行统一采用 `uv`
+- 行为优先：优先保持旧实现的外部可观察行为；若需改变行为，必须在设计文档、迁移说明与测试门禁中显式声明
+- 可选基础设施：数据库、Redis、观测能力按需启用，不成为 base 运行前提
+- 能力边界清晰：监控集成属于框架边界，监控平台部署属于项目/运维边界
+
+约束：
+
+- `uv` 只用于开发、锁定依赖、构建与测试
+- 对外分发与运行仍保持标准 `pip` / wheel 交付模型
+- 不允许把 `uv workspace` 心智扩散成用户运行前提
+
+### 3.1 Django 风格的具体落点
+
+这里说“借鉴 Django”，指的是借鉴其设计哲学，而不是复制其实现：
+
+- 用 app registry / `installed_apps` 管理装配顺序
+- 用命名空间 settings 管理 app 配置，而不是平铺全局字段
+- 用统一 CLI / management command 风格暴露运维入口
+- 用 preflight / system checks 风格在启动前发现阻断项
+- 用显式生命周期与公共门面代替隐式 import side effect
+
+补充约束：
+
+- system checks 的正式入口统一为 `pz check`
+- 检查逻辑统一消费已编译完成的 `RuntimePlan`
+- 不允许 Web startup、debug 页面、worker SDK、子包脚本各自实现第二套检查主链
+
+不借鉴 Django 的部分：
+
+- 不引入过度依赖约定路径的项目骨架魔法
+- 不允许框架偷偷依赖仓库根目录或 vendored 目录结构
+- 不把进程级全局单例当成长期稳定契约
+
+### 3.2 分层与依赖方向
+
+正式架构统一分为五层：
+
+1. 契约层
+   - schema
+   - settings model
+   - manifest
+   - capability interface
+   - provider contract
+2. 编译/聚合层
+   - app registry compiler
+   - route manifest compiler
+   - middleware manifest compiler
+   - resource manifest compiler
+   - infra snapshot compiler
+3. facade/capability 层
+   - context-bound facade
+   - capability registry
+   - provider registry
+4. 适配器层
+   - FastAPI/ASGI
+   - Aerich/Tortoise
+   - Redis client
+   - Prometheus exporter
+5. 入口层
+   - CLI
+   - Web app
+   - worker
+
+依赖方向固定为：
+
+- 入口层 -> facade/capability 层 -> 编译/聚合层 -> 契约层
+- 适配器层 -> 契约层 或 facade/capability 层
+- app 代码 -> public facade / capability contract
+
+禁止：
+
+- 入口层直接操作底层模块级单例
+- app 直接 import core/infra 内部实现细节
+- facade 反向依赖某个具体入口
+- 同一能力在多层各自维护一份规则与状态
+
+### 3.2.1 官方维护最小子包与其它最小子包的正式关系
+
+- 官方维护最小子包与其它最小子包在装配层面完全一致
+- 两者都只是 app
+- 两者都只能通过 `installed_apps` 进入系统
+- 两者都没有装配优先级特权
+
+但在公开交互面上，两者明确分层：
+
+- 官方维护最小子包
+  - 定义为官方 `library app`
+  - 允许其它 app 通过稳定 `public.py` 依赖
+  - 统一由 official infra owner 承载 `infra` 背后的具体实现
+- 独立子包
+  - 定义为独立 `integration app`
+  - 不允许其它 app 直接 import 其内部 Python 模块
+  - 只允许通过稳定交互边界协作：
+    - capability
+    - facade
+    - events
+    - provider contract / internal binding
+    - CLI/task 协议
+    - 必要时的 HTTP API
+
+禁止：
+
+- 让独立子包重新变成“可直接 import 的内部实现仓库”
+- 让任何容器目录在装配上拥有高于其它 app 的优先级
+
+### 3.3 唯一真相源清单
+
+以下对象必须各自成为唯一真相源：
+
+- `project_dir`：项目边界唯一真相源
+- `pz.jsonc`：项目正式配置唯一真相源
+- `<project_dir>/.env` 与 `<project_dir>/.env.{PZ_ENV}`：环境覆盖文件唯一入口集合
+- `installed_apps`：app 装载顺序唯一真相源
+- `[app_replacements]`：app 替换关系唯一真相源
+- route manifest：路由裁决唯一真相源
+- middleware manifest：中间件裁决唯一真相源
+- `<cache_dir>/resources/manifest.json`：资源合并结果唯一真相源
+- `InfraSettings` / `InfraContext`：基础设施状态唯一真相源
+
+任何历史 helper、回退路径或旧门面都不得再生成第二套并行真相源。
+
+补充说明：
+
+- `installed_apps` 的每一项可以是正式最小子包目录名，也可以是正式容器目录名
+- 分组目录只用于 Git 与源码组织，不参与运行时 namespace
+- app registry、settings、resources、routes 都以 `installed_apps` 展开后的最小子包集合为单位工作
+- 正式发现只认目录结构，不做模块名猜测、历史别名补全或 package-level `app` 猜测
+
+### 3.4 唯一组合根与运行计划
+
+正式架构中，必须存在且只存在一个组合根：
+
+- `RuntimePlan` 编译入口
+
+它负责把所有下层正式产物一次性编译为当前进程的运行计划。
+
+`RuntimePlan` 至少固定包含：
+
+- `ProjectContext`
+- `SettingsSnapshot`
+- `AppRegistry`
+- `ResourceManifest`
+- `InfraContext`
+- `RouteManifest`
+- `MiddlewareManifest`
+- `CapabilityRegistry`
+
+其中资源域的正式心智固定为：
+
+- 作者配置入口是 `resources.items`
+- 单个 app 的资源发现结果落在 `ResourceSource.items`
+- 当前项目的统一资源编译结果落在 `ResourceManifest.items`
+- 每个资源项直接持有 `name / source_dirs / output_dir`
+
+正式要求：
+
+- Web、CLI、worker 都只能先构建 `RuntimePlan`，再消费它
+- 不允许某个入口跳过 `RuntimePlan`，直接单独拼 settings、app registry、resource manifest 或 infra context
+- `RuntimePlan` 一旦生成，就作为当前进程唯一运行图输入
+- `RuntimePlan` 产物必须视为不可变快照；后续阶段只能消费，不得原地改写
+- `lifespan/startup/shutdown` 只允许激活或关闭 `RuntimePlan` 中已经编译好的 capability，不再反向改写运行图
+- `CapabilityRegistry` 只作为运行图内部对象存在，不提升为 app 稳定公共依赖面
+
+禁止：
+
+- Web 入口自己再扫一遍 apps
+- worker 入口自己再推一遍 infra config
+- CLI 命令自己再定位一遍 resources/migrations
+- bootstrap/lifespan 再临时补 route、middleware、settings 稳定字段
+
+### 3.5 编译阶段与执行阶段分离
+
+正式架构统一分为两个阶段：
+
+1. 编译阶段
+   - 读取配置
+   - 解析 app
+   - 编译 manifest
+   - 编译 typed snapshot
+   - 生成 `RuntimePlan`
+2. 执行阶段
+   - 挂载 route
+   - 初始化 provider/client
+   - 创建 facade/capability 实例
+   - 启动 Web/CLI/worker
+   - 执行 shutdown/cleanup
+
+正式要求：
+
+- 编译阶段负责裁决与产出，不负责启动任何运行时副作用
+- 执行阶段只消费编译结果，不再重新裁决规则
+- 冲突检测、替换关系、顺序决定、路径决定、enabled/disabled 判定，全部必须在编译阶段完成
+- DB/Redis client 初始化、logger handler 注册、worker loop 启动、route mutation，只允许发生在执行阶段
+
+禁止：
+
+- 在编译阶段偷偷初始化 DB/Redis/metrics/exporter
+- 在执行阶段重新扫描 installed apps、重新推导 settings、重新生成 manifest
+- 在 `startup()`、`lifespan`、middleware 构造期重新做冲突裁决
+- 在 adapter 层重新实现一套编译规则
+
+## 4. 核心决策
+
+### 4.1 包边界
+
+- `legacy_core` 主包只承载框架内核与通用装配能力
+- `pz_contrib` 是官方通用实现最小子包，不具备特殊装配权限
+- 官方能力与业务能力一样，统一以 `<app_id>` 最小子包形式存在
+- 最小子包的正式源码统一收口到某个顶层源码组织根下的 `<app_id>/`，例如 `pz_framework/pz_contrib/<app_id>/`、`pz_apps/<app_id>/`、`pz_apps/<app_id>/`
+- 外部业务 app、第三方 app、官方维护最小子包在装配层面没有优先级差异
+
+补充约束：
+
+- 官方能力不得再通过任何集合层 namespace 暴露长期 import path
+- 任何最小子包都不得再借 `platform.*`、`site_runtime.*`、`contrib.*` 这类集合层路径伪装成正式运行单元
+- `infra` 的具体实现统一收口到官方最小子包；`legacy_core/infra` 只保留薄绑定层
+
+official infra owner 的完整目录结构以 `01-目录与分层重构执行方案.md` 为准。
+
+约束：
+
+- official infra owner 只承接“原本误落在 `legacy_core/infra` 的具体实现”
+- official infra owner 的 `public.py` 负责向其它官方 app 暴露稳定 facade
+- official infra owner `public.py` 的正式导出面以 `16-正式Facade总表.md` 为准
+- middleware 不属于 `core`；`assembly` 只编译 `MiddlewareManifest`，具体 middleware 类统一进入官方基础能力最小子包或对应 app
+- `i18n` / `jinja` 属于展示层 runtime，不进入 infra owner，而进入 shared site UI owner 或对应展示层 app
+- `HealthFacade` 是公开能力面，但 health 聚合实现仍归 `runtime` / capability 层，不单独要求 `foundation/health/`
+- official infra owner 不重新变成第二个 `infra`；它只是集中落位，不改变依赖方向
+
+补充冻结：
+
+- `legacy_core.host` 已删除；正式 installable 通用入口只允许落在 `legacy_core.runtime/*`，workspace 开发辅助脚本只允许位于仓根 `devtools/*`
+- `legacy_core` 不允许 import 或点名任何具体 owner app
+- owner-specific host/runtime 入口必须回到 owner 自己的 app 包下
+- `legacy_core` 只按正式协议、manifest、installed apps 与 capability/host registration 进行发现和编排
+
+禁止：
+
+- 在 `legacy_core` 下恢复 `host/` 或保留 DB / Redis / task runtime 的 owner facade
+- 在宿主项目中再次创建 `project_runtime` 一类第二装配层
+- 让 core 通过硬编码 import path 支持某个特定 app
+
+### 4.2 装配边界
+
+- 所有 app 统一通过 `installed_apps` 装配
+- 默认不再把业务根包 `app` 视为内建特殊层
+- `installed_apps` 可以直接写最小子包，也可以写文件夹/容器目录；真正进入 app registry、settings、resources、routes 的是递归展开后的最小子包
+- `installed_apps` 不接受文件系统路径、distribution 名或 `<pkg>.apps:app` 语法
+- 最小子包判定固定为：
+  - 目录名对应稳定 `<app_id>`
+  - 目录内存在同名 Python 包目录 `<app_id>/`
+  - 同名 Python 包目录内存在正式 `apps.py`
+- 命中最小子包后，不再继续向下扫描其子目录
+- 容器目录展开顺序固定为：先保持 `installed_apps` 条目顺序，再在每个容器内部按目录名字典序深度优先展开
+- 模板、静态、语言、页面声明、模板配置、模型、迁移等资源覆盖规则统一跟随 `installed_apps` 顺序
+- `pages/`、`template_config/` 与 `templates/`、`locales/` 一样，都是正式资源目录；启动时必须走同一套覆盖逻辑，不允许各自再发明第二套扫描或优先级规则
+- 同 `app_id` 冲突默认报错，只有显式替换才允许覆盖
+
+### 4.3 运行边界
+
+- 包目录必须视为只读
+- 合并产物统一写入外部 `cache_dir` / `runtime_dir`
+- 运行期不得假设当前工作目录就是项目根目录
+- 标准用户入口统一为 `legacy_core`
+- `python -m legacy_core` 只保留为技术入口，不作为正式文档主路径
+
+### 4.4 配置边界
+
+- 主配置文件统一为 `pz.jsonc`
+- 环境变量与 `.env` 主要负责敏感值与覆盖
+- app 私有配置统一走 `settings_center.settings.<app_id>`
+- app 代码不得直接读取 `os.environ`
+
+## 5. 目标目录心智
+
+完整目录结构以 `01-目录与分层重构执行方案.md` 为唯一真相源。
+
+这套目录设计先裁掉几个歧义：
+
+- `legacy_core/` 只保留框架入口与内核主链
+- `runtime/assembly/core/infra` 共同组成框架主链，但各自职责单独收口
+- 官方与业务最小子包的正式源码真相源统一收口到各自顶层源码组织根下的 `<app_id>/`
+
+## 5.1 四层目录的硬边界表
+
+为了避免后续又把“暂时方便的实现”塞回错误目录，`runtime / assembly / core / infra` 的文件类型边界固定如下。
+
+### 5.1.1 `runtime/`
+
+允许放入：
+
+- `ProjectContext`、`RuntimePlan` 的运行时持有与访问入口
+- context-bound `Registry` / `Facade` / provider binding 激活逻辑
+- request/app-state/runtime helper
+- Web / CLI / worker 的执行期入口胶水
+- `startup()` / `shutdown()` 的执行器
+- health / metrics / debug surface 的执行期暴露
+- 把已编译 `RouteManifest` / `MiddlewareManifest` / `ResourceManifest` 应用到宿主框架的 adapter glue
+
+补充约束：
+
+- runtime 消费资源编译结果时，只读取 `ResourceManifest.items` 与 `manifest_path/output_root/staging_root/lock_path`
+- runtime 不得自行恢复目录名映射表、固定资源输出字段或第二套资源 facade
+
+禁止放入：
+
+- settings 读取器、`.env` 发现器、project root 推断器
+- app 扫描、资源扫描、迁移扫描、middleware 扫描
+- route / middleware / resource / infra 的编译规则
+- 具体 middleware 类
+- 具体 provider/client/SDK 实现
+- 任何 import-time 单例、全局 setter、全局 manager
+
+### 5.1.2 `assembly/`
+
+允许放入：
+
+- settings compiler
+- app registry compiler
+- route / middleware / resource / infra manifest compiler
+- project/app/resource 路径归一化逻辑
+- 冲突检测、替换裁决、顺序裁决
+- 资源 merge 计划、迁移归属计划、诊断产物编译
+
+禁止放入：
+
+- FastAPI/ASGI 对象创建与 mutation
+- DB/Redis/mail/storage client 初始化
+- logger/exporter/worker loop 启动
+- 具体 middleware 类与具体 provider 实现
+- request helper、app.state helper、thread-local/runtime-local 状态
+- 在编译阶段触发文件写入、网络 I/O、依赖探测
+
+### 5.1.3 `core/`
+
+允许放入：
+
+- app protocol、declaration model、dependency rule
+- route / middleware / resource 的声明模型与纯校验规则
+- error code、error envelope、health result model
+- request correlation id / trace correlation model 的纯协议定义
+- capability contract、provider contract 的纯接口定义
+- 不依赖具体 app / 具体 provider / 具体目录真相源的纯规则
+
+禁止放入：
+
+- 具体 app 清单、具体官方 app import path 特判
+- FastAPI/Request/app.state/CLI 运行时 helper
+- `startup()` / `shutdown()` / lifespan 副作用
+- 具体 middleware 类、模板运行时、i18n 运行时、静态资源服务
+- 具体 DB/Redis/storage/mail/observability provider 实现
+- 任何“因为历史原因先放进 core”的临时实现
+
+### 5.1.4 `infra/`
+
+允许放入：
+
+- typed infra settings / typed context / capability state model
+- provider contract / adapter protocol / binder interface
+- capability 装配所需的最小 runtime binder
+- 最小 noop / null / disabled 语义实现
+- 不带业务语义的 resilience 工具
+
+禁止放入：
+
+- 共享 middleware 实现目录
+- i18n / jinja / site runtime / template helper
+- 平台 app 专属 registry、provider 注册表、模块配置逻辑
+- 具体第三方 SDK / 云服务 / exporter / bot handler 实现
+- import-time 默认 client、默认 registry、默认 logger
+- 任何官方 app 或独立子包的业务逻辑
+
+### 5.1.5 一票否决规则
+
+某个文件只要满足以下任一条件，就不得进入 `core` 或 `infra`：
+
+- 需要知道某个具体官方 app / 独立子包的名字
+- 需要直接 import 具体 provider / 具体 middleware 类
+- 需要在导入期或编译期产生运行时副作用
+- 需要依赖 repo-root、`cwd`、历史目录布局才能工作
+- 需要通过“临时回退”补正式主链缺口
+
+### 5.1.6 二级目录固定说明
+
+完整二级目录结构以 `01-目录与分层重构执行方案.md` 为唯一真相源。
+
+补充约束：
+
+- `runtime/cli/` 只放执行期 CLI context/helper，不承担 console-script 入口发现
+- `assembly/*` 不得夹带执行期状态与宿主框架 mutation
+- `core/*` 不再保留 `app_factory/`、`ops/`、`resources/`、`cli/` 目录
+- `core/` 不设 `apps/` 子目录
+- `infra/*` 若保留 `observability/` 与 `resources/`，也只能保留 contract/noop/path-model 边界
+
+## 6. 关键约定
+
+- `installed_apps` 是唯一 app 顺序真相源
+- `middleware` 是唯一中间件顺序真相源
+- 模板/静态/语言/页面声明/模板配置覆盖按 `installed_apps` 后者覆盖前者
+- 迁移必须落在 `migrations/<app_id>/`
+- app 间禁止直接 import 对方内部实现
+- 跨 app 协作统一走 public facade、capability contract、events，以及必要的 provider contract / internal binding 协议
+
+## 6.1 稳定边界与内部边界
+
+从工程治理角度，`legacy_core` 必须明确区分“稳定公共契约”和“可自由重构的内部实现”。
+
+稳定公共契约包括：
+
+- `pz` CLI 入口语义
+- `pz.app:create_app`
+- `pz.app:create_host_app`
+- `pz.app:run_host_main`
+- `pz.jsonc` 配置结构
+- app 最小协议
+- `installed_apps` / app registry / migrations / resources 的正式约定
+- 官方声明为 `public.py`、capability contract、provider contract 的稳定边界
+
+默认不属于稳定公共契约的内容：
+
+- `legacy_core.settings`
+- `core/*`、`infra/*` 内部 helper 的具体文件布局
+- 官方维护最小子包/独立子包的内部 service / runtime / module 目录
+- 历史 adapter、旧入口和回退路径
+- 任何未在文档中声明为 stable 的私有模块 import path
+
+要求：
+
+- 文档必须明确哪些入口是 stable，哪些不属于稳定公共边界
+- 重构中允许调整内部目录，但不得破坏已声明的 stable 契约
+
+## 6.2 旧路径清理策略
+
+本次重构要求旧路径、旧入口与旧导入魔法全部退出正式设计。
+
+要求：
+
+- 每个旧入口都要列入删除清单：
+  - 当前状态
+  - 正式替代方案
+  - 本次重构中直接移除
+- 正式发布目标中不保留两套主链并存
+- 任何历史导入魔法、自动补全、隐式回退都不得继续扩展能力
+- 开发过程中若仍看到旧路径命中，必须视为未完成项并立即修正
+
+交付边界：
+
+- 对“标准 pip 包化重构”而言，最终交付物只保留新正式路径
+- 真正需要保留的是迁移说明、子包适配改造清单、发布说明
+
+## 6.3 默认失败语义
+
+从最佳工程实践看，框架重构期间最容易失控的点，是把“warning + 继续运行”当成常态。
+
+新规范应默认采用：
+
+- 配置错误默认失败
+- app registry 冲突默认失败
+- route / extension / middleware 冲突默认失败
+- 必需 provider 缺失默认失败
+- 只有显式声明为 optional 的能力，才允许降级为 disabled / unavailable
+
+不采用：
+
+- 先吞异常
+- 留 warning
+- 继续把半初始化结果带入后续装配链
+
+要求：
+
+- 每个装配阶段都应明确哪些错误 fail-fast、哪些错误可降级，以及降级后的正式语义
+
+## 6.4 单一职责与禁止重复实现
+
+核心构件职责固定如下：
+
+- settings compiler 只负责读取与归一化配置，不负责 app 装配
+- app settings 聚合器只负责聚合 app 配置，不负责 runtime override 执行
+- app registry 只负责 app 解析、依赖校验、顺序裁决
+- route registry 只负责 route manifest 编译与冲突裁决
+- middleware registry 只负责 middleware manifest 编译与冲突裁决
+- resource manifest compiler 只负责资源发现、合并、manifest 生成
+- infra snapshot compiler 只负责把配置编译为 typed snapshot
+- readiness aggregator 只负责聚合已启用探针结果，不负责初始化依赖
+- facade/capability 只负责当前上下文的能力暴露，不负责重新解析配置
+- entrypoint 只负责选择进程类型并组装上下文，不负责重写核心规则
+
+禁止：
+
+- 同时在 settings compiler、bootstrap、lifespan 三处重复做字段归一化
+- 同时在 app registry compiler、DB config compiler、resource manifest compiler 三处重复扫描 installed apps
+- 同时在 route registry 与 FastAPI mutation 阶段各做一遍冲突裁决
+- 同时在 facade 与 adapter 中重复维护缓存、订阅、版本游标
+- 每个 app 各自重写一套 env 读取、resource 定位、provider 注册协议
+
+正式要求：
+
+- 相同问题只允许有一个正式编译器/聚合器
+- 其它层只允许消费结果，不允许再派生第二份规则
+
+## 6.5 核心构件唯一命名约束
+
+为了避免同一职责在实现中被 `builder`、`manager`、`service`、`helper`、`loader` 混名复写，正式架构对核心构件名称作如下约束：
+
+- `Compiler`
+  - 只表示编译阶段构件
+  - 负责把声明、配置、元数据编译为不可变 snapshot / manifest / plan
+  - 可以失败、可以输出诊断，但不得持有长期运行态状态
+- `Registry`
+  - 只表示当前 `RuntimePlan` 派生出来的 context-bound 索引与查找容器
+  - 其输入必须来自编译结果，不得再次扫描目录、推导配置、重做冲突裁决
+- `Facade`
+  - 只表示对 app/handler/worker 暴露的稳定公共能力入口
+  - 只消费当前上下文已经编译好的 plan/snapshot/registry/provider
+- `Provider`
+  - 只表示 capability 背后的具体实现、工厂或外部系统绑定点
+  - 必须受当前 context 生命周期约束
+- `Adapter`
+  - 只表示与 FastAPI、Tortoise、Aerich、Redis、Prometheus 之类外部框架或协议的对接层
+  - 只负责协议适配，不负责框架内部裁决
+
+禁止把以下命名作为稳定架构角色继续扩散：
+
+- `manager`
+- `service`
+- `helper`
+- `loader`
+
+这些名称若仍保留，只能作为局部内部实现文件名，且不得承担稳定公共契约职责，不得成为跨 app 依赖入口。
+
+补充要求：
+
+- 同一类问题只能有一个正式 `Compiler`
+- 同一类运行态公共能力只能有一个正式 `Facade`
+- 同一类上下文索引只能有一个正式 `Registry`
+- 文档名、代码名、测试名必须对齐，不再同时并存语义等价的：
+  - `RuntimePlan`
+  - `BootstrapState`
+  - `ExecutionGraph`
+  - `AppAssemblyContext`
+  这类多套同义核心名词
+
+## 6.6 Adapter 层职责与禁止清单
+
+Adapter 层是正式架构里最容易失控的地方，必须明确收口。
+
+Adapter 只允许做：
+
+- 把 `RouteManifest` 挂载到 FastAPI/ASGI
+- 把 `MiddlewareManifest` 转成宿主框架中间件实例
+- 把 `InfraContext` 中的 DB/Redis/metrics 配置接到具体客户端
+- 把 `Facade` / `Provider` 暴露给外部框架需要的调用点
+
+Adapter 不允许做：
+
+- 重新解析 `project_dir`
+- 重新读取 settings 或环境变量
+- 重新扫描 app、资源、迁移目录
+- 重新决定 app 顺序、替换关系、冲突裁决结果
+- 重新生成 route/middleware/resource/infra 规则
+- 在内部偷偷维护第二套 registry/cache/snapshot
+- 夹带业务规则、默认兜底、来源优先级或 heuristic
+- 通过吞异常把 `unavailable` 伪装成 `ready`
+- 直接改写 `RuntimePlan`、`SettingsSnapshot`、`InfraContext`
+
+正式要求：
+
+- 启用/禁用判定只能来自编译阶段产物
+- adapter 读取到的所有输入都必须是已编译完成的 typed snapshot 或 manifest
+- adapter 若发现输入不足，只能 fail-fast 报错，不得在本层补推导逻辑
+
+## 6.7 公共 registry / facade / provider 的统一编译与生命周期
+
+所有平台能力都必须遵守同一套装配模式：
+
+1. 编译阶段由正式 `Compiler` 产出声明和计划
+2. 执行阶段基于计划创建 context-bound `Registry`
+3. 再由 `Registry` 和 `Provider` 组装稳定 `Facade`
+4. 生命周期结束时统一 `shutdown/reset`
+
+正式要求：
+
+- extension、route、middleware、provider、capability、metrics 等同类能力，不得各自发明局部 registry 体系
+- app `startup()` 只允许激活或绑定已编译好的 provider/capability，不得在运行时再创建新的正式 registry 主链
+- 任一公共能力的消费侧只允许依赖对应 facade，不得同时旁路读取 registry、provider 私有状态和模块级缓存
+- 公共 registry 的 owner、scope、reset、diagnostics 语义必须统一，不再让不同平台 app 各自定义
+- facade 不得兼任 compiler；provider 不得兼任 facade；adapter 不得兼任 registry
+
+## 6.8 诊断与系统检查的单一路径原则
+
+诊断能力也必须只有一种正式解决方案。
+
+正式要求：
+
+- system checks 统一由 `RuntimePlan` 驱动
+- 检查结果统一产出结构化 `CheckReport`
+- CLI、debug surface、发布前校验、preflight 都只允许消费同一份 `CheckReport` 或其同源数据
+
+`CheckReport` 至少固定包含：
+
+- check id
+- severity
+- owner
+- scope
+- message
+- remediation
+- related manifest / settings / app_id
+
+禁止：
+
+- 某个入口自己扫描目录再拼一份检查结果
+- 某个平台 app 自己定义一套不同 check 输出格式
+- 用 warning 文本流代替正式检查报告
+
+## 6.9 生命周期状态机的单一路径原则
+
+生命周期也必须有唯一正式语义，不允许不同 app、不同入口各自解释 `init/startup/shutdown`。
+
+正式状态机固定为：
+
+1. declared
+2. compiled
+3. bound
+4. started
+5. stopped
+
+状态含义固定如下：
+
+- declared
+  - app 声明已被读取
+  - 尚未进入运行期绑定
+- compiled
+  - app 已进入 `RuntimePlan`
+  - 所有声明裁决已完成
+- bound
+  - provider / facade / registry 已按当前上下文创建
+  - 尚未启动长期运行副作用
+- started
+  - 必要运行期能力已激活
+- stopped
+  - 已完成对称清理
+
+正式要求：
+
+- `init()` 只允许发生在 declared -> compiled 之间
+- `startup()` 只允许发生在 bound -> started
+- `shutdown()` 只允许发生在 started -> stopped
+- 不允许 `startup()` 补声明
+- 不允许 `shutdown()` 承担新的裁决逻辑
+- Web / CLI / worker / tests 共用同一套生命周期状态机
+
+禁止：
+
+- 某个 app 自己扩展第二套正式生命周期阶段名
+- 入口层与 app 层对同一钩子有不同语义解释
+- 通过重复调用 `startup()` / `shutdown()` 制造隐式重编译或隐式重绑定
+
+## 6.10 错误与诊断编码的单一路径原则
+
+错误语义也必须可编排、可测试、可自动化消费。
+
+正式要求：
+
+- 配置错误、装配错误、能力错误、执行错误使用统一错误编码体系
+- `CheckReport`、CLI `--json` 输出、日志诊断、测试断言都使用同一编码集合
+- 错误编码必须稳定、可枚举、可文档化
+
+最少固定四类前缀：
+
+- `CFG`
+  - 配置与 project context 错误
+- `ASM`
+  - app/route/middleware/resource 装配错误
+- `CAP`
+  - capability/provider/infra 错误
+- `RUN`
+  - 运行期执行与生命周期错误
+
+禁止：
+
+- 只返回自由文本而没有稳定 code
+- CLI、debug、tests 各自定义不同错误标签
+- 用异常类名或第三方库原始报错直接充当正式对外错误编码
+
+## 7. 一次性落地
+
+本次不采用分阶段交付策略，目标是一次性完成标准 `pip` 包化重构。
+
+但工程上仍固定按以下内部顺序实施：
+
+1. 先收口包边界、入口边界、配置边界、运行目录边界
+2. 再收口资源输出、运行目录、可选基础设施
+3. 再完成平台 app、worker、capability、子包适配
+4. 最后补齐测试矩阵、发布说明、迁移说明、子包改造验收
+
+要求：
+
+- 不允许以“先上半套架构，后续再补”为正式交付方式
+- 一次性实现并不等于无顺序开发，而是最终交付目标必须一次达到新架构要求
+- 子包适配应纳入本次整体交付，而不是延后为未来阶段性工作
+
+## 8. DoD
+
+达到以下条件时，可认为“标准 pip 包化”基本成立：
+
+- `pip install legacy_core` 后可直接通过 `legacy_core` 运行
+- 不依赖仓库根路径、默认 `app` 包或包目录可写
+- 资源、迁移、运行态文件全部落在外部 `cache/runtime dir`
+- 官方维护最小子包与其它最小子包可统一装配与替换
+- SQLite、MySQL、PostgreSQL 均可按需启用
+- 无 DB / 无 Redis 场景可正常运行最小应用
+
+交付补全项：
+
+- `public.py` / facade / capability contract 与 internal/private 边界已经文档化
+- 旧路径清理清单、一次性替换说明、迁移说明完整
+- 整体交付具备可回滚发布面，不依赖未来追加 phase 才闭环
+
+## 9. 生产化补充约束
+
+从生产最佳实践看，框架设计除了边界清晰，还必须具备可发布、可回滚、可支持、可诊断。
+
+### 9.1 支持策略
+
+正式要求：
+
+- `legacy_core` core 必须声明明确的 Python 版本支持范围
+- `legacy_core` core 必须声明明确的数据库支持范围：
+  - SQLite
+  - MySQL
+  - PostgreSQL
+- 每个官方维护最小子包 / 独立 app 都必须声明与 core 的版本范围
+- 不允许把“理论上可用”当作正式支持
+
+### 9.2 发布与回滚策略
+
+正式要求：
+
+- 每次 core 发布都必须具备：
+  - 升级说明
+  - 破坏性变更说明
+  - 回滚说明
+- 目录边界、迁移归属、settings 字段、错误编码一旦变更，必须进入发布说明
+- 不允许通过隐藏开关或未文档化回退逻辑充当回滚机制
+
+### 9.3 运行成本边界
+
+正式要求：
+
+- base 安装启动最小应用时，不应默认初始化 DB、Redis、metrics exporter、asset build、worker loop
+- `pz check`、`pz list`、`pz --help` 这类基础命令必须保持轻量，不触发重依赖初始化
+- 资源编译、preflight、迁移工具必须显式进入，不得混入常规启动热路径
+
+### 9.4 core freeze / extension-first
+
+本次 `legacy_core` 重构完成后，`legacy_core` 内核进入冻结治理。
+
+正式要求：
+
+- 重构完成后的 `legacy_core` 不再作为持续承载新功能的默认落位
+- 后续所有 `pz` 相关增量需求，默认进入官方扩展包，而不是继续修改 `legacy_core`
+- 官方扩展包的正式落位为官方最小子包源码根，或单独发布的官方最小子包
+- 只有框架级公共契约、编译边界、运行边界、诊断边界、安全修复与缺陷修复，才允许继续修改 `legacy_core`
+- 任何业务能力、平台能力、provider 实现、共享 middleware、站点能力、任务能力、运维能力，均不得再回灌到 `legacy_core`
+
+判断标准：
+
+- 若一个改动离开某个具体官方扩展包或具体业务 app 后仍然成立，才有资格评估是否进入 `legacy_core`
+- 若一个改动主要服务于某类 app、某类 provider、某类站点/平台场景，则必须进入官方扩展包
+- 不能证明“这是框架级公共边界”的改动，一律不得进入 `legacy_core`
+
+### 9.5 生产红线
+
+正式红线如下：
+
+- 不把 `warning + continue` 当作生产可接受语义
+- 不把 import-time 单例当作生产稳定边界
+- 不把 repo-root/cwd 猜测当作生产项目发现机制
+- 不把 debug/dev surface 当作默认公开能力
+- 不把“后续再补测试/文档/回滚”当作可接受交付
+
+## 10. 进入代码重构前的最终红线清单
+
+以下红线在进入代码重构前必须视为不可退让约束：
+
+1. 不允许再新增第二套真相源。
+2. 不允许 `startup()`、`lifespan`、adapter 层补编译逻辑。
+3. 不允许新增 import-time 全局单例或全局 setter 主链。
+4. 不允许继续依赖 repo-root、`cwd`、`ROOT_DIR`、包目录可写。
+5. 不允许 core 直接依赖具体官方维护最小子包 / 独立子包内部实现。
+6. 不允许独立子包被其它 app 直接 import 其内部模块。
+7. 不允许 middleware 继续走类路径去重、反射补参、后写覆盖。
+8. 不允许 system checks 出现第二套入口或第二套输出格式。
+9. 不允许 CLI / Web / worker 拥有不同生命周期语义和错误编码。
+10. 不允许 base 安装命令路径依赖可选基础设施或重型 extras。
+11. 不允许 warning-only 半初始化结果进入正式运行态。
+12. 不允许发布时缺失升级说明、回滚说明、版本范围说明。
+
+执行要求：
+
+- 任一红线被打破，都不应视为“局部可接受实现”
+- 必须先修架构问题，再继续上层功能开发
+
+## 附录 A. `legacy_core core` 边界总表
+
+### A.1 `legacy_core core` 的正式定位
+
+`legacy_core core` 的正式定位只有一个：
+
+- 标准框架内核与装配层
+
+它负责：
+
+- 定义正式契约
+- 编译运行计划
+- 组装正式运行边界
+- 提供标准入口
+
+它不负责：
+
+- 业务能力实现
+- 平台 app 具体实现
+- 具体第三方服务集成
+- 监控平台、任务平台、邮件平台本身
+
+进入 `core` 的唯一门槛：
+
+- 该内容在没有任何官方 app、独立子包、具体 provider、具体 middleware 实现时仍然成立
+- 该内容必须以契约、声明模型、纯规则或纯校验逻辑存在
+- 该内容不得依赖具体运行时副作用、具体目录真相源、具体 app/provider 名称
+
+### A.2 `legacy_core core` 正式提供什么
+
+- `ProjectContext`
+- `SettingsSnapshot`
+- `AppRegistry`
+- `RouteManifest`
+- `MiddlewareManifest`
+- `ResourceManifest`
+- `InfraSettings`
+- `InfraContext`
+- `CapabilityRegistry`
+- project context compiler
+- settings compiler
+- app registry compiler
+- route / middleware / resource compiler
+- infra snapshot compiler
+- `RuntimePlan` compiler
+- Web / CLI / worker 标准入口流水线
+- capability 激活与 shutdown 边界
+- facade / provider / adapter 的组装边界
+- `pz`
+- `pz.app`
+- system checks 正式入口
+
+补充约束：
+
+- 这里的“装配”只表示正式边界、声明模型和统一入口链，不表示具体 app mutation、startup 副作用、client 初始化
+- `core` 可以定义 route / middleware / resource / capability 的声明模型与校验规则，但不承载其具体实现
+- `ResourceManifest` 的正式公开结构应收敛到 `items + sources + manifest_path + output_root + staging_root + lock_path`
+
+### A.3 `legacy_core core` 明确不提供什么
+
+- 不提供业务 app
+- 不提供任何 app 具体实现
+- 不提供 shared site UI owner / settings runtime owner / task dispatch owner 这类平台 app 的具体实现
+- 不提供 PostgreSQL / MySQL / Redis / SMTP / S3 / GCS / exporter / bot handler 这类具体后端与共享实现
+- 不提供共享 middleware 的具体类
+- 不提供模板渲染、i18n、Jinja、静态资源服务的具体运行时实现
+- 不提供 `startup()` / `shutdown()` 的具体副作用
+- 不直接初始化 DB / Redis / mail / storage client
+- 不直接 mount static / uploads
+- 不直接注册 FastAPI 错误处理器、HTTP middleware 类、ASGI app mutation 流程
+- 不直接做资源 merge、迁移 merge、文件系统写入
+- 不提供 repo-root / `cwd` 驱动心智
+- 不提供 import-time 全局单例主链
+- 不提供第二套 settings / app / resource / infra 真相源
+- 不承载脚手架、debug/dev/ops surface、临时旧入口的长期正式落位
+
+### A.4 `legacy_core core` 与其它层的关系
+
+对 `infra`：
+
+- `core` 只消费 `InfraContext`、typed contract、capability 结果
+- `core` 不直接依赖 `infra` 的旧 manager / 默认 client / setter 主链
+
+对官方维护最小子包：
+
+- 官方维护最小子包是普通 app
+- `core` 不直接依赖某个具体官方 app 内部实现
+- `core` 只依赖 capability / facade / contract
+
+对独立子包：
+
+- `<app_id>` 是普通独立子包
+- `core` 不把独立子包当内部模块
+- 独立子包只通过正式边界接入运行图
+
+对 provider package / extras：
+
+- `core` 只定义 provider contract 与 binding 边界
+- 具体 provider 通过 extras 或独立 package 接入
+
+### A.5 `core` 内部统一原则
+
+`core` 必须保持为“纯规则和纯契约层”，不能再混成“框架剩余物收容站”。
+
+统一要求：
+
+- 同一文件若依赖具体 app、具体 provider、具体 middleware 类、具体目录真相源，就不应留在 `core`
+- 同一能力若既在 `core` 定义契约、又在 `core` 承载具体实现，必须拆分
+- `core` 中允许存在 FastAPI / CLI 相关的最小声明类型，但不允许存在具体装配副作用
+- `core` 中不允许再出现官方 app 内部模块路径、独立子包内部模块路径、具体 `legacy_core.infra.*` 实现路径作为正式依赖真相
+
+判断一个目录是否算“统一的 core”，只看三条：
+
+1. 是否不依赖具体 app 真相。
+2. 是否不依赖具体 infra/provider 真相。
+3. 是否不携带执行期副作用。
+
+三条任意一条不满足，就说明它不该留在 `core`。
+
+### A.6 `core/*` 的目标边界划分
+
+可以保留在 `core`：
+
+- `events`
+  - 只保留事件 contract、topic/handler 协议、纯内存/纯声明模型
+- `extensions`
+  - 只保留 extension declaration、registry contract
+- `routing`
+  - 只保留 route declaration、顺序规则、冲突校验、纯 registry model
+- `health`
+  - 只保留 health contract、result model、capability 聚合规则
+- `errors`
+  - 只保留错误 envelope、错误码、异常 contract
+
+应迁入 `assembly`：
+
+- `apps`
+  - app declaration、registry contract、替换规则、依赖校验规则与 compiler 归 `assembly/apps`
+- `settings`
+  - settings schema、settings compiler、app settings 编译、middleware/resource/app registry 编译
+- `middlewares`
+  - `MiddlewareDecl`、`MiddlewareManifest`、middleware compiler 与纯校验归 `assembly/middlewares`
+- `ops`
+  - 只要本质是预处理、编译、归并、校验、扫描，都归 `assembly`
+- `resources`
+  - 资源目录发现、merge 计划、manifest 编译归 `assembly`
+
+应迁入 `runtime`：
+
+- `app_factory`
+  - FastAPI app 创建、route/middleware/resource 装配、lifespan、startup/shutdown 流程
+- `deps`
+  - request/app.state/runtime helper
+- `health/router.py`
+  - readiness/liveness 的 HTTP 暴露
+- `errors/handlers.py`
+  - FastAPI/ASGI 错误处理器注册
+- `routing` 中直接操作 `FastAPI` 的部分
+
+应迁出到 app 层：
+
+- `middlewares`
+  - 具体 middleware 类全部迁出；共享实现进官方基础能力最小子包，app 专属实现进对应 app
+- `resources` 中依赖展示层、模板、静态服务的实现
+  - 迁到官方基础能力最小子包或对应 app
+
+应迁出到 `infra` 或 provider/app 层：
+
+- `storage`
+  - `core` 只保留 `StoragePort` 级 contract；具体 driver、provider 选择、S3/local 绑定迁出
+- 任何直接 import `legacy_core.infra.*` 具体实现的逻辑
+  - 一律改成 contract / facade / runtime helper
+
+`core` 最终保留的二级目录以 `01-目录与分层重构执行方案.md` 为准。
+
+补充约束：
+
+- `core/` 不设 `apps/` 子目录
+- `core/` 不再保留 `app_factory/`、`ops/`、`resources/`、`cli/`、`deps.py`、运行时 helper
+
+### A.7 `legacy_core core` 的最小完成定义
+
+当以下条件同时满足，才算 `legacy_core core` 边界成立：
+
+- base 安装可运行最小 app
+- `RuntimePlan` 成为唯一组合根
+- Web / CLI / worker 共用同一入口流水线
+- 官方 app / 独立子包都不再被当作 core 特权内容
+- DB / Redis / metrics / mail / storage 都作为可选 capability 表达
+- `core` 内不再直接依赖具体官方 app / 独立子包 / infra 实现路径
+- `core` 内不再保留具体 middleware、resource runtime、static mount、startup side effect