必须在主项目composer.json根级repositories数组中配置path源，本地包需有合法composer.json且name与require完全一致，版本必须用dev-main等分支名，三者缺一不可。
必须在主项目 composer.json 的 repositories 数组里配 {"type":"path","url":"./packages/my-pkg"}，本地包目录下要有合法 composer.json 且 name 字段与 require 中完全一致，版本必须用 dev-main 这类分支名——不是路径写对了就能装上，三者（配置位置、包名、版本写法）缺一不可。
repositories 必须写在主项目 composer.json 根级数组里
Composer 只从项目根目录 composer.json 的根级 repositories 数组读取源，写错位置等于没写。常见错误包括：
- 把
repositories塞进require、config或extra字段里 - 写成对象而非数组，例如
"repositories": { "my-local": { "type": "path", ... } }—— 正确写法是"repositories": [{ "type": "path", "url": "./packages/my-pkg" }] - 路径用了
file://、~、$HOME或 Windows 绝对路径（如C:\work\pkg），这些在多数场景下会静默失败 -
url指向的是composer.json文件本身，而不是包含它的目录
本地包的 composer.json 必须满足硬性条件
Composer 不解析目录结构，只读取并校验本地包根目录下的 composer.json。缺失任一关键字段就会跳过该目录，且不报错：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
name必须是vendor/name格式（如"acme/utils"），大小写敏感，不能省略斜杠，不能含下划线或大写字母 -
version字段建议显式设为"dev-main"或"dev-develop"；若留空或格式非法，composer require可能直接失败 - 整个 JSON 必须语法合法：全双引号、无尾逗号、UTF-8 无 BOM；Windows 下尤其注意编辑器是否悄悄加了 BOM
- 目录必须已执行
git init && git add . && git commit -m "init"，否则 Composer 拒绝加载
require 时版本约束必须匹配分支名，不是版本号
path 类型仓库下，Composer 忽略 version 字段，只按 Git HEAD 所在分支解析。写错约束就找不到包：
- 不要写
"acme/utils": "1.0.0"或"acme/utils": "^1.0"—— 本地包没 tag，必然失败 - 必须写
"acme/utils": "dev-main"（如果本地在main分支），或"acme/utils": "dev-develop"（如果默认分支是develop） - 若项目设了
"minimum-stability": "dev"，还需加@dev后缀，即"acme/utils": "dev-main@dev" - 执行命令必须是
composer require acme/utils:dev-main，不是composer install—— 后者不触发源发现逻辑
改代码后立刻生效的关键是 symlink + update
默认行为是复制（copy），改本地源码不会同步到 vendor。要热更新，必须启用符号链接并重建：
- 在
repositories条目中加"options": {"symlink": true}，例如：{ "type": "path", "url": "./packages/my-pkg", "options": {"symlink": true} } - Linux/macOS 通常默认支持；Windows 必须开启“开发者模式”或以管理员权限运行命令行，否则
symlink创建失败且无提示 - 改完本地包代码后，运行
composer update acme/utils（不是install或dump-autoload）才能刷新链接 - 验证是否成功：
Linux/macOS 执行ls -la vendor/acme/utils，应看到->指向源目录；
Windows 执行dir vendor\acme\utils，应显示为“快捷方式”类型
最容易被忽略的是：本地包目录必须有 Git commit，且 repositories 配置必须是数组形式、写在主项目根级；这两点任一缺失，都会导致静默失败——没有错误提示，也没有任何输出，就像配置根本不存在一样。
