# 扩展 Manifest 与用户设置

> 编写 gemini-extension.json，使用可移植路径并声明敏感配置。

- 网址：https://funcoding.ai/agents/gemini-cli/build/extensions-manifest/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Gemini CLI 官方文档：Extension reference](https://geminicli.com/docs/extensions/reference)、[Gemini CLI 官方文档：Build extensions](https://geminicli.com/docs/extensions/writing-extensions)

---
gemini-extension.json 位于扩展根，定义名称、版本、能力与用户设置。JSON 中不要使用教程省略号或注释作为真实值。

## 最小 MCP Manifest

```json
{
  "name": "my-extension",
  "version": "1.0.0",
  "description": "Project tools and workflows",
  "mcpServers": {
    "project-tools": {
      "command": "node",
      "args": ["${extensionPath}${/}dist/server.js"],
      "cwd": "${extensionPath}"
    }
  }
}
```

需要真实 dist/server.js 和依赖。name 使用小写、数字和连字符，避免空格或下划线，并与扩展目录名一致。

## 路径变量

`${extensionPath}` 是扩展绝对路径，`${workspacePath}` 是当前工作区绝对路径，`${/}` 是平台分隔符。这些变量支持 manifest 与 hooks/hooks.json，便于扩展安装到不同位置。

MCP 的 command 与 args 分开填写。扩展内 MCP 不支持 trust 字段；同名 settings.json 服务具有更高优先级，并按[MCP 覆盖规则](https://funcoding.ai/agents/gemini-cli/build/mcp-configuration/)合并。

## 上下文与计划

contextFileName 指定扩展上下文文件；未设置但根目录存在 GEMINI.md 时仍会加载。内容应保持简洁，因为扩展激活的会话会持续获得这些背景。

plan.directory 是用户未配置计划目录时的回退；两者均未设置时使用 `~/.gemini/tmp/<project>/<session-id>/plans/`。换计划路径不代替对应写入策略。

## 用户设置

```json
{
  "name": "my-extension",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "Credential for the project service",
      "envVar": "MY_SERVICE_API_KEY",
      "sensitive": true
    }
  ]
}
```

安装时收集设置，普通值保存在扩展目录 `.env`；官方说明 sensitive true 值进入系统 keychain 并在 UI 遮蔽。运行时以 envVar 注入，更新入口为 `gemini extensions config <name> [setting] [--scope <scope>]`。

扩展指南要求通过 settings 声明所需变量，不要依赖完整宿主环境继承；其“默认脱敏”概述与通用 Schema 存在差异，本页不承诺未声明变量在所有版本绝不传入。

## 主题

themes 数组可提供 custom 主题，含背景、文字、状态、边框和 UI 色值。选择时用 `/theme` 或 ui.theme，名称带扩展后缀，例如 `shades-of-green (my-green-extension)`。不要把主题名称冲突当作安装失败。