pz-cli 5.0.0__py3-none-any.whl

pz_core/core/health/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .contracts import HealthStatus
+
+__all__ = ["HealthStatus"]
+

pz_core/core/health/contracts.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class HealthStatus:
+    status: str
+    detail: str = ""
+

pz_core/core/middlewares/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .models import MiddlewareDecl, MiddlewareManifest
+
+__all__ = ["MiddlewareDecl", "MiddlewareManifest"]
+

pz_core/core/middlewares/models.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class MiddlewareDecl:
+    id: str
+    factory: str
+    owner: str
+    priority: int = 100
+    replace: str | None = None
+    params_model: str | None = None
+    params: dict[str, Any] | None = None
+
+    @property
+    def import_path(self) -> str:
+        return self.factory
+
+
+@dataclass(frozen=True, slots=True)
+class MiddlewareManifest:
+    middlewares: tuple[MiddlewareDecl, ...]

pz_core/core/routing/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .models import RouteConflictPolicy, RouteDecl, RouteManifest
+
+__all__ = ["RouteConflictPolicy", "RouteDecl", "RouteManifest"]

pz_core/core/routing/models.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+RouteConflictPolicy = Literal["fail", "warn"]
+
+
+@dataclass(frozen=True, slots=True)
+class RouteDecl:
+    path: str
+    method: str
+    name: str
+    owner: str
+    source_path: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RouteManifest:
+    routes: tuple[RouteDecl, ...]
+    conflict_policy: RouteConflictPolicy = "fail"

pz_core/core/settings_contracts.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+AppRouteDefaultMode = Literal["auth", "public"]
+
+
+class AppRoutePolicySettings(BaseModel):
+    """Generic per-app route policy declaration compiled by an auth provider."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    default_mode: AppRouteDefaultMode = "auth"
+    auth_paths: list[str] = Field(default_factory=list)
+    public_paths: list[str] = Field(default_factory=list)
+    delegate_paths: list[str] = Field(default_factory=list)
+    auth_owner: str | None = None
+    public_owner: str | None = None
+    delegate_owner: str | None = None
+
+
+__all__ = ["AppRouteDefaultMode", "AppRoutePolicySettings"]

pz_core/docs/README.md

@@ -0,0 +1,20 @@
+# PZ 文档索引（Start Here）
+
+## 设计依据
+
+本 README 按 `pz` 正式设计文档口径编写，回链如下：
+
+如果本 README 与 `pz` 设计文档、正式 contract 或正式装配约定冲突，以 `pz` 设计文档为准。
+
+- [`新手指南`](新手指南.md)
+- [`pz命令总览`](pz命令总览.md)
+- [`03-App最小子包规范`](pz规范与使用/03-App最小子包规范.md)
+- [`10-测试与契约规范`](pz规范与使用/10-测试与契约规范.md)
+- [`14-分层与扩展规范`](pz规范与使用/14-分层与扩展规范.md)
+- [`15-子包开发使用手册`](pz规范与使用/15-子包开发使用手册.md)
+- [`21-contrib约定与Provider接入规范`](pz规范与使用/21-contrib约定与Provider接入规范.md)
+- [`25-面向对象开发规范`](pz规范与使用/25-面向对象开发规范.md)
+
+## 快速了解
+
+- [`24-pz启动与运行时编译流程`](pz规范与使用/24-pz启动与运行时编译流程.md)

pz_core/docs/distribution-README.md

@@ -0,0 +1,438 @@
+# pz
+
+`pz` 是唯一正式基础包，也是唯一可以独立启动的包。
+
+它只承载稳定合同、发现、编译、组装、启动，以及顶层 `pz` CLI 主链；官方能力与业务能力都应落成最小子包，而不是继续堆回基础层。
+
+## 最重要的设计哲学
+
+- 单一基础包：`pz` 是唯一正式基础包，不能再拆回第二套 core。
+- 最小子包平权：除 `pz` 外，正式运行单元只有最小子包；官方能力和业务能力使用同一套装配模型。
+- 约定优先：目录名、import 包名、distribution、`app_id` 必须围绕稳定 app 身份收敛，不强制特定技术前缀，不保留第二套命名和第二套入口。
+- 分层清晰：基础层只保留稳定合同与薄绑定层；高层能力优先进入 `pz_contrib` 或其它最小子包。
+- 单一真相源：路由、settings、公开 surface、安装单位都必须有唯一正式入口，不做长期兼容桥接层。
+
+## 新手指南
+
+新手入口固定在独立文档：
+
+- [`新手指南.md`](新手指南.md)
+
+里面包含：
+
+- 开发线：先执行 `bash scripts/install_pz.sh` 安装公开 `pz-cli` distribution，拿到 `pz` 后在空目录里运行 `pz dev init`；默认导入官方 `pz_apps` 的正式最小子包并交给业务仓管理，只有显式 `--link` 才保留上游 checkout
+- 生产线：正式安装源、环境配置、覆盖顺序、`PZ_ENV=product` 启动口径
+
+新项目开发线的最短正式路径是：
+
+```bash
+bash scripts/install_pz.sh
+exec "$SHELL" -l
+mkdir my_project && cd my_project
+pz dev init --project-dir .
+```
+
+repo-local 作者面命令仍然统一是：
+
+- `pz env doctor`
+- `pz env install`
+- `pz env init`
+- `pz env sync`
+- `pz startapp`
+- 开发模式下统一走 `pz dev init`
+- 必要时再执行 `pz settings update`
+- 启动时统一走 `pz run`
+
+开发模式默认自动接入：
+
+- 当前目录名对应的默认本地 app
+- 官方 `pz_apps` 中全部正式最小子包；通过系统临时 Git cache 固定 revision 后导入 `apps/<app_id>`，不保留嵌套 `.git`
+- 需要保留 bootstrap checkout 时显式使用 `pz dev init --link --clone-sources`；复用已有本地源码则使用 `pz dev init --link --source-dir <path>`
+- 后续需要上游联调时通过 `pz dev link pz_apps` 或具体 app id 显式绑定，需要业务接管额外源码时通过 `pz dev add <app_id>` 导入单个最小子包
+- `git@github.com:JiXiangTools/pyzza.git`（逻辑仓名 `pz`）
+
+补充说明：
+
+- `--project-dir` 默认就是当前目录；脚本会直接把当前目录初始化成完整项目。
+- 默认 app slug 来自当前目录名；如果要覆盖，可以显式传 `--app-name`.
+- `pz-cli==5.0.0` 是唯一基础 distribution；一个 wheel 固定包含 `pz_core`、`pz_settings_center` 与 `pz_foundation` Python 包。
+- `pz dev init` 默认声明 `pz_settings_center`、`pz_foundation` 与 `apps`；运行时只发现 `apps/` 下的真实本地 app 和可见受管快捷方式。
+- 默认模式通过业务仓中的 `apps/<app_id>` 解析导入源码；只有显式 linked 初始化才把 checkout 和 binding 记录到 typed v5 manifest。
+- linked 模式中的同仓 distributions 通过精确 `[tool.uv.sources]` 指向同一 `apps/.sources/pz` checkout，并默认从 `develop` 创建业务分支；只有显式传 `--base-branch main` 才改用 `main` 基线。
+- 默认初始化会从系统临时 Git cache 导入 `pz_apps` 的全部正式最小叶子；额外仓仍显式选择 `dev add` 业务导入或 `dev link` 上游绑定。
+- 如果同时传了 `--no-sync`，命令仍完成骨架、源码装配、settings 与 IDE 投影，只跳过最终初始环境安装；后续再执行一次 `pz env install --project-dir ...` 或 `pz env sync --project-dir ...` 即可。
+- 启动口径默认就是 `pz run`；它会复用当前 `pz` 所在解释器并执行项目根 `main.py`，不再额外生成第二套启动脚本。
+- 如果在同一个项目目录里重复执行 `pz dev init`，默认模式不得覆盖既有业务源码；linked 模式复用 manifest 中已有 checkout 与 binding。
+
+## 安装
+
+新手正式安装路径：
+
+```bash
+bash scripts/install_pz.sh
+```
+
+重新打开 shell 后可使用：
+
+```bash
+pz --help
+pz --help
+```
+
+本地发布链 smoke：
+
+```bash
+bash scripts/build_pz.sh --no-sources
+```
+
+然后继续按 `docs/pz规范与使用/12-构建与发布检查清单.md` 执行干净 venv 安装 smoke。
+
+基础包 + 官方 contrib 组合：
+
+```bash
+pip install "pz[contrib]"
+```
+
+公开安装 facade：
+
+```bash
+uv tool install pz-cli
+pip install pz-cli
+```
+
+安装口径说明：
+
+- 新手安装 CLI 的唯一正式入口默认走 `bash scripts/install_pz.sh`，它会从 `pub` index 安装公开 `pz-cli` distribution，不要求私有安装凭据。
+- 默认公开安装索引路径是 `packages/pub/+simple/`，安装脚本会优先按这个正式入口解析。
+- `scripts/install_pz.sh` 统一负责安装与 PATH 刷新，确保 `pz` / `pz` 能在 shell 里直接使用。
+- `pz` 是极薄的 launcher facade；它只负责按正式顺序选择 provider，然后进入 `pz_core.cli:main`。
+- `pz-cli` 的 console script 固定指向 `pz_core.pz_launcher:main`；provider 选定后仍只进入同一个 `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_core.cli:main`；`pz` 只是外层 launcher，不引入第二套运行时。
+- `pip install pz` 只负责把 console script 安装到对应解释器的 scripts 目录，不保证那个目录已经在当前 shell 的 `PATH` 里。
+- `pip install pz-cli==5.0.0` / `uv tool install pz-cli` 安装唯一基础 wheel；它直接提供 `pz_core`、`pz_settings_center` 与 `pz_foundation`，不会安装旧拆分 wheel，也不会自动安装 `pz_apps` 仓中的业务子包。
+- `pz` 会先按正式 provider 顺序解析，再决定最终命中的 `pz_core.cli:main`；当前目录只负责项目上下文和项目级 provider 发现，不允许再长出私有 wrapper 语义。
+- 因此验证“已安装的 `pz-cli` 是否可用”时，仍然应在 `pz` 源码树外执行，避免把源码树遮蔽误判成正式安装语义。
+- 单 wheel 不改变源码分层：`pz_core` 仍不得直接 import 官方或业务 app 的内部实现。
+- 顶层项目作者面命令由 `pz` 基础包直接提供，不再要求额外安装 root CLI provider。
+
+## 常用命令
+
+命令分类的唯一正式真相表见 [`pz命令总览.md`](pz命令总览.md)。本 README 只保留三层摘要：
+
+- 编排层命令：`pz dev init`、`pz dev add`、`pz dev link`、`pz dev branch`、`pz dev update`、`pz dev unlink`、`pz env init`、`pz app init`、`pz app add`、`pz app update`、`pz app rm`、`pz pub`、`pz pub batch`
+- 原子层命令：`pz env doctor`、`pz env install`、`pz env sync`、`pz settings init`、`pz settings update`、`pz settings refresh-agents`、`pz settings reset-agents`、`pz startapp`、`pz app versions`、`pz app declare`、`pz app undeclare`、`pz app install`、`pz dev source cache`、`pz dev source import`、`pz dev source link`、`pz dev source branch`、`pz dev source update`、`pz dev source unlink`、`pz dev ide sync`、`pz pub commit`、`pz pub tag`、`pz pub upload`、`pz pub rm`
+- 运行时层命令：`pz run`、`pz list`、`pz check`、`pz db ...`、`pz workers ...`、`pz resources ...`、`pz <app_id> <tool>`
+
+常用入口示例：
+
+```bash
+pz dev init --project-dir .
+pz env doctor --project-dir .
+pz env install --project-dir .
+pz env init --project-dir .
+pz env sync --project-dir .
+pz settings init --force --project-dir .
+pz settings update catalog --project-dir .
+pz startapp demo --project-dir .
+pz app versions catalog --project-dir .
+pz app add catalog --project-dir .
+pz app add catalog --version 1.4.2 --project-dir .
+pz dev add https://example.com/catalog.git --project-dir .
+pz dev add ../catalog/catalog --project-dir .
+pz dev link ../catalog --project-dir .
+pz dev update catalog --project-dir .
+pz dev unlink catalog --project-dir .
+pz pub catalog --target pypi --dry-run --project-dir .
+pz pub rm catalog --target devpi_pub --force --project-dir .
+pz pub batch pz catalog --target pypi --project-dir .
+pz list --project-dir .
+pz catalog config --help
+```
+
+### CLI 扩展
+
+`pz` 现在支持两类扩展命令，统一收口在根命令层：
+
+- app CLI 扩展：每个 app 的正式 CLI 入口固定为 `<app>/cli/*.py`。显式形式始终是 `pz <app_id> <tool>`。
+- project CLI 扩展：项目自身的 npm-like 快捷命令统一写在 `pz.jsonc` 顶层 `commands`。
+
+唯一的 app CLI tool 会自动注册成 `pz <tool>` 根命令；如果多个 app 暴露了同名 tool，根命令不会抢占，而是明确要求写成 `pz <app_id> <tool>`。
+
+`pz.jsonc` 里的 `commands` 支持：
+
+```jsonc
+{
+  "commands": {
+    "hello": "echo hello",
+    "lint": ["python", "-m", "pytest", "-q"],
+    "worker:smoke": {
+      "argv": ["python", "-m", "pytest", "tests/test_worker.py", "-q"],
+      "description": "Run the worker smoke suite."
+    }
+  }
+}
+```
+
+项目级扩展配置还可以声明发布锁：
+
+```jsonc
+{
+  "extensions": {
+    "publish_lock": {
+      "targets": {
+        "pub": ["pz-cli"],
+        "devpi_prod": ["pz"],
+        "dev": ["catalog"]
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- `pub` / `prod` / `dev` 会按正式 devpi index 分类生效。
+- 也可以直接写精确 target 名，比如 `devpi_pub`、`devpi_prod`、`devpi_dev`。
+- 一旦命中对应锁，未列入 allowlist 的包不能执行 `pz pub ...`。
+
+补充约束：
+
+- 内建正式命令仍然优先，项目命令不能覆盖 `run`、`dev`、`list`、`check`、`db` 等正式入口。
+- `pz --help` 会把当前项目可用的扩展命令列到 `Extensions:` 小节。
+
+补充说明：
+
+- 新建开发项目的正式入口是 `pz dev init` / `pz dev init`。
+- `pz env install` / `pz env install` 是“创建或复用项目 `.venv`，再执行首轮依赖同步”的原子命令。
+- `pz env init` / `pz env init` 是“已有目录补齐骨架、托管区块和初始环境安装”的编排命令，不与 `dev init` 竞争新项目入口。
+- CLI 初始化入口固定为分组命令，例如 `pz env init`、`pz app init`、`pz dev init`、`pz settings init`；`pz` 入口遵循同一分组结构。
+
+本地 contrib 安装链 smoke：
+
+执行 `bash scripts/build_pz.sh --no-sources` 后，继续按 `docs/pz规范与使用/12-构建与发布检查清单.md` 的官方最小子包 smoke 路径验证。
+
+`pz.app` 是正式宿主 Python API 入口。
+
+## 重要约定
+
+- 命名规则固定为：
+  - 目录名 = `<app_id>`
+  - import 包名 = `<app_id>`
+  - `app_id = <app_id>`
+  - distribution = `<app_id with _ replaced by ->`
+- 新建子包默认让目录名、import 包名与 `app_id` 对齐；历史稳定 `app_id` 以已声明值为准，不因文档命名口径变化迁移，也不强制 `pz_` 前缀。
+- `installed_apps` 的正式写法只允许目录名；可以写最小子包名，也可以写容器目录名，框架会递归发现其中嵌套的最小子包。
+- Python 运行时代码读取配置只允许：
+  - `import pz_settings_center.public as settings_center`
+  - app 私有配置走 `settings_center.settings.<app_id>.<field>`
+  - 项目级配置走 `settings_center.settings.project.<field>`
+- 每个 app 的 URL 真相源固定在 `<app>/urls.py` 或 `<app>/urls/`，直接使用 FastAPI 原生 `APIRouter()` 与 `include_router(...)`。
+- `public.py` 是 app 唯一稳定公开面；跨包调用优先走 `public.py`，不要直接 import 别的 app 内部实现。
+- `pz_core.cli:main` 是唯一正式 CLI dispatcher；`pz.root_cli` 是顶层命令 provider entry-point group，不是第二个入口。
+- `env`、`settings`、`startapp`、`app`、`dev`、`pub` 都属于正式顶层命令协议，由已安装的 `pz.root_cli` provider handler 注册后交给同一个 dispatcher。
+- 面向用户的主路径优先走编排层；原子命令保留给单一职责动作和编排复用。
+- 其它命令统一收敛到 `pz` 的单一运行时 CLI 主链。
+
+## 使用方式
+
+新建项目：
+
+```bash
+pz env doctor --project-dir /path/to/project
+pz dev init --project-dir /path/to/project
+```
+
+默认会同时生成：
+
+- `pz.jsonc`
+- `pz.develop.jsonc`
+- `pz.test.jsonc`
+- `pz.product.jsonc`
+- `.env`
+- `.env.develop`
+- `.env.test`
+- `.env.product`
+
+其中 `pz.{env}.jsonc` 是非敏感的环境静态覆盖骨架；`.env` 是默认 secrets 模板；`.env.{env}` 只放对应环境的敏感或运行态差异覆盖。
+
+新建子包：
+
+```bash
+pz startapp demo --project-dir /path/to/project
+```
+
+把已发布 app 加入项目声明并安装：
+
+```bash
+pz app add catalog --project-dir /path/to/project
+```
+
+未指定版本时默认安装兼容的最新稳定版本，也可用 `--version <version>` 精确指定。解析结果会以精确版本进入项目声明和 `uv.lock`；安装目标是当前项目解释器环境，不会把源码写进 `apps/`。安装前可用 `pz app versions catalog` 查看可用、当前声明、锁定和已安装版本。
+
+把正式最小子包源码导入本地 `apps/` 并交给业务仓管理：
+
+```bash
+pz dev add https://example.com/catalog.git --project-dir /path/to/project
+```
+
+也可以从本地叶子源码目录导入：
+
+```bash
+pz dev add ../catalog/catalog --project-dir /path/to/project
+```
+
+需要保留上游 checkout 与 Git 生命周期时使用 linked 模式：
+
+```bash
+pz dev link ../catalog --project-dir /path/to/project
+```
+
+新建项目级 settings：
+
+```bash
+pz settings init --project-dir /path/to/project
+```
+
+明确覆盖并重生成项目级 settings：
+
+```bash
+pz settings init --force --project-dir /path/to/project
+```
+
+更新某个 app 的 settings：
+
+```bash
+pz settings update catalog --project-dir /path/to/project
+```
+
+只刷新项目根 `AGENTS.md` 的 pz 托管区块：
+
+```bash
+pz settings refresh-agents --project-dir /path/to/project
+```
+
+整份重置项目根 `AGENTS.md`：
+
+```bash
+pz settings reset-agents --project-dir /path/to/project
+```
+
+补充说明：
+
+- `pz env doctor` 负责检查当前项目目录的作者面前置条件，例如 `python`、`uv`、`git`。
+- `pz dev init` 是新建开发项目的唯一正式入口；它会补齐骨架、默认本地 app、官方源码基线，刷新托管配置区块，并默认调用 `pz env install`，让 `pz run` 可以直接启动。
+- `pz env install` 是正式初始环境安装入口，负责创建或复用项目 `.venv`，并对项目根和已发现的作者面根执行首轮同步。
+- `pz env init` 负责复用底层 scaffold service、`pz settings update` 与 `pz env install` 的正式语义，对已有目录补齐骨架、刷新托管区块，并默认完成初始环境安装。
+- `pz env sync` 是正式依赖同步入口，负责对项目根和已发现的作者面根执行统一的同步编排。
+- 底层 scaffold service 会同时生成 `pz.jsonc`、`pz.develop.jsonc`、`pz.test.jsonc`、`pz.product.jsonc`、`.env`、`.env.develop`、`.env.test`、`.env.product`，但它不作为公开根命令暴露。
+- 默认 `.env` 模板应覆盖当前正式项目常用 env 键面，并显式排除 `PZ_AGENT*` 与 `SEO_OPS*` 这类非当前正式 settings 真相源。
+- 默认 `pz.develop.jsonc` / `pz.test.jsonc` / `pz.product.jsonc` 也必须生成标准环境覆盖骨架，不能退回空 `{}`。
+- `pz env` / `pz settings` / `pz startapp` / `pz app|dev|pub` 都是正式顶层命令协议的一部分。
+- 这些命令由 `pz` 基础包直接提供；官方 `contrib` 组合不是前置条件。
+- `pz startapp <name>` 负责生成符合正式约定的最小子包骨架。
+- 生成骨架默认包含 `urls.py`、`pages/`、`templates/`、`static/`、`models.py` 等目录，并对齐 MVC 心智与“前端展示 / AJAX + API”约定。
+- `pz app add <app_id>` 是项目装配编排命令，依次复用版本查询、精确声明、安装与 settings 原子能力；默认选择兼容的最新稳定版本，也接受 `--version <version>`，且不向 `apps/` 写源码。
+- `pz app update <app_id>` 复用同一编排，默认升级到兼容的最新稳定版本，也可精确切换版本；`pz app versions <app_id>` 是无副作用的版本查看原子命令。
+- `pz app add <app_id>` / `pz app update <app_id>` 永远按 distribution 名称安装，也不回退为源码仓 `editable` 安装；若能从正式 `publish` target 解析出私有索引 `check_url`，则只复用这份索引元数据补全安装认证。
+- `pz app declare <app_id>` / `pz app add <app_id>` 不接管 `apps/<app_id>` 中业务拥有的真实源码；切回 package 模式前必须先由业务 Git 工作流收敛该目录。
+- `pz app add <app_id>` / `pz dev add <source>` / `pz dev link <source>` 完成后都必须检查结果状态；若多个项目本地源码位置同时暴露同一 `app_id`，命令直接报错，并给出标准人工处理指引。
+- 运行时发现阶段若项目源码扫描范围与环境中已安装 distribution 同时都可导入同名最小子包，则正式优先级固定为项目源码优先。
+- `pz dev add <app-or-source>` 编排 `dev source cache -> dev source import -> settings update -> env sync -> dev ide sync`；Git 来源默认使用 `develop` 分支，当前用户隔离的系统临时 cache 存在时先更新、不存在时 staged clone，再按固定 full commit 导入一个最小子包到 `apps/<app_id>`。app 目录、source mode、provenance 与宿主 dependency/`tool.uv.sources` 在同一原子事务落位，最终不保留嵌套 `.git`，导入结果由业务仓管理。
+- `pz dev link <repo-or-app>` 保留现有 `apps/.sources/<repo_key>` checkout 与 `apps/` binding 模型，用于上游源码联调。
+- `pz dev update <app_id>` 只更新 manifest 中的 linked checkout，不更新业务仓拥有的真实目录，也不进入发布链。
+- `pz dev unlink <binding>` 只移除 linked 源码暴露，不删除业务仓真实目录，也不隐式移除项目声明。
+- `pz pub <app_id>` 是正式单包发布编排入口，按顺序执行 package-scoped release commit、`<distribution>@<version>` annotated tag 与 build/upload；不自动升级版本号，不执行 `git push`。
+- `pz pub commit` / `pz pub tag` / `pz pub upload` 是单一职责原子命令，供编排、验证和失败续跑复用。
+- `pz pub batch <app_id>...` 是上层编排命令，只按你显式给出的顺序依次执行完整单包 `pub`，不隐式推断依赖顺序。
+- 发布目标的非敏感配置可以写入项目根 `pz.jsonc` 的 `publish` / `publish.targets.<name>`；若在源码仓根直接发布，则写入源码仓根 `pyproject.toml` 的 `tool.pz.publish`；凭证仍应通过环境变量提供。
+- `pz pub` 会优先使用当前进程环境中的发布凭据；若当前项目根存在 `.env`，会把其中同名凭据补入子进程环境，但不覆盖已显式导出的环境变量。
+- 发布命令既可以在标准项目根执行，也可以在源码仓根执行；项目根读取 `pz.jsonc`，源码仓根读取根 `pyproject.toml`，不要求额外再包一层 `apps/`。
+- 当前正式 devpi 发布目标采用通用命名 `devpi_dev`、`devpi_prod` 与 `devpi_pub`，目标地址与环境变量名写在各源码仓根 `pyproject.toml` 的 `tool.pz.publish`，实际凭证由当前 deploy 仓的 `docker-compose/devpi/.env` 或等价 shell 环境变量提供。
+- `pz settings init` 只用于“目录已存在但还没有 `pz.jsonc`”的场景；如果项目已经执行过 `pz env init` 或 `pz dev init`，通常不再执行这个命令。
+- `pz settings init` 在缺失时也会补齐 `pz.develop.jsonc`、`pz.test.jsonc`、`pz.product.jsonc`、`.env`、`.env.develop`、`.env.test`、`.env.product`，但不会覆盖已有 env / jsonc 文件。
+- 若确实需要按当前已发现的最小子包重新生成托管区块，可显式执行 `pz settings init --force` 覆盖现有 `pz.jsonc`。
+- `pz settings update <target>` 用于把当前项目里目标 app 的默认配置同步进现有 `pz.jsonc`。
+- `pz settings refresh-agents` 只刷新项目根 `AGENTS.md` 里的 pz 托管区块，不改用户手写内容。
+- `pz settings reset-agents` 会把项目根 `AGENTS.md` 重置为当前正式托管块；这是整份文件重置，不保留用户手写内容。
+
+源码仓根 `pyproject.toml` 的发布目标示例：
+
+```toml
+[tool.pz.publish]
+default_target = "devpi_pub"
+
+[tool.pz.publish.targets.devpi_pub]
+publish_url = "https://packages.example.test/packages/pub/"
+check_url = "https://packages.example.test/packages/pub/+simple/"
+username_env = "DEVPI_OWNER"
+password_env = "DEVPI_OWNER_PASSWORD"
+install_username_env = "DEVPI_INSTALL_USER"
+install_password_env = "DEVPI_INSTALL_PASSWORD"
+```
+
+对应发布示例：
+
+```bash
+set -a
+source <deploy_repo_root>/docker-compose/devpi/.env
+set +a
+cd <app_repo_root>
+pz pub catalog --target devpi_dev --project-dir .
+```
+
+## 仓库关系
+
+按照当前设计文档口径，最终只有两个 Git 管理边界：`pz` 是唯一正式基础仓，`pz_apps` 是承载其余最小子包的逻辑源码仓。`pz_apps` 沿用既有物理 Git 远端，不再新建第三个仓库。
+
+- `pz`
+  - 定位：唯一正式基础包与唯一启动壳，负责稳定合同、发现协议、`RuntimePlan` 编译、统一 CLI 主链与通用启动协议。
+  - GitHub：[JiXiangTools/pz](https://github.com/JiXiangTools/pz)
+- `pz_apps`
+  - 定位：承载平台、站点运行时和其它非最小基础能力的最小子包；逻辑 source-root 与 distribution 名称使用 `pz_apps` / `pz-apps-source-root`。
+  - Git 远端：[JiXiangTools/pyzza_platform](https://github.com/JiXiangTools/pyzza_platform)
+
+补充说明：
+
+- `pz_contrib` 是官方最小子包源码容器与官方通用装配实现；在任一宿主里都应通过当前 `[tool.uv.sources]` 或对应源码仓解析出它的正式真相源，而不是把某个固定目录名当 contract，但它本身不形成独立运行时 namespace。
+- `pz` 通过稳定合同承载扩展点；平台能力和站点能力应分别在对应源码仓内按最小子包落地，而不是回写到基础层。
+
+## 设计依据
+
+本 README 按 `pz` 正式设计文档口径编写。
+
+如果本 README 与 `pz` 设计文档、正式 contract 或正式装配约定冲突，以 `pz` 设计文档为准。
+
+- [`03-App最小子包规范`](pz规范与使用/03-App最小子包规范.md)
+- [`10-测试与契约规范`](pz规范与使用/10-测试与契约规范.md)
+- [`14-分层与扩展规范`](pz规范与使用/14-分层与扩展规范.md)
+- [`15-子包开发使用手册`](pz规范与使用/15-子包开发使用手册.md)
+- [`21-contrib约定与Provider接入规范`](pz规范与使用/21-contrib约定与Provider接入规范.md)
+
+## 文档索引
+
+总索引：
+
+- [pz 规范与使用](pz规范与使用/README.md)
+
+架构与分发：
+
+- [00-pz架构总纲](pz规范与使用/00-pz架构总纲.md)
+- [01-目录与分层规范](pz规范与使用/01-目录与分层规范.md)
+- [02-包与分发规范](pz规范与使用/02-包与分发规范.md)
+- [14-分层与扩展规范](pz规范与使用/14-分层与扩展规范.md)
+
+开发与约定：
+
+- [03-App最小子包规范](pz规范与使用/03-App最小子包规范.md)
+- [04-Settings与配置规范](pz规范与使用/04-Settings与配置规范.md)
+- [09-CLI与Worker入口规范](pz规范与使用/09-CLI与Worker入口规范.md)
+- [15-子包开发使用手册](pz规范与使用/15-子包开发使用手册.md)
+- [21-contrib约定与Provider接入规范](pz规范与使用/21-contrib约定与Provider接入规范.md)
+
+测试与治理：
+
+- [10-测试与契约规范](pz规范与使用/10-测试与契约规范.md)
+- [11-仓库真相源地图](pz规范与使用/11-仓库真相源地图.md)
+- [12-构建与发布检查清单](pz规范与使用/12-构建与发布检查清单.md)
+- [26-cutover完工检查清单（历史）](pz规范与使用/archive/中间态/26-cutover完工检查清单.md)