Gemini CLI 项目上下文文件 GEMINI.md 解析：构建、测试与开发规范全景指南

本文以 Gemini CLI 仓库根目录的 GEMINI.md 为主体，完整解析这份面向开发者（以及 AI Agent 本身）的项目上下文文档：它的定位与结构、monorepo 架构与七大工作区职责、构建与调试命令体系、分层测试与 preflight 质量门禁、开发/测试/文档三大约定。读完本文，你将能够独立完成该仓库的本地构建、按规范运行各类测试，并理解 ESLint 如何强制执行其中的硬性约定。

GEMINI.md 是什么：一份写给人和 Agent 的开发手册

GEMINI.md 位于仓库根目录（GEMINI.md），标题为 Gemini CLI Project Context。它是 Gemini CLI 加载进自身上下文的项目级说明文件，承担两个读者对象：

• AI Agent：当你在该仓库中用 Gemini CLI 协作开发时，这份文件会被自动注入上下文，告诉 Agent 如何构建、测试、遵循什么代码规范；
• 人类开发者：它浓缩了 CONTRIBUTING.md、package.json 脚本和 eslint.config.js 中的关键约束，是一张"上手地图"。

全文分五个部分：Project Overview（项目概览）、Building and Running（构建与运行）、Testing and Quality（测试与质量）、Development Conventions（开发约定）、Testing Conventions（测试约定），外加 Documentation（文档约定）。下文按此脉络逐项展开，并给出仓库内的对应证据。

项目概览：定位与技术栈

文档首先给出项目定位：

Gemini CLI 是一个开源 AI Agent，把 Gemini 的能力直接带入终端。它被设计为终端优先、可扩展、强大的开发者工具。

Purpose：为 Gemini 模型提供无缝的终端接口，支持代码理解、生成、自动化，以及通过 MCP（Model Context Protocol）集成。

Main Technologies（文档原文所列技术栈，均可在 package.json 中核对）：

技术	说明	仓库证据
Runtime	Node.js >= 20.0.0，开发推荐 ~20.19.0	package.json 的 engines.node 为 >=20.0.0
Language	TypeScript	根 typescript 5.8.3，各包使用 .ts/.tsx
UI Framework	React + Ink 用于 CLI 渲染	devDependencies 含 @types/react 19.2.0；overrides 与 dependencies 均将 ink 锁定为 fork 版 @jrichman/ink@6.6.9
Testing	Vitest	根依赖 vitest 3.2.4，各工作区测试脚本为 vitest run
Bundling	esbuild	根依赖 esbuild 0.25.0，配套 esbuild.config.js
Lint/Format	ESLint、Prettier	eslint 9.24.0、prettier 3.5.3

架构上，文档明确这是基于 npm workspaces 的 monorepo——package.json 中 "workspaces": ["packages/*"] 与之对应。

Monorepo 七大工作区

文档列出了每个包的职责，逐一核实其 npm 包名如下：

目录	包名	职责（文档原文）
packages/cli	@google/gemini-cli	面向用户的终端 UI、输入处理与显示渲染
packages/core	@google/gemini-cli-core	后端逻辑、Gemini API 编排、提示词构建、工具执行
packages/a2a-server	@google/gemini-cli-a2a-server	实验性的 Agent-to-Agent 服务器
packages/sdk	@google/gemini-cli-sdk	以编程方式嵌入 Gemini CLI 能力的 SDK
packages/devtools	@google/gemini-cli-devtools	内置开发者工具（Network/Console 检查器）
packages/test-utils	@google/gemini-cli-test-utils	共享测试工具与 test rig
packages/vscode-ide-companion	gemini-cli-vscode-ide-companion	与 CLI 配对的 VS Code 扩展

从源码结构看，cli、core、a2a-server、sdk、test-utils 五个包的构建脚本统一指向根目录的 scripts/build_package.js，而 devtools 走 tsc 编译、vscode-ide-companion 走 npm run build:dev，这种差异化配置正好解释了后面 build:all 命令的三步拆解。

构建与运行：命令与底层脚本的对应关系

文档的 Building and Running 一节列出六条核心命令。结合 package.json 的 scripts 段（L19-L79），可以看清每条命令背后实际执行的流程：

npm install          # 安装依赖
npm run build:all    # 构建全部：packages + sandbox + VS Code companion
npm run build        # 仅构建 packages
npm run start        # 开发模式运行
npm run debug        # 调试模式运行（启用 Node.js inspector）
npm run bundle       # 打包项目
npm run clean        # 清理产物

实际脚本实现：

• start（package.json）：cross-env NODE_ENV=development node scripts/start.js——以开发环境变量启动 scripts/start.js；仓库还提供 start:prod（NODE_ENV=production）用于按生产模式运行。
• debug（package.json）：cross-env DEBUG=1 node --inspect-brk scripts/start.js——--inspect-brk 会在入口断点处暂停，等待调试器（如 Chrome DevTools）接入。
• build（package.json）：执行 node scripts/build.js 构建各包。
• build:all（package.json）：npm run build && npm run build:sandbox && npm run build:vscode——即文档所称"Builds packages, sandbox, and VS Code companion"的三步组合，分别对应 scripts/build_sandbox.js 与 scripts/build_vscode_companion.js。
• bundle（package.json）：先执行 npm run generate 生成提交信息，再构建 devtools 包、构建 core 的 browser-mcp，最后依次运行 node esbuild.config.js 与 node scripts/copy_bundle_assets.js 完成单文件打包与资产拷贝。根 bin 字段声明 "gemini": "bundle/gemini.js"，说明 bundle 产物就是最终发布的可执行入口。
• clean（package.json）：执行 node scripts/clean.js 清理构建产物。
• 另有一条 prepare 钩子（package.json）：husky && npm run bundle，即 npm install 完成后会自动安装 git hooks 并触发一次 bundle——这也是"安装依赖"步骤隐含成本的一部分。

测试与质量：从单元到夜线回归的分层体系

文档的 Testing and Quality 一节是该文件信息密度最高的部分，定义了五层测试命令，每层在 package.json 中都有精确落点。

1. 单元测试（全量）

npm run test

对应脚本（package.json）：npm run test --workspaces --if-present && npm run test:sea-launch——遍历所有含 test 脚本的工作区运行 vitest run，再执行 SEA（Single Executable Application）启动测试 vitest run sea/sea-launch.test.js。注意还有一条 posttest 钩子会在测试后自动 npm run build。

2. 集成测试（E2E）

npm run test:e2e

对应脚本（package.json）：cross-env VERBOSE=true KEEP_OUTPUT=true npm run test:integration:sandbox:none，即在无沙箱模式下运行 integration-tests/ 目录下的 vitest（GEMINI_SANDBOX=false vitest run --root ./integration-tests）。仓库还提供了 test:integration:sandbox:docker / :podman 变体，可分别用 Docker 或 Podman 沙箱执行同一套集成用例。

3. 内存与性能回归（仅夜线，勿本地盲跑）

文档在这里给出了一条带引用块的醒目提示：

NOTE: Please run the memory and perf tests locally only if you are implementing changes related to those test areas. Otherwise skip these tests locally and rely on CI to run them on nightly builds.

• Memory（夜线）：npm run test:memory——运行内存回归测试并对比基线。从源码结构看，测试位于 memory-tests/ 目录，配合 baselines.json 做基线比对；另有 test:memory:update-baselines（设置 UPDATE_MEMORY_BASELINES=true）用于刷新基线。该测试被排除在 preflight 之外，由夜线 CI 执行。
• Performance（夜线）：npm run test:perf——CPU 性能回归测试，同样对比基线（perf-tests/ 目录含 baselines.json 与 UPDATE_PERF_BASELINES 刷新开关），同样排除在 preflight 之外、夜线运行。

4. 工作区定向测试

npm test -w <pkg> -- <path>

文档特别强调 <path> 必须相对于工作区根目录，并给出官方示例：

npm test -w @google/gemini-cli-core -- src/routing/modelRouterService.test.ts

这一条是日常迭代效率的关键：改一个文件，就只跑它对应的测试文件，而不是全仓 npm run test。

5. preflight：提交 PR 前的完整校验

npm run preflight

文档将其定性为"Heaviest check"，并在 package.json 中可以看到完整执行链：

npm run clean && npm ci && npm run format && npm run build && npm run lint:ci && npm run typecheck && npm run test:ci

即依次执行：清理 → 干净安装依赖 → 格式化 → 构建 → CI 级 lint → 类型检查 → CI 级测试。文档还给出了两条重要的使用策略（原文建议，值得直接照搬）：

1. 只在实现任务的最末尾运行一次——因为它耗时最长；
2. 失败时用更轻的命令快速迭代——先跑 npm run test、npm run lint 或工作区定向测试定位问题，修好后再重跑 preflight；
3. 纯文档/提示词类改动可跳过，等待 PR 的 CI 校验即可。

typecheck 本身（package.json）会先对每个含该脚本的工作区做 tsc 检查，再额外编译 evals、integration-tests、memory-tests 三个目录的 tsconfig，说明顶层测试目录也在类型门禁范围内。

单项检查

npm run lint        # ESLint（--max-warnings 0，零警告容忍）
npm run format      # Prettier 全仓格式化
npm run typecheck   # 全工作区 TypeScript 类型检查

其中 lint 脚本（package.json）显式加了 NODE_OPTIONS="--max-old-space-size=8192"，侧面反映了这个 monorepo 做类型感知 lint 时的内存开销。

开发约定：从 CLA 到 License Header 的硬约束

Development Conventions 一节列出了五条约定，其中三条有可执行的仓库证据。

1. 贡献流程：遵循 CONTRIBUTING.md，需签署 Google CLA。该文档要求按"找 issue → fork 建分支 → 在 packages/ 中修改 → 跑 npm run preflight → 开 PR"的流程提交，并强调所有 PR 需经 code review，且项目提供了自动评审工具（./scripts/review.sh <PR_NUMBER> [model]）。

2. Pull Request 纪律：PR 保持小而聚焦，且必须关联已存在的 issue。原文有一句强制要求："Always activate the pr-creator skill for PR generation, even when using the gh CLI." 仓库内确实存在该技能文件 .gemini/skills/pr-creator/SKILL.md，其工作流规定了：确认不在 main 分支上 → 按 type(scope): description 格式提交 → 查找并严格遵循 .github 下的 PR 模板 → 描述草稿保留模板全部标题与清单 → 创建 PR 前运行 npm run preflight。

3. 提交信息：遵循 Conventional Commits 规范（feat、fix、docs 等 type(scope) 前缀）。

4. 导入规则：使用具名导入，避免包间的受限相对导入，由 ESLint 强制。在 eslint.config.js 中可以看到 'import/no-relative-packages': 'error'，且对每个包分别配置了 no-restricted-imports：core 内禁止自引用 @google/gemini-cli-core、cli 内禁止自引用 @google/gemini-cli、sdk 内禁止自引用 @google/gemini-cli-sdk——一律要求包内使用相对导入（eslint.config.js）。

5. License Header：所有新的 .ts、.tsx、.js 源文件必须包含当年的 Apache-2.0 许可头（如 Copyright 2026 Google LLC），由 ESLint 强制。这条规则的实现位于 eslint.config.js 的 headers/header-format 规则：

'headers/header-format': [
  'error',
  {
    source: 'string',
    content: [
      '@license',
      'Copyright (year) Google LLC',
      'SPDX-License-Identifier: Apache-2.0',
    ].join('\n'),
    patterns: {
      year: {
        pattern: `202[5-${currentYear.toString().slice(-1)}]`,
        defaultValue: currentYear.toString(),
      },
    },
  },
]

即文件头必须是 @license + Copyright (年份) Google LLC + SPDX-License-Identifier: Apache-2.0 三行结构，年份用正则动态匹配当前年份段，避免硬编码过期。

测试约定：环境变量用 vi.stubEnv 而不是改 process.env

Testing Conventions 一节给出了本仓库测试环境变量的唯一正确姿势，这条规则直接影响你能否写出符合 CI 预期的测试：

When testing code that depends on environment variables, use vi.stubEnv('NAME', 'value') in beforeEach and vi.unstubAllEnvs() in afterEach. Avoid modifying process.env directly as it can lead to test leakage and is less reliable.

标准写法：

beforeEach(() => {
  vi.stubEnv('MY_VAR', 'value');
});

afterEach(() => {
  vi.unstubAllEnvs();
});

要点有二：

• 直接改 process.env 会导致测试间泄漏（leakage）且不可靠，必须避免；
• 要"取消设置"某个变量时，用空字符串 vi.stubEnv('NAME', '') 代替 delete。

这一约定的存在与 lint 配置相互印证：eslint.config.js 对 packages/*/src/**/*.test.{ts,tsx} 统一启用了 @vitest/eslint-plugin 的 recommended 规则，把 Vitest 最佳实践纳入了静态检查。

文档约定：docs-writer 技能与 docs/ 目录

文档最后一部分约定了三条文档规则：

1. 凡是被要求撰写、编辑或评审任何文档时，一律启用 docs-writer 技能；
2. 文档统一位于 docs/ 目录（含 CLI 教程、核心概念、扩展与 Hooks 编写指南、参考手册等完整结构）；
3. 当代码变更使现有文档过时或不完整时，应主动建议更新文档。

技能文件 .gemini/skills/docs-writer/SKILL.md 定义了具体的写作标准：面向全球读者的美式英语、主动语态与现在时、区分硬性要求（must）与建议（we recommend）、避免行话与营销腔，并要求内容严格反映当前代码库。仓库内与本地开发相关的文档还包括 docs/local-development.md（本地 tracing 与遥测调试指南），可与 GEMINI.md 的命令体系配合使用。

快速参考清单

场景	命令 / 动作
首次上手	npm install（会自动触发 prepare → bundle）
全量构建	npm run build:all
开发运行 / 调试	npm run start / npm run debug
日常迭代测试	npm test -w @google/gemini-cli-core -- src/<file>.test.ts
单元全量 / E2E	npm run test / npm run test:e2e
提交 PR 前	npm run preflight（任务末尾跑一次）
新增源文件	顶部加 @license / Copyright (year) Google LLC / SPDX-License-Identifier: Apache-2.0
写测试涉及环境变量	beforeEach 中 vi.stubEnv，afterEach 中 vi.unstubAllEnvs()
开 PR	关联 issue，启用 pr-creator 技能

GEMINI.md 的价值在于把"这个仓库如何构建、如何验证、按什么规范写代码"压缩进一个可被 Agent 自动消费的上下文文件：命令层面与 package.json 的脚本一一对应，规范层面与 eslint.config.js 的强制规则互相咬合。掌握这份文件，等于同时拿到了该项目的构建地图、质量门禁地图和协作规则地图。