Claude Code 扩展体系实战：插件、钩子、MCP 与子代理全解析

说句实话，我给不少团队做过 Cli 工具和 Agent 工作流的落地咨询，最后几乎都会落到同一个问题上：工具本身不难学，难的是怎么把它从“能用”变成“真正贴合自己团队的节奏”。Claude Code 的扩展体系就是干这件事的。这篇总览不是功能清单的堆砌，而是我基于实际使用经验，把这套扩展体系按“插件、钩子、MCP、子代理、自定义命令、记忆文件”六个模块拆开讲清楚，从设计逻辑讲到可落地的配置，最后再附上排查技巧。如果你是刚开始接触、想在团队里搭第一套完整配置的人，或者已经在用但总感觉哪里不对的人，这篇文章都值得你从头到尾过一遍。

1. 扩展体系的整体结构与设计逻辑

1.1 六大模块与角色定位

Claude Code 的扩展体系，表面看是一堆分散的配置文件和命令，实际上可以归纳成六个模块，各有各的职责。我把它们之间的关系用一个表格先摆出来，后面再逐个细说。

这六个模块并不是平行的，它们分属不同层次。插件和子代理决定“Agent 能做什么”，钩子决定“什么时候插入你的逻辑”，MCP 决定“Agent 能触达什么外部世界”，自定义命令和记忆文件决定“你如何给它指令和规则”。想清楚这一层，你就不会在配置时东一榔头西一棒子，而是能按需组合。

1.2 这套设计解决了什么问题

我见过不少人第一次接触这套体系时会有一个疑问：为什么不把这些能力全塞进主程序里？这里就涉及到一个核心取舍：主程序保持精简，能力通过可插拔机制扩展。如果所有功能都内置，主程序会变得越来越庞大，权限模型会越来越复杂，升级一次就可能破坏你依赖的某个行为。而扩展体系把“内核”和“外围”分开，内核负责稳定执行，外围负责灵活适配，两者通过明确的接口通信。

另一个很重要的问题是安全边界。你不可能让 Agent 毫无限制地访问所有东西，也不可能每用一次工具都弹窗确认。扩展体系里每一种能力都有自己的权限声明方式：插件声明它能调动什么工具，MCP 服务器声明它的接口范围，钩子声明它只对某个事件生效。这种“最小权限”思路，本质上和操作系统的用户权限设计是一致的。

还有一个容易被忽略的点：这套体系让协作变得可能。插件可以打包分发，命令可以团队共享，CLAUDE.md 可以纳入版本管理。也就是说，你不再需要把一整套复杂配置用聊天记录发给同事，而是可以直接把配置文件放进仓库，所有人 clone 下来就能获得一致的体验。

2. 插件体系：安装、开发与更新

2.1 插件的安装渠道与命令

插件是扩展体系里最像传统软件包的东西。它做的事情是把一组工具、权限说明和资源配置打包成一个独立单元，让 Claude Code 在不改动主程序的情况下获得新能力。通常它包含一个清单文件来声明元信息，以及若干用来加载工具或资源的脚本。

安装插件最常用的是命令行方式。claude plugin install可以直接指定插件市场或仓库地址。如果你已经在会话里，也可以直接用斜杠命令/plugin打开交互式管理面板，搜索、安装、启用、禁用都在这里完成。我个人更喜欢命令行方式，因为它可以把安装动作写进自动化脚本，方便团队批量初始化。

安装完成后，插件不一定立刻生效。有些插件需要重启会话，有些则会在下一次调用时自动加载。这是新手最容易困惑的地方：明明显示安装成功，但会话里完全看不到新工具，或者工具名一直飘红。我建议安装完之后先看一眼插件详情，确认它的“工具列表”和“启用状态”，再在当前会话里重新加载一次。养成这个习惯之后，你会少踩很多无意义的坑。

2.2 从零写一个本地插件

光会装插件不算会扩展体系，自己动手写一个才能真正理解它。我带过一个最简单的本地插件，作用是在每次项目启动时打印一条提醒消息，并把当前分支名作为上下文注入。虽然很简单，但它的完整链路能说明插件开发的全部关键点。

第一步，准备目录。在合适的目录下新建一个文件夹，里面放一个.claude-plugin清单目录，清单内包含plugin.json文件。这个文件负责声明插件名、描述、版本和权限，类似于软件包里的 manifest。接着，在插件根目录准备一个执行入口文件，里面实现你需要的工具调用逻辑。

这里有一个关键点：插件入口文件不直接跑业务逻辑，而是通过标准输入输出和 Agent 通信。每次工具被调用时，Agent 会向插件进程发送参数，插件进程处理完以后从标准输出返回结果。整个通信过程是短连接的，所以你的插件函数应该写成一个请求进来、一个响应出去的形态，不要在进程里维护长期状态，否则很容易出现拿不到最新值的问题。

第二步，注册工具。在代码里要显式声明你提供哪些工具和每个工具的简单描述。这个描述非常关键，因为 Agent 是靠它来决定什么时候调用你的插件的。描述如果写得太含糊，比如“获取信息”，Agent 会在很多无关场景调用它；如果写得太局限，比如“获取当前分支名称”，Agent 又可能在其他需要分支信息的场景里不知所措。我通常的习惯是写清楚“输入参数是什么、输出什么、常见使用场景”，但并不把话说死。

2.3 插件开发与发布的经验教训

写插件时我踩过几个印象比较深的坑，值得单独拎出来说。

第一个坑是权限声明不完整。插件里用到的每个工具，都要在权限声明中列出来，否则运行时会被拦截。有些拦截模式很迷惑，看起来像是插件代码 bug，其实是权限问题。

第二个坑是插件更新后没有把旧目录清干净。本地开发时我经常是复制一个旧包去改，结果清理的时候把新版本覆盖掉了，Agent 还是加载旧逻辑。后来我养成了在正式发布之前，先把旧版本从插件目录里移除再安装新包的做法。

第三个坑是过度设计。起初我会想着把一套完整业务逻辑全塞进一个插件里，结果那个插件自身的调用链很长，一旦中途出错，定位问题非常痛苦。后来我把插件做成“一个插件解决一件事”，组合关系由多个插件协同完成。这样每个插件都足够简单，出问题时能快速判断是哪一环出了问题。

如果你打算把插件发布到市场，还有一点必须留神：插件包会被其他人执行，这意味着你写的代码相当于运行在别人的机器上。恶意插件可以通过滥用权限去读取文件、执行命令，所以发布之前一定要自查一遍，绝对不能想着“先发出去再修”。

3. 钩子机制：在事件节点上挂接自定义逻辑

3.1 钩子事件与触发时机

如果说插件解决的是“Agent 能做什么”，钩子解决的就是“什么时候由谁介入”。它允许你在 Agent 执行流程的特定节点上挂一段脚本，常见的事件有：用户提交提示词时、工具即将被调用时、工具调用结束后、Agent 暂停或停止时，以及子代理停止时。每个事件对应不同的时机和用途。

其中我最常用的是工具调用前和工具调用后这两个节点。调用前可以拦截危险命令、注入额外上下文；调用后可以记录日志、对结果做二次校验。比如团队里有人喜欢让 Agent 直接执行磁盘清理命令，我就在调用前钩子里检查命令内容，一旦出现特定指令就拒绝执行并返回提示。这样不需要改任何人的使用习惯，就能把安全边界立起来。

钩子的配置通常是写在设置文件里的。你需要为每个事件类型指定对应的钩子脚本，并且可以配置拦截或仅记录等行为。对于拦截行为，如果脚本返回特定标识，Agent 就会认为这个调用被取消了，从而不再执行实际动作。这一个机制在上生产环境后非常管用，强烈建议至少做一层前置拦截。

3.2 日志审计钩子脚本实操

讲一个具体的例子。团队里需要一个审计能力，记录每次工具调用的入参和结果摘要。我写了一个钩子脚本，挂在工具调用后的事件上。脚本本身很简单：从标准输入读取事件数据，提取工具名、入参、执行结果状态，然后追加到本地日志文件。

#!/bin/bash input=$(cat) tool_name=$(echo "$input" | jq -r '.tool_name') input_args=$(echo "$input" | jq -c '.tool_input') status=$(echo "$input" | jq -r '.status') ts=$(date '+%Y-%m-%d %H:%M:%S') echo "$ts | $tool_name | $status | $input_args" >> /var/log/claude_hooks.log

这段脚本的写法本身不复杂，真正要注意的是几件容易被忽略的事。

第一，钩子脚本里要处理“没有读取到标准输入”的情况。有时候 Agent 触发的事件不会携带完整数据，脚本如果直接解析就会报错。我习惯在脚本开头判一下输入是否为空，为空就直接退出，不抛异常。

第二，日志文件要处理并发写。Agent 在并行调用多个工具时，会有多个钩子实例同时往同一个文件追加内容。用>>在大多数场景下问题不大，但我见过极端情况下日志行被截断，后来改成了每行单次写入，并定时轮转日志文件。你们如果日志量特别大，建议也提前考虑轮转策略，否则几个月后一个日志文件几个 CPU 都跑不动。

第三，钩子脚本的超时要控制好。Agent 不会无限等待钩子脚本，超过阈值就会被中断。如果一个钩子需要做网络请求，务必在脚本里加上自己的超时逻辑，别让它变成流程瓶颈。

3.3 钩子配置里容易踩的坑

钩子机制最大的坑是“递归执行”。你在钩子里调用了 Agent 工具，而这个调用又触发了同一个钩子，就会形成无限循环。我一开始做审计钩子时没有考虑这一点，结果钩子脚本里用了日志清理命令，而清理命令又走了前置检查钩子，整个会话直接卡死。解决办法非常笨但有效：在钩子脚本开头加一个环境变量开关，检测到是自己进程发起的调用就跳过后续逻辑。

另一个常见的坑是钩子脚本的返回值格式。不同事件对返回值的要求不一样，有些事件认某个特定字段，有些事件只看退出状态码。如果返回结构不对，看起来钩子已经执行了，但实际上对 Agent 流程毫无影响，行为就是“静默失败”。排查这类问题没有任何捷径，只能先构造一个最小复现场景，逐步打印返回值确认。

还有，钩子的权限范围也要克制。不要写一个钩子把所有事件都挂一遍，然后再在钩子内部用繁琐的条件分支来处理不同场景。更好的做法是每个事件单独配一个极简脚本，各司其职。虽然文件数量会变多，但可读性和排查难度都会好很多。

4. MCP：以统一协议接入外部工具和数据

4.1 MCP 服务器的配置方法

MCP（模型上下文协议）解决的是 Agent 如何触达外部世界的问题。插件和钩子主要是在 Agent 进程内部和周边做文章，而 MCP 可以把数据库、浏览器、文件系统、内部 API 这些原本和 Agent 无关的能力，用一套统一的协议注册进来。配置好以后，Agent 会像使用内置工具一样调用这些外部能力。

配置的入口通常是设置文件里的mcp字段，也可以使用交互命令来添加。添加时你要给这个 MCP 服务器起一个名字，并指定它的启动命令和参数。比如接入一个本地文件索引服务，配置里就要告诉 Agent 用什么命令去启动它。一旦成功连接，Agent 会立刻在会话里看到新的工具。

我建议把 MCP 服务器的配置保存在项目级或用户级的配置文件里，而不是每次手工敲命令。这样换一台机器、新同学加入时，只要有配置文件和对应的启动依赖，就能秒级接入同一套外部能力。

4.2 面向场景的接入思路

接入哪些 MCP 服务器，完全取决于你的工作场景，不是越多越好。我自己常用的几个方向可以作为参考，你们照着这几个方向去选型，基本不会跑偏。

第一个方向是数据查询。让 Agent 能直接查数据库、读数据仓库的表结构、跑只读查询。这是效率最高的一个场景，因为很多需求本质上就是“查一下某张表的数据变化趋势”，而不是要写一段完整的代码。第二个方向是浏览器自动化。适合做页面操作、表单填写、截图验证这类任务。第三是文件系统操作，尤其适合处理大型仓库里跨目录的批量动作。第四是内部 API 的桥接，把公司内部的接口变成一个工具集，但这里要非常注意权限控制。

4.3 权限与性能细节

MCP 服务器的权限控制是最需要认真对待的。一个数据库 MCP 如果允许写操作，Agent 就有可能在你没注意的时候执行了更新或删除语句。我的习惯是，查询型 MCP 只暴露只读权限，写操作单独用另一个服务器，并且挂在专门的、需要额外确认的权限级别上。这一点不管你是单机使用还是团队协作，都非常值得执行。

性能方面，MCP 服务器每次被调用都会走一遍启动、连接、调用的完整链路，如果服务器启动本身很重，每次调用都会很慢。我遇到过接入一个大型本地索引服务的场景，进程启动要三四秒，Agent 调用一次工具就要等这么久，整个会话的节奏被拖得很难受。后来我改成常驻服务模式，只在会话启动时连接一次，后续调用走已有连接，体感快了很多。

如果你发现 MCP 偶发超时，第一反应不应该是加长时间，而是先看服务端日志。很多时候是服务端连接数到上限了，不是网络问题。

5. 子代理与自定义命令：把工作流分类固化

5.1 设计子代理而不是堆 Prompt

子代理本质上是一个有独立系统提示词和独立工具权限范围的“角色”。你可以把它理解成专家分工：主 Agent 负责统筹调度，子代理负责具体某类任务。每个子代理有自己的专业背景设定、可用的工具集和输出规范，主 Agent 会根据任务性质决定调用哪个子代理。

设计子代理最重要的一点是边界清晰。不是让主 Agent 把原来能做的事全拆给子代理，而是要把那些“重复的、专业性强的、对上下文质量要求高”的任务分离出去。比如代码评审是一个很典型的子代理场景：它只负责阅读代码、给出结论，它的工具集限定在文件读取和搜索之类，不包含写操作。这样既避免污染主上下文，又能保证评审视角的一致性。

我从实践里总结出来的子代理配置要素大致有这几个：明确的角色说明、输入输出格式约定、允许使用的工具列表、必须遵守的约束条件。其中约束条件最容易被忽略，但它往往决定了子代理输出质量的下限。比如一个写文档的子代理，如果约束条件里没有“所有操作步骤必须可验证”，它就可能凭想象写出一些不存在的命令。

5.2 自定义命令与模板变量

自定义命令用来把固定流程固化为一条指令。你要做的是在命令配置目录放一个 Markdown 文件，文件内容就是 Agent 要执行的提示词模板。当用户在会话里输入对应斜杠命令时，模板内容会作为提示词输入给 Agent。

自定义命令里的模板变量是它的核心亮点。你可以在模板里定义占位符，用户输入斜杠命令时可以带参数，这些参数会替换到模板里。比如说我经常用一条“生成周报”的命令，模板长这样：

你是一名项目负责人。 请根据以下用户描述，输出一份本周工作总结。 用户描述：{{description}} 输出格式： - 本周完成事项 - 遇到的阻塞和风险 - 下周计划

用户使用时直接输入/weekly dump这样的指令，后面那段“dump”就会作为变量值传入。这个功能极大降低了重复劳动。团队里其他人不需要知道怎么和 Agent 有效沟通，只需要记住几条纹路清晰的斜杠命令，就能获得一致性的输出。

自定义命令还有一种非常实用的变体：命令文件里包含多条子提示，或者引用多个文件，用来组织更复杂的流程。比如我可以建一条“提交代码前检查”命令，它会依次执行变更读取、静态检查、测试预览、生成提交说明。整个过程由模板里定义的步骤来驱动，比让用户手工一句一句引导 Agent 稳定得多。

6. 记忆与规范：CLAUDE.md 和 settings.json 的配合

6.1 CLAUDE.md 该写什么不该写什么

CLAUDE.md 是 Claude Code 的记忆文件，也是很多人最不会用的一层。我见过两种极端：要么一个字不写，所有规则都靠会话里反复重申；要么写了几百行，把什么都塞进去，结果 Agent 被一堆冗余信息干扰得平均表现反而不如不写。

正确姿势是把它当成“新接手项目的人应该看的文档 + 强制约束清单”的混合体。项目级的 CLAUDE.md 应该包含这些内容：项目是什么、技术栈是什么、目录结构怎么组织的、常用的构建和测试命令是什么、代码规范要点有哪些、绝对不能做的事有哪些。

写的时候有几个原则。第一，能不放的都不放，只有那些“每次会话都需要知道”的信息才值得写进去。第二，每条规则必须是可操作的，而不是空泛的口号。比如“代码要写得干净”就不合格，而“新增函数必须带类型注解，且单函数行数不超过 60 行”就合格。第三，把禁止事项放在文件靠前的位置，因为规则靠前意味着更高的优先级，防止 Agent 在长上下文中把它稀释掉。

用户级和项目级的 CLAUDE.md 是叠加生效的，所以要注意层级带来的优先级问题。用户级的习惯和偏好会被所有项目继承，团队协作时最好不要在用户级放太具体的项目规则。我自己会把“通用的行为偏好”放用户级，把“项目独有约束”放项目级，两边职责分明。

6.2 settings.json 的权限与运行参数

settings.json 承担的是运行参数和权限管理职责。你可以在这里控制模型选择、输出风格、环境变量、权限模式等。它和 CLAUDE.md 的关系可以这样理解：CLAUDE.md 管“规则和上下文”，settings.json 管“运行配置和权限边界”。

权限配置是 settings.json 里最值得花时间的部分。Claude Code 默认会有一些权限交互，你可以在这里设置权限模式，决定哪些工具需要确认、哪些工具允许直接执行、哪些工具禁止使用。我的建议是，最重要的工作目录和命令路径要显式允许，危险操作要显式禁止，中间地带保留交互确认。不要图省事全部放行，否则一旦出现 Prompt 注入或误调用，代价远大于配置时多花的时间。

环境变量也是经常被忽略的配置项。有些工具链需要特定的环境变量才能正常工作，把它们固化在设置文件里，能避免每次换机器都要手动 export。另一个实用技巧是，把调试相关的开关放到 settings.json 里，配合日志级别配置，能极大提升排查效率。

7. 常见问题与排查技巧实录

7.1 高频问题和排查表

我把实际使用中最高频的问题整理成了一张表，你们可以直接对照定位。

7.2 个人常用的定位手法

面对复杂问题时，我最常用的定位手段是开调试模式。它会输出非常详细的执行日志，包括 Agent 每步决策的推理过程、工具入参出参、钩子运行情况。一开始看这些日志会觉得很吵，但它能直接告诉你“Agent 以为自己在做什么”，这比瞎猜配置问题高效太多。

一个小技巧是分阶段验证。配置里改动了一个变量以后，不要一次验证三件事，只验证这一件事。比如钩子不生效，你先只配一个最简单的钩子，让它只打日志不做事，确认事件能被捕获，再逐步加上逻辑。这个过程听起来很笨，但它是排查钩子和插件问题最靠谱的方式。我见过一个同事为了省时间直接上了完整配置，最后排查了三天，发现只是钩子脚本里一个路径写错了。

还有一点，多利用日志文件的轮转和切分。长期运行的钩子和 MCP 服务会积累大量输出，如果你把调试级别开很高又不做轮转，可能第二天磁盘就满了。我习惯直接在脚本里配置定期清理，只保留最近几天的日志，这样既不影响排查，也不会让磁盘成为隐患。

最后分享一个我的个人体会：扩展体系的引入顺序比数量重要。我建议先立好 CLAUDE.md 和 settings.json 的权限边界，再上一个审计钩子，然后才考虑插件和 MCP。顺序反了的话，你会在能力铺开之后再回头补安全，那种情况下的返工成本会很高。希望这篇总览帮你把路线一次性规划明白。