Composer 不会自动更新 autoload 文件，必须手动执行 composer dump-autoload 才能刷新 PSR-4 映射；该命令仅重扫描配置路径生成映射，不修改 vendor 包，且 PSR-4 要求命名空间结尾带反斜杠、类名与文件名大小写严格一致、路径真实存在。

Composer 不会“自动”在后台默默更新 autoload 文件——它只在你明确触发时才生成或重写 vendor/autoload.php 及其背后的映射文件。依赖安装完成、代码改完、composer.json 配置加好，都不代表类能立刻被加载。

composer dump-autoload 是唯一正经的刷新命令

这是最常被忽略也最该优先尝试的操作。它不碰 vendor/ 里的包，只重新扫描你配置的源码路径（比如 "src/" 或 "app/"），生成新的映射数组写入 vendor/composer/autoload_psr4.php 等文件。

• 新增了一个 src/Service/CacheManager.php，类名是 App\Service\CacheManager，但 new 的时候报 Class not found → 必须运行 composer dump-autoload
• 改了 composer.json 里 "psr-4": { "App\": "app/" } 这行，把 "app/" 换成 "src/" → 不运行命令，旧映射还在，类照样找不到
• 拉取同事提交的新代码，里面加了命名空间和类 → 光 git pull 不够，得补一句 composer dump-autoload

PSR-4 映射生效的前提很具体

即使 dump-autoload 成功执行，类仍可能加载失败，因为 PSR-4 是严格路径推导机制，不是模糊匹配。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

• 命名空间末尾必须带反斜杠："App\": "src/" 中的 \ 不能少，否则 AppController 会被当成顶层命名空间，找不到对应目录
• 类名与文件名必须完全一致（大小写敏感）：类 UserRepository 必须放在 src/Repository/UserRepository.php，写成 userrepository.php 在 Linux 上直接失败
• 路径必须存在且可读：如果 "App\": "src/" 配了，但项目里根本没有 src/ 目录，dump-autoload 不报错，但映射数组里不会写入任何内容
• 一个命名空间只能映射一个根目录："App\": ["src/", "app/"] 这种写法 Composer 会静默忽略第二个

classmap 和 files 方式需要额外注意

它们不像 PSR-4 那样靠命名空间推导路径，而是靠扫描或显式声明，因此行为更“确定”，但也更易漏掉步骤。

• classmap：只在加 -o 参数时才扫描生效。普通 composer dump-autoload 完全不处理 classmap 配置项；必须用 composer dump-autoload -o 才会去遍历 legacy/ 这类目录并写入 autoload_classmap.php
• files：配置的是要直接 require 的 PHP 文件，比如 "helpers.php"。它不校验文件是否存在，也不检查语法；如果路径写错或文件被删，dump-autoload 依然成功，但后续 require_once 'vendor/autoload.php' 时会直接 fatal error
• autoload-dev 默认不生效：测试类（如 Tests/）配在 autoload-dev 下，composer install 默认不加载它们；需加 --dev 或显式运行 composer dump-autoload --dev

真正容易被卡住的地方，往往不是命令没敲对，而是以为“改完配置就完了”，结果忘了 dump-autoload 这一步；或者以为 PSR-4 能容错，结果路径/大小写/反斜杠错一处，整个链路就断了。映射文件是静态生成的，不是运行时动态解析的——它不会猜你想加载什么，只忠实地执行你写死的规则。