入口脚本必须第一行 require vendor/autoload.php，否则因 autoload 队列为空导致类加载失败；常见错误包括 use 前置、BOM/空白、路径错误；选 CLI 库需匹配抽象层级：symfony/console 为底层标准，spryker/console 封装增强，splitbrain/php-cli 适用于极简单命令场景。
为什么入口脚本必须第一行 require vendor/autoload.php
不加这行，Fatal error: Class 'SymfonyComponentConsoleApplication' 几乎必然发生——不是概率问题，是 PHP 自动加载机制的硬性约束。Composer 的 vendor/autoload.php 并不直接定义类，而是调用 spl_autoload_register() 把 PSR-4 映射规则注册进 PHP 的 autoload 队列。如果前面有任何类实例化（比如 new Application()）、函数调用或命名空间引用，PHP 就会立刻触发 autoload，但此时队列还是空的。
常见错误包括：
- 在
require前写了use SymfonyComponentConsoleApplication;—— 这行本身就会触发 autoload - 入口文件开头有 BOM 或空白字符，导致
require实际没在第一物理行 - 用了
__DIR__.'/vendor/autoload.php'，但脚本放在bin/目录下，正确路径应为__DIR__.'/../vendor/autoload.php'
如何选对 CLI 库：symfony/console vs spryker/console vs php-cli
三者不是替代关系，而是不同抽象层级：
-
symfony/console是底层事实标准，提供Application、Command、InputInterface、OutputInterface等完整契约，适合需要精细控制参数解析、交互逻辑、多命令组织的项目 -
spryker/console是对symfony/console的轻量封装，自动处理命令发现（扫描目录）、依赖注入集成、环境配置绑定，适合 Spryker 生态或希望减少样板代码的中大型项目 -
splitbrain/php-cli更偏向极简脚本工具，没有命令注册中心，靠CLI::run()+ 手动if/else分发，适合单命令、无维护压力的小工具（如部署钩子、数据校验脚本）
选错的典型表现：composer require splitbrain/php-cli 后发现没法注册多个命令、不支持 php bin/app list、帮助信息格式混乱——这不是库的问题，是抽象层级错配。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
立即学习“PHP免费学习笔记（深入）”；
PSR-4 自动加载配置写错会导致命令类根本找不到
即使 vendor/autoload.php 加载成功，命令类仍可能报 Class not found，问题往往出在 composer.json 的 autoload 配置上。
- 命名空间末尾必须带反斜杠：
"App\Commands\"合法，"AppCommands"不匹配 - 路径末尾必须带正斜杠：
"src/Commands/"正确，"src/Commands"会导致拼出src/CommandsMyCommand.php而非src/Commands/MyCommand.php - 类文件名必须与类名严格一致（大小写敏感）：
MyCommand.php中只能定义class MyCommand，Linux 下mycommand.php或class mycommand直接失败 - 改完
composer.json后必须运行composer dump-autoload，否则vendor/composer/autoload_psr4.php不更新，新映射不会生效
复杂 CLI 框架最容易被忽略的初始化环节
真正让 CLI 框架“活起来”的，不是命令类本身，而是启动时的上下文准备。漏掉这些，命令能跑通但无法复用框架能力：
- 没加载框架配置：Laravel 的
artisan在Application实例化前就调用loadConfigurationFrom()；Symfony 的bin/console会提前require config/bootstrap.php - 没设置环境变量：
$_SERVER['APP_ENV']或getenv('APP_DEBUG')缺失，导致日志、缓存、数据库连接全走默认值 - 没初始化服务容器：自定义命令里用
$this->getApplication()->getContainer()报Call to a member function getContainer() on null，说明Application子类没重写doRun()注入容器 - 没处理信号：长时间运行的命令（如队列监听）需手动注册
pcntl_signal()，否则Ctrl+C无法优雅退出
这些环节没有统一标准，但每个成熟框架的官方 CLI 入口脚本（artisan、bin/console、spark）都已固化模式——抄不对，比从零写还容易出错。
