path仓库是唯一可靠方案，因其强制启用符号链接、跳过版本解析、直接映射本地路径，且要求name完全匹配、版本写为"dev-main"等开发别名，否则将回退Packagist拉取。
Composer 本身不支持“多分支并行联调”意义上的热重载或跨包实时通信，所谓“免推包联调”的核心能力，只来自 path 类型仓库 + 符号链接 + 正确的版本约束匹配——其他所有名字（如 “Studio”、“link”、“dev-main symlink”）都是对这一机制的误读或包装。
为什么 path 仓库是唯一可靠方案
很多人试过 composer require vendor/name:dev-main 配 package 类型仓库，结果类找不到、改了不生效。根本原因是：package 类型不会自动创建符号链接，也不跳过版本校验；而 path 类型仓库强制启用 symlink（Linux/macOS）、跳过版本解析、直接映射本地路径，autoload 规则照常加载。
-
path仓库下，vendor/vendor/name是真实软链（ls -l可见->），改本地源码立刻反映到项目中 - 它不依赖 Git 分支名，但要求本地包
composer.json中name字段与require完全一致（包括大小写、斜杠） - 版本号必须写成
"dev-main"或"dev-develop"这类开发分支别名，不能写"*"或"^1.0"—— 否则 Composer 会忽略path源，转而从 Packagist 拉稳定版 - Windows 用户需确认启用了开发者模式，或以管理员身份运行终端；否则 symlink 创建失败，退化为静态拷贝，导致“改了没反应”
composer.json 配置要点与常见报错
配置必须写在主项目的 composer.json 根级，不是本地包自己的文件。路径是相对于该 composer.json 的位置，不是 shell 当前目录，也不是项目根目录。
- 正确示例：
"url": "../my-local-package"（相对路径）或"url": "/home/user/pkg"（绝对路径），不能含~或环境变量 - 错误现象：
Could not find package vendor/name at any version→ 大概率是路径不对、本地包缺composer.json、或name字段拼写不一致 - 本地包必须已执行过
git init && git add . && git commit，否则 Composer 拒绝加载（即使没用 Git 功能） - 若本地包用的是
develop分支而非main，require行必须同步改为"dev-develop"，不能硬写"dev-main"
Windows / Docker / IDE 下的失效排查
符号链接在 Windows 和容器环境中极易静默失败，表现为 vendor/vendor/name 是普通文件夹而非链接，调试断点不触发、代码修改无响应。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 检查是否 fallback 到 copy：运行
ls -la vendor/vendor/name（Linux/macOS）或dir vendor\vendor\name（Windows），看是否有 - 临时关闭 symlink 排查：
composer config --global symlinks false，再composer install看是否变成复制；确认后务必composer config --global symlinks true恢复 - Docker 中若挂载了本地包目录，确保 PHP 进程用户（如
www-data）有权限创建 symlink，或改用composer install --no-dev+ 手动autoload映射绕过 vendor - PHPStorm 等 IDE 可能缓存 autoload 映射，需手动触发 “Reload project from composer.json” 或清空
var/cache/dev
多组件并行时的配置管理
多个本地包共存时，不要用内联写法（如 "require": {"vendor/a": "dev-main", "vendor/b": "dev-main"}），应统一在 repositories 块中声明，避免版本冲突和维护混乱。
- 推荐结构：
"repositories": [{"type":"path","url":"../pkg-a"},{"type":"path","url":"../pkg-b"}] -
require-dev中的本地包也需单独加进repositories，否则composer install --dev无法识别 - CI/CD 流程中必须移除
path配置，可用脚本自动替换：composer config --unset repositories，否则构建会失败或拉错源 - 严禁将
path仓库用于生产环境部署；上线前必须切回真实版本（如"^2.1"）或发布正式 tag
最常被忽略的一点：符号链接是否生效，不取决于你写了多少配置，而取决于 ls -l vendor/vendor/name 的输出。只要看到箭头，就说明路径映射成功；看不到，其他所有操作都是徒劳。调试先看链接，再查路径，最后动代码。
