xhj的博客

第 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 条件注...

第 8 篇：Thinking 与推理控制 — 让模型”想”多少 本篇是《深入 Claude Code 源码》系列的第 8 篇。我们将深入分析 Claude Code 如何精细控制模型的推理深度——从 Extended Thinking 的三种模式、Effort 级别系统、ultrathink 关键词触发，到 Advisor 这一”更强模型审阅”机制。 这些机制共同回答了一个核心问题：在速度、质量和成本之间，如何给用户最大的控制权？ 为什么需要推理控制？大语言模型的推理能力不是免费的。当模型”想得更深”时，它消耗更多的 token、花费更多的时间、产生更高的成本。但并非所有任务都需要深度推理——重命名一个变量和重构整个模块的架构，需要的思考量天差地别。 Claude Code 面对的工程挑战是：如何让用户（和系统）灵活地在”快速响应”和”深度思考”之间切换，同时确保不同模型版本的行为一致性？ 源码中围绕这个问题构建了四个相互关联的子系统： ThinkingConfig — 控制模型是否开启 Extended Thinking 及其模式 Effort — 控制模型的推理努力程度（...

第 7 篇：Prompt Cache — 跨模块的缓存策略如何降低 API 成本 本篇是《深入 Claude Code 源码》系列的第 7 篇。我们将从一个横切视角，解析 Prompt Cache 机制如何贯穿 System Prompt、对话循环、上下文管理三大模块，以及 Fork Agent 如何通过精密的参数对齐实现跨进程缓存共享。 为什么需要理解 Prompt Cache？调用大模型 API 最大的成本来自 input tokens。在一个典型的 Claude Code 交互式会话中，每次用户提问都会把完整的 System Prompt（约 2 万 token）、工具定义（几千 token）、以及之前所有的对话历史一起发送给 API。如果对话进行了 50 轮，每轮平均 5 万 input tokens，那一个会话就消耗 250 万 input tokens。 Anthropic 的 Prompt Caching 机制可以将 重复前缀 的成本降低 90%。服务端会缓存请求前缀（System Prompt + 工具定义 + 消息历史前缀），只要下次请求的前缀字节完全一致，就...