自定义智能体与 Hooks

自定义智能体

自定义智能体让你为特定任务量身定制 Copilot 的专长。你提示 Copilot 执行任务时，它可能在判断某个智能体的专长适合该任务时选用你的自定义智能体。自定义智能体做的工作是用子智能体完成的：子智能体是为完成任务临时启动的智能体，有自己的上下文窗口，可以装入与主智能体无关的信息。

创建：每个自定义智能体由扩展名为 .agent.md 的 Markdown 文件定义。你可以自己创建这些文件，或在 CLI 里添加：在交互模式输入 /agent，选 Create new agent，选择在仓库里创建（Project，.github/agents/）还是在主目录里创建（User，~/.copilot/agents/）。个人智能体和仓库智能体 ID 相同时使用个人智能体（位于 agents 目录根的智能体，ID 是去掉 .agent.md 或 .md 扩展名的文件名）。然后选择让 Copilot 帮你创建文件，还是自己创建：选前者时你输入想创建的智能体的详情（描述专长和何时使用），Copilot 据此写出智能体配置，生成后提供选项（Continue、Review content、Try again、Quit），选择审阅内容会在默认编辑器里打开智能体文件；选后者时 CLI 通过一系列提示引导你填写名称（建议只用小写字母和连字符，便于编程使用）、描述（说明智能体有什么专长以及何时使用）和指令（说明智能体应如何行为）。接着选择智能体能访问哪些工具（默认可访问所有工具，限制访问时会在智能体文件里加 tools 规格）。最后重启 CLI 以加载新智能体。

使用：用斜杠命令（交互模式下输入 /agent，从可用的自定义智能体里选，再输入要传给所选智能体的提示；CLI 的默认智能体不在这个列表里）；显式指示（如「Use the security-auditor agent on all files in the /src/app directory」）；通过推断（用会根据智能体文件里的描述触发某个智能体的提示，如「Check all TypeScript files in or under the src directory for potential security problems」，或在智能体配置里定义了触发词时如 seccheck /src/app/validator.go）；或以编程方式。

Hooks

Hooks 是在智能体工作流的关键点（如智能体会话开始或结束、你输入提示、或工具被调用时）执行自定义 shell 命令的方式。它们通过 JSON 输入接收智能体动作的详细信息，使自动化可以感知上下文。例如可以用 hooks：以编程方式批准或拒绝工具执行；使用内置的安全功能（如密钥扫描）防止凭据泄露；实现自定义验证规则和合规审计日志。Hooks 适用于 GitHub 上的 Copilot 云端智能体以及终端里的 Copilot CLI。

你在 JSON 文件里定义 hooks，存放在仓库的 .github/hooks/*.json，适用于仓库里使用 Copilot 智能体的所有时候；也支持存放在主目录 ~/.copilot/hooks/ 的个人 hooks（设置了 COPILOT_HOME 时在 $COPILOT_HOME/hooks/）。

hook 类型：sessionStart（新的智能体会话开始或恢复已有会话时执行，可用于初始化环境、为审计记录会话开始、验证项目状态和设置临时资源）；sessionEnd（会话完成或终止时，可用于清理临时资源、生成并归档会话报告和日志、发送会话完成的通知）；userPromptSubmitted（用户向智能体提交提示时，可用于为审计和用量分析记录用户请求）；preToolUse（智能体使用任何工具（如 bash、edit、view）之前执行，是最强大的 hook，因为它可以批准或拒绝工具执行，用它阻止危险命令、强制安全策略）；postToolUse（工具执行完成之后，无论成功或失败，可用于记录执行结果、跟踪用量统计、生成审计线索、监控性能指标和发送失败告警）；agentStop（主智能体完成对你提示的回复时）；subagentStop（子智能体完成、返回结果给父智能体之前）；errorOccurred（智能体执行期间发生错误时，可用于为调试记录错误、发送通知、跟踪错误模式和生成报告）。

配置格式：JSON 必须含值为 1 的 version 字段，以及含各 hook 定义数组的 hooks 对象。每个 hook 定义形如：

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ]
  }
}

例如在 ~/.copilot/hooks/notification-hooks.json 里为 agentStop 和 sessionEnd 配置播放声音并显示消息框的命令，让 CLI 完成回复或你退出时提醒你（macOS 用 bash 字段、Windows 用 powershell 字段并需要 PowerShell 7.0 或更高）。各 hook 的输入输出 JSON、最佳实践和高级模式见官方 hooks 参考。