diff --git a/README.md b/README.md index 20813de..4fc4721 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,66 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/google-gemini/gemini-cli) · [上游 README](https://github.com/google-gemini/gemini-cli/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # Gemini CLI [![Gemini CLI CI](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml) -[![Gemini CLI E2E (Chained)](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml) -[![Version](https://img.shields.io/npm/v/@google/gemini-cli)](https://www.npmjs.com/package/@google/gemini-cli) -[![License](https://img.shields.io/github/license/google-gemini/gemini-cli)](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE) -[![View Code Wiki](https://assets.codewiki.google/readme-badge/static.svg)](https://codewiki.google/github.com/google-gemini/gemini-cli?utm_source=badge&utm_medium=github&utm_campaign=github.com/google-gemini/gemini-cli) +[![Gemini CLI E2E（链式）](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml/badge.svg)](https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml) +[![版本](https://img.shields.io/npm/v/@google/gemini-cli)](https://www.npmjs.com/package/@google/gemini-cli) +[![许可证](https://img.shields.io/github/license/google-gemini/gemini-cli)](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE) +[![查看代码 Wiki](https://assets.codewiki.google/readme-badge/static.svg)](https://codewiki.google/github.com/google-gemini/gemini-cli?utm_source=badge&utm_medium=github&utm_campaign=github.com/google-gemini/gemini-cli) -![Gemini CLI Screenshot](/docs/assets/gemini-screenshot.png) +![Gemini CLI 截图](/docs/assets/gemini-screenshot.png) -Gemini CLI is an open-source AI agent that brings the power of Gemini directly -into your terminal. It provides lightweight access to Gemini, giving you the -most direct path from your prompt to our model. +Gemini CLI 是一个开源 AI 代理，将 Gemini 的强大能力直接带到您的终端。它提供轻量级访问 Gemini 的途径，为您提供从提示到模型的最直接路径。 -Learn all about Gemini CLI in our [documentation](https://geminicli.com/docs/). +在[文档](https://geminicli.com/docs/).)中了解 Gemini CLI 的全部内容。 -## 🚀 Why Gemini CLI? +## 🚀 为什么选择 Gemini CLI？ -- **🎯 Free tier**: 60 requests/min and 1,000 requests/day with personal Google - account. -- **🧠 Powerful Gemini 3 models**: Access to improved reasoning and 1M token - context window. -- **🔧 Built-in tools**: Google Search grounding, file operations, shell - commands, web fetching. -- **🔌 Extensible**: MCP (Model Context Protocol) support for custom - integrations. -- **💻 Terminal-first**: Designed for developers who live in the command line. -- **🛡️ Open source**: Apache 2.0 licensed. +- **🎯 免费使用额度**：使用个人 Google 账号即可享受每分钟 60 次请求和每日 1,000 次请求。 +- **🧠 强大的 Gemini 3 模型**：访问改进的推理能力和 100 万 token 上下文窗口。 +- **🔧 内置工具**：Google 搜索验证、文件操作、Shell 命令、网页抓取。 +- **🔌 可扩展**：支持 MCP（模型上下文协议）以实现自定义集成。 +- **💻 终端优先**：为命令行开发者量身打造。 +- **🛡️ 开源**：基于 Apache 2.0 许可证。 -## 📦 Installation +## 📦 安装 -See -[Gemini CLI installation, execution, and releases](https://www.geminicli.com/docs/get-started/installation) -for recommended system specifications and a detailed installation guide. +请参阅 +[Gemini CLI 安装、运行与版本发布](https://www.geminicli.com/docs/get-started/installation)) +了解推荐系统规格和详细的安装指南。 -### Quick Install +### 快速安装 -#### Run instantly with npx +#### 使用 npx 立即运行 ```bash # Using npx (no installation required) npx @google/gemini-cli ``` -#### Install globally with npm +#### 使用 npm 全局安装 ```bash npm install -g @google/gemini-cli ``` -#### Install globally with Homebrew (macOS/Linux) +#### 使用 Homebrew 全局安装（macOS/Linux） ```bash brew install gemini-cli ``` -#### Install globally with MacPorts (macOS) +#### 使用 MacPorts 全局安装（macOS） ```bash sudo port install gemini-cli ``` -#### Install with Anaconda (for restricted environments) +#### 使用 Anaconda 安装（受限环境） ```bash # Create and activate a new environment @@ -71,103 +71,90 @@ conda activate gemini_env npm install -g @google/gemini-cli ``` -## Release Channels +## 发布渠道 -See [Releases](https://www.geminicli.com/docs/changelogs) for more details. +详见[版本发布](https://www.geminicli.com/docs/changelogs))。 -### Preview +### 预览版 -New preview releases will be published each week at UTC 23:59 on Tuesdays. These -releases will not have been fully vetted and may contain regressions or other -outstanding issues. Please help us test and install with `preview` tag. +每周二 UTC 23:59 发布新的预览版。这些版本未经全面验证，可能包含退化或其他未解决的问题。请帮助我们测试，并使用 ``preview`` 标签安装。 ```bash npm install -g @google/gemini-cli@preview ``` -### Stable +### 稳定版 -- New stable releases will be published each week at UTC 20:00 on Tuesdays, this - will be the full promotion of last week's `preview` release + any bug fixes - and validations. Use `latest` tag. +- 每周二 UTC 20:00 发布新的稳定版，即上周 ``preview`` 版本的完整升级，包含所有 Bug 修复和验证。使用 ``latest`` 标签。 ```bash npm install -g @google/gemini-cli@latest ``` -### Nightly +### 每夜版 -- New releases will be published each day at UTC 00:00. This will be all changes - from the main branch as represented at time of release. It should be assumed - there are pending validations and issues. Use `nightly` tag. +- 每天 UTC 00:00 发布新版本，包含截至发布时 main 分支上的所有变更。应假定存在待处理的验证和问题。使用 ``nightly`` 标签。 ```bash npm install -g @google/gemini-cli@nightly ``` -## 📋 Key Features +## 📋 主要功能 -### Code Understanding & Generation +### 代码理解与生成 -- Query and edit large codebases -- Generate new apps from PDFs, images, or sketches using multimodal capabilities -- Debug issues and troubleshoot with natural language +- 查询和编辑大型代码库 +- 利用多模态能力从 PDF、图片或草稿生成新应用 +- 调试问题并使用自然语言排查故障 -### Automation & Integration +### 自动化与集成 -- Automate operational tasks like querying pull requests or handling complex - rebases -- Use MCP servers to connect new capabilities, including - [media generation with Imagen, Veo or Lyria](https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio/tree/main/experiments/mcp-genmedia) -- Run non-interactively in scripts for workflow automation +- 自动化运维任务，如查询拉取请求或处理复杂的变基操作 +- 使用 MCP 服务器连接新能力，包括 + [使用 Imagen、Veo 或 Lyria 生成媒体](https://github.com/GoogleCloudPlatform/vertex-ai-creative-studio/tree/main/experiments/mcp-genmedia)) +- 以非交互模式在脚本中运行，实现工作流自动化 -### Advanced Capabilities +### 高级能力 -- Ground your queries with built-in - [Google Search](https://ai.google.dev/gemini-api/docs/grounding) for real-time - information -- Conversation checkpointing to save and resume complex sessions -- Custom context files (GEMINI.md) to tailor behavior for your projects +- 使用内置的 + [Google 搜索](https://ai.google.dev/gemini-api/docs/grounding))为查询提供实时信息验证 +- 对话检查点功能，可保存和恢复复杂会话 +- 自定义上下文文件（GEMINI.md），为项目定制行为 -### GitHub Integration +### GitHub 集成 -Integrate Gemini CLI directly into your GitHub workflows with -[**Gemini CLI GitHub Action**](https://github.com/google-github-actions/run-gemini-cli): +通过 +[**Gemini CLI GitHub Action**](https://github.com/google-github-actions/run-gemini-cli):) +将 Gemini CLI 直接集成到您的 GitHub 工作流中 -- **Pull Request Reviews**: Automated code review with contextual feedback and - suggestions -- **Issue Triage**: Automated labeling and prioritization of GitHub issues based - on content analysis -- **On-demand Assistance**: Mention `@gemini-cli` in issues and pull requests - for help with debugging, explanations, or task delegation -- **Custom Workflows**: Build automated, scheduled and on-demand workflows - tailored to your team's needs +- **拉取请求审查**：基于上下文的自动化代码审查，提供反馈和建议 +- **问题分类**：基于内容分析自动对 GitHub Issue 进行标注和优先级排序 +- **按需协助**：在 Issue 和拉取请求中提及 ``@gemini-cli``，获取调试、解释或任务委派方面的帮助 +- **自定义工作流**：构建自动化、定时和按需工作流，满足团队需求 -## 🔐 Authentication Options +## 🔐 身份验证选项 -Choose the authentication method that best fits your needs: +选择最适合您的身份验证方式： -### Option 1: Sign in with Google (OAuth login using your Google Account) +### 选项 1：使用 Google 账号登录（OAuth 登录） -**✨ Best for:** Individual developers as well as anyone who has a Gemini Code -Assist License. (see -[quota limits and terms of service](https://cloud.google.com/gemini/docs/quotas) -for details) +**✨ 适合：** 个人开发者以及拥有 Gemini Code Assist 许可证的用户（详见 +[配额限制与服务条款](https://cloud.google.com/gemini/docs/quotas))） -**Benefits:** +**优势：** -- **Free tier**: 60 requests/min and 1,000 requests/day -- **Gemini 3 models** with 1M token context window -- **No API key management** - just sign in with your Google account -- **Automatic updates** to latest models +- **免费使用额度**：每分钟 60 次请求和每日 1,000 次请求 +- **Gemini 3 模型**，附带 100 万 token 上下文窗口 +- **无需管理 API 密钥**——只需使用 Google 账号登录即可 +- **自动更新**至最新模型 -#### Start Gemini CLI, then choose _Sign in with Google_ and follow the browser authentication flow when prompted +#### 启动 Gemini CLI，然后选择"使用 Google 账号登录"并按提示完成浏览器身份验证流程 ```bash gemini ``` -#### If you are using a paid Code Assist License from your organization, remember to set the Google Cloud Project +#### 如果您使用的是所在组织的付费 Code Assist 许可证，请记得设置 Google Cloud 项目 ```bash # Set your Google Cloud Project @@ -175,15 +162,15 @@ export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" gemini ``` -### Option 2: Gemini API Key +### 选项 2：Gemini API 密钥 -**✨ Best for:** Developers who need specific model control or paid tier access +**✨ 适合：** 需要特定模型控制或付费层级访问权限的开发者 -**Benefits:** +**优势：** -- **Free tier**: 1000 requests/day with Gemini 3 (mix of flash and pro) -- **Model selection**: Choose specific Gemini models -- **Usage-based billing**: Upgrade for higher limits when needed +- **免费使用额度**：Gemini 3（Flash 和 Pro 混合）每日 1,000 次请求 +- **模型选择**：选择特定的 Gemini 模型 +- **按用量计费**：需要更高额度时升级 ```bash # Get your key from https://aistudio.google.com/apikey @@ -191,15 +178,15 @@ export GEMINI_API_KEY="YOUR_API_KEY" gemini ``` -### Option 3: Vertex AI +### 选项 3：Vertex AI -**✨ Best for:** Enterprise teams and production workloads +**✨ 适合：** 企业团队和生产环境工作负载 -**Benefits:** +**优势：** -- **Enterprise features**: Advanced security and compliance -- **Scalable**: Higher rate limits with billing account -- **Integration**: Works with existing Google Cloud infrastructure +- **企业级特性**：高级安全性和合规性 +- **可扩展**：使用结算账户获得更高的速率限制 +- **集成**：与现有 Google Cloud 基础设施协同工作 ```bash # Get your key from Google Cloud Console @@ -208,56 +195,56 @@ export GOOGLE_GENAI_USE_VERTEXAI=true gemini ``` -For Google Workspace accounts and other authentication methods, see the -[authentication guide](https://www.geminicli.com/docs/get-started/authentication). +关于 Google Workspace 账号和其他身份验证方式，请参阅 +[身份验证指南](https://www.geminicli.com/docs/get-started/authentication).)。 -## 🚀 Getting Started +## 🚀 快速上手 -### Basic Usage +### 基本用法 -#### Start in current directory +#### 在当前目录启动 ```bash gemini ``` -#### Include multiple directories +#### 包含多个目录 ```bash gemini --include-directories ../lib,../docs ``` -#### Use specific model +#### 使用指定模型 ```bash gemini -m gemini-2.5-flash ``` -#### Non-interactive mode for scripts +#### 脚本模式（非交互） -Get a simple text response: +获取纯文本响应： ```bash gemini -p "Explain the architecture of this codebase" ``` -For more advanced scripting, including how to parse JSON and handle errors, use -the `--output-format json` flag to get structured output: +如需更高级的脚本操作（包括解析 JSON 和处理错误），请使用 +``--output-format json`` 标志获取结构化输出： ```bash gemini -p "Explain the architecture of this codebase" --output-format json ``` -For real-time event streaming (useful for monitoring long-running operations), -use `--output-format stream-json` to get newline-delimited JSON events: +如需实时事件流（适用于监控长时间运行的操作）， +使用 ``--output-format stream-json`` 获取换行符分隔的 JSON 事件： ```bash gemini -p "Run tests and deploy" --output-format stream-json ``` -### Quick Examples +### 快速示例 -#### Start a new project +#### 启动新项目 ```bash cd new-project/ @@ -265,7 +252,7 @@ gemini > Write me a Discord bot that answers questions using a FAQ.md file I will provide ``` -#### Analyze existing code +#### 分析现有代码 ```bash git clone https://github.com/google-gemini/gemini-cli @@ -274,74 +261,52 @@ gemini > Give me a summary of all of the changes that went in yesterday ``` -## 📚 Documentation +## 📚 文档 -### Getting Started +### 快速入门 -- [**Quickstart Guide**](https://www.geminicli.com/docs/get-started) - Get up - and running quickly. -- [**Authentication Setup**](https://www.geminicli.com/docs/get-started/authentication) - - Detailed auth configuration. -- [**Configuration Guide**](https://www.geminicli.com/docs/reference/configuration) - - Settings and customization. -- [**Keyboard Shortcuts**](https://www.geminicli.com/docs/reference/keyboard-shortcuts) - - Productivity tips. +- [**快速开始指南**](https://www.geminicli.com/docs/get-started)) — 快速上手。 +- [**认证设置**](https://www.geminicli.com/docs/get-started/authentication)) — 详细的身份验证配置。 +- [**配置指南**](https://www.geminicli.com/docs/reference/configuration)) — 设置与自定义。 +- [**键盘快捷键**](https://www.geminicli.com/docs/reference/keyboard-shortcuts)) — 提高效率的小技巧。 -### Core Features +### 核心功能 -- [**Commands Reference**](https://www.geminicli.com/docs/reference/commands) - - All slash commands (`/help`, `/chat`, etc). -- [**Custom Commands**](https://www.geminicli.com/docs/cli/custom-commands) - - Create your own reusable commands. -- [**Context Files (GEMINI.md)**](https://www.geminicli.com/docs/cli/gemini-md) - - Provide persistent context to Gemini CLI. -- [**Checkpointing**](https://www.geminicli.com/docs/cli/checkpointing) - Save - and resume conversations. -- [**Token Caching**](https://www.geminicli.com/docs/cli/token-caching) - - Optimize token usage. +- [**命令参考**](https://www.geminicli.com/docs/reference/commands)) — 所有斜杠命令（``/help``、``/chat`` 等）。 +- [**自定义命令**](https://www.geminicli.com/docs/cli/custom-commands)) — 创建你自己的可复用命令。 +- [**上下文文件 (GEMINI.md)**](https://www.geminicli.com/docs/cli/gemini-md)) — 为 Gemini CLI 提供持久化上下文。 +- [**检查点**](https://www.geminicli.com/docs/cli/checkpointing)) — 保存和恢复对话。 +- [**令牌缓存**](https://www.geminicli.com/docs/cli/token-caching)) — 优化令牌用量。 -### Tools & Extensions +### 工具与扩展 -- [**Built-in Tools Overview**](https://www.geminicli.com/docs/reference/tools) - - [File System Operations](https://www.geminicli.com/docs/tools/file-system) - - [Shell Commands](https://www.geminicli.com/docs/tools/shell) - - [Web Fetch & Search](https://www.geminicli.com/docs/tools/web-fetch) -- [**MCP Server Integration**](https://www.geminicli.com/docs/tools/mcp-server) - - Extend with custom tools. -- [**Custom Extensions**](https://geminicli.com/docs/extensions/writing-extensions) - - Build and share your own commands. +- [**内置工具概览**](https://www.geminicli.com/docs/reference/tools)) + - [文件系统操作](https://www.geminicli.com/docs/tools/file-system)) + - [Shell 命令](https://www.geminicli.com/docs/tools/shell)) + - [网络抓取与搜索](https://www.geminicli.com/docs/tools/web-fetch)) +- [**MCP 服务器集成**](https://www.geminicli.com/docs/tools/mcp-server)) — 通过自定义工具进行扩展。 +- [**自定义扩展**](https://geminicli.com/docs/extensions/writing-extensions)) — 构建和分享你自己的命令。 -### Advanced Topics +### 高级主题 -- [**Headless Mode (Scripting)**](https://www.geminicli.com/docs/cli/headless) - - Use Gemini CLI in automated workflows. -- [**IDE Integration**](https://www.geminicli.com/docs/ide-integration) - VS - Code companion. -- [**Sandboxing & Security**](https://www.geminicli.com/docs/cli/sandbox) - Safe - execution environments. -- [**Trusted Folders**](https://www.geminicli.com/docs/cli/trusted-folders) - - Control execution policies by folder. -- [**Enterprise Guide**](https://www.geminicli.com/docs/cli/enterprise) - Deploy - and manage in a corporate environment. -- [**Telemetry & Monitoring**](https://www.geminicli.com/docs/cli/telemetry) - - Usage tracking. -- [**Tools reference**](https://www.geminicli.com/docs/reference/tools) - - Built-in tools overview. -- [**Local development**](https://www.geminicli.com/docs/local-development) - - Local development tooling. +- [**无头模式（脚本化）**](https://www.geminicli.com/docs/cli/headless)) — 在自动化工作流中使用 Gemini CLI。 +- [**IDE 集成**](https://www.geminicli.com/docs/ide-integration)) — VS Code 配套工具。 +- [**沙箱与安全**](https://www.geminicli.com/docs/cli/sandbox)) — 安全的执行环境。 +- [**受信任文件夹**](https://www.geminicli.com/docs/cli/trusted-folders)) — 按文件夹控制执行策略。 +- [**企业指南**](https://www.geminicli.com/docs/cli/enterprise)) — 在企业环境中部署和管理。 +- [**遥测与监控**](https://www.geminicli.com/docs/cli/telemetry)) — 使用追踪。 +- [**工具参考**](https://www.geminicli.com/docs/reference/tools)) — 内置工具概览。 +- [**本地开发**](https://www.geminicli.com/docs/local-development)) — 本地开发工具。 -### Troubleshooting & Support +### 故障排查与支持 -- [**Troubleshooting Guide**](https://www.geminicli.com/docs/resources/troubleshooting) - - Common issues and solutions. -- [**FAQ**](https://www.geminicli.com/docs/resources/faq) - Frequently asked - questions. -- Use `/bug` command to report issues directly from the CLI. +- [**故障排查指南**](https://www.geminicli.com/docs/resources/troubleshooting)) — 常见问题与解决方案。 +- [**常见问题**](https://www.geminicli.com/docs/resources/faq)) — 常见问题解答。 +- 使用 ``/bug`` 命令直接从 CLI 报告问题。 -### Using MCP Servers +### 使用 MCP 服务器 -Configure MCP servers in `~/.gemini/settings.json` to extend Gemini CLI with -custom tools: +在 ``~/.gemini/settings.json`` 中配置 MCP 服务器，以通过自定义工具扩展 Gemini CLI： ```text > @github List my open pull requests @@ -349,51 +314,40 @@ custom tools: > @database Run a query to find inactive users ``` -See the -[MCP Server Integration guide](https://www.geminicli.com/docs/tools/mcp-server) -for setup instructions. +有关设置说明，请参阅 +[MCP 服务器集成指南](https://www.geminicli.com/docs/tools/mcp-server))。 -## 🤝 Contributing +## 🤝 贡献 -We welcome contributions! Gemini CLI is fully open source (Apache 2.0), and we -encourage the community to: +欢迎贡献！Gemini CLI 是完全开源的（Apache 2.0），我们鼓励社区： -- Report bugs and suggest features. -- Improve documentation. -- Submit code improvements. -- Share your MCP servers and extensions. +- 报告 Bug 和提出功能建议。 +- 改进文档。 +- 提交代码改进。 +- 分享你的 MCP 服务器和扩展。 -See our [Contributing Guide](./CONTRIBUTING.md) for development setup, coding -standards, and how to submit pull requests. +请参阅我们的[贡献指南](./CONTRIBUTING.md)，了解开发环境搭建、编码标准以及如何提交 Pull Request。 -Check our [Official Roadmap](https://github.com/orgs/google-gemini/projects/11) -for planned features and priorities. +查看我们的[官方路线图](https://github.com/orgs/google-gemini/projects/11))，了解计划中的功能和优先级。 -## 📖 Resources +## 📖 资源 -- **[Free Course](https://learn.deeplearning.ai/courses/gemini-cli-code-and-create-with-an-open-source-agent/information)** - - Learn the basics. -- **[Official Roadmap](./ROADMAP.md)** - See what's coming next. -- **[Changelog](https://www.geminicli.com/docs/changelogs)** - See recent - notable updates. -- **[NPM Package](https://www.npmjs.com/package/@google/gemini-cli)** - Package - registry. -- **[GitHub Issues](https://github.com/google-gemini/gemini-cli/issues)** - - Report bugs or request features. -- **[Security Advisories](https://github.com/google-gemini/gemini-cli/security/advisories)** - - Security updates. +- **[免费课程](https://learn.deeplearning.ai/courses/gemini-cli-code-and-create-with-an-open-source-agent/information)**)** — 学习基础知识。 +- **[官方路线图](./ROADMAP.md)** — 查看下一步计划。 +- **[更新日志](https://www.geminicli.com/docs/changelogs)**)** — 查看近期重要更新。 +- **[NPM 包](https://www.npmjs.com/package/@google/gemini-cli)**)** — 包注册表。 +- **[GitHub Issues](https://github.com/google-gemini/gemini-cli/issues)**)** — 报告 Bug 或请求功能。 +- **[安全公告](https://github.com/google-gemini/gemini-cli/security/advisories)**)** — 安全更新。 -### Uninstall +### 卸载 -See the [Uninstall Guide](https://www.geminicli.com/docs/resources/uninstall) -for removal instructions. +请参阅[卸载指南](https://www.geminicli.com/docs/resources/uninstall))了解移除步骤。 -## 📄 Legal +## 📄 法律信息 -- **License**: [Apache License 2.0](LICENSE) -- **Terms of Service**: - [Terms & Privacy](https://www.geminicli.com/docs/resources/tos-privacy) -- **Security**: [Security Policy](SECURITY.md) +- **许可证**：[Apache License 2.0](LICENSE) +- **服务条款**：[条款与隐私](https://www.geminicli.com/docs/resources/tos-privacy)) +- **安全**：[安全策略](SECURITY.md)

@@ -408,5 +362,5 @@ for removal instructions. ---

- Built with ❤️ by Google and the open source community + 由 Google 与开源社区 ❤️ 共同构建