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/15-/345/255/220/345/214/205/345/274/200/345/217/221/344/275/277/347/224/250/346/211/213/345/206/214.md

@@ -0,0 +1,1004 @@
+# 子包开发使用手册
+
+> settings 正式口径：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取；`settings.py` / `settings/` 只负责声明，不再作为运行时读取入口。
+> namespace 正式口径：最小子包是唯一正式运行时单位；标准 `apps.py` 是运行时发现入口真相源。每个最小子包默认统一采用 `app_id = <app_id>`、目录名 = `<app_id>`、import 包名 = `<app_id>`、distribution = `<distribution-name>`。`pz` 与 `pz_apps` 只是并列的源码组织根，不进入运行时 namespace。
+> 命名口径：新建子包默认让目录名、import 包名与 `app_id` 对齐；不强制 `pz`、`pz` 或其它特定技术前缀。历史子包已发布的 `app_id` 与 import 包名以稳定值为准，不因文档命名口径变化自动迁移。
+本文档是高频使用手册。
+
+本文按正式架构口径描述：
+
+- `pz` 是唯一正式基础包，也是唯一可以独立启动的包
+- 其它最小子包统一作为 `pz` 的插件按 `installed_apps` 自动加载
+
+目标不是重复所有设计文档，而是给日常开发一个最短可执行版本：
+
+- `pz` 和子包怎么分层
+- 子包应该怎么写
+- 新增功能时先改哪里
+- 改完以后怎么验证
+
+日常开发还必须先按 [`25-面向对象开发规范`](./25-面向对象开发规范.md) 判断对象边界：这个能力是 contract object、compiler object、runtime owner、facade、provider、adapter、service，还是纯函数。判断不清楚时，不应先新增 helper、全局状态或临时 import。
+
+## 1. 四层边界
+
+### `pz`
+
+只放稳定合同：
+
+- app registry / runtime plan / lifecycle
+- 统一 settings 编译与 `settings_center.settings.<app_id>` 读取协议
+- host builder 发现协议
+- 资源加载协议
+- CLI 分发协议
+- 唯一启动壳
+
+不放：
+
+- 官方 host 具体实现
+- 业务逻辑
+- 单个项目的快捷路径
+
+### `pz_settings_center`
+
+只放应用层 settings surface：
+
+- `settings_center.settings`
+- project/app settings 正式读取入口
+- app settings provider 正式注册入口
+- 物理源码固定落在 `pz/pz_contrib/pz_settings_center/`
+
+不放：
+
+- 业务逻辑
+- 第二套配置读取链
+- 宿主级快捷 wrapper
+
+### `pz_contrib`
+
+只放随 `pz-cli` 默认安装的最小基础能力：
+
+- `pz_foundation`
+- `pz_settings_center`
+- 根 `pz-cli` 单 wheel 构建与依赖元数据
+
+可以直接依赖：
+
+- `pz-cli`（提供 `pz_core`、`pz_foundation` 与 `pz_settings_center` Python 包）
+- 其他基础子包的正式公开面
+
+### 其它最小子包
+
+只作为插件声明自己的能力：
+
+- `apps.py`
+- `urls.py` 或 `urls/`
+- `settings.py` 或 `settings/`
+- `public.py`
+- `extensions()`
+- `startup()/shutdown()`
+
+不自己造 host，不自己补第二套框架，不独立启动。
+
+如果该子包含页面开发：
+
+- 目录组织默认遵循 MVC 心智
+- `urls.py` 或 `urls/` 只放 URL 和入口函数
+- 前端只负责展示层，数据交互优先走 AJAX + 后端 API
+
+### 宿主项目
+
+只保留：
+
+- 单一 `main.py`
+- `pz.jsonc`
+- `pz.{env}.jsonc`
+- 项目配置
+- 宿主特有少量扩展
+
+不允许自己重新组装通用 Web host。
+
+## 2. app 最小结构
+
+推荐最小结构：
+
+- `<app_id>/apps.py`
+- `<app_id>/configs/default.jsonc`
+- `<app_id>/configs/default.env`
+- `<app_id>/configs/__init__.py`
+- `<app_id>/urls.py` 或 `<app_id>/urls/`
+- `<app_id>/settings.py` 或 `<app_id>/settings/__init__.py`
+- `<app_id>/public.py`
+- `<app_id>/models.py`
+- `<app_id>/templates/`
+- `<app_id>/static/`
+- `<app_id>/locales/`
+- `<app_id>/pages/`
+- `<app_id>/migrations/<app_id>/`
+
+说明：
+
+- 最小子包目录名默认使用 `<app_id>`
+- `app_id` 默认等于目录名，也就是 `<app_id>`
+- distribution 固定为 `<distribution-name>`
+- 运行时发现只认标准 `apps.py`：文件内必须有 app class、class 上用静态字符串声明 `id`、模块级 `app = <AppClass>()`，并能解析出合法 `app.id`
+- 非 app 模块不得把普通 CLI、工具、路由聚合或 helper 文件命名为 `apps.py`
+- 顶层源码组织根与其下的容器目录若存在，只是 Git 分组容器，不参与 import 与 `app_id`
+- `installed_apps` 的正式语法固定为目录名；目录名可以是最小子包，也可以是容器目录，不接受路径或 `<pkg>.apps:app`
+- 默认项目配置会把 `apps` 声明为 `installed_apps` 扫描目录；运行时不硬编码 `apps`，而是按当前配置展开，配置声明 `apps` 时只发现 `apps/` 下业务仓真实目录与经过 manifest 校验的可见 binding，物理 `apps/.sources/` checkout 不直接贡献 app
+- 同一 `app_id` 同时存在于项目源码扫描范围和当前解释器已安装 distribution 时，项目源码优先；同一 `app_id` 在项目源码范围内出现多份时必须人工收敛
+- 如果 `installed_apps` 同时出现容器目录和显式叶子 app，作者面工具应在写回时自动压平成单一叶子 app 顺序，不保留 `"apps" + 显式 app` 这类双轨真相
+- 只要包已安装且进入 `installed_apps`，`pz` 就按约定自动发现、编译、组装和加载
+- 分发包 `pyproject.toml` 必须把 `configs` 声明为正式子包，并把 `configs/default.jsonc` 与 `configs/default.env` 打入 package-data；常规写法至少包含 `<app_id>.configs`、`*.jsonc`、`**/*.jsonc`、`*.env`、`**/*.env`
+- 如果 app 提供页面声明，统一放在 `pages/`；分发包必须把该目录下的 `*.jsonc` 打入 package-data
+- 宿主业务子包可以维护自己的迁移演进；`apps/.sources` 中的官方/共享包只保留 `0_*` 数据库 init 文件，不新增 `1_*` 及后续迁移文件
+
+### 2.1 pages 约定
+
+`pages/` 是页面声明目录，用来承载页面中心的正式页面输入，同时避免把页面列表、页面路由与页面 payload 塞进 settings。
+
+目录边界固定如下：
+
+- `configs/`：只放 app settings 默认值、secret 模板与配置 schema 配套输入
+- `pages/`：只放页面中心可编译的页面声明
+- `apps.py`：只声明 app 能力、provider、lifecycle、worker、extension
+- `public.py`：只暴露稳定公开 facade
+- provider 模块：只放实现逻辑
+
+页面文件组织推荐如下：
+
+- `pages/base.jsonc`
+- `pages/<namespace>/base.jsonc`
+- `pages/<namespace>/<page>.jsonc`
+
+命名空间规则固定如下：
+
+- 页面声明拥有独立的页面配置命名空间
+- 页面配置命名空间和 settings namespace 一样必须稳定、单一、可审计
+- 页面配置命名空间固定由 `owner_app + 页面相对路径` 确定
+- 不允许再单独声明 `page_namespace`、`module_page_namespace` 或任何同义字段
+- `pages/base.jsonc` 属于当前 owner app 的根页面命名空间，不是无主的全局页面
+
+不要再创建独立的页面注册文件。页面声明统一进入 `pages/`，并由 `pz_page_center` 负责 schema、校验、冲突裁决和编译诊断。
+
+`pages/` 属于正式资源目录。它和 `templates/`、`static/`、`locales/`、`template_config/`、`migrations/` 一样，统一进入资源发现、合并和编译主链；运行期不再单独扫描源码目录。
+
+demo、草稿、说明性样例应放到 owner 明确不扫描的位置。不要在页面声明里新增第二套开关；运行时启停属于 settings owner，源码声明是否参与页面编译属于目录约定。
+
+页面声明的具体字段与覆盖语义以 `pz_page_center` 设计文档和页面 schema 为准。作者侧只需记住：
+
+- `pages/` 是页面声明真相源
+- 页面配置命名空间由 `owner_app + 页面相对路径` 唯一确定
+- 页面中心消费的是合并后的 `pages/`
+- 页面运行时不重扫源码目录
+
+正式链路必须是：
+
+```text
+app registry
+  -> resource discovery
+  -> registrations discovery
+  -> owner schema validation
+  -> RuntimePlan / owner registry
+  -> Web / CLI / worker runtime
+```
+
+运行时不得临时到处读取 registration JSONC；否则会绕过“编译先于运行”，形成第二套运行图。
+
+### 2.2 对象结构约定
+
+最小子包不要求机械拆目录，但复杂度上来后必须按对象职责拆分。
+
+推荐边界：
+
+- `models.py` / `models/`：领域模型、持久化模型、typed value object。
+- `contracts.py`：本子包对外稳定合同、Protocol、命令对象、结果对象。
+- `facade.py`：对外消费面。
+- `runtime.py`：局部组合根或 runtime owner。
+- `service/`：应用服务，只做业务编排，不拥有框架装配。
+- `repository/`：持久化访问，不承担业务决策。
+- `adapters/`：第三方 SDK、HTTP、DB、CLI、浏览器等外部系统适配。
+- `providers/`：正式 provider 实现。
+- `public.py`：只导出稳定 facade / contract，不导出内部 helper。
+
+约束：
+
+- 有身份、生命周期、状态、不变量或可替换实现的能力，应使用对象表达。
+- 纯转换、小范围校验、无状态格式化可以保持函数。
+- `Manager` 只能管理多个同类 runtime/resource/lease；不得同时承担 settings、IO、编译、执行、诊断、CLI 输出。
+- 类依赖必须通过构造参数、factory、context、`RuntimePlan` 或正式 registry 注入，不在方法内部临时 import 具体实现。
+- 编译产物和 snapshot 视为不可变对象，执行阶段只消费，不原地改写。
+
+## 3. URL 约定
+
+URL 真相源固定为 `<pkg>.urls`。
+
+目录约定：
+
+- 简单 app 使用 `urls.py`
+- 复杂 app 使用 `urls/` 目录
+- 复杂 app 的正式入口固定为 `urls/__init__.py`
+
+写法要求：
+
+- 让 `urls.py` 或 `urls/` 像 Django 的 `urls.py` 一样可读
+- 只声明本 app 的路径结构、子模块 include 关系与稳定 namespace
+- `urls.py` 或 `urls/` 只放 URL 声明与 `urlpatterns` 导出
+- `urls.py` 不负责构建路由
+- 具体路由构建与绑定统一通过 `pz_foundation.routing` 的 `path(...)` / `include(...)` / `mount(...)` 完成
+- `urlpatterns` 的路径字符串统一使用 FastAPI / Starlette 原生 path 参数语法；既支持 `/{lang}/{module}/{slug}`，也支持 `/{lang:locale}/{slug}` 这类 convertor 形式
+
+尾斜杠规则：
+
+- 目录型页面 URL 统一以 `/` 结尾
+- 文件型 URL 不以 `/` 结尾
+- `urls.py` 只声明 canonical 版本；不要为了兼容访问同时手工声明两套尾斜杠路径
+- slash 规范化跳转由共享 host / routing 规则统一处理
+- 页面 canonical、hreflang、sitemap、redirect target 必须与正式 URL 规则一致
+
+不允许：
+
+- 在 `apps.py` 里组装 URL
+- 在 `startup()` / `lifespan` 里补挂正式路由
+- 业务包自己处理 prefix 挂载、全局排序、全局清理
+- 在 `urls.py` 里堆业务编排、复杂查询、页面配置拼装、数据访问细节、手工路由绑定或任何路由构建逻辑
+- 再发明一层难懂的 route DSL
+
+统一装配规则：
+
+- 官方 host 统一加载每个 app 的 `<pkg>.urls`
+- prefix 由上层统一挂载
+- 所有 app、mount、host routes 都加载完成后
+- 最后统一执行 `clean_and_reorder_routes()`
+
+推荐模式：
+
+```python
+from pz_foundation.routing import include, path
+
+from .views import demo_page
+
+
+app_name = "pz_demo"
+
+urlpatterns = (
+    path("/demo", demo_page, name="pz_demo:demo-page"),
+    include("pz_demo.api", path_prefix="/api", namespace="pz_demo.api"),
+)
+```
+
+### 3.1 页面开发目录心智
+
+如果子包涉及页面开发，目录组织应遵循 MVC 心智：
+
+- `models.py` 或 `models/`：数据模型与持久化结构
+- `views.py` 或 `views/`：页面入口函数与控制器职责；仅当 `urls.py` 需要拆分时使用
+- 页面入口函数：控制器职责，负责把请求接到模板渲染或 API 调用
+- `templates/`、`static/`：视图展示层
+
+这里的 MVC 是作者心智，不是要求框架再发明一套 MVC 基类。重点是职责分离：
+
+- `urls.py` 只做 URL 声明与 `urlpatterns` 导出，不负责构建路由
+- `pages/` 保留给页面声明目录，不用作页面入口实现模块名
+- 入口函数负责控制器职责
+- 模板和前端资源只负责展示
+- 业务数据读写与交互协议优先走正式后端 API
+
+### 3.2 前端与数据交互约定
+
+`pz` 对页面前端的默认约定是：
+
+- 前端部分优先只负责展示、交互增强与局部异步刷新
+- 数据交互尽可能通过 AJAX 调用后端 API 完成
+- 后端 API 是数据读写、校验、状态变更与业务规则的正式落点
+
+不建议：
+
+- 在模板脚本里长期维护复杂业务状态机
+- 让页面模板直接承担第二套数据聚合中心
+- 把核心业务协议埋进零散前端脚本，而不形成正式 API
+
+## 4. settings 约定
+
+settings 作者面默认模板固定为配对的 `<app_id>/configs/default.jsonc` 与 `<app_id>/configs/default.env`。
+
+其中：
+
+- `default.jsonc` 展示 app settings 的完整 key 树与默认/占位值
+- `default.env` 只展示 `.env` 层面的 password、secret、token、key 路径键等敏感覆盖项
+
+二者可以被 Git 追踪，并且只由 `pz settings init/update` 读取；启动阶段不得直接读取 app 包内的 `configs/default.jsonc` 或 `configs/default.env`。
+
+settings 声明模块固定为 `settings.py` 或 `settings/`。
+Python 运行时正式读取入口固定为 `settings_center.settings.<app_id>`。
+
+允许两种文件形态：
+
+- `settings.py`
+- `settings/__init__.py`
+
+无论使用哪种形态，运行时都不再直接 import 该模块读取配置。
+运行时只认：
+
+- `settings_center.settings.<app_id>`
+
+规则：
+
+- `configs/default.jsonc` 负责 settings init/update 的默认值模板
+- `configs/default.env` 负责 settings init/update 的密钥/密码/令牌/Key 占位模板
+- `settings.py` / `settings/` 负责 schema、校验、normalize、`__runtime_overrides__`
+- `AppSettings` 不再承载默认值真相源
+- 子包新增默认配置键后，必须通过 `pz settings update` 显式同步到项目根配置；启动阶段不得回退读取包内模板补值
+- 启动期缺必需配置时，错误应指向缺失配置路径并提示执行 `pz settings update`，而不是隐式读取 `configs/default.jsonc`
+- settings namespace 固定等于 `app.id`
+- 不允许在 `apps.py` 里再声明独立的 `settings_namespace`
+- 新建子包默认让 `app.id` 等于最小子包目录名；历史子包已发布的 `app.id` 以稳定值为准
+- `pages/` 不属于 settings 默认值真相源；settings 可以放协议开关，但不得承载完整页面声明列表
+
+不允许：
+
+- `apps.py` 再带一套默认配置
+- `urls.py` 或 `urls/` 再带一套默认配置
+- `public.py` 再带一套默认配置
+- `services/*` 直接成为第二套 settings 真相源
+- `settings.py` / `settings/` 在 import 阶段读取包内 `configs/default.jsonc`、包内 `configs/default.env`、项目 `.env*` 或进程环境变量
+- `configs/default.jsonc` 塞入页面列表、菜单列表、资源列表、页面 registry 或 payload blocks
+
+补充规则：
+
+- 脚手架应直接用最小子包目录名初始化 `app.id`
+- 进入运行时后，正式 namespace 只认 `<app_id>`
+- 没有最小子包身份的内部模块，不允许自己读一套独立配置
+- 这类模块只能：
+  - 读取所属最小子包的 settings namespace，也就是 `settings_center.settings.<app_id>`
+  - 或读取 `settings_center.settings.project.<field>`
+
+补充 auth 路由注册纪律：
+
+- 子包若需要声明“哪些 URL 由系统 auth 接管”，默认正式入口是 `configs/default.jsonc` 经 `pz settings init/update` 同步到项目 settings 后，再由 `settings.py -> route_policy` 完成 schema 与 normalize。
+- 只有当 app 的路由裁决超出 `route_policy` 的配置表达力时，才使用 `extensions() -> auth.route_policy_provider`。
+- `route_policy` 的常规字段固定为 `default_mode`、`auth_paths`、`public_paths`、`delegate_paths`；普通子包优先用这组配置表达，不要为常规受保护面再发明第二套私有 guard 语法。
+- 已安装的正式 auth owner 负责消费 `route_policy` 与 `auth.route_policy_provider`，并把已挂载路由编译成请求期唯一 route-policy 真相源。
+- `default_mode = "auth"` 表示“整个子包默认注册为受保护面，再用 `public_paths` / `delegate_paths` 开例外”；`default_mode = "public"` 表示“只注册 `auth_paths` / `delegate_paths` 等显式配置的 URL”。
+- 对需要稳定 delegate owner / public owner 的高级场景，可在 `route_policy` 里额外声明 `auth_owner`、`public_owner`、`delegate_owner`；这仍然属于正式 auth owner 的配置编译输入，不需要再包一层私有 provider。
+- `route_policy` 是否进入线上治理面，由 settings runtime owner 按 `AppSettings.__runtime_overrides__` 与内建治理规则消费，不由业务 app 自建第二套白名单。
+- 推荐每个最小子包都预留 `<app>/auth/` 空包作为高级 auth 注册保留位；默认保持为空，不要在尚未需要高级规则时把它变成第二套认证入口。
+- `auth.route_policy_provider` 只在 app 需要超出配置表达力的自定义规则时使用；不要为普通的默认公开面/受保护面再写第二套私有 middleware。
+- 但这些字段只属于编译输入；请求期唯一真相源仍是 auth owner 编译后的 runtime route policies。
+- 不允许再在业务 app 里保留第二套 `auth_guard` middleware、白名单中间件或独立未登录跳转协议。
+- 请求期认证细节属于正式 auth owner；普通子包不要假设 auth middleware 会为旧 token 或缺 claims token 在每个请求里回库补救。若确实需要最新用户资料，显式使用 auth owner 暴露的 model 依赖或公开面，而不是把默认 identity 解析当 ORM loader。
+
+推荐做法：
+
+- 初始模板默认生成 `configs/default.jsonc`、`configs/default.env` 与 `settings.py`
+- 只有当配置拆分需求变多时，再升级成 `settings/`
+
+项目级配置分层固定如下：
+
+- `configs/default.jsonc`：各 app 的 settings init/update 默认值模板，不是启动期读取来源
+- `configs/default.env`：各 app 的 Git 可追踪 `.env` 层密钥占位模板，不是启动期读取来源
+- `pz.jsonc`：项目基础装配与全局静态覆盖
+- `pz.{env}.jsonc`：按环境的项目静态覆盖，例如 `pz.develop.jsonc`、`pz.test.jsonc`、`pz.product.jsonc`
+- `.env`：项目基础 secrets 与初始化提示来源
+- `.env.{env}`：按环境的 secrets 覆盖，例如 `.env.develop`、`.env.test`、`.env.product`
+- 显式环境变量：覆盖 `.env.{env}`
+
+推荐加载顺序：
+
+1. settings 声明
+2. `pz.jsonc`
+3. `pz.{PZ_ENV}.jsonc`
+4. `.env`
+5. `.env.{PZ_ENV}`
+6. 显式环境变量
+
+运行时正式读取顺序：
+
+1. `SettingsSnapshot`
+2. app settings provider
+3. settings runtime override provider
+
+规则：
+
+- 未显式指定 `PZ_ENV` 时，正式默认环境固定为 `develop`
+- `product` 环境必须在启动命令或进程环境中显式指定
+- `.env.{PZ_ENV}` 只在环境已经确定后参与加载，不负责反向决定当前环境
+- `.env + .env.{PZ_ENV} + 显式环境变量` 构成受保护 env layer，静态 TOML 只补充它未给出的值
+- `pz.jsonc` / `pz.{env}.jsonc` / app `configs/default.jsonc` 的字段名统一使用 `lower_snake_case`；其中 app `configs/default.jsonc` 只作为 settings 工具模板来源
+- `.env` / `.env.{env}` 中用于 settings override 的路径键统一使用 `lower_snake_case`，例如 `project__base_url`、`<app_id>__secret_key`、`<app_id>__nested__password`
+- 真正的进程级环境变量保留大写命名，例如 `PZ_ENV`、`PZ_HOST_PROJECT_DIR`、`APP_PORT`
+- `APP_PORT` / `BASE_URL` 属于宿主 `main.py` 与 host settings override 的启动特例，不代表通用 settings env 应改成大写扁平键
+- 项目级 JSONC 负责项目装配与静态覆盖，不负责替代 secrets 输入
+- 项目正式配置文件名固定为 `pz.jsonc`
+- JSONC 的正式读写必须统一通过 `pz/utils/project_jsonc/`
+- 工具注释独占前缀固定为 `// @pz:`
+- `pz settings init` 生成 `pz.jsonc` 时，应通过 `// @pz:managed:start <path>` / `// @pz:managed:end <path>` 维护托管区块
+- 正式托管区块固定为 `installed_apps`、`middlewares`
+- `middlewares` 托管区由工具按当前已发现 app 编译 conventional middleware manifest 生成；`pz settings update` 时若项目已写入显式 middleware 顺序，则应保留该顺序并把新发现 middleware 按 conventional 顺序补入
+- 若项目需要主动回收历史 middleware 顺序漂移，正式入口是 `pz settings update --reset-middlewares-order`
+- grouped init 命令复用的底层 scaffold service 默认同时生成 `pz.jsonc`、`pz.develop.jsonc`、`pz.test.jsonc`、`pz.product.jsonc`、`.env`、`.env.develop`、`.env.test`、`.env.product`
+- `pz settings init` 在这些文件缺失时也必须补齐，但不得覆盖已存在的 env / jsonc 文件
+- `.env` 必须写入默认 env 模板；`.env.develop` / `.env.test` / `.env.product` 只写环境差异覆盖模板
+- 已安装 app 的 `configs/default.env` 必须在 `pz settings init/update` 时合并进项目 `.env*`：`.env` 写入未注释占位符，`.env.{PZ_ENV}` 写入注释占位符；若项目文件已有同名变量，必须保留现有值
+- `pz.develop.jsonc` / `pz.test.jsonc` / `pz.product.jsonc` 必须写入环境级 JSONC 覆盖骨架，承载非敏感静态覆盖；不要把它们留成长期空对象
+- 默认 `.env` 模板应参考当前正式项目常用 env 键，并排除 `PZ_AGENT*`、`SEO_OPS*` 这类非当前正式 settings 真相源配置
+- `project_default.jsonc` 属于 `pz` 的通用作者面默认骨架，不属于 app 私有默认值真相源
+- `project_default.jsonc` 当前没有正式扩展点；不要试图为它增加 app / contrib / 宿主侧补丁入口
+- `configs/default.jsonc` 属于各最小子包自己的 settings 作者面默认模板，是 `pz settings init/update` 的输入，不是启动期 settings 编译输入
+- `configs/default.jsonc` 可以声明受控的顶层路由默认值 `routing.default_language`、`routing.all_supported_languages`、`routing.language_aliases`；`pz settings init/update` 会把它们提升到根 `routing`，并从 `apps.<app_id>` 私有配置里剥离
+- `configs/default.jsonc` 可以声明受控的顶层快捷命令 `commands`；`pz settings init/update` 会把它们提升到根 `commands`，同名命令以 app 默认刷新，未声明的项目自定义命令保留
+- `configs/default.jsonc` 可以声明受控的项目装配状态 `apps.*.sources.source_mode`；`pz settings init/update` 会把该字段提升到根 `apps` 对应 owner，作为 local/git/package 源码策略的单一真相
+- `configs/default.env` 属于各最小子包自己的 secret 模板，是项目 `.env*` 的生成提示来源，不是启动期 settings 编译输入
+- 当前版本不定义正式的初始化骨架扩展协议；不要为业务默认值发明第二套 init 命令、profile 参数或隐式注册器
+- app 私有作者面模板固定为自己的 `configs/default.jsonc` / `configs/default.env`；项目级通用默认骨架只来自 `pz` 内建的 `project_default.jsonc`
+- 未知 `// @pz:*` 工具注释应识别但默认忽略，不得作为当前版本的报错原因
+- 普通 `// ...` 注释只作为说明文本，不参与配置语义；工具写回时应尽量保留，但不承诺字节级原样保留
+
+宿主入口快捷环境变量补充规则：
+
+- 宿主入口允许读取的大写快捷变量固定为：
+  - `APP_HOST`
+  - `APP_PORT`
+  - `APP_RELOAD`
+  - `APP_WORKERS`
+  - `UVICORN_LOOP`
+  - `UVICORN_HTTP_IMPL`
+  - `UVICORN_LOG_LEVEL`
+  - `UVICORN_PROXY_HEADERS`
+  - `UVICORN_FORWARDED_ALLOW_IPS`
+  - `UVICORN_ACCESS_LOG`
+- 其中与 `project` 小写字段语义相同的快捷变量，必须在 settings 编译链中以最高优先级回写到最终 `SettingsSnapshot.project`
+- 当前正式映射固定为：
+  - `APP_HOST -> project.app_host`
+  - `APP_PORT -> project.app_port`
+  - `APP_WORKERS -> project.app_workers`
+  - `APP_RELOAD -> project.app_reload`
+  - `BASE_URL -> project.base_url`
+  - `STATIC_TARGET_PATH -> project.static_target_path`
+  - `STATIC_TARGET_OWNER -> project.static_target_owner`
+- 上述映射只描述宿主启动快捷层；项目配置文件和 `.env` 内的正式 settings 键仍然使用 `project__...` / `<app_id>__...`
+- 这意味着 `settings_center.settings.project.app_host` / `app_port` / `app_workers` / `app_reload` 读取到的是环境变量覆盖后的最终值
+- `APP_HOST` 只表示监听地址，不属于 `project.base_url` 的别名
+- `base_url` 表示站点对外访问基址；监听地址与对外基址是两个不同语义，不允许混用
+- 若项目根已存在 `pz.jsonc`，`pz settings init` 默认必须拒绝覆盖；只有显式传入 `--force` 时，才允许强制重置项目 settings 配置
+- `pz settings init --force` 必须在删除/重建前自动备份当前 `pz.jsonc`、`pz.{env}.jsonc` 与 `.env*` 到 `.runtime/backups/pz-update-settings/`
+- `pz settings init --force` 的语义是删除相关 settings 配置后按当前可发现 app 集重新生成，而不是在旧 `pz.jsonc` 上做保留式 merge
+- `pz settings init --force` 发现 app 时必须重新扫描当前项目 `apps/` 容器；若旧 `installed_apps` 显式声明了外部正式 app，也应作为发现输入保留，但不得因此漏掉当前本地 app
+- `pz settings update` 只补充默认值中新出现的键，不覆盖项目已写入的现有值
+- 上述“不覆盖”只适用于项目作者显式写入的业务值；如果 app 在 `settings.py` / `settings/` 中声明了正式 normalize 规则，`pz settings update` 只允许做当前稳定合同内部的归一化，不再承担历史别名或旧键迁移
+- 这类收口必须由 app 自己在 `settings.py` / `settings/` 中声明，不允许宿主手改 `pz.jsonc` 作为长期方案
+- `pz settings update <target>` 可只同步指定最小子包的默认配置
+- `pz settings update --reset-middlewares-order` 可按当前 conventional middleware manifest 重写托管区顺序，用于从历史显式顺序回收到当前正式默认序
+
+如果某些最小子包配置只能在 app 启动后确定：
+
+- 优先通过 `extensions()` 声明 `settings.provider`
+- 不要自己再造一套 settings service
+- provider 只补充运行态值，不承担 DB/Redis/基础 client 连接配置真相源
+- 如果底层存在 `register_app_settings_provider(...)` 一类 API，也只应作为正式 `settings.provider` 实现内部细节，而不是业务侧第二入口
+
+如果某些字段允许线上热更新：
+
+- 统一在 `AppSettings.__runtime_overrides__` 里写详细配置对象
+- 由 settings runtime owner 从 `AppSettings.__runtime_overrides__` 提取 schema，并通过正式 `settings.provider` patch 进入统一 settings 合并链
+- schema 注册后，settings runtime owner 只认这套声明；不会再接受手写旁路白名单
+- 这些热更新字段应在 `configs/default.jsonc` 中给出对应 settings init/update 模板默认值；若字段允许 `None` 且 TOML 不能表达空值，可暂时省略
+
+mode 语义固定为：
+
+- `live`
+  - 当前进程立即生效
+- `refresh`
+  - 写入后等待运行态 refresh 链路生效
+- `restart_required`
+  - 写入后等待进程重启生效
+
+额外约束：
+
+- `__runtime_overrides__` 里每个 key 都必须真的存在于 `AppSettings`
+- 每个 value 都必须是详细配置对象，不能再写字符串、tuple/list 简写
+- 错误 mode、错误字段名、错误 type hint 必须在注册期直接报错
+- `route_policy` 属于正式保留的 runtime override surface；app 若声明了该字段，settings runtime owner 可自动暴露该对象，不要求每个 app 再手写第二份 route-policy 白名单。
+
+推荐：
+
+```python
+__runtime_overrides__ = {
+    "enabled": {
+        "mode": "live",
+        "label": "启用开关",
+    },
+    "limit": {
+        "mode": "refresh",
+        "label": "数量限制",
+        "description": "调整后，新请求会读取新的限制。",
+    },
+}
+```
+
+不要继续：
+
+- 手写一份脱离 `AppSettings` 的 runtime override 白名单
+- 让 settings runtime owner 自己猜哪些字段可热更新
+- 同时保留 tuple/list 简写、字段级标记等多套声明方式
+
+### 4.1 共享站点首帧与会话启动约定
+
+首屏展示与首帧稳定的统一真相源固定为 `23-首屏展示与首帧稳定规范.md`。
+本节只保留高频开发提醒；若与 `30` 冲突，以 `30` 为准。
+
+站点型页面固定遵循一条正式主线：
+
+- 首帧稳定由 shared site UI owner 负责
+- 用户态启动链由 shared site UI owner 的正式 user runtime 统一负责
+- 用户态变更事件只允许由 shared site UI owner 的正式 user runtime 派发
+
+业务 app 的页面脚本不要做这些事：
+
+- 在页面启动时再次主动调用共享会话检查
+- 在业务脚本里自行派发共享用户态变更事件
+- 用旧 DOM overlay、refresh shell、快照壳一类旧页面状态复用方案解决刷新抖动
+
+共享层能统一治理的内容：
+
+- SSR 首帧必须直接输出稳定可见状态
+- 能从当前请求直接判定的状态，必须优先 SSR 输出最终态
+- 只有依赖纯客户端判定的临时 UI，SSR 才默认隐藏，初始化后再 reveal
+- 首屏关键资源用 eager / high priority
+- 初始化测量阶段不暴露中间态动画
+- 对外部可见且需要 SEO 的 HTML 页面，首屏所需稳定翻译必须优先由后端按当前页面和当前语言直接输出
+- 上述页面的前端翻译请求只能用于非首屏交互区块、异步组件或缺词补拉，不得作为首屏正文真相源
+
+业务侧仍需自己遵守的内容：
+
+- 业务自定义 widget 如果依赖异步配置，默认先隐藏，拿到确认配置后再渲染
+- 业务脚本不得再加第二条用户态启动链
+- 业务组件若必须按会话状态分支，只读取共享层已经收敛后的最终状态
+- 如果状态可由 `cookie`、`Accept-Language`、请求头、`module_config`、已编译 settings 直接判定，不要再做“SSR 先隐藏，客户端再纠正”的二次方案，应直接让 SSR 输出最终首帧
+- 如果页面可被 CDN/代理缓存，SSR 输出与缓存头必须对齐最终受众，不能让“匿名缓存首帧 + 客户端再纠正登录态”成为正式方案
+- 匿名公开 HTML 的正式口径是：
+  - 浏览器侧 `Cache-Control: public, max-age=0, must-revalidate`
+  - CDN 侧 `Cloudflare-CDN-Cache-Control: public, max-age=<ttl_seconds>`，TTL 唯一来自 `apps.pz_foundation.cache_control.policies["http.public_html_cdn"].ttl_seconds`
+- 用户态 HTML 的正式口径是：
+  - `Cache-Control: private, no-store, no-cache, must-revalidate, max-age=0, s-maxage=0`
+  - `Cloudflare-CDN-Cache-Control: no-store`
+  - `Vary: Cookie, Authorization`
+- 若页面用户态依赖认证 cookie 集合，这个集合必须进入 app 的正式 settings/defaults/normalize 链；不要把“框架内建识别一部分、宿主配置再补一部分、CDN 规则再猜一部分”拆成三套真相源
+- 如果页面已有 SSR widget root / launcher / config，客户端只能 hydrate 现有节点，不要整块 `innerHTML` 重建
+- 页面级 required-post、heartbeat、轮询端点必须按页面或模块显式开启，不要在全局模板里默认给所有页面注入
+- cookie consent 只能处理合规展示、偏好持久化和 telemetry / ads / analytics consent 信号；不得控制支付、登录、上传、翻译、搜索、导航等页面功能
+- 即使用户拒绝 consent，或浏览器拒绝 `localStorage` / cookie 持久化，页面核心功能也必须继续可用；失败只能退化为“偏好无法持久化”
+- 公开页共享运行时里的会话检查、登出桥和通用请求头能力，应留在共享 base/runtime 正式主链；认证页专用动作和认证页表单逻辑应留在 `auth.js` 或认证页自己的页面脚本里，不要让首页/header 为了用户态检查继续捆绑认证页脚本。
+- 公开页共享运行时里的语言切换路径解析、语言偏好持久化和 `window.changeLanguage` 正式入口，也应留在共享 base/runtime 主链；`nav.js` 只负责导航 DOM 交互，不要再让 header、footer banner、语言推荐各自长出第二套语言跳转实现。
+- 共享公开页的 source 资产是作者真相源；develop / test 默认加载 source，不因为 `site.min.js` / `site.min.css` 文件存在而自动消费旧聚合产物。
+- `site.min.js` / `site.min.css` 只在 product 或显式 `ASSETS_COMBINE` 下作为正式构建产物加载；产物缺失时应走正式构建、检查失败或保守 source 回退，不用 inline 补丁掩盖旧聚合产物。
+- 共享 bundle 自身也应继续收敛职责边界：`site.min.js` 这类共享公开页 bundle 只应承载真正共享且偏首屏/偏全局的公共能力；像页脚增强、cookie banner、语言推荐、评论区、示例区块这类非首屏增强，不应因为“同属共享层”就继续默认卷进共享首屏 bundle。
+- 若上述共享增强脚本仍需要统一加载，应继续复用共享 runtime 现有的声明式加载主链，例如 header/footer/page deferred loader；不要因为 bundle 变轻，就在模板里再长出第四套散落 `<script>` 清单。
+- 对没有正式运行时职责的历史空壳脚本或兼容标记脚本，应优先从正式 bundle 和正式 loader 清单中移除，而不是长期保留在公开页主链里增加请求和解析负担。
+- 页面级正式聚合产物必须声明在页面 `page_config.asset_bundle`，再由 app 通过 `site_assets.page_bundle` 扩展公开给共享层统一构建；不要在模板、模块配置或宿主里再维护第二套页面资源清单。
+- `page_config.asset_bundle` 至少应稳定声明页面 bundle `key` 与正式输出路径；页面模板默认优先消费共享层已生成的页面 bundle，只有在 bundle 缺失时才允许短期 fallback 到拆分资源。
+- 若页面需要把非首屏交互脚本延后到接近视口再加载，正式声明位固定为页面 `page_config.deferred_js`；共享 runtime 统一按声明加载，不允许在模板里手写第三套脚本清单。
+- `page_config.deferred_js` 只用于非首屏增强脚本，例如下半屏组件、评论区、示例区块等；首屏关键交互仍应留在 `page_config.asset_bundle` 的 critical bundle 中。
+- 已安装的检查 / 预检 owner 可以通过 `public.get_check_facade()` 接入 `pz check`；页面 bundle 等具体 blocking 检查项归其 owning 子包文档维护，新增子包必须通过正式检查链，而不是依赖宿主兜底。
+- 若业务覆盖了首屏 hero 的图片源，必须同时在页面 `hints` block 中为首屏图片补对应的 `rel="preload" as="image"`；共享层只能为约定内的共享默认 hero 资源提供通用预加载
+- 若页面属于 SEO/landing/公开关键词页/博客/帮助页等可缓存公开页面，首屏翻译网络请求目标应为 `0`
+- 不要为了图省事把整模块或整站翻译全集注入 HTML；只允许输出当前页面首屏实际需要的最小词条集合
+- `admin`、内部运营页、自用后台、强登录态工作台可按交互效率优先，不强制要求首屏翻译请求为 `0`
+
+## 5. `apps.py` 约定
+
+`apps.py` 是最小子包元信息入口。
+
+标准形态固定为：
+
+- 定义一个 app class
+- class 上声明 `id`、`name`、`version`、`required_pz`
+- `id` 使用静态字符串，不依赖 settings 常量、环境变量、函数调用或运行时计算
+- 模块级暴露 `app = <AppClass>()`
+- `app.id` 是 settings namespace、migration owner、extension owner 与诊断身份的唯一真相源
+
+`apps.py` 是 app 入口保留名。非 app 模块不应使用这个文件名；例如 runtime CLI、普通命令分发、工具集合、路由聚合等应使用更具体的文件名。
+
+应主要放：
+
+- `id`
+- `name`
+- `version`
+- `required_pz`
+- `requires_apps`
+- `extensions()`
+- `startup()/shutdown()`
+
+不应把这些东西继续塞回去：
+
+- URL 主链
+- 默认配置模板来源或运行时读取入口
+- 本地 host 壳
+
+`extensions()` 返回值应统一采用结构化扩展对象，而不是裸函数、隐式 import path 或模块级全局注册。
+
+扩展对象应是声明期 contract object；其中挂载的 provider、builder、tool、handler 必须是稳定对象实现，不能依赖 import-time 副作用完成注册。
+
+推荐所有扩展点共享一个最小公共头：
+
+- `kind`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+
+然后再挂各自专用字段。
+
+最常用的三类扩展对象形状固定如下：
+
+- `host.builder`
+  - `builder.build(ctx) -> HostBuildResult`
+  - 用于产出唯一最终 host
+- `settings.provider`
+  - `provider.provide(ctx) -> tuple[SettingsPatch, ...]`
+  - 用于补充运行时 settings patch
+- `cli.tool`
+  - `tool.configure(parser) -> None`
+  - `tool.run(ctx) -> int`
+  - 用于暴露正式 app CLI 命令
+
+不要在 `extensions()` 里返回：
+
+- 裸字符串
+- 任意 import path
+- 未带 `kind/id/owner_app` 的匿名函数
+- 依赖 import 时副作用才能生效的隐式注册器
+
+## 6. `public.py` 约定
+
+`public.py` 是稳定公开面。
+
+只有明确要给其它 app 依赖的 facade / helper 才能从这里出。
+
+优先从 `public.py` 暴露窄 facade、Protocol、命令对象、结果对象或 factory；不要把内部 service、repository、adapter、SDK client、session、pool、临时 cache 作为跨包公开面。
+
+跨子包依赖规则固定如下：
+
+- `pz_contrib` 可以直接 import `pz`
+- 其它最小子包可以依赖 `pz` 的正式公开面
+- 除 `* -> pz` 外，其它业务子包默认不要直接 import 另一个子包的内部实现
+- 非官方维护最小子包的跨包依赖，优先走对方的 `public.py`
+- 如果是进程边界或服务边界能力，优先走 HTTP / API / 明确声明的 provider
+- 只有明确声明为正式公开面的模块，才允许成为跨子包依赖入口
+
+不要让其它最小子包直接 import：
+
+- `service.py`
+- `manager.py`
+- 内部 adapter
+- 临时 runtime helper
+- `apps.py`
+- `urls.py` 或 `urls/`
+- `settings.py` 或 `settings/` 内部实现细节
+
+补充规则：
+
+- `settings.provider` 属于扩展点合同，不属于 `public.py` 读取入口
+- 跨包读取配置仍然只能走 `pz_settings_center`
+- `host.builder`、`settings.provider` 等 registry 扩展的具体实现可以放在子模块中，但正式暴露应通过 `extensions()` 返回结构化对象
+- app CLI 的正式暴露面固定为 `<app>/cli/<tool>.py` 中的模块级 `tool = CliToolSpec(...)`，并由 `pz` 编译进 `RuntimePlan.cli_manifest`
+
+## 7. 新增功能时的决策顺序
+
+按这个顺序判断：
+
+1. 能不能只改最小子包自己的 `urls.py` 或 `urls/` / `settings` / `extensions()`
+2. 能不能在 `pz_contrib` 增加官方通用处理
+3. 只有正式合同缺位时，才改 `pz`
+
+动代码前先补一个对象边界判断：
+
+- 谁是 owner？
+- 状态生命周期归谁？
+- 依赖是否已有 public surface / Protocol / provider contract？
+- 输出是否是结构化对象？
+- 是否会形成第二套 registry、loader、settings reader、path helper 或 runtime owner？
+
+一句话：
+
+- 先改子包
+- 再改 `pz_contrib` 容器里的官方通用实现
+- 最后才允许改 `pz`
+
+## 8. 工作区开发流程
+
+共享包改动必须直接在解析后的正式源码仓完成；当前工作区默认以项目 `.sources/...` 下解析出的真实 git 根为准，不在宿主里打补丁。
+
+标准流程：
+
+1. 在源仓修改
+2. 执行 `pz env sync`
+3. 跑宿主验证
+4. 执行 `pz run`
+5. 再看 `/health`
+
+标准命令：
+
+```bash
+pz env sync --project-dir /path/to/project
+pz run
+```
+
+补充说明：
+
+- 上述流程是当前工作区的共享包开发规则
+- 它不等于所有 `pz` 项目都必须把源码直接改在宿主目录里
+- 对普通 `pz` 项目，上层编排命令可以提供“把正式最小子包源码拉到项目本地开发目录”的能力
+- 但这类开发态源码拉取，不改变当前工作区“共享包真相源在解析后的正式源码仓”的规则
+- 宿主依赖同步的唯一作者面真相源应回到项目 `pyproject.toml` 的 `[tool.uv.sources]`
+- `apps/.sources/` 若存在，也只作为 `pz dev` 管理的开发态 checkout 承载区；它不再需要额外的工作区包清单
+
+### 8.1 项目开发态与发布态命令边界
+
+针对普通 `pz` 项目，上层命令边界固定如下：
+
+- `pz startapp <app_id>`
+  - 在项目 `apps/` 下创建一个正式最小子包骨架
+  - 只负责脚手架，不负责 distribution 安装与发布
+- `pz dev init`
+  - 作为新建开发项目的唯一正式编排入口
+  - 默认创建或复用项目骨架与默认本地 app，通过 `dev source cache` 固定官方 `pz_apps` revision，并把全部正式最小叶子导入 `apps/<app_id>` 交给业务仓管理
+  - 显式 `--link` 才保留原 bootstrap checkout；必须且只能搭配 `--clone-sources` 或 `--source-dir`
+  - 创建或复用项目根 `.venv`
+  - 所有源码原子阶段后只执行一次 settings、环境和 IDE 投影收敛；`--no-sync` 只跳过环境安装
+- `pz app init`
+  - 作为生产装配模型下的项目默认包初始化命令
+  - 只从已有 `apps/.sources` checkout 读取默认包名与内部 PyPI 安装位置
+  - 默认把 `.sources` 中所有正式最小 app 子包加入 `installed_apps`
+  - 创建或复用项目根 `.venv`
+  - 默认把 `pz-cli` 与这些正式最小 app 的已发布 distribution 安装进项目 `.venv`
+  - 安装必须走内部 PyPI / devpi，不得从源码 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
+  - `--no-sync` / `-S` 是跳过安装开关；默认行为会安装 distribution
+  - 按 source app 的 `requires_apps` 依赖关系写入 `installed_apps`
+  - 不 clone 源码、不发布 package
+- `pz app add <app_id>`
+  - 编排 `app versions -> app declare -> app install -> settings update`
+  - 默认解析并安装兼容的最新稳定版本；`--version <version>` 精确指定版本
+  - 把解析后的精确 distribution/version 写入项目声明和 `uv.lock`，不得把 `latest` 作为持久化值
+  - 不把源码写入项目 `apps/`
+- `pz app rm <app_id>`
+  - 编排 `app undeclare -> env sync -> settings update`，移除项目声明并收敛环境
+- `pz app update <app_id>`
+  - 默认把已声明 app 升级到兼容的最新稳定版本；`--version <version>` 精确切换版本
+  - 复用与 `app add` 相同的版本解析、精确声明和安装原子能力
+- `pz app versions <app_id>`
+  - 只读列出索引中的可用版本、当前声明版本、当前锁定版本与已安装版本
+  - 按 PEP 440 排序并标记 prerelease 和 yanked；默认最新版本选择不把它们作为候选
+- `pz app declare/undeclare/install`
+  - 分别拥有精确依赖声明、撤销声明和依赖环境收敛的原子事务
+  - `declare` 不接管 `apps/<app_id>` 中业务拥有的真实源码；同名真实目录存在时先用业务 Git 工作流收敛源码所有权
+  - 不隐式串联 settings 或其它阶段；上层 `app add/update/rm/init` 负责完整编排
+  - 编排跨原子阶段采用前向续跑：已完成阶段保留，失败时报告精确版本、`completed_stages` 与 `next_stage`
+- `pz dev add <app-or-source>`
+  - 编排 `dev source cache -> dev source import -> settings update -> env sync -> dev ide sync`；非 Git 本地输入跳过 cache
+  - 输入必须唯一解析到一个正式最小子包
+  - Git 来源默认使用 `develop` 分支；cache 命中时先更新，未命中时 clone，再从固定 full revision 导出目标源码
+  - 最终源码原子落位到 `apps/<app_id>`，不保留 `.git`、虚拟环境、cache 或构建产物
+  - 导入源码由业务仓统一管理；PZ 不自动更新、覆盖或删除
+  - 项目 `apps.<app_id>.sources.source_mode`、app provenance、宿主 dependency 与指向 `apps/<app_id>` 的 editable `tool.uv.sources` 在同一事务收敛
+  - Git provenance 记录无凭据 canonical source、full revision 与 leaf subpath；本地目录 provenance 只记录 `source = "local"`、不可逆 source identity 与 leaf subpath
+  - 允许传非 Git 本地目录，但遵守相同的唯一叶子解析、排除和校验合同
+  - 任意真实本地 app、linked binding 或其他项目本地路径已暴露相同 `app_id` 时直接失败；冲突按 app 身份判断，不按路径名称判断
+- `pz dev link <repo-or-app>`
+  - 编排 `dev source link -> settings update -> env sync -> dev ide sync`
+  - Git checkout 固定落在 `apps/.sources/<repo_key>`，受管 checkout 的目标分支固定为当前项目 `business_app_id`
+  - `apps/.sources/<repo_key>` 若已是外部共享 Git checkout 的符号链接，则直接只读复用，不切换共享目标分支
+  - 默认基础分支是 `develop`，显式替代值只有 `main`
+  - 允许直接传非 Git 本地目录；此时记录 direct link，不切换外部目录的分支
+  - 目录输入在 `apps/<repo_key>` 建立目录 binding；叶子输入在 `apps/<app_id>` 建立叶子 binding
+  - runtime 只发现 `apps/` 下的真实本地 app 和可见 binding，物理 `apps/.sources` 不贡献 app
+- `pz dev branch <repo-or-app>`
+  - 编排 `dev source branch -> env sync -> dev ide sync`
+  - 原子 source 阶段把已有受管 checkout 切到 manifest 业务分支
+  - worktree 必须 clean；不自动 stash、commit、merge、rebase、reset 或 push
+  - 共享 checkout 返回 `PZ_DEV_SHARED_CHECKOUT_READ_ONLY`
+- `pz dev update <repo-or-app>`
+  - 编排 `dev source update -> env sync -> dev ide sync`
+  - 只在 clean 的业务分支上执行 upstream fast-forward-only 更新
+  - 共享 checkout 返回 `PZ_DEV_SHARED_CHECKOUT_READ_ONLY`，由共享仓库 owner 在真实目录更新
+- `pz dev unlink <binding>`
+  - 编排 `dev source unlink -> settings update -> env sync -> dev ide sync`
+  - 只删除精确 binding 和对应快捷方式，默认保留 checkout
+  - `--delete-checkout` 仅在最后一个 binding 且没有未推送提交时允许
+  - 共享 checkout 的 `--delete-checkout` 只解除 `apps/.sources/<repo_key>` 链接，不删除外部目标
+  - 不删除 `pz dev add` 导入的业务仓真实源码
+- `pz dev source cache/import/link/branch/update/unlink`
+  - 分别拥有可丢弃 Git 获取 cache、业务源码导入、binding、linked Git 分支/更新和解除 binding 的原子事务
+  - `source cache` 只在当前用户隔离的 `<system-temp>/pz/users/<user-key>/git/` 创建或刷新 checkout；root、lock、checkout 与 owner marker 必须验证当前用户 owner、限制权限和非符号链接
+  - cache 结果必须携带 canonical `repo_key`、full commit 与不可变 resolution ref；失败续跑只验证已有 exact ref，cache/ref 丢失时明确失败
+  - Git 模式 `source import` 必须显式消费 `repo_key + full revision` 并验证 resolution ref，绝不读取 branch、`HEAD` 或 cache 最新状态；本地目录模式不需要 revision
+  - 不刷新 settings、环境或 IDE；日常人工入口使用上层 `dev add/link/branch/update/unlink`
+- `pz dev ide sync`
+  - 编译一次可见最小子包投影，并分别委托 PyCharm 与 VS Code provider
+  - PyCharm 原子维护 `.idea/pz.generated.sources.iml` 与 `modules.xml` 中唯一 PZ entry；linked app 登记 canonical 叶子根
+  - VS Code 结构化维护 `.vscode/settings.json` 中 PZ 插入的 `python.analysis.extraPaths`，使用项目可见叶子路径，并以 `pz.generated.sources.json` 区分用户与 PZ entries
+  - 不登记整个 `.sources` checkout，不复制源码，不进入运行时/发布真相；对应 IDE 目录不存在时 provider 返回 `not_applicable`
+- `pz pub <app_id>`
+  - 作为单包发布编排命令，依次执行目标子包 commit、package tag 与 build/upload
+  - 优先接受当前 Git 仓库根 distribution 的精确匹配，否则枚举 `apps/.sources` 并复用正式 workspace 子包发现程序搜索目标 app
+  - 不从业务仓复制目录发布；没有 Git、找不到目标、多个仓库重复命中分别失败
+  - 根 distribution 提交显式 `.` 整仓 scope；嵌套子包只提交目标路径，不提交同仓其他子包修改，不执行 `git push`
+- `pz pub commit <app_id>`
+  - 原子提交目标子包当前可发布源码，commit subject 固定为 `release(<app_id>): <version>`
+- `pz pub tag <app_id>`
+  - 原子创建 `<distribution-name>@<version>` annotated tag
+- `pz pub upload <app_id>`
+  - 要求当前 checkout clean 且 HEAD 等于 package tag commit，直接构建、验证 version/wheel 后 upload，不创建临时 worktree
+- `pz pub rm <app_id>`
+  - 只负责从目标 publish index 删除这个 distribution 的全部已发布版本
+- `pz pub batch <app_id>...`
+  - 作为上层编排命令，按显式给定顺序为每个 app 串行执行完整 `pub` 编排
+
+不要混淆：
+
+- `startapp` 是本地最小子包脚手架命令
+- `dev init` 是新项目开发编排命令
+- `app init` 默认是已有 `.sources` 到 distribution 安装清单、项目声明和项目 `.venv` 的生产装配命令；`--no-sync` 只完成声明与 settings 刷新，不创建 `.venv`
+- `app init` / `app add` / `app rm` / `app update` 是项目装配编排命令；`app versions` / `app declare` / `app undeclare` / `app install` 是可独立调用的版本与声明原子命令
+- `app update` 会刷新当前项目解释器环境中的已发布 distribution，而不改源码 checkout
+- `dev add` / `dev link` / `dev branch` / `dev update` / `dev unlink` 是日常编排命令；`dev source ...` 与 `dev ide sync` 是可单独验证和续跑的原子命令
+- `pub` 是 commit/tag/upload 发布编排命令
+- `pub commit` / `pub tag` / `pub upload` 是发布态原子命令
+- `pub rm` 是发布态删除命令
+- `pub batch` 是发布态编排命令
+- `app add` 的安装目标是当前项目解释器环境，不是 `apps/` 本地源码容器
+- `app add` / `app update` 永远按 distribution 名称安装，也不回退为源码仓 `editable` 安装
+- `app add` / `app update` 未指定版本时解析兼容的最新稳定版本，指定 `--version` 时只接受该精确版本；两种路径最终都必须持久化精确版本并更新 `uv.lock`
+- `app rm` 只允许移除已声明 app；若目标 app 未声明，命令必须报错，不得返回误导性的成功提示
+- 若项目 `publish` 或对应 source-root 的 `tool.pz.publish.targets.<name>.check_url` 已声明正式私有索引，`app add` / `app update` 可以只复用这份索引元数据补全安装认证；这不改变 distribution 安装语义
+- `app add` / `dev add` / `dev link` 完成后必须检查结果状态；若多个项目本地源码位置同时暴露同一 `app_id`，命令直接报错，同时给出标准人工处理指引
+- 运行时发现阶段若项目源码扫描范围与环境中已安装 distribution 同时都可导入同名最小子包，正式优先级固定为项目源码优先
+- `dev add` 的业务源码统一落在 `apps/<app_id>`；`dev link` 的真实 Git checkout 统一落在 `apps/.sources/<repo_key>`，输入粒度只决定 `apps/` 下建立目录 binding 还是叶子 binding
+- 叶子最小子包 repo 直接暴露目录；只有 monorepo 才需要仓库级 checkout 复用模型
+- 仅仅“同步源码到本地”不等于“可以发布”
+- `--base-branch` 只允许 `develop` 或 `main`，只决定业务分支首次创建点；direct link 不进入 Git 分支协议
+- 批量发布不推断依赖顺序；若存在依赖链，顺序必须由调用方显式给出
+- 单包 `pub` 不自动升级 `project.version` 或生成 changelog；版本必须在调用前明确
+- `pub` 只创建本地 release commit 与 annotated tag，不执行 `git push`
+- 后续阶段失败时保留已完成 commit/tag；重跑必须复用精确匹配状态并从未完成阶段继续
+
+正式要求：
+
+- 发布前必须有明确版本号
+- 发布前必须满足当前 Git root distribution 精确匹配，或 `apps/.sources` 中目标子包唯一命中
+- `project.version` 是 release version 真相源；tag 固定为 `<distribution-name>@<version>`
+- Git index 必须预先 clean；只允许目标 app path 进入 release commit
+- 其他正式最小子包的 unstaged 修改可以保留，未归属任何最小子包的 shared-root 未提交修改阻止单包发布
+- package tag commit 必须就是当前 clean HEAD；tag、`project.version`、wheel metadata 与远端 artifact identity 必须一致
+- `publish` 不得直接消费未版本化的源码目录状态
+- 顶层不再设计 `pz sync`；linked checkout 更新统一使用 `pz dev update`，业务仓源码更新统一走业务 Git 工作流
+- 若 `A`、`B` 两个最小子包属于同一个 Git 仓库，`pz dev link B` 必须复用因 `A` 已存在的本地仓库 checkout，而不是再次 clone 第二份；`pz dev add` 每次只导入调用方明确选择的一个最小子包，不保留共享 checkout
+- 根 distribution 可直接从自身 Git root 发布；嵌套目标源码仓仍通过宿主 `apps/.sources/<repo_key>` 暴露。源码仓根在 `pyproject.toml` 的 `tool.pz.publish` 下声明发布目标
+- 若调用时未在项目 `pz.jsonc` 中声明 `publish`，`pz pub` 必须从目标包根向上查找最近的 source-root `pyproject.toml`，并使用其中的 `tool.pz.publish`
+- 当前正式 devpi 发布目标分为 `devpi_dev`、`devpi_prod` 与 `devpi_pub`
+- 非敏感目标配置写在各源码仓根 `pyproject.toml` 的 `tool.pz.publish`，凭证通过当前 deploy 仓的 `docker-compose/devpi/.env` 或等价 shell 环境变量注入
+- `devpi_dev` 用于开发态验证与依赖闭环；`devpi_prod` 用于正式私有发布；`devpi_pub` 用于正式公开发布
+- `pz pub` 默认使用目标上的 `username_env` / `password_env` 解析上传凭据；若当前项目根存在 `.env`，CLI 可以把其中同名凭据补入子进程环境，但不覆盖已显式导出的环境变量
+- `pz pub rm` 与 `pz pub` 复用同一份 target 与凭据解析；当前正式只支持 devpi target
+- `pz app add` / `pz app update` 若命中正式 devpi `check_url`，默认使用 `DEVPI_INSTALL_USER` / `DEVPI_INSTALL_PASSWORD` 作为安装认证；若 target 显式声明 `install_username_env` / `install_password_env`，则以 target 配置为准
+
+发布锁：
+
+- 项目可以在 `pz.jsonc` 顶层 `extensions.publish_lock.targets` 里声明允许发布到特定索引的包名单
+- key 既可以写 index 分类：`pub` / `prod` / `dev`
+- 也可以写精确 publish target 名：例如 `devpi_pub` / `devpi_prod` / `devpi_dev`
+- 当 `pz pub` 命中对应锁时，只有 allowlist 里的 app / distribution 才允许继续发布
+
+示例：
+
+```jsonc
+{
+  "extensions": {
+    "publish_lock": {
+      "targets": {
+        "pub": ["pz-cli"],
+        "devpi_prod": ["pz"],
+        "dev": ["example-app"]
+      }
+    }
+  }
+}
+```
+
+发布目标示例：
+
+```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"
+
+[tool.pz.publish.targets.devpi_prod]
+publish_url = "https://packages.example.test/packages/prod/"
+check_url = "https://packages.example.test/packages/prod/+simple/"
+username_env = "DEVPI_OWNER"
+password_env = "DEVPI_OWNER_PASSWORD"
+install_username_env = "DEVPI_INSTALL_USER"
+install_password_env = "DEVPI_INSTALL_PASSWORD"
+
+[tool.pz.publish.targets.devpi_dev]
+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
+cd <pz_apps_repo_root>
+set -a
+source <deploy_repo_root>/docker-compose/devpi/.env
+set +a
+pz pub example-app --target devpi_dev --project-dir .
+```
+
+正式版本发布示例：
+
+```bash
+cd <pz_apps_repo_root>
+set -a
+source <deploy_repo_root>/docker-compose/devpi/.env
+set +a
+pz pub example-app --target devpi_prod --project-dir .
+```
+
+正式要求补充：
+
+- `devpi_prod` 只允许发布已经显式升级 `project.version` 的版本
+- 进入 `devpi_prod` 前，应先在 `devpi_dev` 完成上传与安装闭环验证
+- 若一个最小子包依赖同批次其它新版本子包，应先把依赖链发布到同一目标索引，再发布上层包
+
+## 9. 什么时候必须补契约测试
+
+这些场景必须补 source-repo 或宿主契约测试：
+
+- 改了 `urls.py` / `urls/` / URL 装配规则
+- 改了 `settings.py` / `settings/` 声明协议或 `settings_center.settings.<app_id>` 读取规则
+- 改了 provider 补值逻辑或热更新字段白名单
+- 改了 `public.py` 公开面
+- 改了 host builder / host assembly
+- 改了 scaffold 模板
+
+测试要锁死的是：
+
+- 正式真相源在哪里
+- 哪些旧写法不允许回流
+- 新人照着模板写不会再次走偏
+
+## 10. 最常见的错误
+
+不要再做这些事：
+
+- 把官方实现塞回 `pz`
+- 让多个最小子包各自提供独立启动壳
+- 在 `apps.py` 里重新拼 URL
+- 在 app 里造自己的 FastAPI host
+- 在多个文件里分散默认配置
+- 为了“灵活”再造一层别人看不懂的声明 DSL
+- 改了共享包却只在本地源码目录验证，不重装宿主环境
+
+## 11. 快速判断
+
+如果你只想快速判断一个改动应该落哪里：
+
+- 改 URL 聚合：先看 `urls.py` 或 `urls/`
+- 改默认配置模板：先看 `configs/default.jsonc`，再看 `settings.py` / `settings/`
+- 改 HTML / CDN 缓存边界：先看共享 middleware，再看对应 app 的 `configs/default.jsonc` 模板与 `settings.py` / `settings/`
+- 改公开依赖面：只看 `public.py`
+- 改官方通用 host：看 `pz_contrib`
+- 改合同层：最后才看 `pz`