pz-cli 5.0.0__py3-none-any.whl

pz_core/docs/pz/345/221/275/344/273/244/346/200/273/350/247/210.md

@@ -0,0 +1,1011 @@
+# `pz` 命令总览
+
+本文件专门记录当前正式 `pz` 命令面。
+
+如果本文件与 `pz` 设计文档、正式 contract 或源码实际行为冲突，以后者为准。
+
+相关文档：
+
+- [`README.md`](README.md)
+- [`新手指南.md`](新手指南.md)
+- [`pz规范与使用/24-pz启动与运行时编译流程.md`](pz规范与使用/24-pz启动与运行时编译流程.md)
+- [`pz规范与使用/09-CLI与Worker入口规范.md`](pz规范与使用/09-CLI与Worker入口规范.md)
+- [`pz dev source ownership 设计`](../../../docs/superpowers/specs/2026-07-13-pz-dev-add-link-source-ownership-design.md)
+- [`pz app version resolution 设计`](../../../docs/superpowers/specs/2026-07-13-pz-app-version-resolution-design.md)
+- [`pz pub Git release orchestration 设计`](../../../docs/superpowers/specs/2026-07-13-pz-publish-git-release-orchestration-design.md)
+
+## 1. 总原则
+
+- 项目启动统一走 `pz run`
+- 项目配置初始化、更新、托管区块刷新统一走 `pz settings ...` / `pz env ...`
+- 新开发项目统一从 `pz dev init` 进入
+- 发布包安装统一走 `pz app ...`
+- 业务源码导入与上游源码联调统一走 `pz dev ...`
+- 发布统一走 `pz pub ...`
+- 运行时诊断统一走 `pz list`、`pz check`、`pz db ...`、`pz <app_id> <tool>`
+
+`pz` 只是正式 launcher facade，不是第二套运行时真相源。
+
+`pz` 是高频基础入口，定型后必须保持稳定。允许变更范围固定为：
+
+- 修复与既有 contract 不一致的 bug
+- 补齐缺失的 contract / 测试 / 文档
+- 增加明确纳入 contract 的新命令或新选项
+
+不得随业务能力变化而改变既有命令语义、provider 顺序、入口函数、安装依赖边界或 `project_dir` 解析规则。
+
+每次执行 `pz` 时，provider 选择顺序固定为：
+
+1. 当前项目本地 `.venv`
+2. 当前项目 dev manifest 里记录的 `pz` bootstrap runtime path（正式 checkout 位于 `apps/.sources/pz`）
+3. 当前解释器里的已安装 `site-packages`
+4. `uv tool run --from pz-cli pz`
+
+这一步只负责决定这次命令最终落到哪个 `pz_core.cli:main`，不改变 `pz` 仍然是唯一正式基础包与唯一正式 CLI 真相源的约束。`pz.root_cli` 只是顶层命令 provider entry-point group，不是第二个 CLI 入口。
+
+## 2. 命令分类唯一真相表与顶层清单
+
+所有正式命令只属于下列三层之一。本表是命令分类的唯一正式真相源；`README.md`、`09-CLI与Worker入口规范.md` 和 `pz --help` 只做一致摘要，不另行定义分类。
+
+| 层级 | 唯一命令集合 | 边界 |
+| --- | --- | --- |
+| 编排命令 | `pz dev init`、`pz dev add`、`pz dev link`、`pz dev branch`、`pz dev update`、`pz dev unlink`、`pz env init`、`pz app init`、`pz app add`、`pz app update`、`pz app rm`、`pz pub`、`pz pub batch` | 组合多个已有原子动作，不引入第二套装配、版本解析、IDE 投影或发布协议。 |
+| 原子命令 | `pz env doctor`、`pz env install`、`pz env sync`、`pz settings init`、`pz settings update`、`pz settings refresh-agents`、`pz settings reset-agents`、`pz startapp`、`pz app versions`、`pz app declare`、`pz app undeclare`、`pz app install`、`pz dev source cache`、`pz dev source import`、`pz dev source link`、`pz dev source branch`、`pz dev source update`、`pz dev source unlink`、`pz dev ide sync`、`pz pub commit`、`pz pub tag`、`pz pub upload`、`pz pub rm` | 执行一个可单独验证、重试的作者面动作。 |
+| 运行时命令 | `pz run`、`pz list`、`pz check`、`pz db ...`、`pz workers ...`、`pz resources ...`、`pz <app_id> <tool>` | 编译或消费当前正式运行时计划，不修改作者面命令分类。 |
+
+以下是当前正式顶层命令签名清单：
+
+- `pz env doctor`
+- `pz env install`
+- `pz env init`
+- `pz env sync`
+- `pz settings init`
+- `pz settings update`
+- `pz settings refresh-agents`
+- `pz settings reset-agents`
+- `pz run`
+- `pz run develop`
+- `pz run dev`
+- `pz run test`
+- `pz run product`
+- `pz startapp`
+- `pz app init`
+- `pz app add`
+- `pz app rm`
+- `pz app update`
+- `pz app versions`
+- `pz app declare`
+- `pz app undeclare`
+- `pz app install`
+- `pz dev init`
+- `pz dev add`
+- `pz dev link`
+- `pz dev branch`
+- `pz dev update`
+- `pz dev unlink`
+- `pz dev source cache`
+- `pz dev source import`
+- `pz dev source link`
+- `pz dev source branch`
+- `pz dev source update`
+- `pz dev source unlink`
+- `pz dev ide sync`
+- `pz pub`
+- `pz pub commit`
+- `pz pub tag`
+- `pz pub upload`
+- `pz pub rm`
+- `pz pub batch`
+- `pz list`
+- `pz check`
+- `pz db makemigrations`
+- `pz db migrate`
+- `pz db showmigrations`
+- `pz workers list`
+- `pz workers status`
+- `pz workers stop`
+- `pz workers restart`
+- `pz workers run`
+- `pz resources images`
+- `pz <app_id> <tool>`
+
+命令路径不做缩写，不登记 `pz e d`、`pz a i`、`pz b mm` 这类二级 alias，也不按前缀猜测命令。高频简写只发生在参数层，并且必须通过 `pz_core.cli_options.add_cli_option()` 的同一份公共表注册；各命令的 `-h` 由 argparse 自动展示长短参数。
+
+当前正式参数短选项：
+
+| 完整参数 | 短参数 |
+| --- | --- |
+| `--app-name` | `-a` |
+| `--base-branch` | `-b` |
+| `--clone-sources` | `-C` |
+| `--concurrency` | `-c` |
+| `--dry-run` | `-n` |
+| `--delete-checkout` | `-X` |
+| `--extra` | `-x` |
+| `--force` | `-f` |
+| `--group` | `-g` |
+| `--host` | `-H` |
+| `--json` | `-j` |
+| `--no-sync` | `-S` |
+| `--once` | `-o` |
+| `--poll-interval` | `-I` |
+| `--port` | `-p` |
+| `--prepare-workspace` | `-w` |
+| `--project-dir` | `-d` |
+| `--project-only` | `-P` |
+| `--reinstall-package` | `-i` |
+| `--reload` | `-r` |
+| `--replica-slot` | `-l` |
+| `--reset-middlewares-order` | `-M` |
+| `--shutdown-timeout` | `-T` |
+| `--status` | `-s` |
+| `--target` | `-t` |
+| `--target-dir` | `-D` |
+| `--workers` | `-W` |
+
+## 3. 新项目与作者面
+
+### `pz dev init`
+
+用途：
+
+- 新建开发项目的唯一正式入口
+- 默认把官方 `pz_apps` 中每个正式最小子包导入业务仓；显式 `--link` 才保留上游 checkout
+- 负责项目骨架、默认本地 app、源码装配、托管配置刷新、初始环境安装与 IDE 投影
+- 默认会通过 `pz env install` 确保项目根 `.venv` 存在；后续 `pz` provider 会优先使用该项目环境
+
+常用写法：
+
+```bash
+pz dev init -d .
+pz dev init -a demo -d .
+pz dev init -S -d .
+pz dev init --link -C -d .
+pz dev init --link --source-dir ../pz -d .
+```
+
+边界：
+
+- 它是编排命令，不替代 `pz run`
+- 它不替代后续按需使用的 `pz dev add`、`pz dev link`、`pz app add`、`pz settings update`
+- 默认模式编排 scaffold、`dev source cache`、对全部正式叶子执行 `dev source import`、一次 `settings update`、一次 `env install` 与一次 `dev ide sync`
+- 默认模式不保留 `pz_apps` checkout；每个导入叶子落在 `apps/<app_id>`，由业务仓拥有
+- linked 模式必须写成 `--link --clone-sources` 或 `--link --source-dir <path>`，两个 source selector 必须且只能出现一个
+- `--clone-sources` / `--source-dir` 不带 `--link` 时直接失败，不允许隐式推断所有权模式
+- linked 模式只保留原 bootstrap scope，不隐式暴露整个 `pz_apps` 仓；新增 linked 仓继续显式使用 `pz dev link`
+- linked 模式默认基础分支是 `develop`；只有显式 `--base-branch main` 才从 `main` 创建业务分支
+- 业务分支名固定来自 `business_app_id`：优先使用 `--app-name`，否则使用项目目录名归一化结果
+- 最后调用 `pz dev ide sync`；已有 `.idea/` / `.vscode/` 对应 provider 执行投影，不存在的 IDE 目录只让该 provider 返回 `not_applicable`
+- 默认执行完成后，`pz run` 可以直接启动；`--no-sync` 只跳过 `env install`，不跳过 IDE 投影同步
+
+参考：
+
+- [`新手指南.md`](新手指南.md)
+- [`pz规范与使用/09-CLI与Worker入口规范.md`](pz规范与使用/09-CLI与Worker入口规范.md)
+
+### `pz env doctor`
+
+用途：
+
+- 检查当前项目目录的作者面前置条件
+- 当前主要检查 `python`、`uv`、`git`
+
+常用写法：
+
+```bash
+pz env doctor -d .
+pz env doctor -j -d .
+```
+
+### `pz env install`
+
+用途：
+
+- 创建或复用当前项目根 `.venv`
+- 对当前项目根和已发现的作者面根执行首轮依赖同步
+- 作为 `pz dev init` / `pz env init` 复用的正式原子能力
+
+常用写法：
+
+```bash
+pz env install -d .
+pz env install -g dev -d .
+pz env install -x docs -d .
+pz env install -i pz -d .
+pz env install -P -d .
+```
+
+### `pz env init`
+
+用途：
+
+- 面向“目录已存在，但需要补齐正式 pz 骨架与托管配置”的场景
+- 复用底层 scaffold service、`pz settings update`、`pz env install` 的正式语义
+
+常用写法：
+
+```bash
+pz env init -d .
+pz env init -S -d .
+```
+
+边界：
+
+- 不替代 `pz dev init` 的新项目职责
+- CLI 初始化入口固定为分组命令，例如 `pz env init`、`pz app init`、`pz dev init`、`pz settings init`
+
+### `pz env sync`
+
+用途：
+
+- 对正式项目根和已发现的作者面根执行依赖同步
+- source-root workspace overlay 只镜像源码真相；`.venv`、`.pytest_cache`、`__pycache__`、`*.egg-info` 与 Python 包根 `dist` 等生成目录不会进入 overlay，也不会成为 editable build 输入；依赖目录内部的同名资源目录不属于清理范围，生成目录符号链接只解除链接而不跟随删除外部目标
+
+常用写法：
+
+```bash
+pz env sync -d .
+pz env sync -g dev -d .
+pz env sync -x docs -d .
+pz env sync -i pz -d .
+pz env sync -P -d .
+```
+
+## 4. 配置与托管区块
+
+### `pz settings init`
+
+用途：
+
+- 扫描已安装 app，读取各 app 的 `configs/default.jsonc` / `configs/default.env`，生成或覆盖 `pz*.jsonc` 与 `.env*` 的托管内容
+
+常用写法：
+
+```bash
+pz settings init -d .
+pz settings init -f -d .
+```
+
+边界：
+
+- 更适合“目录已存在但还没有 `pz.jsonc`”的场景
+
+### `pz settings update`
+
+用途：
+
+- 把当前 app 的 `configs/default.jsonc` 默认配置模板同步进现有 `pz*.jsonc`
+- 把当前 app 的 `configs/default.env` 占位模板同步进现有 `.env*`
+- 刷新托管配置区块，但不覆盖非托管项目值
+
+常用写法：
+
+```bash
+pz settings update -d .
+pz settings update <target> -d .
+pz settings update -M -d .
+```
+
+硬约束：
+
+- 项目配置更新统一走这个正式入口，不要直接手写第二套更新脚本
+
+### `pz settings refresh-agents`
+
+用途：
+
+- 只刷新项目根 `AGENTS.md` 的 pz 托管区块
+- 保留用户手写内容
+
+常用写法：
+
+```bash
+pz settings refresh-agents -d .
+```
+
+### `pz settings reset-agents`
+
+用途：
+
+- 整份重置项目根 `AGENTS.md` 为当前正式托管块
+- 不保留用户手写内容
+
+常用写法：
+
+```bash
+pz settings reset-agents -d .
+```
+
+## 5. 项目启动
+
+### `pz run`
+
+用途：
+
+- 项目启动唯一正式入口
+
+等价关系：
+
+- `pz run`
+- `pz run develop`
+- `pz run dev`
+
+都映射到 `PZ_ENV=develop`
+
+其它正式环境：
+
+- `pz run test`
+- `pz run product`
+
+常用写法：
+
+```bash
+pz run -d .
+pz run develop -d .
+pz run dev -d .
+pz run test -d .
+pz run product -d .
+```
+
+硬约束：
+
+- 项目启动统一只走 `pz run`
+- 不要再发明 `python main.py`、自制 wrapper、第二套 shell 启动链作为正式入口
+
+运行时细节：
+
+- `pz run` 会先判断是否需要 `handoff`
+- 如果项目绑定了 dev runtime/source，会切到项目绑定的 Python + runtime import roots 再执行
+- `app` 模式与 `dev` 模式的前半链路不同，但最后都汇合到统一 `RuntimePlan` / `host.builder` 主链
+
+参考：
+
+- [`pz规范与使用/24-pz启动与运行时编译流程.md`](pz规范与使用/24-pz启动与运行时编译流程.md)
+- [`pz规范与使用/09-CLI与Worker入口规范.md`](pz规范与使用/09-CLI与Worker入口规范.md)
+
+## 6. 最小子包骨架
+
+### `pz startapp`
+
+用途：
+
+- 在 `apps/<app_id>/` 下创建正式最小子包骨架
+- 默认写入项目 `installed_apps` 并刷新托管 settings；传 `--target-dir` / `-D` 时只生成源码骨架，不改项目声明
+
+常用写法：
+
+```bash
+pz startapp demo -d .
+pz startapp pz_site_crawler -D /path/to/source-root -d .
+```
+
+边界：
+
+- 只负责最小子包骨架，不负责安装发布包，不负责源码绑定
+- 默认写入 `<project-dir>/apps/<app_id>/`；传 `--target-dir` / `-D` 时写入 `<target-dir>/<app_id>/` 且不刷新项目 settings
+- 生成的 app 骨架默认对齐正式最小子包规范：
+  - URL 入口固定为 `<app>/urls.py`
+  - 页面声明固定为 `<app>/pages/`
+  - 页面开发目录遵循 MVC 心智
+  - 前端默认只负责展示层，数据交互优先走 AJAX + 后端 API
+
+## 7. 发布包安装链
+
+### `pz app init`
+
+用途：
+
+- 从当前项目已有 `apps/.sources` 读取默认包名和内部 PyPI / devpi 安装位置
+- 默认把 `.sources` 中所有正式最小子包加入 `installed_apps`
+- 默认创建或复用项目根 `.venv`
+- 默认把单一基础 distribution `pz-cli` 与已发现正式最小 app 的已发布 distribution 安装进项目 `.venv`
+- 声明完成后刷新托管 settings，把已发现 app 的模板同步进项目根 `pz*.jsonc` / `.env*`
+
+常用写法：
+
+```bash
+pz app init -d .
+pz app init -S -d .
+```
+
+边界：
+
+- 它是生产装配模型下的编排命令；默认复用 `.sources` 包清单发现、项目声明、settings update、`.venv` 准备和 distribution 安装原子语义
+- 默认安装位置来自 `.sources` 中各包最近 source-root 的 `tool.pz.publish.default_target` 与对应 `targets.<target>.check_url`；若默认包清单跨多个内部 PyPI / devpi index，`app init` 会把这些 index 去重后交给同一次安装解析
+- 安装项使用 `.sources` 中各包 `pyproject.toml` 的 distribution 名，具体版本由内部 PyPI / devpi 与项目锁仓策略解析；`app init` 不把源码 checkout 的当前 version 当作生产安装 pin
+- 未显式指定版本时，每个包先解析正式 index 中最新兼容稳定版，再形成一份依赖安全的 exact-version 计划；解析冲突在项目 mutation 前失败
+- 最终 exact pin 写入项目依赖并由 `uv.lock` 固定，不保留浮动 `latest`
+- `--no-sync` / `-S` 同时跳过项目根 `.venv` 准备与 distribution 安装；声明和 settings 刷新仍会完成
+- 它不 clone 或导入源码；需要业务接管源码时使用 `pz dev add`，需要 linked checkout 时使用 `pz dev link` 或 `pz dev init`
+- 它不从源码 editable 安装；安装必须走内部 PyPI / devpi
+- 它不发布 package；发布仍走 `pz pub ...`
+- 它会安装 `pz-cli` distribution，但只把正式最小 app 子包写入 `installed_apps`
+- 它会跳过 `pz-cli` 和没有 `apps.py` 的集合包，避免把非 app distribution 写进运行时声明
+- 它会按 source app 声明的 `requires_apps` 依赖关系写入 `installed_apps`，避免生成运行时无法编译的顺序
+
+### `pz app add`
+
+用途：
+
+- 编排版本解析、精确声明、精确安装与 settings 刷新，把正式最小 app 加入项目
+
+常用写法：
+
+```bash
+pz app add pz_demo -d .
+pz app add pz_demo --version 2.4.1 -d .
+```
+
+边界：
+
+- 未传 `--version` 时解析当前正式 index 中最新兼容稳定版
+- `--version` 只接受一个精确 PEP 440 版本
+- 解析出的版本以精确 pin 写入项目依赖并进入 `uv.lock`；不得把 `latest` 持久化
+- 固定编排 `app versions -> app declare -> app install -> settings update`
+- 它安装 distribution，不向 `apps/` 写源码
+- `apps/<app_id>` 已存在业务拥有的真实源码时，`app declare` / `app add` 直接返回 `PZ_APP_SOURCE_OWNERSHIP_CONFLICT`；需要发布包模式时先由业务 Git 工作流移除或迁出该源码
+
+### `pz app rm`
+
+用途：
+
+- 从项目声明中移除一个正式最小 app
+- 编排 `app undeclare -> env sync -> settings update`
+
+常用写法：
+
+```bash
+pz app rm pz_demo -d .
+```
+
+注意：
+
+- 如果同名 linked dev source 仍存在，需要再执行 `pz dev unlink <app_id>`；业务仓真实源码由业务 Git 工作流管理
+
+### `pz app update`
+
+用途：
+
+- 把已声明 app 更新到最新兼容稳定版，或切换到调用方指定的精确版本
+
+常用写法：
+
+```bash
+pz app update pz_demo -d .
+pz app update pz_demo --version 2.3.0 -d .
+```
+
+边界：
+
+- 未传 `--version` 时解析最新兼容稳定版；当前已是最新时幂等成功
+- `--version` 只接受一个精确 PEP 440 版本
+- 固定编排版本解析、精确声明、精确安装、lock 与 settings 刷新
+- 仍然是发布包更新，不是源码同步
+
+### `pz app versions`
+
+用途：
+
+- 只读查看目标 app 在正式 package index 中的现有版本及当前项目版本状态
+
+常用写法：
+
+```bash
+pz app versions pz_demo -d .
+pz app versions pz_demo -j -d .
+```
+
+输出：
+
+- 按 PEP 440 降序排列的可用版本
+- 最新兼容稳定版
+- 当前项目 declared、locked 与 installed 版本
+- prerelease 与 yanked 标记
+- 不修改项目、环境、lock 或远端 index
+
+### `pz app declare` / `pz app undeclare` / `pz app install`
+
+用途：
+
+- 提供 app 编排可单独验证和失败续跑的原子能力
+
+常用写法：
+
+```bash
+pz app declare pz_demo --version 2.4.1 -d .
+pz app install pz_demo --version 2.4.1 -d .
+pz app undeclare pz_demo -d .
+```
+
+规则：
+
+- `declare` 只原子维护 exact distribution pin 与 app identity/load-order 声明
+- `declare` 不接管 `apps/<app_id>` 中业务拥有的真实源码；存在同名真实目录时返回 `PZ_APP_SOURCE_OWNERSHIP_CONFLICT`
+- `install` 只安装调用方已经解析出的精确版本，并校验 installed metadata
+- `undeclare` 只移除 project pin 与 app 声明
+- 三者都不选择 latest，不拉取源码，不发布 package
+
+## 8. 业务源码与 linked checkout
+
+### `pz dev add`
+
+用途：
+
+- 把一个正式最小子包导入 `apps/<app_id>`，交由业务仓管理
+- 编排 `dev source cache -> dev source import -> settings update -> env sync -> dev ide sync`；非 Git 本地输入跳过 cache
+
+常用写法：
+
+```bash
+pz dev add git@github.com:<org>/<repo>.git -d .
+pz dev add ../catalog/pz_page_center -d .
+pz dev add pz_page_center -d .
+pz dev add pz_page_center --branch feature-preview -d .
+```
+
+规则：
+
+- 输入必须唯一解析到一个正式最小子包；零个或多个候选时直接失败
+- Git 来源默认使用 `develop` 分支；`--branch` 才显式选择其他分支
+- PZ 先检查当前用户隔离的 `<system-temp>/pz/users/<user-key>/git/<repo_key>`：无可用 Git cache 时 staged clone，有匹配 cache 时先 fetch/update，再固定 exact commit
+- cache root、repo lock、checkout 与 `.pz-cache-owner.json` 必须通过当前用户 owner、权限、非符号链接和 canonical remote 校验
+- cache 更新失败直接报错，不静默复制旧 revision；cache 只作可丢弃优化，不是项目源码真相
+- 最终目录固定为 `apps/<app_id>`，不得包含 `.git`、虚拟环境、cache 或构建产物
+- 导入源码由业务仓统一管理；PZ 不自动覆盖、更新或删除
+- 项目 source mode 收敛为 `local`；宿主 `pyproject.toml` 同一事务声明 app dependency 与指向 `apps/<app_id>` 的精确 editable `tool.uv.sources`；任一步失败整体回滚
+- Git provenance 记录无凭据 canonical source、full revision 和 leaf subpath；本地目录 provenance 只记录 `source = "local"`、不可逆 source identity 与 leaf subpath，不泄露绝对路径
+- destination、同名 binding 或其他本地同名 `app_id` 已存在时直接失败
+- 导入先在 `apps/` 同文件系统隐藏目录校验，再原子落位；失败不得留下半成品
+- 项目本地源码与当前环境里的同名 distribution 同时存在时，本地源码优先
+
+### `pz dev link`
+
+用途：
+
+- 保留上游 Git checkout，并通过 `apps/` binding 暴露源码用于联调
+- 编排 `dev source link -> settings update -> env sync -> dev ide sync`
+
+常用写法：
+
+```bash
+pz dev link git@github.com:<org>/<repo>.git -d .
+pz dev link ../catalog -d .
+pz dev link pz_page_center -b main -d .
+```
+
+规则：
+
+- Git checkout 固定落在 `apps/.sources/<repo_key>`
+- `apps/.sources/<repo_key>` 可以是指向项目外现存 Git checkout 的共享符号链接；这种 checkout 由外部所有，PZ 只读取，不切分支、不更新目标内容
+- 目录输入在 `apps/<repo_key>` 建立目录 binding；叶子输入在 `apps/<app_id>` 建立叶子 binding
+- 运行时只发现 `apps/` 下的真实本地 app 与可见 binding；物理 `apps/.sources` 不贡献 app
+- 默认基础分支是 `develop`；显式替代值只有 `main`
+- 受管 checkout 的目标分支固定为 manifest 中的 `business_app_id`，不能从命令行任意指定
+- 任意业务仓真实目录或其他 linked binding 已暴露相同 `app_id` 时直接失败；冲突按解析后的 app 身份判断，不按路径名称判断
+
+### `pz dev branch`
+
+用途：
+
+- 编排 `dev source branch -> env sync -> dev ide sync`，把已有受管 checkout 切到当前项目的业务分支
+
+常用写法：
+
+```bash
+pz dev branch pz_apps -d .
+pz dev branch pz_apps -b main -d .
+```
+
+规则：
+
+- 只接受已有 repo 或 binding 身份
+- 只作用于 manifest 中的 linked checkout；业务仓拥有的 `apps/<app_id>` 必须拒绝
+- worktree 必须 clean
+- 不执行 stash、commit、merge、rebase、reset 或 push
+- `--base-branch` 只决定业务分支首次创建点，不允许指定任意目标分支
+
+### `pz dev update`
+
+用途：
+
+- 编排 `dev source update -> env sync -> dev ide sync`，更新本地 dev checkout
+
+常用写法：
+
+```bash
+pz dev update pz_page_center -d .
+```
+
+规则：
+
+- 只作用于 manifest 中的 linked checkout；业务仓拥有的 `apps/<app_id>` 必须拒绝
+- 只允许在 clean 的业务分支上执行
+- 有 upstream 时只做 fast-forward-only 更新；没有 upstream 时只 fetch 并报告状态
+- 共享 checkout 不执行 update，命令返回 `PZ_DEV_SHARED_CHECKOUT_READ_ONLY`；共享仓库应在其真实目录中独立更新
+
+### `pz dev unlink`
+
+用途：
+
+- 移除精确的本地 source binding 和对应符号链接
+- 编排 `dev source unlink -> settings update -> env sync -> dev ide sync`
+
+常用写法：
+
+```bash
+pz dev unlink pz_page_center -d .
+pz dev unlink pz_page_center -X -d .
+```
+
+规则：
+
+- 默认保留任何 checkout；只有显式 `--delete-checkout` 才进入删除检查
+- 只有最后一个 binding、worktree clean、upstream 可验证且没有未推送提交时，`--delete-checkout` 才允许删除 checkout
+- checkout 条目若为共享符号链接，`--delete-checkout` 最多只解除项目内链接，绝不跟随删除外部目标
+- 不删除 `pz dev add` 导入的业务仓真实目录
+
+### `pz dev source ...`
+
+用途：
+
+- 提供 Git cache、源码导入、binding、分支、更新与解除 binding 的原子能力
+- 供 `pz dev add/link/branch/update/unlink` 编排、失败续跑和自动化测试复用
+
+规则：
+
+- `source cache` 只拥有当前用户隔离的 `<system-temp>/pz/users/<user-key>/git/<repo_key>` 的 clone/update、owner marker、remote identity、branch 与 exact commit 解析；默认分支是 `develop`
+- `source cache` 返回 canonical `repo_key`、exact full commit 与不可变 resolution ref；失败续跑以 `--revision <full-commit>` 验证已有 ref，cache/ref 丢失时明确失败，不把任意 Git object 提升为可信 handoff
+- Git 模式 `source import` 必须显式接收 `--repo-key <repo_key> --revision <full-commit>`，并在同一 repo lock 下验证 resolution ref；不得读取 branch、`HEAD` 或 cache 最新状态
+- `source import` 只从已验证的 cache-pinned commit 或非 Git 本地目录复制业务源码，并原子拥有 app 目录、source-mode、provenance 与宿主 dependency/`tool.uv.sources` 事务；不执行网络更新
+- `source link` / `source unlink` 只拥有 checkout、manifest 与 binding 事务
+- `source branch` / `source update` 只拥有 linked checkout Git 事务
+- 不刷新 settings、环境或 IDE 投影
+- cache 命中必须先更新；损坏、remote 不匹配、符号链接重定向或无法证明 PZ 所有权的 temp entry 不得被信任或递归删除
+
+### `pz dev ide sync`
+
+用途：
+
+- 原子刷新 PZ 管理的 IDE 影子投影，确保 PyCharm 与 VS Code 精确索引所有可见最小子包
+
+规则：
+
+- 只编译一次可见最小子包投影，再分别交给 PyCharm 与 VS Code provider；不新增 IDE 专用命令
+- `.idea/` 存在时维护 `.idea/pz.generated.sources.iml` 与 `modules.xml` 中唯一 PZ module entry
+- `.vscode/` 存在时使用 JSONC 结构化维护 `settings.json` 中 PZ 插入的 `python.analysis.extraPaths`，并用 `pz.generated.sources.json` 记录 PZ-owned entries
+- PyCharm linked 源码登记 canonical 精确叶子根；VS Code 使用 `${workspaceFolder}/apps/<visible-leaf-path>`，两者都不得登记整个 `.sources` checkout
+- 只生成 IDE metadata，不复制源码，不参与运行时、打包、资源覆盖或发布
+- 对应 `.idea/` / `.vscode/` 不存在时，该 provider 返回 `not_applicable`，PZ 不主动创建 IDE 项目配置目录
+- 使用结构化 XML / JSONC 更新并保留全部用户内容；VS Code 只删除状态账本记录的旧 PZ entries
+- provider 失败时保留或恢复上一份有效投影；中断的 VS Code 双文件更新通过事务 journal 续跑
+
+## 9. 发布链
+
+### `pz pub`
+
+用途：
+
+- 编排目标子包的精确 Git commit、package tag、构建与发布
+
+常用写法：
+
+```bash
+pz pub pz_demo -t devpi_dev -d .
+pz pub pz_demo -t devpi_dev -n -d .
+```
+
+规则：
+
+- 固定按 `pub commit -> pub tag -> pub upload` 执行
+- 若 `project_dir` 本身是 Git root 且根 `pyproject.toml` 的 distribution 精确匹配目标，直接以仓库根作为发布源和整仓 release scope；否则再枚举 `apps/.sources` 并复用既有 workspace 子包发现程序
+- 非根发布目标必须在 `.sources` Git 仓库中唯一命中；没有可用 Git、未找到子包、多个仓库重复命中分别报错，不回退发布业务复制目录
+- 唯一命中外部共享只读 checkout 时，`pub commit/tag/upload` 返回 `PZ_PUB_SHARED_CHECKOUT_READ_ONLY`；`pub rm` 只操作索引，不受 source gate 约束
+- commit 前先检查目标 index 的 distribution/version；远端已存在但本地没有精确匹配 release state 时直接失败
+- 发布前必须已有明确 `project.version`；`pub` 不自动选择或升级版本号
+- 根 distribution 显式提交 `.` 整仓 scope；嵌套最小子包只提交目标 package path，不提交同仓其他子包改动
+- tag 固定为 `<distribution-name>@<version>`，例如 `pz-auth@5.0.1`
+- 创建本地 commit 与 annotated tag，但不执行 `git push`
+- 后续阶段失败时保留已经完成的 commit/tag；重跑复用精确匹配状态并继续
+- `pub upload` 只从当前干净 checkout 直接构建，要求 HEAD 精确等于 package tag commit；不创建临时 Git worktree
+- `--dry-run` 完成范围、版本、tag、build、publish lock 与目标规划，但不修改 Git 或远端
+
+### `pz pub commit`
+
+用途：
+
+- 原子地提交目标最小子包当前可发布源码
+
+常用写法：
+
+```bash
+pz pub commit pz_demo -d .
+```
+
+规则：
+
+- Git index 必须没有预先 staged 的内容
+- 只按目标 package path 执行 deletion-aware stage 与 commit
+- 根 distribution 的目标 path 固定为显式 `.`，整仓属于同一个 release scope
+- 其他已识别最小子包中的 unstaged 修改允许保留且不得进入 commit
+- 不属于任何最小子包的未提交共享根文件属于歧义变更，阻止单包发布
+- commit subject 固定为 `release(<app_id>): <version>`
+- 不执行 stash、reset、clean、amend、rebase 或 push
+
+### `pz pub tag`
+
+用途：
+
+- 为当前目标子包 release commit 创建 annotated package tag
+
+常用写法：
+
+```bash
+pz pub tag pz_demo -d .
+```
+
+规则：
+
+- tag 不存在时，在 `pub commit` 返回的精确 release commit 上创建；首次路径通常是 HEAD，失败重试时允许是当前分支可到达的历史 commit
+- annotation 固定为 `release(<app_id>): <distribution-name> <version>`
+- tag 已存在、annotation 与 release commit 精确匹配且该 commit 可从当前分支到达时幂等复用，即使 HEAD 已前进
+- tag 指向其他 commit 或 metadata 不匹配时直接失败，不移动或删除 tag
+
+### `pz pub upload`
+
+用途：
+
+- 原子执行目标子包的 build 与 package-index upload
+
+常用写法：
+
+```bash
+pz pub upload pz_demo -t devpi_dev -d .
+pz pub upload pz_demo -t devpi_dev -n -d .
+pz pub upload pz_demo --version 1.2.3 -t devpi_dev -d .
+```
+
+规则：
+
+- package tag 必须精确指向当前 HEAD release commit
+- 当前 index 与 worktree 必须 clean；`--version` 必须与当前 `project.version` 一致
+- 必须从当前 package root 直接构建，不创建临时 worktree 或源码副本
+- 当前 `project.version`、tag 与 wheel metadata 必须一致
+- clean-environment wheel install/import smoke 必须在远端 upload 前通过
+- 继续复用 publish lock、目标配置、凭据和凭据脱敏合同
+- 不执行 commit、tag、push 或源码修改
+- 远端同版本只有在 artifact identity 与 hash 一致时才作为幂等成功，否则冲突
+
+### `pz pub rm`
+
+用途：
+
+- 从发布目标移除一个版本化包的已发布产物
+- 只解析 distribution 与 publish target，不要求 `apps/.sources` 存在 Git 仓库
+
+常用写法：
+
+```bash
+pz pub rm pz_demo -t devpi_pub -d .
+pz pub rm pz_demo -t devpi_pub -f -d .
+```
+
+### `pz pub batch`
+
+用途：
+
+- 按你显式给出的顺序发布多个包
+
+常用写法：
+
+```bash
+pz pub batch pz catalog -t devpi_dev -d .
+```
+
+边界：
+
+- 不会替你猜依赖顺序
+- 对每个 app 顺序执行完整 `pub commit -> pub tag -> pub upload`
+- 每个 app 生成独立 release commit 与 package tag
+- 任一 app 失败即停止；重跑时复用精确匹配的已完成阶段
+
+## 10. 运行时工具
+
+### `pz list`
+
+用途：
+
+- 展示已发现 app 与当前 runtime 状态
+
+常用写法：
+
+```bash
+pz list -d .
+pz list -j -d .
+```
+
+### `pz check`
+
+用途：
+
+- 运行项目与 runtime 检查
+
+常用写法：
+
+```bash
+pz check -d .
+pz check -j -d .
+```
+
+边界：
+
+- 它是系统检查唯一正式入口
+
+### `pz db makemigrations`
+
+用途：
+
+- 通过正式 runtime context 生成迁移
+
+### `pz db migrate`
+
+用途：
+
+- 通过正式 runtime context 执行迁移
+
+### `pz db showmigrations`
+
+用途：
+
+- 查看迁移状态
+
+常用写法：
+
+```bash
+pz db makemigrations -d .
+pz db migrate -d .
+pz db showmigrations -d .
+```
+
+边界：
+
+- `db` CLI 只能消费正式 app registry、正式迁移 owner 规则和当前 `RuntimePlan`
+
+### `pz resources images`
+
+用途：
+
+- 通过正式资源编译链生成响应式图片派生产物
+
+常用写法：
+
+```bash
+pz resources images -d .
+pz resources images --force -d .
+```
+
+其中 `--force` 会绕过资源构建缓存并覆盖已有同名图片派生产物；同时，`pz_foundation.resources.images.force=true` 时，`pz resources images` 默认等价启用 `--force`。
+只有 CLI 未传 `--force` 且配置 force 为 false 时，才沿用资源构建缓存与图片派生的“已有同名产物则跳过”语义。
+
+边界：
+
+- 图片派生属于 `pz_foundation.resources` 通用资源能力，不挂在某个站点子包的 app CLI 下。
+- 图片派生输出只进入合并后的 runtime/cache static 产物，不写回业务包源码目录。
+
+### `pz workers`
+
+用途：
+
+- 管理当前项目的 managed worker。
+
+常用写法：
+
+```bash
+pz workers --project-dir . list
+pz workers --project-dir . status --json
+pz workers --project-dir . stop
+pz workers --project-dir . restart
+pz workers --project-dir . restart mission_carrier.task_center_worker
+pz workers --project-dir . restart --start-timeout 90
+```
+
+选择规则：
+
+- 不传 `name` 且不传 `--all` 时，只作用于当前 RuntimePlan 中 `auto_start=true` 的 worker。
+- `name` 可匹配 worker 稳定名称、extension id，或 `<app_id>.<tool_name>`。
+- `--all` 只在未显式传入 `name` 时扩展目标集合，包含非自动启动 worker role。
+
+常用参数：
+
+| 参数 | 适用命令 | 说明 |
+| --- | --- | --- |
+| `--project-dir <path>` | 全部 | 指定包含 `pz.jsonc` 的项目根；默认从当前目录发现项目。 |
+| `--json` | `list/status/stop/restart` | 输出机器可读 JSON。 |
+| `--all` | `list/status/run/stop/restart` | 未传 `name` 时包含非自动启动 worker。 |
+| `--timeout <seconds>` | `stop/restart` | 停止旧 worker / supervisor 的等待窗口。 |
+| `--start-timeout <seconds>` | `restart` | detached supervisor 启动后等待状态刷新的窗口。 |
+| `--poll-interval <seconds>` | `run/restart` | supervisor reconcile loop 间隔。 |
+| `--owner-pid <pid>` | `run/restart` | 绑定宿主 PID；宿主退出后 detached supervisor 可收口。 |
+| `--detach` | `run` | 后台拉起 detached supervisor 并立即返回。 |
+| `--force-restart` / `--no-force-restart` | `run --detach` | 本次命令显式覆盖 `pz_foundation.managed_workers.force_restart_on_host_start`。 |
+
+边界：
+
+- `workers` 由 `pz_foundation` 通过正式 root CLI provider 暴露。
+- `list/status/stop/restart/run` 的实现集中在 `pz_foundation.cli.workers`，底层进程状态与 stop 语义集中在 `pz_foundation.managed_workers`。
+- `run` 是 supervisor 底层入口；人工运维优先使用 `restart`、`stop`、`status`。
+- `restart --start-timeout` 只控制命令等待新 supervisor 状态刷新的时间，不改变 worker 目标集合。
+- `pz pz_foundation workers ...` 是同一实现的 app CLI 入口。
+
+### `pz <app_id> <tool>`
+
+用途：
+
+- 调用某个 app 暴露出来的 CLI 工具
+
+常用写法：
+
+```bash
+pz <app_id> <tool> -d .
+```
+
+边界：
+
+- app CLI 的正式调用路径就是这一条
+
+## 11. 最常用命令组合
+
+新开发项目：
+
+```bash
+pz dev init -d .
+pz run -d .
+```
+
+新增业务仓源码：
+
+```bash
+pz dev add git@github.com:<org>/<repo>.git -d .
+pz run -d .
+```
+
+新增 linked 源码联调：
+
+```bash
+pz dev link git@github.com:<org>/<repo>.git -d .
+pz settings update -d .
+pz run -d .
+```
+
+新增已发布 app：
+
+```bash
+pz app add pz_demo -d .
+pz settings update -d .
+pz run -d .
+```
+
+只刷新 `AGENTS.md`：
+
+```bash
+pz settings refresh-agents -d .
+```
+
+发布前检查：
+
+```bash
+pz env doctor -d .
+pz check -d .
+```
+
+## 12. 命令边界速记
+
+- 要启动项目：`pz run`
+- 要更新项目配置：`pz settings update`
+- 要刷新 `AGENTS.md`：`pz settings refresh-agents`
+- 要新建开发项目：`pz dev init`
+- 要装发布包：`pz app add`
+- 要把源码交给业务仓管理：`pz dev add`
+- 要绑定上游 checkout 联调：`pz dev link`
+- 要发包：`pz pub`
+- 要做系统检查：`pz check`
+- 要做迁移：`pz db ...`