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/99-/350/265/204/346/272/220/346/224/266/345/217/243/345/220/216/347/273/255TODO.md

@@ -0,0 +1,84 @@
+# 99-资源收口后续 TODO
+
+状态：Active Todo
+
+本文档只记录 `pz` 资源主链在本轮收口后，仍待继续完成的正式问题。
+
+正式设计真相仍以：
+
+- `05-资源与运行目录规范.md`
+- `31-pz启动与运行时编译流程.md`
+
+为准。
+
+## 1. `resource.contribution` 协议仍是旧模型
+
+当前 `ResourceContributionSpec` 仍只提供：
+
+- `templates_dir`
+- `static_dir`
+- `locales_dir`
+- `migrations_dir`
+
+对应入口：
+
+- `pz/core/extensions/registry.py::ResourceContributionSpec`
+- `pz/assembly/extensions/compiler.py::_coerce_resource_contribution_spec`
+
+这和当前资源主链已经统一到：
+
+- `resources.items`
+- `ResourceSource.items`
+- `ResourceManifest.items`
+
+的正式模型不一致。
+
+### 需要完成的事
+
+1. 把 `resource.contribution` 收口到统一资源项协议。
+2. 评估该协议是否应直接声明资源项列表，而不是四个固定目录字段。
+3. 补上 `pages`、`template_config` 与后续统一资源项的扩展能力。
+4. 删除固定字段心智，避免扩展点再次分叉出第二套资源模型。
+
+## 2. `ResourceManifest.items` 还没有携带项目级来源聚合
+
+当前 `compile_resource_manifest()` 创建 `manifest.items` 时，`source_dirs` 固定为空元组。
+
+对应入口：
+
+- `pz/assembly/resources/compiler.py::compile_resource_manifest`
+
+当前只有：
+
+- `manifest.sources[*].items`
+
+持有每个 app 的实际来源目录集合。
+
+这意味着：
+
+- `ResourceManifest.items` 更像项目级输出项索引
+- 还不是完整的“项目级资源项结果”
+
+### 需要完成的事
+
+1. 决定 `ResourceManifest.items` 是否应聚合项目级 `source_dirs`。
+2. 如果应聚合，明确聚合顺序是否按 `installed_apps` 顺序保留。
+3. 如果不聚合，就在 contract 和文档里进一步明确：
+   - `manifest.items` 只表达项目级输出
+   - `manifest.sources[*].items` 才表达来源明细
+
+## 3. 资源消费方契约测试仍偏少
+
+当前资源层已有 compiler contract tests，但消费方尚未充分验证：
+
+- 页面域是否消费 `ResourceManifest`
+- 模板配置域是否消费 `ResourceManifest`
+- 运行时 facade 是否只依赖新模型
+
+### 需要完成的事
+
+1. 增加跨子系统契约测试，而不只测 resource compiler。
+2. 至少覆盖：
+   - `pz_page_center` 的页面声明消费
+   - `pz_page_center` 的模板配置消费
+   - 新资源项模型在 runtime/facade 层的可用性

pz_core/docs//345/217/221/347/211/210/345/211/215/346/270/205/345/215/225-4.0.11.md

@@ -0,0 +1,84 @@
+# 4.0.11 发版前清单
+
+> 设计迁移状态（2026-07-13）：本文只保留 4.0.11 拆分 wheel 发布记录，不是 5.0.0 当前合同；当前基础包只发布 `pz-cli` 单 wheel。其中 `pz pub` 命令序列对应当时的 build/upload-only 实现，不包含新的 package-scoped commit、annotated tag 与 `pub upload` 原子阶段，不得把本清单当作新版本可直接执行模板。
+
+本次发版目标：
+
+- `pz==4.0.11`
+- `pz-contrib==4.0.11`
+- 本批 release manifest 中的官方最小子包统一提升到 `4.0.11`
+- 薄安装 distribution 改为 `pz-cli==4.0.11`
+
+正式安装口径：
+
+- distribution 安装名：`pz-cli`
+- 实际命令名：`pz`
+- 真相源入口：`pz_core.cli:main`
+
+升级说明：
+
+- 终端用户安装方式从 `uv tool install pz` / `pip install pz` 收口为 `uv tool install pz-cli` / `pip install pz-cli`
+- 已安装后的使用命令不变，仍然执行 `pz ...`
+- `pz_contrib` 共享默认值已去业务化；业务默认值继续落在宿主 `pz.jsonc` 或业务 app 自己的默认配置
+
+回滚说明：
+
+- 若本次发布后需要回滚，先回退安装入口 distribution 到上一版 `pz-cli`
+- 再按依赖反向顺序回退 `pz`、`pz-contrib` 与本批次已发布的官方最小子包
+- 宿主项目回退后必须重新执行正式重装与健康检查
+
+版本范围说明：
+
+- release manifest 中的官方最小子包 `required_pz` 统一收口为 `>=4.0.0`
+- `pz` 的 `contrib` extra 统一要求 `pz-contrib>=4.0.0`
+- `pz-contrib` 聚合包统一要求本批次 release manifest 中的官方最小子包 `>=4.0.0`
+
+建议发布顺序：
+
+1. 先发基础包：`pz`
+2. 再按 release manifest 顺序发布官方最小子包；具体包名与顺序以 owning repo 的 manifest 为准
+3. 再发聚合包：`pz-contrib`
+4. 最后发安装 facade：`pz-cli`
+
+顺序说明：
+
+- `pz` 是所有正式子包的基础依赖，必须先上传。
+- `pz-contrib` 是聚合 distribution，必须放在最小子包之后。
+- `pz-cli` 只是安装门面 distribution，但会直接依赖 `pz-core` 与完整 `pz-contrib` 集合包；它放在最后上传，是为了确保闭包中的 `pz-settings-center`、`pz-foundation`、`pz-contrib` 与 `pz-core` 都已发布。该闭包不包含 `pz_apps` 业务子包。
+- 官方最小子包之间可能存在交叉依赖，上传阶段按 release manifest 固定顺序串行执行；安装闭环放到整批上传完成后统一验证。
+
+可直接执行的 `pz pub` 命令序列：
+
+默认先发到 `devpi_dev` 做完整验证；确认无误后，把 `PZ_RELEASE_TARGET` 改成 `devpi_pub`，再原样执行一遍。
+
+```bash
+export PZ_RELEASE_TARGET="${PZ_RELEASE_TARGET:-devpi_dev}"
+set -a
+source <deploy_repo_root>/docker-compose/devpi/.env
+set +a
+
+cd <pz_repo_root>
+pz pub pz --target "$PZ_RELEASE_TARGET" --project-dir .
+
+cd <pz_contrib_repo_root>
+# 按 release manifest 中声明的顺序逐个发布官方最小子包。
+pz pub <official-app-distribution> --target "$PZ_RELEASE_TARGET" --project-dir .
+pz pub pz-contrib --target "$PZ_RELEASE_TARGET" --project-dir .
+
+cd <pz_cli_repo_root>
+pz pub pz-cli --target "$PZ_RELEASE_TARGET" --project-dir .
+```
+
+正式发布到公共索引前，先显式切换目标：
+
+```bash
+export PZ_RELEASE_TARGET=devpi_pub
+```
+
+建议验证：
+
+- 在源码仓根执行对应 `pz pub <package> --target devpi_dev`
+- 完成 dev index 上传后，使用干净环境验证 `uv tool install --default-index https://packages.example.test/packages/pub/+simple/ pz-cli`
+- 验证 `pz --help`
+- 验证 `pz dev init`
+- 验证宿主重装与 `pz run` 健康检查

pz_core/docs//346/226/260/346/211/213/346/214/207/345/215/227.md

@@ -0,0 +1,422 @@
+# pz 新手指南
+
+这份文档给一条最短可执行的新手路径，分成开发线和生产线。
+
+如果本指南与正式设计文档冲突，以正式设计文档为准：
+
+- [`04-Settings与配置规范`](./pz规范与使用/04-Settings与配置规范.md)
+- [`09-CLI与Worker入口规范`](./pz规范与使用/09-CLI与Worker入口规范.md)
+- [`14-分层与扩展规范`](./pz规范与使用/14-分层与扩展规范.md)
+- [`15-子包开发使用手册`](./pz规范与使用/15-子包开发使用手册.md)
+- [`20-私有包仓与统一认证部署规范`](./pz规范与使用/20-私有包仓与统一认证部署规范.md)
+
+先记住正式边界：
+
+- 新项目开发线的单一正式入口是：先执行 `bash scripts/install_pz.sh` 安装公开 `pz-cli` distribution，拿到 `pz` 后执行 `pz dev init`。
+- 默认 `pz dev init` 负责项目骨架、默认本地 app、官方 `pz_apps` 全部正式最小叶子导入、托管 settings、初始环境安装与 IDE 投影。
+- 需要保留上游 Git checkout 时显式使用 `pz dev init --link --clone-sources` 或 `pz dev init --link --source-dir <path>`；linked 模式默认基础分支是 `develop`，显式替代值只有 `main`。
+- 开发线需要业务仓接管额外子包源码时使用 `pz dev add`；需要保留上游 checkout 联调时使用 `pz dev link`。
+- 生产线只安装已发布 distribution，不拉开发源码，不保留本地 checkout 作为正式依赖。
+- `pz dev add` 默认从 `develop` 分支更新或创建系统临时 Git cache，再导入一个最小子包到 `apps/<app_id>`，不保留嵌套 `.git`；`pz dev link` 才把 Git checkout 放在 `apps/.sources` 并建立 binding。
+
+## 开发线
+
+目标：从零安装公开 `pz-cli` distribution，确保全局 `pz` 可直接使用，然后在空目录里直接用 `pz dev init` 建好项目、接入官方源码并启动。
+
+### 0. 先检查前置条件
+
+开始前至少确认：
+
+- 本机已经有可用的 Python
+- 本机已经安装 `uv`
+- 本机已经安装 `git`
+- GitHub SSH key 已配置完成，可以直接访问 `git@github.com:...`
+
+建议先跑：
+
+```bash
+python --version
+uv --version
+git --version
+ssh -T git@github.com
+```
+
+### 1. 安装 `pz`，并把它接入 PATH
+
+当前 devpi 的正式 index 规划是：
+
+- `https://packages.example.test/packages/pub/+simple/`：公开读，适合直接安装 `pz`
+- `https://packages.example.test/packages/dev/+simple/`：开发包私有 index
+- `https://packages.example.test/packages/prod/+simple/`：正式包私有 index
+
+新手安装 `pz` 时，正式口径固定为安装脚本包装，直接走 `pub`，不需要私有安装凭据：
+
+```bash
+bash scripts/install_pz.sh
+```
+
+完成后重新打开一个 shell，或执行：
+
+```bash
+exec "$SHELL" -l
+```
+
+然后确认：
+
+```bash
+pz --help
+```
+
+补充说明：
+
+- `pub` 是公开安装面；拿 CLI 不需要 Basic Auth
+- `scripts/install_pz.sh` 会正式安装公开 `pz-cli==5.0.0` distribution；单个 wheel 固定提供 `pz_core`、`pz_settings_center` 与 `pz_foundation`
+- `dev` / `prod` 仍然是私有 index，给内部安装已发布私有包与发布链路使用
+- 如果你后续要安装私有包、发布内部包或使用 `pz pub`，再配置对应的安装/上传账号
+- `pip install pz` 只适合你已经明确管理好解释器和 PATH 的场景；它不是新手正式入口，也不承诺装完后当前 shell 立刻能直接找到 `pz`
+- `pip install pz-cli` / `uv tool install pz-cli` 与安装脚本表达同一条正式安装语义：公开安装 facade 是 `pz-cli`，实际命令仍然是 `pz`，最终仍然进入 `pz_core.cli:main`
+- `pz` 每次执行都会按正式顺序选择 provider：项目 `.venv` -> 项目 dev manifest 里记录的 `apps/.sources/pz` bootstrap runtime -> 当前解释器 `site-packages` -> `uv tool run --from pz-cli pz`
+- 所以检查“刚安装好的 `pz-cli` 是否正常”时，仍然必须离开 `pz` 源码树再执行，避免把源码树遮蔽误判成正式 provider 选择结果。
+- 项目根 `.env` 里的 `DEVPI_OWNER` / `DEVPI_OWNER_PASSWORD` / `DEVPI_INSTALL_USER` / `DEVPI_INSTALL_PASSWORD` 会被 `pz pub`、`pz app add`、`pz app update` 优先复用到正式私有包仓链路里；如果你已经在 shell 里显式导出了这些环境变量，CLI 不会再覆盖它们
+
+### 2. 在空目录里直接执行 `pz dev init`
+
+```bash
+mkdir demo_project
+cd demo_project
+pz dev init --project-dir .
+```
+
+这就是开发线的新手正式入口。对于空目录，它会一次性完成：
+
+- 创建项目骨架：`pyproject.toml`、`main.py`、`pz.jsonc`、`pz.{env}.jsonc`、`.env*`
+- 创建默认本地 app：默认使用当前目录名归一化后的 slug；需要覆盖时可传 `--app-name <slug>`
+- 通过 `dev source cache` 固定官方 `pz_apps` revision，并把全部正式最小叶子导入 `apps/<app_id>`；项目不保留该 Git checkout
+- 默认项目配置声明 `pz_settings_center`、`pz_foundation` 与 `apps`；运行时只发现 `apps/` 下的真实本地 app 和可见受管快捷方式
+- 刷新项目根托管 settings 区块，把默认本地 app 与官方 source-root 的 settings 模板同步进 `pz*.jsonc` / `.env*`
+- 执行一次初始环境安装：创建或复用项目根 `.venv`，安装完整依赖闭包
+- 执行一次 `pz dev ide sync`：已有 `.idea/` 时生成 PyCharm source-root 投影，已有 `.vscode/` 时维护 VS Code `python.analysis.extraPaths`；不存在的 IDE 目录不会由 PZ 创建
+- 刷新 `AGENTS.md`
+- 默认执行完成后可以直接 `pz run`
+
+生成结果至少包括：
+
+- `main.py`
+- `pyproject.toml`
+- `pz.jsonc`
+- `pz.develop.jsonc`
+- `pz.test.jsonc`
+- `pz.product.jsonc`
+- `.env`
+- `.env.develop`
+- `.env.test`
+- `.env.product`
+- `apps/`
+- `apps/<当前目录名归一化后的 app>/`
+
+补充说明：
+
+- 默认导入的源码由业务仓统一管理，不保留嵌套 `.git`，PZ 不自动覆盖或更新
+- linked 初始化必须写成 `--link --clone-sources` 或 `--link --source-dir <path>`；两个 source selector 必须且只能出现一个
+- linked 模式的 `[tool.uv.sources]` 只写一个 `pz-cli = { path = "apps/.sources/pz", editable = true }`；不得恢复旧拆分 distribution 的 source 键
+- linked 模式默认基础分支是 `develop`；只有显式 `--base-branch main` 才使用 `main`，业务分支名固定来自 `business_app_id`
+- `pz dev init` 按正式新手流程做幂等收口，不会重复覆盖既有业务源码
+- 如果暂时不跑最终初始环境安装，可显式传 `--no-sync`；后续再执行一次 `pz env install --project-dir .`，IDE 投影同步不因此跳过
+
+### 3. 需要更多源码时，选择 `pz dev add` 或 `pz dev link`
+
+正式口径下，开发模式直接执行：
+
+```bash
+pz dev init --project-dir .
+```
+
+这一步默认把官方正式最小子包导入业务仓。额外源码仍必须根据所有权选择导入或链接。
+
+希望源码成为当前业务仓的一部分时，执行：
+
+```bash
+pz dev add git@github.com:<org>/<repo>.git --project-dir .
+pz dev add ../catalog/pz_page_center --project-dir .
+pz dev add pz_page_center --project-dir .
+```
+
+补充说明：
+
+- 输入必须唯一解析到一个正式最小子包
+- Git 默认读取 `develop` 分支；系统临时 cache 已存在时先更新，不存在时 clone，再把固定 full revision 的源码导入 `apps/<app_id>`，不带 `.git`
+- cache 只减少网络开销；导入后 `apps/<app_id>` 是业务代码的唯一真相源，cache 更新失败不会静默使用陈旧版本
+- 导入后由业务仓统一管理，PZ 不自动更新、覆盖或删除
+- 任意真实本地 app 或 linked binding 已暴露相同 `app_id` 时直接失败；冲突按 app 身份判断，不按路径名称判断
+
+希望继续在上游 Git checkout 上联调时，执行：
+
+```bash
+pz dev link git@github.com:<org>/<repo>.git --project-dir .
+pz dev link ../catalog --project-dir .
+pz dev link pz_page_center --base-branch main --project-dir .
+```
+
+linked 模式补充说明：
+
+- `pz dev link` 默认基础分支是 `develop`，显式替代值只有 `main`
+- 目标业务分支由 manifest 的 `business_app_id` 决定，不接受任意目标分支参数
+- `pz dev link pz_apps` 暴露目录 binding；`pz dev link pz_page_center` 只暴露该叶子 binding
+- checkout 位于 `apps/.sources/<repo_key>`；物理 `.sources` 本身永远不进入运行时 app 发现
+- 已有 checkout 需要重新对齐业务分支时，使用 `pz dev branch <repo-or-app>`
+- 删除 binding 使用 `pz dev unlink <binding>`，不会删除业务仓真实源码
+
+### 4. 按需刷新托管配置区块
+
+`pz dev init` 会在 scaffold、默认 app 和官方源码基线准备完成后刷新托管配置区块。只有你后面新增了 app、增加了 dev source，或者确实要重建托管配置区块时，才手工执行：
+
+```bash
+pz settings update --project-dir .
+```
+
+如果你只想处理项目根 `AGENTS.md`，正式命令是：
+
+```bash
+pz settings refresh-agents --project-dir .
+pz settings reset-agents --project-dir .
+```
+
+边界：
+
+- `pz settings refresh-agents` 只刷新根 `AGENTS.md` 的 pz 托管区块，保留用户手写内容
+- `pz settings reset-agents` 直接把根 `AGENTS.md` 重置为当前正式托管块，不保留用户手写内容
+
+执行完后，项目根应至少保有：
+
+- `pz.jsonc`
+- `pz.develop.jsonc`
+- `pz.test.jsonc`
+- `pz.product.jsonc`
+- `.env`
+- `.env.develop`
+- `.env.test`
+- `.env.product`
+
+环境配置说明：
+
+- `PZ_ENV` 是唯一正式环境选择变量，可选值固定为 `develop`、`test`、`product`
+- 未显式指定 `PZ_ENV` 时，默认按 `develop` 处理
+- `pz.jsonc` 放项目基础装配和通用非敏感配置
+- `pz.develop.jsonc` / `pz.test.jsonc` / `pz.product.jsonc` 放对应环境的非敏感静态覆盖
+- `.env` 放通用敏感配置基线，例如数据库密码、Redis 密码、第三方密钥
+- `.env.develop` / `.env.test` / `.env.product` 放对应环境自己的敏感覆盖
+- 正式约束是：非敏感配置优先写 JSONC，敏感配置优先写 `.env`
+
+覆盖顺序：
+
+1. `pz.jsonc`
+2. `pz.{PZ_ENV}.jsonc`
+3. `.env`
+4. `.env.{PZ_ENV}`
+5. 显式环境变量
+
+各子包 `configs/default.jsonc` 与 `configs/default.env` 只在 `pz settings init/update` 时读取，用来生成或补全项目根 `pz*.jsonc` 与 `.env*`；启动阶段不直接读取子包默认文件。
+
+最终优先级从低到高是：
+
+- `pz.jsonc`
+- `pz.{PZ_ENV}.jsonc`
+- 通用 `.env`
+- 环境 `.env`
+- 显式环境变量
+
+直接例子：
+
+- `database.host`、`project.base_url` 这类非敏感环境差异，放 `pz.product.jsonc`
+- `<infra_owner>__database__password`、`<infra_owner>__cache__password`、`<auth_owner>__oauth_client_secret` 这类敏感值，放 `.env.product`
+- 如果部署平台再显式注入环境变量，那么它会覆盖 `.env.product`
+
+补充说明：
+
+- 如果你面对的不是一个刚通过 `pz dev init` 创建的新项目，而是一个已经存在、但还没有 `pz.jsonc` 的目录，才适合先跑 `pz env init --project-dir .` 或 `pz settings init --project-dir .`
+- CLI 初始化入口固定为分组命令，统一写成 `pz env init`、`pz app init`、`pz dev init`、`pz settings init` 这类形式。
+- app 导入问题、运行时装配问题、启动链问题，统一留到 `pz run` 或显式运行运行时命令时再处理；不要把这类动作塞回 `pz dev init`
+
+### 4.1 项目根命令扩展
+
+`pz` 的根命令现在分两层扩展：
+
+- app CLI：每个 app 的正式入口固定为 `<app>/cli/*.py`，显式调用形式固定是 `pz <app_id> <tool>`
+- project CLI：项目自己的快捷命令统一写在 `pz.jsonc` 顶层 `commands`
+
+例子：
+
+```jsonc
+{
+  "commands": {
+    "hello": "echo hello",
+    "test:smoke": ["python", "-m", "pytest", "-q"],
+    "worker:smoke": {
+      "argv": ["python", "-m", "pytest", "tests/test_worker.py", "-q"],
+      "description": "Run worker smoke checks."
+    }
+  }
+}
+```
+
+执行时可以直接写：
+
+```bash
+pz hello
+pz test:smoke
+```
+
+补充约束：
+
+- 如果某个 app CLI tool 在当前项目里只出现一次，它会自动注册成 `pz <tool>`
+- 如果多个 app 暴露了同名 tool，根命令不会抢占，必须显式写成 `pz <app_id> <tool>`
+- 内建正式命令优先，项目 `commands` 不允许覆盖 `pz run`、`pz dev`、`pz list`、`pz check`、`pz db` 等正式入口
+- `pz --help` 会把这些扩展命令列到 `Extensions:` 小节
+
+### 5. 根据需要补做 `pz env install` 或额外 `pz env sync`
+
+如果当前项目已经通过 `pz dev init` 走过默认路径，项目根 `.venv` 和全部导入 app 的依赖闭包已经同步过一次。
+
+如果你之前在 `pz dev init` 时显式传了 `--no-sync`，或者只是想补做一次正式初始环境安装，直接执行：
+
+`--no-sync` 不会提前创建项目根 `.venv`；环境仍由下面的正式原子命令统一创建和同步。
+
+```bash
+pz env install --project-dir .
+```
+
+如果你是在后续 `pz dev add` 或 `pz dev link` 之后继续执行：
+
+```bash
+pz env init --project-dir .
+```
+
+那么当前项目根以及新增的业务源码或 linked 开发源码根，也会按同一正式口径继续完成托管区刷新和初始环境安装。
+
+如果你只是想再次同步依赖，而不需要重做骨架与 settings 刷新，直接执行：
+
+```bash
+pz env sync --project-dir .
+```
+
+如果 linked 源码仓也需要单独开发，进入 `pz dev link` 输出的 checkout 根再执行一次：
+
+```bash
+# 进入 pz dev link 输出的对应本地 checkout 根目录
+cd ...
+python -m pip install -e .
+```
+
+### 6. 启动项目
+
+普通 `pz` 项目默认直接使用：
+
+```bash
+pz run
+pz run develop
+pz run dev
+pz run test
+pz run product
+```
+
+这里的正式口径是：
+
+- `pz run` / `pz run develop` / `pz run dev` 会进入同一个 develop 环境
+- `pz run test` / `pz run product` 分别进入 test / product
+- 它会直接 handoff 到项目根 `main.py`，不再在外面保留第二层长期父进程
+- 它不会创建第二个宿主入口，也不会替代项目自己的 `main.py`
+- 安装后的 `pz` / `pz` 来自正式 `console_scripts`，不依赖额外 shim 回写
+- 这些命令底层都只是在进入 `main.py` 前显式设置 `PZ_ENV`
+- 其中 `pz run = pz run develop = pz run dev`
+- 规范环境名仍然是 `develop`，`dev` 只是 CLI 别名
+- `pz run test` 对应 `test`，`pz run product` 对应 `product`
+- 运行时 snapshot 中看到的 `project.pz_env` 是编译后的派生结果，不是新的外部选择变量
+
+开发线约束：
+
+- 业务仓源码接管走 `pz dev add`
+- 上游 checkout 联调走 `pz dev link`
+- 依赖同步走 `pz env sync`
+- 宿主启动命令统一走 `pz run` 三态入口
+- 本地源码 checkout 只属于开发态，不等于已发布产物
+
+## 生产线
+
+目标：只使用已发布产物部署，不把开发态源码 checkout 带进生产环境。
+
+### 1. 准备项目代码与配置文件
+
+```bash
+pz env doctor --project-dir .
+pz env init --project-dir .
+pz settings update --project-dir .
+```
+
+然后补齐：
+
+- `pz.jsonc`
+- `pz.product.jsonc`
+- `.env`
+- `.env.product`
+
+生产环境配置口径：
+
+- 启动命令必须显式进入 `product`
+- `product` 不能靠 `.env.product` 文件存在与否自动推导
+- 生产环境的非敏感差异写 `pz.product.jsonc`
+- 生产环境的敏感差异写 `.env.product` 或部署平台显式环境变量
+
+### 2. 生产环境只安装已发布 distribution
+
+不要在生产环境执行：
+
+```bash
+pz dev add ...
+pz dev link ...
+```
+
+正式做法是让项目依赖指向已发布版本，然后安装：
+
+```bash
+pz app versions <app_id> --project-dir .
+pz app add <app_id> --project-dir .
+# 或精确指定
+pz app add <app_id> --version 1.4.2 --project-dir .
+pz env sync --project-dir .
+```
+
+`app add` 与 `app update` 都是编排命令：默认选择兼容的最新稳定版本，也可用 `--version` 精确指定；底层版本查询、精确声明和安装仍由可单独执行的原子命令承担。最终项目声明和 `uv.lock` 只记录精确版本，不记录 `latest`。
+
+需要发布正式版本时，若当前目录本身就是目标 distribution 的 Git 仓库根，可直接使用；否则先确保目标源码仓已经通过 `apps/.sources/<repo_key>` 暴露为 Git source-root：
+
+```bash
+pz pub <app_id> --target devpi_prod --project-dir .
+```
+
+目标发布合同下，这一个编排命令会：
+
+1. 优先精确匹配当前 Git 仓库根的 distribution，否则枚举 `apps/.sources` 并复用正式 workspace 子包发现程序唯一定位目标子包；
+2. 根 distribution 提交整仓 `.` scope，嵌套子包只提交目标路径，commit subject 为 `release(<app_id>): <version>`；
+3. 创建 `<distribution-name>@<version>` annotated tag；
+4. 要求当前 checkout clean 且 HEAD 等于 tag commit，直接验证 `project.version` 与 wheel metadata 后上传，不创建临时 worktree。
+
+业务仓中的复制目录不是发布源。当前仓库根不匹配且没有 `.sources` Git 仓库、仓库中找不到目标子包、或多个仓库重复发现目标子包都会在 Git mutation 前分别报错。它不会自动升级版本号，也不会执行 `git push`。发布失败后已创建的 commit/tag 会保留；重跑 upload 前必须让干净 HEAD 回到精确 tag commit。
+
+### 3. 用正式生产命令启动 `product`
+
+```bash
+pz run product
+```
+
+生产环境启动也遵循同一原则：
+
+- 正式命令固定写成 `pz run product`
+- `product` 必须通过显式命令进入，不能靠文件存在与否猜测
+- 这仍然只是执行项目根 `main.py`，不是额外的生产启动脚本
+
+生产线约束：
+
+- 正式依赖来源是已发布 distribution，不是本地源码 checkout
+- 发布链正式走 `pz pub`
+- 生产启动命令必须显式进入 `product`
+- 生产问题优先通过正式配置、正式入口、正式发布链解决，不靠开发态 link 或临时路径 hack

pz_core/infra/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .settings import (
+    InfraContext,
+    InfraComponent,
+    ResourceItemContract,
+    ResilienceSettings,
+    ResourceSettings,
+)
+
+__all__ = [
+    "InfraContext",
+    "InfraComponent",
+    "ResourceItemContract",
+    "ResilienceSettings",
+    "ResourceSettings",
+]

pz_core/infra/db/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .contracts import (
+    DatabaseAdapter,
+    DatabaseMigrationPort,
+    DatabaseMigrationSnapshot,
+    DatabaseReadinessProbe,
+    DatabaseSession,
+    DatabaseTransaction,
+    DbOwner,
+    MigrationSource,
+)
+
+__all__ = [
+    "DatabaseAdapter",
+    "DatabaseMigrationPort",
+    "DatabaseMigrationSnapshot",
+    "DatabaseReadinessProbe",
+    "DatabaseSession",
+    "DatabaseTransaction",
+    "DbOwner",
+    "MigrationSource",
+]