Swoole 是 C 扩展，不能用 composer install 或 require 安装；须先通过系统包管理器或编译安装并启用扩展，再由 Composer 校验 ext-swoole 依赖，且需确保 CLI 与 FPM 的 php.ini 均正确加载 extension=swoole。
composer install swoole 失败：PHP 版本或扩展依赖不满足
直接运行 composer require swoole 会失败，因为 Swoole 是 PHP 扩展，不是纯 PHP 包 —— Composer 只能装 PHP 类库，不能装 C 扩展。你看到的错误通常是：ext-swoole not found 或 Package requirements could not be resolved。
真正要做的，是先用系统包管理器或源码编译安装 swoole 扩展，再让 PHP 加载它，最后 Composer 才能校验通过（如果项目 composer.json 中声明了 "ext-swoole": "*"）。
- Linux（Ubuntu/Debian）：运行
sudo apt install php-swoole（PHP 8.1+ 默认已带，但需确认启用） - macOS（Homebrew）：先
brew install swoole，再检查php.ini是否包含extension=swoole - Windows：基本不建议生产使用；如测试，需下载对应 PHP 版本的
php_swoole.dll，放入ext/并在php.ini中启用 - 验证是否成功：
php -m | grep swoole或php --ri swoole
composer.json 里写 "ext-swoole": "*" 没用？检查 autoload 和 require-dev 场景
很多人加了 "ext-swoole": "*" 到 require 或 require-dev，但本地开发没报错、上线却崩了——这是因为 Composer 只在 install/update 阶段检查扩展是否存在，不参与运行时加载。它只是“提醒你环境缺东西”，不是“帮你装东西”。
更关键的是：如果你的代码只在 CLI 下跑（比如 Swoole HTTP 服务），但 php.ini 配置的是 FPM 或 Apache 的版本，php -v 看到有 swoole，php-fpm -v 却没有，就会出现“本地跑得通、部署后 Class 'Swoole\Http\Server' not found”。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 查 CLI 的配置：
php --ini→ 看 Loaded Configuration File 路径 - 查 FPM 的配置：
php-fpm -i | grep "Loaded Configuration File" - 确保两个环境都启用了
swoole扩展（尤其是extension=swoole在对应php.ini中且未被注释） -
"ext-swoole": "*"放require-dev更合理：Swoole 通常不参与 Web 请求链路，而是用于命令行启动服务
用 composer 安装 swoole-src 源码？别这么干
有人搜到 composer require swoole/swoole-src，这是个陷阱。这个包只是 Swoole 官方放的源码镜像，不含任何可执行逻辑，也没有自动编译或安装能力。Composer 安装后，你还是得手动 phpize && ./configure && make && sudo make install，而且路径、PHP 配置容易出错。
它唯一适合的场景是：你想在 CI 中固定某个 Swoole 版本源码做编译测试，且已有一套成熟的构建脚本。对绝大多数人来说，绕过包管理器直接装扩展更稳。
- 不要
composer require swoole/swoole-src - 不要指望
vendor/bin下会出现 swoole 命令行工具（它不存在） - Swoole 的命令行能力（如
swoole-server）只在扩展安装后通过 PHP 脚本调用，不提供独立 CLI 入口
异步环境配好了，为什么协程不生效？
装好扩展、写好 Swoole\Coroutine\run，但 go(function () { sleep(1); echo "done"; }); 还是阻塞主线程？问题往往出在「没进协程调度器」或「混用了同步函数」。
Swoole 协程不是全自动的：只有在 Swoole\Coroutine\run 或 Swoole Server 的回调中，才能触发协程调度。普通 CLI 脚本里直接 go() 是无效的。
- 必须包裹在
Swoole\Coroutine\run(function () { ... });中 -
sleep()是同步阻塞，要用Swoole\Coroutine::sleep(1) - MySQL/Redis 等客户端必须用 Swoole 提供的协程版（如
Swoole\Coroutine\MySQL），原生mysqli或PDO会退化为同步 - 文件操作也一样：
file_get_contents同步，得用Swoole\Coroutine\FileSystem或co::readFile
php.ini 配置错位，或一个 sleep 忘换，整个协程就垮了。 
