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/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/351/207/215/346/236/204/346/211/247/350/241/214/346/226/271/346/241/210.md

@@ -0,0 +1,224 @@
+# 目录与分层重构执行方案
+
+> 历史说明：本文中的 `legacy_core` 表述属于迁移前设计语境与旧目录边界记录；当前正式基础包统一为 `pz`。
+
+本文档用于把历史 `legacy_core -> pz` 的重构方式从“按命中点逐个修补”，切换为“先冻结正式目录边界，再自上而下收口实现”。
+
+正式原则：
+
+- 先定义目录边界，再做代码迁移
+- 同一类职责只允许落在一个目录层
+- `core` 只保留内核编译与运行边界，不再吞平台实现
+- `infra` 只保留可选基础设施适配，不再承担入口/配置真相源
+- 系统里真正存在的正式单位，只有最小子包
+- 除 `pz` 基础包外，其它正式能力都必须落成独立最小子包 `<app_id>`
+- 最小子包必须有稳定唯一的 `app_id`，新建子包默认让目录名、import 包名与 `app_id` 对齐；历史稳定 `app_id` 以已声明值为准，不强制特定技术前缀
+- 外层目录只用于 Git 与源码组织，不再表达正式运行时 namespace
+- 所有公开入口都只通过正式 facade 暴露
+
+职责：
+
+- 本文档只负责冻结目录结构、目标落位和迁移顺序
+- `runtime / assembly / core / infra` 的硬边界以 `00-重构总纲.md` 为准
+- `infra` 的细粒度迁移与切断门禁以 `15-infra裁剪与落位清单.md` 为准
+- facade / capability 的正式边界以 `16-正式Facade总表.md` 为准
+
+## 1. 唯一完整目录结构
+
+完整目录结构只在本文档定义一次，其它文档只允许引用，不再重复展开目录树。
+
+```text
+workspace/
+  pz_framework/  (框架本体源码组织根，不是运行时 namespace)
+    pz/  (顶层终端用户 CLI 包)
+      pyproject.toml
+      pz/
+      tests/
+    legacy_core/
+      pyproject.toml
+      docs/
+      legacy_core/
+        __init__.py
+        __main__.py
+        app.py
+        settings.py
+        runtime/
+        assembly/
+        core/
+        infra/
+      tests/
+    pz_contrib/  (框架内官方维护子包容器；不进入 import namespace)
+      <official_app_id>/
+        pyproject.toml
+        <official_app_id>/
+          __init__.py
+          public.py
+          apps.py
+          settings.py
+    pz_apps/  (并列源码组织根；不进入 import namespace)
+      <platform_app_id>/
+    pz_apps/  (并列源码组织根；不进入 import namespace)
+      <site_runtime_app_id>/
+```
+
+边界：
+
+- `legacy_core/` 只保留框架入口与内核主链
+- 每个正式能力都必须落成独立最小子包 `<app_id>/`
+- `pz_framework/`、`pz_apps/`、`pz_apps/` 这些顶层源码组织根只承担 Git 与 ownership 分组职责
+- `pz_contrib/` 只表示框架仓内的官方维护子包容器，不表示特殊运行时层
+- 不再保留 `plugins`、旧集合层目录、`platform namespace` 作为正式目录概念
+
+边界：
+
+- official infra owner `public.py` 的正式导出面以 `16-正式Facade总表.md` 为准
+
+## 2. 目录到目标目录的映射
+
+### 2.1 包根
+
+保留在包根：
+
+- `__init__.py`
+- `__main__.py`
+- `app.py`
+- `settings.py`
+
+约束：
+
+- `__init__.py` 只暴露公开 Python API
+- `__main__.py` 只负责 CLI 入口调用
+- `app.py` 只暴露 ASGI/Python 入口
+- `settings.py` 只保留 schema / normalize / 默认值聚合等声明职责；运行时读取统一走 `settings_center.settings`
+
+### 2.2 框架主链目录映射
+
+`runtime/`
+
+- 承接当前 `core/runtime.py`
+- 承接 `core/context.py` 中与 `ProjectContext` / `RuntimePlan` 直接相关的部分
+- 承接 `core/infra_runtime.py`
+- 承接执行期 manifest 消费与 HTTP / CLI / worker adapter glue
+
+`assembly/`
+
+- 承接 `core/settings/*` 中的编译逻辑
+- 承接 `core/app_settings.py`
+- 承接 `core/resources/merge_order.py`
+- 承接 `core/ops/*` 中编译、预处理、校验、扫描性质逻辑
+
+`core/`
+
+- 最终只保留 events、extensions、routing、health、errors 的纯 contract 与纯规则
+- 一切依赖具体 app、具体 provider、具体 middleware 类、执行期副作用的内容都迁出
+
+`infra/`
+
+- 最终只保留 `settings/`、`db/`、`kv/`、`storage/`、`observability/`、`health/`、`resilience/`、`resources/`
+- 以上目录只保留 contract、typed settings、binder、lifecycle、noop/default 边界
+
+### 2.6 最小子包
+
+最小子包是系统里除 `legacy_core` 外唯一正式的能力单位。
+
+其中源码落位固定为：
+
+- 每个正式能力都必须落在自己的包根：`<app_id>/`
+- 包根内部的正式 Python 包目录默认同样叫 `<app_id>/`
+- `<app_id>/` 可以放在任意顶层源码组织根下，但外层目录不参与运行时命名
+- `installed_apps` 可以直接声明某个 `<app_id>/`，也可以声明容器目录；框架需要负责递归发现其中嵌套的最小子包
+
+边界：
+
+- `legacy_core/` 不再承载任何业务能力或官方能力的具体实现
+- 任何能力型代码都必须进入某个最小子包，而不是继续挂在集合层目录名下
+- 各最小子包默认不通过内部 Python import 直接协作，只通过 facade / API / events / CLI 等稳定交互面协作
+
+最小映射规则：
+
+- `legacy_core/infra` 中 contract / binder / noop 保留在框架内核
+- `legacy_core/infra` 中具体 adapter / manager / handler 实现迁到对应最小子包，例如 official infra owner
+- `legacy_core/infra/i18n/*`、`legacy_core/infra/jinja/*` 迁到对应展示层最小子包，例如 shared site UI owner
+- app 专属 middleware 直接迁到对应 app
+
+## 2.7 二级目录固定说明
+
+完整二级目录结构已在第 1 节一次性列出。
+
+补充约束：
+
+- `runtime/` 只保留执行期运行图与入口胶水
+- `assembly/` 只保留编译、裁决与诊断编排
+- `core/` 不设 `apps/` 子目录，只保留纯规则与纯契约相关目录
+- `infra/` 只保留薄绑定层所需的 typed settings、binder、capability state 与 noop 边界
+
+## 3. 非运行时目录边界
+
+不进入正式运行主链：
+
+- `.runtime/`
+- `dist/`
+- `.venv/`
+- `logs/`
+- `docs/`
+
+要求：
+
+- `.runtime/` 只作为运行时输出目录，不纳入包分发语义
+- `dist/` 只作为构建产物目录
+- `logs/` 不得再作为源码默认依赖目录
+
+## 4. 重构顺序
+
+### 第一批：冻结正式边界
+
+- 冻结顶层目录职责
+- 冻结哪些内容留在包根
+- 冻结 `runtime / assembly / core / infra / apps` 的正式边界
+
+### 第二批：切真相源
+
+- `settings` 真相源统一到 settings snapshot
+- `project_dir` 真相源统一到 `ProjectContext`
+- 资源路径真相源统一到 `ResourceManifest`
+- app 装配真相源统一到 app registry / runtime plan
+
+资源域补充口径：
+
+- 作者配置入口统一到 `resources.items`
+- 单个 app 的资源发现结果统一到 `ResourceSource.items`
+- 当前项目的资源输出路径、源目录集合与 manifest 路径统一到 `ResourceManifest`
+
+### 第三批：清历史耦合
+
+- 清 `legacy_core.settings` 直读
+- 清 `ROOT_DIR / cwd / app/*`
+- 清 import-time 单例 / setter
+- 清 vendored / wrapper 心智
+
+### 第四批：物理迁移目录
+
+- 从当前 `core/*` 中拆出 `runtime/*` 与 `assembly/*`
+- 把所有官方能力与独立能力代码迁入各自的 `<app_id>/` 正式源码树
+- 从分散 tests 迁出正式 contract tests
+
+## 5. 正式任务树
+
+接下来所有任务都挂在这五个总任务下：
+
+1. `P0-目录冻结`
+2. `P1-真相源收口`
+3. `P2-core/infra 解耦`
+4. `P3-apps 收口与平台 app 去特权`
+5. `P4-contract tests 与 wheel/base-only 验证`
+
+## 6. 验收标准
+
+满足以下条件，才算目录级重构完成：
+
+- 包根只剩公开入口
+- `legacy_core / <app_id>` 与 `runtime / assembly / core / infra` 职责边界稳定
+- 不再存在 repo-root / `cwd` / `app/*` 作为正式路径心智
+- base-only wheel 安装可以正常执行 `pz --help`
+- 可选依赖缺失不会在 import-time 打崩基础命令
+- 正式 tests 能按分层验证入口、配置、资源、可选 infra、官方 app 装配