Agent 概念 | Jul1en

Hooks

概念

学习概念最好的方法就是参考官方文档：code.claude.com/docs/en/hooks

Hooks 是用户定义的 shell 命令、HTTP 端点或 LLM 提示，它们在 Claude Code 的生命周期中的特定点自动执行。用于参考查找事件模式、配置选项、JSON 输入/输出格式以及异步 hooks、HTTP hooks 和 MCP 工具 hooks 等高级功能。

生命周期（Lifecyle）

Hook 在 Claude Code 会话的特定时间点触发。当事件被触发且匹配器匹配时，Claude Code 会将关于该事件的 JSON 上下文传递给您的钩子处理器。

对于命令 Hook，输入会通过标准输入（stdin）到达
对于 HTTP Hook，输入会作为 POST 请求体到达

然后你的处理器可以检查输入、采取行动，并可选择返回一个决策。

事件分为三种节奏：每次会话一次（ SessionStart ， SessionEnd ）、每次回合一次（ UserPromptSubmit ， Stop ， StopFailure ），以及在每个工具调用中（在代理循环内）（ PreToolUse ， PostToolUse ），如图：

hooklife2

执行时间

下表总结了每个事件触发的时间。Hooks 事件部分记录了每个事件的完整输入模式和决策控制选项。

Event	触发时机
`SessionStart`	当会话开始或恢复
`UserPromptSubmit`	当你提交提示词，在 Claude 处理它之前
`PreToolUse`	在工具调用执行之前。可能会阻止它
`PermissionRequest`	当权限对话框出现时
`PermissionDenied`	当自动模式分类器拒绝工具调用时，返回 {retry: true} 告诉模型它可以重试被拒绝的工具调用
`PostToolUse`	工具调用成功后
`PostToolUseFailure`	工具调用失败后
`Notification`	当 Claude Code 发送通知时
`SubagentStart`	当子代理被创建时
`SubagentStop`	当子代理完成时
`TaskCreated`	当任务通过 TaskCreate 创建时
`TaskCompleted`	当任务被标记为完成时
`Stop`	当 Claude 完成响应
`StopFailure`	当本轮交互因API 错误而终止时触发，此时输出内容及退出码将被忽略
`TeammateIdle`	当代理团队的队友即将进入空闲状态
`InstructionsLoaded`	当 CLAUDE.md 或 .claude/rules/*.md 加载至上下文时触发；会话启动及会话中文件懒加载时均会触发
`ConfigChange`	当会话期间配置文件发生变化时触发
`CwdChanged`	工作目录发生变更时触发（例如 Claude 执行 cd 命令），可搭配 direnv 等工具实现响应式环境管理。
`FileChanged`	当磁盘上的被监听文件发生变更时触发，匹配器字段用于指定需要监听的文件名称。
`WorktreeCreate`	通过 –worktree 参数或 isolation: “worktree” 配置创建 Git 工作区时触发该行为会替换 Git 的默认逻辑
`WorktreeRemove`	移除 Git 工作区时触发，触发时机为会话退出或子代理执行完毕后
`PreCompact`	在上下文压缩之前触发
`PostCompact`	上下文压缩完成后触发
`Elicitation`	MCP 服务器在工具调用过程中请求用户输入时触发
`ElicitationResult`	用户响应 MCP 信息征询后、响应结果回传至服务器前触发
`SessionEnd`	会话结束时触发

如何解析

要了解这些部分如何协同工作，可以以 PreToolUse 钩子举例，它用于阻止破坏性 shell 命令。 matcher 会缩小到 Bash 工具调用，而 if 条件会进一步缩小到以 rm 开头的命令，因此 block-rm.sh 只会在两个过滤器都匹配时才会触发

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

该脚本从标准输入读取 JSON 输入，提取命令，如果包含 rm -rf ，则返回 permissionDecision 的 “deny” ：

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # allow the command
fi

现在假设 Claude Code 决定运行 Bash “rm -rf /tmp/build” 。以下是解析流程图

hook1

如何配置

Hooks 在 JSON 配置文件中定义。配置具有三个级别的嵌套：

选择要响应的 hook 事件，例如 PreToolUse 或 Stop
添加一个匹配器组来过滤何时触发，例如“仅适用于 Bash 工具”
定义一个或多个 hook 处理器来在匹配时运行

具体 hook 实现可参考官方文档：https://code.claude.com/docs/en/hooks-guide#reload-environment-w…

如果不知道如何手动配置，那就把网站丢给他让它给你配置就好了~！

RAG

中文语义就是检索增强生成，是一种技术理念

概念

RAG 是指对大语言模型输出进行优化，使其能够在生成响应之前引用训练数据来源之外的权威知识库。 LLM用海量数据进行训练，使用数十亿个参数为回答问题、翻译语言和完成句子等任务生成原始输出。

在 LLM 本就强大的功能基础上，RAG 将其扩展为能访问特定领域或组织的内部知识库，所有这些都无需重新训练模型。 这是一种经济高效地改进 LLM 输出的方法，让它在各种情境下都能保持相关性、准确性和实用性。

为什么RAG很重要？

LLM 技术的性质给 LLM 响应带来了不可预测性。此外，LLM 训练数据是静态的，从而为其掌握的知识限定了截止日期。

LLM 面临的已知挑战包括：

在没有答案的情况下提供虚假信息。
在用户需要具体的最新响应时，提供过时或宽泛的信息。
依据非权威来源创建响应。
由于术语混淆，不同的培训来源使用相同的术语来谈论不同的事情，因此会产生不准确的响应。

可以将大语言模型看作是一个过于热情的新员工，他拒绝随时了解时事，但总是会绝对自信地回答每一个问题，这就有很大可能会回答错或者过时。则向量数据库能够提供实时信息来源。

RAG 是解决其中这些问题的一种方法。它会重定向 LLM，从权威的、预先确定的知识来源中检索相关信息。 组织可以更好地控制生成的文本输出

工作原理

如果没有 RAG，LLM 会接收用户输入，并根据训练信息（即其已知信息）创建响应。
如果有 RAG，则会引入一个信息检索组件，利用用户输入首先从新数据源提取信息。用户查询和相关信息都提供给 LLM。 LLM 使用新知识及其训练数据来创建更好的响应。以下各部分概述了该过程。

创建外部数据

LLM 原始训练数据集之外的新数据称为外部数据。它可以来自多个数据来源，例如 API、数据库或文档存储库。

数据可能以各种格式存在，例如文件、数据库记录或长篇文本。另一种称为嵌入语言模型的技术将数据转换为数字表示形式并将其存储在向量数据库中。

检索相关信息

下一步是执行相关性搜索。用户查询将转换为向量表示形式，并与向量数据库匹配。

例如，一个可以回答组织的人力资源问题的智能聊天机器人。如果员工搜索 ：“我有多少年假？” ，系统将检索年假政策文档以及员工个人过去的休假记录。将会返回这些与员工输入的内容高度相关的特定文档。 相关性是使用数学向量计算和表示法计算得出并确立的。

增强 LLM 提示

接下来，RAG 模型通过在上下文中添加检索到的相关数据来增强用户输入或提示（就是用户输入 + RAG模型添加的相关数据发给LLM）

更新外部数据

下一个问题可能是——如果外部数据过时了怎么办？要维护当前信息以供检索，可以异步更新文档并更新文档的嵌入表示形式，通过自动化实时流程或定期批处理来执行此操作。

具体的流程图所示：

检索增强生成与语义搜索有什么区别？

语义搜索可以完善 RAG 结果，适用于想要在其 LLM 应用程序中添加大量外部知识源的组织。现代企业在各种系统中存储大量信息，例如手册、常见问题、研究报告、客户服务指南和人力资源文档存储库等。上下文检索在规模上具有挑战性，因此会降低生成输出质量。
语义搜索技术可以扫描包含不同信息的大型数据库，并更准确地检索数据。 例如，他们可以回答诸如 “去年在机械维修上花了多少钱？” 之类的问题，方法是将问题映射到相关文档并返回特定文本而不是搜索结果。 然后，开发人员可以使用该答案为 LLM 提供更多上下文。
RAG 中的传统或关键字搜索解决方案对知识密集型任务产生的结果有限。 相比之下，语义搜索技术可以完成知识库准备的所有工作（单词嵌入、文档分块和其他复杂问题） 。它们还生成语义相关的段落和按相关性排序的标记词，以最大限度地提高 RAG 有效载荷的质量。

我的搜索引擎项目不是 RAG，是用到了语义搜索模块，RAG项目讲结果作为上下文重新再交给LLM生成，我的是直接返回结果。

Skill

它是模块化、可复用、按需加载的结构化能力封装标准。

什么是skills：Skill不是写得更好的prompt，而是可安装、可复用、带执行能力的能力包；它既不是纯文本提示，也不是静态知识库，而是让AI主动识别任务、调用工具、执行动作的标准化单元。一个文件夹即一个Skill，最小仅需一个 skill.md 即可运行；包含三核心组件——YAML元数据+Markdown指令层+可执行脚本（Python/Shell/JS）+按需加载的参考资料。

与prompt的区别

Prompt是反应式、一次性、高开销：用户提问才响应，对话结束即失效，越长越贵，无法跨会话复用，上下文占用大。
Skill是主动式、持久化、低消耗：安装一次长期生效，AI自主判断调用时机；按需加载资源，支持多Skill组合成流水线；包含prompt但远超prompt——它是结构化、可执行、可迭代的能力工程产物。

内部四层结构

Skill内部四层结构解析

YAML Front Matter（元数据层）： name 和 description 为必填项，其中description是AI路由决策的核心依据，决定能否被精准触发。
Markdown正文（指令层）：定义角色、核心任务、输出格式、约束条件等，相当于AI执行任务的“操作手册”。
Scripts目录（执行层）：存放Python/Shell/JavaScript等可执行脚本，AI在沙箱中真实运行代码，不止于生成文字。
Resources目录（资源层）：存放合规手册、知识文档等参考资料，仅在指令明确引用时才加载，避免无效token消耗。

‍

Agent调用Skill全流程演示（以会议审计为例）

路由阶段：用户输入“分析年度采购会议记录，检查超预算违规项”，Agent扫描所有Skill description，LLM推理命中关键词“会议记录”“审计”“预算”，锁定 meeting-auditor 技能。
加载阶段：系统将 meeting-auditor.skill.md 全文载入上下文，AI获得完整审查逻辑与输出模板。
引用阶段：指令中声明“参考compliance-rules.md第三章”，仅该章节被加载，其余合规文档零占用。
推理阶段：AI结合会议记录+合规条款生成审计报告草稿。
执行阶段：用户确认后输入“归档”，Agent调用归档脚本，在沙箱中执行并返回唯一归档编号——全程一句自然语言驱动全链路自动化。