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/16-/346/211/251/345/261/225/347/202/271/346/255/243/345/274/217/345/215/217/350/256/256/346/270/205/345/215/225.md

@@ -0,0 +1,352 @@
+# 扩展点正式协议清单
+
+本文档固定 `pz` 插件系统的正式扩展点协议。
+
+适用边界：
+
+- 只定义 `pz` 基础层应识别的扩展点合同
+- 不定义官方具体实现
+- 不在本文档中引入第二套隐式注册机制
+
+## 1. 总原则
+
+- 除 app CLI 使用固定 `<app>/cli/<tool>.py -> CliToolSpec -> RuntimePlan.cli_manifest` 声明链外，其它扩展点都必须通过 `extensions()` 声明
+- 所有扩展点都必须是结构化对象，不允许裸函数、字符串路径、import-time 注册器
+- 所有扩展点都共享同一组最小公共头
+- 扩展冲突必须在编译期裁决，不允许静默覆盖
+- `pz` 基础层不仅识别内建协议，也必须允许最小子包把自己的正式协议注册进 core 编译主链；core 负责注册、校验、冲突裁决与诊断，不直接接管该子包的 runtime owner 实现
+
+最小公共头固定为：
+
+- `kind`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+
+## 2. `host.builder`
+
+用途：
+
+- 产出项目最终 host
+
+正式对象至少包含：
+
+- `kind = "host.builder"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `runtime_kind`
+- `builder`
+
+`builder` 必须实现：
+
+- `build(ctx: HostBuildContext) -> HostBuildResult`
+
+`HostBuildContext` 至少包含：
+
+- `project`
+- `plan`
+- `settings`
+- `bindings`
+
+`HostBuildResult` 至少包含：
+
+- `app`
+- `app_kind`
+- `health_path`
+
+约束：
+
+- 一个项目最终只能有一个生效的 `host.builder`
+- 多个 builder 按 `priority` 裁决；同优先级冲突直接报错
+- builder 声明对象本身不得带副作用
+
+## 3. `settings.provider`
+
+用途：
+
+- 为最终运行时 settings 提供结构化补丁
+
+正式对象至少包含：
+
+- `kind = "settings.provider"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `provider`
+
+`provider` 必须实现：
+
+- `provide(ctx: SettingsProviderContext) -> tuple[SettingsPatch, ...]`
+
+`SettingsProviderContext` 至少包含：
+
+- `project`
+- `snapshot`
+- `settings`
+
+`SettingsPatch` 至少包含：
+
+- `app_id`
+- `payload`
+- `source`
+- `priority`
+
+route manifest / URL 正式补充要求：
+
+- route registry / route manifest 必须持有 URL canonical 所需的正式元数据
+- 其中至少包括 namespace、path、path type 或等价 slash policy、replace target、route hints
+- trailing-slash 规范化不属于业务 provider 各自实现的私有逻辑；它必须由 host 消费统一 route manifest 后统一执行
+- 业务包若需要公开页面 canonical、hreflang、sitemap 或 redirect target，必须与同一份 route manifest slash policy 保持一致
+
+约束：
+
+- provider 只能返回 patch，不能直接改写全局 settings 状态
+- patch 只能写正式 schema 已声明字段
+- provider 应尽量纯函数、幂等、可重复执行
+
+## 4. `cli.tool`
+
+用途：
+
+- 向 `pz` 命令树暴露正式 app CLI
+
+正式对象至少包含：
+
+- `kind = "cli.tool"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `command`
+- `summary`
+- `tool`
+
+`tool` 必须实现：
+
+- `configure(parser) -> None`
+- `run(ctx: CliInvocationContext) -> int`
+
+当前 app CLI 文件约定固定为：
+
+- 每个 `<app>/cli/<tool>.py` 必须暴露模块级 `tool = CliToolSpec(...)`
+- `pz` 在 `compile_runtime_plan()` 阶段把这些对象编译进 `RuntimePlan.cli_manifest`
+- CLI / worker 执行阶段只消费 `RuntimePlan.cli_manifest`，不再重新扫描目录或临时 import 模块生成命令图
+- `pz` 不再调用模块级 `main()` / `worker_main()` 自由函数
+- worker 型 CLI 仍使用同一个 `CliToolSpec`；若需要进入正式 worker runtime，`tool.tool` 可额外暴露 `worker_entry(...)`
+
+`CliInvocationContext` 至少包含：
+
+- `project`
+- `args`
+- `stdout`
+- `stderr`
+
+约束：
+
+- `command` 必须是稳定命令路径
+- `configure()` 只配置参数，不执行副作用
+- `run()` 必须返回稳定 exit code
+
+## 5. `route.contribution`
+
+用途：
+
+- 向统一 route manifest 提交正式路由声明
+
+正式对象至少包含：
+
+- `kind = "route.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `router`
+- `prefix`
+- `tags`
+
+约束：
+
+- `router` 必须来自正式 `<pkg>.urls` 导出的 `DeclaredUrlSpec` 或其显式派生对象
+- route contribution 只声明路由来源，不承担最终跨 app 排序裁决
+- 不允许在 contribution 中夹带运行期副作用或局部挂载动作
+
+## 6. `middleware.contribution`
+
+用途：
+
+- 向统一 middleware manifest 提交中间件声明
+
+正式对象至少包含：
+
+- `kind = "middleware.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `factory`
+- `replace`
+
+约束：
+
+- `factory` 必须采用正式签名
+- `replace` 只允许显式替换已知 middleware id
+- 不允许依赖历史类路径、隐式补参或 import-time 注册
+
+## 7. `lifecycle.contribution`
+
+用途：
+
+- 向统一 lifecycle state machine 提交声明期或运行期钩子
+
+正式对象至少包含：
+
+- `kind = "lifecycle.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `phase`
+- `handler`
+
+其中 `phase` 只允许正式集合：
+
+- `init`
+- `startup`
+- `shutdown`
+
+约束：
+
+- `init` 只允许做声明期注册
+- `startup` 只允许激活已编译能力
+- `shutdown` 只允许对称清理
+- 不允许 lifecycle contribution 重新拼装第二份运行图
+
+## 8. `resource.contribution`
+
+用途：
+
+- 向统一 resource manifest 提交资源目录声明
+
+正式对象至少包含：
+
+- `kind = "resource.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `templates_dir`
+- `static_dir`
+- `locales_dir`
+- `migrations_dir`
+
+约束：
+
+- 资源目录必须来自标准 app 包布局
+- 不允许自定义第二套 `resources()` / `assets()` 声明协议进入正式主链
+- 资源覆盖顺序只允许由 `installed_apps` 展开顺序与显式裁决规则决定
+- 若 `locales_dir` 需要声明 shared bundle / page-type bundle / consumer binding / composition profile / page-local override / allowlist 之类治理元信息，只允许作为 `resource.contribution` 的结构化元数据进入资源编译主链
+- 若 `composition profile` 需要约束某个页面只支持部分语言，必须在同一份结构化元数据中声明 `page_supported_language`，并由语言切换、`seo.provider`、`seo.sitemap_provider` 统一消费；不得分别维护多份语言名单
+- 若业务子包需要把页面语言支持能力对外公开，正式公开面应优先收敛到单个 `page_profile` / `page_config` 解析入口；`page_supported_language` 只作为页面级合同字段暴露，不鼓励再长期维护第二个独立“语言列表”公开接口
+- `resource.contribution` 只声明资源来源目录及其配套资源治理元数据，不直接在运行期拼装页面级 i18n 规则对象
+- `resource.contribution` 不得表达无限覆盖链；正式覆盖层级最多只允许 `shared bundle -> page-type bundle -> page-local override`
+
+## 9. `page.profile_provider`
+
+用途：
+
+- 让业务子包或运行时子包按统一协议提供页面级 `page_profile`
+- 让页面语言切换、`seo.provider`、`seo.sitemap_provider` 等共享消费方走同一条解析链
+
+正式对象至少包含：
+
+- `PageProfileProviderSpec(...)`
+- `kind = "page.profile_provider"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `provider`
+
+`provider` 必须实现：
+
+- `resolve_page_profile(**kwargs) -> dict[str, object]`
+
+约束：
+
+- 子包应返回单个 `page_profile` / `page_config` 结构化对象；`page_supported_language` 只作为页面级合同字段暴露
+- `page.profile_provider` 必须通过 `PageProfileProviderSpec` 声明，不再允许长期使用 `ExtensionSpec(kind="page.profile_provider")`
+- 共享消费方不得再绕回子包 `public.py` 猜测 `get_public_surface_languages()`、`resolve_public_page_profile()` 之类私有约定
+- 多个 provider 可以按 `priority` 形成显式覆盖链；若同一页面出现多个同优先级命中，消费链必须报冲突，不得静默择一
+- provider 导入、实例化、调用失败不得静默吞掉；必须进入正式诊断
+- 页面解析 owner 的主链只消费 `PageProfileProviderSpec`；不再保留运行时 generic `ExtensionSpec` fallback
+- provider 只提供页面事实，不直接输出 nav、hreflang 或 sitemap 成品
+
+## 10. 子包正式协议注册
+
+用途：
+
+- 让最小子包把自己的正式扩展协议注册进 `pz` core 编译主链
+- 保持“协议进入 core、runtime 仍留在 owning app”这一长期架构
+
+正式要求：
+
+- `pz` 基础层必须提供正式的“子包协议注册”机制，而不是为每个高优先级子包长期手写特例
+- 子包注册进入 core 的对象应至少声明：
+  - 协议 `kind`
+  - 协议对象名或等价稳定标识
+  - provider/import 约束
+  - 最小必需字段
+  - 校验与冲突规则
+  - 运行时由谁消费
+- 该机制编译进入 `RuntimePlan` / `ExtensionRegistry` 主链后，Web / CLI / worker 与各 runtime 仍只消费已编译结果
+
+对公开页面中心的长期口径：
+
+- 页面中心 runtime 不进入 `pz` 基础层
+- 公开页面 owner runtime 继续整体保留在 `pz_page_center`
+- 页面中心通过 core 的子包协议注册机制，把自己的正式协议接入编译主链
+- 第一批需要进入 core 主链的页面中心协议至少包括：
+  - `page_center.page_provider`
+  - `page_center.seo_provider`
+- 若未来需要正式化关键词页注册输入协议，也应通过同一机制进入，而不是再单独发明第二套注册器
+
+## 11. `RuntimePlan` 最小组合根
+
+所有扩展点最终都只允许进入唯一 `RuntimePlan`。
+
+`RuntimePlan` 至少应包含：
+
+- `project`
+- `settings`
+- `app_registry`
+- `route_manifest`
+- `middleware_manifest`
+- `resource_manifest`
+- `cli_manifest`
+- `lifecycle_manifest`
+- `capability_registry`
+- `extension_conflicts`
+
+约束：
+
+- `RuntimePlan` 是运行图唯一组合根
+- `RuntimePlan` 在编译完成后必须视为不可变快照
+- Web / CLI / worker 执行阶段只消费 `RuntimePlan`，不再重新生成局部计划
+
+## 12. 冲突裁决规则
+
+- 同类扩展点同 `id` 默认冲突
+- `priority` 越高优先级越高
+- 同优先级冲突直接报错
+- 不允许按 import 顺序或最后加载者静默覆盖
+
+## 13. 正式结论
+
+- 扩展点协议必须是声明式、结构化、可审计的对象协议
+- `extensions()` 是唯一正式扩展声明入口
+- `pz` 只消费这些对象，不负责猜测历史形态
+- 子包级正式协议可以进入 `pz` core 编译主链，但子包 runtime owner 不因此迁入 core

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/17-pz.protocols.v1/346/255/243/345/274/217/345/215/217/350/256/256.md

@@ -0,0 +1,266 @@
+# pz.protocols.v1 正式协议
+
+本文档收口 `pz` 基础层的统一协议对象总表。
+
+适用边界：
+
+- 只定义协议对象
+- 不定义官方具体实现
+- 不定义历史兼容桥接
+
+## 1. 总原则
+
+- `pz.protocols.v1` 只收正式协议对象
+- 所有对象都应为声明式、结构化、可审计的数据协议
+- 协议对象本身不得依赖 import-time 副作用
+- 版本演进统一通过 `api_version`
+
+## 2. 最小公共扩展头
+
+所有扩展对象共享最小公共头：
+
+- `kind`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+
+字段语义：
+
+- `kind`
+  - 扩展点种类
+- `id`
+  - 同类扩展内唯一身份
+- `owner_app`
+  - 正式 `app.id`
+- `api_version`
+  - 协议版本，例如 `v1`
+- `priority`
+  - 编译期冲突裁决优先级
+
+## 3. v1 对象清单
+
+### 3.1 `HostBuilderSpec`
+
+- `kind = "host.builder"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `runtime_kind`
+- `builder`
+
+### 3.2 `HostBuildContext`
+
+- `project`
+- `plan`
+- `settings`
+- `bindings`
+
+### 3.3 `HostBuildResult`
+
+- `app`
+- `app_kind`
+- `health_path`
+
+### 3.4 `SettingsProviderSpec`
+
+- `kind = "settings.provider"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `provider`
+
+### 3.5 `SettingsProviderContext`
+
+- `project`
+- `snapshot`
+- `settings`
+
+### 3.6 `SettingsPatch`
+
+- `app_id`
+- `payload`
+- `source`
+- `priority`
+
+### 3.7 `CliToolSpec`
+
+- `kind = "cli.tool"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `command`
+- `summary`
+- `tool`
+
+### 3.8 `CliInvocationContext`
+
+- `project`
+- `args`
+- `stdout`
+- `stderr`
+
+### 3.9 `RouteContributionSpec`
+
+- `kind = "route.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `router`
+- `prefix`
+- `tags`
+
+### 3.10 `MiddlewareContributionSpec`
+
+- `kind = "middleware.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `factory`
+- `replace`
+
+### 3.11 `LifecycleContributionSpec`
+
+- `kind = "lifecycle.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `phase`
+- `handler`
+
+### 3.12 `ResourceContributionSpec`
+
+- `kind = "resource.contribution"`
+- `id`
+- `owner_app`
+- `api_version`
+- `priority`
+- `templates_dir`
+- `static_dir`
+- `locales_dir`
+- `migrations_dir`
+
+### 3.13 `LocaleBundleSpec`
+
+- `owner_app`
+- `bundle_id`
+- `bundle_scope`
+- `language`
+- `source_path`
+- `fallback_policy`
+- `dependencies`
+
+### 3.14 `LocaleDependencySpec`
+
+- `owner_app`
+- `bundle_id`
+- `depends_on`
+- `optional`
+
+### 3.15 `LocaleConsumerBinding`
+
+- `owner_app`
+- `consumer_kind`
+- `consumer_id`
+- `bundle_ids`
+
+### 3.16 `LocaleCompositionProfile`
+
+- `owner_app`
+- `profile_id`
+- `template_id`
+- `route_binding`
+- `page_supported_language`
+- `page_language_alternates`
+- `shared_bundle_ids`
+- `page_type_bundle_ids`
+- `page_local_override_id`
+- `dependency_policy`
+- `variables`
+
+### 3.17 `LocaleOverridePatch`
+
+- `owner_app`
+- `override_id`
+- `target_profile_id`
+- `language`
+- `source_path`
+- `allowed_keys`
+
+### 3.18 `ModuleConfigDefinition`
+
+- `module_id`
+- `title`
+- `owner_app`
+- `version`
+- `description`
+- `enabled_by_default`
+- `fields`
+- `bindings`
+- `depends_on`
+
+### 3.19 `ModuleConfigField`
+
+- `name`
+- `type`
+- `label`
+- `description`
+- `required`
+- `default`
+- `choices`
+- `secret`
+- `group`
+- `runtime_override`
+- `restart_mode`
+
+### 3.20 `ModuleConfigBinding`
+
+- `source_field`
+- `target_app`
+- `target_path`
+- `transform`
+- `priority`
+- `condition`
+
+### 3.21 `ModuleConfigPatch`
+
+- `app_id`
+- `payload`
+- `source_module`
+- `priority`
+
+### 3.22 `RuntimePlan`
+
+- `project`
+- `settings`
+- `app_registry`
+- `route_manifest`
+- `middleware_manifest`
+- `resource_manifest`
+- `cli_manifest`
+- `lifecycle_manifest`
+- `capability_registry`
+- `extension_conflicts`
+
+## 4. 协议版本策略
+
+v1 规则：
+
+- 新增可选字段
+  - 不升大版本
+- 删除字段、修改字段语义、修改返回对象结构
+  - 必须升协议版本
+- 同一运行主链默认只认一个正式主版本
+- 旧版本若保留，只能通过显式迁移桥接，不得进入长期主链
+
+## 5. 正式结论
+
+- `pz.protocols.v1` 是协议总表，不是实现包
+- 所有正式扩展点与配置对象都应能映射到这份总表
+- 若对象无法映射到此总表，应先补协议，再补实现