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/05-/350/265/204/346/272/220/344/270/216/350/277/220/350/241/214/347/233/256/345/275/225/350/247/204/350/214/203.md

@@ -0,0 +1,575 @@
+# 项目目录、资源与运行目录规范
+
+> 本文涉及 settings 时统一采用单一路径：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取。
+
+## 1. 目标
+
+项目目录、资源目录与运行态文件系统策略必须适用于标准安装包场景。
+
+核心原则：
+- 目录边界统一由 `ProjectContext` 提供
+- 包目录视为只读
+- 一切运行态输出写入外部目录
+- 长期身份、账号、记忆、浏览器环境等资产写入项目资产目录，不写入 `.runtime`
+- 资源覆盖顺序只取决于 `installed_apps`
+
+## 2. 目录角色定义
+
+`pz` 运行时只允许依赖以下一等目录概念：
+
+- `project_dir`
+  - 项目配置与项目级扩展的根目录
+- `cache_dir`
+  - 可删除后重建的派生产物目录
+- `runtime_dir`
+  - 当前部署实例的运行态目录
+- `asset_dir`
+  - 不可删除的持久资产与业务文件目录
+
+### 2.0 `project_dir`
+
+`project_dir` 是项目级配置与项目级 app 扩展的锚点，不等于：
+
+- `pz` 包安装目录
+- 当前 shell 的任意 `cwd`
+- 某个固定仓库根目录
+
+统一发现顺序：
+
+1. 显式 CLI 参数 `--project-dir`
+2. 环境变量 `PZ_PROJECT_DIR`
+3. 当前目录向上搜索 `pz.jsonc`
+
+正式要求：
+
+- `project_dir`、`cache_dir`、`runtime_dir`、`asset_dir` 统一由 `ProjectContext` 或项目级 typed accessor 提供
+- Web / CLI / worker / app / adapter 只能消费当前 `RuntimePlan.project` 或等价 `ProjectContext`
+- 不允许任何调用方绕过 `ProjectContext` 自行拼目录
+
+禁止：
+
+- 从 `cwd`、repo root、模块文件路径反推目录
+- 从历史 `upload_path`、`worker_storage_path` 再次推导项目持久根
+- 从 helper 内部临时重建 project context
+
+### 2.1 `cache_dir`
+
+用于存放可重建产物，例如：
+- 合并后的 `templates`
+- 合并后的 `static`
+- 合并后的 `locales`
+- 合并后的 `pages`
+- 合并后的 `template_config`
+- 合并后的 `migrations`
+- 迁移聚合产物
+
+特点：
+- 可删除后重建
+- 不应承载业务真相数据
+
+### 2.2 `runtime_dir`
+
+用于存放运行期状态，例如：
+- lock files
+- pid files
+- sockets
+- 临时目录
+- 本地运行标记
+
+特点：
+- 面向当前进程或当前部署环境
+- 可在重启后重新生成
+
+### 2.3 `asset_dir`
+
+`asset_dir` 是不可删除持久文件的正式根目录。
+
+用于存放：
+- 上传内容、本地 storage backend 数据、worker 共享文件输入输出等需要跨重启保留的业务文件
+- actor / identity / persona / memory / relationship 等影响力资产
+- 平台账号上下文、账号绑定、浏览器环境 inventory
+- 资产索引、证据引用索引、发布历史索引
+
+约束：
+- 项目内开发默认固定为 `<project_dir>/.assets`
+- `.assets` 是不可删除目录，不是运行 cache；不得被 `pz clean runtime` 或普通运行时清理当作可删除目录
+- `.runtime` 只承载可删除、可重建的 materialized profile、workdir、pid、lock、cache 和短窗账本
+- `storage` 默认本地 backend 的 `base_dir` 应明确落在 `asset_dir` 下
+- 不应继续默认使用相对 `"uploads"`、`"var/media"` 一类历史路径
+- 资产目录通常应进入 `.gitignore`，真实 secret / cookie / token 不应进入仓库
+
+### 2.4 目录访问接口的单一路径原则
+
+目录访问接口必须统一，避免每层各自发明 path helper。
+
+正式要求：
+
+- 目录访问统一通过 `ProjectContext` 或其 typed accessors 完成
+- `cache_dir/resources`、`cache_dir/migrations`、`runtime_dir/locks`、`asset_dir/uploads`、`asset_dir/<owner>` 这类子路径，应由统一 accessor 生成
+- app/独立子包 不得定义自己的 project root/path root/helper 作为正式公共依赖
+
+不允许：
+
+- `resource_root()`
+- `repo_root()`
+- `pkg_root()`
+- `uploads_root()`
+- `worker_storage_root()`
+
+### 2.5 作者面 IDE 影子投影
+
+PyCharm 与 VS Code 都是作者面工具，不属于运行时目录模型。为了让 IDE 精确识别业务仓真实 app 与 linked app，PZ 编译一次可见 app 投影，再交给已有 IDE 目录对应的 provider：
+
+- `.idea/pz.generated.sources.iml`：PZ 唯一拥有的生成 module
+- `.idea/modules.xml`：PZ 只拥有指向上述 module 的精确 entry，其余 XML 内容全部属于用户/IDE
+- `.vscode/settings.json`：PZ 只拥有自己插入的 `python.analysis.extraPaths` 数组项
+- `.vscode/pz.generated.sources.json`：记录上一轮成功同步中由 PZ 插入的 VS Code paths，不参与 VS Code 读取
+
+正式约束：
+
+- 影子投影只包含 content/source root metadata，不复制任何源码、模板、静态资源、配置或文档
+- PyCharm 中业务仓 app 使用项目相对 `apps/<app_id>`，linked app 使用 canonical 叶子源码根
+- VS Code 统一使用 `${workspaceFolder}/apps/<visible-leaf-path>`，通过项目可见 binding 访问 linked 叶子，不写入外部绝对路径
+- 不得把整个 `.sources`、整个 monorepo checkout、未绑定叶子或生成目录登记为 source root
+- 更新必须使用结构化 XML / JSONC API；VS Code 通过状态账本只移除 PZ 旧条目，并保留用户路径、注释与其他 settings
+- `.idea/` 或 `.vscode/` 不存在时，对应 provider 返回 `not_applicable`，不得由 PZ 主动创建 IDE project 目录
+- VS Code 双文件更新使用 staging 与事务 journal；受控失败恢复旧文件，中断后由下一次 sync 恢复或完成
+- 生成 module 与 machine-local entry 必须被 Git 忽略，不得进入 wheel、sdist、发布 tag 的 package scope 或共享配置
+- VS Code 状态账本在 Git 项目中通过 `.git/info/exclude` 精确忽略，不修改共享 `.gitignore`
+- 影子投影不进入 `ProjectContext`、`RuntimePlan`、`SettingsSnapshot.import_roots`、资源发现或 import precedence
+- 唯一原子写入口是 `pz dev ide sync`；`pz dev add/link/unlink/branch/update` 只通过编排调用它
+
+## 3. 默认路径
+
+项目内开发默认值：
+- `project_dir = "."`
+- `cache_dir = ".runtime/cache"`
+- `runtime_dir = ".runtime/run"`
+- `asset_dir = ".assets"`
+
+系统级部署默认值：
+- `project_dir = "/srv/<project>"`
+- `cache_dir = "/var/cache/pz/<project>"`
+- `runtime_dir = "/var/run/pz/<project>"`
+- `asset_dir = "/var/lib/pz/<project>"`
+
+## 3.1 多实例与权限约束
+
+从实际部署角度，目录规范还必须覆盖多实例和权限边界。
+
+要求：
+
+- `runtime_dir` 必须允许按实例区分，避免同机多实例共享锁与 socket
+- `asset_dir` 必须具备清晰且严格的读写权限边界；不得默认暴露给 Web 静态目录扫描
+- `cache_dir` 可共享与否必须显式决定，不能依赖“恰好同一路径”
+- 若正式目录不存在且无法创建，或已存在但不可写，必须 fail-fast 并给出明确诊断
+
+## 4. 资源发现
+
+每个 app 可提供：
+- `templates/`
+- `static/`
+- `locales/`
+- `pages/`
+- `template_config/`
+- `migrations/`
+
+系统根据 `installed_apps` 顺序扫描这些目录。
+
+补充说明：
+- `installed_apps` 若声明的是组织包，应先自动递归展开到最小叶子子包
+- 真正参与资源发现与覆盖顺序计算的是展开后的叶子 app
+- 宿主不应为了资源扫描再手工把组织包内所有叶子子包逐个列出
+- 作者面对资源类型的正式配置入口是 `resources.items`
+- 每个资源项至少声明 `name`
+- 当前默认资源项为：
+  - `templates`
+  - `static`
+  - `locales`
+  - `pages`
+  - `template_config`
+  - `migrations`
+
+规则：
+- 后出现的 app 覆盖先出现的同名资源
+- 不再区分“官方容器优先”或“业务 app 优先”
+- 唯一顺序真相源是 `installed_apps`
+
+补充要求：
+
+- `templates/`、`static/`、`locales/`、`pages/`、`template_config/`、`migrations/` 都属于同一套正式资源覆盖语义
+- `pz` 资源层的正式覆盖语义是文件级别覆盖，不承担页面声明或业务 payload 的 `dict` 级 merge
+- 正式资源编译结果只保留统一资源项结果；每个资源项直接持有自己的 `name / source_dirs / output_dir`，不再维持目录名映射表或每类资源一个固定字段的第二套 facade
+- `ResourceSource.items` 是单个 app 的资源发现结果
+- `ResourceManifest.items` 是当前项目的统一资源编译结果
+- 合并目录里的文件只是当前启动编译得到的运行时派生产物，不是作者面源码真相源
+- 如果需要修改页面声明、模板声明、多语言文案、模板文件、静态文件或迁移文件，必须回到原始最小子包资源目录修改
+- 不允许把 merged/cache 目录中的合并结果当成长期维护入口
+
+约束：
+- 资源发现不应继续通过 `ResourcesMixin` 内部反推 repo root 或包路径特例来补默认源目录
+- 资源发现应基于已解析的 installed_apps/app registry 和正式 project_dir/cache_dir 边界
+- 不应继续保留依赖仓库布局的资源 token
+- 不应再对某个官方 app 做内建特殊排序，例如模板层把 shared site UI owner 固定放到最后
+- 不应继续由 core 内部 `merge_order` token 去扫描历史容器目录或旧业务根目录
+- app 包根目录的定位应来自正式 app registry 元数据，而不是运行时再次 import package 反推
+
+## 5. 资源输出
+
+运行期聚合产物必须输出到外部目录，不再写回：
+- 包目录
+- 源码目录
+- `site-packages`
+
+不得保留包内 merged 目录、源码目录或 `site-packages` 目录作为资源输出目标。
+
+补充约束：
+- 合并服务的临时目录、old backup 目录、互斥锁目录也必须相对 `cache_dir/runtime_dir`
+- 不应继续通过 `Path.cwd()` 解释相对 merged 路径
+- `templates/static/locales/pages/template_config/migrations` 六类资源服务都应显式表达自己的源目录、目标目录、锁目录和临时目录
+
+正式要求：
+
+- merged 目录是运行时消费面，不是编辑面
+- `resources.output_root` 决定 merged 资源根目录
+- `resources.manifest_name` 决定资源 manifest 文件名
+- `resources.staging_dir` 决定原子切换前的 staging 目录名
+- `resources.lock_name` 决定资源编译锁文件名
+- 各类资源读取方只能把 merged 目录视为只读输入
+- 作者修改必须发生在原始 app 资源目录；重新启动或重新编译后，再由正式资源合并链生成新的 merged 结果
+
+## 5.1 资源合并的原子性与一致性
+
+资源 merge 不只是“写到外部目录”，还必须保证失败时不会留下半成品状态。
+
+要求：
+
+- merge 输出必须采用原子切换策略
+- 不允许直接就地覆盖当前正在服务的目标目录
+- merge 失败时应保留上一个可用版本，或明确暴露“当前无有效产物”状态
+- 锁粒度、临时目录命名、清理策略必须可诊断
+
+正式要求：
+
+- 使用：
+  - staging dir
+  - 校验完成后 rename/swap
+  - 旧版本延迟清理
+- 将当前激活版本、构建时间、输入清单写入 manifest，便于诊断和回滚
+
+## 5.2 资源服务实例化边界
+
+资源服务的生命周期也必须符合正式运行模型，不能继续靠 import-time 单例维持。
+
+正式要求：
+
+- `templates/static/locales/pages/template_config/migrations` 相关服务不得在模块导入期就基于全局 `settings` 创建单例
+- 资源服务的源目录、目标目录、锁目录、manifest 路径必须来自当前 `ProjectContext` / `ResourceManifest`
+- `ResourceManifest` 的输出目录必须按 `PZ_ENV` 分区，默认形态为 `<cache_dir>/<pz_env>/<resources.output_root>`；资源构建锁默认位于 `<runtime_dir>/<pz_env>/locks/<resources.lock_name>`，避免同一项目内 develop / product 并行运行时互相覆盖派生产物
+- 同一进程内切换不同 `project_dir` 或重复创建 app 时，资源服务必须可重建，不得复用旧快照
+- runtime 只消费已编译好的 `ResourceManifest` 与构建结果，不再通过 import-time service 反推目录
+
+禁止：
+
+- 在 `core/resources/*` 导入时立即创建 `static_files_service`、`template_files_service`、`locales_files_service`、`pages_files_service`、`template_config_files_service`、`migration_files_service`
+- 让资源服务依赖全局 settings 单例，而不是显式消费当前 `ProjectContext` / `ResourceManifest` 与 `settings_center.settings`
+- 让模块级资源服务成为正式公共 API
+
+## 5.3 asset build 与资源优化执行边界
+
+资源 merge、asset build、图片优化、bundle/minify 都属于派生产物流程，但这些流程的执行边界必须继续细分。
+
+正式要求：
+
+- Web `startup()`、`create_host_app()`、`create_app()` 不得默认触发 asset build / deploy / image generation
+- `preflight` 中的 fail-fast 检查与优化型任务必须分离
+- 图片生成、bundle/minify、静态优化若需要存在，只能作为显式命令、显式 preflight 子任务或显式编译步骤运行
+- 图片响应式派生属于通用资源能力，正式 owner 是 `pz_foundation.resources`；强制覆盖同名派生产物的正式入口是 `pz resources images --force`
+- 这些任务的输出、锁、临时目录、构建 manifest 统一落在当前 `cache_dir/runtime_dir`
+- source 资产是作者真相源；develop / test 默认加载 source 资产，不得因为聚合产物文件存在而自动切到旧 bundle
+- product 或显式资源合并开关才允许加载正式构建产物；若声明要加载的聚合产物缺失，运行时应保守回退到 source 资产或在显式检查阶段失败
+- 非聚合 source 入口是 develop / test 的默认消费面，也是正式构建产物缺失时的保守 fallback；不得用 inline 补丁掩盖旧聚合产物
+
+禁止：
+
+- 在 Web 启动链里 best-effort 执行 `ensure_built_and_deployed()` 后吞异常继续启动
+- 在 `preflight.startup()` 里同时承担“阻断型检查”和“非阻断优化任务”
+- 让生产首个请求路径隐式承担 asset 构建成本
+- 在 develop / test 中因 `site.min.*` 文件存在而隐式加载旧聚合产物
+- 通过 inline CSS / JS 为旧聚合产物打补丁，替代正式 asset build 或 source 回退
+
+## 6. 迁移输出
+
+多 app 迁移聚合的临时/合并产物也必须写入 `cache_dir`。
+
+正式路径：
+- `<cache_dir>/migrations`
+
+要求：
+- 迁移聚合过程使用并发锁保护
+- 不得写回包目录
+- 不得假设框架安装路径可写
+
+补充要求：
+
+- 迁移聚合结果应有 manifest，记录：
+  - 参与 app
+  - owner
+  - 输入版本
+  - 生成时间
+- 若聚合失败，不得留下“看起来成功但内容不完整”的目录快照
+
+补充约束：
+
+- 迁移聚合工作空间不得写入 repo-root 或包内 merged 目录
+- `db` CLI 若需要临时工作目录，必须显式落在当前 `cache_dir`
+- 迁移工具不得通过临时 `PYTHONPATH` 注入、repo-root 推断、包内 `aerich.ini` 写入来弥补目录模型缺口
+- 迁移文件格式修复、owner 推断、models 发现必须作为显式子命令或显式检查结果出现，不得在正式迁移主路径里偷偷补丁式修复
+
+## 7. 锁文件与临时文件
+
+所有锁文件、swap 目录、tmp 目录、合并中间目录应写入 `runtime_dir` 或 `cache_dir`。
+
+正式规则：
+- 锁和进程相关文件放 `runtime_dir`
+- 大型合并中间产物放 `cache_dir`
+- asset build / merge / preflight 使用的锁统一放 `<runtime_dir>/locks`
+- 文件锁只作为单机实例互斥手段，不作为跨主机/跨共享文件系统的正式协调机制
+
+约束：
+- worker supervisor 锁不得默认落到系统临时目录
+- 资源构建锁不得默认落到包目录旁
+- 资源合并产生的 `.__*_tmp_*`、`.__*_old_*` 目录不应散落到项目当前工作目录
+- 合并服务的路径 helper 不应在相对路径场景下回落到 `Path.cwd()`
+- 若部署场景需要跨主机协调，应使用显式 capability 或外部基础设施，不继续复用本地 file lock 语义
+
+## 8. import 资源策略
+
+运行时统一通过包路径定位资源目录，但必须满足：
+- 只读取包内资源
+- 只向外部目录写入合并产物
+
+正式默认不支持 zipimport。
+
+## 8.1 i18n 与模块配置约束
+
+语言资源与模块配置要求：
+
+- 继续从包内 `locales/` 发现源资源
+- 将合并产物写入 `cache_dir`
+- 但不得把“包内 merged 目录”当成唯一真相
+
+对于模块配置文件默认值：
+
+- 页面相关 `module config` 的正式输入应来自 app `pages/base.jsonc`，并由 `pz_page_center` 统一编译
+- app 若需要私有 JSON 文件，只能作为 app 内部实现细节存在，不得再作为正式页面配置入口
+- `locales/config.json` 已退出 `module_config` 正式主链，不应再要求某个 import-time 全局服务先加载 merged locales
+- settings runtime owner 不应通过模块级单例长期持有 merged locales 目录快照来间接驱动 `module_config`
+
+### 8.2 i18n / 模块配置 runtime 隔离
+
+从生产多实例、多项目复用角度，语言与模块配置 runtime 还必须满足隔离要求。
+
+正式要求：
+
+- translation manager、module config manager、默认 locale/module 这类 runtime 状态不得通过模块级全局变量长期持有
+- 相关 runtime 必须与当前 `ProjectContext` / `RuntimePlan` 绑定
+- 同一进程内切换不同 `project_dir`、重复创建 app、或测试并行执行时，不得复用上一份 merged locales / module config 快照
+- 若需要 lazy load，也必须是 context-bound lazy load，而不是 process-wide singleton lazy load
+
+禁止：
+
+- 通过 `set_i18n_runtime_config()` 这一类全局 setter 维持正式运行态
+- 通过包级 `translation_manager` / `module_config_manager` 代理对象充当长期稳定公共依赖面
+- 在资源 merge 前基于旧 merged locales 快照提前完成全局同步
+
+## 9. 覆盖规则
+
+模板、静态、语言、页面声明、模板声明、迁移资源覆盖统一采用：
+- `installed_apps` 后者覆盖前者
+
+不再额外引入：
+- 容器目录特权顺序
+- `business app` 保底强插队
+- 隐式 priority
+
+## 10. 资产构建约束
+
+资源合并后的 bundle/minify 等资产构建：
+
+- 只能读取包内资源和 `cache_dir` 中的合并结果
+- 只能向 `cache_dir` 写入产物
+- 不应由 core 直接依赖某个具体最小子包的 builder 实现
+
+约束：
+- asset builder 的 project root 不应继续通过 `Path(__file__).parents[...]` 推断
+- build 锁目录统一进入 `<runtime_dir>/locks`
+- 若某个正式静态产物允许以“源码目录 + 统一构建”方式维护，例如 `default/js/base/` -> `default/js/base.js`，则源码目录只作为声明侧；runtime 与模板仍只能消费正式产物路径，不得把源码目录暴露成第二套运行时入口
+- 这类源码目录的收口必须发生在正式 asset build 链内部，并且先于后续 bundle/minify；例如共享公开页最终仍只对外暴露 `base.js`、`site.min.js` 这类正式产物，而不是把源码分片列表变成页面脚本真相源
+- 正式 bundle 的输入集合也必须符合职责边界，而不是只看“能不能拼进去”：共享公开页 bundle 应优先只包含共享且偏首屏/偏公共启动的资产；共享但非首屏的增强脚本，应继续通过已有 runtime loader 或页面声明位加载，不应为了省事全部卷回 `site.min.js`
+- 同理，认证页专用脚本不应因为“刚好也在共享仓”就继续卷入共享公开页 bundle；若公开页只需要通用会话检查、登出或请求头能力，应把这部分收敛进 base/runtime 正式主链，而不是让 `auth.js` 反向成为公开页的基础依赖。
+- 同理，若导航、语言推荐 banner、页脚语言入口都会触发同一套语言跳转与偏好持久化逻辑，这套逻辑也应统一收敛进共享 base/runtime 正式主链；不要把 `changeLanguage` 一会儿放在 `nav.js`，一会儿又让其它共享脚本各自 fallback 一套。
+- 对浏览器会主动探测的根资源入口，例如 `/favicon.ico`、`/favicon-32x32.png`、`/favicon-16x16.png`、`/apple-touch-icon.png` 与 `/apple-touch-icon-precomposed.png`，若共享公开页已经有正式静态资产，则应由共享公开页子包提供稳定直出路由或等价正式入口；模板也应优先引用这些正式根入口，而不是再把公开 head 真相源写成 `/static/...`。
+- 浏览器 head 中声明的图标资源必须与共享公开页实际提供的正式资产保持一致；若某个历史声明位对应的正式资产并不存在，例如 `mask-icon` 对应文件缺失，则应先移除悬空声明或补齐正式资产，不要长期保留会稳定产出 404 的 head 链接。
+- 若某个历史脚本已经没有独立正式职责，只剩空壳、兼容标记或可被现有 bundle/runtme 直接吸收的极薄逻辑，应直接退出 asset build 的正式输入清单；不要让 bundle/minify 持续为无效资产背书
+- 若页面需要区分 critical 与 deferred 脚本，critical 资产继续走正式 page bundle；deferred 资产必须通过页面声明位统一交给共享 runtime 加载，不能在模板或宿主中追加手写 `<script>` 清单。
+
+## 11. 资源服务与存储门面约束
+
+资源服务与存储门面应满足：
+
+- 必须延迟创建
+- 必须按 app context 重建
+- 不在 import 阶段绑定首次加载时的 `settings`
+- 失败语义明确，不以 best-effort 吞异常作为正式装配策略
+
+不允许：
+
+- 在模块级直接创建 `static_files_service`、`template_files_service`、`locales_files_service` 并把目录永久绑定到首次导入时的 settings
+- 本地存储 adapter 将 `file://` URL 作为长期对外公共访问契约
+- 在 bootstrap 中直接改写这些全局服务的目录列表，然后立刻触发 merge / reload 外部模块级单例
+- 在 resources bootstrap 中顺手调用：
+  - `module_config_manager.load_configs()`
+  - `translation_manager.reload_translations()`
+  这类跨层全局刷新动作
+- `attach_storage_to_context()` 失败时直接吞异常，导致 Web 运行起来但 storage backend 实际未完成装配
+- 通过固定 `/uploads` 挂载把 `global_settings.upload_path` 暗中变成公开资源边界
+
+正式要求：
+
+- merge 产物目录旁必须生成固定路径的资源 manifest：`<cache_dir>/resources/manifest.json`
+- `manifest.json` 作为当前资源合并结果的唯一真相源
+- 模板 renderer、static facade、translation facade、module config facade 只允许消费当前 manifest，不再各自重新扫描目录树推导结果
+- 本地存储的公开访问 URL 由显式 mount/base_url 决定
+- 若没有公开访问入口，只返回逻辑路径或受控下载路由，而不是宿主机文件路径
+- static/uploads/media 公开挂载边界由当前 project context 的 mount 配置决定，而不是历史固定路由
+
+## 10.2 资源诊断与审计的单一路径原则
+
+资源体系的诊断面也必须唯一。
+
+正式要求：
+
+- 资源相关诊断统一读取 `<cache_dir>/resources/manifest.json`
+- debug 页面、CLI 诊断、preflight 检查、错误报告都只允许基于当前 manifest 输出
+- 不允许某个诊断入口再次扫描文件系统，得出与 manifest 不一致的“另一份事实”
+
+manifest 至少必须承载：
+
+- 当前激活版本
+- 输入 app 顺序
+- 每类资源的来源 app 与源目录
+- 输出目录与构建时间
+- 冲突裁决结果
+
+结论：
+
+- manifest 不只是 merge 副产物
+- 它还是资源边界唯一审计视图
+
+## 11.1 资源与公开暴露的安全边界
+
+从工程实践看，目录外置之后还必须补齐资源暴露边界。
+
+要求：
+
+- 不允许把整个 `runtime_dir` / `asset_dir` 直接公开挂载
+- 只允许显式声明的子目录进入公开静态暴露面
+- 模板、静态、上传、导出文件的公开路径应各自独立，不应混成一个“万能目录”
+- 资源服务必须防止路径穿越和越界读取
+
+正式要求：
+
+- 公开挂载基于显式白名单目录
+- 公开下载统一走受控下载路径，不走宿主目录直出
+- 任意由 app 提供的静态/模板路径都先归一化再参与 merge
+
+## 12. 模板与 i18n 运行时约束
+
+模板与 i18n 运行时应满足：
+
+- 模板目录与语言目录可按当前 app/project context 重建
+- 默认 locale/default module 不依赖模块级全局变量长期保存
+- Jinja globals/filters 的注册必须可重入且可清理
+
+不允许：
+
+- 将 merged templates/locales 路径在 import 阶段固化到全局模板环境
+- 将默认 locale/module 仅保存在进程级 `_RUNTIME` 并跨项目上下文共享
+
+正式要求：
+
+- 模板 renderer、translation facade、request 级 helper 分层
+- 默认 locale/default module 从 settings snapshot 或 app context 解析，而不是从全局变量读取
+- 模板环境与翻译运行时都必须从当前资源 manifest 和 settings snapshot 构造，不再自行猜测 merged 目录位置
+
+约束：
+- i18n 同步逻辑不应在 bootstrap 阶段直接通过 merged locales `base/config.json` 改写全局 modules provider 和 middleware 配置
+- 这类同步应进入当前 app context 的 i18n facade / registry
+- 资源合并失败、翻译重载失败、模块配置重载失败也不应仅通过 warning 吞掉后继续依赖一组半初始化全局对象
+
+## 13. 日志与静态版本目录补充约束
+
+运行目录外置后，日志与静态资源版本辅助逻辑也应一起收口。
+
+要求：
+
+- 默认日志目录应落到 `runtime_dir/logs`，或完全交给 stdout/stderr 与外部 collector
+- 不应在 import `logger.core` 时就在当前工作目录创建 `logs/*`
+- 静态资源版本追加逻辑若依赖文件 mtime，也必须绑定当前 app context 的 static facade
+
+日志输出目录与静态版本目录来源都必须绑定到当前 project context，并按 `runtime_dir/cache_dir` 边界收口。
+
+## 14. Asset Build 与 Preflight 约束
+
+资源 merge 之外，asset build/bundle/minify 也必须纳入同一目录边界。
+
+要求：
+
+- asset build 只读取当前 app registry 导出的静态源与 `cache_dir` 中的 merge 结果
+- bundle/minify 输出只能写到 `cache_dir`
+- `create_app()` / `startup()` 不应默认 best-effort 触发 asset build
+- preflight app 统一通过显式 task/CLI/worker 运行，不应在 Web 启动链里偷偷构建
+
+### 14.1 资源构建链的单一路径原则
+
+资源构建也必须收口为一条正式流水线。
+
+正式要求：
+
+1. 先基于 app registry 编译资源 manifest
+2. 再基于 manifest 执行 build/bundle/minify
+3. 构建结果写入 `cache_dir`
+4. 后续 runtime 只消费 manifest 与 build 输出
+
+页面或其它上层子域贡献 asset bundle 时，必须在运行时编译阶段写入
+`RuntimePlan.runtime_manifests["resource.asset_bundles"]`。`pz` 资源 CLI 只消费该通用
+manifest 键，不得直接 import `pz_page_center` 或其它业务子包公开面。
+
+禁止：
+
+- preflight 自己再扫描 repo 目录
+- asset builder 自己再推导项目根和 merge order
+- runtime 再次临时 build 一遍静态资源
+- 模板或 runtime 同时维护“源码分片直出”和“正式 bundle 产物”两套长期主链
+
+结论：
+
+- resource merge 与 asset build 是一条编译链上的前后两步
+- 不能拆成多套各自推导目录与顺序的实现
+- 如果为了治理单文件过大而引入源码分片，也必须在这条编译链内先收口回正式产物，再参与后续 bundle/minify；源码分片不是新的公开资源合同
+
+asset build 必须出清 repo-root、包内 merged 目录、`app/static` 这类布局假设，并按 manifest + `cache_dir` 的单一路径收口。
+
+## 15. Resource Merge Order 与 Preflight Image Overlay 约束
+
+资源 merge order 与 preflight 输出路径也必须完全切到 app registry / project dir 语义。
+
+要求：
+
+- merge order 的唯一正式输入应是显式 app registry / installed_apps 顺序
+- 不应继续支持任何 repo-layout token
+- 不应继续对具体站点 UI / 站点能力 owner 做资源层硬编码特殊顺序
+- preflight 派生资源若要写回项目目录，也必须写到显式 `cache_dir` 或单独声明的生成目录，而不是默认 `app/static`
+
+资源发现与 preflight 输出都必须出清仓库布局假设，并按 `project_dir + installed_apps` 决定资源边界的模型收口。