Claude_Code_源码深度研究报告_26页_334kb

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 + 工具调用器”的组合。