扩展来源与兼容格式

区分 Git、归档、npm、市场插件转换及旧 Git 安装限制。

This page has not been translated into English yet. The original Chinese version is shown below.

同一 install 命令可以接收多种来源，但来源格式决定安装转换、更新方式和支持能力。不要把能安装解释为原平台全部功能等价。

常用来源

来源	形式与条件
Git	Git URL 或 `owner/repo`
本地目录	扩展根路径
本地或远程归档	`.zip`、`.tar.gz`，根或唯一顶层目录中包含完整扩展
npm	仅 `@scope/package`，可附版本或 dist-tag
Claude 市场	市场名/仓库 URL，可加 `:<plugin-name>` 选插件
Agent Plugins v1	保留标准 manifest 的便携包，能力范围另行限制

远程归档 URL 可更新，但必须继续指向同一扩展的新归档。本地 install 是复制，源目录变化不会自动映射到安装副本。

Claude 插件安装时转换清单、agent、Skill 和工具映射。Gemini 扩展将 gemini-extension.json 转为原生清单，TOML 命令迁移 Markdown，并保留 MCP、上下文和设置。

Qoder 使用 .qoder-plugin/plugin.json，保留 commands、agents、skills；根 .mcp.json 纳入扩展 MCP。根 system-prompt.md 作为上下文，与 QWEN.md 或其他声明上下文一起保留并去重。

Agent Plugins v1则原生读取，不生成 qwen-extension.json，也不改写 portable 文件，不能按以上转换流程推断能力。

qwen extensions install @scope/my-extension@1.2.0
qwen extensions install @scope/my-extension --registry https://registry.example.com

仅 scoped 包受支持，避免与 owner/repo 混淆。注册表优先级：显式 --registry、.npmrc 的 scope 注册表、.npmrc 默认注册表，最后 npm 官方注册表。

认证优先 NPM_TOKEN，再读取当前目录和用户 home 的 .npmrc，支持 host 级与带路径的 _authToken。包根需要 qwen-extension.json 或符合 v1 的 plugin.json，不是任意 npm 包都能当扩展。

带凭据、非 GitHub、嵌套 marketplace、submodules、Git LFS 来源要求 Git 2.37 或更高，以便把 Git 连接固定到已验证的 DNS 结果。

较旧 Git 只支持匿名公开 GitHub 根仓库 HTTPS URL：先把 ref 解析为 commit，再下载源码归档。该回退不能处理 submodules 或 LFS；仓库有 Releases 时仍优先 release 安装。

回退下载限制为压缩 100 MiB，归档 100,000 项、展开 1 GiB、路径元数据 8 MiB，包含最多 100 个链接所物化的文件。仅允许直接指向仓库内普通文件的符号链接，并要求系统允许创建；Windows 可能需 Developer Mode 或额外权限。

目录、链式、悬空、绝对、逃逸、硬链接及 POSIX 字面反斜杠目标都会拒绝。其他 Agent Plugin 安装路径仍省略符号链接，不能把 GitHub 旧 Git 回退的特例推广到全部安装路径。