Gemini CLI 项目上下文文件 GEMINI.md 解析构建、测试与开发规范全景指南【免费下载链接】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.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 模型提供无缝的终端接口支持代码理解、生成、自动化以及通过 MCPModel Context Protocol集成。Main Technologies文档原文所列技术栈均可在 package.json 中核对技术说明仓库证据RuntimeNode.js 20.0.0开发推荐 ~20.19.0package.json的engines.node为20.0.0LanguageTypeScript根typescript5.8.3各包使用.ts/.tsxUI FrameworkReact Ink 用于 CLI 渲染devDependencies含types/react19.2.0overrides与dependencies均将ink锁定为 fork 版jrichman/ink6.6.9TestingVitest根依赖vitest3.2.4各工作区测试脚本为vitest runBundlingesbuild根依赖esbuild0.25.0配套 esbuild.config.jsLint/FormatESLint、Prettiereslint9.24.0、prettier3.5.3架构上文档明确这是基于 npm workspaces 的 monorepo——package.json中workspaces: [packages/*]与之对应。Monorepo 七大工作区文档列出了每个包的职责逐一核实其 npm 包名如下目录包名职责文档原文packages/cligoogle/gemini-cli面向用户的终端 UI、输入处理与显示渲染packages/coregoogle/gemini-cli-core后端逻辑、Gemini API 编排、提示词构建、工具执行packages/a2a-servergoogle/gemini-cli-a2a-server实验性的 Agent-to-Agent 服务器packages/sdkgoogle/gemini-cli-sdk以编程方式嵌入 Gemini CLI 能力的 SDKpackages/devtoolsgoogle/gemini-cli-devtools内置开发者工具Network/Console 检查器packages/test-utilsgoogle/gemini-cli-test-utils共享测试工具与 test rigpackages/vscode-ide-companiongemini-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 # 清理产物实际脚本实现startpackage.jsoncross-env NODE_ENVdevelopment node scripts/start.js——以开发环境变量启动 scripts/start.js仓库还提供start:prodNODE_ENVproduction用于按生产模式运行。debugpackage.jsoncross-env DEBUG1 node --inspect-brk scripts/start.js——--inspect-brk会在入口断点处暂停等待调试器如 Chrome DevTools接入。buildpackage.json执行node scripts/build.js构建各包。build:allpackage.jsonnpm 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。bundlepackage.json先执行npm run generate生成提交信息再构建 devtools 包、构建 core 的 browser-mcp最后依次运行node esbuild.config.js与node scripts/copy_bundle_assets.js完成单文件打包与资产拷贝。根bin字段声明gemini: bundle/gemini.js说明 bundle 产物就是最终发布的可执行入口。cleanpackage.json执行node scripts/clean.js清理构建产物。另有一条prepare钩子package.jsonhusky npm run bundle即npm install完成后会自动安装 git hooks 并触发一次 bundle——这也是安装依赖步骤隐含成本的一部分。测试与质量从单元到夜线回归的分层体系文档的Testing and Quality一节是该文件信息密度最高的部分定义了五层测试命令每层在 package.json 中都有精确落点。1. 单元测试全量npm run test对应脚本package.jsonnpm run test --workspaces --if-present npm run test:sea-launch——遍历所有含test脚本的工作区运行vitest run再执行 SEASingle Executable Application启动测试vitest run sea/sea-launch.test.js。注意还有一条posttest钩子会在测试后自动npm run build。2. 集成测试E2Enpm run test:e2e对应脚本package.jsoncross-env VERBOSEtrue KEEP_OUTPUTtrue npm run test:integration:sandbox:none即在无沙箱模式下运行 integration-tests/ 目录下的 vitestGEMINI_SANDBOXfalse vitest run --root ./integration-tests。仓库还提供了test:integration:sandbox:docker/:podman变体可分别用 Docker 或 Podman 沙箱执行同一套集成用例。3. 内存与性能回归仅夜线勿本地盲跑文档在这里给出了一条带引用块的醒目提示NOTE: Please run the memory and perf tests locallyonly ifyou 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_BASELINEStrue用于刷新基线。该测试被排除在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 级测试。文档还给出了两条重要的使用策略原文建议值得直接照搬只在实现任务的最末尾运行一次——因为它耗时最长失败时用更轻的命令快速迭代——先跑npm run test、npm run lint或工作区定向测试定位问题修好后再重跑preflight纯文档/提示词类改动可跳过等待 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-size8192侧面反映了这个 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 thepr-creatorskill for PR generation, even when using theghCLI.仓库内确实存在该技能文件 .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-importscore内禁止自引用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(), }, }, }, ]即文件头必须是licenseCopyright (年份) Google LLCSPDX-License-Identifier: Apache-2.0三行结构年份用正则动态匹配当前年份段避免硬编码过期。测试约定环境变量用vi.stubEnv而不是改process.envTesting Conventions一节给出了本仓库测试环境变量的唯一正确姿势这条规则直接影响你能否写出符合 CI 预期的测试When testing code that depends on environment variables, usevi.stubEnv(NAME, value)inbeforeEachandvi.unstubAllEnvs()inafterEach. Avoid modifyingprocess.envdirectly 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/目录文档最后一部分约定了三条文档规则凡是被要求撰写、编辑或评审任何文档时一律启用docs-writer技能文档统一位于 docs/ 目录含 CLI 教程、核心概念、扩展与 Hooks 编写指南、参考手册等完整结构当代码变更使现有文档过时或不完整时应主动建议更新文档。技能文件 .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单元全量 / E2Enpm run test/npm run test:e2e提交 PR 前npm run preflight任务末尾跑一次新增源文件顶部加license / Copyright (year) Google LLC / SPDX-License-Identifier: Apache-2.0写测试涉及环境变量beforeEach中vi.stubEnvafterEach中vi.unstubAllEnvs()开 PR关联 issue启用pr-creator技能GEMINI.md的价值在于把这个仓库如何构建、如何验证、按什么规范写代码压缩进一个可被 Agent 自动消费的上下文文件命令层面与 package.json 的脚本一一对应规范层面与 eslint.config.js 的强制规则互相咬合。掌握这份文件等于同时拿到了该项目的构建地图、质量门禁地图和协作规则地图。【免费下载链接】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），仅供参考