mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
6993677ed9
- Introduced command-relationships.json to define relationships between various commands. - Created essential-commands.json to provide detailed descriptions and usage scenarios for key commands. - Implemented update-index.sh script for maintaining command index files, including backup and validation processes. - Added templates for bug reports, feature requests, and questions to streamline issue reporting and feature suggestions.
93 lines
4.5 KiB
Markdown
93 lines
4.5 KiB
Markdown
# 常见问题与解决方案
|
||
|
||
在使用 Gemini CLI 的过程中，您可能会遇到一些问题。本指南旨在帮助您诊断和解决这些常见问题，确保您能顺利使用 CLI。
|
||
|
||
## 1. 命令执行失败或未找到
|
||
|
||
**问题描述**:
|
||
- 您输入的命令没有响应，或者系统提示“命令未找到”。
|
||
- 命令执行后出现错误信息，但您不理解其含义。
|
||
|
||
**可能原因**:
|
||
- 命令拼写错误。
|
||
- CLI 未正确安装或环境变量配置不正确。
|
||
- 命令所需的依赖项缺失。
|
||
- 命令参数不正确或缺失。
|
||
|
||
**解决方案**:
|
||
1. **检查拼写**: 仔细核对您输入的命令是否正确，包括命令名称和任何参数。
|
||
2. **查看帮助**: 使用 `gemini help` 或 `gemini [command-name] --help` 来查看命令的正确用法、可用参数和示例。
|
||
3. **验证安装**: 确保 Gemini CLI 已正确安装，并且其可执行文件路径已添加到系统的环境变量中。您可以尝试重新安装 CLI。
|
||
4. **检查日志**: CLI 通常会生成日志文件。查看这些日志可以提供更详细的错误信息，帮助您定位问题。
|
||
5. **更新 CLI**: 确保您使用的是最新版本的 Gemini CLI。旧版本可能存在已知错误，通过 `gemini version` 检查并更新。
|
||
|
||
## 2. 权限问题
|
||
|
||
**问题描述**:
|
||
- CLI 尝试读取、写入或创建文件/目录时，提示“权限被拒绝”或类似错误。
|
||
- 某些操作（如安装依赖、修改系统配置）失败。
|
||
|
||
**可能原因**:
|
||
- 当前用户没有足够的权限执行该操作。
|
||
- 文件或目录被其他程序占用。
|
||
|
||
**解决方案**:
|
||
1. **以管理员身份运行**: 尝试以管理员权限（Windows）或使用 `sudo`（Linux/macOS）运行您的终端或命令提示符。
|
||
```bash
|
||
# Windows (在命令提示符或 PowerShell 中右键选择“以管理员身份运行”)
|
||
# Linux/macOS
|
||
sudo gemini [command]
|
||
```
|
||
2. **检查文件/目录权限**: 确保您对目标文件或目录拥有读/写/执行权限。您可能需要使用 `chmod` (Linux/macOS) 或修改文件属性 (Windows) 来更改权限。
|
||
3. **关闭占用程序**: 确保没有其他程序正在使用您尝试访问的文件或目录。
|
||
|
||
## 3. 配置问题
|
||
|
||
**问题描述**:
|
||
- CLI 行为异常，例如无法连接到 LLM 服务，或者某些功能无法正常工作。
|
||
- 提示缺少 API 密钥或配置项。
|
||
|
||
**可能原因**:
|
||
- 配置文件（如 `.gemini.json` 或相关环境变量）设置不正确。
|
||
- API 密钥过期或无效。
|
||
- 网络连接问题导致无法访问外部服务。
|
||
|
||
**解决方案**:
|
||
1. **检查配置文件**: 仔细检查 Gemini CLI 的配置文件（通常位于用户主目录或项目根目录）中的设置。确保所有路径、API 密钥和选项都正确无误。
|
||
2. **验证环境变量**: 确认所有必要的环境变量（如 `GEMINI_API_KEY`）都已正确设置。
|
||
3. **网络连接**: 检查您的网络连接是否正常，并确保没有防火墙或代理设置阻止 CLI 访问外部服务。
|
||
4. **重新初始化配置**: 对于某些配置问题，您可能需要使用 `gemini cli-init` 命令重新初始化 CLI 配置。
|
||
```bash
|
||
gemini cli-init
|
||
```
|
||
|
||
## 4. 智能代理 (LLM) 相关问题
|
||
|
||
**问题描述**:
|
||
- 智能代理的响应质量不佳，不相关或不准确。
|
||
- 代理响应速度慢，或提示达到速率限制。
|
||
|
||
**可能原因**:
|
||
- 提示不够清晰或缺乏上下文。
|
||
- 选择了不适合当前任务的 LLM 模型。
|
||
- LLM 服务提供商的速率限制或服务中断。
|
||
|
||
**解决方案**:
|
||
1. **优化提示**: 尝试使用 `enhance-prompt` 命令来优化您的输入，提供更清晰、更具体的上下文信息。
|
||
2. **选择合适的工具**: 根据任务类型，使用 `--tool` 标志选择最合适的 LLM 模型（如 `codex` 适用于代码生成，`gemini` 适用于复杂推理）。
|
||
```bash
|
||
gemini analyze --tool gemini "分析这个复杂算法"
|
||
```
|
||
3. **检查 API 密钥和配额**: 确保您的 LLM 服务 API 密钥有效，并且没有超出使用配额。
|
||
4. **重试或等待**: 如果是速率限制或服务中断，请稍后重试或联系服务提供商。
|
||
|
||
## 5. 寻求帮助
|
||
|
||
如果以上解决方案都无法解决您的问题，您可以：
|
||
|
||
- **查阅官方文档**: 访问 Gemini CLI 的官方文档获取更全面的信息。
|
||
- **社区支持**: 在相关的开发者社区或论坛中提问。
|
||
- **提交问题**: 如果您认为是 CLI 的 bug，请在项目的问题跟踪器中提交详细的问题报告。
|
||
|
||
希望本指南能帮助您解决遇到的问题，让您更好地利用 Gemini CLI！
|