# 发布扩展与更新渠道

> 选择 Git ref、GitHub Release 或 npm，准备完整归档并核对平台资产名称。

- 网址：https://funcoding.ai/agents/qwen-code/customize/extension-releasing/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Qwen Code 官方文档：Extension Releasing](https://github.com/QwenLM/qwen-code/blob/main/docs/users/extension/extension-releasing.md)、[Qwen Code 官方文档：Extensions](https://github.com/QwenLM/qwen-code/blob/main/docs/users/extension/introduction.md)

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

## Git ref 更新

```bash
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}.{arch}.{name}.tar.gz` 或 zip |
| 平台 | `{platform}.{name}.tar.gz` 或 zip |
| 通用 | 仅附一个资产时作为 fallback |

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 发布：

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

以上会实际发布包，应由扩展作者在自己的发布流程中执行。私有注册表读取 NPM_TOKEN 或当前目录/home `.npmrc` 认证，详见[来源配置](https://funcoding.ai/agents/qwen-code/customize/extension-sources/)。

## npm 更新规则

| 安装形式 | 更新来源 |
| --- | --- |
| `@scope/pkg` | latest dist-tag |
| `@scope/pkg@beta` | beta dist-tag |
| `@scope/pkg@1.2.0` | 精确固定，视为已最新，不提示升级 |

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