ai-agent-deep-dive/README.md

# AI Agent Deep Dive

## Quick Links

- PDF 下载 / PDF Report: [claude-code-deep-dive-xelatex.pdf](./claude-code-deep-dive-xelatex.pdf)

## Notes

- 本仓库仅保留面向学习与评论的分析材料，不提供源码目录。
- 第二版 PDF 正在制作中。

---

# AI Agent Deep Dive Notes

> 这是一份围绕现代 Coding Agent 产品设计的学习型研究笔记，重点关注：整体架构、提示词系统、Agent 编排、Skills、Plugins、Hooks、MCP、权限与工具调用机制，以及这些系统为什么会让 Agent 产品更稳定、更好用。

---

## 目录

1. 研究范围与结论总览
2. 源码结构全景：它为什么更像 Agent Operating System
3. 系统提示词总装：`prompts.ts` 的真实地位
4. Prompt 全量提取与模块级拆解
5. Agent Prompt 与 built-in agents 深挖
6. Agent 调度链深挖：从 AgentTool 到 runAgent 再到 query
7. Skills / Plugins / Hooks / MCP 生态深挖
8. 权限、Hook、工具执行链深挖
9. 为什么 Claude Code 这么强：从源码看它真正的护城河
10. 关键文件索引与后续可继续深挖方向

---

# 1. 研究范围与结论总览

## 1.1 这次到底研究了什么

这份材料的核心目标，是围绕现代 Coding Agent 产品做系统性拆解，重点包括：

- Coding Agent 的整体架构
- 主系统提示词如何动态拼装
- AgentTool / SkillTool 的模型侧协议
- built-in agents 的角色分工
- Agent 调度链路如何跑通
- Plugin / Skill / Hook / MCP 如何接入并影响运行时
- Permission / Tool execution / Hook decision 如何协同
- 它为什么在体验上比“普通 LLM + 工具调用器”强很多

## 1.2 关键确认事实

本次研究重点关注了以下核心文件和模块：

1. 主系统提示词核心文件：
   - `src/constants/prompts.ts`
2. Agent Tool Prompt 核心文件：
   - `src/tools/AgentTool/prompt.ts`
3. Skill Tool Prompt 核心文件：
   - `src/tools/SkillTool/prompt.ts`
4. Agent 调度核心文件至少包括：
   - `src/tools/AgentTool/AgentTool.tsx`
   - `src/tools/AgentTool/runAgent.ts`
5. 工具执行链核心文件至少包括：
   - `src/services/tools/toolExecution.ts`
   - `src/services/tools/toolHooks.ts`

## 1.3 先给最重要的总判断

Claude Code 的强，不是来自某个“神秘 system prompt”，而是来自一个完整的软件工程系统：

- Prompt 不是静态文本，而是模块化 runtime assembly
- Tool 不是直接裸调，而是走 permission / hook / analytics / MCP-aware execution pipeline
- Agent 不是一个万能 worker，而是多种 built-in / fork / subagent 的分工系统
- Skill 不是说明文档，而是 prompt-native workflow package
- Plugin 不是外挂，而是 prompt + metadata + runtime constraint 的扩展机制
- MCP 不是单纯工具桥，而是同时能注入工具与行为说明的 integration plane

一句话总结：

> Claude Code 的价值，不是一段 prompt，而是一整套把 prompt、tool、permission、agent、skill、plugin、hook、MCP、cache 和产品体验统一起来的 Agent Operating System。

---

# 2. 源码结构全景：它为什么更像 Agent Operating System

## 2.1 顶层结构暴露出的系统复杂度

从相关目录结构看，Claude Code 至少有这些重要模块：

- `src/entrypoints/`：入口层
- `src/constants/`：prompt、系统常量、风险提示、输出规范
- `src/tools/`：工具定义与具体实现
- `src/services/`：运行时服务，例如 tools、mcp、analytics
- `src/utils/`：底层共用能力
- `src/commands/`：slash command 与命令系统
- `src/components/`：TUI / UI 组件
- `src/coordinator/`：协调器模式
- `src/memdir/`：记忆 / memory prompt
- `src/plugins/` 与 `src/utils/plugins/`：插件生态
- `src/hooks/` 与 `src/utils/hooks.js`：hook 系统
- `src/bootstrap/`：状态初始化
- `src/tasks/`：本地任务、远程任务、异步 agent 任务

这已经说明它不是简单 CLI 包装器，而是一个完整运行平台。

## 2.2 入口层说明它是平台，而不是单一界面

可见入口包括：

- `src/entrypoints/cli.tsx`
- `src/entrypoints/init.ts`
- `src/entrypoints/mcp.ts`
- `src/entrypoints/sdk/`

也就是说它从设计上就考虑了：

- 本地 CLI
- 初始化流程
- MCP 模式
- SDK 消费者

这是一种平台化思维：同一个 agent runtime，可以服务多个入口和多个交互表面。

## 2.3 命令系统是整个产品的操作面板

`src/commands.ts` 暴露出非常多系统级命令，例如：

- `/mcp`
- `/memory`
- `/permissions`
- `/hooks`
- `/plugin`
- `/reload-plugins`
- `/skills`
- `/tasks`
- `/plan`
- `/review`
- `/status`
- `/model`
- `/output-style`
- `/agents`
- `/sandbox-toggle`

这说明命令系统不是“锦上添花”，而是用户与系统运行时交互的重要控制面。

## 2.4 Tools 层才是模型真正“能做事”的根

从 prompt 和工具名能确认的重要工具包括：

- FileRead
- FileEdit
- FileWrite
- Bash
- Glob
- Grep
- TodoWrite
- TaskCreate
- AskUserQuestion
- Skill
- Agent
- MCPTool
- Sleep

工具层的本质，是把模型从“回答器”变成“执行体”。Claude Code 的强，很大程度来自这层做得正式、清晰、可治理。

---

# 3. 系统提示词总装：`prompts.ts` 的真实地位

## 3.1 真正的主入口：`src/constants/prompts.ts`

这份文件是整个系统最关键的源码之一。不是因为它写了一大段神奇文案，而是因为它承担了：

- 主系统提示词的总装配
- 环境信息注入
- 工具使用规范注入
- 安全与风险动作规范
- Session-specific guidance 注入
- language / output style 注入
- MCP instructions 注入
- memory prompt 注入
- scratchpad 说明注入
- function result clearing 提示注入
- brief / proactive / token budget 等 feature-gated section 注入

Claude Code 的 prompt 不是静态字符串，而是一个 **system prompt assembly architecture**。

## 3.2 `getSystemPrompt()` 不是文本，而是编排器

`getSystemPrompt()` 里最核心的结构，是先构造静态部分，再加上动态部分。你可以把它理解成：

### 静态前缀（更适合 cache）
- `getSimpleIntroSection()`
- `getSimpleSystemSection()`
- `getSimpleDoingTasksSection()`
- `getActionsSection()`
- `getUsingYourToolsSection()`
- `getSimpleToneAndStyleSection()`
- `getOutputEfficiencySection()`

### 动态后缀（按会话条件注入）
- session guidance
- memory
- env info
- language
- output style
- mcp instructions
- scratchpad
- function result clearing
- summarize tool results
- token budget
- brief

这个设计非常值钱，因为它不是“把能想到的都写进 system prompt”，而是把 prompt 当作可编排运行时资源来管理。

---

# 4. Prompt 全量提取与模块级拆解

## 4.1 身份与基础定位

系统提示词会先定义它是 interactive agent，并明确它是帮助用户完成软件工程任务的，不是普通聊天机器人。

## 4.2 基础系统规范

这里会规定：

- 所有非工具输出都直接给用户看
- 工具运行在 permission mode 下
- 用户拒绝后不能原样重试
- tool result 可能含系统提醒或外部内容
- 需要对 prompt injection 保持警惕

## 4.3 做任务哲学

它非常强调：

- 不要乱加功能
- 不要过度抽象
- 不要瞎重构
- 先读代码再改代码
- 不要轻易创建新文件
- 结果要诚实汇报

这部分是它稳定性的关键来源之一。

---

# 5. Agent Prompt 与 built-in agents 深挖

## 5.1 AgentTool Prompt 的价值

这份 prompt 本质上是在告诉模型：

- 何时该启动 agent
- 何时该 fork 自己
- 何时不该用 AgentTool
- 如何正确地写 subagent prompt

## 5.2 built-in agents 的意义

内建 agents 至少包括：

- General Purpose Agent
- Explore Agent
- Plan Agent
- Verification Agent

这说明它不是一个万能 worker，而是通过角色分工来提高稳定性。

## 5.3 Verification Agent 为什么值钱

Verification Agent 的核心不是“再看一眼”，而是主动去验证、去尝试打破实现。它要求 build、tests、type-check、真实命令输出和最终 verdict，这对提高任务完成质量非常关键。

---

# 6. Agent 调度链深挖

## 6.1 总体调度链

主链路可以抽象为：

1. 主模型决定调用 Agent 工具
2. AgentTool 解析输入并选择路径
3. 判断 fork / normal / background / remote / worktree
4. 构造 prompt messages 与 system prompt
5. 组装工具池与上下文
6. 调用 `runAgent()`
7. `runAgent()` 再进入 `query()` 主循环

## 6.2 为什么这个调度链重要

因为这说明 agent execution 不是简单“开个新会话”，而是一个完整的 runtime lifecycle。

---

# 7. Skills / Plugins / Hooks / MCP 生态深挖

## 7.1 Skill 的本质

Skill 不是文档，而是可复用的 workflow package。它让系统能把重复流程变成按需注入的 prompt 资产。

## 7.2 Plugin 的本质

Plugin 不是普通脚本扩展，而是 prompt、metadata 和 runtime constraints 的组合包。

## 7.3 Hook 的本质

Hook 是运行时治理层，它可以改输入、给权限建议、阻止继续执行、注入上下文。

## 7.4 MCP 的本质

MCP 不只是工具桥，还能通过 instructions 影响模型如何理解和使用这些工具。

---

# 8. 权限、Hook、工具执行链深挖

Claude Code 的工具调用并不是模型直接裸调，而是完整的 runtime pipeline：

- schema 校验
- validateInput
- pre-tool hooks
- permission decision
- tool call
- telemetry
- post-tool hooks
- failure hooks

这也是它比很多“会调工具的 Agent”更稳定的重要原因。

---

# 9. 为什么 Claude Code 这么强

最核心的原因不是模型更聪明一点，而是它把这些东西系统化了：

- Prompt architecture
- Tool runtime governance
- Permission model
- Agent specialization
- Skill workflow packaging
- Plugin / MCP extensibility
- Context hygiene
- Async/background lifecycle
- Product-level engineering

所以它真正厉害的不是某一句 prompt，而是整个 operating model。

---

# 10. 最终结论

> Claude Code 的真正价值，不是一段 system prompt，而是一个把 prompt architecture、tool runtime、permission model、agent orchestration、skill packaging、plugin system、hooks governance、MCP integration、context hygiene 和 product engineering 统一起来的系统。

这也是为什么它不像一个“会调工具的聊天机器人”，而更像一个真正的 Agent Operating System。