扩展 Manifest 与用户设置

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

最小 MCP Manifest

{
  "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 覆盖规则合并。

上下文与计划

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

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

用户设置

{
  "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)。不要把主题名称冲突当作安装失败。