vrr/qwen-code
2
0
Fork 0
mirror of https://github.com/QwenLM/qwen-code.git synced 2026-04-28 11:41:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

Merge pull request #2719 from QwenLM/feat/npm-extension-installation

Browse source 
feat(extension): Add npm registry support for extension installation
This commit is contained in:
tanzhenxin 2026-04-01 16:18:17 +08:00 • committed by GitHub
commit 2eb2f4e319
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 924 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

87
docs/users/extension/extension-releasing.md
View file

@ -1,11 +1,12 @@
# Extension Releasing
There are two primary ways of releasing extensions to users:
There are three primary ways of releasing extensions to users:
- [Git repository](#releasing-through-a-git-repository)
- [Github Releases](#releasing-through-github-releases)
- [npm Registry](#releasing-through-npm-registry)
Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files.
Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files. npm registry releases are ideal for teams that already use npm for package distribution, especially with private registries.
## Releasing through a git repository
@ -119,3 +120,85 @@ jobs:
release/linux.arm64.my-tool.tar.gz
release/win32.arm64.my-tool.zip
```
## Releasing through npm registry
You can publish Qwen Code extensions as scoped npm packages (e.g. `@your-org/my-extension`). This is a good fit when:
- Your team already uses npm for package distribution
- You need private registry support with existing auth infrastructure
- You want version resolution and access control handled by npm
### Package requirements
Your npm package must include a `qwen-extension.json` file at the package root. This is the same config file used by all Qwen Code extensions — the npm tarball is simply another delivery mechanism.
A minimal package structure looks like:
```
my-extension/
├── package.json
├── qwen-extension.json
├── QWEN.md # optional context file
├── commands/ # optional custom commands
├── skills/ # optional custom skills
└── agents/ # optional custom subagents
```
Make sure `qwen-extension.json` is included in your published package (i.e. not excluded by `.npmignore` or the `files` field in `package.json`).
### Publishing
Use standard npm publishing tools:
```bash
# Publish to the default registry
npm publish
# Publish to a private/custom registry
npm publish --registry https://your-registry.com
```
### Installation
Users install your extension using the scoped package name:
```bash
# Install latest version
qwen extensions install @your-org/my-extension
# Install a specific version
qwen extensions install @your-org/my-extension@1.2.0
# Install from a custom registry
qwen extensions install @your-org/my-extension --registry https://your-registry.com
```
### Update behavior
- Extensions installed without a version pin (e.g. `@scope/pkg`) track the `latest` dist-tag.
- Extensions installed with a dist-tag (e.g. `@scope/pkg@beta`) track that specific tag.
- Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date and will not prompt for updates.
### Authentication for private registries
Qwen Code reads npm auth credentials automatically:
1. **`NPM_TOKEN` environment variable** — highest priority
2. **`.npmrc` file** — supports both host-level and path-scoped `_authToken` entries (e.g. `//your-registry.com/:_authToken=TOKEN` or `//pkgs.dev.azure.com/org/_packaging/feed/npm/registry/:_authToken=TOKEN`)
`.npmrc` files are read from the current directory and the user's home directory.
### Managing release channels
You can use npm dist-tags to manage release channels:
```bash
# Publish a beta release
npm publish --tag beta
# Users install beta channel
qwen extensions install @your-org/my-extension@beta
```
This works similarly to git branch-based release channels but uses npm's native dist-tag mechanism.

40
docs/users/extension/introduction.md
View file

@ -12,11 +12,11 @@ We offer a suite of extension management tools using both `qwen extensions` CLI
You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
| Command | Description |
| ------------------------------------- | ----------------------------------------------------------------- |
| `/extensions` or `/extensions manage` | Manage all installed extensions |
| `/extensions install <source>` | Install an extension from a git URL, local path, or marketplace |
| `/extensions explore [source]` | Open extensions source page(Gemini or ClaudeCode) in your browser |
| Command | Description |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| `/extensions` or `/extensions manage` | Manage all installed extensions |
| `/extensions install <source>` | Install an extension from a git URL, local path, npm package, or marketplace |
| `/extensions explore [source]` | Open extensions source page(Gemini or ClaudeCode) in your browser |
### CLI Extension Management
@ -89,6 +89,34 @@ Gemini extensions are automatically converted to Qwen Code format during install
- TOML command files are automatically migrated to Markdown format
- MCP servers, context files, and settings are preserved
#### From npm Registry
Qwen Code supports installing extensions from npm registries using scoped package names. This is ideal for teams with private registries that already have auth, versioning, and publishing infrastructure in place.
```bash
# Install the latest version
qwen extensions install @scope/my-extension
# Install a specific version
qwen extensions install @scope/my-extension@1.2.0
# Install from a custom registry
qwen extensions install @scope/my-extension --registry https://your-registry.com
```
Only scoped packages (`@scope/package-name`) are supported to avoid ambiguity with the `owner/repo` GitHub shorthand format.
**Registry resolution** follows this priority:
1. `--registry` CLI flag (explicit override)
2. Scoped registry from `.npmrc` (e.g. `@scope:registry=https://...`)
3. Default registry from `.npmrc`
4. Fallback: `https://registry.npmjs.org/`
**Authentication** is handled automatically via the `NPM_TOKEN` environment variable or registry-specific `_authToken` entries in your `.npmrc` file.
> **Note:** npm extensions must include a `qwen-extension.json` file at the package root, following the same format as any other Qwen Code extension. See [Extension Releasing](./extension-releasing.md#releasing-through-npm-registry) for packaging details.
#### From Git Repository
```bash
@ -127,7 +155,7 @@ This is useful if you have an extension disabled at the top-level and only enabl
### Updating an extension
For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `qwen-extension.json` `version` field) with `qwen extensions update extension-name`.
For extensions installed from a local path, a git repository, or an npm registry, you can explicitly update to the latest version with `qwen extensions update extension-name`. For npm extensions installed without a version pin (e.g. `@scope/pkg`), updates check the `latest` dist-tag. For those installed with a specific dist-tag (e.g. `@scope/pkg@beta`), updates track that tag. Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date.
You can update all extensions with: