Composer通过bin字段将脚本链接至vendor/bin/或~/.composer/vendor/bin/，需设执行权限、shebang及显式引入autoload.php；PATH配置、链接有效性与跨环境验证是关键。
Composer 本身不提供 CLI 工具开发框架，但它是分发和加载 PHP CLI 工具包的事实标准 —— 关键在于正确声明 bin、配置 autoload，并确保入口脚本可执行。
如何让 Composer 安装后自动注册命令到系统 PATH
核心是 composer.json 中的 bin 字段。它声明一个或多个可执行脚本路径（相对于项目根目录），Composer 在全局安装（composer global require）或本地安装后，会将这些路径软链接到 vendor/bin/；若用 composer global，还会链接到 ~/.composer/vendor/bin/（需确保该路径在系统 $PATH 中）。
实操建议：
-
bin数组里填的是脚本文件路径，不是类名或函数名，例如："bin": ["bin/mytool"] - 脚本文件（如
bin/mytool）必须有 Unix 执行权限（chmod +x bin/mytool），Windows 用户用 Git Bash 或 WSL 开发时同样需要 - 脚本第一行必须是 shebang，如
#!/usr/bin/env php，否则 shell 执行时报Permission denied或直接忽略 - 不要在
bin/mytool里写大量逻辑，只做最小引导：加载 autoloader，实例化主命令类，调用run()
为什么 CLI 入口脚本不能直接 new 类而要先加载 autoload
因为 Composer 的自动加载机制（由 vendor/autoload.php 驱动）不会自动生效 —— CLI 脚本是独立进程入口，PHP 不会像 Web 请求那样隐式包含 autoloader。
常见错误现象：运行 mytool 报 Fatal error: Class 'MyTool\Application' not found，即使类已按 PSR-4 正确声明。
实操建议：
- 入口脚本开头必须显式引入：
require __DIR__.'/../vendor/autoload.php'; - 路径要写对：
__DIR__是bin/目录，所以../vendor/autoload.php才能命中（本地开发）；全局安装时，__DIR__指向~/.composer/vendor/xxx/yyy/bin/，相对路径依然成立 - 避免用
require_once 'vendor/autoload.php'（少个../）或硬编码绝对路径（破坏可移植性）
如何支持全局安装 + 命令补全（bash/zsh）
Composer 只管链接，补全是 Shell 层的事。工具自身需提供补全脚本，并提示用户手动启用。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
使用场景：用户希望输入 mytool [tab][tab] 列出子命令，或 mytool run --[tab] 补全选项。
实操建议：
- 在项目中提供
contrib/mytool-completion.bash（或.zsh），内容调用 Symfony Console 的completion命令（如果基于 Console 构建） - 文档明确写出启用方式，例如：
source /path/to/mytool/contrib/mytool-completion.bash，并建议加到~/.bashrc - 不依赖 Composer 自动注入补全 —— 它没这个能力；也不要试图在
bin/mytool里动态生成或加载补全逻辑，那属于运行时开销且不可靠 - 验证方式：新开终端，执行
type _mytool，有输出说明补全已加载
为什么 vendor/bin 下的命令有时“找不到”，有时又正常
根本原因只有两个：PATH 未包含 vendor/bin，或当前执行的是旧链接（如切换分支后未重装依赖）。
性能与兼容性影响：Composer 7+ 对 bin 链接做了缓存优化，但 Windows（CMD/PowerShell）下仍可能因符号链接权限失败而回退为复制，导致更新滞后。
实操建议：
- 检查当前 PATH：
echo $PATH | grep vendor（Linux/macOS）或echo %PATH%（Windows CMD） - 确认链接真实存在：
ls -l vendor/bin/mytool，应指向../packages/name/bin/mytool，而非死链接 - 遇到异常优先执行：
composer install --no-cache（清除 bin 缓存）或composer dump-autoload（仅刷新自动加载） - CI/CD 环境中避免用
vendor/bin/mytool，改用php bin/mytool绕过链接问题（更稳定）
CLI 工具包最难缠的不是功能实现，而是跨环境的一致性：不同用户的 composer global 路径、Shell 类型、权限策略、甚至 Git 配置（core.autocrlf）都可能让 bin 脚本静默失效。每次发布前，在干净 Docker 容器里跑一遍 composer global require + 手动执行，比写十个单元测试更能暴露问题。
