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/18-/346/211/251/345/261/225/347/202/271/345/206/262/347/252/201/350/243/201/345/206/263/346/200/273/350/241/250.md

@@ -0,0 +1,131 @@
+# 扩展点冲突裁决总表
+
+本文档固定 `pz` 扩展点的统一冲突裁决规则。
+
+## 1. 总原则
+
+- 冲突必须在编译期裁决
+- 不允许静默覆盖
+- 不允许按 import 顺序或最后加载者获胜
+- 同优先级冲突默认直接报错
+
+## 2. 单例型扩展点
+
+以下扩展点在一个项目内最终只能有一个生效对象：
+
+- `host.builder`
+
+裁决规则：
+
+1. 先按 `priority` 排序
+2. 最高优先级唯一者生效
+3. 若最高优先级不唯一，直接报错
+
+## 3. 多实例可并存扩展点
+
+以下扩展点默认允许多个对象并存：
+
+- `settings.provider`
+- `cli.tool`
+- `route.contribution`
+- `middleware.contribution`
+- `lifecycle.contribution`
+- `resource.contribution`
+
+裁决规则：
+
+- `id` 不冲突时可并存
+- 同类同 `id` 时进入冲突裁决
+
+## 4. `replace` 的适用范围
+
+`replace` 不是通用字段，只适用于显式支持替换语义的扩展点。
+
+v1 正式允许：
+
+- `middleware.contribution`
+
+v1 不允许：
+
+- `host.builder`
+- `settings.provider`
+- `cli.tool`
+- `route.contribution`
+- `lifecycle.contribution`
+- `resource.contribution`
+
+## 5. 各扩展点裁决规则
+
+### 5.1 `host.builder`
+
+- 单例
+- 按 `priority` 裁决
+- 同优先级冲突直接报错
+
+### 5.2 `settings.provider`
+
+- 默认可并存
+- provider patch 在目标路径层面再做冲突检测
+- 同目标路径同优先级冲突直接报错
+
+### 5.3 `cli.tool`
+
+- 默认可并存
+- `command` 路径冲突时按 `priority` 裁决
+- 同优先级冲突直接报错
+
+### 5.4 `route.contribution`
+
+- 默认可并存
+- 路由实际冲突由 route manifest 编译器裁决
+- 不允许依赖运行期去重和后处理重排兜底
+
+### 5.5 `middleware.contribution`
+
+- 默认可并存
+- 若显式 `replace=<middleware_id>`，则替换目标必须存在
+- 多个对象同时替换同一目标时，按 `priority` 裁决
+- 同优先级冲突直接报错
+
+### 5.6 `lifecycle.contribution`
+
+- 默认可并存
+- 排序按：
+  - `phase`
+  - app dependency order
+  - `priority`
+- 同 `phase` 同 `id` 冲突直接报错
+
+### 5.7 `resource.contribution`
+
+- 默认可并存
+- 覆盖顺序不由 `priority` 主导，而由 `installed_apps` 展开顺序主导：按 `installed_apps` 从前到后合并，同相对路径资源由后面的 app 覆盖前面的 app
+- `templates/`、`static/`、`locales/`、`pages/`、`template_config/` 都属于这套正式资源覆盖语义，不能在子系统里单独定义第二套扫描或优先级规则
+- `migrations/` 也属于这套正式资源覆盖语义
+- 运行时若消费 merged 资源目录，只能把它视为编译产物；作者修改必须回原始子包资源目录
+- `priority` 只用于极少数明确声明的冲突裁决点
+
+## 6. 冲突输出最小结构
+
+所有冲突诊断至少应包含：
+
+- `kind`
+- `id`
+- `owner_app`
+- `code`
+- `message`
+- `contenders`
+- `resolution`
+
+其中：
+
+- `contenders`
+  - 冲突对象摘要列表
+- `resolution`
+  - `error` / `selected:<id>` / `replaced:<id>`
+
+## 7. 正式结论
+
+- 编译期冲突裁决是唯一正式冲突治理链
+- `priority` 只用于显式裁决，不用于掩盖协议不清
+- `replace` 只能出现在正式声明允许的扩展点上

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/19-/351/224/231/350/257/257/347/240/201/344/270/216/350/257/212/346/226/255/345/215/217/350/256/256.md

@@ -0,0 +1,176 @@
+# 错误码与诊断协议
+
+本文档固定 `pz` 基础层的错误码与诊断协议。
+
+## 1. 总原则
+
+- 正式失败语义必须依赖稳定 `code`，不能依赖自由文本
+- CLI、HTTP、编译器、检查器对同类错误应共享同一编码体系
+- 诊断对象必须可机器读取、可测试、可审计
+
+## 2. 最小诊断对象
+
+所有正式诊断对象至少应包含：
+
+- `code`
+- `message`
+- `stage`
+- `owner`
+- `action`
+
+按需字段：
+
+- `detail`
+- `scope`
+- `severity`
+- `request_id`
+- `path`
+- `app_id`
+- `kind`
+
+## 3. 错误阶段分类
+
+正式 `stage` 集合：
+
+- `project`
+- `settings`
+- `app_registry`
+- `extensions`
+- `runtime_plan`
+- `cli`
+- `http`
+- `worker`
+- `infra`
+
+## 4. 错误码前缀
+
+建议固定前缀：
+
+- `PZ_PROJECT_*`
+- `PZ_SETTINGS_*`
+- `PZ_APP_*`
+- `PZ_EXTENSION_*`
+- `PZ_RUNTIME_PLAN_*`
+- `PZ_CLI_*`
+- `PZ_HTTP_*`
+- `PZ_WORKER_*`
+- `PZ_INFRA_*`
+
+## 5. 必须稳定编码的错误类别
+
+### 5.1 项目与配置
+
+- project dir 无效
+- `pz.jsonc` 无效
+- 环境文件无效
+- settings schema 冲突
+- app settings provider 冲突
+- runtime override 非法
+
+### 5.2 app 与扩展点
+
+- 重复 `app_id`
+- `required_pz` 不满足
+- app dependency cycle
+- 扩展点 `id` 冲突
+- `host.builder` 冲突
+- middleware replace 目标不存在
+- lifecycle phase 非法
+
+### 5.3 运行图编译
+
+- route manifest 冲突
+- middleware manifest 冲突
+- resource manifest 冲突
+- CLI command 冲突
+- `RuntimePlan` 缺失必要 section
+
+### 5.4 执行阶段
+
+- host build 失败
+- worker 启动失败
+- infra 缺失
+- request 级运行时错误
+
+### 5.5 Git release 与发布
+
+- `PZ_PUB_GIT_REQUIRED`：当前仓库根不匹配目标且 `apps/.sources` 中没有可用 Git 仓库；中文消息固定为 `当前仓库根与 apps/.sources 中都没有可用的发布 Git 仓库：<app_id>`
+- `PZ_PUB_APP_NOT_FOUND`：存在 Git 仓库，但未在其中发现目标子包；中文消息固定为 `未在 apps/.sources 的 Git 仓库中找到子包：<app_id>`
+- `PZ_PUB_APP_AMBIGUOUS`：多个 Git 仓库发现同一目标子包；中文消息固定为 `在 apps/.sources 的多个 Git 仓库中发现同一子包：<app_id>`
+- `PZ_PUB_SHARED_CHECKOUT_READ_ONLY`：唯一命中的 Git 仓库是外部共享只读 checkout；中文消息固定为 `apps/.sources 中的共享 Git 仓库为只读，无法发布子包：<app_id>`
+- `PZ_PUB_GIT_DETACHED_HEAD`：目标 Git worktree 当前处于 detached HEAD
+- `PZ_PUB_GIT_IDENTITY_MISSING`：Git author 或 tagger identity 未完整配置
+- `PZ_PUB_GIT_INDEX_DIRTY`：Git index 已存在调用方 staged 内容
+- `PZ_PUB_GIT_SCOPE_AMBIGUOUS`：未提交 shared-root 内容无法安全归属单一子包
+- `PZ_PUB_RELEASE_COMMIT_CONFLICT`：当前 HEAD 或既有 release commit 与目标 app/version 不一致
+- `PZ_PUB_TAG_CONFLICT`：目标 package tag 已存在但 commit 或 annotation 不一致
+- `PZ_PUB_RELEASE_STATE_INVALID`：release commit、tag annotation、tagged `project.version` 或 wheel metadata 不一致
+- `PZ_PUB_REMOTE_ARTIFACT_CONFLICT`：远端同 distribution/version artifact identity 或 hash 不一致
+
+上述错误统一使用 `stage=cli`，并携带 `app_id`、package path、distribution、version 与已完成 stage 等非敏感上下文。Git remote、publish URL 与底层异常输出必须先移除内嵌凭据。
+
+### 5.6 Dev 编排与 IDE 影子投影
+
+- `PZ_DEV_CACHE_INVALID`：当前用户隔离的系统临时 Git cache root、lock、checkout 或 owner marker 无法通过 owner、权限、非符号链接或结构校验
+- `PZ_DEV_CACHE_REMOTE_MISMATCH`：已有 cache 的 canonical remote identity 与请求仓库不一致
+- `PZ_DEV_CACHE_REFRESH_FAILED`：cache fetch、分支更新或目标 revision 固定失败；不得静默回退到陈旧 revision
+- `PZ_DEV_CACHE_RESOLUTION_MISSING`：import 或失败续跑无法证明 cache 中仍存在请求的 immutable full revision
+- `PZ_DEV_IDE_PROJECT_INVALID`：已有 `.idea` / `.vscode` 不是可安全维护的真实目录，或 PyCharm project XML 不是可解析结构
+- `PZ_DEV_IDE_VSCODE_SETTINGS_INVALID`：`.vscode/settings.json` 不是可保留更新的 JSONC，或 `python.analysis.extraPaths` 不是字符串数组
+- `PZ_DEV_IDE_VSCODE_STATE_INVALID`：PZ-owned VS Code entry 状态账本缺失、损坏或与 settings 不一致
+- `PZ_DEV_IDE_TRANSACTION_INCOMPLETE`：发现上次中断的 IDE 投影事务，需要先恢复或完成旧 pair
+- `PZ_DEV_IDE_PROJECTION_INVALID`：可见 app 投影包含缺失、重复、越界、整个 checkout 或未绑定叶子 source root
+- `PZ_DEV_IDE_SYNC_FAILED`：PZ-owned PyCharm/VS Code 投影无法完成 staged replace 或恢复
+- `PZ_DEV_ORCHESTRATION_INCOMPLETE`：源码原子阶段已成功，但后续项目 source、settings、environment 或 IDE 原子阶段失败；按 `next_stage` 调用公开原子命令继续，具备可证明 provenance 的 `dev add` 可在重跑时自动跳过已完成导入
+
+IDE 错误 detail 只允许暴露 project-relative path；linked external absolute path 必须脱敏或转换为 app/repo identity。编排错误必须报告 `completed_stages`、`next_stage` 与原始稳定错误码，不得通过删除业务源码、reset checkout 或覆盖用户 `.idea` 内容伪装全局回滚。
+
+### 5.7 App 版本解析与安装
+
+- `PZ_APP_INDEX_QUERY_FAILED`：无法从正式索引读取目标 distribution 的版本信息
+- `PZ_APP_VERSION_NOT_FOUND`：显式版本不存在，或默认解析没有得到可安装的稳定版本
+- `PZ_APP_VERSION_INCOMPATIBLE`：候选版本不满足 Python、发行包依赖图或当前项目约束；app 声明中的 `required_pz` / protocol 仍由运行时编译合同校验
+- `PZ_APP_SOURCE_OWNERSHIP_CONFLICT`：`app declare/add` 发现 `apps/<app_id>` 已由业务仓真实源码拥有，拒绝把 package 声明反向接管该路径
+- `PZ_APP_VERSION_STATE_MISMATCH`：项目精确声明、`uv.lock` 与当前已安装 metadata 无法收敛到同一版本
+- `PZ_APP_ORCHESTRATION_INCOMPLETE`：版本已解析或前置原子阶段已成功，但后续声明、安装、lock 或 settings 阶段失败，需要前向续跑
+
+版本错误统一使用 `stage=cli`，并携带 `app_id`、distribution、请求版本与经过脱敏的 index identity。认证信息、带凭据 URL 和底层工具原始命令行不得进入诊断输出。
+
+`app add/update` 编排错误必须同时报告已选择的精确版本、`completed_stages` 与 `next_stage`；`app rm` 没有版本选择，只报告阶段信息。已成功的 declaration、lock、安装或 undeclare 阶段不得通过跨命令隐式回滚伪装成全局原子事务；`app add/update` 可按声明、lock 与 installed 状态自动跳过已完成原子阶段，其他情况按 `next_stage` 显式继续。
+
+## 6. 各入口输出协议
+
+### 6.1 CLI
+
+- `--json` 模式下必须输出稳定错误对象
+- exit code 非 `0` 时必须带 `code`
+
+### 6.2 HTTP
+
+- error envelope 必须带 `code`
+- request 级错误应带 `request_id`
+- 公共 `message` 与内部 `detail` 必须分层
+
+### 6.3 CheckReport
+
+- 每条检查项必须带：
+  - `code`
+  - `severity`
+  - `owner`
+  - `scope`
+
+## 7. 安全约束
+
+正式错误与诊断输出不得直接回显：
+
+- 密码
+- token
+- DSN
+- 宿主机绝对私有路径
+- 原始第三方异常敏感文本
+
+## 8. 正式结论
+
+- 错误码是正式协议，不是实现细节
+- 同类错误不得在不同入口发明不同 code
+- 没有稳定 `code` 的失败，不算完成协议设计

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/20-/347/247/201/346/234/211/345/214/205/344/273/223/344/270/216/347/273/237/344/270/200/350/256/244/350/257/201/351/203/250/347/275/262/350/247/204/350/214/203.md

@@ -0,0 +1,243 @@
+# 私有包仓与统一认证部署规范
+
+本文用于固定 `pz` 当前正式的私有包仓方案、安装口径与统一认证约定。
+
+## 1. 目标
+
+需要同时解决三件事：
+
+- 正式安装不走 Git，而走标准 Python distribution
+- 上传与下载安装使用同一套简单授权
+- 浏览器访问、`pip`、`uv` 的行为保持一致
+
+## 2. 正式结论
+
+当前正式方案固定为：
+
+- 私有包仓：`devpi`
+- 对外入口：`HTTPS` 域名
+- 反向代理：`Nginx Proxy Manager`
+- 统一认证：入口层 `Basic Auth`
+- 包仓协议：标准 PyPI-compatible simple index
+
+当前不采用的方案：
+
+- 正式安装走 Git URL
+- 正式发布物直接依赖本地源码 checkout
+- 上传一套口令、下载安装另一套口令
+- 匿名公开整个 `devpi` 站点
+
+一句话口径：
+
+- 正式发布、上传、安装都走 `devpi`
+- 正式访问统一走 `HTTPS`
+- 上传与下载安装统一使用一组 Basic Auth 凭据
+
+## 3. 安装与源码边界
+
+必须严格区分：
+
+- 源码获取 / 开发联调
+- 正式安装 / 正式发布
+
+正式要求：
+
+- Git 只负责源码获取、开发联调与版本管理
+- `devpi` 才是正式安装与正式发布入口
+- 用户侧正式安装只允许：
+  - `pip install ...`
+  - `uv add ...`
+  - `uv publish ...`
+
+不允许：
+
+- 把 `git clone` 或 `pip install git+...` 当作正式安装方案
+- 把本地工作区目录直接当成正式交付边界
+
+## 4. 当前正式拓扑
+
+正式链路固定为：
+
+1. 浏览器 / `pip` / `uv`
+2. `https://<private-domain>`
+3. `Nginx Proxy Manager`
+4. `Basic Auth`
+5. `devpi`
+6. 对应 index，例如 `packages/prod`
+
+当前实现要求：
+
+- `devpi` 本身只监听内部回源地址
+- 对外域名必须通过反向代理暴露
+- `DEVPI_OUTSIDE_URL` 必须写最终对外 `HTTPS` 域名
+
+如果把 `DEVPI_OUTSIDE_URL` 写成：
+
+- `http://<ip>:3141`
+- `http://127.0.0.1:3141`
+- 其它内部回源地址
+
+则 `devpi` 会把页面链接和静态资源生成为错误的 HTTP 地址，浏览器会出现 `Mixed Content`。
+
+## 5. 统一认证模型
+
+当前正式认证模型固定为两层共用一组凭据：
+
+- 外层：Nginx Proxy Manager `Basic Auth`
+- 内层：`devpi` 用户认证
+
+正式约定：
+
+- Basic Auth 用户名 = `DEVPI_OWNER`
+- Basic Auth 密码 = `DEVPI_OWNER_PASSWORD`
+- `DEVPI_ROOT_PASSWORD` 只用于初始化与管理员维护，不作为日常安装/上传账号
+
+当前共享账号模型的定位：
+
+- 用于统一浏览器访问
+- 用于 `pip` 下载安装
+- 用于 `uv` 下载安装
+- 用于 `uv publish` 上传
+
+这样做的目的只有一个：
+
+- 上传与下载安装只保留一组简单授权
+
+## 6. 反向代理硬约束
+
+如果使用 `Nginx Proxy Manager`，`Advanced` 配置必须包含：
+
+```nginx
+auth_basic "Restricted devpi";
+auth_basic_user_file /data/access/devpi.htpasswd;
+proxy_set_header Authorization $http_authorization;
+```
+
+这三行缺一不可：
+
+- `auth_basic` 负责统一入口认证
+- `auth_basic_user_file` 负责 Basic Auth 口令文件
+- `proxy_set_header Authorization $http_authorization;` 负责把同一组凭据继续透传给 `devpi`
+
+如果不透传 `Authorization`：
+
+- 浏览器访问可能正常
+- 但 `devpi` 上游拿不到上传认证头
+- 结果会变成“能进站、不能上传”
+
+## 7. 正式命令示例
+
+假设：
+
+- 用户名：`packages`
+- 密码：`<password>`
+- 域名：`https://packages.example.test`
+
+安装：
+
+```bash
+pip install --index-url "https://packages:<password>@packages.example.test/packages/prod/+simple/" pz
+```
+
+```bash
+uv add --index "https://packages:<password>@packages.example.test/packages/prod/+simple/" pz
+```
+
+安装官方扩展组合：
+
+```bash
+pip install --index-url "https://packages:<password>@packages.example.test/packages/prod/+simple/" "pz[contrib]"
+```
+
+```bash
+uv add --index "https://packages:<password>@packages.example.test/packages/prod/+simple/" "pz[contrib]"
+```
+
+上传：
+
+```bash
+uv publish --publish-url "https://packages:<password>@packages.example.test/packages/prod/"
+```
+
+## 8. 公共依赖继承
+
+如果私有包 `A` 依赖公开包 `B`，正式处理方式不是把 `B` 重新打进私有仓源码树，而是让私有 index 继承公开 PyPI。
+
+当前正式约定：
+
+- `packages/dev` 必须继承 `root/pypi`
+- `packages/prod` 必须继承 `root/pypi`
+
+这意味着：
+
+- 私有包从 `packages/dev` 或 `packages/prod` 获取
+- 公开依赖从继承链上的 `root/pypi` 获取
+- 客户端仍然只需要配置一个私有入口域名
+
+因此，像下面这种情况是允许的：
+
+- `pz` 或某个 `<app_id>` 在私有仓
+- 它依赖的 `httpx`、`requests`、`pydantic` 等公开包不在私有上传列表
+- 安装时仍然通过 `packages/prod -> root/pypi` 正常解算
+
+当前 `devpi` 部署的正式索引要求就是：
+
+- `packages/dev bases=root/pypi`
+- `packages/prod bases=root/pypi`
+
+如果未来某个环境不希望继承公开 PyPI，那必须作为一次性整体策略切换处理，而不是让不同环境长期并存两套 index 继承规则。
+
+## 9. 账号职责
+
+当前正式职责划分：
+
+- `root`
+  - 只负责 `devpi` 初始化、重置、管理员维护
+- `packages`
+  - 负责日常上传
+  - 负责下载安装
+  - 负责浏览器访问
+
+如果未来需要更细粒度审计，再拆成：
+
+- 只读下载账号
+- 上传账号
+- 管理员账号
+
+不引入第二套正式方案。
+
+## 10. 部署真相源
+
+当前部署真相源位于：
+
+- `deploy/docker-compose/devpi/`
+
+其中关键文件为：
+
+- `docker-compose.yml`
+- `Dockerfile`
+- `.env`
+- `bootstrap.sh`
+- `devpi-entrypoint.sh`
+- `nginx.devpi.conf.example`
+- `nginx_proxy_manager.basic_auth.conf.example`
+
+部署说明与示例配置以该目录为准，不再另起第二套部署文档。
+
+## 11. 当前正式约束总结
+
+- 正式安装不走 Git，只走私有包仓
+- 私有包仓当前正式方案固定为 `devpi`
+- 对外入口必须是 `HTTPS` 域名
+- 上传与下载安装共用一组简单授权
+- `Basic Auth` 与 `devpi` 认证必须使用同一组共享凭据
+- 反向代理必须透传 `Authorization`
+- `DEVPI_OUTSIDE_URL` 必须等于最终对外 `HTTPS` 域名
+- `packages/dev` 与 `packages/prod` 必须继承 `root/pypi`
+- 目标发布合同下，`pz pub upload` 原子命令负责把 `DEVPI_OWNER` / `DEVPI_OWNER_PASSWORD` 注入 `uv publish` 上传链；`pz pub` 编排命令复用该能力，不在 commit/tag 阶段暴露上传凭据
+- `pz app add` / `pz app update` 在命中正式 devpi `check_url` 时，应自动把 `DEVPI_INSTALL_USER` / `DEVPI_INSTALL_PASSWORD` 注入安装链
+- `pz app versions` 与 `pz app add` / `pz app update` 复用同一正式索引发现和安装认证链，不允许再引入第二套版本查询凭据
+- `pz app add` / `pz app update` 未指定版本时只从已认证索引解析兼容的最新稳定版本，指定 `--version` 时验证并安装精确版本；解析结果必须以精确版本进入项目声明和 lock
+- 版本查询、解析失败与 `--json` 诊断只允许输出脱敏后的 index identity，不得回显 Basic Auth、环境变量值或带凭据 URL
+
+如果后续需要迁移到其它制品平台，必须整体替换这套正式方案，而不是长期并存两套私有包仓口径。