Gemini Rust Suite 🦀

Gemini Rust Suite 🦀

本项目提供了一套用于与 Google Gemini 模型交互的 Rust crate，支持通过模型上下文协议（MCP）使用工具、持久化语义记忆，以及适用于 Linux 终端的强大命令行界面（CLI）等高级功能。

✨ 目录

• 架构
• 功能
• 先决条件
• 安装（CLI）
  • 手动安装
• 配置
  • CLI 配置（config.toml）
  • MCP 服务配置（mcp_servers.json）
  • API 密钥优先级
  • 系统提示词优先级
• CLI 用法
  • 交互模式
  • 聊天记录
  • 记忆功能
  • MCP 集成与函数调用
• 开发

🏗️ 架构

Gemini Rust Suite 是一个模块化项目，由 Cargo 工作区中的多个 crate 组成：

• gemini-core：提供基础组件：

  • 用于与 Google Gemini API（generateContent 端点）交互的异步 GeminiClient。
  • 与 Gemini API 请求/响应格式相对应的类型安全 Rust 结构体（内容部分、函数调用、生成配置）。
  • 核心配置加载（从 TOML 加载 GeminiConfig）和错误处理（GeminiError）。
  • MCP 使用的共享 JSON-RPC 类型（Request、Response、ServerCapabilities、Tool）。

• gemini-ipc：集中定义进程间通信：

  • 为不同守护进程/客户端之间传递的消息定义标准化 Rust 结构体/枚举（例如 gemini-cli、mcp-hostd、HAPPE、IDA）。
  • 确保通信协议一致（依靠 serde 进行序列化）。

• gemini-mcp：实现模型上下文协议（MCP）的主机端：

  • McpHost 负责发现、启动（通过 stdio、SSE、WebSocket）并与 MCP 服务（外部工具/服务）通信。
  • 处理用于工具执行（mcp/tool/execute）和资源检索的 JSON-RPC 通信。
  • 在 Gemini 函数调用与 MCP 工具执行之间进行转换。
  • 包含 mcp-hostd 二进制文件，这是一个独立的 MCP 主机守护进程（使用 gemini-ipc 与客户端通信）。
  • 提供内置 MCP 服务（filesystem、command、memory_store）的源代码。

• gemini-memory：实现持久化语义记忆库：

  • 使用 LanceDB 作为向量数据库。
  • 存储记忆（带元数据的键值对）及其向量嵌入。
  • 根据查询含义执行语义搜索，以查找相关记忆。
  • 依靠 McpHostInterface（通常由 gemini-mcp 提供）调用外部 embedding/embed 工具来生成向量。
  • 提供 enhance_prompt 功能，为大模型提示词添加相关记忆上下文。

• gemini-cli：面向用户的主要应用程序：

  • 使用其他 crate 构建的命令行界面（gemini-cli-bin）。
  • 支持单次提示词、交互式聊天和任务循环。
  • 集成 MCP 以使用工具，并集成 Memory 以感知上下文和历史记录。
  • 管理用户配置、聊天历史记录和会话状态。
  • 可以连接到 mcp-hostd 守护进程（通过 gemini-ipc），或运行内嵌的 McpHost。
  • 还可以通过标志（--filesystem-mcp 等）直接运行内置 MCP 服务。

• （新增）HAPPE：主机应用环境守护进程：

  • 旨在作为主要执行环境，在更复杂的场景中取代直接使用 CLI。
  • 管理用户/客户端、主大模型、IDA 和 MCP 服务之间的交互。
  • 使用 gemini-ipc 与 IDA 通信。
  • 处理大模型调用和由大模型发起的 MCP 工具执行。

• （新增）IDA：内部对话应用守护进程：

  • 管理持久化记忆及其他后台认知任务。
  • 通过 gemini-ipc 与 HAPPE 通信。
  • 通过 Memory MCP 服务（使用 gemini-mcp 客户端逻辑）进行检索和存储。

🚀 功能

本套件通过其组件提供一套全面的功能：

• 核心 API 访问：与 Gemini API 进行可靠的异步通信。
• 工具使用（MCP）：通过 Model Context Protocol 将 Gemini 连接到外部工具和服务，扩展其能力。
• 持久化记忆：使用语义向量数据库（LanceDB）为 Gemini 配备长期记忆，支持跨会话检索上下文。
• 自动增强提示词：自动将相关记忆注入提示词。
• 自动存储记忆：自动将对话中的关键信息保存到记忆库。
• 交互式 CLI：提供易于使用的命令行界面（gemini），支持多种交互模式。
• 聊天历史记录：在不同 CLI 命令之间保留对话历史记录（需要 shell 包装函数）。
• 配置：通过配置文件和环境变量管理 API 密钥、系统提示词、模型和功能开关。
• 格式化输出：CLI 支持 Markdown 渲染和语法高亮。
• 内置工具：提供可直接使用的 MCP 服务，支持文件系统操作、命令执行以及记忆存储和嵌入。

✅ 前置条件

• Rust 工具链： 从 https://rustup.rs/ 安装 🛠️
• Gemini API 密钥： 从 Google AI Studio 获取 🔑
• 支持的 Shell（用于 CLI 包装器）： 建议使用 Bash 或 Zsh，以便流畅地使用 gemini 命令 🐚
• （可选）外部 MCP 服务： 如果你想连接内置工具以外的工具。

📦 安装（CLI）

使用本套件的主要方式是通过 gemini-cli 应用。最简单的安装方式是使用提供的脚本：

# Clone the repository (if you haven't already)
# git clone https://github.com/your-username/gemini-rust-suite
# cd gemini-rust-suite

# Run the installation script from the project root
./install.sh

该脚本将：

1. 检查是否已安装 Rust。
2. 检查安装目录（~/.local/bin）是否存在；如不存在，则创建该目录。
3. 构建发布版二进制文件（gemini-cli-bin 和 mcp-hostd）。
4. 将二进制文件安装到 ~/.local/bin/。
5. 如果找到 install_mcp_servers.sh，则尝试使用它安装 MCP 服务包装脚本（例如，内置服务的包装脚本）。
6. 在你的 ~/.bashrc 或 ~/.zshrc（如果检测到）中添加名为 gemini 的包装函数。此包装函数对于在不同命令之间管理会话历史记录至关重要。
7. （仅限 Zsh） 添加名为 mcpd 的辅助函数，用于管理 mcp-hostd 守护进程（mcpd start、mcpd stop、mcpd status、mcpd logs）。
8. 提示你重新加载 shell 配置（例如，source ~/.zshrc）。

重要： 安装后，必须重新加载 shell 配置，gemini 命令（Zsh 用户还包括 mcpd）才能使用。🔄

手动安装（不使用 Bash/Zsh 或偏好手动设置时）🔧

1. 构建所需的二进制文件：

   cargo build --release --bin gemini-cli-bin --bin mcp-hostd
   

2. 将二进制文件复制到 PATH 中的某个位置：

   cp target/release/gemini-cli-bin ~/.local/bin/
   cp target/release/mcp-hostd ~/.local/bin/
   

3. 确保所选位置（例如，~/.local/bin）已加入 PATH。
4. 至关重要的是，请将 gemini 包装函数（可在 install.sh 脚本或下文中找到）手动添加到 shell 配置文件（.bashrc、.zshrc 等），以便在不同命令之间保留会话历史记录。没有该包装函数，历史记录只会在单个交互式（-i）会话中保留。

   # Gemini CLI Wrapper Function Start
   # This function wraps the gemini-cli-bin to manage session environment variables
   gemini() {
       # Path to the actual binary
       local gemini_bin="$HOME/.local/bin/gemini-cli-bin"
       
       # Check if binary exists
       if [ ! -x "$gemini_bin" ]; then
           echo "Error: gemini-cli-bin not found or not executable at $gemini_bin" >&2
           return 1
       fi
   
       # Run the actual binary, capturing output
       local output
       # Use eval to handle potential quotes in arguments correctly
       output=$(eval "$gemini_bin \"\$@\"") 
       local exit_code=$?
   
       # Extract export commands from the output if the command was successful
       if [ $exit_code -eq 0 ]; then
           # Filter lines starting with # export
           local exports
           exports=$(echo "$output" | grep '^# export')
   
           # Execute the export commands if any were found
           if [ -n "$exports" ]; then
               # Remove the comment and execute
               eval "$(echo "$exports" | sed 's/^# export //')"
           fi
           
           # Print the output, excluding the export lines
           echo "$output" | grep -v '^# export'
       else
           # If the command failed, just print the output (likely error messages)
           echo "$output"
       fi
   
       return $exit_code
   }
   # Gemini CLI Wrapper Function End
   

5. 重新加载 shell 配置。

⚙️ 配置

本套件使用若干配置文件，主要通过 CLI 进行管理：

CLI 配置（config.toml）

• 位置： ~/.config/gemini-suite/config.toml
• 用途： 为 CLI 和守护进程（HAPPE、IDA、mcp-hostd）提供统一配置。
• 管理方式： 使用 gemini config 或 gemini daemon-manager config 子命令。
• 详情： 请参阅 cli/README.md 和 daemon-manager/README.md。

MCP 服务配置（mcp_servers.json）

• 位置： ~/.config/gemini-suite/mcp_servers.json
• 用途： 定义 MCP Host 如何连接到外部工具服务。
• 管理方式： 使用 gemini mcp 或 gemini daemon-manager mcp 子命令。

API 密钥优先级 🔑

1. ~/.config/gemini-suite/config.toml 中的值。
2. GEMINI_API_KEY 环境变量。
3. 当前工作目录中的 .env 文件（或开发期间的项目根目录）中的值。

系统提示词优先级 🗣️

1. ~/.config/gemini-suite/config.toml 中的值。
2. CLI 中嵌入的默认提示词。

💡 CLI 用法

安装并重新加载 shell 后，使用 gemini 包装命令。

# Basic prompt
gemini "Explain Rust's ownership model."

# Interactive chat mode (maintains history within the session)
gemini -i
# Type '/exit' or press Ctrl+C to quit

# Using the wrapper for history across commands:
# First command (creates a session ID):
gemini "What is the capital of France?"
# Subsequent command uses the history (if shell reloaded/wrapper sourced):
gemini "What language do they speak there?"

# Start a new conversation thread (gets a new session ID)
gemini --new-chat "Tell me about Tokio."

# Ask Gemini for command help (requires 'command' MCP server)
gemini -c "list files sorted by modification time"

# Ask Gemini to use a tool (requires relevant MCP server)
gemini "Read the contents of my main.rs file."

# Task loop mode
gemini -t "Refactor the Rust code in src/utils.rs to improve error handling."

# Show configuration
gemini --show-config

# Get help on all flags
gemini --help

# Manage the MCP Host Daemon (Zsh only, via install.sh helper function)
mcpd start
mcpd status
mcpd stop
mcpd logs

交互模式

• 单次模式（默认）： 发送一条提示词，获取一条回复。
• 交互式聊天（-i）： 在单次 CLI 执行中进行 REPL 风格的对话。历史记录会在此模式下保留。
• 任务循环（-t）： 分配一项复杂任务，由 Gemini 自主处理，可使用工具，并仅在必要时请求澄清。

聊天历史记录

• 历史记录会保存到 ~/.local/share/gemini-suite/history/ 中的文件。
• 要在不同 shell 会话间正常使用，必须使用安装程序安装的包装函数。

记忆功能

由 gemini-memory 和 LanceDB（~/.local/share/gemini-suite/memory.db）提供支持。

• 记忆代理（--enable-memory-broker / --disable-memory-broker）： 自动检索相关的历史记忆，并将其作为上下文添加到提示词中。
• 自动记忆（--enable-auto-memory / --disable-auto-memory）： 自动从对话中提取并保存关键信息。
• 需要嵌入服务，通常由内置的 memory-store-mcp 服务提供，或使用通过 mcp_servers.json 配置的外部同类服务。

MCP 集成与函数调用

由 gemini-mcp 提供支持。

• CLI 会连接 mcp_servers.json 中定义的 MCP 服务（通过 mcp-hostd 守护进程或内部主机）。
• 发现的工具会提供给 Gemini。
• 当 Gemini 决定使用工具时：
  1. CLI 会显示拟议的工具调用（例如，filesystem.readFile(path="./README.md")）。
  2. 执行前会请求你确认（y/n）。
  3. 确认后，通过 MCP 主机／服务执行该工具。
  4. 将结果发送回 Gemini。
• 安全： 确认前务必检查工具调用，尤其是执行 command 或修改文件系统的操作。
• 内置服务： CLI 二进制文件本身可以运行随附的服务：
  • gemini --filesystem-mcp
  • gemini --command-mcp
  • gemini --memory-store-mcp（为记忆功能提供嵌入和存储） （这些标志仅运行服务；不接受提示词。）
• 守护进程管理： mcp-hostd 二进制文件是独立的守护进程。你可以直接管理它（例如，mcp-hostd &），也可以使用 install.sh 为 Zsh 用户添加的 mcpd 辅助函数（mcpd start、mcpd stop、mcpd status、mcpd logs）。

💻 开发

此项目是一个 Cargo 工作区。

# Clone the repository
# git clone https://github.com/your-username/gemini-rust-suite
# cd gemini-rust-suite

# Build all crates
cargo build

# Build the CLI specifically (release mode)
cargo build --release --package gemini-cli

# Run the CLI directly from the workspace root
# (Ensure API key is set via .env in workspace root or exported env var)
cargo run --package gemini-cli -- "Your prompt"

cargo run --package gemini-cli -- -i # Interactive mode

cargo run --package gemini-cli -- -c "find text in files" # Command help

# Run tests for all crates
cargo test

# Run tests for a specific crate
cargo test --package gemini-core

# Run the MCP Host Daemon directly
cargo run --package gemini-mcp --bin mcp-hostd