path仓库必须用本地绝对路径，因相对路径在CI/CD或Docker中因getcwd()不确定而解析失败；正确写法为完整绝对路径，如/home/you/projects/common-utils或C:devcommon-utils。
path仓库在微服务项目中为什么必须用本地绝对路径
微服务拆分后，多个服务共用的私有包（如common-utils、auth-contract）常需边开发边联调。若用git源或私有composer镜像，每次改完都要git push → tag → composer update，来回十几秒起步，根本没法调试。用path仓库可直接映射本地目录，改完立刻生效。
但注意：path类型仓库只接受**绝对路径**。相对路径（如../common-utils）在CI/CD或Docker中会解析失败——因为composer install运行时的getcwd()不一定是项目根目录，尤其当命令被封装进脚本或通过php -r触发时。
- 正确写法：
/home/you/projects/common-utils（Linux/macOS）、C:devcommon-utils（Windows） - 错误写法：
../common-utils、./packages/common、~/common-utils - 验证方式：运行
composer config repositories，输出中的url字段必须是完整绝对路径，不能含..或~
如何安全添加path仓库而不破坏packagist主源
很多团队误把path仓库硬编码进composer.json的repositories数组，结果导致packagist.org被降级为普通候选源，依赖解析变慢，甚至漏装某些仅在Packagist发布的包。
正确做法是用composer config命令注入，并确保packagist键仍存在且未被覆盖：
- 执行：
composer config repositories.packagist composer https://mirrors.aliyun.com/composer/（先保主源） - 再执行：
composer config repositories.my-common path /home/you/projects/common-utils（追加自定义源） - 检查：
composer config repositories应输出包含两个对象："packagist"和"my-common"，且packagist的type必须是"composer" - 关键点：不要手动编辑
composer.json里的repositories，否则容易写成数组格式，触发Composer的“合并所有源”逻辑而非“主源+补充源”逻辑
path仓库的autoload与符号链接陷阱
path仓库本身不自动加载代码——它只让Composer知道“这个包存在”，真正加载靠autoload配置。如果common-utils/composer.json里没配autoload（如"psr-4": {"Common": "src/"}），即使require成功，new CommonSomeClass()也会报Class not found。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
另一个常见坑是符号链接（symlink）：
- 如果你用
ln -s把/home/you/projects/common-utils链到/var/www/my-service/packages/common，然后在repositories里填后者路径——Composer会读取目标目录的composer.json，但vendor/autoload.php生成时可能把路径解析错，导致require失败 - 更稳妥的做法：直接用真实绝对路径，并在
common-utils/composer.json中确认autoload指向的是包内相对路径（如"src/"），不是链接外的路径 - 验证：进入
my-service后运行composer dump-autoload -o，再grep -r "Common\\\" vendor/composer/autoload_psr4.php，看映射是否正确
CI/CD中path仓库必须禁用或条件化
path仓库只适用于本地开发。CI流水线（GitHub Actions/GitLab CI）或Docker构建时，目标机器上根本不存在/home/you/projects/common-utils，composer install会直接报错Source path "/xxx" does not exist。
解决方法不是删掉配置，而是用环境变量控制：
- 在
composer.json中把repositories设为空对象："repositories": {} - 本地开发时，用脚本自动补全：
if [ -d "/home/you/projects/common-utils" ]; then composer config repositories.my-common path /home/you/projects/common-utils; fi - CI环境中，跳过该步骤；或统一用
git源（如"type": "vcs", "url": "https://gitlab.internal/common-utils.git"）替代 - 终极保险：在
composer.json中加"config": {"allow-plugins": false}，防止某些插件意外激活path逻辑
微服务下path仓库最易被忽略的点，是它完全绕过了版本约束校验——你require "common-utils": "^1.0"，但本地目录实际是dev-main分支，Composer不会报错也不会警告。上线前务必确认composer.lock中记录的dist信息是否为你预期的稳定版本，而不是"source": {"type": "path", ...}这种开发态快照。
