发布扩展与更新渠道

扩展可通过 Git 仓库、GitHub Releases 或 scoped npm 包分发。选择渠道同时决定用户如何追踪更新，不能只看清单 version。

Git ref 更新

qwen extensions install <your-repo-uri> --ref=stable

ref 可为分支、标签或 commit，默认仓库默认分支。Git 路径按所跟踪 ref 的 HEAD 判断最新内容，不按 qwen-extension.json 版本号排序，因而也可通过移动所跟踪分支回到旧内容。

可用 stable、preview、dev 分支组织发布；具体合并和发布由项目流程决定。用户固定 commit 与追踪持续移动的分支有不同更新预期，应在发布说明写清。

GitHub Release 与资产选择

默认查 GitHub 标记为 latest 的 Release；显式 --ref=<release-tag> 可以固定。该渠道目前不提供选择 pre-release 或 semver 范围的机制。

归档必须自包含，包含根 qwen-extension.json 或 Agent Plugins v1 plugin.json，以及所有运行所需文件。需要构建的扩展应附编译产物，不能要求用户安装后凭空生成未打包的 dist。

平台资产按以下优先级选择：

platform 为 darwin、linux、win32，arch 为 x64 或 arm64。例如 darwin.arm64.my-tool.tar.gz、linux.x64.my-tool.tar.gz、win32.my-tool.zip。

自动发布流程应核对实际构建平台与上传文件名。官方示例的构建 x64 与上传 arm64 文件名存在不一致，不宜直接照抄；这里保留命名契约，不复制该未对齐 workflow。

npm 包与认证

包必须是 scoped 名称，根有受支持 manifest，并且 package.json 的 files 或 .npmignore 未排除引用资源。完成包内容检查后才执行标准 npm 发布：

npm publish
npm publish --registry https://registry.example.com

以上会实际发布包，应由扩展作者在自己的发布流程中执行。私有注册表读取 NPM_TOKEN 或当前目录/home .npmrc 认证，详见来源配置。

npm 更新规则

可以通过 npm publish --tag beta 发布预览，再让用户安装对应 tag。npm dist-tag 与 GitHub pre-release 支持是两个独立机制，不能互相推断。