Amazon Q CLI: A Deep Dive into Usage, Configuration, and Best Practices
Amazon Q, an AI-powered assistant, extends its capabilities directly to your terminal through the Amazon Q CLI. This powerful tool enhances developer productivity by providing intelligent assistance, code generation, and contextual insights directly within your command-line workflow. This article offers a detailed exploration of how to use and configure the Amazon Q CLI effectively, along with best practices to maximize its potential.
1. 入门：安装与认证 (Getting Started: Installation and Authentication)
使用 Amazon Q CLI 的第一步是安装并进行身份验证。
1.1. 安装 (Installation)
Amazon Q CLI 支持多种操作系统：
* macOS: 可通过 GUI 安装。
* Linux: 提供 AppImage 或原生 Ubuntu 安装方式。对于无头环境，也可以通过 zip 文件进行安装。
* Windows: 推荐通过 WSL (Windows Subsystem for Linux) 进行安装。
如果在安装过程中遇到问题，可以使用 q doctor 命令获取诊断信息和帮助。
1.2. 认证 (Authentication)
Amazon Q CLI 的认证方式主要有两种：
* AWS Builder ID: 这是免费的认证方式。安装过程会引导您通过浏览器完成身份验证。
* IAM Identity Center: 适用于企业环境，与 Amazon Q Developer Pro 集成，用于管理用户访问。在使用前，您需要安装并配置 AWS CLI，通过运行 aws configure sso 来设置 IAM Identity Center。
安装完成后，在终端中使用 q login 命令启动登录流程。
2. Model Context Protocol (MCP) 配置 (Model Context Protocol (MCP) Configuration)
Model Context Protocol (MCP) 是 Amazon Q CLI 的核心功能之一，它允许 Amazon Q 连接到外部服务和数据源，极大地扩展了其能力。
2.1. 配置方式 (Configuration Methods)
MCP 服务器的配置主要通过 ~/.aws/amazonq/mcp.json 文件进行。这是一个 JSON 文件，用于列出 MCP 服务器及其设置。
- 全局配置: 在
~/.aws/amazonq/mcp.json中配置 MCP 服务器，这些设置将应用于所有 Amazon Q CLI 项目。 - 工作区配置: 对于项目特定的配置，Amazon Q 会在项目根目录创建
./amazonq/目录。如果全局和工作区配置同时存在，Amazon Q 会合并它们，工作区配置在冲突时具有更高优先级。
2.2. MCP 的安全考量 (Security Considerations for MCP)
由于 MCP 服务器能够连接到外部资源并可能下载和安装库，因此需要特别注意安全性。
* 信任工具: 默认情况下，MCP 服务器提供的工具是不受信任的。每次使用时，Amazon Q CLI 都会提示您进行批准。您可以使用 /tools trust 命令在 Amazon Q CLI 聊天界面中切换信任状态，允许工具在未经提示的情况下运行。
* 恶意软件风险: 在集成 MCP 服务器时务必谨慎，因为不信任的 MCP 服务器可能引入恶意软件。在自动信任工具时要格外小心。
* 依赖项: 确保您的环境中安装了 MCP 服务器所需的所有依赖项（例如 Python、uv 包管理器）。
2.3. 配置选项 (Configuration Options)
MCP 服务器的配置项可以包括：
* command 和 args: 指定如何执行 MCP 服务器。
* env: 用于自定义服务器行为的环境变量（例如 AWS_PROFILE, AWS_REGION）。
* disabled: 一个标志，用于临时禁用特定服务器。
* autoApprove: 一个操作列表，这些操作不需要手动批准。
3. 上下文管理 (Context Management)
Amazon Q CLI 具有强大的上下文感知能力，能够理解您的项目结构并记住当前工作目录。
3.1. 项目上下文集成 (Project Context Integration)
对于现有项目，您可以提示 Amazon Q 分析您的代码库并生成项目摘要。将此摘要保存为 Markdown 文档（例如 <project-directory-root>/.amazonq/context/project-introduction.md），以便为未来的交互提供上下文。
3.2. /context 命令 (The /context Commands)
使用 /context 命令可以管理 Amazon Q 可以访问的文件和目录：
* /context: 列出当前的上下文文件。
* /context add [path]: 将文件/目录添加到上下文。
* /context remove [path]: 从上下文中移除文件/目录。
* /context clear: 清除所有上下文。
3.3. 工作目录 (Working Directory)
Amazon Q CLI 在您的项目文件夹中运行时效果最佳，因为它能够更好地理解项目结构和依赖关系。
4. 自定义与功能 (Customization and Features)
Amazon Q CLI 提供了一些自定义选项和实用功能。
- Beta 功能: 您可以考虑启用 Beta 功能以访问最新的特性，但这取决于您的个人偏好和对稳定性的要求。
- 自动补全: Amazon Q 提供上下文相关的命令行提示和自动补全功能。您可以使用右箭头键接受长补全建议。
- 隐私设置: 根据您的偏好或组织要求，您可能需要禁用与 AWS 共享 Amazon Q 内容，并关闭遥测数据共享。
- 会话管理:
/save [name]: 保存会话历史，以便后续检索。/tangent: 进入/退出“切线模式”，用于探索与主对话无关的侧面话题，而不会中断主对话流。
5. 安全与数据保护 (Security and Data Protection)
Amazon Q 在设计时考虑了安全性，并提供了多层保护机制。
- IAM 集成: Amazon Q 与 IAM 集成以管理访问权限。确保已设置适当的 IAM 策略来控制用户权限。
- 数据保护: Amazon Q 负责数据保护、存储和加密。您可以在 IDE 和命令行中选择退出数据共享。
- 本地文件系统访问: 本地文件系统和命令执行仅限于用户自身的权限。
- HTTPS 通信: CLI 与 AWS 服务之间的所有通信都通过 HTTPS 进行加密保护。
结论 (Conclusion)
Amazon Q CLI 是一个强大的开发工具，通过将 AI 助手直接集成到您的终端，显著提升了开发效率。通过理解其安装、认证、MCP 配置、上下文管理以及安全最佳实践，您可以充分利用 Amazon Q CLI 的潜力，使其成为您日常开发工作流中不可或缺的一部分。正确的使用和配置将使您能够更高效、更安全地进行开发。