Hook Reference

本参考提供所有 hook 类型、其 JSON 模式、输入/输出格式以及通信协议的完整技术文档。

Hook 类型

Cline 提供多种 hook 类型，允许您接入 AI 工作流的不同阶段。它们根据触发点和用例进行分类。

下面的 hook 名称是您需要创建的准确文件名。例如，要使用 TaskStart hook，请在您的 hooks 目录中创建一个名为 TaskStart 的文件（没有文件扩展名）。

除了特定数据外，每个 hook 还会接收基本字段：clineVersion、hookName、timestamp、taskId、workspaceRoots、userId。

工具执行 Hooks

这些 hook 在工具操作执行前后进行拦截和验证。使用它们来强制执行策略、跟踪更改以及从操作中学习。

`PreToolUse（工具使用前）`

在 Cline 使用任何工具之前立即触发（有关所有可用工具，请参阅Cline 工具参考指南）。使用它来阻止无效操作、验证参数，并在更改发生之前强制执行项目策略。 输入字段：

{
  "clineVersion": "string",
  "hookName": "PreToolUse",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "preToolUse": {
    "toolName": "string",
    "parameters": {}
  }
}

用法示例

#!/usr/bin/env bash
input=$(cat)

# Block creating .js files in TypeScript projects
tool_name=$(echo "$input" | jq -r '.preToolUse.toolName')
if [[ "$tool_name" == "write_to_file" ]]; then
  file_path=$(echo "$input" | jq -r '.preToolUse.parameters.path')
  if [[ "$file_path" == *.js ]] && [[ -f "tsconfig.json" ]]; then
    echo '{"cancel": true, "errorMessage": "JavaScript files not allowed in TypeScript project"}'
    exit 0
  fi
fi

echo '{"cancel": false}'

`PostToolUse（工具使用后）`

在 Cline 使用任何工具之后立即触发（有关所有可用工具，请参阅Cline 工具参考指南）。使用它来从结果中学习、跟踪性能指标，并根据已执行的操作构建项目知识。 输入字段：

{
  "clineVersion": "string",
  "hookName": "PostToolUse",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "postToolUse": {
    "toolName": "string",
    "parameters": {},
    "result": "string",
    "success": boolean,
    "executionTimeMs": number
  }
}

用法示例

#!/usr/bin/env bash
input=$(cat)

# Log slow operations for performance monitoring
execution_time=$(echo "$input" | jq -r '.postToolUse.executionTimeMs')
tool_name=$(echo "$input" | jq -r '.postToolUse.toolName')

if (( execution_time > 5000 )); then
  context="PERFORMANCE: Slow operation detected - $tool_name took ${execution_time}ms"
  echo "{\"cancel\": false, \"contextModification\": \"$context\"}"
else
  echo '{"cancel": false}'
fi

用户交互 Hooks

这些 hook 监控和增强用户与 Cline 的通信。使用它们来验证输入、注入上下文以及跟踪交互模式。

`UserPromptSubmit（用户提示提交）`

当用户在提示框中输入文本并按回车键来开始新任务、继续已完成任务或恢复已取消任务时触发。使用它来验证输入、根据提示注入上下文以及跟踪交互模式。 输入字段：

{
  "clineVersion": "string",
  "hookName": "UserPromptSubmit",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "userPromptSubmit": {
    "prompt": "string",
    "attachments": ["string"]
  }
}

用法示例

#!/usr/bin/env bash
input=$(cat)

# Inject coding standards context for certain keywords
prompt=$(echo "$input" | jq -r '.userPromptSubmit.prompt')
context=""

if echo "$prompt" | grep -qi "component\|react"; then
  context="CODING_STANDARDS: Follow React functional component patterns with proper TypeScript types"
elif echo "$prompt" | grep -qi "api\|endpoint"; then
  context="CODING_STANDARDS: Use consistent REST API patterns with proper error handling"
fi

if [[ -n "$context" ]]; then
  jq -n --arg ctx "$context" '{"cancel": false, "contextModification": $ctx}'
else
  echo '{"cancel": false}'
fi

任务生命周期 Hooks

这些 hook 监控和响应从开始到结束的任务状态变化。使用它们来跟踪进度、恢复状态并触发工作流。

`TaskStart（任务开始）`

在新任务开始时触发一次。使用它来检测项目类型、初始化跟踪，并注入塑造 Cline 处理工作的初始上下文。 输入字段：

{
  "clineVersion": "string",
  "hookName": "TaskStart",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskStart": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string",
      "initialTask": "string"
    }
  }
}

用法示例

#!/usr/bin/env bash
input=$(cat)

# Detect project type and inject relevant context
context=""

if [[ -f "package.json" ]]; then
  if grep -q "react" package.json; then
    context="PROJECT_TYPE: React application detected. Follow component-based architecture."
  elif grep -q "express" package.json; then
    context="PROJECT_TYPE: Express.js API detected. Follow RESTful patterns."
  else
    context="PROJECT_TYPE: Node.js project detected."
  fi
elif [[ -f "requirements.txt" ]] || [[ -f "pyproject.toml" ]]; then
  context="PROJECT_TYPE: Python project detected. Follow PEP 8 standards."
elif [[ -f "Cargo.toml" ]]; then
  context="PROJECT_TYPE: Rust project detected. Follow Rust conventions."
fi

if [[ -n "$context" ]]; then
  jq -n --arg ctx "$context" '{"cancel": false, "contextModification": $ctx}'
else
  echo '{"cancel": false}'
fi

`TaskResume（任务恢复）`

当用户恢复已被取消或中止的任务时触发。使用它来恢复状态、刷新上下文，并记录恢复情况以用于分析或外部系统通知。 输入字段：

{
  "clineVersion": "string",
  "hookName": "TaskResume",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskResume": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string"
    },
    "previousState": {
      "lastMessageTs": "string",
      "messageCount": "string",
      "conversationHistoryDeleted": "string"
    }
  }
}

`TaskCancel（任务取消）`

当用户取消任务或中止 hook 执行时触发。使用它来清理资源、记录取消详情，并通知外部系统有关中断的工作。 输入字段：

{
  "clineVersion": "string",
  "hookName": "TaskCancel",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskCancel": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string"
    }
  }
}

`TaskComplete（任务完成）`

当 Cline 完成工作并成功执行 attempt_completion 工具以最终确定任务输出时触发。使用它来跟踪完成指标、生成报告、记录任务结果并触发完成工作流。 输入字段：

{
  "clineVersion": "string",
  "hookName": "TaskComplete",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskComplete": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string"
    }
  }
}

用法示例

#!/usr/bin/env bash
input=$(cat)

# Extract task metadata
task_id=$(echo "$input" | jq -r '.taskComplete.taskMetadata.taskId // "unknown"')
ulid=$(echo "$input" | jq -r '.taskComplete.taskMetadata.ulid // "unknown"')

# Log completion
completion_log="$HOME/.cline_completions/$(date +%Y-%m-%d).log"
mkdir -p "$(dirname "$completion_log")"

echo "$(date -Iseconds): Task $task_id completed (ULID: $ulid)" >> "$completion_log"

# Provide context about completion
context="TASK_COMPLETED: Task $task_id finished successfully. Completion logged."
jq -n --arg ctx "$context" '{"cancel": false, "contextModification": $ctx}'

系统事件 Hooks

这些 hook 监控内部 Cline 操作和系统级事件。使用它们来跟踪上下文使用情况、记录系统行为并分析性能模式。

JSON 通信协议

Hook 通过 stdin 接收 JSON，并通过 stdout 返回 JSON。

输入格式

所有 hook 通过 stdin 接收具有此基本结构的 JSON 对象

{
  "clineVersion": "string",
  "hookName": "string", 
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "[hookSpecificField]": {
    // Hook-specific data structure
  }
}

输出格式

您的 hook 脚本必须将 JSON 响应作为最终的 stdout 内容输出

{
  "cancel": false,
  "contextModification": "WORKSPACE_RULES: Use TypeScript",
  "errorMessage": "Error details if blocking"
}

字段说明

cancel（必需）：布尔值，控制执行是否继续
- true：阻止当前操作
- false：允许操作继续进行
contextModification（可选）：注入到对话中的字符串
- 影响未来的 AI 决策，而非当前的决策
- 使用清晰的前缀，如 WORKSPACE_RULES:、PERFORMANCE:、SECURITY: 进行分类
- 最大长度：50KB
errorMessage（可选）：当 cancel 为 true 时显示给用户的字符串
- 仅在阻止操作时显示
- 应解释操作被阻止的原因

执行期间的日志记录

您的 hook 脚本可以在执行期间将日志记录或诊断信息输出到 stdout，只要 JSON 响应是最后写入的内容即可

#!/usr/bin/env bash
echo "Processing hook..."  # This is fine
echo "Tool: $tool_name"    # This is also fine

# The JSON must be last:
echo '{"cancel": false}'

Cline 将仅解析 stdout 中的最终 JSON 对象。

错误处理

Hook 执行错误不会阻止任务执行 - 只有返回 "cancel": true 才能中止任务。所有其他错误都被视为 hook 失败，而不是中止任务的原因。 Hook 状态显示：

已完成（灰色）：Hook 执行成功，无论它返回 "cancel": false 还是没有 JSON 输出
失败（红色）：Hook 以非零状态退出、输出无效 JSON 或超时。UI 显示错误详情（例如，退出代码）
已中止（红色）：Hook 返回 "cancel": true，中止任务。用户必须手动恢复任务才能继续

重要：即使 hook 失败（非零退出、无效 JSON、超时），Cline 也会继续执行任务。只有 "cancel": true 才会停止执行。

上下文修改时机

上下文注入影响未来的决策，而非当前的决策。当 hook 运行时

AI 已经决定要做什么
hook 可以阻止或允许它
任何上下文都会被添加到对话中
下一个 AI 请求会看到该上下文

这意味着

PreToolUse hooks：用于阻止不良操作 + 为下一个决策注入上下文
PostToolUse hooks：用于从已完成的操作中学习

有用提示：JSON 中的字符串转义

当您的 hook 需要在 JSON 输出中包含带有未转义引号字符 (") 的字符串时，请使用 jq 的 --arg 标志进行正确的转义

#!/usr/bin/env bash

# When $output contains unescaped quote characters (")...
output='{"foo":"bar"}'

# Use the --arg flag for automatic string escaping
jq -n --arg ctx "$output" '{cancel: false, contextModification: $ctx}'

# This will result in:
# {
#     "cancel": false,
#     "contextModification": "{\"foo\":\"bar\"}"
# }

--arg 标志会自动转义特殊字符，防止在您的上下文修改包含复杂字符串或嵌套 JSON 结构时出现 JSON 解析错误。

Hook 执行环境

执行上下文

Hook 是可执行脚本，以与 VS Code 相同的权限运行。它们对以下内容拥有无限制访问权限

整个文件系统（用户可以访问的任何文件）
所有环境变量
系统命令和工具
网络资源

Hook 可以执行用户在终端中可以执行的任何操作，包括读取和写入工作区外部的文件、发出网络请求以及执行系统命令。

安全注意事项

Hook 以与 VS Code 相同的权限运行。它们可以访问所有工作区文件和环境变量。在启用来自不受信任来源的 hook 之前，请对其进行审查。

性能指南

Hook 有 30 秒的超时时间。只要您的 hook 在此时间内完成，它就可以执行所需的任何操作，包括网络调用或繁重的计算。

Hook 发现

Cline 按此顺序搜索 hook

项目特定：工作区根目录中的 .clinerules/hooks/
用户全局：~/Documents/Cline/Hooks/

项目特定的 hook 会覆盖同名的全局 hook。

简介

入门

最佳实践

CLI

功能

模型与提供商配置

MCP 集成

Cline 工具参考

参考

Hook 类型

工具执行 Hooks

`PreToolUse（工具使用前）`

`PostToolUse（工具使用后）`

用户交互 Hooks

`UserPromptSubmit（用户提示提交）`

任务生命周期 Hooks

`TaskStart（任务开始）`

`TaskResume（任务恢复）`

`TaskCancel（任务取消）`

`TaskComplete（任务完成）`

系统事件 Hooks

JSON 通信协议

输入格式

输出格式

执行期间的日志记录

错误处理

上下文修改时机

有用提示：JSON 中的字符串转义

Hook 执行环境

执行上下文

安全注意事项

性能指南

Hook 发现

简介

入门

最佳实践

CLI

功能

模型与提供商配置

MCP 集成

Cline 工具参考

参考

​Hook 类型

​工具执行 Hooks

​PreToolUse（工具使用前）

​PostToolUse（工具使用后）

​用户交互 Hooks

​UserPromptSubmit（用户提示提交）

​任务生命周期 Hooks

​TaskStart（任务开始）

​TaskResume（任务恢复）

​TaskCancel（任务取消）

​TaskComplete（任务完成）

​系统事件 Hooks

​JSON 通信协议

​输入格式

​输出格式

​执行期间的日志记录

​错误处理

​上下文修改时机

​有用提示：JSON 中的字符串转义

​Hook 执行环境

​执行上下文

​安全注意事项

​性能指南

​Hook 发现

Hook 类型

工具执行 Hooks

`PreToolUse（工具使用前）`

`PostToolUse（工具使用后）`

用户交互 Hooks

`UserPromptSubmit（用户提示提交）`

任务生命周期 Hooks

`TaskStart（任务开始）`

`TaskResume（任务恢复）`

`TaskCancel（任务取消）`

`TaskComplete（任务完成）`

系统事件 Hooks

JSON 通信协议

输入格式

输出格式

执行期间的日志记录

错误处理

上下文修改时机

有用提示：JSON 中的字符串转义

Hook 执行环境

执行上下文

安全注意事项

性能指南

Hook 发现