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/19-core/345/215/225/344/270/200/346/255/243/345/274/217/346/226/271/346/241/210/346/224/266/346/225/233/346/211/247/350/241/214/346/270/205/345/215/225.md

@@ -0,0 +1,161 @@
+# 19-legacy_core 并入 pz 迁移执行清单
+
+> 历史说明：本文本身就是 `legacy_core -> pz` 的迁移执行记录，因此会保留大量 `legacy_core` 字样；当前正式基础包统一为 `pz`。
+
+本文档只定义一件事：
+
+- 把 `legacy_core` 作为历史过渡基础包并入 `pz`，完成单一基础包 cutover。
+
+适用边界：
+
+- 只处理基础层迁移、公开面迁移、命令迁移与契约治理
+- 不在 `legacy_core` 内继续补长期兼容层
+- 需要迁移的消费侧，迁到 `pz` 正式公开面，不保留双轨
+
+## 目标
+
+迁移完成后，系统必须满足：
+
+- 只有 `pz` 是正式基础包与唯一可独立启动的包
+- `legacy_core` 不再作为长期独立 distribution / import 面 / CLI 主入口
+- 正式命令、正式 Python API、正式 RuntimePlan 编译链全部收敛到 `pz`
+- 共享子包只依赖 `pz` 正式公开面
+
+## 总顺序
+
+按下面顺序执行，禁止跳步：
+
+1. 收 `pz` / `legacy_core` 基础层边界与目标公开面
+2. 收命令入口与 Python API 到 `pz`
+3. 收 import surface、distribution 与共享子包依赖
+4. 收扩展点合同与配置合同
+5. 清理 `legacy_core` 历史兼容别名与桥接入口
+6. 重跑契约、重装受影响共享包、重启宿主、跑宿主验证
+
+原则：
+
+- 先收正式公开面，再收消费侧
+- 每一步完成后都补契约测试
+- 不保留长期双轨
+- cutover 必须是一次性切换，不接受“先都支持着”
+
+## 阶段一：基础层目标公开面收口
+
+目标：
+
+- 明确 `pz` 是唯一正式基础包
+- 明确 `legacy_core` 仅作为短期迁移桥接
+
+范围：
+
+- 冻结 `pz` 最终必须保留的基础层协议模块
+- 冻结 `legacy_core` 最终不应继续承载的具体实现
+- 冻结 `pz` 的正式 CLI、正式 Python API、正式扩展点合同
+
+完成标志：
+
+- `pz` 成为文档、CLI、契约测试中的唯一基础包名
+- `legacy_core` 不再出现在新设计的正式示例里
+- `pz` 公开面清单稳定冻结
+
+## 阶段二：命令入口与 Python API cutover
+
+目标：
+
+- 所有正式命令与 Python API 收敛到 `pz`
+
+范围：
+
+- `legacy_core` CLI -> `pz`
+- `legacy_core check` -> `pz check`
+- `legacy_core db` -> `pz db`
+- `legacy_core <app_id> <tool>` -> `pz <app_id> <tool>`
+- `legacy_core.app:create_app` / `register_pz` -> `pz.app:*`
+
+完成标志：
+
+- 帮助文案、README、测试、宿主入口只使用 `pz`
+- CLI 与 Python API 共用同一条编译链
+- `legacy_core` 旧命令不再是正式主路径
+
+## 阶段三：import surface 与 distribution cutover
+
+目标：
+
+- 共享子包与宿主项目改为依赖 `pz`
+
+范围：
+
+- `pyproject.toml` 依赖切到 `pz`
+- import 面从 `legacy_core.*` 迁到 `pz.*`
+- 收 distribution、entrypoint、安装校验脚本
+
+完成标志：
+
+- 新增代码不再直接依赖 `legacy_core`
+- 宿主和共享包以 `pz` 为唯一基础依赖
+- `legacy_core` 不再是正式依赖链关键节点
+
+## 阶段四：扩展点与配置合同 cutover
+
+目标：
+
+- 扩展点与配置协议全面切到新合同
+
+范围：
+
+- `host.builder`
+- `settings.provider`
+- `cli.tool`
+- module config owner / settings surface owner / settings runtime owner 协作链
+- `required_pz` 字段与 app 元数据校验
+
+完成标志：
+
+- 运行时与编译期都只认新扩展点对象形状
+- 配置体系只保留单一运行时读取入口
+- 契约测试锁死新对象协议与冲突策略
+
+## 阶段五：清理 `legacy_core` 历史桥接
+
+目标：
+
+- 删除 `legacy_core` 中仍残留的历史兼容入口与桥接别名
+
+范围：
+
+- 删除历史命令入口
+- 删除历史 import shim
+- 删除历史别名与宽松兼容逻辑
+- 将 `legacy_core` 收敛为迁移期最小桥接壳，直至彻底下线
+
+完成标志：
+
+- `legacy_core` 不再是正式公开主路径
+- 历史桥接不再进入正式主链
+- 旧入口回流会被契约测试直接拦截
+
+## 验证要求
+
+每个阶段都要执行：
+
+1. source repo 本地契约测试
+2. `pz env sync --project-dir <host-project-dir>`
+3. 若 public surface 影响到共享包，再补宿主 `pz run` / `/health` 验证
+
+宿主最终要求：
+
+- 重启完成
+- `/health` 返回 `200`
+- 对应 host integration contract 通过
+
+## 当前执行决议
+
+阶段一处于文档冻结中。
+
+本轮优先执行：
+
+- 冻结 `pz` 基础层协议模块
+- 冻结扩展点对象合同
+- 冻结配置三层协作链
+- 为 `legacy_core -> pz` cutover 准备契约测试与宿主 smoke 要求

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/25-/345/215/217/350/256/256/345/210/260/346/272/220/347/240/201/345/267/256/350/267/235/346/270/205/345/215/225.md

@@ -0,0 +1,377 @@
+# 25-协议到源码差距清单
+
+> 历史说明：本文里保留的 `legacy_core` 只用于差距追踪、旧 owner package 记录与迁移尾项描述；当前正式基础包统一为 `pz`。
+
+本文档只做一件事：
+
+- 对照 `22-pz.protocols.v1 草案`、`23-扩展点冲突裁决总表`、`24-错误码与诊断协议`，记录源码差距的收口结果与剩余治理尾项。
+
+适用边界：
+
+- 不重复定义新协议
+- 不把迁移语境重新写回正式规则
+- 只记录“当前源码是否已经完成正式 cutover”
+
+## 1. 当前结论
+
+当前正式运行主链已经完成 cutover：
+
+- `required_core -> required_pz` 已完成
+- `settings.provider` 已成为正式主链
+- `host.builder`、`route`、`middleware`、`lifecycle`、`resource` contribution 已完成对象化
+- 正式 CLI 已收敛到 `pz`
+- 正式 Python API 已收敛到 `pz.*`
+- 宿主重装、重启、健康检查与关键契约测试已通过
+
+当前剩余事项只保留两类治理尾项：
+
+1. `workspace_packages.toml` 仍保留 `legacy-core` 的 migration-only source-repo 条目
+2. 少量迁移文档与仓库说明仍保留旧口径，用于记录 cutover 过程，而不是定义当前正式规则
+3. 多国语言资源治理仍停留在历史 `base + namespace` 约定，尚未完全映射到正式 locale bundle / consumer binding 协议
+
+本文档每条差距统一补充下面 5 类执行信息：
+
+- `owner repo`
+- `owner package`
+- `status`
+- `DoD ref`
+- `tests`
+
+## 2. 配置链差距
+
+本节差距已全部关闭。
+
+### 2.1 `settings.provider` 正式主链
+
+处理结果：
+
+- `SettingsProviderSpec` 已成为正式声明对象
+- `RuntimePlan` 已直接编译 provider manifest
+- provider 正式输出已统一为 `SettingsPatch`
+- settings surface owner 的 `public.py` 不再把命令式注册 API 作为稳定公开面
+- settings surface owner 不再公开 `load_app_settings()` / `load_typed_app_settings()` 这类第二读取 helper
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/legacy_core`
+  - `pz_framework/pz_contrib`
+- `owner package`
+  - `pz`
+  - settings surface owner
+- `status`
+  - `done`
+- `DoD ref`
+  - `C1`
+  - `C2`
+- `tests`
+  - 现有：settings provider 编译与 settings surface 契约测试
+  - 现有：宿主 settings smoke、runtime override smoke
+
+### 2.2 settings runtime owner 接入方式
+
+处理结果：
+
+- settings runtime owner 已通过正式 `SettingsProviderSpec` 接入
+- 不再依赖命令式 provider 注册作为主链
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/pz_contrib`
+- `owner package`
+  - settings runtime owner
+- `status`
+  - `done`
+- `DoD ref`
+  - `C1`
+  - `C2`
+- `tests`
+  - 现有：settings operator import smoke
+  - 现有：runtime override 与 provider 共存测试
+
+### 2.3 check / preflight owner import-time provider 注册
+
+处理结果：
+
+- import-time provider 注册已删除
+- check / preflight settings 注入已改为正式 `extensions()` 输出的 `settings.provider`
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/pz_contrib`
+- `owner package`
+  - check / preflight owner
+- `status`
+  - `done`
+- `DoD ref`
+  - `C2`
+- `tests`
+  - 现有：preflight import smoke
+  - 现有：无 import-time 副作用测试
+
+## 3. 扩展点差距
+
+本节差距已全部关闭。
+
+### 3.1 `host.builder`
+
+处理结果：
+
+- `foundation` 已输出结构化 `HostBuilderSpec`
+- `RuntimePlan` 已直接挂结构化 host manifest
+- `runtime.host` 已直接消费 `HostBuilderSpec`
+- 冲突裁决只认 `priority`
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/pz_contrib`
+  - `pz_framework/legacy_core`
+- `owner package`
+  - official infra owner
+  - `pz`
+- `status`
+  - `done`
+- `DoD ref`
+  - `D1`
+- `tests`
+  - 现有：host runtime 契约测试
+  - 现有：host integration 契约测试
+  - 现有：宿主 `/health`
+
+### 3.2 其它 contribution
+
+处理结果：
+
+- `route`、`middleware`、`lifecycle`、`resource` contribution 已全部对象化
+- `extensions()` 正式返回值已只保留协议对象
+- 旧 dict 声明已退出正式主链
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/legacy_core`
+  - `pz_framework/pz_contrib`
+  - `pz_apps`
+  - `pz_apps`
+- `owner package`
+  - 受影响最小子包
+- `status`
+  - `done`
+- `DoD ref`
+  - `D2`
+- `tests`
+  - 现有：`RuntimePlan` 结构测试
+  - 现有：各 contribution 契约测试
+
+## 4. App 元数据与编译器差距
+
+本节差距已全部关闭。
+
+### 4.1 `required_pz`
+
+处理结果：
+
+- 编译器与 `AppDecl` 已统一到 `required_pz`
+- 错误码与错误消息已围绕 `required_pz` 收口
+- app 声明、测试、模板已同步切换
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/legacy_core`
+  - `pz_framework/pz_contrib`
+  - `pz_apps`
+  - `pz_apps`
+- `owner package`
+  - 受影响最小子包
+- `status`
+  - `done`
+- `DoD ref`
+  - `A1`
+  - `B1`
+- `tests`
+  - 现有：app registry 契约测试
+  - 现有：apps.py 元数据契约测试
+
+## 5. 脚手架与顶层包差距
+
+本节差距已全部关闭。
+
+### 5.1 `pz startapp`
+
+处理结果：
+
+- 脚手架模板已输出 `pz` 正式依赖
+- `apps.py` 模板已输出 `required_pz`
+- 新生成代码不再扩散旧字段与旧依赖
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/pz`
+- `owner package`
+  - `pz`
+- `status`
+  - `done`
+- `DoD ref`
+  - `A1`
+  - `A2`
+- `tests`
+  - 现有：`pz` CLI 契约测试
+
+### 5.2 `pz` 顶层 README 与正式入口
+
+处理结果：
+
+- `pz` 顶层 README 已改为单一基础包叙述
+- 正式 CLI 与正式 Python API 已收敛到 `pz`
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/pz`
+- `owner package`
+  - `pz`
+- `status`
+  - `done`
+- `DoD ref`
+  - `A2`
+  - `E1`
+  - `E2`
+- `tests`
+  - 现有：CLI 契约测试
+  - 现有：Python API smoke
+
+## 6. 仓库元数据与工作区尾项
+
+### 6.1 workspace migration-only 条目
+
+当前状态：
+
+- `workspace_packages.toml` 仍存在 `[packages."legacy-core"]`
+- 该条目已明确标注为 migration-only source-repo entry
+
+说明：
+
+- 该条目对应的是真相源仓库位置，而不是终端用户正式 CLI/安装口径
+- 正式基础包、正式 CLI、正式 Python API 已经收敛到 `pz`
+
+执行信息：
+
+- `owner repo`
+  - `mt` workspace root
+- `owner package`
+  - workspace metadata
+- `status`
+  - `accepted_migration_context`
+- `DoD ref`
+  - `B2`
+- `tests`
+  - 现有：`pz env sync` 宿主依赖刷新验证
+  - 现有：宿主 `pz run` 与 `/health` 验证
+
+## 7. 文档尾项
+
+当前状态：
+
+- `22/23/24/25/26` 主协议与执行文档已收口到新口径
+- 少量迁移文档与仓库说明仍保留旧口径，用于记录迁移过程
+
+说明：
+
+- 这些残留不再定义当前正式规则
+- 它们属于治理尾项，不再阻塞正式运行主链完工
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/legacy_core`
+  - `pz_framework/pz`
+- `owner package`
+  - docs
+  - readmes
+- `status`
+  - `accepted_migration_context`
+- `DoD ref`
+  - `F1`
+- `tests`
+  - 现有：文档 `rg` 扫描
+  - 现有：`compileall docs`
+
+## 8. 多国语言资源治理差距
+
+### 8.1 locale bundle / consumer binding 正式协议
+
+当前状态：
+
+- `29-多国语言资源治理与按需加载规范` 已定义 locale governance 方向
+- `22-pz.protocols.v1 草案` 已补 `LocaleBundleSpec`、`LocaleDependencySpec`、`LocaleConsumerBinding`、`LocaleCompositionProfile`、`LocaleOverridePatch`
+- 源码主链尚未把 `resource.contribution` 的 locale governance metadata 编译为正式 locale bundle manifest
+
+说明：
+
+- 当前运行时仍主要停留在历史 namespace/base 回退模型
+- bundle、dependency、consumer binding、composition profile、page-local override 尚未成为可执行正式主链
+- `locales/config.json` 已在实现层退出 `module_config` 正式主链；当前遗留点主要在 locale governance manifest 尚未完全编译落地，而不是 `module_config` 继续依赖它
+- `page_supported_language` / `page_language_alternates` 也尚未完整进入旧清单所描述的主链，因此页面语言切换、hreflang 与 sitemap 还未统一消费同一份页面语言事实投影
+
+执行信息：
+
+- `owner repo`
+  - `pz_framework/pz`
+  - `pz_framework/pz_contrib`
+- `owner package`
+  - `pz`
+  - 共享 i18n owner 子包
+- `status`
+  - `planned`
+- `DoD ref`
+  - `I1`
+  - `I2`
+- `tests`
+  - 待补：resource manifest locale metadata 契约测试
+  - 待补：bundle dependency / consumer binding 契约测试
+  - 待补：SEO keyword page composition profile 契约测试
+  - 待补：`page_supported_language` / `page_language_alternates` 到语言切换 / hreflang / sitemap 的一致性契约测试
+  - 待补：page-local override 白名单与体积预算测试
+  - 待补：按 bundle 按需加载与体积预算测试
+
+## 9. 当前收口顺序回顾
+
+本轮已按下面顺序完成源码收口：
+
+1. `required_core -> required_pz`
+2. `settings.provider` 主链对象化
+3. `host.builder` 与其它 contribution 对象化
+4. `pz` 顶层 README、脚手架模板与正式入口切换
+5. 文档与 workspace 元数据收口
+
+## 10. 本轮非目标
+
+为避免任务继续膨胀，本轮明确不做：
+
+- 全仓 `legacy_core.* -> pz.*` 机械重命名
+- 全量重写所有 `uv.lock`
+- 重写与本轮协议无关的业务实现
+- 在宿主内补影子包、桥接包或本地装配 hack
+
+## 11. 验证要求
+
+本轮收口已覆盖下列验证：
+
+1. 对应 source repo 契约测试
+2. `pz` CLI smoke
+3. 受影响共享包 import smoke
+4. `pz env sync --project-dir <host-project-dir>`
+5. 宿主重启后 `/health`
+
+## 12. 当前执行决议
+
+当前正式决议如下：
+
+- 协议层不再继续加新概念
+- 运行时主链 cutover 已完成
+- 后续只继续处理迁移文档与 source-repo 元数据的治理尾项

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/26-cutover/345/256/214/345/267/245/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,117 @@
+# 26-cutover 完工检查清单
+
+> 历史说明：本文保留 `legacy_core -> pz` 字样，仅用于 cutover 完工判定与历史任务闭环；当前正式基础包统一为 `pz`。
+
+本文档用于确认 `legacy_core -> pz`、旧扩展协议 -> 新扩展协议、旧配置主链 -> 新配置主链这批任务是否已经按单一路径完成收口。
+
+它不是迁移愿景文档，也不是差距盘点文档。
+
+## 1. 使用规则
+
+- 只按正式协议判断是否完成
+- 不允许靠 shim、alias、双轨兼容层把“未完成”伪装成“已完成”
+- 若后续再发现协议缺位，应先回到协议文档补正式合同，再继续施工
+
+## 2. 总体完工定义
+
+本轮任务在同时满足下面全部条件后，视为已完成：
+
+- `pz` 成为唯一正式基础包、唯一正式 CLI、唯一正式 Python API 主入口
+- 新 app 脚手架不再生成 `legacy-core`、`required_core`、旧 dict 扩展声明
+- app 编译器、扩展编译器、settings 编译链只认新协议
+- `settings.provider`、`host.builder`、其它 contribution 全部走结构化协议对象
+- 运行主链不再依赖 import-time 注册和全局 provider 主路径
+- `workspace_packages.toml`、README、主要规范文档不再把 `legacy-core` 当正式长期口径
+- 宿主重装、重启、健康检查、关键契约测试全部通过
+
+## 3. 阶段 A：止血项
+
+### A1. app 元数据止血
+
+- [x] `required_core` 不再作为新增代码和模板字段出现
+
+### A2. 基础依赖止血
+
+- [x] 新生成代码不再把 `legacy-core` 写入正式依赖
+
+## 4. 阶段 B：编译器与元数据切换
+
+### B1. app 编译器切到 `required_pz`
+
+- [x] `AppDecl` 与编译器校验逻辑切到 `required_pz`
+
+### B2. workspace 与分发真相源收口
+
+- [x] 工作区与分发说明不再把 `legacy-core` 作为长期正式包
+
+补充说明：
+
+- `workspace_packages.toml` 中的 `legacy-core` 条目仍保留，但已明确标注为 migration-only source-repo entry，不再代表终端用户正式入口。
+
+## 5. 阶段 C：settings 主链切换
+
+### C1. `settings.provider` 成为正式主链
+
+- [x] settings 注入统一改为结构化 `SettingsProviderSpec`
+
+### C2. 清退命令式 provider 注册入口
+
+- [x] `register_app_settings_provider(...)` 退出正式公开面
+
+## 6. 阶段 D：扩展点对象化切换
+
+### D1. `host.builder` 切换到结构化对象
+
+- [x] `host.builder` 不再使用旧 dict + payload 声明
+
+### D2. 其它 contribution 切换到结构化对象
+
+- [x] route / middleware / lifecycle / resource contribution 全部完成对象化
+
+## 7. 阶段 E：CLI 与运行入口切换
+
+### E1. `pz` 成为唯一正式 CLI
+
+- [x] 正式命令全部收敛到 `pz`
+
+### E2. Python API 主链切换
+
+- [x] 正式 Python API 只认 `pz.*`
+
+## 8. 阶段 F：全局清扫
+
+### F1. 文档清扫
+
+- [x] 正式文档不再混用新旧口径
+
+补充说明：
+
+- 旧口径仅允许留在明确历史说明或迁移说明中；不再作为当前正式规则出现。
+
+### F2. 旧桥接清理
+
+- [x] 长期不需要的 shim、alias、fallback 全部删除
+
+## 9. 最终宿主验收
+
+- [x] source repo 契约测试通过
+- [x] `pz` CLI smoke 通过
+- [x] 受影响共享包 import smoke 通过
+- [x] `pz env sync --project-dir <host-project-dir>` 通过
+- [x] 宿主重启完成
+- [x] `http://127.0.0.1:8000/health` 返回 `200`
+- [x] 关键 host integration contract 通过
+
+## 10. 最终交付前复核
+
+下面问题现在的答案都应为“否”：
+
+- [x] 现在是否仍存在第二套正式配置读取入口
+- [x] 现在是否仍存在第二套正式扩展声明格式
+- [x] 现在是否仍存在第二套正式 CLI 名称
+- [x] 现在是否仍存在第二套正式基础包名字
+- [x] 现在是否仍存在新脚手架继续输出旧口径
+- [x] 现在是否仍依赖 import-time 副作用完成主链装配
+- [x] 现在是否仍有关键验证只靠宿主偶然环境成立
+
+只有全部答案都是“否”，这轮任务才算真正收口。