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/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203-/345/220/253/345/216/206/345/217/262/345/217/243/345/276/204.md

@@ -0,0 +1,671 @@
+# 包与分发规范
+
+> 历史说明：本文保留的 `legacy_core` 字样只用于描述迁移前分发方案、旧命令与禁用路径；当前正式基础包统一为 `pz`。
+
+> 本文统一服从最高优先级公约：系统里真正存在的正式单位，只有最小子包；`pz` 是负责组装的基础包；`pz_framework`、`pz_apps`、`pz_apps` 等顶层源码组织根只用于 Git 管理，不进入运行时 namespace。
+
+## 1. 目标
+
+`pz` 必须优先被设计为标准 Python 安装包，而不是“需要内嵌到业务仓库才能正常运行”的子目录。
+
+统一口径：
+- `pz` 作为一个标准 Python 包进行分发、安装与开发管理
+- settings surface owner 作为独立最小子包提供应用层 settings surface，物理源码落位由 owning 子包文档和仓库真相源地图维护
+- 除 `pz` 基础包外，其它正式能力统一分发为独立最小子包 distribution
+- 每个最小子包必须有稳定唯一的 `app_id`；新建子包默认让目录名、import 包名与 `app_id` 对齐，distribution 使用对应的 Python 分发名
+- 正式命名不强制 `pz`、`pz` 或其它特定技术前缀；历史稳定 `app_id` 以已声明值为准，不因文档命名口径变化迁移
+- 当前 `pz` 的开发、依赖锁定、命令执行、构建与测试统一使用 `uv` 管理
+- 对外分发与安装边界仍保持标准 `pip install` 模型
+
+## 2. 包层级
+
+范围：
+
+- 目录结构以 `01-目录与分层规范.md` 为准
+- 本文只定义分发语义、安装模型、稳定 import 面和 wheel 要求
+
+### 2.1 `legacy_core`
+
+主包负责：
+- core 装配
+- settings 载入与 app 命名空间挂载
+- CLI
+- 资源与迁移聚合
+- 可选 infra 集成
+
+主包不负责：
+- 内置具体业务站点
+- 强绑定任何默认业务 `app`
+- 将官方 app 当作内核特权对象
+
+### 2.2 官方最小子包
+
+官方维护的能力不再通过任何集合层 namespace 暴露，而是和业务能力一样，统一落成独立最小子包：
+
+- distribution：`<app_id with _ replaced by ->`
+- 目录名：`<app_id>`
+- import 包名：`<app_id>`
+- `app_id`：`<app_id>`
+
+例如：
+
+- `<settings_surface_owner_app_id>`
+- `<infra_owner_app_id>`
+- `<shared_site_ui_owner_app_id>`
+- `<auth_owner_app_id>`
+- `<seo_owner_app_id>`
+
+正式要求：
+
+- 官方能力与业务能力在运行时装配模型上完全平权
+- 任何官方能力都不得再以集合层 namespace 作为长期正式 import 面
+- `pz_contrib` 只视为 `pz_framework` 仓内的源码聚合容器，不是长期正式运行时单位
+- `pz_apps`、`pz_apps` 与 `pz_framework` 在目录层面并列，也都只是源码组织根
+
+### 2.3 外部 app / 独立子包
+
+外部 business app、第三方 app、独立 app 子包：
+- 均通过 `installed_apps` 进入系统
+- 与官方最小子包使用同一套 `apps.py` / `settings.py` / `migrations` 声明约定，以及同一套 `settings_center.settings` 读取约定
+- 可显式替换官方最小子包
+
+补充约束：
+
+- 独立子包在代码依赖规则上定义为 `integration app`
+- 其它 app 不允许直接 import 独立子包内部 Python 模块
+- 与独立子包的交互只允许通过稳定集成边界：
+  - capability
+  - facade
+  - events
+  - CLI/task 协议
+  - 必要时的 HTTP API
+
+- 官方最小子包和独立子包不是“两套装配模型”
+- 它们是“同一装配模型下的两种公开交互类型”
+- 但无论官方还是独立，长期正式的分发与 import 单位都只能是自己的 `<app_id>`
+
+## 3. 安装模式
+
+本章明确区分两类“依赖”：
+
+- 源码 / 分层依赖：谁的 Python 实现可以直接 import 谁、谁建立在谁的稳定合同之上。
+- distribution 安装依赖：为了给终端用户提供默认安装组合，某个 distribution 在 `pip install` 时顺带拉起哪些其它 distribution。
+
+正式要求：
+
+- 这两类依赖必须分开理解，不得混为“基础层可以直接依赖高层实现”的许可。
+- `pz-cli` 若作为公开安装 facade distribution 存在，只承担安装层职责：依赖基础包 `pz` 并暴露 `pz` 命令；它不是第二基础包，也不是新的运行时单位。
+- `pz-cli` 不得依赖 `pz[contrib]`、`pz-contrib` 或任何官方 / 业务最小子包；`pz` 命令本身只负责 launcher facade 与 provider 选择。
+- `pz` 在源码 / 分层意义上始终是基础层，不因为 extras 安装会带上官方扩展组合，就获得对 `pz_contrib` 或其子包内部实现的反向源码依赖权。
+- `pz-contrib` 作为官方扩展组合应通过 `pip install "pz[contrib]"` 这类 extras 安装口径显式拉起，而不是反向成为 `pz` 基础依赖。
+- 官方最小子包与业务最小子包对 `pz` 的源码依赖仍按正式分层管理；`pz` 代码不得直接 import `pz_contrib` 集合层或 contrib 子包内部实现。
+
+补充一条针对项目开发与发布的正式区分：
+
+- 开发形态允许把最小子包源码 checkout 到项目本地目录中联调
+- 发布形态不允许把“当前源码目录”直接视为正式发布物
+- 一旦进入发布链，正式交付单位仍然必须是带明确版本号的 distribution / artifact
+
+依赖正式分层为：
+
+- `legacy_core`
+  - 最小可运行基础，不要求 DB、Redis
+- `pz-cli`
+  - 公开安装 facade distribution
+  - 只依赖 `pz`
+  - 只暴露 `pz -> pz.pz_launcher:main`
+- `pz`
+  - 顶层正式 CLI 真相源与基础包
+- `pz-contrib`
+  - 官方扩展组合 distribution，用于通过 `pz[contrib]` 拉起 contrib 最小子包集合
+- `<app_id with _ replaced by ->`
+  - 单个最小子包的正式 distribution
+- `legacy_core[db]`
+  - ORM 与迁移基础
+- `legacy_core[db-postgres]`
+  - PostgreSQL 驱动
+- `legacy_core[db-mysql]`
+  - MySQL 驱动
+- `legacy_core[redis]`
+  - Redis 客户端
+- `legacy_core[observability]`
+  - 指标、追踪、日志增强
+- `legacy_core[full]`
+  - 拉起开发或测试所需的官方最小子包组合，但不改变“最小子包才是正式分发单位”的原则
+
+### 3.0 开发态源码拉取与发布态分发的边界
+
+为了支持项目内联调，`pz` 可以提供开发态源码拉取能力，例如把某个 `<app_id>` 的源码 checkout 到项目本地 `apps/` 容器中。
+
+但这只属于开发态：
+
+- 用于阅读源码
+- 用于本地修改
+- 用于项目内联调
+
+不属于发布态：
+
+- 不代表已完成版本化
+- 不代表可直接部署
+- 不代表可直接发布给其它环境消费
+
+正式要求：
+
+- 开发态源码拉取与发布态分发必须拆成两条命令链
+- “同步源码到本地”与“发布包”不得由同一命令隐式串联
+- 如果某个 app 只是被拉到本地开发目录，它仍然只是 source checkout，不是 release artifact
+
+### 3.0.1 开发态
+
+开发态的目标是把正式 app 源码带到项目边界内，便于修改和联调。
+
+规划中的上层命令语义应固定为：
+
+- `pz app add <app_id>`
+  - 把 app 加入当前项目声明
+  - 并把已发布 distribution 安装到当前项目的 Python / uv 环境
+  - 不把源码写入项目 `apps/`
+- `pz app init`
+  - 作为生产装配模型下的项目默认包初始化命令
+  - 只从已有 `apps/.sources` checkout 读取默认包名与内部 PyPI 安装位置
+  - 默认扫描 `.sources` 中所有正式最小 app 子包，写入 `installed_apps`
+  - 创建或复用项目根 `.venv`
+  - 默认把 `pz`、`pz-contrib` 与已发现正式最小 app 的已发布 distribution 安装到项目 `.venv`
+  - 安装必须走正式内部 PyPI / devpi `check_url`，不得回退到源码 `editable` 安装
+  - 默认安装位置来自 `.sources` 中各包最近 source-root 的 `tool.pz.publish.default_target` 与对应 `targets.<target>.check_url`；若默认包清单跨多个内部 PyPI / devpi index，`app init` 会把这些 index 去重后交给同一次安装解析
+  - 安装项使用 `.sources` 中各包 `pyproject.toml` 的 distribution 名，具体版本由内部 PyPI / devpi 与项目锁仓策略解析；`app init` 不把源码 checkout 的当前 version 当作生产安装 pin
+  - 按 source app 的 `requires_apps` 依赖关系写入 `installed_apps`
+  - 不 clone 源码，不发布 package，也不改变 `pz app add` 的发布包安装语义
+- `pz app rm <app_id>`
+  - 把 app 从当前项目声明中移除
+- `pz app update <app_id>`
+  - 对某个已声明 app 在当前项目解释器环境中重新安装或升级其已发布 distribution
+- `pz dev add <repo-or-app>`
+  - 默认拉取 `dev` 分支
+  - 可通过 `--branch <name>` 指定分支
+  - 只负责“远端到本地”的源码获取
+  - 若目标本身已是叶子最小子包 repo，则直接平铺暴露为 `apps/<app_id>/`
+  - 若输入定位到容器仓 / 容器目录，则项目层一次暴露该容器范围内全部已发现的最小子包，并保留原本组织目录
+  - 若目标 app 属于 monorepo 且输入只定位到某个叶子最小子包，则项目层仍按叶子最小子包处理，直接平铺暴露为 `apps/<app_id>/`
+- `pz dev update <app_id>`
+  - 只负责更新已有 checkout
+  - 不负责发布
+- `pz dev rm <app_id>`
+  - 只负责移除本地开发态 checkout
+  - 不负责发布
+  - 不负责远端删除
+
+开发态约束：
+
+- `app` 组命令只管理项目声明，不管理源码 checkout
+- `app init` 只消费已经存在的 `apps/.sources` checkout，用它确定默认包清单与内部 PyPI 位置；真正安装的是 distribution，不负责拉取源码
+- `app add` / `app update` 操作的是当前项目解释器环境中的 distribution 安装状态，不向 `apps/` 写源码
+- `app add` / `app update` 永远按 distribution 名称执行安装，不读取 `workspace_packages.toml`，也不回退到源码仓 `editable` 安装
+- `app rm` 只移除已声明 app；若目标 app 未声明，命令必须报错，不得返回误导性的成功提示
+- `app add` / `dev add` 完成后必须检查结果状态；若同名最小子包同时存在于 `apps/` 与当前解释器 `site-packages`，或在 `apps/` 内出现多个同名来源，命令直接报错，同时给出标准人工处理指引
+- 运行时发现阶段若项目本地 `apps/` 与当前解释器环境中已安装 distribution 同时都可导入同名最小子包，正式优先级固定为项目本地 `apps/` 最小子包优先
+- 叶子最小子包 repo 优先按“直接暴露目录”处理
+- `dev add` 进入 `apps/` 时，只有输入是容器目录 / source-root / monorepo 根时，才保留来源仓的组织目录；若输入本身就是叶子最小子包，则直接映射为 `apps/<app_id>/`
+- 同一 git 仓库若已因某个最小子包存在本地 checkout，后续同仓其它最小子包必须复用该 checkout
+- 不默认推送远端
+- 不自动 build
+- 不自动 publish
+- 不自动修改发布版本号
+
+### 3.0.2 发布态
+
+发布态的目标是输出可被其它环境稳定消费的正式分发物。
+
+因此正式要求：
+
+- 发布前必须存在明确版本号
+- 发布链消费的是版本化 package / wheel / artifact
+- 不允许把“本地 checkout 的当前目录状态”直接当作正式发布输入
+
+规划中的上层命令语义应固定为：
+
+- `pz pub <app_id>`
+  - 只进入构建与发布链
+  - 不承担源码拉取职责
+
+结论：
+
+- 项目声明层解决“项目要装哪些 app”
+- 开发态解决“源码到位 / 更新 / 移除”
+- 发布态解决“版本化交付”
+- 两者必须在设计上硬分离
+
+约束：
+- base 安装不应强依赖 `asyncpg`、`asyncmy`、`redis`
+- SQLite 不应要求额外第三方驱动
+- `legacy_core[full]` 通过 extras 显式拉起官方最小子包与必要独立子包，而不是把这些能力重新打包进 core wheel
+- 若需要安装官方 contrib 组合，正式命令应使用 `pip install "pz[contrib]"`；不得通过让 `pz` 基础包或 `pz-cli` 默认依赖 `pz-contrib` 来表达
+
+补充要求：
+- `aerich` 不应继续留在 base 依赖中
+- `boto3`、`fastapi-mail`、`prefect`、`stripe` 这类明显模块化依赖必须按能力拆到 extras，而不是全部放进 base
+- 包描述与元数据不应继续使用 “monorepo with uv workspace” 这一类仓库开发者心智作为对外说明
+
+后续实现必须按这组 extras 名称和轻量 base 目标收口。
+
+## 3.0 工具链约束
+
+重构后的 `legacy_core` 包在开发、锁定依赖、构建、测试执行层面统一采用 `uv` 管理。
+
+正式要求：
+
+- 新版 `legacy_core` 包必须提供标准 `pyproject.toml`
+- 开发环境统一通过 `pz env sync` 建立
+- 命令执行统一优先使用正式 `pz` CLI 或 `python -m ...`
+- 构建产物统一优先通过 `uv build` 产出
+- 依赖锁文件统一采用 `uv.lock`
+
+同时必须满足：
+
+- 对外分发仍是标准 wheel / sdist
+- 用户侧仍可通过标准 `pip install legacy_core` 安装
+- 运行时行为不能依赖 `uv workspace` 或 `uv` 私有运行时语义
+
+结论：
+
+- `uv` 是新版 `legacy_core` 的正式开发与构建工具链
+- 标准 `pip` 分发仍是正式对外交付边界
+
+## 3.1 官方最小子包与业务最小子包的正式分工
+
+正式要求：
+
+- 所有官方能力都必须落成独立最小子包 `<app_id>`
+- 所有业务能力也必须落成独立最小子包 `<app_id>`
+- 无论官方还是业务，进入系统的方式都只能是把对应最小子包写入 `installed_apps`
+- 不再保留“官方组合包有独立运行时 namespace、业务包走另一套 namespace”的双轨模型
+
+典型官方最小子包类别例如：
+
+- settings surface owner
+- infra owner
+- shared site UI owner
+- settings runtime owner
+- auth owner
+- account / profile owner
+- SEO owner
+
+## 3.2 非 app 型能力的拆分原则
+
+以下能力不应继续留在 core base 依赖或 core wheel 中：
+
+- observability handlers / exporters
+- mail sender integration
+- object storage / cloud backends
+- billing / stripe / external platform clients
+- 其它与外部服务强绑定的 provider 实现
+
+正式要求：
+
+- 若它们需要作为官方默认实现存在，统一进入某个官方最小子包，例如 official infra owner
+- 若它们需要独立治理，则进入自己的最小子包 `<app_id>/`
+- 不再引入第三套 `bundles/`、`providers/`、官方重型分发目录概念
+
+- core wheel 只保留框架内核、最小装配能力、middleware manifest/compiler/adapter glue、标准 CLI
+- 官方能力与业务能力都统一进入各自的 `<app_id>/`
+- 用户安装体验通过 extras、顶层 CLI 包和独立最小子包解决，而不是把实现重新打进 core wheel
+
+### 3.2.4 源码目录落位
+
+目录边界必须和分发边界一致，不能只在 wheel 构建时排除文件：
+
+- 仓库根 `legacy_core/` 只保留 core 代码与标准安装包入口
+- 每个最小子包都必须拥有自己的源码根：
+  - `<app_id>/`
+- 每个最小子包内部的正式 Python 包目录也必须叫：
+  - `<app_id>/`
+- 正式 import path 固定为最小子包自己的包名 `<app_id>`
+- `legacy_core/infra/*` 只保留薄绑定层，不再作为具体实现的长期源码真相源
+- `infra` 的具体实现统一进入对应最小子包，例如 official infra owner
+
+若采用当前工作区的 Git 聚合布局，上述目录实际落位固定为：
+
+- `<some_group_dir>/<app_id>/`
+- 或 `<repo_root>/<app_id>/`
+
+补充禁止：
+
+- 不得在 `legacy_core` 核心仓内新增新的业务或官方能力源码
+- 不得把任何最小子包重新塞回 `legacy_core` core wheel
+
+official infra owner 的完整目录结构以 `01-目录与分层规范.md` 为准。
+
+约束：
+
+- `db/`、`kv/`、`storage/`、`observability/`、`notifications/`、`middlewares/` 只承接默认实现
+- `public.py` 的正式导出面以 `16-正式Facade总表.md` 为准
+- `i18n/`、`jinja/` 不进入 infra owner，而进入对应展示层最小子包，例如 shared site UI owner
+
+### 3.2.5 最小子包 import path 契约
+
+由于正式运行时单位已经统一收敛为最小子包，因此 import path 契约也必须收敛为最小子包自己的包名。
+
+正式要求：
+
+- 每个最小子包的正式 import path 固定为 `<app_id>`
+- 官方能力与业务能力都不得复用集合层 import path
+- 模板、资源、app 发现若需要定位某个能力源码，必须从对应最小子包或正式包资源读取，而不是反推旧集合目录
+- 文档、测试、构建脚本都不得再把集合层目录名当成正式源码真相源
+
+禁止：
+
+- 独立子包复用集合层路径伪装成正式运行单元
+- 通过 build `force-include` 把同一套根目录源码同时喂给 `legacy_core/` 与多个集合层壳
+- 通过固定相对路径反推旧集合层 app 根目录
+
+边界：
+
+- 最小子包自己的 import path 才是稳定契约
+- 集合层目录不是正式边界，也不是正式公开面
+
+### 3.2.6 最小子包的 wheel / package 契约
+
+既然正式运行时单位已经统一为最小子包，则 wheel 与 package 契约也必须直接对应最小子包本身，而不是再经过集合层 namespace。
+
+正式方案：
+
+- 不采用 namespace package
+- `legacy_core` 主包继续保持普通 package
+- 每个最小子包 wheel 只负责产出自己的 `<app_id>/**` 包树
+
+正式要求：
+
+- `<app_id>` 必须通过正式 wheel 布局直接成立，而不是依赖集合层目录偶然同构
+- `legacy_core` core wheel 不产出任何业务或官方能力型包树
+- 每个最小子包 wheel 必须只产出：
+  - `<app_id>/__init__.py`
+  - `<app_id>/**`
+- 构建脚本不得依赖 `PYTHONPATH` 注入、repo-root 相对路径或手工复制目录来让集合层 namespace 成立
+- 每个最小子包安装后，必须稳定提供自己的 `<app_id>`
+- 同一 `app_id` 只允许由一个 wheel 提供
+
+实现约束：
+
+- `legacy_core/__init__.py` 保持普通包语义，不改造成 namespace package
+- 每个最小子包都必须在自己的 wheel 内显式写出 `<app_id>/**`
+- 文档、脚本、测试都不得假定“源码在集合层目录里，安装后自然就能 import 某个集合层 namespace”
+- core wheel 与最小子包 wheel 不得同时提供同一路径文件
+- 若未来继续拆包，各 wheel 的写入子树必须按 `<app_id>/` 严格互斥
+
+禁止：
+
+- 依赖源码 checkout 目录运行来证明集合层 import path 可用
+- 依赖 `sys.path` 注入、editable 模式特例或 vendored 目录结构来补齐集合层 namespace
+- 让独立子包通过复制旧集合层目录结构伪装成官方组合包成员
+- 在 core wheel 中放置空壳集合层包，再要求其它 wheel 覆写同一文件
+
+交付要求：
+
+- 明确记录 `legacy_core` 主包只产出 `legacy_core/**`
+- 明确记录每个最小子包 wheel 只产出自己的 `<app_id>/**`
+- 安装后 import contract 必须由契约测试证明，而不是由 README 示例间接证明
+
+## 3.3 `infra` 分发与目录收口
+
+`infra` 在新方案里保留，但必须显著瘦身。
+
+正式要求：
+
+- `infra` 只保留最小基础设施 contract、typed snapshot、adapter interface、capability binder
+- 不再把共享 middleware、平台 app provider、站点运行时、第三方集成实现统统留在 `infra`
+
+迁出原则固定为：
+
+- 共享但非核心 middleware
+  - 进入官方基础能力最小子包，例如 official infra owner
+- shared site UI owner / 展示层 / i18n / template runtime
+  - 若属于基础能力实现，进入 official infra owner；若已明确属于展示层，再进入 shared site UI owner
+- settings runtime owner / task dispatch owner 专属 provider 与 registry
+  - 进入对应 settings runtime owner 或 task dispatch / worker owner
+- SMTP、S3/GCS、bot handlers、支付/外部云客户端
+  - 进入官方基础能力最小子包或 extras；成熟后再拆成独立最小子包
+
+这条规则的目标是保证 core wheel 足够轻，并阻止 `legacy_core.infra.*` 继续膨胀成事实上的第二公共 API 面。
+
+## 4. 入口规范
+
+### 4.1 标准入口
+
+唯一标准入口：
+- `pz`
+
+通过 `console_scripts` 提供：
+
+```toml
+[project.scripts]
+pz = "pz.cli:main"
+pz = "pz.pz_launcher:main"
+```
+
+补充要求：
+- `pyproject.toml` 必须显式声明该入口，不再只依赖目录执行
+- 所有正式脚本必须直接落到同一个 CLI 真相源；不允许再引入额外 wrapper / shim 同步链
+- 所有用户文档、README、示例命令、帮助文案只使用 `pz ...`
+- `pyproject.toml` 中实际声明的 extras 名称应与文档约定一致，避免出现 `infra-db`/`infra-kv` 这类实现名与用户心智名并存
+- `python -m pz` 若保留，也只作为技术入口复用同一正式 CLI 真相源，不作为需要单独维护的第二套文档主路径
+
+入口、元数据、extras 命名都必须按本规范收口。
+
+### 4.2 非标准入口
+
+以下路径不再视为正式入口：
+
+- `python legacy_core`
+- wrapper
+- `legacy_core init`
+
+约束：
+- `legacy_core init` 不再作为框架安装/初始化主路径
+- 历史 `git_plugins` 不再作为正式入口，且不能默认扫描安装包内目录
+- 历史 `run` 不再作为正式命令，不再出现在主帮助文案与正式教程中
+- 历史 `python legacy_core` 目录执行、vendored/symlink 目录执行，不再作为正式安装包心智
+
+旧命令处理规则：
+
+- `git_plugins` 在本次重构中直接移除，且不得默认扫描安装包内 `legacy_core/plugins`
+- `init` 在本次重构中直接移除，不承担 shell rc / wrapper / `PYTHONPATH` 写入职责
+- `run` 在本次重构中直接移除，不保留独立命令模型
+
+`init` / `git_plugins` 不再作为 vendored 仓库运行模型的正式入口。
+
+### 4.3 项目上下文发现
+
+CLI 查找项目上下文固定遵循以下优先级：
+
+1. `--project-dir`
+2. `PZ_PROJECT_DIR`
+3. 当前目录向上搜索项目标记文件
+
+项目标记文件唯一采用：
+- `pz.jsonc`
+
+不得再默认假设：
+- 当前目录必定是项目根
+- 项目根下一定存在 `legacy_core/`
+- 项目根下一定存在 `app/`
+
+## 5. 项目配置文件
+
+正式项目配置文件唯一采用：
+
+- `pz.jsonc`
+
+正式规则：
+- 结构化配置放 TOML
+- 敏感值与环境差异通过环境变量覆盖
+- `.env` 仅作为开发便捷手段，不再承载全部系统配置
+
+## 6. 默认 app 策略
+
+主包不应默认内置业务 `app`。
+
+正式规则：
+- `installed_apps` 默认为空列表
+- 项目通过 `pz.jsonc` 显式声明需要的 app
+
+不采用：
+- 在框架默认设置中直接硬编码业务 `app`
+- 把大量官方 app 与业务 app 混在框架默认装载清单中
+
+## 7. wheel / 安装要求
+
+必须保证：
+- 安装后可在 `site-packages` 中正常运行
+- 包目录可视为只读
+- 运行时不会尝试写回 `site-packages` 或源包目录
+
+还必须保证：
+- 构建产物不依赖 uv workspace 语义才能被普通 `pip install` 使用
+- wheel 安装后不需要额外执行 `legacy_core init` 才能得到标准命令入口
+- CLI 与迁移工具不会假设存在可写的 repo-root `legacy_core/merged`
+- CLI 不通过修改 `PYTHONPATH` 或扫描包内 git 仓目录来弥补项目边界不清晰
+
+### 7.1 wheel 内容要求
+
+wheel 中必须包含运行所需非 Python 资源：
+
+- `templates/`
+- `static/`
+- `locales/`
+- `migrations/`
+- `configs/`
+
+否则标准安装包场景无法成立。
+
+补充要求：
+- 除了“资源在 wheel 内存在”，还必须保证：
+  - 这些资源不会要求运行时写回同目录
+  - asset builder / migrations merge / templates merge 的输出目录都在外部
+- 包内历史辅助目录若仅作为源码仓组织手段，不应被 CLI 当项目工作目录默认扫描
+
+### 7.2 extras 分层要求
+
+最终目标不是“一个超大全依赖包”，而是：
+
+- base 仅包含最小运行所需
+- DB 驱动独立 extra
+- Redis 独立 extra
+- 观测独立 extra
+- 官方完整组合通过 `full` 提供
+
+不在本阶段目标内：
+- zipimport/zip-safe 运行
+
+## 8. 公共 API 与导入边界
+
+从分发与长期维护角度，包化之后必须明确哪些 import path 可以被外部项目依赖。
+
+稳定公共 import 面唯一采用：
+
+- `pz`
+- `pz.app`
+- 文档中声明的 `public.py`
+
+默认不承诺稳定的 import 面：
+
+- `legacy_core.settings`
+- `legacy_core.core.*`
+- `legacy_core.infra.*`
+- 官方 app / 独立子包的内部实现模块
+- 任意旧入口
+
+要求：
+
+- 文档和代码层都必须把公共 API 收口到少量稳定入口
+- 如果外部项目确需依赖某能力，应先把它提升到 `public.py`，而不是继续扩散多种公共入口样式
+- `legacy_core.settings` 只作为包根入口文件存在，不视为正式稳定公共读取入口
+
+### 8.1 公共导出面的唯一方案
+
+为了落实“一个问题只有一种解决方案”，公共导出面必须显式唯一化。
+
+正式要求：
+
+- core 的稳定公共入口只允许：
+  - `pz`
+  - `pz.app`
+- app 的稳定公共入口只允许：
+  - `<app>.public`
+
+不再把以下路径当作外部稳定导出候选：
+
+- `api.py`
+- `ports.py`
+- `sdk/`
+- `service.py`
+- `manager.py`
+
+这些模块若存在，只能服务于内部实现拆分，不构成跨包稳定契约。
+
+结论：
+
+- 外部项目依赖能力时，只能依赖 `public.py`
+- 文档、示例、README、测试都不得再宣传第二套公共入口样式
+
+## 9. 构建与发布要求
+
+从最佳工程实践看，标准 pip 包除了“能装”，还要“可重复、可诊断、可升级”。
+
+要求：
+
+- 同时支持构建 wheel 与 sdist
+- wheel 内容应可由 CI 自动校验，而不是只靠本地人工验证
+- 非 Python 资源应通过正式包数据机制打包，并通过 `importlib.resources` 读取，而不是依赖源码相对路径
+- 发布元数据要围绕最终安装者，而不是围绕 monorepo 开发者
+- extras 的命名、说明、依赖集合必须在文档和 `pyproject.toml` 中保持一致
+
+发布前必须自动验证：
+
+- 发布前自动验证：
+  - wheel 内容
+  - `console_scripts`
+  - extras 依赖解析
+  - 非源码目录 smoke run
+
+## 10. 版本治理
+
+重构后的 `legacy_core` 需要有明确的版本治理策略。
+
+要求：
+
+- 稳定公共契约的破坏性变更只能通过主版本引入
+- 本次重构移除的旧入口需要在发布说明中明确列出
+- 迁移期聚合容器拆分后，其版本关系应能回溯到 core 版本范围
+
+正式规则：
+
+- `required_pz` 继续作为 app 级版本约束
+- `legacy_core` 发布后进入 core freeze / extension-first 治理
+- 新增业务能力、平台能力、provider 实现、共享 middleware，默认通过官方扩展包发布，而不是继续并入 `legacy_core`
+- 官方扩展包必须直接表现为最小子包 `<app_id>`；它们都属于扩展层，不属于 `legacy_core` 内核
+- 发布说明中维护：
+  - 本版本新增的正式契约
+  - 本次重构直接移除的旧入口
+
+## 11. 外部 app / 独立子包信任模型
+
+从实用角度必须说清楚一点：
+
+- 外部 app / 独立子包本质上是可执行 Python 代码
+- `installed_apps` 不是“安全沙箱”
+- 框架不应暗示“安装第三方 app 就是安全的”
+
+要求：
+
+- 文档中明确：外部 app 的引入属于受信代码接入
+- `legacy_core` core 不承担第三方 app 的安全审计职责
+- 若未来引入 app 元数据校验，也只解决版本约束与诊断，不等于安全隔离
+
+正式要求：
+
+- 项目侧维护允许装载的 app 白名单/供应源策略
+- 第三方 app 至少声明：
+  - 版本
+  - `required_pz`
+  - 公开 API 面
+  - 迁移/数据影响面