使用上下文挂钩 - Amazon Q 开发者版
上下文挂钩的类型管理上下文挂钩使用案例示例行为和限制安全性注意事项故障排除

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

使用上下文挂钩

上下文挂钩是 Amazon Q Developer CLI 中的一项功能，您可以使用它在与 Q Developer 的对话中自动注入上下文。上下文挂钩不是用/context命令手动添加上下文，而是运行命令并将其输出作为上下文包含在内。

上下文挂钩的类型

Q 开发者 CLI 支持两种类型的上下文挂钩：

对话开始挂钩

在对话开始时运行一次。他们的输出将添加到对话上下文中，并在整个会话中持续存在。

按提示挂钩

使用每条用户消息运行。它们的输出仅添加到当前提示中。

管理上下文挂钩

您可以使用 Q Developer CLI 中的/context hooks命令来管理上下文挂钩。

查看您的挂钩

要在全局和配置文件级别查看所有已配置的挂钩，请执行以下操作：

/context hooks

此命令显示为当前配置文件和全局级别配置的所有挂钩及其状态（启用或禁用）。

添加一个钩子

要添加新的上下文挂钩，请执行以下操作：

/context hooks add [--global] <name> --trigger <trigger> --command <command>
<name>

挂钩的唯一名称

<trigger>

per_prompt 或 conversation_start

<command>

要执行的 shell 命令

--全球

（可选）将挂钩添加到全局配置而不是当前配置文件中

例 添加 git 状态挂钩
/context hooks add git-status --trigger per_prompt --command "git status --short"

移除挂钩

要移除现有的上下文挂钩，请执行以下操作：

/context hooks rm <name> [--global]

启用或禁用挂钩

要启用特定的挂钩，请执行以下操作：

/context hooks enable [--global] <name>

要禁用特定的挂钩，请执行以下操作：

/context hooks disable [--global] <name>

要启用所有挂钩，请执行以下操作：

/context hooks enable-all [--global]

要禁用所有挂钩：

/context hooks disable-all [--global]

获取有关挂钩的帮助

要显示挂钩命令的详细帮助，请执行以下操作：

/context hooks help

配置

您可以在以下位置验证挂钩的配置。

如果挂钩是全局的：

~/.aws/amazonq/global_context.json

如果挂钩是基于配置文件的：

~/.aws/amazonq/profiles/profile-name/context.json

使用案例示例

以下示例演示了上下文挂钩的常见用例。

Git 状态

添加一个挂钩以在每个提示中显示 git 状态：

/context hooks add git-status --trigger per_prompt --command "git status --short"

此挂钩在每个提示符之前运行git status --short命令，并将输出包含在您与 Q Developer 的对话中。当你询问有关版本控制的问题或需要有关 git 命令的帮助时，这可以帮助 Q Developer 了解你的 git 存储库的当前状态。

项目信息

添加一个挂钩以在对话开始时显示项目信息：

/context hooks add project-info --trigger conversation_start --command "echo 'Project: '$(basename $(pwd))"

此挂钩在对话开始时运行一次，并在上下文中包含当前项目名称。这有助于 Q Developer 针对您的项目提供更相关的回复。

提示

您可以扩展此挂钩以包含更多项目信息，例如编程语言、框架或项目结构。

行为和限制

使用上下文挂钩时，请记住以下行为和限制：

  • Hook 并行运行，以最大限度地减少对响应时间的影响

  • Hook 输出经过格式化并在上下文中清晰标记

  • 该/clear命令会重新评估对话开始挂钩

  • 挂钩存储在你的 Q 开发者 CLI 配置中

  • 当前，仅支持内联命令挂钩

  • 每个挂钩的输出限制为 10KB

  • 默认情况下，挂钩会在 5 秒后超时

安全性注意事项

使用上下文挂钩时，请考虑以下安全最佳实践：

  • 上下文挂钩使用您当前的用户权限执行 shell 命令。请注意在挂钩中包含哪些命令，因为它们与您的用户帐户具有相同的访问权限。

  • 添加可能泄露敏感信息（例如凭据或个人数据）的挂钩时要小心。查看挂钩的输出，确保它们不包含您不想共享的信息。

  • 考虑在不需要挂钩时将其禁用。这降低了意外泄露敏感信息的风险。

  • 不要使用挂钩来运行可能修改系统或数据的命令。Hooks 应该用于读取信息，而不是用于进行更改。

  • 在共享环境中使用挂钩时要小心。如果其他用户有权访问您的 Q Developer CLI 会话，他们也许可以看到您的挂钩的输出。

警告

切勿在挂钩中包含暴露密码、访问密钥或其他凭据的命令。这些信息可能会存储在您的对话历史记录中，并有可能泄露给其他人。

故障排除

如果您在使用上下文挂钩时遇到问题，请尝试以下解决方案：

排除上下文挂钩故障
事务 解决方案
Hook 无法运行 验证挂钩是否已启用 /context hooks
命令失败 直接在终端中测试该命令以确保它能正常工作
输出太大 修改命令以限制输出大小
Hook 超时了 优化您的命令以加快执行速度