管理自定义代理 - Amazon Q 开发者版
自定义代理文件位置组织自定义代理的最佳实践与团队共享自定义代理

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

管理自定义代理

本节介绍如何在开发工作流程中有效地组织、管理和使用自定义代理。

自定义代理文件位置

自定义代理配置文件以 JSON 文件形式存储在特定目录中：

全球定制代理

~/.aws/amazonq/cli-agents/{agent-name}.json

可在系统上的所有项目和目录中使用。

项目级自定义代理

.amazonq/cli-agents/{agent-name}.json

仅在特定的项目目录及其子目录中可用。

重要：文件名{agent-name}中的仅供参考。实际的代理名称由 JSON 配置文件本身中的name字段确定，这是必填字段。

自定义代理优先级和冲突解决方案

当 Amazon Q Developer CLI 寻找定制代理时，它会遵循特定的优先顺序：

  1. 首先是本地定制代理-检查当前工作目录中是否有定制代理

  2. 其次是全局定制代理-回退到主目录中的自定义代理

  3. 内置默认值-如果未找到自定义代理，则使用默认代理

如果本地和全局目录都包含同名的自定义代理，则优先使用本地定制代理。发生这种情况时，Amazon Q Developer CLI 将显示一条警告消息：

WARNING: Agent conflict for my-agent. Using workspace version.

此优先系统允许您：

  • 使用特定于项目的版本覆盖全局自定义代理

  • 在将自定义代理修改设为全球之前，先在本地对其进行测试

  • 为不同的项目维护不同的自定义代理配置

组织自定义代理的最佳实践

何时使用全球定制代理

使用全局定制代理：

  • 通用工作流程-跨多个项目使用的自定义代理

  • 个人生产力-根据您的个人工作风格量身定制的客服

  • 常见开发任务-代码审查、调试、文档生成

  • 特定于工具的工作流程- AWS 管理、Git 操作、Docker 工作流程

何时使用本地定制代理

使用本地定制代理：

  • 特定于项目的配置-需要访问特定项目文件的自定义代理

  • 团队协作-通过版本控制共享自定义代理

  • 开发环境-对特定项目有独特要求的自定义代理

  • 测试和实验-在不影响全局设置的情况下临时修改自定义代理

自定义代理命名约定

为了更好地组织自定义代理，请考虑以下命名约定：

  • 基于目的的名称-aws-specialist.json、、code-reviewer.json documentation-writer.json

  • 特定于技术的名称-python-dev.json、、react-frontend.json terraform-ops.json

  • 特定于项目的名称-project-alpha.json、、mobile-app.json api-backend.json

  • 特定于环境的名称-development.json、、staging.json production.json

与团队共享自定义代理

可以通过版本控制系统与团队成员共享本地自定义代理。这种方法使团队能够：

  • 标准化开发环境-确保所有团队成员都可以使用相同的工具和配置

  • 共享项目特定的上下文-包括项目文档、编码标准和自定义脚本

  • 保持一致性-在整个团队中使用相同的工具权限和设置

  • 协作改进-使用拉取请求来查看和改进自定义代理配置

版本控制最佳实践

通过版本控制共享自定义代理时：

  • 包括自定义代理目录-.aws/amazonq/agents/ 添加到您的存储库

  • 记录自定义代理的用途-在自定义代理配置文件中使用清晰的描述

  • 查看自定义代理更改-像对待代码更改一样对待自定义代理配置更改

  • 测试自定义代理配置-验证共享自定义代理是否适用于所有团队成员

  • 避免使用敏感信息-不要在共享的自定义代理中包含 API 密钥、密码或个人信息