# 原生扩展 Manifest 与设置

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

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

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

## 最小清单

```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 服务。

```bash
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 发现](https://funcoding.ai/agents/qwen-code/customize/skill-discovery/)。

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