Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/design/qoder-plugin-compatibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Qoder Plugin Compatibility

## Context

Qwen Code installs extensions from directories, archives, Git repositories, archive URLs, and scoped npm packages. Each source is normalized to a local directory before its manifest is loaded. The [Qoder plugin layout](https://docs.qoder.com/en/cli/sdk/plugins) uses `.qoder-plugin/plugin.json` with standard commands, agents, skills, and a root `.mcp.json` file.

## Design

The existing compatible-extension conversion step recognizes the Qoder manifest after native Qwen, Gemini, and Claude manifests. It copies the plugin into a temporary extension directory, writes a generated `qwen-extension.json`, and records `Qoder` as the install origin. Converted Git installs record the checked-out commit in install metadata so update checks remain available after Git metadata is removed.

The generated manifest preserves `name`, `version`, `displayName`, and `description`. A missing version defaults to `1.0.0`. Standard resource directories remain in place, while existing resource path declarations use the same confined collection logic as other compatible plugin formats. Root `.mcp.json` servers are normalized to Qwen transports unless the manifest already defines MCP servers.

A safe root `system-prompt.md` is added to the extension context list. An existing `QWEN.md` and explicitly configured context files remain active alongside it, with duplicates removed.

## Security

The manifest must resolve within the plugin directory and parse as a JSON object with a valid name. Referenced resources and context files must remain inside the plugin. Bulk copying skips symlinks that escape the source root and omits Git metadata. Archive validation accepts the Qoder manifest at the archive root or inside one supported top-level wrapper directory.

## Compatibility

Adding `Qoder` to the shared extension-origin union lets CLI, daemon, SDK, ACP, and Web Shell consumers identify converted plugins without changing install commands or route shapes.
16 changes: 15 additions & 1 deletion docs/users/extension/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Qwen Code extensions package prompts, MCP servers, subagents, skills and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Qwen Code and share those capabilities with others. They are designed to be easily installable and shareable.

Extensions and plugins from [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/) and [Claude Code Marketplace](https://claudemarketplaces.com/) can be directly installed into Qwen Code. This cross-platform compatibility gives you access to a rich ecosystem of extensions and plugins, dramatically expanding Qwen Code's capabilities without requiring extension authors to maintain separate versions.
Extensions and plugins from [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/), [Claude Code Marketplace](https://claudemarketplaces.com/), and Qoder can be directly installed into Qwen Code. This cross-platform compatibility gives you access to a rich ecosystem of extensions and plugins, dramatically expanding Qwen Code's capabilities without requiring extension authors to maintain separate versions.

## Extension management

Expand Down Expand Up @@ -99,6 +99,20 @@ 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 Qoder Plugins

Qwen Code supports [Qoder plugins](https://docs.qoder.com/en/cli/sdk/plugins) that contain a `.qoder-plugin/plugin.json` manifest. Install a local directory, archive, Git repository, archive URL, or scoped npm package with the existing `qwen extensions install` command:

```bash
qwen extensions install ./sample-qoder-plugin
qwen extensions install ./sample-qoder-plugin.zip
qwen extensions install owner/sample-qoder-plugin
```

The installer converts the Qoder manifest to `qwen-extension.json` and preserves standard `commands/`, `agents/`, and `skills/` directories. MCP servers declared in a root `.mcp.json` file are included as extension MCP servers.

When a Qoder plugin contains `system-prompt.md` at its root, Qwen Code loads it as extension context. If the plugin also contains `QWEN.md` or declares other context files, all context files are retained and deduplicated.

#### 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.
Expand Down
35 changes: 34 additions & 1 deletion integration-tests/cli/extensions-install.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

import { expect, test } from 'vitest';
import { TestRig } from '../test-helper.js';
import { writeFileSync } from 'node:fs';
import { mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

const extension = `{
Expand Down Expand Up @@ -50,3 +50,36 @@ test('installs a local extension, verifies a command, and updates it', async ()

await rig.cleanup();
});

test('installs a local Qoder plugin', async () => {
Comment thread
callmeYe marked this conversation as resolved.
Resolved
const rig = new TestRig();
rig.setup('qoder plugin install test');
const manifestDir = join(rig.testDir!, '.qoder-plugin');
mkdirSync(manifestDir, { recursive: true });
writeFileSync(
join(manifestDir, 'plugin.json'),
JSON.stringify({ name: 'sample-qoder-plugin', version: '1.0.0' }),
);
writeFileSync(join(rig.testDir!, 'system-prompt.md'), '# System context');
const skillDir = join(rig.testDir!, 'skills', 'sample-skill');
mkdirSync(skillDir, { recursive: true });
writeFileSync(
join(skillDir, 'SKILL.md'),
'---\nname: sample-skill\ndescription: Synthetic skill\n---\n',
);

try {
const result = await rig.runCommand(
['extensions', 'install', rig.testDir!],
{ stdin: 'y\n' },
);
expect(result).toContain('sample-qoder-plugin');

const listResult = await rig.runCommand(['extensions', 'list']);
Comment thread
callmeYe marked this conversation as resolved.
Resolved
expect(listResult).toContain('sample-qoder-plugin');

await rig.runCommand(['extensions', 'uninstall', 'sample-qoder-plugin']);
} finally {
await rig.cleanup();
}
});
6 changes: 5 additions & 1 deletion packages/acp-bridge/src/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1065,7 +1065,11 @@ export type ServeExtensionInstallType =
| 'npm'
| 'archive-url';

export type ServeExtensionOriginSource = 'QwenCode' | 'Claude' | 'Gemini';
export type ServeExtensionOriginSource =
| 'QwenCode'
| 'Claude'
| 'Gemini'
| 'Qoder';

export interface ServeExtensionCapabilities {
mcpServerCount: number;
Expand Down
3 changes: 2 additions & 1 deletion packages/core/src/config/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -672,14 +672,15 @@ function normalizeGitCoAuthor(value: GitCoAuthorParam | undefined): {
};
}

export type ExtensionOriginSource = 'QwenCode' | 'Claude' | 'Gemini';
export type ExtensionOriginSource = 'QwenCode' | 'Claude' | 'Gemini' | 'Qoder';
export type ExtensionNetworkPolicy = 'public';

export interface ExtensionInstallMetadata {
source: string;
type: 'git' | 'local' | 'link' | 'github-release' | 'npm' | 'archive-url';
originSource?: ExtensionOriginSource;
releaseTag?: string; // Only present for github-release and npm installs.
gitCommit?: string; // Only present when a converted Git install cannot retain .git.
registryUrl?: string; // Only present for npm installs.
ref?: string;
autoUpdate?: boolean;
Expand Down
3 changes: 3 additions & 0 deletions packages/core/src/extension/claude-converter.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1371,6 +1371,7 @@ describe('convertClaudePluginPackage — git-subdir source', () => {
JSON.stringify({ name: 'p', version: '1.0.0' }),
'utf-8',
);
return 'test-commit';
});

writeMarketplace({
Expand Down Expand Up @@ -1422,6 +1423,7 @@ describe('convertClaudePluginPackage — git-subdir source', () => {
vi.mocked(cloneFromGit).mockImplementation(async (_meta, dir) => {
// The clone succeeded but does not contain the requested subdir.
fs.mkdirSync(path.join(dir as string, 'other'), { recursive: true });
return 'test-commit';
});
writeMarketplace({
source: 'git-subdir',
Expand All @@ -1440,6 +1442,7 @@ describe('convertClaudePluginPackage — git-subdir source', () => {
// A hostile repo commits the subdir as a symlink whose name stays inside
// the clone but whose target escapes it.
fs.symlinkSync(secretDir, path.join(dir as string, 'sub'));
return 'test-commit';
});
writeMarketplace({
source: 'git-subdir',
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/extension/claude-converter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -591,7 +591,7 @@ function resolvePluginRelativeFile(
* (`convertClaudePluginPackage`) and standalone (`convertClaudePluginStandalone`)
* conversion paths.
*/
async function buildQwenExtensionFromPlugin(
export async function buildQwenExtensionFromPlugin(
pluginSource: string,
mergedConfig: ClaudePluginConfig,
): Promise<{ config: ExtensionConfig; convertedDir: string }> {
Expand Down
10 changes: 9 additions & 1 deletion packages/core/src/extension/extension-converter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ import {
convertClaudePluginPackage,
convertClaudePluginStandalone,
} from './claude-converter.js';
import {
convertQoderPlugin,
QODER_PLUGIN_MANIFEST,
} from './qoder-converter.js';
import type {
ExtensionNetworkPolicy,
ExtensionOriginSource,
Expand All @@ -25,9 +29,10 @@ export const SUPPORTED_EXTENSION_MANIFESTS = [
'gemini-extension.json',
'.claude-plugin/marketplace.json',
'.claude-plugin/plugin.json',
QODER_PLUGIN_MANIFEST,
] as const;

export async function convertGeminiOrClaudeExtension(
export async function convertCompatibleExtension(
extensionDir: string,
pluginName?: string,
networkPolicy?: ExtensionNetworkPolicy,
Expand Down Expand Up @@ -62,6 +67,9 @@ export async function convertGeminiOrClaudeExtension(
newExtensionDir = (await convertClaudePluginStandalone(extensionDir))
.convertedDir;
originSource = 'Claude';
} else if (fs.existsSync(path.join(extensionDir, QODER_PLUGIN_MANIFEST))) {
newExtensionDir = (await convertQoderPlugin(extensionDir)).convertedDir;
originSource = 'Qoder';
}
signal?.throwIfAborted();
return { extensionDir: newExtensionDir, originSource };
Expand Down
154 changes: 154 additions & 0 deletions packages/core/src/extension/extensionManager.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ const mockGit = {
};
const mockDownloadFromArchiveUrl = vi.hoisted(() => vi.fn());
const mockExtractArchiveFile = vi.hoisted(() => vi.fn());
const mockDownloadFromNpmRegistry = vi.hoisted(() => vi.fn());

vi.mock('simple-git', () => ({
CheckRepoActions: { IS_REPO_ROOT: 'is-repo-root' },
Expand All @@ -65,6 +66,14 @@ vi.mock('./github.js', async (importOriginal) => {
};
});

vi.mock('./npm.js', async (importOriginal) => {
const actual = await importOriginal<typeof import('./npm.js')>();
return {
...actual,
downloadFromNpmRegistry: mockDownloadFromNpmRegistry,
};
});

const mockHomedir = vi.hoisted(() => vi.fn());
vi.mock('os', async (importOriginal) => {
const mockedOs = await importOriginal<typeof os>();
Expand Down Expand Up @@ -153,6 +162,8 @@ describe('extension tests', () => {
Object.values(mockGit).forEach((fn) => fn.mockReset());
mockDownloadFromArchiveUrl.mockReset();
mockExtractArchiveFile.mockReset();
mockDownloadFromNpmRegistry.mockReset();
mockGit.revparse.mockResolvedValue('sample-commit');
});

afterEach(() => {
Expand Down Expand Up @@ -187,6 +198,20 @@ describe('extension tests', () => {
);
}

function writeQoderPlugin(destination: string) {
fs.mkdirSync(path.join(destination, '.qoder-plugin'), {
recursive: true,
});
fs.writeFileSync(
path.join(destination, '.qoder-plugin', 'plugin.json'),
JSON.stringify({ name: 'sample-qoder-plugin', version: '1.0.0' }),
);
fs.writeFileSync(
path.join(destination, 'system-prompt.md'),
'# System context',
);
}

it('installs and uninstalls within an injected extension store root', async () => {
const archivePath = path.join(tempWorkspaceDir, 'custom-root.zip');
fs.writeFileSync(archivePath, 'archive');
Expand Down Expand Up @@ -676,6 +701,135 @@ describe('extension tests', () => {
});
});

it('should install a Qoder plugin with skills and system context', async () => {
const sourcePath = path.join(tempWorkspaceDir, 'sample-qoder-plugin');
fs.mkdirSync(path.join(sourcePath, '.qoder-plugin'), {
recursive: true,
});
fs.writeFileSync(
path.join(sourcePath, '.qoder-plugin', 'plugin.json'),
JSON.stringify({ name: 'sample-qoder-plugin', version: '1.0.0' }),
);
fs.writeFileSync(
path.join(sourcePath, 'system-prompt.md'),
'# System context',
);
const skillPath = path.join(sourcePath, 'skills', 'sample-skill');
fs.mkdirSync(skillPath, { recursive: true });
fs.writeFileSync(
path.join(skillPath, 'SKILL.md'),
'---\nname: sample-skill\ndescription: Synthetic skill\n---\n',
);
const requestConsent = vi.fn(async () => {});
const manager = createExtensionManager();
await manager.refreshCache();

const extension = await manager.installExtension(
{ source: sourcePath, type: 'local' },
requestConsent,
);

expect(extension.installMetadata).toMatchObject({
source: sourcePath,
type: 'local',
originSource: 'Qoder',
});
expect(extension.contextFiles).toEqual([
path.join(extension.path, 'system-prompt.md'),
]);
expect(extension.skills?.map((skill) => skill.name)).toEqual([
'sample-skill',
]);
expect(requestConsent).toHaveBeenCalledWith(
expect.objectContaining({ originSource: 'Qoder' }),
);
});

it.each([
{
type: 'local' as const,
source: 'sample-qoder-plugin.zip',
},
{
type: 'archive-url' as const,
source: 'https://example.com/sample-qoder-plugin.zip',
},
{
type: 'npm' as const,
source: '@example/sample-qoder-plugin',
},
])('should install a Qoder plugin from $type', async (installMetadata) => {
const resolvedInstallMetadata =
installMetadata.type === 'local'
? {
...installMetadata,
source: path.join(tempWorkspaceDir, installMetadata.source),
}
: installMetadata;
if (resolvedInstallMetadata.type === 'local') {
fs.writeFileSync(resolvedInstallMetadata.source, 'synthetic archive');
mockExtractArchiveFile.mockImplementation(
async (_source: string, destination: string) => {
writeQoderPlugin(destination);
},
);
} else if (installMetadata.type === 'archive-url') {
mockDownloadFromArchiveUrl.mockImplementation(
async (_metadata: ExtensionInstallMetadata, destination: string) => {
writeQoderPlugin(destination);
},
);
} else {
mockDownloadFromNpmRegistry.mockImplementation(
async (_metadata: ExtensionInstallMetadata, destination: string) => {
writeQoderPlugin(destination);
return { version: '1.0.0', type: 'npm' };
},
);
}
const manager = createExtensionManager();
await manager.refreshCache();

const extension = await manager.installExtension(
resolvedInstallMetadata,
async () => {},
);

expect(extension.name).toBe('sample-qoder-plugin');
expect(extension.installMetadata?.originSource).toBe('Qoder');
expect(extension.contextFiles).toEqual([
path.join(extension.path, 'system-prompt.md'),
]);
});

it('should install a Qoder plugin from Git', async () => {
mockGit.clone.mockImplementation(async () => {
writeQoderPlugin(mockGit.path());
});
mockGit.getRemotes.mockResolvedValue([
{
name: 'origin',
refs: { fetch: 'https://github.com/example/sample-qoder-plugin' },
},
]);
mockGit.fetch.mockResolvedValue(undefined);
mockGit.checkout.mockResolvedValue(undefined);
const manager = createExtensionManager();
await manager.refreshCache();

const extension = await manager.installExtension(
{
type: 'git',
source: 'https://github.com/example/sample-qoder-plugin',
},
async () => {},
);

expect(extension.name).toBe('sample-qoder-plugin');
expect(extension.installMetadata?.originSource).toBe('Qoder');
expect(extension.installMetadata?.gitCommit).toBe('sample-commit');
});

it('should emit mutation lifecycle events around install', async () => {
const archivePath = path.join(tempWorkspaceDir, 'local-extension.zip');
fs.writeFileSync(archivePath, 'not used by mocked extractor');
Expand Down
Loading
Loading