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/14-/345/210/206/345/261/202/344/270/216/346/211/251/345/261/225/350/247/204/350/214/203.md

@@ -0,0 +1,550 @@
+# 分层与扩展规范
+
+> 本文涉及 settings 时统一采用单一路径：只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取；`settings.py` / `settings/` 只负责声明。
+> namespace 统一采用最小子包稳定身份：每个正式 app 必须有稳定唯一的 `app.id`，settings namespace 必须与 `app.id` 一致；新建子包默认让目录名、import 包名与 `app.id` 对齐，distribution 使用对应 Python 分发名；非叶子内部模块不得自定义 namespace。
+
+本文档固定 `pz` 的正式高层分层模型。
+
+- `pz` 是唯一正式基础包，也是唯一可以独立启动的包
+- 其它最小子包统一按 `pz` 插件模型发现、编译、组装与加载
+
+## 最高优先级公约
+
+- 系统里唯一正式的基础启动包只有 `pz`。
+- 必须区分源码 / 分层依赖与 distribution 安装依赖；安装层为了默认产品体验建立的 bundle 关系，不得解释为基础层可以反向依赖高层实现。
+- 除 `pz` 外，其它正式运行单元统一是最小子包，并作为 `pz` 的插件按约定自动发现和加载。
+- `pz` 与 `pz_apps` 是彼此并列的顶层源码组织根，只用于 Git 与源码组织，不再作为正式架构层，不再进入 import namespace。
+- `pz_contrib` 是官方最小子包源码容器，不是运行时 namespace。
+- 正式依赖面只允许依赖最小子包本身，不允许依赖集合层目录名。
+- 每个最小子包的正式命名必须统一：
+  - `app_id = <app_id>`
+  - 目录名 = `<app_id>`
+  - import 包名 = `<app_id>`
+  - distribution = `<distribution-name>`
+- 新建子包默认让目录名、import 包名与 `app_id` 对齐；不强制 `pz`、`pz` 或其它特定技术前缀。
+- 历史子包已发布的 `app_id` 与 import 包名以稳定值为准，不因文档命名口径变化自动迁移。
+
+## 目标
+
+`pz` 不是“宿主项目里不断长大的框架集合”，而是一套单一基础包加插件层的体系：
+
+- `pz` 提供稳定内核、正式合同与唯一启动壳
+- 官方通用能力进入官方扩展层
+- 业务能力进入业务扩展层
+- 宿主项目只做装配，不承担框架实现职责
+- concrete infra capability 的作者面与实现 owner 也必须留在最小子包层；`pz` 基础层只保留 typed contract、编译协议与扩展点
+
+这套模型与 task dispatch / worker owner 的设计目标一致：
+
+- 中心运行时稳定
+- 高层能力通过标准扩展接入
+- 业务变化优先在外层实现，不频繁回写内核
+
+面向对象落位规则：
+
+- 分层不是目录分组，而是对象职责边界。
+- `pz` 基础层优先拥有 contract object、compiler object、`RuntimePlan`、runtime context、capability/facade contract。
+- `pz_contrib` 与 owner 子包优先拥有 runtime owner、provider chain、assembler、adapter、对外 facade。
+- 业务子包优先拥有领域模型、应用 service、provider 实现、外部 adapter、`public.py` facade。
+- 宿主项目只保留项目配置与启动调用，不拥有通用 runtime owner 或第二套组合根。
+
+具体开发约束见 [`25-面向对象开发规范`](./25-面向对象开发规范.md)。
+
+## 四层模型
+
+### 1. 稳定内核与启动层：`pz`
+
+职责：
+
+- 唯一正式启动入口
+- `RuntimePlan` 编译
+- app registry / event registry / extension registry
+- bindings / lifecycle / capability registry
+- middleware / route / resource / provider 的正式合同
+- host builder 的发现约定、资源加载约定与调度协议
+- 标准 CLI 命令分发协议
+- 顶层 root CLI provider 协议
+- `infra.provider` 等面向 typed infra snapshot 的正式扩展合同
+
+约束：
+
+- 不承载官方业务实现
+- 不承载宿主页面壳
+- 不承载项目定制逻辑
+- 不为了单个业务问题新增一次性快捷路径
+- 即使 `pz-cli` 单 wheel 同时交付 `pz_core` 与官方 app Python 包，`pz_core` 仍不得直接 import 官方或业务 app 的内部实现
+
+允许进入 `pz` 基础层的改动只有两类：
+
+- 正式合同缺位
+- 现有正式合同无法表达多个扩展层共用的稳定抽象
+
+`pz` 基础层最终只应保留以下协议模块：
+
+- 项目与启动协议
+  - `project context`
+  - bootstrap config loader
+  - `installed_apps` 解析规则
+  - 环境覆盖顺序规则
+  - 唯一启动入口与 host 启动调度
+- 最小子包发现协议
+  - 最小子包判定规则
+  - 容器目录递归展开规则
+  - app identity 规则
+  - 项目本地 `apps/` 最小子包与已安装 distribution 同名并存时，本地最小子包优先
+  - 重复 `app_id` / 重复扩展冲突检测
+- 扩展点合同模块
+  - `host.builder`
+  - `settings.provider`
+  - `infra.provider`
+  - `cli.tool`
+  - 子包正式协议注册机制
+  - middleware / lifecycle / route / resource contribution
+- 编译与组装协议
+  - `RuntimePlan`
+  - settings snapshot 编译协议
+  - route / middleware / resource / CLI manifest 编译协议
+  - 冲突裁决规则
+- 运行时核心状态机
+  - lifecycle state machine
+  - runtime bindings contract
+  - capability / event registry contract
+  - runtime access facade
+- 错误与诊断合同
+  - 统一错误模型
+  - 统一诊断模型
+  - 编译期 / 启动期错误分类
+- CLI 主链协议
+  - `pz` 根命令分发
+  - app CLI 发现规则
+  - CLI tool 注册合同
+  - 命令冲突裁决
+- 资源加载协议
+  - 标准资源目录规则
+  - 资源 manifest
+  - 合并顺序与 cache/output 规则
+
+`RuntimePlan` 作为基础层唯一运行图组合根，最少必须稳定包含：
+
+- `project`
+- `settings`
+- `app_registry`
+- `route_manifest`
+- `middleware_manifest`
+- `resource_manifest`
+- `cli_manifest`
+- `lifecycle_manifest`
+- `capability_registry`
+- `extension_conflicts`
+
+补充约束：
+
+- `RuntimePlan.infra` 仍然是基础设施能力的唯一 typed snapshot
+- 但 `pz` 不再直接拥有 database / cache / mail / storage / health / metrics / tracing 的 concrete 作者面
+- `pz` 基础层只固定：
+  - `InfraContext` typed contract
+  - capability 状态语义
+  - `infra.provider` patch 编译协议
+- 具体配置字段写在哪个 app namespace，由对应 capability owner app 自己负责
+
+正式要求：
+
+- 所有扩展点都只允许先编译进入 `RuntimePlan`
+- 跨可选 runtime owner 的协议贡献必须显式声明 `ProtocolExtensionSpec(optional=True)`；owner 未安装时贡献保持惰性，owner 一旦安装仍执行完整协议校验。普通协议贡献默认严格，未知 kind 继续编译失败。
+- Web / CLI / worker 执行阶段只消费 `RuntimePlan`
+- `RuntimePlan` 编译完成后必须保持不可变快照语义
+- 入口层只能激活 `RuntimePlan` 已经编译出的对象图，不得在入口层重新选择 provider、adapter 或 runtime owner
+- 具体运行时资源必须归 owner object 管理；host、worker、infra、task、browser/session 等资源都不得以模块级全局状态存在
+- `startup()` / `lifespan` / adapter 不得在 `RuntimePlan` 外重新拼装第二份运行图
+- 若某个最小子包需要定义自己的正式 provider 协议，例如公开页面中心的页面装配或 SEO provider 协议，长期正式做法不是把该子包 runtime 搬进 `pz`，而是让 `pz` 提供“子包正式协议注册机制”，再由该子包把自己的协议注册进 `pz` 编译主链。
+- `pz` 基础层负责协议注册、编译、校验、冲突裁决与诊断主链；子包自身继续负责协议的具体消费、运行时装配与 owner 语义。
+- 因此，像公开页面中心这类公开页面 owner runtime，应保持 runtime 实现整体高内聚；不应因为协议要进入 core，就把 runtime owner 实现反向拆散到 `pz` 或 `contrib`。
+
+不应进入 `pz` 基础层的内容包括：
+
+- 官方 Web host 具体实现
+- settings surface owner、module config owner、settings runtime owner 的具体实现
+- admin owner / auth owner / infra owner / SEO owner / shared site UI owner 等官方功能包
+- DB / storage / mail / redis / s3 / 模板引擎的官方实现
+- database / cache / mail / storage / health / metrics / tracing 的 concrete settings owner
+- 配置管理 UI、项目模板、app 模板等高层实现
+
+### 2. 框架仓内官方维护子包容器：`pz_contrib`
+
+职责：
+
+- 收纳框架仓内官方维护的最小子包
+- 收纳框架仓内官方脚手架与通用装配实现
+- 不形成独立运行时 namespace
+
+典型内容：
+
+- settings surface owner
+- official infra owner
+- shared site UI owner
+- SEO owner
+- admin owner
+- auth owner
+- 通用 Web host
+- 官方 concrete infra owner app
+
+规则：
+
+- 这里可以快速演进
+- 但必须建立在 `pz` 已有合同之上
+- 如果发现合同缺口，先证明这是跨业务、跨扩展层的稳定需求，再回到 `pz`
+- `pz_contrib` 可以提供共享实现能力，但不承担“高优先级就应进入 contrib”的兜底角色；某个运行时若本质上是公开页面 owner，应优先保持在自己的 runtime 包内高内聚实现，而不是为抽象美观拆散到多个容器
+- `pz_contrib` 可以在源码分层上依赖 `pz`
+- 若 distribution 安装口径上需要官方扩展组合，正式命令应通过 `pz[contrib]` extras 表达，不改变源码分层方向
+
+对于 host，官方扩展层负责：
+
+- 声明 `host.builder`
+- 提供 Web host 的具体实现
+- 提供统一 route registry / route finalizer
+- 处理 infra bootstrap、route/middleware/static/lifecycle 装配
+- 在所有 app 的 URL 声明加载完成后，统一执行最终路由清理与排序
+- 为外部可见且需要 SEO 的 HTML 页面提供统一的首屏内容渲染约束：
+  - 首屏可见正文、SEO 关键文案、结构化数据所需稳定文本必须以后端渲染为正式主链
+  - 前端只负责交互增强、异步数据刷新与非首屏区块补充，不得反向成为首屏内容真相源
+  - `admin`、内部运营页、自用后台、强登录态工作台不强制纳入这条 SEO 首屏约束
+- 为上述公开 HTML 页面提供统一的请求期页面状态绑定 helper：
+  - 至少统一绑定 `lang`、`translation_module`、`page_profile`、`translation_bundles`、`client_translation_scopes`、`page_supported_language`、`page_language_alternates`
+  - 共享模板层与共享翻译 facade 应优先消费这份请求期合同，而不是要求各业务路由重复手写 state 注入
+  - 该 helper 属于 `pz_contrib` 或业务扩展层职责，不回写 `pz` 基础层
+- 对受保护 surface，正式 auth owner 是未登录拦截、登录页跳转与登录后按 `next` 回跳合同的唯一 owner；其它官方子包只通过正式 provider/extension 或 `route_policy` 注册公开例外、强制保护或 delegate surface，不保留第二套未登录重定向真相源
+- 对请求期认证语义，正式 auth owner 应采用 token-first 的稳定模型；普通子包不要假设 auth middleware 会为旧 token 或缺 claims token 在每个请求里回库补救，只有显式 model 依赖才应回库
+- 提供子路由组织与 include 式装配的统一能力，让最小子包只做模块声明，不重复实现框架级装配机制：
+  - 每个 app 的正式入口固定为 `<pkg>.urls`
+  - 简单 app 使用 `urls.py`
+  - 复杂 app 使用 `urls/` 目录，但正式入口仍然是 `urls/__init__.py`
+  - prefix、最终排序、最终清理由共享装配层统一处理
+- 若某个官方子包同时拥有 concrete infra capability，则它还负责：
+  - 定义自己的 settings namespace，例如 `settings_center.settings.<owner_app>.database`
+  - 通过 `infra.provider` 把 app settings 编译进 `RuntimePlan.infra`
+  - 让 DB CLI、readiness、worker、Web host 与 facade 继续只消费 `RuntimePlan.infra`
+
+上述公开 HTML 页面所适用的首屏展示、首帧稳定、首屏翻译、首屏关键资源与缓存对齐规则，统一以 `23-首屏展示与首帧稳定规范.md` 为准；本文件只保留分层责任，不再复制第二套细则。
+
+### 3. 业务扩展层：业务 app / 独立子包
+
+职责：
+
+- 业务 URL 声明
+- 业务 provider
+- 业务 middleware 声明
+- 业务 startup / shutdown
+- 业务 host 扩展声明
+
+规则：
+
+- 业务新增功能优先通过现有扩展点接入
+- 不直接改 `pz` 来适配单个业务
+- 对外部可见且需要 SEO 的业务 HTML 页面，默认必须先完成后端首屏渲染，再由前端做 hydrate 或增强
+- 不允许把公开页面的首屏正文、SEO 主文案、首屏 CTA 依赖前端二次请求后再补齐
+- 这类页面在进入模板前，必须先绑定统一请求期页面状态合同；业务路由不应长期各自手写同构 `request.state` 注入
+- 页面级前端增量取词范围必须通过正式字段暴露；纯 SSR 页面应显式给出空范围，而不是依赖隐式缺省
+- `admin`、内部工具页、纯登录后工作台不受这条 SEO 首屏规则强制约束
+- 不在宿主里手写框架替代层
+- 业务子包之间默认不直接 import 对方内部实现
+- 业务子包跨包依赖优先走对方 `public.py`、HTTP / API 或其它正式声明的 provider / facade
+- 不允许把 `apps.py`、`urls.py`、`urls/`、`settings` 内部实现当作跨包依赖入口
+- 需要认证的业务或官方 surface，默认由正式 auth owner 接管；子包只通过 `route_policy` / control-plane provider 声明“整包公开、公开例外、强制保护、delegate”这类正式输入，不在子包内部长期保留第二套未登录拦截、中间件跳登录或登录后回跳协议
+
+上述业务页面的首屏细则、SSR 稳定态、首屏资源优先级和 hydrate 约束，统一引用 `23-首屏展示与首帧稳定规范.md`，不在本文件内再维护一份并列规范。
+
+业务包应优先暴露：
+
+- `urls.py` 或 `urls/`
+- `extensions()`
+- `middlewares()`
+- `startup()`
+- `shutdown()`
+
+其中：
+
+- `<pkg>.urls` 是 app 自己的 URL 真相源，职责类似 Django app 内部的 `urls.py`
+- `apps.py` 不承担 URL 组装职责
+- 业务包只声明自己的路由树、子模块 include 关系与稳定 namespace
+- prefix 挂载、跨 app 装配、最终清理与排序都属于共享装配层职责
+
+### 4. 宿主装配层：项目仓
+
+职责：
+
+- `project_dir`
+- `.env`
+- `pz.jsonc`
+- `pz.{env}.jsonc`
+- 安装哪些 app
+- 调用通用 host builder
+
+规则：
+
+- 宿主不自己发明框架机制
+- 宿主不自己实现通用 host
+- 宿主不直接依赖外层源码仓布局
+- 宿主不补本地 shadow package
+
+宿主只允许保留：
+
+- bootstrap
+- 项目配置
+- 极少量宿主特有扩展声明
+
+项目配置规则：
+
+- app 配置读取真相源始终是 `settings_center.settings.<app_id>`
+- app 的正式 namespace 始终是其显式声明的 `app.id`，且必须与最小子包目录名、import 包名完全一致
+- `pz.jsonc` 只负责项目基础装配与非敏感覆盖
+- `pz.{env}.jsonc` 负责开发、测试、生产等环境差异覆盖
+- `.env` 负责通用敏感配置基线，`.env.{env}` 负责环境专属敏感覆盖
+- 通过 `PZ_ENV=develop|test|product` 选择环境覆盖文件；未显式指定时默认 `develop`
+- `product` 环境必须显式指定，不能靠 `.env.product` 的存在自动推导
+- 项目正式配置文件名固定为 `pz.jsonc`
+- 项目级 JSONC 的正式读写必须统一通过 `pz/utils/project_jsonc/`
+- 工具注释独占前缀固定为 `// @pz:`
+
+## 跨层依赖规则
+
+跨层与跨子包依赖固定遵循下面的单向约束：
+
+- `pz` 不依赖 `pz_contrib`、业务子包或宿主项目
+- `pz_contrib` 可以依赖 `pz`
+- 业务子包可以依赖 `pz` 与 `pz_contrib` 的正式公开面
+- 业务子包之间默认不直接 import 对方内部模块
+- 业务子包之间如需通信，优先走：
+  - 对方 `public.py`
+  - HTTP / API
+  - provider / facade / event 等正式暴露面
+- 对象依赖必须通过构造参数、factory、context、`RuntimePlan` 或正式 registry 显式注入；业务对象不得在方法内部临时 import 对方内部模块来选择实现
+
+不允许：
+
+- 子包直接把别的子包内部模块当依赖
+- 直接 import 对方的 `apps.py`、`urls.py`、`urls/`、`settings.py`、`settings/` 内部模块、service/manager/adapter
+- 通过“先能跑起来”作为理由建立跨子包源码硬耦合
+- 让调用方直接持有对方内部 repository、adapter、SDK client、session、pool 等实现对象
+
+## 变更决策顺序
+
+新增能力时，按下面顺序决策：
+
+1. 先判断能否只通过现有 app 合同完成
+2. 如果不能，判断能否在官方扩展层新增扩展处理器
+3. 只有当正式合同本身缺位时，才修改 `pz`
+
+反向约束：
+
+- 不允许因为单个业务页面需求直接扩展 `pz`
+- 不允许为了临时装配方便把通用实现塞回宿主
+
+## Host 规则
+
+Web host 相关能力应统一进入官方扩展层，而不是宿主手写：
+
+- app route declarations
+- middleware
+- lifecycle
+- static / resource mounts
+- health / ready
+
+宿主定制通过正式 host 扩展完成，例如：
+
+- `host.route`
+- `host.mount`
+- `host.state`
+
+`pz` 在这条链路里只负责一件事：
+
+- 从已安装 app 的 `extensions()` 中发现 `host.builder`
+- 按约定调用唯一生效的 builder
+
+`pz` 不允许：
+
+- 写死某个 official infra owner host builder 实现路径
+- 直接承载官方 host 组装实现
+- 夹带业务 bootstrap 或业务 router
+
+后续如确有必要，可继续扩展：
+
+- `host.static`
+- `host.openapi`
+- `host.response_header`
+
+### `host.builder` 正式对象形状
+
+`host.builder` 必须是单实例 builder 对象，而不是任意函数路径或隐式副作用入口。
+
+正式要求：
+
+- 每个 `host.builder` 必须至少具备：
+  - `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` 裁决；同优先级冲突直接报错
+- `build()` 只负责基于已编译 plan 产出 host，不重新发明第二套装配逻辑
+- `host.builder` 声明对象本身不得带副作用
+
+## Settings Provider 规则
+
+`settings.provider` 是正式补丁提供者，不是第二套运行时配置读取入口。
+
+正式要求：
+
+- 每个 `settings.provider` 必须至少具备：
+  - `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`
+
+约束：
+
+- provider 只能返回结构化 patch，不得直接改写全局 settings 状态
+- patch 只允许写正式 schema 已声明字段
+- provider 应幂等、可重复执行、尽量纯函数
+- 同目标路径同优先级冲突直接报错
+- 运行时代码仍然只能通过 `pz_settings_center` 读取配置
+
+## URL 组装规则
+
+URL 管理采用 Django 式集中装配模型：
+
+- 每个 app 的正式路由入口固定为 `<pkg>.urls`
+- 简单 app 使用 `urls.py`
+- 复杂 app 使用 `urls/` 目录，但正式入口固定为 `urls/__init__.py`
+- `<pkg>.urls` 使用 FastAPI 原生 `APIRouter()` / `include_router()` 声明本 app 的路由树
+- 官方扩展层统一收集所有 app 的 URL 声明，形成单一 route registry
+- Web host 只加载每个 app 的 `<pkg>.urls`
+- prefix 由上层统一挂载
+- 统一的 `clean_and_reorder_routes()` 只能存在于官方扩展层，并且必须在所有 app、host route、mount 都加载完成后最后执行
+- route namespace 必须稳定、清晰、可审计
+- 全站 trailing-slash 规范只能有一个正式解决方案
+
+全站 trailing-slash 正式方案：
+
+- slash 语义的正式真相源属于 route manifest，而不是业务包局部 helper
+- 每条正式 URL 只允许声明一个 canonical 版本；目录型页面 canonical 必须带 `/`，文件型 URL canonical 不带 `/`
+- host 必须基于已编译的 route manifest 与正式 redirect middleware 统一执行 slash normalization
+- 业务包不得各自手写第二套 trailing-slash redirect、canonical 修正或 slash dedupe
+- FastAPI/Starlette 默认的 `redirect_slashes` 不是正式契约真相源；host 应显式关闭这套默认行为，并只保留正式 redirect owner 的统一规范化结果
+- canonical、hreflang、sitemap、内部链接、redirect target 都必须消费同一套 slash 规则
+
+SEO 口径：
+
+- Google 将带 `/` 与不带 `/` 视为两个不同 URL；正式系统必须为每个公开页面选定唯一 preferred canonical
+- preferred canonical 必须通过稳定的永久重定向与一致的 canonical/hreflang/sitemap/internal links 表达
+- 是否选择“目录带 `/`、文件不带 `/`”不是 SEO 成败关键；单一 canonical、一致输出与永久重定向才是正式要求
+
+不允许：
+
+- app 在 `apps.py`、`startup()`、`lifespan` 中局部拼装 URL 主链
+- 宿主在 `main.py` 或 host 壳中手写 app 级路由排序规则
+- 依赖 app-local 的 route repair / dedupe / reorder 作为正式冲突治理
+- 业务包自己承担 prefix 挂载、跨 app 装配或最终清理职责
+- 各 app 自己复制机制性 helper，形成第二套路由装配框架
+- 各 app 自己实现第二套 trailing-slash middleware、slash redirect helper 或 canonical slash 修补逻辑
+
+## CLI 与脚手架规则
+
+CLI 命令入口属于 `pz`，因为用户安装 `pz` 后就应当拥有统一根命令。
+
+因此：
+
+- `pz` 根命令名与保留命令路径在 `pz` 中定义
+- `pz` 同时保留顶层 root CLI provider 协议、分发规则与内建作者面实现
+- `pz env` / `pz settings` / `pz startapp` / `pz app|dev|pub` 的具体实现统一放在 `pz`
+- `pz` 不为具体业务宿主再开第二套 init 命令或 `--profile <business>` 参数
+
+高层、官方模板化能力应优先放到官方扩展层，例如：
+
+- richer host template
+- 官方 app 模板集合
+- 官方项目模板集合
+
+也就是说：
+
+- 命令协议、根分发与项目作者面实现都在 `pz`
+- `pz_contrib` 不再承载第二套脚手架或项目 settings 作者面实现
+- 当前版本不定义“初始化骨架扩展点”；`pz` 的项目作者面骨架只来自内建通用实现
+- 业务化项目级默认值不应通过第二套命令或隐式注册器注入；app 作者面模板固定为各自配对的 `configs/default.jsonc` / `configs/default.env`，并且只由 `pz settings init/update` 同步到项目配置与项目 `.env*`
+
+### `cli.tool` 正式对象形状
+
+`cli.tool` 必须是带命令元数据的命令对象，而不是散落在任意模块里的自由函数。
+
+正式要求：
+
+- 每个 `cli.tool` 必须至少具备：
+  - `kind = "cli.tool"`
+  - `id`
+  - `owner_app`
+  - `api_version`
+  - `priority`
+  - `command`
+  - `summary`
+  - `tool`
+- `tool` 必须实现：
+  - `configure(parser) -> None`
+  - `run(ctx: CliInvocationContext) -> int`
+- `CliInvocationContext` 至少包含：
+  - `project`
+  - `args`
+  - `stdout`
+  - `stderr`
+
+约束：
+
+- `command` 必须是稳定命令路径，例如 `("settings", "sync")`
+- `configure()` 只配置参数，不执行副作用
+- `run()` 必须返回明确 exit code
+- 命令冲突按 `priority` 裁决；同优先级冲突直接报错
+- CLI 发现只基于正式 `cli/` 目录约定与 `CliToolSpec` 对象，不靠动态脚本猜测
+- CLI 发现必须在 `RuntimePlan` 编译阶段产出 `cli_manifest`
+- Web / CLI / worker 执行阶段只允许消费 `RuntimePlan.cli_manifest`，不得重新扫描目录生成第二份命令图
+
+## 稳定性目标
+
+`pz` 基础层达到冻结线后，应遵循：
+
+- 默认不改
+- 改动必须证明是合同级问题
+- 新功能默认进入扩展层
+
+验收标准：
+
+- 新业务不需要修改 `pz` 就能接入
+- 官方通用能力不需要宿主手写壳
+- 宿主只做装配和配置