Gemini CLI 从下载安装到运行：知识库搭建教程，附配置参数和测试方法

适用场景与准备工作

Gemini CLI 是面向开发者和内容团队的命令行工具，适合在本地终端中调用 Gemini 模型，完成代码解释、文档问答、资料归纳、脚本生成等任务。它的优势在于不用频繁切换网页界面，可以直接读取当前目录下的文件，并把项目说明、接口文档、产品资料组织成一个轻量级 AI 知识库。对于小团队来说，这种方式部署成本低、更新方便；对于个人用户来说，也适合管理学习笔记、技术手册和常用提示词。

安装前建议准备三类内容：第一，确认电脑已安装 Node.js，建议使用当前长期维护版本，并能正常执行 node -v 与 npm -v；第二，准备可用的 Gemini API 密钥，密钥应只保存在本机环境变量或安全配置文件中，不要写入公开仓库；第三，整理知识库目录，例如 kb/docs 存放文档，kb/rules 存放回答规范，kb/output 存放测试结果。资料文件优先使用 Markdown、TXT、JSON、CSV 等易读取格式，扫描版 PDF 或图片资料需要先转成文本。

下载与安装步骤

在终端中先检查运行环境：node -v、npm -v。如果无法识别命令，需要先安装 Node.js，并重新打开终端。随后执行全局安装命令：npm install -g @google/gemini-cli。安装完成后输入 gemini --version 查看版本号，能返回版本信息即表示安装成功。

接下来配置密钥。macOS 或 Linux 可在终端执行：export GEMINI_API_KEY="你的密钥"，如需长期生效，可写入当前用户的 shell 配置文件。Windows PowerShell 可执行：setx GEMINI_API_KEY "你的密钥"，然后重新打开终端。配置后输入 gemini 进入交互模式，尝试提问“请用三句话介绍 Gemini CLI 的用途”，若能收到正常回复，说明基础链路可用。

如果团队多人使用，不建议共用同一个密钥。更稳妥的方式是每位成员单独配置，并限制密钥可访问的服务范围。遇到安装缓慢、权限不足或命令不可用时，可优先检查 npm 源、全局安装目录权限、系统 PATH 是否包含 npm 全局 bin 目录，不要随意下载来历不明的安装包。

知识库目录设计

Gemini CLI 搭建知识库的核心不是把资料“上传到某个黑盒”，而是让模型在明确边界内读取本地资料并按规则回答。推荐目录结构为：kb/source 放原始资料，kb/clean 放清洗后的文本，kb/prompts 放提示词模板，kb/tests 放测试问题，GEMINI.md 放全局说明。这样便于维护，也方便排查模型回答依据。

GEMINI.md 可以写明知识库角色、可引用资料范围、回答格式和禁止事项。例如：回答必须优先依据 kb/clean 中的内容；不确定时说明“资料中未找到明确依据”；涉及版本、价格、配置项时必须提示用户二次核对；不得编造文件中不存在的结论。这个文件相当于知识库的“使用说明”，对降低幻觉很有帮助。

资料清洗也很关键。建议每个文档开头保留标题、来源、更新时间和适用版本；长文档按章节拆分，单个文件不宜过大；相同内容不要重复存放；过期资料放入 archive 并在说明中标注不再作为默认依据。对于接口文档、产品手册、FAQ 等高频资料，可以按主题拆分，方便命令行快速引用。

常用配置参数思路

实际使用中，常见配置主要围绕模型、输出长度、随机性、上下文范围和工具权限展开。模型参数可选择适合当前任务的 Gemini 版本：资料问答更看重稳定性，代码分析更看重推理能力，长文档总结则看重上下文容量。温度参数 temperature 建议在知识库问答中设为较低值，例如 0.2 到 0.4，以减少随意发挥；如果是创意文案或头脑风暴，可适当提高。

输出长度可通过 max output tokens 或类似参数控制。知识库问答建议不要无限拉长，优先要求“先给结论，再列依据，再给注意事项”。top_p 可保持默认，除非需要严格控制生成风格。上下文范围方面，应尽量让模型只读取必要文件，不要把整个硬盘目录暴露给工具。可以通过在提示中明确文件路径，或在项目目录内运行 CLI，控制可见资料边界。

一个实用的启动方式是先进入知识库根目录：cd kb，再执行 gemini。提问时写清楚引用范围，例如“请只依据 clean 目录下的安装手册，总结 Windows 安装步骤，并列出可能失败的原因”。如果 CLI 支持文件引用语法，可按工具提示引用指定文件；不支持时，也可以把关键资料拆小后逐步输入，避免一次塞入过多内容。

从零运行一次知识库问答

第一步，把产品说明、安装指南、常见问题整理到 kb/clean。第二步，在根目录创建 GEMINI.md，写入回答规则：优先引用本地资料；输出必须包含“结论、依据、操作建议”；无法确认时不得补写。第三步，启动 CLI，并输入测试问题：“用户安装失败，提示找不到 npm，应该如何处理？”此时观察回答是否能定位到 Node.js 环境、PATH、终端重启等关键点。

第四步，进行追问测试：“请指出答案依据来自哪些文件或章节。”如果模型无法给出依据，说明资料结构或提示规则还不够清晰，需要补充文档标题、章节编号或文件说明。第五步，加入反向问题，例如询问资料中不存在的功能，看模型是否会承认未找到依据。一个可靠的知识库，不是每次都给出看似完整的答案，而是在证据不足时能收敛。

第六步，保存高质量问答样例。可以把问题、期望答案、实际答案、评价结果记录到 kb/tests/result.md。当资料更新、CLI 升级或模型切换后，重新跑这些样例，快速判断知识库质量是否下降。

测试方法与验收标准

知识库测试建议覆盖五类问题。第一类是事实检索，例如“某功能支持哪些系统版本”；第二类是步骤复述，例如“从安装到启动需要几步”；第三类是故障排查，例如“命令不可识别如何处理”；第四类是边界问题，例如“资料没有写到的功能能否使用”；第五类是综合任务，例如“根据手册生成给新同事的操作清单”。

验收时可使用四个指标：准确性，看答案是否与资料一致；可追溯性，看是否能说明依据；完整性，看关键步骤是否遗漏；安全性，看是否泄露密钥、内部路径或无关文件内容。对于企业内部资料，还应增加权限检查，不同成员只能访问自己被授权的目录。不要把客户信息、合同细节、账号凭据直接放进可被模型读取的开放目录。

常见问题与处理建议

如果提示找不到 gemini 命令，多半是全局安装目录未加入 PATH，可重新打开终端或检查 npm 全局路径。如果提示认证失败，先确认环境变量名称是否正确、密钥是否复制完整、当前终端是否已重新加载配置。如果回答明显跑偏，优先降低 temperature，并在 GEMINI.md 中强化“只依据指定资料”的规则。

如果长文档回答不完整，应拆分文件并增加目录说明，而不是一次性堆入所有内容。如果资料更新后答案仍旧使用旧内容，检查是否存在重复文件、归档资料是否仍在默认读取范围内。如果团队协作出现答案风格不一致，可以统一提示词模板，例如固定输出“结论、步骤、风险、下一步确认项”。

升级、回滚与安全边界

升级前先记录当前版本：gemini --version，并备份 GEMINI.md、提示词模板和测试样例。升级可执行 npm update -g @google/gemini-cli。升级后不要马上用于正式工作，先跑一轮测试问题，确认回答格式、文件读取方式和参数表现没有明显变化。

如果升级后出现兼容问题，可尝试安装指定旧版本，具体版本号以官方发布记录为准。回滚后同样要复测关键问题。安全边界方面，密钥不要提交到代码仓库，不要把私密资料放到无关目录，不要让模型处理没有授权的个人信息；生成的结论应由人工复核后再对外发布。把 Gemini CLI 当作高效助手，而不是最终裁判，才能让 AI 知识库既好用又可控。