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/23-/351/246/226/345/261/217/345/261/225/347/244/272/344/270/216/351/246/226/345/270/247/347/250/263/345/256/232/350/247/204/350/214/203.md

@@ -0,0 +1,269 @@
+# 首屏展示与首帧稳定规范
+
+> 本文只约束“对外部可见且需要 SEO 的 HTML 页面”的正式首屏主链；`admin`、内部运营页、自用后台、强登录态工作台默认不强制纳入。
+> 本文中的 settings 仍统一采用正式读取面：`import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 或 `settings_center.settings.project.<field>` 读取。
+> `pz_site_ui` 的公开站点前端组件作者面约定见 `../../../pz_contrib/pz_site_ui/docs/前端组件约定.md`；公开页面图片、hero、媒体组件和业务模板边界应先遵守该约定。
+
+## 1. 目标
+
+首屏展示不是单页优化技巧，而是 `pz` 站点型页面的正式运行时约束。
+
+这套规范固定三件事：
+
+- 公开 HTML 页面的首屏可见内容必须以后端渲染为正式主链
+- 共享首帧稳定治理由 shared site UI owner 落地，页面 SEO 主链由 SEO owner 消费
+- 业务 app 只负责在自己的页面边界内声明内容、状态和资源，不再各页复制第二套首屏修法
+
+## 2. 适用范围
+
+适用页面：
+
+- 公开首页、落地页、博客、CMS 页面、公开关键词页、帮助页
+- 其它可直接被搜索引擎、分享卡片、外部链接访问的 HTML 页面
+
+默认不强制：
+
+- `admin`
+- 内部工具页
+- 纯登录后工作台
+- 仅面向运营人员的强用户态控制面
+
+## 3. 正式主线
+
+对外部可见且需要 SEO 的 HTML 页面，固定遵循这一条正式主线：
+
+1. 请求进入统一 host 与共享 runtime
+2. 页面路由在进入模板前绑定正式请求期页面状态
+3. 后端直接输出首屏可见正文、稳定翻译、SEO 关键文案与结构化数据
+4. 模板输出首屏关键资源 hints 与正式 bundle 声明
+5. 前端只做 hydrate、交互增强、异步刷新与非首屏区块补充
+
+不允许：
+
+- 把首屏正文、首屏 CTA、SEO 主文案依赖前端二次请求后再补齐
+- 把结构化数据真相源放到客户端拼接
+- 把“先渲染临时状态，再靠客户端纠偏”当成长期正式方案
+
+## 4. 页面状态合同
+
+公开 HTML 页面在进入模板前，必须先绑定统一请求期页面状态。
+
+至少包含：
+
+- `lang`
+- `translation_module`
+- `page_profile`
+- `translation_bundles`
+- `client_translation_scopes`
+- `page_supported_language`
+- `page_language_alternates`
+
+规则：
+
+- 共享模板层、共享翻译 facade、共享语言切换逻辑优先消费这份请求期合同
+- 业务路由不应长期各自手写同构 `request.state` 注入
+- 若某类页面状态会在多个页面重复出现，应优先沉淀到 shared site UI owner 或对应正式共享 helper
+- 若公开页面需要服务内 SSR 片段缓存，正式声明位固定为 `page_profile.page_config.render_cache`；共享层只消费这份页面事实，不再在实现里猜测页面依赖或长期硬编码业务字段。
+
+`page_config.render_cache` 约束：
+
+- 缓存对象必须是页面内的 SSR 片段，不是整页匿名壳体。
+- 必须显式声明 `slot`、目标受众和 `vary` 页面事实。
+- 受众与 `Vary` 必须对齐最终 HTML 受众；登录态、cookie 态和语言态不可偷跑到匿名缓存。
+
+## 5. SSR 首帧规则
+
+固定规则：
+
+- SSR 首帧必须直接输出稳定可见状态
+- 能从当前请求直接判定的状态，必须优先 SSR 输出最终态
+- 只有依赖纯客户端判定的临时 UI，SSR 才默认隐藏，初始化后 reveal
+- 初始化测量阶段不得暴露中间态动画
+- 任何需要尺寸测量、运行时裁剪或客户端恢复后才能稳定的 UI，必须先隐藏或保持稳定占位态
+
+可直接 SSR 判定的常见来源：
+
+- `cookie`
+- `Accept-Language`
+- 请求头
+- 已编译 settings
+- `module_config`
+- 当前请求 URL / path params / query params
+
+不采用：
+
+- refresh snapshot shell 一类旧页面状态复用方案
+- 旧 DOM overlay 一类覆盖旧 DOM 的方案
+- 第二套页面壳
+- 匿名缓存首帧后再由客户端纠正登录态或语言态
+
+## 6. 首屏内容与翻译
+
+公开 HTML 页面必须满足：
+
+- 首屏可见正文以后端渲染为正式真相源
+- SEO 关键文案以后端渲染为正式真相源
+- 结构化数据所需稳定文本以后端渲染为正式真相源
+- 首屏稳定翻译必须按当前页面和当前语言直接输出
+
+前端翻译请求只允许用于：
+
+- 非首屏交互区块
+- 异步组件
+- 缺词补拉
+
+不允许：
+
+- 把首屏正文翻译依赖前端拉取
+- 为图省事把整模块或整站翻译全集注入 HTML
+
+补充要求：
+
+- SEO/landing/公开关键词页/博客/帮助页这类可缓存公开页面，首屏翻译网络请求目标应为 `0`
+- 纯 SSR 页面应显式给出空的前端增量取词范围，而不是依赖隐式缺省
+
+## 7. 首屏关键资源
+
+首屏关键资源固定规则：
+
+- 首屏关键图必须显式声明为 eager / high priority
+- 不允许把首屏关键图长期保留为 `loading=\"lazy\"`
+- 页面级正式聚合产物必须声明在 `page_config.asset_bundle`
+- 非首屏增强脚本若需延后加载，正式声明位固定为 `page_config.deferred_js`
+
+共享层责任：
+
+- shared site UI owner 统一消费正式 bundle 声明与 deferred 声明
+- 对共享默认首屏 hero，shared site UI owner 应在 head 输出正式图片 preload
+- 响应式图片、hero 图片、卡片媒体图等公开站点前端优化应优先沉淀为 `pz_site_ui` 组件，业务模板只声明源图、alt、尺寸和关键资源语义
+
+业务责任：
+
+- 若业务覆盖了首屏 hero 图片源，必须通过 `pz_site_ui` 组件或正式资源 hint 合同声明关键资源语义，不在业务模板中手写第二套 preload / `srcset` / `sizes`
+- 首屏关键交互必须留在 critical bundle 中，不得误塞到 deferred loader
+- 业务 JS 不得用 `new Image()` 主动预加载公开首屏或非首屏原始大图，避免绕过浏览器 `srcset` 选择与资源优先级调度
+
+## 8. 共享运行时与用户态启动
+
+共享首帧治理默认由 shared site UI owner 落地。
+
+固定规则：
+
+- 共享用户态启动链只有一条，由 shared site UI owner 的正式 user runtime 持有
+- 用户态变更事件只允许由 shared site UI owner 的正式 user runtime 派发
+- 会话检查、登出委托、CSRF/请求头等公开页通用会话能力，应收敛在共享 base/runtime 主链
+- 依赖 session probe 的公开 shell 组件必须走 shared site UI owner 的 session stable island 合同；SSR 匿名占位、probe pending、resolved out/in 与 re-probe 保持已解析状态必须由同一套 helper 管理
+- 同一 tab 硬刷新恢复只允许保存最小 UI hint，且必须同时校验 session cookie hint；不得把用户资料或账户事实放进客户端首帧恢复缓存
+- 语言切换路径解析、语言偏好持久化与统一 `changeLanguage` 入口，也应收敛在共享 base/runtime 主链
+
+业务脚本不要做：
+
+- 页面启动时再次主动调用共享会话检查
+- 在业务脚本里自行派发用户态变更事件
+- 为 Login、Dashboard 或其它 session 相关 shell CTA 复制第二套防闪状态机
+- 为 header、footer、语言推荐、cookie banner 各自维护第二套用户态或语言态启动链
+
+## 9. Hydration 与增强
+
+若共享或业务 widget 已经在 SSR 输出 root、launcher 或 config，客户端只能 hydrate 现有结构。
+
+不允许：
+
+- 先渲染一个版本，再用 `innerHTML` 整块替换
+- 把共享 SSR root 当成临时占位，然后客户端再重建第二份 DOM
+
+前端正式职责只有：
+
+- hydrate 现有节点
+- 补齐缺失交互
+- 刷新异步数据
+- 加载非首屏增强区块
+
+## 10. 页面级行为声明
+
+页面级行为必须显式声明开启，不得由全局模板默认注入。
+
+包括但不限于：
+
+- required-post
+- heartbeat
+- 轮询端点
+- 页面保活路径
+
+规则：
+
+- 由页面或模块显式 opt-in
+- 共享层按声明注入到首帧配置或共享 runtime
+- 不允许在全局页面壳里给所有页面默认注入同一条 heartbeat 或 required-post path
+
+## 11. 缓存与受众对齐
+
+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 集合，这个集合必须进入正式 settings/defaults/normalize 链
+- 不允许拆成“框架内建识别一部分、宿主配置再补一部分、CDN 规则再猜一部分”的三套真相源
+
+## 12. 合规与首屏解耦
+
+cookie consent 的正式职责仅限于：
+
+- 合规展示
+- 偏好持久化
+- telemetry / ads / analytics consent 信号同步
+
+不得反向控制：
+
+- 支付
+- 登录
+- 上传
+- 翻译
+- 搜索
+- 导航
+- 会话恢复
+
+无论用户接受、拒绝，或浏览器拒绝 `localStorage` / cookie 持久化：
+
+- 页面核心功能都必须继续可用
+- 失败只能退化为“偏好无法持久化”
+
+## 13. 分层落位
+
+责任划分固定如下：
+
+- `pz`
+  - 不承载首屏展示具体实现
+  - 只承载稳定协议、运行图编译与统一装配合同
+- `pz_contrib`
+  - 承载共享 host、shared site UI owner、SEO owner 等正式消费主链
+- shared site UI owner
+  - 落地共享首帧稳定治理与请求期页面状态 helper
+- SEO owner
+  - 消费页面 SEO provider / sitemap provider，不拥有页面内容真相
+- 业务 app
+  - 提供页面内容、页面状态声明、页面资源声明与 provider
+  - 不复制第二套首屏 runtime
+
+## 14. 文档关系
+
+本文是首屏展示规范的统一真相源。
+
+其它文档与本文的关系固定为：
+
+- `14-分层与扩展规范`：定义它属于哪一层、由谁负责
+- `15-子包开发使用手册`：给开发者提供可执行落地规则
+- `21-contrib约定与Provider接入规范`：说明 shared site UI owner / SEO owner 如何正式落地
+
+若这些文档与本文冲突，以本文为准。

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/24-pz/345/220/257/345/212/250/344/270/216/350/277/220/350/241/214/346/227/266/347/274/226/350/257/221/346/265/201/347/250/213.md

@@ -0,0 +1,245 @@
+# `pz` 启动与运行时编译流程
+
+## 1. 目标
+
+本文件只回答一件事：
+
+- `pz` 启动项目时，正式做了哪些事情
+
+它描述的是 `pz` 总体启动与编译主链，不替代具体子包的 owner 文档。
+
+## 2. 总原则
+
+- `pz` 是唯一正式基础包，也是唯一可独立启动的包
+- `pz` / `pz` 的正式入口，最终都要进入同一条 `RuntimePlan` 编译链
+- 启动过程必须先编译，再执行
+- Web / CLI / worker 运行期只消费编译结果，不再二次扫描或二次 merge
+
+补充：
+
+- `pz` 是直接 CLI 真相源
+- `pz` 是正式 launcher facade
+- `pz` launcher 只负责在进入 `pz_core.cli:main` 前选择 provider，不得定义第二套运行时或第二套编译链；`pz.root_cli` 只是顶层命令 provider group
+
+## 3. `pz` 启动时做什么
+
+`pz` 启动项目时，正式主链固定为：
+
+0. 先为这次 `pz` 命令选择 provider：项目 `.venv` -> 项目 dev manifest 里记录的 `apps/.sources/pz` bootstrap runtime -> 当前解释器 `site-packages` -> `uv tool run --from pz-cli pz`
+1. 解析 `project_dir`
+2. 解析 `PZ_ENV`
+3. 读取项目 `pz*.jsonc`、项目 `.env*` 与显式环境变量，编译 `SettingsSnapshot`
+4. 解析 `installed_apps`，展开正式最小子包顺序
+5. 编译 `AppRegistry`
+6. 按 app 顺序发现并合并资源目录
+7. 编译 `ResourceManifest`
+8. 编译 `InfraContext`
+9. 编译 `RouteManifest` 与 `MiddlewareManifest`
+10. 组装 `CapabilityRegistry`
+11. 产出统一 `RuntimePlan`
+12. Web / CLI / worker 只消费该 `RuntimePlan` 进入执行阶段
+
+`pz run` / Web startup 不直接读取各子包 `configs/default.jsonc` / `configs/default.env`，也不在启动链中临时补写默认值。需要判断项目 settings 是否落后于当前 app 默认模板时，统一通过 `pz check` 暴露 settings update drift 诊断；该诊断复用 `pz settings update` 的 dry-run 计划，并输出同一份 `CheckReport`。
+
+第 0 步的边界固定为：
+
+- `pz` 是高频基础入口，定型后只允许 bugfix、contract 补齐与明确纳入 contract 的新能力
+- 不得随业务能力变化而改变既有命令语义、provider 顺序、入口函数、安装依赖边界或 `project_dir` 解析规则
+- 只负责选择这次命令使用哪个 `pz_core.cli:main`
+- 不负责重新定义 settings、resource、route、capability 规则
+- 一旦 provider 选定，后续仍然进入同一条正式 `RuntimePlan` 编译链
+
+第 4 步的 `installed_apps` 展开规则固定为：
+
+- `installed_apps` 只表达装载顺序和扫描入口，不表达第二套源码映射。
+- 运行时不硬编码 `apps`，只展开当前项目配置中实际声明的 `installed_apps` 条目；默认项目配置会声明 `apps` 作为扫描目录。
+- 若配置条目是 `apps`，框架只扫描项目 `apps/` 下的真实本地 app 和可见受管快捷方式。
+- 物理 `apps/.sources/` 永远不贡献 app，也不会因额外 import root 或 symlink 隐式进入运行时 namespace。
+- 目录 binding 只展开快捷方式下顶层正式叶子；叶子 binding 只暴露一个正式叶子。快捷方式的 realpath 必须与 typed v5 manifest 完全一致。
+- 同一 `app_id` 若同时存在于项目源码扫描范围和当前解释器 `site-packages`，项目源码优先；同一 `app_id` 若在多个项目本地源码位置同时出现，则编译前作者面检查必须要求人工收敛。
+- `SettingsSnapshot.import_roots` 由已声明 app 的 import root 加上这些 app 在本地 source-root 中声明的 path 依赖递归组成；它不是 source-root 全量包扫描结果。
+- 运行时允许 `mission_carrier` 这类已装载 app 通过正式依赖获得 `agent_tool_contracts` 这样的本地源码依赖，但普通 site runtime / contrib 包不能因此被迫直接依赖 Agent / Tool 运行时内部实现。
+
+## 4. 启动期资源合并
+
+每个最小子包都可以提供正式作者资源目录：
+
+- `pages/`
+- `template_config/`
+- `locales/`
+- `templates/`
+- `static/`
+- `migrations/`
+
+这些目录都属于最小子包自己的源码真相源。
+
+`pz` 启动项目时，`pz` 会按正式 app 启动顺序，把这些目录合并到当前项目的运行时聚合目录中；后出现的 app 覆盖先出现的同名资源。
+
+作者面的正式配置入口固定为 `resources.items`。
+
+- 每个资源项至少声明 `name`
+- 资源聚合输出根目录由 `resources.output_root` 决定
+- 资源 manifest 文件名由 `resources.manifest_name` 决定
+- 资源 staging 目录名由 `resources.staging_dir` 决定
+- 资源编译锁文件名由 `resources.lock_name` 决定
+- 实际输出路径按当前 `PZ_ENV` 分区：`resources.output_root` 落在 `<cache_dir>/<pz_env>/` 下，资源锁落在 `<runtime_dir>/<pz_env>/locks/` 下；同一项目同时运行 develop 与 product 时不得共享同一套派生资源目录
+
+正式要求：
+
+- `pages/`、`template_config/`、`locales/`、`templates/`、`static/`、`migrations/` 必须服从同一套资源覆盖语义
+- `pz` 资源层的正式语义是文件级别的覆盖
+- 不允许某个子系统再为其中某一类目录定义第二套扫描规则、优先级规则或私有覆盖规则
+- 运行期各子系统消费的是合并后的正式结果，而不是逐个子包现扫现拼
+- 单个 app 的资源发现结果统一落在 `ResourceSource.items`
+- 当前项目的统一资源编译结果统一落在 `ResourceManifest.items`
+
+这里的“文件级别覆盖”指：
+
+- 资源层首先裁决的是“同一个相对路径最终保留哪一个文件”
+- 它不是页面声明 payload 的 `dict merge`
+- 它也不是业务子域私有 JSON 合并协议
+
+补充说明：
+
+- 当前若某个官方子包在资源 build 阶段对特定文件类型做了额外结构化 merge，应视为局部实现或待收口特例，不应反向改写 `pz` 资源层的总语义
+- 页面声明的 `dict` 级递归 merge，仍然归属于 `pz_page_center` 编译阶段，而不属于 `pz` 通用资源层；页面声明任意层都可通过 `$merge` 编译指令声明 path-level replace/deep-merge 策略，但这仍是 page center 子域编译语义
+
+## 5. 合并目录与原始资源的边界
+
+合并目录只是运行时派生产物，不是作者面真相源。
+
+正式要求：
+
+- 页面、模板、文案、静态资源、迁移脚本的修改，都必须回到原始最小子包目录进行
+- 不允许把合并目录里的文件直接当成长期维护入口
+- 运行期读取方只能把 merged 结果视为只读输入
+- 修改原始资源后，应通过重新启动或重新编译，生成新的正式合并结果
+
+## 5.1 merge 函数分层
+
+全项目正式 merge 函数只允许两类：
+
+1. 文件夹覆盖合并函数
+2. `dict` 深度合并函数
+
+对应分层固定为：
+
+1. `pz` 资源层的文件夹覆盖合并函数
+2. 子域编译阶段的 `dict` 深度合并函数，例如 `page_center` 的页面声明 merge；该函数可以接收显式 path-level 策略，但策略来源和生效范围必须由子域 owner 声明
+
+正式要求：
+
+- 不允许新增第三类长期正式 merge 语义
+- 这两类函数必须在语义上严格分层
+- 不允许把子域编译期 merge 伪装成 `pz` 通用资源覆盖
+- 也不允许让 `pz` 资源层承担业务子域 payload merge 职责
+
+正式建议：
+
+- 这两类 merge 函数后续应收敛到 `pz_contrib` 的共享 utils
+- 当前若 `pz_contrib` 没有独立共享 utils 包，则应优先落在最接近平台资源 owner 的正式共享位置，而不是继续散落在各子包私有模块中
+
+## 6. 页面域在启动期的消费方式
+
+页面域只是这条总启动链上的一个正式消费者。
+
+本节描述的是已经选择 Page Center 治理的页面。普通功能页、用户态页面和轻量站点页不因为是 HTML 页面就自动进入 Page Center；它们仍以 `<pkg>.urls` 为 URL 真相源，可以通过 `PageProfile` / `page.profile_provider` / `pz_site_ui` request page state 提供共享 shell、多语言和页面资产事实。
+
+对页面系统来说，固定心智模型是：
+
+1. 作者在各子包内维护原始 `pages/`、`template_config/`、`locales/`、`templates/`
+2. `pz` 按 app 顺序统一合并资源
+3. `pz_page_center` 消费 `ResourceManifest` 指向的合并后页面相关资源
+4. 编译 `page_config`、`page_config_key`、页面合同、canonical path 与 slash policy，并贡献路由投影
+5. 页面 runtime registry 作为 `RuntimePlan.runtime_manifests` 的正式 manifest 固化
+6. URL manifest、worker 内 route materialize、startup 预热和页面 handler 都消费同一份已编译结果
+
+页面系统的正式页面配置叫 `page_config`。`page_config` 通过 `pages/*.jsonc` 维护，`pages/base.jsonc`、`pages/<app_id>/base.jsonc` 和具体页面文件是同一个 `page_config` model 的不同叠加层。任意层都可以携带 `$merge.replace_paths` 和 `$merge.deep_merge_paths`，用于声明该层在叠加时哪些路径走替换、哪些路径重新打开深合并；各层 `$merge` 作为编译期策略累积，路径更深的 `deep_merge_paths` 可以排除上层 replace。该指令只参与编译，不进入 runtime snapshot。运行时按 URL 查 `page_config` 时使用 `page_config_key`；`page_config_key` 由 `path_segments + slug` 归一化得到，例如 `manga-translator` 或 `manga-translator/panel-ocr`。只注册 URL、没有具体 `page_config` 文件的默认页面，读取 `page_config` 时必须回落到对应层级的 base 合成配置。
+
+`page.profile_provider` 不是路由声明，也不是第二套 `page_config`。它只为普通页面或其它内容 owner 提供页面框架事实；如果某页面需要由 Page Center 统一输出 canonical、alias、hreflang、sitemap、page renderer 或长尾治理投影，必须升级为 `pages/*.jsonc` 并进入本节的编译链。
+
+页面系统不允许：
+
+- 在运行期再次扫描原始 app 资源目录
+- 在运行期自己重做一遍资源 merge
+- 在 `RuntimePlan` 外再拼第二份页面图
+- 让 URL manifest 和实际 FastAPI route materialize 使用不同的页面 registry
+
+## 7. Foundation Route 与 URL 真相源
+
+Foundation route 层是系统级 URL 装配、canonical、alias、尾斜杠、redirect 与路由冲突裁决的正式真相源。`RouteManifest` 是 `RuntimePlan` 的编译期产物；Web / worker materialize、redirect middleware、SEO / sitemap / hreflang 投影和页面 handler 都只能消费这份 manifest 或它的正式投影。
+
+系统级 owner 固定为：
+
+- `pz_foundation.routing`：提供 `path(...)`、`include(...)`、`mount(...)`、path convertor 与 canonical helper。
+- `pz_foundation.route_owner` / redirect owner middleware：消费 `RouteManifest`，统一执行 slash normalization、canonical redirect 和冲突裁决。
+- 页面类 owner、admin owner、auth owner 等子域只能向 `RouteManifest` 提交声明或消费它的投影，不得各自实现第二套路由核心。
+
+系统级 URL 规则：
+
+- `routing.default_language` 决定默认语言是否使用 prefixless canonical；如果默认语言是 `en`，则 `/en/xxx/` 的 canonical 是 `/xxx/`。
+- `routing.all_supported_languages` 是语言前缀归一化、alias 解析和 route manifest 编译使用的系统 URL 语言全集；例如 `/zh-cn/` 301 到 `/zh-CN/`。它不是页面级 nav、hreflang 或 sitemap 暴露集合，页面类 owner 必须用自己的页面级语言事实约束对外投影。
+- `routing.language_aliases` 是公开 URL 语言段的唯一别名表；语言别名不得分散写到 redirect 规则、业务 handler、SEO 或前端脚本里。
+- 目录型 URL 统一保留结尾 `/`；文件型 URL 不强行加 `/`；exact URL 按声明保持精确匹配。
+- page center 首页由 `page_config.home=true` 声明；默认语言首页 canonical 是 `/`，非默认语言首页 canonical 是 `/{lang}/`。如果首页 `page_config` 同时声明 `slug`，则 `/{slug}/`、`/{default_language}/{slug}/`、`/{lang}/{slug}/` 只是首页 alias。
+- canonical、alias、301 redirect、hreflang、sitemap URL 必须由同一套 route manifest / canonical helper 生成，不得由 handler、SEO provider、sitemap provider 或前端脚本各自重算。
+- 公开站内 href 生成必须走 Foundation canonical helper。Foundation helper 先执行默认语言 prefixless、语言 alias、尾斜杠等通用规则，再消费页面 owner 注册的 public route canonical resolver，把已编译 route facts 中的 alias path 映射回 canonical path。页面 owner 只贡献 canonical / alias facts，不在模板或 SEO provider 中重新实现站内链接归一规则。
+- host 必须关闭 FastAPI / Starlette 默认 `redirect_slashes`，避免框架默认 `307/308` 与正式 canonical redirect 并存。
+
+路由贡献与 materialize 规则：
+
+- app 的 URL 真相源固定为 `<pkg>.urls`，或由正式 owner 在编译期产生 runtime manifest / route projection。
+- 普通功能页、登录后页面和轻量支持页优先由 `<pkg>.urls` 提交显式路由；`PageProfile` 只提供共享 shell、多语言和页面状态事实，不替代 route contribution。
+- route contribution 只提交路由来源、owner、path、path type / slash policy、route hints、override policy 等编译输入；最终跨 app 排序、冲突裁决和 materialize 只由 foundation route 编译链完成。
+- 固定合同路由可以使用编译期枚举 path convertor，例如已知语言、已知 `page_config_key`。无限量动态 `slug` 不得膨胀为同等数量的 FastAPI route。
+- 动态 `slug` 必须挂在已知父级合同路由之下，由 handler 做格式校验和 repository 查询；它不能反过来定义 route manifest。对 page center 来说，DB 长尾词实例必须挂在已编译 `page_config_key` 下。
+- Foundation URL manifest 编译、worker 内 FastAPI route materialize、startup 预热和运行时 handler 必须消费同一份已编译 route manifest / runtime projection。
+
+冲突优先级必须固定：
+
+1. 显式具体路径优先于固定合同路由。
+2. 固定合同路由优先于泛路由兜底。
+3. 同一路径发生冲突时，如果已有路由不允许覆盖，则编译失败。
+4. 如果已有路由允许覆盖，则后注册者按 `installed_apps` / 编译顺序覆盖，并写入冲突日志。
+5. 泛路由兜底永远不能覆盖显式具体路径或固定合同路由。
+
+执行阶段不得：
+
+- 重新扫描 URL 声明或 owner runtime manifest。
+- 在 `startup()` / `lifespan` 里补挂正式路由。
+- 让 URL manifest 和实际 FastAPI route materialize 使用不同的 route graph。
+- 在业务 handler、SEO、sitemap、redirect 或前端脚本里临时实现另一套语言前缀、尾斜杠、canonical 或 alias 规则。
+
+## 8. 执行阶段不再做什么
+
+进入执行阶段后，Web / CLI / worker 不再负责：
+
+- 重新扫描 `installed_apps`
+- 重新 merge `pages/`、`template_config/`、`locales/`、`templates/`、`static/`、`migrations/`
+- 重新编译局部 settings
+- 重新裁决 route / middleware / capability
+- 重新发明一套局部 trailing-slash / canonical URL 规范
+
+正式要求：
+
+- 执行阶段只消费 `RuntimePlan`
+- `startup()` / `lifespan` 只激活已经编译好的能力
+- 不允许在执行阶段偷偷补第二套装配链
+- URL slash normalization 必须消费编译后的 route manifest，不得在业务路由 handler 内临时重做一份全站规则
+
+补充：
+
+- route manifest 应显式携带正式 slash policy，例如目录型页面、文件型 URL 或 exact URL
+- host 在挂载 route manifest 后统一提供 slash normalization
+- 正式执行点应是 redirect owner middleware；不要依赖 FastAPI/Starlette 默认 `redirect_slashes`
+- host 应关闭框架默认 `redirect_slashes`，避免默认 `307/308` 与正式 canonical redirect 并存
+- canonical、hreflang、sitemap、redirect target 必须与这份 slash policy 一致
+
+## 9. 对子包作者的直接结论
+
+如果你在开发最小子包，只需要记住：
+
+1. 原始文件改在子包自己的资源目录
+2. 运行时读的是 `pz` 启动后生成的合并结果
+3. 资源覆盖顺序只看 `installed_apps`
+4. 编译先于运行；运行期不要再发明第二套发现、merge 或编译逻辑