path仓库require须写"@dev"而非"dev-main"，因path类型不解析Git分支，"@dev"可匹配任意本地version（含无version字段），而"dev-main"会错误触发分支查找；需确保repositories在composer.json顶层、路径正确、name完全匹配，并启用symlink及清理OPCache。
path仓库为什么require写@dev而不是dev-main
因为path类型仓库不走 Git 分支解析逻辑，它只认composer.json里定义的name和你require中声明的版本约束。写"my/package": "dev-main"会让 Composer 去找一个叫dev-main的分支或别名，但本地路径下根本没 Git，自然失败。
正确做法是用"my/package": "@dev"——这个@dev是 Composer 的“通配开发版”标记，会匹配任何本地composer.json里的version（哪怕没设 version 字段也行），且强制触发 path 解析流程。
-
composer install可能跳过 path 仓库，必须用composer update my/package或composer update --with-all-dependencies - 如果本地包
composer.json里写了"version": "1.0.0"，你写"1.0.0"也能命中，但不如@dev灵活 - 大小写必须完全一致：
My/Package≠my/package，报错时先检查 name 字段
为什么vendor/my/package不是软链接，而是复制的文件
默认情况下，Composer 对 path 仓库也会走 dist 安装流程（即复制），除非你显式启用 symlink。这不是 bug，是设计行为。
解决方式是在主项目composer.json的config里加preferred-install配置：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
{
"config": {
"preferred-install": {
"my/package": "source"
}
}
}
- 全局启用
"preferred-install": "source"也行，但会影响所有包，不推荐 - Windows 需开启开发者模式或以管理员身份运行终端，否则
symlink创建失败 - Linux/macOS 上某些挂载卷（如 Docker volume、NAS）不支持 symlink，
composer show my/package里 source 路径显示正常，但ls -l vendor/my/package仍是目录而非链接，这时只能接受复制模式
composer show my/package不显示source: path /xxx怎么办
说明 Composer 根本没走 path 仓库逻辑，还在从 Packagist 或其他仓库拉取。最常见原因是repositories配置位置不对或被覆盖。
-
repositories必须写在composer.json顶层，不能嵌套在require或config里 - 多个仓库时，path 类型要放在数组前面——Composer 按顺序查找，Packagist 默认在最后，如果它先匹配到同名包就直接用了
- 确认
url路径是否真的存在：ls -l ../my-package（从主项目composer.json所在目录执行） - 路径里不能有空格或中文；Windows 上一律用正斜杠
/，不要用\ - 本地包目录下必须有
composer.json，且里面不能有"type": "project"（这种包会被 Composer 主动忽略）
调试时改了本地包代码，PHP 还是加载旧类
大概率是 OPCache 缓存了已加载的类文件，不是 Composer 配置问题。Composer 的 symlink 已生效，但 PHP 进程没重新读取文件。
- CLI 环境下：重启 PHP 进程，比如
php -S服务要停掉重起，或phpunit跑完后清 OPCache（opcache_reset()） - FPM 环境下：需要
sudo systemctl reload php*-fpm或手动清理 OPCache（opcache_reset()需在 Web 请求中执行） - 确认 autoload 是否覆盖：本地包若用了
autoload-dev，而主项目没运行composer dump-autoload --dev，那些类就不会进自动加载映射 - 别只看
vendor/my/package是不是软链接，关键看composer show my/package输出里有没有source: path这一行
实际用起来，最易卡住的点不是配置语法，而是路径基准和 OPCache。每次怀疑不生效，先composer show看 source，再ls -l vendor看链接，最后php -r 'var_dump(opcache_get_status());'确认缓存状态。
