Class not found 的主因是 autoload 映射未生效：本地包 name 必须与 require 字符串完全一致（大小写、分隔符），path repository 路径须指向含 composer.json 的目录且无尾斜杠，需在本地包 composer.json 中配置 "options": {"symlink": true} 并确保 symlink 创建成功，同时本地包必须声明合法 autoload 规则且路径/命名空间严格匹配，最后 IDE 路径映射须指向真实源码路径而非 vendor 副本。
本地包 require 成功但类仍报 Class not found，90% 是 autoload 映射没生效，不是包没装上——Composer 能看到包、vendor 里有文件夹，但 vendor/autoload.php 根本没加载它的 PSR-4 规则。
本地包的 name 和路径必须逐字匹配
Composer 不做模糊匹配。你 require 的字符串（如 acme/utils）必须和本地包 composer.json 中的 name 字段**完全一致**：大小写、分隔符（只允许短横线 -）、vendor 名全部对齐。
-
"name": "acme/utils"✅ 对应composer require acme/utils -
"name": "Acme/utils"❌ 大写 A 导致失败 -
"name": "acme_utils"❌ 下划线不被接受 -
"url": "../my-pkg/"❌ 末尾斜杠会让整个 path repository 静默失效
路径还必须指向**含 composer.json 的目录**，且是相对于主项目 composer.json 的位置（例如 ../my-pkg），不是 shell 当前目录。
symlink 没启用，改代码等于白改
path repository 默认尝试创建符号链接，但失败时会静默 fallback 到复制（copy）——你改本地源码，vendor/acme/utils 里还是旧副本，autoload 却照常加载它，结果永远“找不到新类”。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 关键不在主项目配
"symlink": true，而在**本地包自己的composer.json中是否声明了"options": {"symlink": true}** - Windows 必须以管理员身份运行终端，否则 symlink 创建失败且无提示
- Docker 容器需加
--cap-add=SYS_ADMIN，且挂载方式要支持 symlink（如bind而非cached） - 验证是否真用了 symlink：
ls -la vendor/acme/utils（Linux/macOS）或dir vendorcmeutils（Windows），看到箭头或JUNCTION才算成功
autoload 映射压根没生成或没更新
即使 symlink 生效、路径也对，如果本地包的 composer.json 里没写 autoload 段，或者写了但路径/命名空间不匹配，Composer 就不会把它加入自动加载规则。
- 检查本地包
composer.json是否有合法autoload配置，例如："autoload": {"psr-4": {"Acme\": "src/"}} - 确认类文件路径与命名空间严格对应：
AcmeUtilsClient必须在src/Utils/Client.php，不能是src/utils/client.php（Linux 大小写敏感） - 主项目执行
composer dump-autoload -o后，打开vendor/composer/autoload_psr4.php，搜索Acme\，看映射路径是否指向本地包的真实目录（如$baseDir . '/../my-pkg/src'） - 如果没出现，说明 Composer 根本没读取到本地包的 autoload 配置——先确认本地包
composer.json语法有效（无尾逗号、全双引号）
IDE 路径映射错位导致 Xdebug 断点失效
类能加载、也能运行，但 Xdebug 断点不触发？大概率是 IDE（如 PHPStorm）里配置的“路径映射”指向了 vendor/acme/utils 的副本路径，而实际执行的是 symlink 指向的本地源码路径。
- IDE 的路径映射必须和真实磁盘路径一致：若本地包在
/Users/me/my-pkg，就映射到这个绝对路径，不能映射到vendor/... - PHPStorm 中：Settings → PHP → Servers → Path Mapping，确保 “Absolute path on the server” 指向本地包根目录
- VS Code 中：
launch.json的pathMappings同理
最隐蔽的坑是：symlink + autoload + IDE 路径三者只要一个错位，就会表现为“类存在但断点不进、修改不生效、报错行号对不上”——这时候别怀疑代码，先查这三处。
