Composer 本身不托管代码，仅解析下载；私有框架必须通过 Git + Satis 等外部服务组合实现，satis.json 需显式声明各仓库、启用 ZIP 归档、确保 name 严格匹配且 packages.json 可被正确访问。
私有框架核心包不能直接“托管”在 Composer 本身，必须通过外部仓库（如 Git）+ 元数据索引服务（如 Satis）组合实现。Composer 只负责解析和下载，不存代码、不跑服务。
为什么不能把框架代码直接扔进 composer.json？
Composer 的 composer.json 是声明文件，不是存储介质。你写 "myorg/framework": "1.2.0"，它只负责找这个包的元数据（比如版本、autoload 规则、dist 下载地址），然后去指定位置拉 ZIP 或克隆 Git —— 它自己不保存任何源码。
常见误操作包括：把框架代码塞进项目 vendor 目录手动维护、在主项目的 repositories 里写本地路径（"type": "package" + "dist" 指向 ./framework）、甚至试图用 path 类型指向内网 NFS 路径。这些方式要么无法被其他项目复用，要么破坏依赖隔离，要么在 CI 中彻底失效。
satis.json 必须显式列出每个框架仓库
Satis 不自动发现 Git 仓库，必须人工在 satis.json 的 repositories 数组中逐条声明。框架类包通常不止一个（比如 core、http-kernel、database-adapter），漏掉任意一个，composer update 就会报 Could not find package。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
"type": "vcs"是唯一可靠类型；"type": "git"或"type": "package"在框架场景下极易出错 - URL 必须是可
git clone的地址，例如"https://git.example.com/myorg/framework-core.git"，不能是网页地址 - 若框架使用子模块或 Git LFS，Satis 默认不处理，需额外配置
archive.format和钩子脚本预构建 - 多个框架包之间有依赖关系时，
satis.json中的require段要对齐实际版本约束，否则build阶段会跳过不满足条件的版本
dist ZIP 必须包含 autoload 映射且不可省略
框架核心包体积大、类多，靠 source（即 Git clone）安装极慢，且每次 composer install 都要重走 Git 协议。启用 archive 是刚需，但容易踩坑：
-
"format": "zip"比"tar"更通用，Windows CI 和某些旧版 PHP 不支持 tar 解压 -
"prefix-url"必须可公开访问（哪怕仅限内网），且 Web 服务器要返回Content-Type: application/zip，否则 Composer 回退到 source 并静默失败 - ZIP 包内结构必须与框架自身
composer.json的autoload段一致 —— 比如框架声明了"psr-4": {"MyOrg\Framework\": "src/"}，那 ZIP 解压后必须有src/目录，且不能多一层冗余目录（如framework-core-1.2.0/src/） - 构建时加
--skip-dev，避免把tests/或dev-scripts/打进 ZIP，既增大体积又可能触发自动加载冲突
客户端 require 时 name 大小写和 vendor 名必须完全一致
框架包名不是“随便起的别名”。Composer 匹配 require 字段时做的是严格字符串比对，大小写、连字符、下划线全部敏感：
- 如果框架仓库的
composer.json写的是"name": "MyOrg/Framework-Core"，你在业务项目中就必须写"MyOrg/Framework-Core": "^1.2"，写成"myorg/framework-core"或"myorg/framework_core"都会失败 - vendor 名建议全小写、无特殊符号（如
myorg），但一旦定死就不能改；改了等于发布新包，旧项目不会自动迁移 - 框架若提供多个子包（如
myorg/framework-http），它们的name必须在各自仓库的composer.json中正确定义，且不能与主包同名
最常被忽略的一点：Satis 构建后的 packages.json 文件必须被客户端真实读取。很多团队把 Satis 输出目录部署到 Nginx，却忘了配 try_files $uri /packages.json，导致 404 后 Composer 自动 fallback 到 packagist.org —— 表面看 install 成功了，实际装的是公共同名包，框架特有功能全失效。
