Satis不是服务而是静态生成器，必须配Web服务器托管、客户端显式声明type:"composer"源并禁用packagist.org；构建失败主因是Git权限、非法version、output-dir路径错误或Web配置未对齐。
不是“装完就能用”，Satis 生成的是静态文件，必须配 Web 服务器托管 + 客户端显式声明源 + 禁用 packagist.org 才能生效。
php bin/satis build 跑不起来？先查构建环境
根本不是命令写错，而是 satis 运行时缺权限、路径或 Git 认证。它不会报错，只会静默跳过问题包，最后 packages.json 为空。
- 运行用户必须能免密
git clone所有repositories.url：SSH 方式确认ssh -T git@gitlab.internal通；HTTPS 方式执行git config --global credential.helper store并输一次密码，或用COMPOSER_AUTH传 token -
output-dir必须是绝对路径（如/var/www/satis），且确保 Web 用户对该路径有读写权限 - 目标 Git 仓库根目录下必须有合法
composer.json，其中name字段只能含小写字母和短横线（如my-org/my-lib），version不能是"dev-main"这类非法值
satis.json 里哪些字段写错会导致包直接消失？
结构错位或语义错误会让 satis 静默忽略整个仓库，下游完全看不到包——没报错，但 packages.json 就是空的。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
repositories必须是顶层数组，每个元素是完整对象：{"type": "vcs", "url": "https://git.internal/lib"}，不能只写字符串 URL -
require-all和require不能共存；想拉所有 tag/branch 就设"require-all": true，否则用"require": {"vendor/package": "*"} - 私有 Git 用
v1.2.0或dev-main？得在对应repositories项里加"no-api": true和"branches": ["main"]，否则 satis 解析失败就跳过
客户端 composer.json 怎么写才真正走私有源？
配置错一个字符，Composer 就当没这回事——它不兜底、不重定向、不回退，只按字面匹配。
-
repositories必须是项目根级composer.json的顶层字段，不能嵌套在require或其他位置 - 每条源必须明确写
"type": "composer"，不能写"type": "vcs"，也不能漏掉type -
url必须以/结尾："https://packages.internal/"是对的，"https://packages.internal"会拼成packages.json错误路径导致 404 - 务必加
"packagist.org": false，且放在repositories数组最前面，否则同名包优先从官方源拉取
Web 服务器怎么配才能让 packages.json 可访问？
Satis 不起服务，只扔文件。Nginx/Apache 配错一点，curl https://satis.example.com/packages.json 就返回 404 或 HTML 欢迎页。
- Nginx 的
root必须精确等于satis.json中的output-dir值（如/var/www/satis） - 加
index packages.json;，否则访问根路径/会找index.html（Satis 默认不生成） - 确保
types { application/json json; }，否则packages.json可能被当成 text/plain 返回，Composer 拒绝解析 - dist ZIP 路径如
dist/vendor-package/version-hash.zip必须可被直接 GET，Nginx/Apache 不能限制.zip后缀或/dist/路径
最常被忽略的点：homepage 字段必须和实际可访问的根 URL 完全一致，包括协议、域名、端口和末尾斜杠；差一个字符，所有 dist 下载链接和元数据都会错乱。
