结论：对未打 Tag 的纯开发库，必须用 dev-branch#commit-hash 或 alias（如 2.5.x-dev）锁定版本，因 ^/~ 约束仅作用于 SemVer 标签，dev-main 等分支名不参与版本计算且每次 update 都拉最新提交。
直接说结论：对未打 Tag 的纯开发库（比如只维护 dev-main 或 dev-develop），不能用 ^ 或 ~ 约束，必须显式写分支名 + 提交哈希或别名才能精准回溯。
为什么 ^2.0 这类语义化约束对 dev-main 完全无效
Composer 的 ^ 和 ~ 只作用于符合 SemVer 规则的标签版本（如 v1.2.3、2.4.0）。分支名（dev-main、dev-feature/x）不参与版本计算，也不受任何范围约束影响——它永远只指向该分支最新提交，且每次 composer update 都会拉最新代码。
常见错误现象是：你昨天用 "vendor/package": "dev-main" 装了某个功能，今天 composer install 却发现行为变了，但 composer.lock 里显示还是 dev-main —— 因为 lock 文件记录的是当时 HEAD 的 commit hash，而 install 默认不重 fetch 分支，除非你删了 vendor/ 或加 --force-install。
-
dev-main在composer.json里只是“符号引用”，不是版本号 -
composer show vendor/package输出的version字段会是类似dev-main#abc1234，其中abc1234是实际锁定的提交 - 如果远程分支被 force-push 覆盖，旧 commit 可能丢失，导致
composer install失败并报Could not find package
如何用 commit hash 锁定未打 Tag 的开发库
最可靠的方式是把分支名替换成具体 commit hash，并带上 # 前缀。Composer 支持这种写法，且会把它当作“精确版本”处理：
composer require vendor/package:dev-main#abc1234
这条命令会：
- 把
"vendor/package": "dev-main#abc1234"写入composer.json - 在
composer.lock中记录该 commit 的完整 hash 和下载 URL - 后续
composer install严格按此 hash 拉取，不会更新到分支新提交
注意：abc1234 必须是远程仓库中真实存在的 commit，且该 commit 未被 GC 或 force-push 删除；否则安装失败。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
用 dev-branch-name + alias 实现“伪稳定版本”
如果你不想每次手动填 hash，又需要控制升级节奏，可在开发库自己的 composer.json 中设置 alias：
{
"name": "vendor/package",
"version": "dev-main",
"extra": {
"branch-alias": {
"dev-main": "2.5.x-dev"
}
}
}
然后你在下游项目中就可以这样写：
"vendor/package": "2.5.x-dev"
效果等价于 dev-main，但好处是：
-
2.5.x-dev可以参与^2.5约束（虽然仍只匹配分支，不真做版本比较） - 团队沟通时可用
2.5.x指代某阶段的main快照，比dev-main更具语义 - 一旦未来打了
v2.5.0Tag，^2.5会自动切换到 tag 版本，无需改约束
⚠️ 注意：alias 必须由包作者在源码中声明，下游项目无法自行指定。
回溯到历史 dev-main 提交的实操步骤
当你发现当前 dev-main 引入 bug，想退回上周的版本，但没记 commit hash：
- 先查
composer.lock：搜索vendor/package，找到"reference"字段值（就是上次 install 用的 hash） - 或者运行
composer show -s vendor/package，输出里有source→reference - 若 lock 文件已丢，去 GitHub/GitLab 页面翻
main分支的 commit history，找时间点相近的 commit - 执行
composer require vendor/package:dev-main#xxx --with-all-dependencies，强制重装 - 验证：运行
composer show vendor/package，确认version显示为dev-main#xxx
别指望 composer update --rollback 或改 composer.json 后跑 update 能生效——Composer 没这功能，分支回溯只能靠显式指定 hash 或 alias。
