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

@@ -0,0 +1,403 @@
+# 包与分发规范
+
+> 本文统一服从最高优先级公约：系统里真正存在的正式单位只有最小子包；`pz` 是负责稳定合同、发现、编译、组装与启动的基础包；顶层源码组织根只用于 Git 管理，不进入运行时 namespace。
+
+## 1. 目标
+
+`pz` 必须作为标准 Python 安装包分发、安装与运行，而不是需要嵌入业务仓库才能工作的子目录。
+
+统一口径：
+
+- `pz` 是唯一正式基础包，也是唯一可独立启动的包。
+- `pz` 的开发、依赖锁定、命令执行、构建与测试统一使用 `uv` 管理。
+- 对外分发与安装边界保持标准 `pip install` / wheel / sdist 模型。
+- 除 `pz` 基础包外，其它正式能力统一分发为独立最小子包 `<distribution-name>`。
+- 每个最小子包的目录名、import 包名、`app_id` 统一为 `<app_id>`。
+- 最小子包必须有稳定唯一的身份；新建子包默认让目录名、import 包名与 `app_id` 对齐，但不强制特定技术前缀。
+- 历史子包已发布的 `app_id` 与 import 包名以稳定值为准，不因文档命名口径变化自动迁移。
+
+## 2. 包层级
+
+本文只定义分发语义、安装模型、稳定 import 面和 wheel 要求。目录结构以 `01-目录与分层规范.md` 为准。
+
+正式 distribution 层级：
+
+- `pz-cli`
+  - `pz` 基础能力的唯一正式 distribution，版本从 `5.0.0` 开始。
+  - 一个 wheel 同时包含 `pz_core`、`pz_settings_center` 与 `pz_foundation` Python 包，并暴露 `pz` 命令。
+  - 源码分层保持独立，但不再分别构建 `pz-core`、`pz-settings-center`、`pz-foundation` 或 `pz-contrib` wheel。
+- `<distribution-name>`
+  - 单个最小子包的正式 distribution。
+  - 安装后提供唯一 import 包 `<app_id>`。
+
+## 3. 安装模型
+
+必须区分两类依赖：
+
+- 源码 / 分层依赖：谁的 Python 实现可以直接 import 谁，谁建立在谁的稳定合同之上。
+- distribution 安装依赖：为了给用户提供安装组合，某个 distribution 在 `pip install` 时拉起哪些其它 distribution。
+
+正式要求：
+
+- `pz_core` 在源码 / 分层意义上始终是基础层，不得直接 import 官方或业务 app 的内部实现。
+- `pip install pz-cli==5.0.0` 安装一个 wheel，并提供 `pz_core`、`pz_settings_center`、`pz_foundation` 与 `pz` console script。
+- `pz-cli` 不会自动安装 `pz_apps` 仓中的业务子包；这些最小子包仍是独立 distribution。
+- 旧 `pz-core`、`pz-settings-center`、`pz-foundation`、`pz-contrib` distribution 已退出正式发布图，旧环境必须重建或迁移。
+- 官方最小子包与业务最小子包对 `pz` 的源码依赖按正式分层管理。
+- 默认安装组合不得被解释为基础层可以反向依赖扩展层实现。
+
+## 4. 开发态与发布态
+
+开发态允许把最小子包源码导入业务仓，或把上游 checkout 链接到项目中联调。发布态的正式交付单位必须是带明确版本号的 distribution / artifact。
+
+正式要求：
+
+- 开发态源码拉取与发布态分发必须是两条命令链。
+- 同步源码到本地与发布包不得由同一命令隐式串联。
+- 本地业务源码或 linked checkout 不代表已完成版本化，也不代表可直接部署。
+- 发布链消费版本化 package / wheel / artifact。
+
+项目开发与发布的上层命令语义以 `09-CLI与Worker入口规范.md` 和 `15-子包开发使用手册.md` 为准。
+
+开发态源码发现的正式口径：
+
+- 项目 `installed_apps` 配置条目为 `apps` 时，`apps` 表示扫描目录；运行时只发现 `apps/` 下业务仓真实本地 app 与经过 manifest 校验的可见 binding，物理 `apps/.sources/` 不直接贡献 app。
+- `apps` 只是默认项目配置里的扫描目录条目，不是运行时硬编码入口；项目显式改写 `installed_apps` 时，运行时按改写后的配置展开。
+- `pz dev add <app-or-source>` 编排 `dev source cache` 与 `dev source import`：默认从 `develop` 分支获取源码，先复用并更新当前用户隔离的 `<system-temp>/pz/users/<user-key>/git/<repo_key>` cache，cache miss 才 staged clone；cache root、lock、checkout、owner marker 与 remote identity 都必须验证。cache 以 canonical `repo_key`、full commit 与不可变 resolution ref 交接，import 必须验证该精确 revision，不读取 branch 或 `HEAD`。随后把一个正式最小子包、项目 source mode、provenance 和宿主 dependency/`tool.uv.sources` 作为一个事务原子导入 `apps/<app_id>`。导入结果不包含嵌套 `.git`，其源码由业务仓统一管理；Git provenance 保存 canonical source、exact revision 与 subpath，本地目录 provenance 只保存 `source = "local"`、不可逆 source identity 与 subpath，不保存绝对路径。
+- system-temp Git cache 只作可丢弃获取优化，不参与运行时、项目 binding、发布或源码优先级；cache 更新失败不得静默使用旧 revision。
+- `pz dev init --link --clone-sources`、`pz dev init --link --source-dir <path>` 与 `pz dev link` 将需要保留上游 Git 生命周期的 checkout 固定放在 `apps/.sources/<repo_key>`，并在 `apps/` 下建立项目 binding；默认 `pz dev init` 则导入官方 `pz_apps` 的全部正式最小叶子，不保留 checkout。链接目录时暴露目录，链接单个子包时只暴露该子包，不生成额外 wrapper 源码树。
+- `pz dev unlink` 只移除 linked binding；业务仓拥有的 `apps/<app_id>` 由业务 Git 工作流删除或回退，PZ 不把它当作可删除缓存。
+- `pz dev add/link/branch/update/unlink` 是作者面编排命令；源码事务由 `pz dev source ...` 原子命令拥有，PyCharm/VS Code 投影由 `pz dev ide sync` 原子命令统一拥有，settings 与环境继续复用既有原子命令。
+- `.idea/pz.generated.sources.iml` 为 PyCharm 登记精确 roots；`.vscode/settings.json` 中的 PZ-owned `python.analysis.extraPaths` 为 VS Code 登记项目可见叶子路径。两者都不复制源码、不参与运行时发现、editable 依赖解析、打包或发布，也不登记整个 `.sources` checkout。
+- 若源码扫描范围和当前解释器 `site-packages` 中同时存在同一 `app_id`，源码优先；环境 distribution 只是没有本地源码时的可导入来源。
+- 若项目源码扫描范围内出现多个同名 `app_id` 来源，作者面命令必须要求人工收敛，不能用环境包或路径顺序静默裁决。
+- 开发态运行时只把已装载 app 的 import root 及其本地 path 依赖 import root 纳入 `SettingsSnapshot.import_roots`；本地 path 依赖来自该包依赖声明与最近 source-root `[tool.uv.sources]` 的匹配结果，并递归展开。
+- 不允许因为某个 source-root 被扫描，就把同一 source-root 下所有未声明依赖的包一并加入运行时 import path；可选能力必须仍由拥有者包的正式依赖或惰性扩展入口表达。
+
+## 5. 开发工具链
+
+`pz` 包在开发、锁定依赖、构建、测试执行层面统一采用 `uv` 管理。
+
+正式要求：
+
+- `pz` 必须提供标准 `pyproject.toml`。
+- 开发环境统一通过 `pz env sync` 建立。
+- 命令执行统一优先使用正式 `pz` CLI 或 `python -m pz_core`。
+- 构建产物统一优先通过 `uv build` 产出。
+- 依赖锁文件统一采用 `uv.lock`。
+
+同时必须满足：
+
+- 对外分发仍是标准 wheel / sdist。
+- 用户侧可通过标准 `pip install pz-cli` 安装最小完整命令能力。
+- 运行时行为不能依赖 `uv workspace` 或 `uv` 私有运行时语义。
+
+## 6. 官方最小子包
+
+官方维护的能力和业务能力一样，统一落成独立最小子包：
+
+- distribution：`<distribution-name>`
+- 目录名：`<app_id>`
+- import 包名：`<app_id>`
+- `app_id`：`<app_id>`
+
+正式要求：
+
+- 官方能力与业务能力在运行时装配模型上完全平权。
+- 官方能力不得以集合层 namespace 作为长期正式 import 面。
+- `pz_contrib` 只视为 `pz` 仓内的源码聚合容器，不是运行时单位。
+- `pz_apps` 与 `pz` 都只是源码组织根。
+
+典型官方最小子包类别包括：
+
+- settings surface owner
+- infra owner
+- shared site UI owner
+- settings runtime owner
+- auth owner
+- account / profile owner
+- SEO owner
+
+## 7. 独立子包
+
+外部 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。
+- 官方最小子包和独立子包不是两套装配模型，而是同一装配模型下的两种公开交互类型。
+
+## 8. 非 app 型能力拆分
+
+以下能力不应留在 `pz` base 依赖或 base wheel 中：
+
+- observability handlers / exporters
+- mail sender integration
+- object storage / cloud backends
+- billing / stripe / external platform clients
+- 其它与外部服务强绑定的 provider 实现
+
+正式要求：
+
+- 若它们需要作为官方默认实现存在，统一进入某个官方最小子包，例如 official infra owner。
+- 若它们需要独立治理，则进入自己的最小子包 `<app_id>/`。
+- 不引入第三套 `bundles/`、`providers/`、官方重型分发目录概念。
+- base wheel 只保留基础包、最小装配能力、manifest/compiler/adapter glue、标准 CLI。
+
+## 9. 源码目录与分发边界
+
+目录边界必须和分发边界一致，不能只在 wheel 构建时排除文件。
+
+正式要求：
+
+- `pz/` 只保留基础包代码与标准安装包入口。
+- 每个最小子包都必须拥有自己的源码根 `<app_id>/`。
+- 每个最小子包内部的正式 Python 包目录也必须叫 `<app_id>/`。
+- 正式 import path 固定为最小子包自己的包名 `<app_id>`。
+- `pz/infra` 只保留薄绑定层，不作为具体实现的长期源码真相源。
+- `infra` 的具体实现统一进入对应最小子包，例如 official infra owner。
+
+补充禁止：
+
+- 不得在 `pz` 基础包内新增业务或官方能力源码。
+- 不得把任何最小子包重新塞回 `pz` base wheel。
+- 不得通过 build `force-include` 把同一套源码同时喂给基础包与多个集合层壳。
+- 不得通过固定相对路径反推旧集合层 app 根目录。
+
+official infra owner 的完整目录结构以 `01-目录与分层规范.md` 为准；`public.py` 的正式导出面以 `13-正式Facade总表.md` 为准。
+
+## 10. 最小子包 wheel 契约
+
+正式方案：
+
+- 不采用 namespace package。
+- `pz` 基础包保持普通 package。
+- 每个最小子包 wheel 只负责产出自己的 `<app_id>/**` 包树。
+
+正式要求：
+
+- `<app_id>` 必须通过正式 wheel 布局直接成立。
+- `pz` base wheel 不产出任何业务或官方能力型包树。
+- 每个最小子包 wheel 必须只产出自己的 `<app_id>/__init__.py` 与 `<app_id>/**`。
+- 构建脚本不得依赖 `PYTHONPATH` 注入、repo-root 相对路径或手工复制目录来让集合层 namespace 成立。
+- 同一 `app_id` 只允许由一个 wheel 提供。
+- core wheel 与最小子包 wheel 不得同时提供同一路径文件。
+
+禁止：
+
+- 依赖源码 checkout 目录运行来证明集合层 import path 可用。
+- 依赖 `sys.path` 注入、editable 模式特例或 vendored 目录结构补齐集合层 namespace。
+- 让独立子包通过复制集合层目录结构伪装成官方组合包成员。
+- 在 base wheel 中放置空壳集合层包，再要求其它 wheel 覆写同一文件。
+
+## 11. 入口规范
+
+正式入口：
+
+- `pz`
+- `python -m pz_core`
+
+`pz-cli` distribution 通过 `console_scripts` 提供：
+
+```toml
+[project.scripts]
+pz = "pz_core.pz_launcher:main"
+```
+
+正式要求：
+
+- `pyproject.toml` 必须显式声明入口，不依赖目录执行。
+- 所有正式脚本必须直接落到同一个 CLI 真相源。
+- 所有用户文档、README、示例命令、帮助文案优先使用 `pz ...`。
+- `python -m pz_core` 只作为技术入口复用同一正式 CLI 真相源，不作为第二套主路径。
+- extras 命名与 `pyproject.toml` 中实际声明保持一致。
+
+非正式入口不得出现在主帮助文案与正式教程中。
+
+## 12. 项目上下文发现
+
+CLI 查找项目上下文固定遵循以下优先级：
+
+1. `--project-dir`
+2. `PZ_PROJECT_DIR`
+3. 当前目录向上搜索项目标记文件
+
+项目标记文件唯一采用：
+
+- `pz.jsonc`
+
+不得默认假设：
+
+- 当前目录必定是项目根。
+- 项目根下一定存在 `app/`。
+- 项目根下一定存在源码 checkout。
+
+## 13. 项目配置文件
+
+正式项目配置文件：
+
+- `pz.jsonc`
+- `pz.{PZ_ENV}.jsonc`
+
+正式规则：
+
+- 结构化配置放 JSONC。
+- 敏感值与环境差异通过 `.env` / `.env.{PZ_ENV}` 或环境变量覆盖。
+- `.env` 主要承载敏感值与开发便捷覆盖，不承载全部系统配置。
+- app 私有配置统一进入其 `app_id` namespace。
+
+## 14. 默认 app 策略
+
+`pz` base 不默认内置业务 app。
+
+正式规则：
+
+- `installed_apps` 默认为空列表或由项目模板显式生成。
+- 项目通过 `pz.jsonc` 显式声明需要的 app。
+- 官方扩展组合由项目安装和 `installed_apps` 显式表达。
+
+不采用：
+
+- 在基础包默认设置中硬编码业务 `app`。
+- 把大量官方 app 与业务 app 混在基础包默认装载清单中。
+
+## 15. wheel / 安装要求
+
+必须保证：
+
+- 安装后可在 `site-packages` 中正常运行。
+- 包目录可视为只读。
+- 运行时不会尝试写回 `site-packages` 或源包目录。
+- 构建产物不依赖 uv workspace 语义才能被普通 `pip install` 使用。
+- wheel 安装后不需要额外执行初始化命令才能得到标准 CLI 入口。
+- CLI 与迁移工具不会假设存在可写的 repo-root 合并目录。
+- CLI 不通过修改 `PYTHONPATH` 或扫描包内 git 仓目录弥补项目边界不清晰。
+
+wheel 中必须包含运行所需非 Python 资源：
+
+- `templates/`
+- `static/`
+- `locales/`
+- `migrations/`
+- `configs/`
+
+补充要求：
+
+- 资源不会要求运行时写回同目录。
+- asset build / migrations merge / templates merge 的输出目录都在外部 runtime/cache 目录。
+- 包内源码组织目录不得被 CLI 当项目工作目录默认扫描。
+
+## 16. extras 分层
+
+目标不是一个超大全依赖包，而是轻量 base 加显式能力组合。
+
+正式要求：
+
+- base 仅包含最小运行所需。
+- DB 驱动独立 extra。
+- Redis 独立 extra。
+- 观测能力独立 extra。
+- 官方完整组合通过 `contrib` 或 `full` 类 extra 显式提供。
+- SQLite 不要求额外第三方驱动。
+- `aerich`、`asyncpg`、`asyncmy`、`redis`、`boto3`、`fastapi-mail`、`prefect`、`stripe` 等模块化依赖不得进入 base。
+
+不在正式默认目标内：
+
+- zipimport / zip-safe 运行。
+
+## 17. 公共 API 与导入边界
+
+稳定公共 import 面：
+
+- `pz`
+- `pz.app`
+- 文档中声明的 `<app>.public`
+
+默认不承诺稳定的 import 面：
+
+- `pz.runtime.*`
+- `pz.assembly.*`
+- `pz.core.*`
+- `pz.infra.*`
+- 官方 app / 独立子包的内部实现模块。
+- 任意未在文档中声明为 stable 的路径。
+
+正式要求：
+
+- 文档和代码层都必须把公共 API 收口到少量稳定入口。
+- 如果外部项目确需依赖某能力，应先把它提升到 `public.py`，而不是扩散多种公共入口样式。
+- app 的稳定公共入口只允许 `<app>.public`。
+
+不再把以下路径当作外部稳定导出候选：
+
+- `api.py`
+- `ports.py`
+- `sdk/`
+- `service.py`
+- `manager.py`
+
+这些模块若存在，只能服务于内部实现拆分，不构成跨包稳定契约。
+
+## 18. 构建与发布
+
+要求：
+
+- 同时支持构建 wheel 与 sdist。
+- wheel 内容应由 CI 自动校验。
+- 非 Python 资源通过正式包数据机制打包，并通过 `importlib.resources` 读取。
+- 发布元数据围绕最终安装者，而不是围绕 monorepo 开发者。
+- extras 的命名、说明、依赖集合必须在文档和 `pyproject.toml` 中保持一致。
+
+发布前必须自动验证：
+
+- wheel 内容。
+- `console_scripts`。
+- extras 依赖解析。
+- 非源码目录 smoke run。
+- base-only 安装 smoke。
+- 最小子包 wheel import contract。
+
+## 19. 版本治理
+
+正式规则：
+
+- 一个 Git 仓库可以承载多个最小子包，但发布、版本、release commit、tag 与 distribution 的正式单位始终是单个最小子包。
+- 每个最小子包自己的 `[project].version` 是该 distribution 的唯一 release version 真相源；仓库根版本不得覆盖叶子版本。
+- 同仓最小子包共享 Git 历史但拥有独立 distribution 版本与发布生命周期；独立版本不要求拆分 Git 仓库。
+- `pz app add/update` 未指定 `--version` 时解析正式 index 中最新兼容稳定版，指定时只接受一个精确 PEP 440 版本；两条路径最终都写入 exact project pin 与 `uv.lock`，不得持久化浮动 `latest`。
+- `pz app versions <app_id>` 是查看 available/latest/declared/locked/installed 版本的只读原子命令。
+- `pz pub <app_id>` 是单包发布编排命令，固定组合 package-scoped commit、annotated package tag 与 build/upload 原子能力。
+- 发布解析优先接受 `project_dir` Git root 中根 distribution 的精确匹配，否则枚举 `apps/.sources` 并复用正式 workspace 子包发现程序；不得另建扫描协议或回退发布 `apps/<app_id>` 业务复制目录。
+- 根 distribution 的 release commit 使用显式 `.` 整仓 scope；嵌套最小子包只允许包含目标路径，同仓其他子包修改不得被隐式提交。
+- package tag 固定为 `<distribution-name>@<version>`，并且必须与 release commit、当前 HEAD、`project.version`、wheel metadata 和已发布版本一致；build/upload 从当前干净 checkout 直接执行，不创建临时 worktree。
+- `pz pub` 不自动选择或升级版本号，不自动生成 changelog，不执行 `git push`。
+- commit/tag/upload 中途失败不得通过 reset、amend、删 tag 或历史改写回滚；精确匹配的已完成阶段由重跑幂等复用。
+- 稳定公共契约的破坏性变更只能通过主版本引入。
+- `required_pz` 作为 app 级版本约束。
+- `pz` 基础层遵循 core freeze / extension-first 治理。
+- 新增业务能力、平台能力、provider 实现、共享 middleware，默认通过官方扩展包或业务最小子包发布。
+- 官方扩展包必须直接表现为最小子包 `<app_id>`；它们属于扩展层，不属于 `pz` 内核。
+- 发布说明中维护本版本新增的正式契约、移除的旧入口和升级影响。
+
+## 20. 外部 app 信任模型
+
+外部 app / 独立子包本质上是可执行 Python 代码，`installed_apps` 不是安全沙箱。
+
+正式要求：
+
+- 文档中明确：外部 app 的引入属于受信代码接入。
+- `pz` base 不承担第三方 app 的安全审计职责。
+- 项目侧维护允许装载的 app 白名单/供应源策略。
+- 第三方 app 至少声明：
+  - 版本。
+  - `required_pz`。
+  - 公开 API 面。
+  - 迁移/数据影响面。