初始化可发布PHP包需三要素：composer.json（含合法name和psr-4 autoload映射）、src/目录、至少一个匹配命名空间的PHP类；运行composer dump-autoload并测试实例化类不报错即结构正确。
怎么初始化一个可发布的 PHP 包目录结构
Composer 包不是随便建个文件夹就能发的，核心是让 composer install 能认出它、加载它、自动注册类。最简但不可省的三样东西：一个 composer.json、一个命名空间对应的源码目录（比如 src/）、至少一个带命名空间的 PHP 类。
-
composer.json必须有"name"（格式为vendor/name，比如myorg/my-utils），否则 Packagist 拒绝收录 -
"autoload"里推荐用"psr-4"，映射如"MyOrg\MyUtils\": "src/"，别漏掉末尾斜杠和命名空间末尾双反斜杠 - 类文件路径必须严格匹配 PSR-4 规则：命名空间
MyOrgMyUtilsHelper→ 文件路径src/Helper.php，大小写敏感，错一个字母就Class not found - 别急着写功能，先跑通
composer dump-autoload+php -r 'new MyOrgMyUtilsHelper();'，不报错才算结构稳了
为什么 vendor/bin 目录里的可执行文件总找不到命令
Composer 包里放 CLI 工具（比如 my-utils 命令）时，光在 bin/ 下放脚本不够，composer.json 还得显式声明 "bin" 字段，否则 composer install 不会软链到 vendor/bin/。
-
"bin"值必须是相对路径字符串数组，例如"bin": ["bin/my-utils"]，不能写成"bin/my-utils"（少了一层数组） - 脚本第一行必须是
#!/usr/bin/env php，且文件要有可执行权限（chmod +x bin/my-utils），Windows 用户容易漏这点，导致my-utils: command not found - 脚本内别直接用
require __DIR__.'/../vendor/autoload.php'—— Composer 安装后 autoload 是全局的，应通过use引入类，靠 PSR-4 自动加载 - 本地测试时，运行
composer install --dev后检查vendor/bin/下是否真有对应软链接，没有就说明bin配置没生效
发布前必须验证的 3 个 Composer 兼容性点
包能跑通本地不等于别人能装上。Packagist 和下游用户环境更“挑”，尤其 PHP 版本、扩展依赖、稳定性标记这三项最容易卡发布。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
"require"里写的 PHP 版本（如"php": "^8.1"）必须和你实际开发/测试的版本一致，写"^7.4 || ^8.0"却只在 8.2 下测过，CI 极可能失败 - 如果用了
ext-gmp或ext-redis这类扩展，必须在"require"里明确写上，否则用户composer require后运行时报Call to undefined function gmp_init()才发现 -
"minimum-stability"默认是stable，但你的包还没打 v1.0.0 tag，只有dev-main分支，就得在composer.json加"prefer-stable": true并确保"minimum-stability": "dev"，否则别人require时提示Could not find package
如何让别人 require 你的包时不被 autoload 错乱搞崩
很多人本地测试好好的，一发布，别人 composer require myorg/my-utils 后却报 Class MyOrgMyUtilsHelper not found —— 问题往往出在 autoload 配置和实际文件布局的微小错位。
立即学习“PHP免费学习笔记（深入）”；
- 运行
composer validate，它会检查composer.json格式、字段合法性，以及 autoload 路径是否存在；报Autoload configuration is invalid就别急着 push - 用
composer dump-autoload -o生成优化后的 classmap，再进vendor/composer/autoload_psr4.php翻一眼，确认你的命名空间映射值确实是["MyOrg\MyUtils\"]=> array($baseDir . "/src") - 如果你的包同时支持 PHP 7 和 8，但用了 PHP 8 的联合类型（
string|int），PHP 7 用户composer install会成功，但运行时报ParseError—— 这类语法兼容性不会被composer validate捕获，得靠 CI 覆盖多版本测试 - 别在
src/外另建lib/或classes/目录然后手动 require，PSR-4 只认你声明的路径，多出来的文件根本不会被扫描
最常被忽略的是：改完 composer.json 后忘了 composer dump-autoload，或者 push 到 GitHub 前没 git add composer.json —— Packagist 同步的永远是你仓库里实际存在的那个 JSON 文件，本地改了不算数。
