Gemini CLI 扩展参考gemini extensions命令与gemini-extension.json清单全解析【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文系统讲解 Gemini CLI 扩展机制的两大核心终端下的gemini extensions命令组安装、卸载、启用/禁用、更新、模板创建、本地链接、配置以及gemini-extension.json清单文件的完整字段语义并结合仓库源码印证加载流程、设置存储.env与系统钥匙串与变量替换的底层实现。读完后你可以独立完成扩展的全生命周期管理并能构建包含 MCP 服务器、自定义命令、Hooks、Skills、策略与主题的完整扩展包。命令组总览与使用边界gemini extensions命令组是管理扩展的唯一终端入口涵盖安装、卸载、禁用/启用、更新、配置、新建与本地链接等操作。在使用前需要明确两个使用边界原文档明确说明交互式模式内不支持管理类命令gemini extensions install等管理命令只能在 CLI 外部执行进入交互式会话后只能通过/extensions list查看已安装的扩展。配置变更需重启会话生效所有管理操作包括对斜杠命令的更新只有在重启 CLI 会话后才生效。安装扩展install安装时提供 GitHub 仓库 URL 或本地文件路径gemini extensions install source [--ref ref] [--auto-update] [--pre-release] [--consent] [--skip-settings]参数说明source扩展的 GitHub URL 或本地路径。--ref要安装的 git 引用分支、标签或提交。--auto-update为该扩展启用自动更新。--pre-release允许安装预发布版本。--consent确认了解安全风险跳过确认提示。--skip-settings跳过安装时的配置settings 填写流程。关键行为说明与 install.ts 的实现对应安装的是副本不是引用Gemini CLI 在安装时会创建扩展的副本后续要从源仓库拉取变更必须执行gemini extensions update。从 GitHub 安装要求本机装有git。本地安装会触发信任检查从源码看当源类型为local或link时handleInstall会调用isWorkspaceTrusted判断目录是否受信未受信时执行FolderTrustDiscoveryService.discover向用户列出该目录包含的自定义命令、MCP 服务器、Hooks、Skills、Agents 与设置覆盖项并展示发现错误与安全警告用户确认后才会将该目录写入受信列表并继续安装。--consent的行为跳过交互式确认提示但仍会把INSTALL_WARNING_MESSAGE记入调试日志这是面向自动化脚本的选项请自行确认安全影响。--skip-settings的行为源码中它把requestSetting回调置为null即安装过程中不再交互式询问 manifest 里声明的 settings如 API key。卸载扩展uninstallgemini extensions uninstall name...支持一次传入多个扩展名批量卸载。禁用扩展disable扩展默认在全局范围内启用可以整体禁用也可以只针对特定工作区禁用gemini extensions disable name [--scope scope]name要禁用的扩展名。--scope禁用作用域取值为user或workspace。启用扩展enable重新启用已禁用的扩展gemini extensions enable name [--scope scope]参数与disable完全对称name为扩展名--scope取user或workspace。更新扩展update将扩展更新到其gemini-extension.json中指定的版本gemini extensions update name一次性更新所有已安装扩展gemini extensions update --all从模板创建扩展newgemini extensions new path [template]path要创建的目录。[template]使用的模板文档示例给出mcp-server、context、custom-commands。从源码new.ts可以看到两个实现细节模板取自内置的examples目录当前仓库内置的模板包括custom-commands、exclude-tools、hooks、mcp-server、policies、skills、themes-example见 examples 目录yargs 通过choices限定合法模板名。如果不指定模板命令会创建一个空目录并写入一份最小清单{name: 目录名, version: 1.0.0}随后提示用gemini extensions link path进行测试。本地链接扩展link在开发目录与 Gemini CLI 扩展目录之间创建符号链接让你无需重新安装即可立即测试改动gemini extensions link path开发工作流推荐组合gemini extensions new或手写目录→ 开发 →gemini extensions link热测试。配置扩展设置config更新扩展的用户设置详见下文“扩展设置”一节gemini extensions config name [setting] [--scope scope]结合 configure.ts 的实现可以补充三点--scope取值为user或workspace默认user。[setting]可传设置的显示名name或环境变量名envVar二者皆可匹配。该功能受实验开关保护settings.json中experimental.extensionConfig置为false时命令会直接报错退出默认开启。命令会拒绝包含路径分隔符或..的扩展名防止路径穿越。扩展格式与加载机制Gemini CLI 从home/.gemini/extensions目录加载扩展每个扩展的根目录必须包含一个gemini-extension.json文件。从源码看该目录由 storage.ts 中的ExtensionStorage.getUserExtensionsDir()解析而每个扩展目录内还会额外存放两类文件.gemini-extension-install.json安装元数据记录来源类型、ref 等供update与migratedTo迁移逻辑使用.env非敏感设置的值文件见“扩展设置”一节。gemini-extension.json完整示例{ name: my-extension, version: 1.0.0, description: My awesome extension, mcpServers: { my-server: { command: node, args: [${extensionPath}/my-server.js], cwd: ${extensionPath} } }, contextFileName: GEMINI.md, excludeTools: [run_shell_command], migratedTo: https://github.com/new-owner/new-extension-repo, plan: { directory: .gemini/plans } }字段说明name扩展名称用于唯一标识扩展并在扩展命令与用户/项目命令同名时参与冲突消解。命名要求为小写字母或数字用连字符代替下划线或空格该名称应扩展目录名保持一致用户也将以此名称在 CLI 中引用你的扩展。version扩展版本。description扩展的简短描述会展示在扩展画廊中。migratedTo扩展迁移后的新仓库源 URL。设置后CLI 会自动检查新源的更新并在发现更新时将扩展安装迁移到新源。mcpServersMCP 服务器映射键为服务器名值为服务器配置。这些服务器在启动时加载行为等同于 settings.json 中定义的 MCP 服务器。注意若扩展与settings.json定义了同名的 MCP 服务器settings.json中的定义优先除trust外所有 MCP 服务器配置项均受支持为可移植性引用扩展目录内文件时应使用${extensionPath}可执行文件与参数应分别放在command与args中不要都塞进command。contextFileName包含扩展上下文的文件名从扩展目录加载。若不声明该属性但扩展目录中存在GEMINI.md则该文件会被自动加载。excludeTools要从模型中排除的工具名数组。支持对部分工具做命令级限制例如excludeTools: [run_shell_command(rm -rf)]会拦截rm -rf命令。注意这与 MCP 服务器配置中列出的excludeTools功能不同。plan规划功能配置。plan.directory规划产物存储目录用户未在工作区设置中指定时作为回退。若扩展与用户都未指定默认为~/.gemini/tmp/project/session-id/plans/。对应的磁盘结构类型定义见 extension.ts 中的ExtensionConfig接口name、version、mcpServers、contextFileName、excludeTools、settings、themes、plan、migratedTo。启动时 Gemini CLI 会加载所有扩展并合并其配置如有冲突工作区配置优先。扩展设置Settings扩展可以在安装时要求用户提供设置如 API key 或 URL。这些值存储在扩展目录内的.env文件中。在清单中添加settings数组来声明{ name: my-api-extension, version: 1.0.0, settings: [ { name: API Key, description: Your API key for the service., envVar: MY_API_KEY, sensitive: true } ] }字段说明name设置的显示名。description设置的清晰说明。envVar值所存储的环境变量名。sensitive为true时值存入系统钥匙串并在 UI 中做掩码处理。extensionSettings.ts 的实现进一步揭示了存储细节敏感与非敏感分流存储sensitive: true的值经KeychainTokenStorage写入系统钥匙串键名形如Gemini CLI Extensions 扩展名 extensionIdworkspace 作用域还会追加工作区目录非敏感值写入.env文件且.env内容会经过校验——变量名必须匹配^[a-zA-Z_][a-zA-Z0-9_]*$值不能包含换行。作用域user 作用域的.env位于扩展目录内home/.gemini/extensions/name/.envworkspace 作用域则写入workspaceDir/.env。getEnvContents合并两者时workspace 值覆盖 user 值。设置变更的增量同步getSettingsChanges会对比新旧 settings 清单对新增项提问、对移除项从.env/钥匙串中清理升级扩展时不会留下过期密钥。环境变量清洗Security 机制出于安全考虑敏感环境变量默认会被过滤不会传递给扩展或 MCP 服务器。扩展不会继承用户完整的 shell 环境变量它们只能访问标准的安全变量如HOME、PATH、TMPDIR在gemini-extension.json的settings数组中通过envVar显式声明并请求的变量。因此如果扩展需要特定的环境变量API key、自定义主机名、配置路径等必须在settings数组中声明CLI 才会将其加入白名单供扩展使用。这是编写扩展时最容易被忽略的一条硬性约束。扩展可提供的能力清单自定义命令在扩展的commands/子目录中放置 TOML 文件即可提供自定义命令命令名由目录结构决定。以扩展gcp为例commands/deploy.toml→/deploycommands/gcs/sync.toml→/gcs:sync用冒号命名空间Hooks通过 hooks 拦截并自定义 CLI 行为。注意 Hooks不定义在gemini-extension.json中而是放在扩展目录的hooks/hooks.json文件里。Agent Skills通过打包 agent skills 提供专门化工作流将技能定义放入skills/目录。例如skills/security-audit/SKILL.md会暴露一个security-audit技能。子代理预览功能子代理Sub-agents目前为预览功能仍在积极开发中。在扩展根目录添加agents/目录放入代理定义文件.md即可向用户暴露可委派任务的子代理。策略引擎Policy Engine扩展可以为 Gemini CLI 的 策略引擎 贡献策略规则与安全校验器规则定义在.toml文件中在扩展激活时生效。在扩展根目录创建policies/目录并放入.toml策略文件即可CLI 会自动加载其中所有.toml。扩展贡献的规则运行在独立的 tier 2 层级与工作区策略同层优先级高于默认规则但低于用户或管理员策略。安全警告出于安全考虑Gemini CLI 会忽略扩展策略中的任何allow决策与yolo模式配置确保扩展无法在未经确认的情况下自动批准工具调用或绕过安全措施。policies.toml示例[[rule]] mcpName my_server toolName dangerous_tool decision ask_user priority 100 [[safety_checker]] mcpName my_server toolName write_data priority 200 [safety_checker.checker] type in-process name allowed-path required_context [environment]主题扩展可以在gemini-extension.json的themes数组中提供自定义主题{ name: my-green-extension, version: 1.0.0, themes: [ { name: shades-of-green, type: custom, background: { primary: #1a362a }, text: { primary: #a6e3a1, secondary: #6e8e7a, link: #89e689 }, status: { success: #76c076, warning: #d9e689, error: #b34e4e }, border: { default: #4a6c5a }, ui: { comment: #6e8e7a } } ] }扩展主题可通过/theme命令或settings.json中的ui.theme属性选择。引用扩展主题时主题名后以括号附带扩展名例如shades-of-green (my-green-extension)。冲突消解扩展命令的优先级最低。当扩展命令名与用户或项目命令冲突时扩展命令会以扩展名前缀点号分隔呈现例如/gcp.deploy。变量替换Gemini CLI 在gemini-extension.json与hooks/hooks.json中支持变量替换变量说明${extensionPath}扩展目录的绝对路径。${workspacePath}当前工作区的绝对路径。${/}平台相关的路径分隔符。从 variables.ts 的实现可以看到其工作原理hydrateString用正则/\${(.*?)}/g扫描字符串并替换已定义的变量recursivelyHydrateStrings递归处理整个 JSON 对象包括嵌套数组与对象替换发生在扩展清单装载阶段。此外递归水合时通过UNMARSHALL_KEY_IGNORE_LIST显式丢弃__proto__、constructor、prototype三个键防御原型污染validateVariables则保证必填变量缺失时提前报错。${/}的使用可以跨平台安全地拼接command/args中的本地脚本路径例如${extensionPath}${/}bin${/}server.js。延伸阅读从零构建第一个扩展构建扩展指南安全与可靠性实践扩展最佳实践扩展概览与画廊入口扩展总览命令与设置定义示例参考 examples 目录 中的mcp-server、hooks、policies等模板。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考