挂钩配置

查找有关配置钩子以用于 GitHub Copilot 命令行界面 和 Copilot 编码智能体 的信息。

本文内容

本参考文章详细描述了可用的挂钩类型，并附有示例，包括输入和输出格式、脚本最佳实践以及用于日志记录、安全策略实施和外部集成的高级模式。 有关创建挂钩的一般信息，请参阅 将钩子与 GitHub Copilot 代理配合使用。

挂钩类型

会话启动挂钩

在新代理会话开始或恢复现有会话时执行。

          **输入 JSON：**
JSON
{
  "timestamp": 1704614400000,
  "cwd": "/path/to/project",
  "source": "new",
  "initialPrompt": "Create a new feature"
}

          **领域：**

* timestamp：Unix 时间戳（以毫秒为单位） * cwd：当前工作目录 * source "new" ：（新会话）、 "resume" （恢复会话）或"startup" * initialPrompt：用户的初始提示（如果提供）

          **输出：** 忽略 （未处理返回值）

          **示例钩子：**
JSON
{
  "type": "command",
  "bash": "./scripts/session-start.sh",
  "powershell": "./scripts/session-start.ps1",
  "cwd": "scripts",
  "timeoutSec": 30
}

          **示例脚本（Bash）：**
Shell
#!/bin/bash
INPUT=$(cat)
SOURCE=$(echo "$INPUT" | jq -r '.source')
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')

echo "Session started from $SOURCE at $TIMESTAMP" >> session.log

会话结束钩子

在代理会话完成或终止时执行。

          **输入 JSON：**
JSON
{
  "timestamp": 1704618000000,
  "cwd": "/path/to/project",
  "reason": "complete"
}

          **领域：**

* timestamp：Unix 时间戳（以毫秒为单位） * cwd：当前工作目录 * reason：其中一个 "complete"、 "error"、 "abort"、 "timeout"或 "user_exit"

          **输出：** 被忽略

          **示例脚本**：
Shell
#!/bin/bash
INPUT=$(cat)
REASON=$(echo "$INPUT" | jq -r '.reason')

echo "Session ended: $REASON" >> session.log
# Cleanup temporary files
rm -rf /tmp/session-*

用户提示提交的钩子

当用户向代理提交提示时执行。

          **输入 JSON：**
JSON
{
  "timestamp": 1704614500000,
  "cwd": "/path/to/project",
  "prompt": "Fix the authentication bug"
}

          **领域：**

* timestamp：Unix 时间戳（以毫秒为单位） * cwd：当前工作目录 * prompt：用户提交的确切文本

          **输出：** 忽略（目前不支持在客户挂钩中进行提示更改）

          **示例脚本**：
Shell
#!/bin/bash
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt')
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')

# Log to a structured file
echo "$(date -d @$((TIMESTAMP/1000))): $PROMPT" >> prompts.log

预使用工具钩子

在代理使用任何工具（例如bash、edit、view）之前执行。 这是最强大的挂钩，因为它可以 批准或拒绝工具执行。

          **输入 JSON：**
JSON
{
  "timestamp": 1704614600000,
  "cwd": "/path/to/project",
  "toolName": "bash",
  "toolArgs": "{\"command\":\"rm -rf dist\",\"description\":\"Clean build directory\"}"
}

          **领域：**

* timestamp：Unix 时间戳（以毫秒为单位） * cwd：当前工作目录 * toolName：要调用的工具的名称（如“bash”、“edit”、“view”、“create”） * toolArgs：包含工具参数的 JSON 字符串

          **输出 JSON （可选）：**
JSON
{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Destructive operations require approval"
}

          **输出字段：**

* permissionDecision：或"allow"``"deny"``"ask"（当前仅"deny"处理） * permissionDecisionReason：对决策的易理解解释

          **阻止危险命令的示例挂钩：**
Shell
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
TOOL_ARGS=$(echo "$INPUT" | jq -r '.toolArgs')

# Log the tool use
echo "$(date): Tool=$TOOL_NAME Args=$TOOL_ARGS" >> tool-usage.log

# Check for dangerous patterns
if echo "$TOOL_ARGS" | grep -qE "rm -rf /|format|DROP TABLE"; then
  echo '{"permissionDecision":"deny","permissionDecisionReason":"Dangerous command detected"}'
  exit 0
fi

# Allow by default (or omit output to allow)
echo '{"permissionDecision":"allow"}'

          **强制实施文件权限的示例挂钩：**
Shell
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')

# Only allow editing specific directories
if [ "$TOOL_NAME" = "edit" ]; then
  PATH_ARG=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.path')
  
  if [[ ! "$PATH_ARG" =~ ^(src/|test/) ]]; then
    echo '{"permissionDecision":"deny","permissionDecisionReason":"Can only edit files in src/ or test/ directories"}'
    exit 0
  fi
fi

# Allow all other tools

后工具使用钩子

在工具完成执行后执行（无论是成功还是失败）。

          **示例输入 JSON：**
JSON
{
  "timestamp": 1704614700000,
  "cwd": "/path/to/project",
  "toolName": "bash",
  "toolArgs": "{\"command\":\"npm test\"}",
  "toolResult": {
    "resultType": "success",
    "textResultForLlm": "All tests passed (15/15)"
  }
}

          **领域：**

* timestamp：Unix 时间戳（以毫秒为单位） * cwd：当前工作目录 * toolName：已执行的工具的名称 * toolArgs：包含工具参数的 JSON 字符串 * toolResult：结果对象包含： * resultType：或"success"``"failure"``"denied" * textResultForLlm：结果文本显示给代理

          **输出：** 忽略（当前不支持结果修改）

          **将工具执行统计信息记录到 CSV 文件的示例脚本：**

此脚本将工具执行统计信息记录到 CSV 文件，并在工具失败时发送电子邮件警报。

Shell
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
RESULT_TYPE=$(echo "$INPUT" | jq -r '.toolResult.resultType')

# Track statistics
echo "$(date),${TOOL_NAME},${RESULT_TYPE}" >> tool-stats.csv

# Alert on failures
if [ "$RESULT_TYPE" = "failure" ]; then
  RESULT_TEXT=$(echo "$INPUT" | jq -r '.toolResult.textResultForLlm')
  echo "FAILURE: $TOOL_NAME - $RESULT_TEXT" | mail -s "Agent Tool Failed" [email protected]
fi

出现错误挂钩

在代理执行期间发生错误时执行。

          **示例输入 JSON：**
JSON
{
  "timestamp": 1704614800000,
  "cwd": "/path/to/project",
  "error": {
    "message": "Network timeout",
    "name": "TimeoutError",
    "stack": "TimeoutError: Network timeout\n    at ..."
  }
}

          **领域：**

* timestamp：Unix 时间戳（以毫秒为单位） * cwd：当前工作目录 * error：错误对象包含： * message：错误消息 * name：错误类型/名称 * stack：堆栈跟踪（如果可用）

          **输出：** 忽略（当前不支持错误处理修改）

          **将错误详细信息提取到日志文件的示例脚本：**
Shell
#!/bin/bash
INPUT=$(cat)
ERROR_MSG=$(echo "$INPUT" | jq -r '.error.message')
ERROR_NAME=$(echo "$INPUT" | jq -r '.error.name')

echo "$(date): [$ERROR_NAME] $ERROR_MSG" >> errors.log

脚本最佳做法

读取输入

此示例脚本将 stdin 中的 JSON 输入读取到变量中，然后使用 jq 提取 timestamp 和 cwd 字段。

          **Bash：**
Shell
#!/bin/bash
# Read JSON from stdin
INPUT=$(cat)

# Parse with jq
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')
CWD=$(echo "$INPUT" | jq -r '.cwd')

PowerShell：

PowerShell
# Read JSON from stdin
$input = [Console]::In.ReadToEnd() | ConvertFrom-Json

# Access properties
$timestamp = $input.timestamp
$cwd = $input.cwd

输出 JSON

此示例脚本演示如何从挂钩脚本输出有效的 JSON。 在 Bash 中使用 jq -c 进行紧凑的单行输出，或在 PowerShell 中使用 ConvertTo-Json -Compress。

          **Bash：**
Shell
#!/bin/bash
# Use jq to compact the JSON output to a single line
echo '{"permissionDecision":"deny","permissionDecisionReason":"Security policy violation"}' | jq -c

# Or construct with variables
REASON="Too dangerous"
jq -n --arg reason "$REASON" '{permissionDecision: "deny", permissionDecisionReason: $reason}'

PowerShell：

PowerShell
# Use ConvertTo-Json to compact the JSON output to a single line
$output = @{
    permissionDecision = "deny"
    permissionDecisionReason = "Security policy violation"
}
$output | ConvertTo-Json -Compress

错误处理

此脚本示例演示如何处理挂钩脚本中的错误。

          **Bash：**
Shell
#!/bin/bash
set -e  # Exit on error

INPUT=$(cat)
# ... process input ...

# Exit with 0 for success
exit 0

PowerShell：

PowerShell
$ErrorActionPreference = "Stop"

try {
    $input = [Console]::In.ReadToEnd() | ConvertFrom-Json
    # ... process input ...
    exit 0
} catch {
    Write-Error $_.Exception.Message
    exit 1
}

处理超时

挂钩的默认超时为 30 秒。 对于较长的操作，请增加 timeoutSec。

JSON
{
  "type": "command",
  "bash": "./scripts/slow-validation.sh",
  "timeoutSec": 120
}

高级模式

同一类型的多个挂钩

可以为同一事件定义多个挂钩。 它们按照顺序执行：

JSON
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "comment": "Security validation - runs first"
      },
      {
        "type": "command", 
        "bash": "./scripts/audit-log.sh",
        "comment": "Audit logging - runs second"
      },
      {
        "type": "command",
        "bash": "./scripts/metrics.sh",
        "comment": "Metrics collection - runs third"
      }
    ]
  }
}

脚本中的条件逻辑

          **示例：仅阻止特定工具**
Shell
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')

# Only validate bash commands
if [ "$TOOL_NAME" != "bash" ]; then
  exit 0  # Allow all non-bash tools
fi

# Check bash command for dangerous patterns
COMMAND=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.command')
if echo "$COMMAND" | grep -qE "rm -rf|sudo|mkfs"; then
  echo '{"permissionDecision":"deny","permissionDecisionReason":"Dangerous system command"}'
fi

结构化日志记录

          **示例：JSON 行格式**
Shell
#!/bin/bash
INPUT=$(cat)
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
RESULT_TYPE=$(echo "$INPUT" | jq -r '.toolResult.resultType')

# Output structured log entry
jq -n \
  --arg ts "$TIMESTAMP" \
  --arg tool "$TOOL_NAME" \
  --arg result "$RESULT_TYPE" \
  '{timestamp: $ts, tool: $tool, result: $result}' >> logs/audit.jsonl

与外部系统的集成

          **示例：将警报发送到 Slack**
Shell
#!/bin/bash
INPUT=$(cat)
ERROR_MSG=$(echo "$INPUT" | jq -r '.error.message')

WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{\"text\":\"Agent Error: $ERROR_MSG\"}"

示例用例：

合规性审核线索

通过日志脚本记录合规要求的所有代理的操作。

JSON
{
  "version": 1,
  "hooks": {
    "sessionStart": [{"type": "command", "bash": "./audit/log-session-start.sh"}],
    "userPromptSubmitted": [{"type": "command", "bash": "./audit/log-prompt.sh"}],
    "preToolUse": [{"type": "command", "bash": "./audit/log-tool-use.sh"}],
    "postToolUse": [{"type": "command", "bash": "./audit/log-tool-result.sh"}],
    "sessionEnd": [{"type": "command", "bash": "./audit/log-session-end.sh"}]
  }
}

成本跟踪

跟踪成本分配的工具使用情况：

Shell
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')
USER=${USER:-unknown}

echo "$TIMESTAMP,$USER,$TOOL_NAME" >> /var/log/copilot/usage.csv

代码质量控制实施

防止不符合代码标准的提交

Shell
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')

if [ "$TOOL_NAME" = "edit" ] || [ "$TOOL_NAME" = "create" ]; then
  # Run linter before allowing edits
  npm run lint-staged
  if [ $? -ne 0 ]; then
    echo '{"permissionDecision":"deny","permissionDecisionReason":"Code does not pass linting"}'
  fi
fi

通知系统

发送有关重要事件的通知：

Shell
#!/bin/bash
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt')

# Notify on production-related prompts
if echo "$PROMPT" | grep -iq "production"; then
  echo "ALERT: Production-related prompt: $PROMPT" | mail -s "Agent Alert" [email protected]
fi