xhj的博客

第 18 篇：Hooks 系统 — 用 Shell 命令扩展 AI 行为 本篇是《深入 Claude Code 源码》系列第 18 篇。我们将深入 Hooks 系统的完整实现，揭示 Claude Code 如何让用户在 AI 生命周期的关键节点注入自定义逻辑，以及这套系统在安全性、可扩展性和性能上的精巧设计。 为什么需要 Hooks？想象一个场景：你希望 Claude Code 在每次执行 Write 工具后自动运行 prettier 格式化代码，或者在 Session 启动时自动加载项目特定的环境变量，又或者在模型即将结束回答时用一个验证脚本检查代码质量。 这些需求有一个共同特征：它们不是 AI 本身的能力，而是用户希望在 AI 工作流的特定节点注入的自定义行为。 Hooks 系统正是为此而生。它是 Claude Code 的”生命周期钩子”框架 —— 类似于 Git Hooks、Webpack Plugins 或 React 的 useEffect，但面向的是 AI Agent 的执行周期。用户通过 settings.json 声明：在哪个事件（event）、匹配什么条件（...

第 17 篇：Settings 系统 — 多层配置的合并之道 本篇是《深入 Claude Code 源码》系列第 17 篇。我们将剖析 Settings 系统如何从 5 个正式配置源（加 1 个 Plugin 基底层）中读取、验证、合并配置，以及如何在运行时监听变更并热更新 —— 一个面向企业级部署的多层配置合并架构。 为什么需要多层配置？一个 CLI 工具的配置需求看似简单 —— 用户写一个 JSON 文件就行了。但 Claude Code 面对的现实远比这复杂： 个人偏好 —— 用户想全局设置自己偏好的模型、权限规则 团队共享 —— 项目组要把 MCP 服务器、Hook 脚本提交到 Git 仓库共享 本地覆盖 —— 个人本地调试需要覆盖项目设置，但不能提交到 Git 企业管控 —— 安全团队需要强制启用沙箱、禁用危险权限，且用户不能覆盖 远程策略 —— 企业管理员通过 API 远程下发配置，无需触碰每台机器 平台差异 —— macOS 用 plist + MDM、Windows 用注册表、Linux 用文件 这些需求层层叠加，任何单一配置文件都无法满足。Claude C...

第 16 篇：权限系统 — AI 安全的最后一道防线 本篇是《深入 Claude Code 源码》系列第 16 篇。我们将深入权限系统的完整架构：从权限模式、规则体系、决策管线到 AI Classifier 辅助判断，揭示一个生产级 AI Agent 如何在”自动化”与”安全”之间找到平衡。 为什么权限系统是 AI 产品中最关键的模块？传统 CLI 工具的权限模型很简单——用户敲什么命令就执行什么命令，责任完全在用户。但 AI Agent 改变了这个范式：模型自主决定执行什么操作。用户说”帮我重构这个项目”，模型可能决定删除文件、执行 shell 命令、修改配置——这些操作的风险程度天差地别。 这意味着，AI 产品的权限系统面临独特的挑战： 操作不可预测：用户无法提前知道模型会调用哪些工具、传入什么参数 风险谱系宽广：从读取文件（无害）到 rm -rf /（灾难性），所有操作都通过同一个工具接口 效率与安全的矛盾：每次都弹确认对话框会让用户抓狂，但完全自动化又有安全风险 Claude Code 的权限系统用 多层防线 + 渐进式信任 的方式解决了这个矛盾。本篇将从三个层面解...

第 15 篇：MCP 协议实现 — 连接外部工具的标准化桥梁 本篇是《深入 Claude Code 源码》系列的第 15 篇。我们将剖析 Claude Code 如何实现 Model Context Protocol（MCP），包括类型系统设计、多层配置合并、传输层适配、连接生命周期管理、Tool 发现与代理，以及认证体系。 为什么需要 MCP？Claude Code 内置了 40+ 个工具（BashTool、FileEditTool、GlobTool 等），足以覆盖大部分编程场景。但真实世界的开发远不止于此——你可能需要查询 Jira 看板、操作 Slack 消息、调用公司内部的 API 网关、访问 GitHub Issues……这些能力不可能全部内置，也不应该内置。 Model Context Protocol（MCP） 就是这个问题的答案。它是 Anthropic 提出的一个开放标准，定义了 AI 应用（Client）与外部工具/数据服务（Server）之间的通信协议。可以把 MCP 理解为 AI 世界的 “USB 接口”——只要服务实现了 MCP 协议，Cla...

第 14 篇：任务系统 — Agent 的并发执行引擎 本篇是《深入 Claude Code 源码》系列的第 14 篇。我们将深入分析 Claude Code 如何通过一套统一的任务系统，管理从后台 Shell 命令到多 Agent 并行协作的所有异步工作。 为什么需要任务系统？在前几篇中，我们已经见过了 Agent 系统（第 12 篇）和内置 Agent 设计模式（第 13 篇）。但有一个关键问题尚未解决：当模型同时发起多个 Agent、多个后台 Shell 命令、甚至一个”做梦”式的记忆整理任务时，这些并发工作如何被统一管理？ 想象一个真实场景：Coordinator 模式下，主 Agent 同时派出 3 个 Worker 去研究代码库的不同部分，每个 Worker 又可能启动自己的后台 Shell 命令。此时系统需要： 追踪所有任务的生命周期（pending → running → completed/failed/killed） 安全地终止任务（包括清理子进程、释放文件句柄） 收集并转发任务输出（任务完成时通知主 Agent） 隔离任务状态（一个任...

第 13 篇：内置 Agent 设计模式 — Explore、Plan、Verification 的 Prompt 设计 本篇是《深入 Claude Code 源码》系列第 13 篇。我们将深入 6 个内置 Agent 的 System Prompt 设计，揭示如何通过 prompt 工程将同一套工具系统塑造出截然不同的 Agent 人格与行为模式，并解析自定义 Agent 的 markdown frontmatter 配置全貌。 为什么需要内置 Agent？在第 12 篇中，我们了解了 Agent 系统的整体架构 —— AgentDefinition 数据结构、runAgent() 生命周期、createSubagentContext() 的隔离机制。但架构只是骨架，真正赋予 Agent “灵魂”的是它们的 System Prompt 设计。 一个核心问题：Claude Code 拥有 40+ 个工具，为什么不让一个通用 Agent 做所有事？答案藏在工程实践中： 成本控制 —— Explore Agent 用 Haiku 模型就够了，不需要用 Opus 来做文件搜索 安全...

第 12 篇：Agent 系统 — 从单体到多智能体协作 本篇是《深入 Claude Code 源码》系列的第 12 篇。我们将深入剖析 Agent 子系统的完整架构：从 Agent 定义的数据结构与加载机制，到 runAgent() 的完整生命周期，再到 createSubagentContext() 如何实现 context 隔离与选择性共享。 为什么需要多 Agent？当你让 Claude Code 帮你”重构整个模块的测试”时，一个单体 Agent 会怎么做？它会搜索文件、阅读代码、编写测试、运行验证——所有步骤串行执行，上下文窗口迅速膨胀。更糟糕的是，搜索过程中产生的大量中间输出（grep 结果、文件内容）会永久占据上下文，挤压真正有价值的信息空间。 Claude Code 的解决方案是多 Agent 协作：主 Agent 可以按需生成子 Agent，每个子 Agent 拥有独立的上下文窗口和对话循环，完成任务后只返回精炼的结果。这就像一个团队 lead 把任务分派给专人，每个人独立工作后汇报结论。 这个设计解决了三个核心问题： 上下文污染：搜索类任务的海量中间输出...

第 11 篇：命令系统 — 斜杠命令的聚合与扩展架构 本篇是《深入 Claude Code 源码》系列第 11 篇。我们将深入 commands.ts 及其周边模块，揭示 Claude Code 如何将内建命令、用户自定义 Skill、Plugin 命令、Bundled Skill、MCP Skill 和 Workflow 命令统一到一套类型体系中，并实现懒加载、条件注册和动态发现。 为什么需要一个命令系统？当你在 Claude Code REPL 里输入 /commit、/compact、/review 时，你用的是斜杠命令（Slash Command）。这些命令看起来只是快捷操作，但在 Claude Code 中，它们承载着远比表面复杂的职责： 有的命令本地执行（如 /clear 清空对话历史） 有的命令生成 Prompt 发给模型（如 /commit 生成代码审查提示词） 有的命令需要渲染交互式 UI（如 /config 弹出配置面板） 有的命令来自用户自定义 Skill（.claude/skills/ 目录下的 Markdown 文件） 有的命令来自第三方 Plugi...

第 10 篇：BashTool 深度剖析 — 最复杂的单个工具 本篇是《深入 Claude Code 源码》系列第 10 篇。BashTool 是 Claude Code 中代码量最大、安全逻辑最复杂的单个工具，总计约 12,400 行代码。我们将从命令语义分析、多层安全防线、沙箱执行、输出处理、权限匹配五个维度，完整剖析它如何让 AI 安全地执行 Shell 命令。 为什么 BashTool 是最复杂的工具？在第 9 篇中我们了解了 buildTool() 的抽象体系和 Tool 接口的设计。所有工具都遵循相同的 name / inputSchema / call() / checkPermissions() 协议。但 BashTool 的特殊之处在于：它是唯一一个允许 AI 在用户机器上执行任意代码的工具。 这意味着它必须同时解决两个相互矛盾的需求： 足够强大 — AI 需要通过 Shell 命令完成 git 操作、运行测试、安装依赖、查看日志等几乎一切任务 足够安全 — 绝不能让 AI（或通过 prompt injection 操控 AI 的攻击者）执行破坏性操作 这...

第 9 篇：工具系统设计 — buildTool() 的抽象之美 本篇是《深入 Claude Code 源码》系列的第 9 篇。我们将深入工具系统的核心设计：从 Tool 接口的核心方法，到 buildTool() 的 builder 模式，到 tools.ts 的注册表架构，再到 ToolSearch 的延迟加载机制，揭示一个生产级 AI Agent 如何管理 40+ 个内置工具和无限数量的 MCP 工具。 为什么工具系统是 Agent 的灵魂？一个 AI Agent 与普通 chatbot 的本质区别在于：Agent 能执行动作。当模型决定读取一个文件、运行一条 Shell 命令、或搜索代码时，它依赖的就是工具系统。 Claude Code 拥有 40+ 个内置工具（BashTool、FileReadTool、GlobTool……）和通过 MCP 协议接入的无限数量外部工具。管理这样规模的工具集面临几个核心挑战： 接口一致性：每个工具需要统一的调用、验证、权限检查、UI 渲染协议 安全默认：工具涉及文件系统和 Shell 操作，默认行为必须 fail-closed 条件注...