> **来源：[研报客](https://pc.yanbaoke.cn)** ```markdown # Claude Code 源码深度研究报告总结 ## 核心内容概述 Claude Code 是一个基于 prompt 的 Agent Operating System，其设计融合了提示词架构、工具执行治理、权限控制、Agent 分工、Skill 包装、Hook 政策、MCP 集成等多层机制，构建了一个可扩展、可治理、可产品化的系统。它不是简单地调用工具，而是通过系统级设计，将模型行为、工具调用、权限判断、上下文管理等统一起来。 ## 主要观点 - **系统不是一个 prompt，而是一个 operating model** 它通过结构化提示词、工具执行链、权限模型、Hook 政策等构建了一个完整的系统框架，而非依赖单一的 system prompt。 - **Prompt 是模块化、可编排的 runtime assembly** 源码中的 `prompts.ts` 不仅是提示词，更是系统提示词的编排器，能够动态拼接静态前缀与动态后缀，支持运行时注入。 - **Agent 不是万能 worker，而是分工明确的系统角色** Explore Agent、Plan Agent、Verification Agent 等内建 Agent 有清晰的职责划分，避免行为漂移和混乱。 - **工具执行链是权限、Hook、MCP 三重治理下的流程** 工具调用前需要输入校验、Hook 拦截、权限决策，确保执行安全和可控。 - **生态不是“可安装”，而是“模型可感知”** 通过 Skill、Plugin、Hook、MCP 的方式，系统让模型能感知并合理使用扩展能力，提升交互质量。 - **上下文是稀缺资源，系统通过 cache 与 context 继承进行优化** fork path 与 parent context 的共享机制，确保子任务执行时能复用主线程的 cache，降低 token 成本。 ## 关键信息 ### 源码结构全景 - **顶层结构复杂**：包含入口层、常量层、工具层、服务层、组件层、协调层、记忆层、插件层等。 - **入口层支持多种交互模式**：包括本地 CLI、MCP 模式、SDK 消费者等，体现平台化思维。 - **命令系统是核心控制面**：提供如 `/mcp`、`/memory`、`/permissions`、`/skills` 等系统级命令，用于管理运行时状态和行为。 ### 系统提示词总装 - **核心文件：src/constants/prompts.ts** 负责主系统提示词的动态拼装，包括身份、系统规范、任务哲学、风险规范、工具使用规范等。 - **prompt 是可编排的 runtime 构造** 通过 `getSystemPrompt()` 构造提示词，分为静态前缀与动态后缀，支持运行时注入。 - **Prompt Cache Boundary** 明确区分静态与动态部分，确保 cache 有效性和运行时可控性。 ### Agent Prompt 与 built-in agents - **AgentTool/prompt.ts** 是 Agent 协议说明书，规定了如何展示 Agent 列表、如何定义子 Agent 类型、如何区分 fork 与 fresh agent 等。 - **fork 机制优化 cache 和 context 继承** fork 时继承父上下文，使用相同 prompt cache，减少 token 消耗。 - **built-in agents 职责分工明确** Explore Agent 专注读取，Plan Agent 专注规划，Verification Agent 专注验证，避免角色混杂。 ### Agent 调度链深挖 - **调度链包括**：AgentTool.call() → runAgent() → query() 其中 AgentTool 是调度控制器，runAgent() 是子 Agent 的 runtime 构造器，query() 是主循环执行器。 - **fork 与 normal path 分叉** fork 优化缓存命中，normal path 独立构造 agent prompt。 - **background 与 foreground 生命周期分离** background agent 可异步运行，foreground agent 需等待结果，体现产品化设计。 ### Skills / Plugins / Hooks / MCP 生态 - **Skill 是 workflow package** 通过 frontmatter 定义，支持按需注入，并可与 MCP 集成。 - **Plugin 是 prompt + metadata + runtime constraint 的扩展单元** 支持环境变量注入、权限控制、运行时约束，提升系统灵活性。 - **Hook 是运行时治理层** 支持 PreToolUse、PostToolUse、PostToolUseFailure，能拦截、修改、补充、阻断执行流程。 - **MCP 是行为注入通道** 可注入新工具和行为说明，提升模型的扩展性和行为控制能力。 ### 权限、Hook、工具执行链 - **工具执行链是权限、Hook、MCP 的组合流程** 工具调用前需校验输入、执行 Hook 拦截、根据权限决策执行。 - **Hook 与权限耦合成熟** Hook 可提供 allow / ask / deny 决策，但不能绕过权限模型。 - **工具执行后仍需 Hook 处理** 成功或失败后，Hook 可追加信息、注入上下文、更新 MCP 输出，确保流程可控。 ### 护城河与系统优势 - **Agent Operating System 的设计优势** 包括 prompt 架构、tool runtime、权限模型、agent orchestration、skill packaging、hook governance、MCP integration、context hygiene 和产品工程。 - **制度化“好行为”** 通过提示词和运行时规则，确保模型行为一致，避免随意生成、过度抽象、未验证执行等问题。 - **用户体验与产品化设计** 输出高效、统一交互风格、提供可恢复的 transcript 和 metadata，体现产品级思维。 ## 关键文件索引 ### 核心 Prompt 文件 - `src/constants/prompts.ts`：主系统提示词总装配 - `src/tools/AgentTool/prompt.ts`：Agent 工具提示词 - `src/tools/SkillTool/prompt.ts`：Skill 工具提示词 - `src/tools/FileReadTool/prompt.ts`、`src/tools/GlobTool/prompt.ts` 等：工具级提示词 ### 核心 Agent 文件 - `src/tools/AgentTool/AgentTool.tsx`：Agent 工具主文件 - `src/tools/AgentTool/runAgent.ts`：子 Agent 运行时处理 - `src/tools/AgentTool/built-in/exploreAgent.ts`、`planAgent.ts`、`verificationAgent.ts`：内建 Agent 实现 ### 核心 Skill / Plugin / Hook / MCP 文件 - `src/tools/SkillTool/constants.ts`、`prompt.ts`：Skill 工具定义 - `src/utils/plugins/PluginCommands.ts`：插件命令处理 - `src/services/tools/toolHooks.ts`：Hook 系统 - `src/services/mcp/types.ts`、`normalization.ts` 等：MCP 系统定义与集成 ## 后续可继续深挖方向 - `query.ts`：主会话循环与模型交互流 - `resumeAgent.ts`：Agent 恢复机制 - `loadSkillsDir`：Skill 完整加载链 - `pluginLoader`：插件加载与内建插件生态 - `systemPromptSections.ts`：Prompt section 注册细节 - `coordinator/*`：多 Agent 协调器模式 - `attachments.ts`：Skill / Agent 列表与 MCP delta 的消息注入方式 - `AgentSummary`：后台 Agent 进度总结机制 ## 最终结论 Claude Code 的真正价值不在于某一段提示词，而在于它构建了一个完整的 Agent Operating System。通过将 prompt、tool、permission、agent、skill、hook、MCP 等元素统一起来，它实现了高度可扩展、可治理、可产品化的交互系统，使其在体验上远超“普通 LLM + 工具调用器”的组合。 ```