私有源配置必须写在项目顶层composer.json的repositories数组中，且为json数组格式；auth.json需600权限并存放于项目根目录或composer_home；私有包版本须严格遵循semver并打git tag；satis构建后须重新发布packages.json并刷新cdn缓存。
私有源仓库配置必须写在项目 composer.json 里
很多人以为改私有包自己的 composer.json 就够了，其实完全无效。Composer 只读取你当前要安装依赖的那个项目的顶层 composer.json 中的 repositories 数组。
常见错误现象：Could not find package —— 不是源没搭好，而是项目里根本没声明。
-
repositories必须是 JSON 数组，不能是对象（比如{"my-repo": {}}是错的） - 每项必须含
"type"和"url"；type只能是"vcs"、"composer"或"path" - URL 指向 Git 仓库根目录（即包含
composer.json的那个地址），不能是 GitHub 的 tag 页面链接，也不能带.git后缀（vcs类型下可加但非必须；composer类型下绝对不能加） - 多个源时顺序决定优先级：Composer 从上到下匹配，第一个命中就停，同名包后面的会被忽略
auth.json 是唯一合法凭据载体，权限必须为 600
HTTPS 私有 Git（GitLab/GitHub/Bitbucket）或 Satis 源需要认证，但凭据绝不能硬编码进 composer.json 或 URL 里，否则泄露风险极高。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
auth.json必须放在项目根目录（与composer.json同级）或全局COMPOSER_HOME目录下 - Linux/macOS 下必须运行
chmod 600 auth.json；权限不对，Composer 会静默忽略，不报错也不提示 - 内容格式示例：
{"http-basic": {"git.example.com": {"username": "token", "password": "abc123..."}}}
私有包版本号必须严格遵循语义化版本（SemVer）
公司内部组件不是“改完 push 就完事”，每个 git tag 都对应一次正式发布，且必须是 v1.2.3 或 1.2.3 这种格式。否则 Satis 构建时无法识别，composer require 会 fallback 到 dev-main 分支，失去版本控制意义。
- 主版本（MAJOR）升级 = 破坏性变更，所有下游项目必须人工评估并修改调用代码
- 次版本（MINOR）升级 = 新增向后兼容功能，建议用
^1.2.0约束，CI 中自动测试通过即可上线 - 修订版本（PATCH）升级 = 仅修复 bug，可用
~1.2.0锁定范围，适合高频 hotfix 场景 - 禁止使用
dev-master或dev-main在生产环境 —— 它们不锁定 commit hash，下次composer update可能拉到任意未测代码
Satis 构建后必须重新 publish packages.json 并刷新 CDN 缓存
Satis 不是实时服务，它把所有包元数据静态编译成一个 packages.json 文件。这意味着：
- 每次新增或更新私有包，必须重新运行
satis build satis.json web/ - 如果用了 CDN 或反向代理（如 Nginx 缓存），
packages.json的 HTTP 响应头需设置Cache-Control: no-cache，否则项目composer update可能读到过期索引 - 推荐在 CI 流程末尾自动触发构建 + rsync 推送，避免人工漏操作
- 验证是否生效：直接
curl https://your-satis.com/packages.json | jq '.packages["vendor/package"]'，确认 tag 列表已更新
composer update 中拿到不一致的状态。
