pz-cli 5.0.0__tar.gz

pz_cli-5.0.0/.gitignore

@@ -0,0 +1,85 @@
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+.coverage.*
+pz_core.egg-info/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.DS_Store
+.idea/
+.vscode/
+/.runtime/
+/output/
+/var/
+/logs/
+.git.monorepo-backup/
+.venv.pre-*-migration/
+.pw-user-data/
+.pw-user-data-*/
+playwright-report/
+test-results/
+.playwright/
+.playwright-cli/
+*.swp
+*.swo
+
+# Testing
+.tox/
+.nox/
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Flask
+instance/
+.webassets-cache
+
+# Logs
+*.log
+logs/
+
+# Database
+*.db
+*.sqlite3
+
+# Local development settings
+local_settings.py
+
+# Media and static files (if managed separately)
+media/
+# static/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+.claude/
+
+# Compiled translations
+*.mo
+*.pot
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Uploaded files
+uploads/
+worker_tmp_dir/
+
+# Merged static files
+merged
+.static_files_merge*
+
+pg_data
+
+# local deploy repo / worktree (kept independent from pz)
+/deploy/

pz_cli-5.0.0/AGENTS.md

@@ -0,0 +1,5 @@
+# Agent Instructions
+
+## Agent Prompt Dependency
+
+Spend time thinking carefully before answering. Do not rush to the final answer. For difficult coding or reasoning tasks, prefer correctness over responsiveness. Avoid optional progress updates unless they are necessary for tool use.

pz_cli-5.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: pz-cli
+Version: 5.0.0
+Summary: PZ CLI, runtime compiler, settings owner, and foundation runtime
+Project-URL: Homepage, https://github.com/JiXiangTools/pz
+Project-URL: Repository, https://github.com/JiXiangTools/pz
+Author: pz maintainers
+License-Expression: LicenseRef-Proprietary
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: aerich<1.0,>=0.8
+Requires-Dist: aiofiles<25.0,>=24.1
+Requires-Dist: boto3<2.0,>=1.38
+Requires-Dist: fastapi<1.0,>=0.110
+Requires-Dist: packaging<26,>=24
+Requires-Dist: pillow<13.0,>=10.4
+Requires-Dist: pydantic<3.0,>=2.10
+Requires-Dist: redis<7,>=5
+Requires-Dist: requests<3.0,>=2.32
+Requires-Dist: tomlkit<1.0,>=0.13
+Requires-Dist: tortoise-orm<1.0,>=0.25
+Requires-Dist: uvicorn<1.0,>=0.35
+Provides-Extra: db-mysql
+Requires-Dist: pymysql<2.0,>=1.1; extra == 'db-mysql'
+Provides-Extra: db-postgres
+Requires-Dist: asyncpg<1,>=0.30; extra == 'db-postgres'
+Requires-Dist: psycopg[binary,pool]<4.0,>=3.2; extra == 'db-postgres'
+Description-Content-Type: text/markdown
+
+# pz-cli
+
+`pz-cli` is the single install and release unit for the PZ base runtime.
+
+Version 5.0.0 bundles the `pz_core`, `pz_settings_center`, and `pz_foundation`
+Python packages in one wheel and exposes the formal `pz` command. The retired
+`pz-core`, `pz-contrib`, `pz-settings-center`, and `pz-foundation`
+distributions are no longer built or installed separately. Business packages
+from the `pz_apps` repository remain independent distributions.
+
+```bash
+pip install pz-cli==5.0.0
+```
+
+The source checkout uses one root `pyproject.toml` and one root `uv.lock`.
+Package-specific documentation lives under each bundled Python package's
+`docs/` directory.

pz_cli-5.0.0/README.md

@@ -0,0 +1,17 @@
+# pz-cli
+
+`pz-cli` is the single install and release unit for the PZ base runtime.
+
+Version 5.0.0 bundles the `pz_core`, `pz_settings_center`, and `pz_foundation`
+Python packages in one wheel and exposes the formal `pz` command. The retired
+`pz-core`, `pz-contrib`, `pz-settings-center`, and `pz-foundation`
+distributions are no longer built or installed separately. Business packages
+from the `pz_apps` repository remain independent distributions.
+
+```bash
+pip install pz-cli==5.0.0
+```
+
+The source checkout uses one root `pyproject.toml` and one root `uv.lock`.
+Package-specific documentation lives under each bundled Python package's
+`docs/` directory.

pz_cli-5.0.0/docs/history/pz_contrib/2026-04-22-contrib-deprecated-code-audit.md

@@ -0,0 +1,388 @@
+# pz_contrib 废弃代码排查临时 todo
+
+日期：2026-04-22
+
+## 目标
+
+先完成 `pz_contrib` 的废弃代码排查，按以下违规类型收敛：
+
+- 旧入口仍被当作正式入口使用
+- 第二套运行时读取面仍在主链生效
+- 历史兼容壳 / shim / alias 仍在正式装配链
+- 已无引用的残留文件仍留在源码树
+
+## 已确认
+
+### 1. `pz_settings_operator` 旧 `config-center` 路径未完成 cutover
+
+- `apps.py` 的 admin panel 已切到 `/admin/settings-operator`
+- 但 admin menu children 仍指向：
+  - `/admin/config-center/runtime`
+  - `/admin/config-center/security`
+- `routes.py` 仍把 `legacy_router` 纳入正式 router 导出
+- `settings_admin/pages.py` 仍保留整组 `/admin/config-center* -> /admin/settings-operator*` redirect
+- 现有测试仍把这组旧路径当作当前 contract 的一部分
+
+相关文件：
+
+- `pz_settings_operator/pz_settings_operator/apps.py`
+- `pz_settings_operator/pz_settings_operator/routes.py`
+- `pz_settings_operator/pz_settings_operator/settings_admin/pages.py`
+- `tests/test_settings_operator_menu_contract.py`
+- `tests/test_settings_operator_admin_redirects.py`
+
+### 2. `pz_api_access` 仍保留第二套运行时 settings 读取面
+
+- 文档口径已收敛为运行时只读 `settings_center.settings.pz_api_access.*`
+- 但 `settings.py` 仍导出 `runtime_settings_namespace()`
+- `public.py` 仍通过 `_read_runtime_setting(..., legacy_field=...)` 对旧大写字段做运行时 fallback
+- 多个运行时代码仍直接 import / 调用 `runtime_settings_namespace()`
+
+已确认调用点：
+
+- `pz_api_access/pz_api_access/public.py`
+- `pz_api_access/pz_api_access/routers.py`
+- `pz_api_access/pz_api_access/deps.py`
+- `pz_api_access/pz_api_access/account/widgets.py`
+- `pz_api_access/pz_api_access/storage/input_storage.py`
+
+### 3. `pz_foundation/routers.py` 疑似无引用残留壳
+
+- 正式 URL 真相源已经是 `pz_foundation/routes.py`
+- 同级仍保留 `routers.py`
+- 文件内容只有空的 `routers = ()`
+- 当前在 `pz_contrib` 与宿主源码里未检出真实引用
+
+相关文件：
+
+- `pz_foundation/pz_foundation/routers.py`
+- `pz_foundation/pz_foundation/routes.py`
+
+### 4. `pz_account` 仍保留第二套未登录跳转协议
+
+状态：已完成（2026-04-22）
+
+- `pz_auth` 文档已冻结：受保护 HTML surface 的未登录拦截、登录页跳转和 `next` 回跳由 `pz_auth` 单一持有
+- `pz_account` 自己的 `settings.py + configs/default.jsonc` 已声明 `route_policy`
+- 但页面仍在本地通过 `Depends(get_current_user)` 手写：
+  - `/{lang}/dashboard -> /{lang}/login?next=...`
+  - `/{lang}/dashboard/subscription/paypal/{subscription_id} -> /{lang}/login?next=...`
+- 客户端脚本 `paypal-subscription.js` 在收到 `401` 时也会自行跳转登录页
+
+相关文件：
+
+- `pz_account/pz_account/pages.py`
+- `pz_account/pz_account/static/account/js/paypal-subscription.js`
+- `pz_account/pz_account/settings.py`
+- `pz_account/pz_account/configs/default.jsonc`
+
+### 5. `pz_api_access` 页面仍保留第二套未登录跳转协议
+
+状态：已完成（2026-04-22）
+
+- `pz_api_access/configs/default.jsonc` 已把 `/{lang}/account/api-examples` 纳入 `route_policy.auth_paths`
+- 但页面实现仍使用 `Depends(get_current_user)` 本地判空后手写跳转：
+  - `/{lang}/account/api-examples -> /{lang}/login?next=...`
+- 这使得 `auth.route_policy` 和页面本地 redirect 同时成为未登录跳转 owner
+
+相关文件：
+
+- `pz_api_access/pz_api_access/pages.py`
+- `pz_api_access/pz_api_access/settings.py`
+- `pz_api_access/pz_api_access/configs/default.jsonc`
+
+### 6. `pz_admin` 仍保留旧的模块配置 owner 页面 `/admin/settings`
+
+状态：已完成（2026-04-22）
+
+- 历史 `pz_module_config` README 与设计文档曾把 `/admin/module-config` 定义为模块配置唯一正式后台入口
+- 当前正式语义已经收口到 `pz_page_center`；`module_config` 只保留为其内部子域实现目录
+- 但 `pz_admin.pages` 仍继续导出 `/admin/settings`
+- 该页面实际渲染的就是模块配置 UI：
+  - 顶部标题仍写“系统设置”
+  - 页面内部调用 `/api/v1/module-config/modules`
+  - 校验/应用走 `/api/v1/module-config/validate` 与 `/api/v1/module-config/apply`
+- 旧文档里的 `pz_module_config` owner 口径已过时，不再作为正式边界依据
+- 这说明 `/admin/settings` 不是独立正式能力，而是模块配置 cutover 后仍残留在 `pz_admin` 的旧 owner 入口；当前正式 owner 应按 `pz_page_center` 口径理解
+
+相关文件：
+
+- `pz_admin/pz_admin/pages.py`
+- `pz_admin/pz_admin/templates/admin/settings.html`
+- `pz_page_center/pz_page_center/module_config/admin/pages.py`
+- `pz_page_center/README.md`
+- `pz_page_center/docs/设计文档.md`
+- `pz_settings_operator/docs/01-settings_operator能力边界.md`
+- `tests/test_admin_app_contract.py`
+
+### 7. `pz_admin` 仍保留旧的 runtime settings owner 页面 `/admin/runtime-settings`
+
+状态：已完成（2026-04-22）
+
+- `pz_settings_operator` README 已把 admin 侧 runtime settings 管理后台定义为自己的正式职责
+- `pz_settings_operator.settings_admin.pages` 已正式持有：
+  - `/admin/settings-operator`
+  - `/admin/settings-operator/runtime`
+- 但 `pz_admin.pages` 仍继续导出 `/admin/runtime-settings`
+- 两边渲染的是同一个 `admin/runtime_settings.html` 模板
+- 模板内部实际调用的 API 也全部是 `/api/v1/settings-operator/*`
+- 因此 `/admin/runtime-settings` 更像 settings operator cutover 后遗留的旧 owner 页面，而不是独立正式入口
+
+相关文件：
+
+- `pz_admin/pz_admin/pages.py`
+- `pz_admin/pz_admin/templates/admin/runtime_settings.html`
+- `pz_settings_operator/pz_settings_operator/settings_admin/pages.py`
+- `pz_settings_operator/README.md`
+- `pz_settings_operator/docs/01-settings_operator能力边界.md`
+- `tests/test_admin_app_contract.py`
+
+### 8. `pz_foundation` 仍保留旧的 project-level infra settings 读取面
+
+状态：已完成（2026-04-22）
+
+- `pz_foundation` README 已把运行时正式读取路径收敛为：
+  - `settings_center.settings.pz_foundation.database`
+  - `settings_center.settings.pz_foundation.cache`
+  - `settings_center.settings.pz_foundation.storage`
+  - `settings_center.settings.pz_foundation.mail`
+  - `settings_center.settings.pz_foundation.health`
+  - `settings_center.settings.pz_foundation.observability`
+- 但多组 foundation runtime helper 仍直接走 `resolve_settings(...).project.get(...)` 读取旧 project-level section：
+  - `project.database`
+  - `project.redis`
+  - `project.storage`
+  - `project.mail`
+  - `project.metrics`
+  - `project.runtime_dir`
+  - `project.data_dir`
+  - `project.cache_dir`
+- 其中 database helper 还继续接受旧 alias 字段：
+  - `database_url`
+  - `db_type`
+  - `db_host`
+  - `db_port`
+  - `db_user`
+  - `db_password`
+  - `db_name`
+- 这些 helper 不是闲置代码，`lifecycle.py`、`host/*`、`kv/deps.py`、health / observability probe 等运行时主链仍在调用它们
+- 这等于 `pz_foundation` 仍保留了一整套绕开 `settings_center.settings.pz_foundation.*` 的历史 infra settings surface
+
+相关文件：
+
+- `pz_foundation/README.md`
+- `pz_foundation/pz_foundation/db/database.py`
+- `pz_foundation/pz_foundation/kv/cache.py`
+- `pz_foundation/pz_foundation/kv/deps.py`
+- `pz_foundation/pz_foundation/storage/service.py`
+- `pz_foundation/pz_foundation/storage/local.py`
+- `pz_foundation/pz_foundation/notifications/email.py`
+- `pz_foundation/pz_foundation/observability/runtime.py`
+- `pz_foundation/pz_foundation/health.py`
+- `pz_foundation/pz_foundation/lifecycle.py`
+- `pz_foundation/pz_foundation/host/lifespan.py`
+- `pz_foundation/pz_foundation/host/redis_runtime.py`
+- `pz_foundation/pz_foundation/host/db/config.py`
+
+### 9. 多个 contrib app 仍直接依赖 `pz.runtime.settings`，绕过 `pz_settings_center.public`
+
+状态：已完成（2026-04-22）
+
+- `pz_settings_center` 文档已经明确：
+  - `legacy_core.runtime.settings` 只保留底层 machinery
+  - 应用层正式入口固定为 `pz_settings_center.public`
+  - `public.py` 是唯一正式入口
+- 但当前仍有多个 contrib app 直接 import core runtime helper，而不是走 `pz_settings_center.public`
+- 已确认存在 formal public 等价 helper 但仍直接走 core 的位置包括：
+  - `pz_account.apps` -> `current_settings_project_dir`
+  - `pz_seo.apps` -> `current_settings_project_dir`
+  - `pz_preflight.checks.defaults.page_asset_bundles` -> `active_settings_project`, `bound_settings_snapshot`
+  - `pz_preflight.checks.defaults.event_declarations` -> `active_settings_project`, `bound_settings_snapshot`
+  - `pz_settings_operator.settings_runtime.runtime_binding` -> `current_settings_project_dir`
+  - `pz_auth.route_policy_runtime` -> `get_applied_runtime_overrides`
+  - `pz_auth.route_policy_settings` -> `get_applied_runtime_overrides`
+- `pz_settings_center/README.md` 还明确写了 `public.py` 对外暴露 runtime override helper
+- 这说明 contrib 层对 core settings machinery 的直接依赖还没完全收口到 `pz_settings_center.public`
+
+相关文件：
+
+- `pz_settings_center/docs/01-settings_center能力边界.md`
+- `pz_settings_center/README.md`
+- `pz_settings_center/pz_settings_center/public.py`
+- `pz_account/pz_account/apps.py`
+- `pz_seo/pz_seo/apps.py`
+- `pz_preflight/pz_preflight/checks/defaults/page_asset_bundles.py`
+- `pz_preflight/pz_preflight/checks/defaults/event_declarations.py`
+- `pz_settings_operator/pz_settings_operator/settings_runtime/runtime_binding.py`
+- `pz_auth/pz_auth/route_policy_runtime.py`
+- `pz_auth/pz_auth/route_policy_settings.py`
+
+### 10. `pz_redirects` 仍保留 CMS-owned redirect 运行链与 API namespace
+
+状态：已完成（2026-04-22）
+
+- `pz_redirects/README.md` 已把本包定义为独立的 redirects 最小子包：
+  - 自己负责数据库重定向、配置规则、缓存管理、admin 面板与 API
+  - 对外正式接入也要求走 `pz_redirects.public` 或其 admin/API surface
+- 但当前运行时主链仍把 CMS 当成 redirect storage / content section 的事实 owner：
+  - `cache.py` 的 `_repository()` 直接 import `pz_cms.public.get_content_service()`，并从其 `repository` 读取 redirect rules
+  - `api.py` 的 CRUD 入口 `_content_repository()` 也先走 `pz_cms.public.get_content_service().repository`
+  - `TrailingSlashMiddleware` 继续从 `pz_cms` 的 app config 读取 `sections`
+- 同时正式 surface 仍保留旧 CMS 命名：
+  - API 前缀仍是 `/api/v1/cms/seo`
+  - admin 模板内部请求也全部打到 `/api/v1/cms/seo/redirects*`
+- 这不是单纯的历史命名残留，而是 redirect app 的运行时存储链和 API namespace 仍然绑定在旧 CMS owner 上，cutover 没有真正收口到 `pz_redirects`
+
+相关文件：
+
+- `pz_redirects/README.md`
+- `pz_redirects/pz_redirects/api.py`
+- `pz_redirects/pz_redirects/cache.py`
+- `pz_redirects/pz_redirects/middlewares/trailing_slash_redirect.py`
+- `pz_redirects/pz_redirects/templates/admin/redirects.html`
+
+### 11. `pz_auth` / `pz_admin` 仍把 `settings.py` 当运行时 loader 入口
+
+状态：已完成（2026-04-22）
+
+- `pz_settings_center/README.md` 与工作区规范已经收敛为：
+  - Python 运行时代码获取配置只允许 `import pz_settings_center.public as settings_center`
+  - app 私有配置唯一正式读取路径固定为 `settings_center.settings.<app_id>.<field>`
+  - 不再允许 `load_<app>_settings()`、`load_app_settings()`、`load_typed_app_settings()` 或其它绕开 `settings_center` 的第二套入口
+- 但当前仍有 contrib runtime 主链直接调用 `settings.py` 中的 resolver：
+  - `pz_auth.lifecycle` 在 startup 时调用 `resolve_auth_settings(project_dir=...)`
+  - `pz_admin.assembly` 在 runtime 装配时调用 `resolve_admin_settings(project_dir=...)`
+- 这意味着 `settings.py` 仍不只是 schema/defaults 声明面，而是继续作为运行时 typed loader 生效，和 `settings_center.settings.<app_id>` 并存成第二套读取入口
+
+相关文件：
+
+- `AGENTS.md`
+- `pz_settings_center/README.md`
+- `pz_auth/pz_auth/settings.py`
+- `pz_auth/pz_auth/lifecycle.py`
+- `pz_admin/pz_admin/assembly.py`
+
+### 12. `pz_redirects` 仍保留 CMS-era 存储表与索引命名
+
+状态：已完成（2026-04-22）
+
+- `pz_redirects` 的运行时 owner 与 API namespace 已收口到正式 app surface
+- 但实际 ORM / schema 命名仍保留旧 CMS-era 表名与索引名：
+  - `RedirectRuleModel.Meta.table = "cms_redirect_rules"`
+  - `repository.py` 里的 schema self-heal SQL 仍操作 `cms_redirect_rules`
+  - 索引名仍为 `idx_cms_redirect_rules_tenant_is_system`
+- 这已经不再是 API/owner 链问题，而是独立的数据库迁移问题
+- 本轮已完成：
+  - 正式表名切到 `pz_redirect_rules`
+  - repository 自愈 SQL 的正式表名 / index 名同步切换
+  - 新增 `migrations/pz_redirects/0_20260422130000_redirect_storage_owner_cutover.py`
+  - migration 兼容旧 `cms_redirect_rules` 到新 owner 表名的 rename/create 场景
+  - 宿主重装、健康检查与 `pz db history/status` owner 识别验证通过
+
+相关文件：
+
+- `pz_redirects/pz_redirects/models.py`
+- `pz_redirects/pz_redirects/repository.py`
+- `pz_redirects/pz_redirects/migrations/pz_redirects/0_20260422130000_redirect_storage_owner_cutover.py`
+- `pz_auth/pz_auth/lifecycle.py`
+- `pz_admin/pz_admin/settings.py`
+- `pz_admin/pz_admin/assembly.py`
+
+### 12. `pz_seo.apps.__all__` 仍导出不存在的 `load_seo_settings`
+
+状态：已完成（2026-04-22）
+
+- `pz_seo/apps.py` 文件末尾仍写着：
+  - `__all__ = ["SeoApp", "app", "load_seo_settings"]`
+- 但当前 `pz_seo/apps.py` 与同包源码中都没有 `load_seo_settings` 的定义或导入
+- 仓内检索结果里，这个名字只剩下：
+  - `pz_seo/apps.py::__all__`
+  - settings contract 测试里对历史 `load_seo_settings` loader helper 的清理约束
+- 这更像 cutover 后漏清的历史导出名，而不是仍有职责的正式 surface
+
+相关文件：
+
+- `pz_seo/pz_seo/apps.py`
+- `pz_seo/pz_seo/settings.py`
+- `tests/test_settings_contract.py`
+
+### 13. `pz_redirects.settings.resolve_redirects_settings()` 是未收口的旧 loader helper
+
+状态：已完成（2026-04-22）
+
+- `pz_redirects/README.md` 已明确：
+  - 运行时正式读取路径固定为 `settings_center.settings.pz_redirects.*`
+  - `settings.py` 只负责 schema、规则类型与默认值装配
+- 但 `pz_redirects.settings` 仍继续导出 `resolve_redirects_settings()`
+- 仓内检索结果里，这个名字只剩下：
+  - `pz_redirects/settings.py` 的函数定义
+  - 同文件 `__all__` 导出
+- 在 `pz_contrib`、`MangaTranslate`、tests、docs 中都未检出任何真实调用或文档承诺
+- 这说明它不是当前正式运行面，而是 cutover 后遗留在 `settings.py` 里的旧 typed loader helper
+
+相关文件：
+
+- `pz_redirects/README.md`
+- `pz_redirects/pz_redirects/settings.py`
+- `tests/test_settings_contract.py`
+
+### 14. `pz_admin.settings.project_settings` 是遗留的 settings alias 公开面
+
+状态：已完成（2026-04-22）
+
+- `pz_admin/README.md` 已明确：
+  - 唯一稳定公开面是 `pz_admin.public`
+  - `settings.py` 只负责 schema 声明与默认值装配
+- 但 `pz_admin.settings` 仍保留：
+  - `project_settings = settings_center.settings`
+  - 并把它放进 `__all__`
+- 仓内检索没有任何运行时代码通过 `pz_admin.settings.project_settings` 读取配置
+- 现有唯一命中只剩 `tests/test_settings_contract.py` 顶部的一条 import，而且该别名在测试体内没有实际使用
+- 这说明它已经不是仍有职责的正式入口，而是 `settings_center.settings` 收口后没清掉的历史 alias surface
+- 本轮已一并删除同文件内无人引用的 `resolve_admin_settings()` 旧 loader helper，避免继续在 `settings.py` 留第二套运行时读取面
+
+相关文件：
+
+- `pz_admin/README.md`
+- `pz_admin/pz_admin/settings.py`
+- `tests/test_settings_contract.py`
+
+## 继续排查
+
+- [ ] `pz_admin`
+- [ ] `pz_auth`
+- [ ] `pz_account`
+- [ ] `pz_api_access`
+- [ ] `pz_foundation`
+- [ ] `pz_module_config`
+- [ ] `pz_preflight`
+- [ ] `pz_redirects`
+- [ ] `pz_seo`
+- [ ] `pz_settings_center`
+- [ ] `pz_settings_operator`
+- [ ] `pz_site_ui`
+
+## 待确认
+
+- `pz_module_config.runtime`
+  - 仍保留 `pz_cms_module_config_active_project_dir` 这类旧 ContextVar 名字
+  - 运行时异常文案也仍写着 `cms module_config runtime binding is ambiguous`
+  - 已验证仓内没有任何代码或文档以这些旧名字作为正式 surface 依赖
+  - `README` / `public.py` 的正式公开面也都没有暴露这些字符串
+  - 目前更像内部命名残留，不单独升格为废弃代码项；后续若做 cleanup，可作为顺手重命名处理
+- 在 `MangaTranslate` 宿主源码中未检出对 `/admin/settings`、`/admin/runtime-settings`、`/admin/config-center`、`/admin/settings-operator` 的显式引用
+
+相关文件：
+
+- `pz_admin/pz_admin/pages.py`
+- `pz_admin/pz_admin/routes.py`
+- `pz_admin/README.md`
+- `tests/test_admin_app_contract.py`
+- `tests/test_settings_contract.py`
+- `pz_module_config/pz_module_config/runtime.py`
+
+## 排查备注
+
+- 先查全，不在这个阶段直接删代码
+- 新发现继续追加到本文件
+- 最终再按“明确废弃 / 高概率废弃 / 需验证后再删”三档收敛

pz_cli-5.0.0/docs/history/pz_contrib/README.md

@@ -0,0 +1,22 @@
+# Docs Index
+
+`pz_contrib` 是官方实现的 source-root 容器仓。
+
+子包文档入口按约定位置查找：
+- `pz_account/docs/README.md`
+- `pz_admin/docs/README.md`
+- `pz_api_access/docs/README.md`
+- `pz_auth/docs/README.md`
+- `pz_foundation/docs/README.md`
+- `pz_page_center/docs/README.md`
+- `pz_preflight/docs/README.md`
+- `pz_redirects/docs/README.md`
+- `pz_seo/docs/README.md`
+- `pz_settings_center/docs/README.md`
+- `pz_settings_operator/docs/README.md`
+- `pz_site_ui/docs/README.md`
+
+阅读顺序：
+- 先读本索引
+- 再进入目标子包的 `docs/README.md`
+- 如果子包后续冻结了 `docs/设计文档.md`，再以该设计文档为高优先级约束