原生扩展 Manifest 与设置

配置能力目录、MCP、上下文和环境设置，理解命令与 Skill 名称差异。

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

原生扩展根目录使用 qwen-extension.json。名称应与扩展目录匹配，采用小写字母、数字与连字符，不用空格或下划线。

最小清单

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "node-server": {
      "command": "node",
      "args": ["${extensionPath}${/}dist${/}server.js"],
      "cwd": "${extensionPath}"
    }
  },
  "commands": "commands",
  "skills": "skills",
  "agents": "agents"
}

示例需有编译后的 dist/server.js。扩展 MCP 支持一般服务配置选项，但不支持 trust；settings.json 中同名服务优先于扩展服务。

能力字段

字段	内容
contextFileName	上下文文件；不写但根有 QWEN.md 时也会加载
commands	Markdown 命令目录，默认 commands
skills	Skill 目录，默认 skills
agents	YAML 或 Markdown agent 目录，默认 agents
workflows	目录或目录/JS 文件列表，默认 workflows
channels	名称到 entry 与可选 displayName 的映射
settings	安装时需要用户填写的环境设置

Channel entry 指向编译 JS，需导出符合 ChannelPlugin 接口的 plugin 对象。声明路径与实际分发文件应一致，不能仅提交 TypeScript 源文件却引用不存在的 dist。

变量

${extensionPath} 是扩展绝对路径，不解开 symlink；${workspacePath} 是当前工作区绝对路径；${/}、${pathSeparator} 为平台路径分隔符。使用这些变量避免写死作者机器上的安装目录。

环境设置

每项 settings 可声明 name、description、envVar、sensitive。用户安装时提供值，运行时以环境变量传给 MCP 服务。

qwen extensions settings set <extension-name> <setting-name> --scope user
qwen extensions settings set <extension-name> <setting-name> --scope workspace
qwen extensions settings list <extension-name>

用户设置适用所有项目，工作区设置优先；文档列出对应 .qwen/.env 的 home 与项目位置。敏感值在列表中不以明文展示；显示遮盖不能被当作所有落盘方式都有同样加密保证。

命令、Skill 与规则的名称

commands/deploy.md 默认提供 /deploy，嵌套 commands/gcs/sync.md 提供 /gcs:sync。与用户或项目命令冲突时，扩展命令优先级最低，改名如 /gcp.deploy。

Skill 则始终加所有者：gcp 扩展中的 pdf-processor 注册为 gcp:pdf-processor，文件内 name 不被改写。禁用可匹配裸名或注册名，启用授权使用完整注册名，详见Skill 发现。

扩展 rules 必须有 paths 条件，无 paths 会跳过并警告；已启用扩展的 QWEN.md 则进入每个请求，没有相关性筛选。长期上下文只放总是适用的少量信息，场景方法用 Skills 或条件规则，并用 /context detail 检查成本。