基于 Claude Code 泄露源码的系统化课程，从零构建对生产级 AI Agent 的完整认知。
课程总览
模块一：基础认知 [第 01-03 课] ← 无前置依赖
模块二：启动与状态 [第 04-06 课] ← 依赖模块一
模块三：Agent 核心循环 [第 07-09 课] ← 依赖模块二
模块四：工具系统 [第 10-14 课] ← 依赖模块三
模块五：权限体系 [第 15-16 课] ← 依赖模块四
模块六：System Prompt [第 17-19 课] ← 依赖模块三、五
模块七：记忆与上下文 [第 20-22 课] ← 依赖模块六
模块八：MCP 协议 [第 23-24 课] ← 依赖模块四
模块九：多 Agent 架构 [第 25-27 课] ← 依赖模块四、五、六
模块十：扩展与 UI [第 28-30 课] ← 依赖全部
知识依赖图
┌──────────┐
│ 模块一 │
│ 基础认知 │
└────┬─────┘
│
┌────▼─────┐
│ 模块二 │
│ 启动状态 │
└────┬─────┘
│
┌────▼─────┐
│ 模块三 │
│ Agent 循环│
└────┬─────┘
│
┌────▼─────┐
┌─────┤ 模块四 ├─────┐
│ │ 工具系统 │ │
│ └────┬─────┘ │
│ │ │
┌────▼─────┐ │ ┌─────▼────┐
│ 模块五 │ │ │ 模块八 │
│ 权限体系 │ │ │ MCP 协议 │
└────┬─────┘ │ └──────────┘
│ │
┌────▼──────────▼┐
│ 模块六 │
│ System Prompt │
└────┬────────────┘
│
┌─────────┼──────────┐
│ │ │
┌───▼───┐ ┌──▼────┐ ┌───▼──────┐
│模块七 │ │模块九 │ │ 模块十 │
│记忆 │ │多Agent│ │ 扩展与UI │
└───────┘ └───────┘ └──────────┘
模块一：基础认知（第 01-03 课）
目标：建立全局视角，理解项目的技术选型和架构哲学。
第 01 课：全局架构鸟瞰
学习目标： 能画出 Claude Code 的核心模块关系图，理解一次用户交互的完整数据流。
核心内容：
- Claude Code 是什么：一个基于 React 的终端 AI Agent，不仅仅是 CLI
- 核心数据流：用户输入 → REPL → query() → Claude API → tool_use → 工具执行 → 结果返回
- 目录结构全景：按职责分类理解 50+ 顶层目录的归属
重点文件：
README.md— 项目概览（来自社区分析）- 顶层目录结构
课后练习：
- 绘制 Claude Code 的模块关系图
- 列出你认为最核心的 5 个目录并说明理由
第 02 课：技术栈深度解析
学习目标： 理解 Claude Code 选择 Bun + React/Ink + TypeScript + Zod 的技术决策及其协作方式。
前置依赖： 第 01 课
核心内容：
- Bun 作为运行时和打包器：为何不用 Node.js？
feature()来自bun:bundle - React/Ink 在终端中的应用：
ink/目录是一个完整的终端 React 渲染器 - TypeScript 的类型驱动设计：Zod schema 同时作为运行时校验和类型推导
- 关键依赖：
@anthropic-ai/sdk（API 客户端）、@modelcontextprotocol/sdk（MCP）
重点文件：
ink/— 终端 React 渲染引擎（50+ 文件）Tool.ts第 10 行 —zfromzod/v4的使用
课后练习：
- 阅读 Ink 官方文档，理解 React 如何渲染到终端
- 对比 Bun 和 Node.js 的打包差异，理解
feature()的编译时替换原理
第 03 课：Feature Gate 双层体系
学习目标： 掌握编译时 feature flag 和运行时 GrowthBook 的协作模式，理解同一份代码如何产出内部/外部两种构建。
前置依赖： 第 02 课
核心内容：
- 编译时 Feature Gate：
feature('COORDINATOR_MODE')、feature('KAIROS')等 12 个开关 - 死代码消除（DCE）：
feature()返回 false → 整个 if 分支被移除 - 运行时 Feature Flag：GrowthBook 管理的
tengu_前缀开关 getFeatureValue_CACHED_MAY_BE_STALE()— 缓存策略的性能取舍USER_TYPE === 'ant'— Anthropic 内部功能隔离
重点文件：
query.ts第 15-21 行 —feature('REACTIVE_COMPACT')的条件加载constants/betas.ts— API Beta Feature 协商列表
课后练习：
- 搜索所有
feature(调用，列出完整的编译时开关清单 - 搜索
tengu_前缀，统计运行时 flag 数量并分类
模块二：启动与状态（第 04-06 课）
目标：理解应用从启动到就绪的完整生命周期，以及状态如何流转。
第 04 课：入口与启动流程
学习目标： 追踪从 node cli.js 到 REPL 就绪的完整启动链路。
前置依赖： 第 01-03 课
核心内容：
- 三个入口点：
entrypoints/cli.tsx（CLI）、entrypoints/mcp.ts（MCP Server）、entrypoints/sdk/（Agent SDK） cli.tsx启动顺序：版本快速路径 → OAuth/Settings 预取 → 权限初始化 → MCP 配置加载 → 工具注册 → REPL 启动init.ts：初始化序列（环境检测、配置加载、迁移执行）main.tsx（803KB）：所有模块在此汇聚，理解其作为"粘合层"的角色migrations/目录：16 个迁移脚本，揭示产品演化历史（Fennec → Opus, Sonnet1m → Sonnet45 → Sonnet46）
重点文件：
entrypoints/cli.tsx— 主 CLI 入口entrypoints/init.ts— 初始化序列main.tsx— 粘合层（建议先看导入部分，不必通读）
课后练习：
- 画出启动流程时序图：cli.tsx → init.ts → main.tsx → REPL
- 阅读
migrations/中的文件名，推断产品版本演化时间线
第 05 课：状态管理架构
学习目标： 理解 AppState 的结构设计、Store 模式和不可变更新策略。
前置依赖： 第 04 课
核心内容：
state/AppStateStore.ts— AppState 的完整形状定义：messages, tools, permissions, speculation, plugins, MCP connections, notifications, UI statestate/store.ts— 泛型Store<T>模式：getState()/setState(updater)/subscribe(listener)- 不可变更新：所有状态变更通过
setState(prev => ({...prev, field: newValue}))完成 state/AppState.tsx— React Provider 包装，注入 MailboxProvider / VoiceProviderstate/onChangeAppState.ts— 变更传播与副作用触发state/selectors.ts— 状态查询辅助函数
重点文件：
state/AppStateStore.ts— AppState 类型定义state/store.ts— Store 实现state/AppState.tsx— React Provider
课后练习：
- 列出 AppState 中所有顶层字段，按"核心/UI/扩展"分类
- 对比 Redux 和此 Store 模式的异同
第 06 课：REPL 交互循环
学习目标： 理解用户输入如何被接收、处理，以及响应如何渲染到终端。
前置依赖： 第 05 课
核心内容：
screens/REPL.tsx— 主交互界面，管理 UI 状态、权限、消息历史、钩子执行- 用户输入流：PromptInput 组件 → 消息创建 → query() 调用 → 流式响应 → 工具执行 → 结果渲染
- 权限交互：工具调用触发权限请求 → 用户 approve/deny → 继续/中止
- 会话管理：
screens/ResumeConversation.tsx— 会话恢复 - 健康检查：
screens/Doctor.tsx— 诊断界面
重点文件：
screens/REPL.tsx— 核心交互屏幕components/PromptInput/— 用户输入组件components/MessageSelector/— 消息展示组件
课后练习：
- 追踪一次完整的用户输入到响应显示的代码路径
- 找到权限请求弹窗的触发逻辑
模块三：Agent 核心循环（第 07-09 课）
目标：深入 Agent 的"心脏" — 理解 Claude Code 如何与 API 交互、调度工具、管理对话。
第 07 课：query.ts — Agent 循环的心脏
学习目标： 完整理解一次 API 调用的生命周期：构建请求、流式处理、工具分发、错误恢复。
前置依赖： 第 06 课
核心内容：
query()函数的核心职责：发送消息到 Claude API → 接收流式响应 → 处理tool_use块 → 执行工具 → 收集结果 → 决定是否继续- 流式处理：
StreamEvent类型（RequestStartEvent,ToolUseSummaryMessage,TombstoneMessage等） - 工具分发：
findToolByName()定位工具 →ToolUseContext传递执行上下文 - 错误恢复：
FallbackTriggeredError重试机制、PROMPT_TOO_LONG_ERROR_MESSAGE处理 - 自动压缩触发：
isAutoCompactEnabled()+calculateTokenWarningState()决定何时压缩上下文
重点文件：
query.ts— 核心 Agent 循环QueryEngine.ts— 查询引擎封装services/api/withRetry.ts— 重试策略
课后练习：
- 在 query.ts 中标注"API 调用"、"工具执行"、"压缩触发"三个关键分支点
- 理解
normalizeMessagesForAPI()做了哪些消息格式化
第 08 课：消息类型与对话流转
学习目标： 掌握所有消息类型及其在对话中的角色，理解消息如何在系统中流转。
前置依赖： 第 07 课
核心内容：
- 消息类型体系（
types/message.ts）：UserMessage— 用户输入AssistantMessage— Claude 响应SystemMessage— 系统指令SystemLocalCommandMessage— 本地命令（如 /help, /clear）AttachmentMessage— 附件（图片、文件）ProgressMessage— 工具执行进度ToolUseSummaryMessage— 工具调用摘要TombstoneMessage— 已被压缩的消息占位符
- 消息工具函数（
utils/messages.ts）：createUserMessage(),createUserInterruptionMessage()— 用户消息创建normalizeMessagesForAPI()— API 格式化getMessagesAfterCompactBoundary()— 压缩边界后的消息提取stripSignatureBlocks()— 签名块清理
重点文件：
types/message.ts— 消息类型定义utils/messages.ts— 消息工具函数
课后练习：
- 画出消息类型的继承/组合关系图
- 追踪一条
UserMessage从创建到被 API 消费的完整路径
第 09 课：上下文构建
学习目标： 理解 Claude Code 如何为每次 API 调用构建丰富的上下文信息。
前置依赖： 第 08 课
核心内容：
context.ts— 上下文主文件：getGitStatus()— 带缓存的 Git 状态获取（分支、状态、日志、用户信息）getUserContext()/getSystemContext()— 记忆化的上下文构建
- 上下文数据源：
- Git 信息（当前分支、未提交变更、最近提交）
- 环境信息（平台、Shell、OS 版本、模型名称）
- 工作目录（cwd、是否 Git 仓库）
- 活跃文件和最近编辑
context/目录 — React Context Providers：notifications.tsx— 通知上下文mailbox.tsx— Agent 间邮箱voice.tsx— 语音上下文stats.tsx,fpsMetrics.tsx— 性能指标
重点文件：
context.ts— 上下文构建主逻辑context/— React Context 集合
课后练习：
- 列出
computeEnvInfo()收集的所有环境变量 - 理解 Git 信息缓存策略：什么时候刷新？缓存多久？
模块四：工具系统（第 10-14 课）
目标：深入理解 AI Agent 最核心的能力 — 工具系统的设计与实现。
第 10 课：Tool.ts — 工具接口设计
学习目标： 掌握 Tool 接口的完整定义，理解一个工具从注册到执行的完整生命周期。
前置依赖： 第 07 课
核心内容：
Tool<Input, Output, ProgressData>泛型接口：- 核心方法：
call()执行、description()描述、prompt()提示词 - 校验：
inputSchema（Zod）、inputJSONSchema（JSON Schema）、validateInput() - 权限：
checkPermissions()→{behavior: 'allow'|'ask'|'deny', updatedInput} - 元数据：
isReadOnly(),isDestructive(),isConcurrencySafe(),interruptBehavior() - 展示：
renderToolUseMessage(),renderToolResultMessage(),renderToolUseProgressMessage() - 延迟加载：
shouldDefer,alwaysLoad— ToolSearch 集成
- 核心方法：
buildTool()工厂函数：fail-closed 默认值（不安全操作默认拒绝）findToolByName()— query.ts 中的工具查找入口ToolUseContext— 工具执行上下文（传递 AppState、权限、会话信息）
重点文件：
Tool.ts— 完整接口定义（约 300 行类型）
课后练习：
- 手动实现一个符合 Tool 接口的最简工具（伪代码即可）
- 思考：为什么
buildTool()选择 fail-closed 默认值？
第 11 课：只读工具 — FileRead, Glob, Grep
学习目标： 通过三个最简单的工具理解工具实现模式，掌握"读"类工具的设计模式。
前置依赖： 第 10 课
核心内容：
- FileReadTool：
- 输入：
file_path+ 可选的offset/limit/pages - 能力：读文本、读图片（多模态）、读 PDF（分页）、读 Jupyter Notebook
- 权限：
isReadOnly() = true，低风险
- 输入：
- GlobTool：
- 基于 glob 模式的文件搜索，按修改时间排序
- 底层可能使用原生
bfs（breadth-first search）加速
- GrepTool：
- 基于 ripgrep 的内容搜索
- 输出模式：
content（行内容）、files_with_matches（文件路径）、count（计数） - 支持 multiline、context lines、offset/limit 分页
- 共同模式：Zod inputSchema → JSON Schema 导出 → 权限检查 → 执行 → 结果渲染
重点文件：
tools/FileReadTool/— 文件读取tools/GlobTool/— 文件搜索tools/GrepTool/— 内容搜索
课后练习：
- 对比三个工具的
inputSchema，找出 Zod → JSON Schema 的转换模式 - 阅读 GrepTool 的参数设计，思考为什么需要
head_limit和offset
第 12 课：写入工具 — FileEdit, FileWrite
学习目标： 理解"写"类工具的额外复杂度：diff 追踪、冲突检测、渲染策略。
前置依赖： 第 11 课
核心内容：
- FileEditTool（
FileEditTool.ts+UI.tsx）：- 基于精确字符串替换（
old_string→new_string），非行号 - 唯一性约束：
old_string必须在文件中唯一，否则失败 replace_all模式用于批量替换- Diff 追踪与 UI 渲染分离：
UI.tsx（34KB）独立处理展示
- 基于精确字符串替换（
- FileWriteTool：
- 整文件写入（覆盖式），必须先 Read 才能 Write
- 与 FileEdit 的分工：Edit 用于修改已有文件，Write 用于新建或完全重写
- NotebookEditTool：
- Jupyter Notebook 编辑，处理 cell 结构
- Speculation State：AppState 中追踪进行中的编辑，支持乐观更新
重点文件：
tools/FileEditTool/FileEditTool.ts— 编辑逻辑tools/FileEditTool/UI.tsx— 编辑结果渲染（diff 展示）tools/FileWriteTool/— 文件写入
课后练习：
- 理解 FileEdit 的"唯一性约束"设计意图：为什么不用行号定位？
- 追踪一次 FileEdit 从调用到 diff 展示的完整路径
第 13 课：BashTool — Shell 执行与安全防线
学习目标： 深入理解最复杂也是最危险的工具 — BashTool 的安全架构。
前置依赖： 第 12 课
核心内容：
BashTool.tsx（160KB+）— 最大的单一工具文件- 安全层次：
bashSecurity.ts（102KB）— 命令安全分析（危险命令检测、注入防护）bashPermissions.ts（98KB）— 权限决策（基于命令内容判断风险等级）readOnlyValidation.ts（68KB）— 只读模式校验pathValidation.ts（43KB）— 路径遍历防护
- 沙箱机制：可选的沙箱执行环境
- 超时管理：默认 120s，最大 600s，支持后台运行（
run_in_background） - 输出处理：stdout/stderr 捕获、结果截断
重点文件：
tools/BashTool/BashTool.tsx— 主逻辑tools/BashTool/bashSecurity.ts— 安全分析tools/BashTool/bashPermissions.ts— 权限决策
课后练习：
- 列出 BashTool 检测的所有"危险命令"模式
- 思考：为什么 BashTool 的安全代码量（300KB+）远超其功能代码量？
第 14 课：工具注册表与延迟加载
学习目标： 理解 40+ 工具如何被注册、过滤、按需加载。
前置依赖： 第 10-13 课
核心内容：
tools.ts— 中央工具注册表：- 静态导入的核心工具：Agent, Bash, FileEdit, FileRead, Glob, Grep 等
- Feature-gated 的条件工具：REPL, Sleep, Cron, RemoteTrigger, WebBrowser 等
- 工具过滤：
ALL_AGENT_DISALLOWED_TOOLS（子 Agent 禁用列表）、ASYNC_AGENT_ALLOWED_TOOLS（异步 Agent 白名单）
- 延迟加载机制：
shouldDefer标志 → 工具不在初始加载中注册ToolSearchTool— 用户/模型通过搜索发现并加载延迟工具alwaysLoad标志 → 强制始终加载
- Schema 缓存：
tools/toolSchemaCache.ts— 避免重复序列化 JSON Schema - 工具合并：
useMergedTools()— 核心工具 + MCP 工具 + 技能工具的合并逻辑
重点文件：
tools.ts— 工具注册表tools/ToolSearchTool/— 工具发现机制tools/toolSchemaCache.ts— Schema 缓存
课后练习：
- 统计有多少工具是延迟加载的，分析延迟加载的判断标准
- 思考：ToolSearch 机制解决了什么问题？如果所有工具都加载会怎样？
模块五：权限体系（第 15-16 课）
目标：理解 AI Agent 安全执行的核心 — 权限系统如何平衡安全与效率。
第 15 课：权限基础 — 模式、规则与风险分级
学习目标： 掌握四种权限模式和三级风险分类，理解权限决策流程。
前置依赖： 第 10 课
核心内容：
- 四种权限模式（
types/permissions.ts）：default— 交互式提示，每次工具调用询问用户auto— ML 分类器自动审批（基于 transcript classifier）bypass— 跳过检查（仅限受信环境）yolo— 拒绝所有（反讽命名，实际是最严格模式）
- 三级风险分类：
LOW、MEDIUM、HIGH- 每个工具的每种操作都有预设风险等级
- 风险等级决定默认权限行为
- 权限规则来源：
~/.claude/permissions.json— 用户持久化规则- Permission Context — 每会话构建的权限上下文
- Tool 自身的
checkPermissions()返回值
- 受保护文件：
.gitconfig,.bashrc,.zshrc,.mcp.json,.claude.json等禁止自动编辑 hooks/PermissionContext.ts— 不同模式（interactive / coordinator / worker）的处理器
重点文件：
types/permissions.ts— 权限类型定义hooks/useCanUseTool.ts— 权限检查 Hookhooks/PermissionContext.ts— 权限上下文
课后练习：
- 画出权限决策流程图：工具调用 → 风险分级 → 模式判断 → 决策
- 列出所有受保护文件，理解为什么这些文件需要特殊保护
第 16 课：高级权限 — 自动模式与安全防护
学习目标： 理解 auto 模式的 ML 分类器工作原理，以及路径遍历、注入攻击的防护策略。
前置依赖： 第 15 课
核心内容：
- Auto 模式分类器：
- Transcript Classifier — 基于对话上下文的 ML 决策
- YOLO Classifier — 快速权限判断系统
- 输入：
toAutoClassifierInput()将工具调用转换为分类器输入
- 路径遍历防护（
tools/BashTool/pathValidation.ts）：- URL 编码遍历检测（
%2e%2e/） - Unicode 规范化攻击防护
- 反斜杠注入拦截
- 大小写不敏感路径操控检测
- URL 编码遍历检测（
- 权限解释器：
- 单独的 LLM 调用向用户解释工具风险
- "这个命令将修改你的 git config" — 这条解释本身由 Claude 生成
- 拒绝追踪：
utils/permissions/denialTracking.ts— 记录用户拒绝历史，避免重复请求相同操作
重点文件：
tools/BashTool/bashSecurity.ts— Bash 安全分析tools/BashTool/pathValidation.ts— 路径校验utils/permissions/denialTracking.ts— 拒绝追踪
课后练习：
- 列出所有路径遍历攻击向量及其防护方式
- 思考：权限解释器（LLM 解释风险）和硬编码解释相比有什么优缺点？
模块六：System Prompt 架构（第 17-19 课）
目标：理解 Claude Code 如何构建复杂、动态、可缓存的 System Prompt。
第 17 课：Prompt 组装架构
学习目标： 掌握模块化 System Prompt 的组装策略，理解静态/动态分区和缓存边界。
前置依赖： 第 07 课（Agent 循环）、第 15 课（权限）
核心内容：
constants/prompts.ts— System Prompt 主组装函数getSystemPrompt()：- 静态节（跨组织可缓存）：介绍、系统指引、行为准则、工具说明、语气风格、输出效率
- 动态节（每会话变化）：会话指引、记忆、语言、输出风格、MCP 指令、Token 预算
systemPromptSection()— 可缓存节构造器DANGEROUS_uncachedSystemPromptSection()— 显式破坏缓存的节（命名即警告）SYSTEM_PROMPT_DYNAMIC_BOUNDARY— 静态/动态分割标记- 缓存策略：API 的 prompt caching 要求静态部分保持不变，动态部分追加在后
重点文件：
constants/prompts.ts— 主组装逻辑constants/systemPromptSections.ts— 节定义
课后练习：
- 列出所有静态节和动态节，画出它们的组装顺序
- 思考：
DANGEROUS_uncachedSystemPromptSection()在什么场景下必须使用？
第 18 课：动态节 — 记忆、MCP 指令与环境
学习目标： 理解每次 API 调用时哪些信息被动态注入到 System Prompt 中。
前置依赖： 第 17 课
核心内容：
- 记忆注入：
MEMORY.md和记忆文件被读取并注入到 System Prompt - MCP 指令：
getMcpInstructions()— 格式化所有连接的 MCP Server 的使用指南 - 环境信息：
computeEnvInfo()构建包含以下内容的环境块：- 工作目录和 Git 仓库信息
- 平台、Shell、OS 版本
- 模型名称和上下文窗口大小
- 知识截止日期
- Scratchpad：
tengu_scratchfeature gate 控制的跨 Worker 共享知识区 - Token 预算：告知模型当前可用的 token 数量
- 工具说明动态生成：根据实际加载的工具列表生成使用指南
重点文件：
constants/prompts.ts中的动态节部分context.ts—computeEnvInfo()函数
课后练习：
- 拼出一个完整的 System Prompt 示例（可以用占位符）
- 计算：System Prompt 大约消耗多少 token？留给用户对话的空间有多大？
第 19 课：安全指令与 Undercover 模式
学习目标： 理解 AI Agent 的行为边界如何通过 Prompt 约束，以及内部员工使用时的特殊处理。
前置依赖： 第 17 课
核心内容：
- Cyber Risk Instruction（
constants/cyberRiskInstruction.ts）：- 由 Safeguards 团队拥有，修改需审核
- 允许：授权安全测试、防御安全、CTF、教育
- 禁止：破坏技术、DoS 攻击、供应链攻击、检测规避
- 双用途工具（C2 框架、凭证测试）需要明确授权上下文
- Undercover 模式（
utils/undercover.ts）：- 触发条件：
USER_TYPE === 'ant'且不在内部仓库 - 注入 prompt："你正在以卧底身份在公开仓库工作"
- 禁止项：内部代号（Capybara, Tengu）、未发布版本号、内部链接、AI 署名
- 激活逻辑：
CLAUDE_CODE_UNDERCOVER=1强制开启，无法强制关闭
- 触发条件：
- 安全设计哲学：宁可过度保护，不可意外泄露
重点文件：
constants/cyberRiskInstruction.ts— 安全行为边界utils/undercover.ts— Undercover 模式
课后练习：
- 分析 Cyber Risk Instruction 的 prompt 结构，它如何平衡"有用"和"安全"？
- 思考：如果你是 Safeguards 团队，你会增加或修改哪些规则？
模块七：记忆与上下文管理（第 20-22 课）
目标：理解 AI Agent 如何"记住"和"遗忘" — 从实时记忆到做梦整合到上下文压缩。
第 20 课：SessionMemory — 实时对话记忆
学习目标： 理解 Claude Code 如何在对话中提取和维护关键记忆。
前置依赖： 第 17 课（System Prompt）
核心内容：
services/SessionMemory/sessionMemory.ts— 会话记忆主逻辑：- 触发阈值：初始化需 10K token 的对话量
- 更新门控：5K token 增长 OR 3 次工具调用间隔
- 执行方式：forked subagent（非阻塞，不影响主对话）
services/SessionMemory/prompts.ts— 记忆提取 promptservices/SessionMemory/sessionMemoryUtils.ts— 辅助函数- 记忆存储：Markdown 文件（
MEMORY.md+ 主题文件），带 frontmatter 元数据 - 记忆类型：user（用户画像）、feedback（行为反馈）、project（项目上下文）、reference（外部引用）
services/extractMemories/— 独立的记忆提取服务
重点文件：
services/SessionMemory/sessionMemory.ts— 主逻辑services/SessionMemory/prompts.ts— 提取 prompt
课后练习：
- 画出 SessionMemory 的触发流程图（阈值检查 → fork subagent → 写入文件）
- 分析记忆提取 prompt：它如何指导 Claude 判断什么值得记住？
第 21 课：autoDream — "做梦"系统
学习目标： 深入理解后台记忆整合的三门触发机制和四阶段处理流程。
前置依赖： 第 20 课
核心内容：
services/autoDream/autoDream.ts— 做梦主逻辑- 三门触发机制（必须全部满足）：
- 时间门：距上次做梦 ≥ 24 小时
- 会话门：距上次做梦 ≥ 5 个会话
- 锁门：获取 consolidation lock（防并发）
services/autoDream/consolidationLock.ts— 锁实现（基于文件 mtime，PID 竞态检测，1 小时过期）services/autoDream/consolidationPrompt.ts— 四阶段 prompt：- Phase 1 - Orient：
ls记忆目录，读 MEMORY.md，浏览现有主题文件 - Phase 2 - Gather：查找新信息（日志 → 偏移记忆 → 对话搜索）
- Phase 3 - Consolidate：写入/更新记忆文件，相对日期转绝对日期，删除矛盾事实
- Phase 4 - Prune：MEMORY.md 控制在 200 行 / 25KB 以内
- Phase 1 - Orient：
- 安全限制：做梦 subagent 只有只读 bash 权限
services/autoDream/config.ts— 做梦配置参数
重点文件：
services/autoDream/autoDream.ts— 触发逻辑services/autoDream/consolidationPrompt.ts— 四阶段 promptservices/autoDream/consolidationLock.ts— 并发锁
课后练习：
- 为什么需要三门机制？如果只用时间门会有什么问题？
- 分析做梦 prompt 的四个阶段，每个阶段解决什么问题？
第 22 课：Context Compression — 上下文压缩
学习目标： 理解当对话超长时，Claude Code 如何压缩上下文而不丢失关键信息。
前置依赖： 第 20 课
核心内容：
services/compact/compact.ts— 核心压缩逻辑：- 按 API 轮次分组消息（
grouping.ts） - 去除图片等大体积内容
- 生成摘要替代原始消息
- 压缩后恢复文件/技能上下文（file restoration / skill restoration）
- 按 API 轮次分组消息（
- Token 预算：
- 压缩后上下文目标：50K token
- 单文件上限：5K token
- 单技能上限：5K token
- 技能总量上限：25K token
services/compact/autoCompact.ts— 自动压缩触发：calculateTokenWarningState()— 计算 token 消耗状态- 当输出 token 超过预算时自动触发
services/compact/microCompact.ts— 轻量级压缩（不做完整摘要）services/compact/compactWarningHook.ts— 压缩前警告- Feature-gated：
REACTIVE_COMPACT（反应式压缩）、CONTEXT_COLLAPSE（上下文折叠）
重点文件：
services/compact/compact.ts— 压缩核心services/compact/autoCompact.ts— 自动触发services/compact/grouping.ts— 消息分组
课后练习：
- 画出压缩触发到完成的流程图
- 思考：为什么压缩后需要"恢复"文件和技能上下文？直接保留原始消息不行吗？
模块八：MCP 协议（第 23-24 课）
目标：理解 Model Context Protocol 在 Claude Code 中的完整集成。
第 23 课：MCP 基础 — 传输层与客户端
学习目标： 掌握 MCP 协议的三种传输方式和客户端连接管理。
前置依赖： 第 10 课（工具系统）
核心内容：
- MCP 是什么：Model Context Protocol — 让 AI 模型访问外部工具和数据的标准协议
services/mcp/— 25 个文件组成的 MCP 子系统- 三种传输方式：
Stdio— 标准输入/输出，适合本地进程SSE（Server-Sent Events）— HTTP 长连接，适合远程服务HTTP— 标准 HTTP 请求InProcessTransport.ts— 同进程 MCP（linked pair 模式）
services/mcp/client.ts— MCP 客户端核心：- 连接管理：建立、维持、重连
- 工具注册：将 MCP Server 的工具转换为 Claude Code 的 Tool 接口
- 资源注册：将 MCP Server 的资源转换为可查询的内容
- 配置：
.mcp.json— MCP Server 配置文件 services/mcp/config.ts— 配置加载与验证
重点文件：
services/mcp/client.ts— 客户端核心services/mcp/types.ts— MCP 类型定义services/mcp/InProcessTransport.ts— 同进程传输
课后练习：
- 对比三种 MCP 传输方式的适用场景
- 追踪一个 MCP 工具从 Server 注册到被 Claude 调用的完整路径
第 24 课：MCP 进阶 — OAuth、沙箱与官方注册表
学习目标： 理解 MCP 的安全机制、认证流程和生态管理。
前置依赖： 第 23 课
核心内容：
- OAuth 认证（
services/mcp/auth.ts）：- Token 自动刷新机制
- 支持多种认证流程
- Elicitation（
services/mcp/elicitationHandler.ts）：- 交互式认证：MCP Server 需要用户提供额外信息时的对话流程
- 沙箱隔离：MCP 工具在受限环境中执行
- 权限管理（
services/mcp/channelPermissions.ts）：- MCP 工具继承 Claude Code 的权限框架
normalization.ts— 输入规范化，防止注入
- 官方注册表（
services/mcp/officialRegistry.ts）：- Anthropic 审核的 MCP Server 列表
- 质量和安全保证
- System Prompt 集成：MCP Server 的使用说明被注入到 System Prompt 的动态节中
tools/MCPTool/— MCP 工具的 Claude Code 封装tools/ListMcpResourcesTool/+tools/ReadMcpResourceTool/— MCP 资源访问工具
重点文件：
services/mcp/auth.ts— OAuth 认证services/mcp/elicitationHandler.ts— 交互式认证services/mcp/officialRegistry.ts— 官方注册表services/mcp/channelPermissions.ts— 权限管理
课后练习：
- 画出 MCP OAuth 认证的时序图
- 思考：为什么需要官方注册表？如果任何人都能发布 MCP Server 会有什么风险？
模块九：多 Agent 架构（第 25-27 课）
目标：理解 Claude Code 如何从单 Agent 演化为多 Agent 协作系统。
第 25 课：AgentTool — 子 Agent 生成
学习目标： 理解如何在一个 Agent 内部生成和管理子 Agent。
前置依赖： 第 10 课（工具系统）、第 15 课（权限）
核心内容：
tools/AgentTool/AgentTool.tsx（160KB+）— 最复杂的工具之一：- 输入：prompt、description、model（可选）、subagent_type（可选）
- 生成新的 Agent 实例，拥有独立的工具列表和权限上下文
- 支持
isolation: "worktree"— 在 Git worktree 中隔离执行
- Agent 定义：
tools/AgentTool/loadAgentsDir.ts— 从~/.claude/agents/加载用户自定义 Agent - 工具限制：子 Agent 使用受限的工具列表（
ALL_AGENT_DISALLOWED_TOOLS） - 通信机制：子 Agent 完成后返回单条结果消息给父 Agent
tools/SendMessageTool/— Agent 间直接消息传递tools/shared/spawnMultiAgent.ts— 多 Agent 共享生成逻辑- 权限桥接：子 Agent 的权限请求传递给父 Agent 的用户交互
重点文件：
tools/AgentTool/AgentTool.tsx— 主逻辑tools/AgentTool/loadAgentsDir.ts— Agent 定义加载tools/SendMessageTool/— 消息传递
课后练习：
- 画出父子 Agent 之间的交互时序图
- 对比 AgentTool 和普通工具的权限模型差异
第 26 课：Task 系统 — 后台任务管理
学习目标： 理解如何管理长时间运行的后台任务和异步 Agent 操作。
前置依赖： 第 25 课
核心内容：
- 6 个 Task 工具：
TaskCreateTool— 创建后台任务TaskGetTool— 获取任务状态TaskListTool— 列出所有任务TaskUpdateTool— 更新任务状态（in_progress → completed）TaskOutputTool— 读取任务输出TaskStopTool— 终止任务
Task.ts— 任务类型定义tasks.ts— 任务管理逻辑- 任务生命周期：created → in_progress → completed / failed / stopped
- 与 Agent 的关系：AgentTool 可以
run_in_background创建后台 Agent 任务 - 进度追踪：
ToolProgressData类型中的TaskOutputProgress— 实时进度上报 tools/TodoWriteTool/— 遗留的任务追踪工具（被 Task 系统取代）
重点文件：
tools/TaskCreateTool/等 6 个 Task 工具Task.ts— 任务类型tasks.ts— 任务管理
课后练习：
- 画出任务状态机：所有可能的状态转换
- 设计一个场景：用 3 个并行 Task 完成一个代码审查任务
第 27 课：Coordinator 模式 — 多 Worker 编排
学习目标： 理解 Claude Code 最高级的多 Agent 架构：Coordinator-Worker 模式。
前置依赖： 第 25-26 课
核心内容：
coordinator/coordinatorMode.ts— 编排核心：isCoordinatorMode()— Feature gate 检查getCoordinatorSystemPrompt()— Coordinator 角色 promptgetCoordinatorUserContext()— Worker 上下文构建
- 四阶段工作流：
- Research：Workers 并行调查代码库
- Synthesis：Coordinator 阅读发现、理解问题、制定规格
- Implementation：Workers 按规格做针对性修改并提交
- Verification：Workers 验证修改生效
- 关键设计原则（来自 Coordinator prompt）：
- "并行是你的超级能力" — 尽量并行而非串行
- "不要说'基于你的发现' — 读取实际发现并精确指定要做什么" — 禁止懒惰委派
- Worker 通信：
<task-notification>XML 消息格式 - Scratchpad：
tengu_scratchfeature gate 下的跨 Worker 共享知识目录 - Agent Teams/Swarm（
tengu_amber_flint）：- 进程内队友（AsyncLocalStorage 隔离）
- 基于 tmux/iTerm2 面板的进程间队友
- 团队记忆同步
- 颜色分配用于视觉区分
tools/TeamCreateTool/+tools/TeamDeleteTool/— 团队管理
重点文件：
coordinator/coordinatorMode.ts— 编排核心tools/TeamCreateTool/— 团队创建tools/shared/spawnMultiAgent.ts— 多 Agent 生成
课后练习：
- 用 Coordinator 模式设计一个"重构用户认证模块"的完整编排方案
- 对比 Coordinator 和 AgentTool 直接生成子 Agent 的使用场景
模块十：扩展与 UI（第 28-30 课）
目标：理解 Claude Code 的可扩展性设计和用户界面层。
第 28 课：插件、技能与钩子体系
学习目标： 掌握 Claude Code 的三大扩展机制及其协作关系。
前置依赖： 第 14 课（工具注册）
核心内容：
- 插件系统（
plugins/）：plugins/builtinPlugins.ts— 内置插件注册services/plugins/pluginOperations.ts— 安装/卸载/启用/禁用/更新services/plugins/PluginInstallationManager.ts— 磁盘持久化- 插件可包含：commands、agents、skills、hooks、MCP servers
- 技能系统（
skills/）：skills/bundledSkills.ts— 技能注册表- 内置技能：batch, claudeApi, debug, keybindings, loop, remember, simplify, verify 等
skills/loadSkillsDir.ts— 动态加载用户技能目录skills/mcpSkillBuilders.ts— MCP 集成技能tools/SkillTool/— 技能执行工具
- 钩子系统（
hooks/，70+ 文件）：- PreToolUse — 工具执行前（校验、参数修改）
- PostToolUse — 工具执行后（自动格式化、检查）
- Stop — 会话结束时（最终验证）
hooks/useQueueProcessor— 命令队列（优先级：'now' > 'next' > 'later'）- 钩子可配置在
~/.claude/settings.json中
- 三者关系：插件是容器，可包含技能和钩子；技能是可调用的能力单元；钩子是事件驱动的自动化
重点文件：
plugins/builtinPlugins.ts— 插件注册skills/bundledSkills.ts— 技能注册hooks/— 钩子集合
课后练习：
- 设计一个插件，包含一个技能和两个钩子，描述它们如何协作
- 追踪一次
/verify技能的完整执行路径
第 29 课：UI 层 — 终端渲染与交互设计
学习目标： 理解 Claude Code 如何在终端中实现丰富的交互体验。
前置依赖： 第 06 课（REPL）
核心内容：
- Ink 终端渲染引擎（
ink/，50 文件）：ink.tsx— 入口，ThemeProvider 包装renderer.ts+render-node-to-output.ts+render-to-screen.ts— 三阶段渲染管线terminal.ts— 终端底层控制parse-keypress.ts— 按键解析colorize.ts,bidi.ts— 颜色化和双向文本
- 组件库（
components/，146 个子目录）：App/— 主应用壳PromptInput/— 用户输入框MessageSelector/— 消息展示PermissionRequest/— 权限请求弹窗diff/— Diff 渲染器design-system/— 主题系统ContextVisualization/— 上下文可视化DevBar/— 开发者工具栏
- 键绑定系统（
keybindings/，13 文件）：defaultBindings.ts— 默认 QWERTY 绑定parser.ts+resolver.ts+validator.ts— 绑定解析管线loadUserBindings.ts— 加载~/.claude/keybindings.jsonreservedShortcuts.ts— 保留快捷键
- Vim 模式（
vim/，5 文件）：motions, operators, textObjects, transitions, types - 输出样式：
outputStyles/— 不同的输出格式化策略
重点文件：
ink/ink.tsx— 渲染入口ink/renderer.ts— 渲染器核心keybindings/defaultBindings.ts— 默认键绑定vim/motions.ts— Vim 移动命令
课后练习：
- 追踪一次按键从物理输入到 UI 响应的完整路径
- 对比 Ink 和浏览器 React 的渲染流程差异
第 30 课：特殊功能全景与架构总复习
学习目标： 了解所有未覆盖的高级功能，整合全部知识形成完整认知。
前置依赖： 全部前置课程
核心内容：
Part A — 特殊功能巡览：
- Bridge 模式（
bridge/，33 文件）：JWT 认证的 claude.ai 集成，支持 single-session / worktree / same-dir 三种工作模式 - Buddy 宠物系统（
buddy/）：Tamagotchi 式伴侣，Mulberry32 PRNG 决定物种，18 种生物 + 闪光变种，ASCII 精灵动画 - Voice 模式（
voice/）：语音输入支持 - KAIROS 模式（
assistant/）：始终在线的主动式 Assistant，15 秒阻塞预算，专属工具（SendUserFile, PushNotification, SubscribePR） - ULTRAPLAN：30 分钟远程 Opus 规划会话，浏览器审批
- Remote Agent（
remote/）：远程会话管理，WebSocket 通信 - Upstream Proxy（
upstreamproxy/）：容器感知代理中继，反 ptrace，CA 证书下载 - Computer Use（"Chicago"）：截图 + 点击/键盘输入 + 坐标变换
Part B — 架构总复习：
- 分层视角：UI 层 → 交互层 → Agent 循环层 → 工具层 → 权限层 → API 层
- 数据流全景：用户输入 → REPL → State → query() → API → tool_use → 权限检查 → 执行 → 结果 → 压缩 → 记忆
- 设计哲学总结：
- Fail-closed — 安全默认值（权限、工具注册）
- 编译时消除 — 同一代码库，多种构建（内部/外部）
- 不可变状态 — 可预测的状态流转
- 子 Agent 隔离 — 权限、工具、上下文均可独立控制
- 渐进式加载 — ToolSearch 延迟加载，按需扩展工具集
- 缓存优先 — System Prompt 分区、Schema 缓存、Feature Flag 缓存
课后总练习：
- 画出 Claude Code 的完整架构图（至少包含 15 个核心模块）
- 选择一个方向写一篇 2000 字的技术分析文章：
- A) AI Agent 的安全架构设计（权限 + 安全指令 + Undercover）
- B) 多 Agent 协作系统设计（AgentTool + Task + Coordinator）
- C) AI Agent 的记忆系统设计（SessionMemory + autoDream + Compact）
- D) 终端 AI 应用的工程架构（Bun + Ink + Feature Gate + 状态管理）
附录 A：课程知识依赖清单
| 课程 | 直接依赖 | 说明 |
|---|---|---|
| 01 | 无 | 起点 |
| 02 | 01 | 需要全局架构认知 |
| 03 | 02 | 需要理解技术栈 |
| 04 | 01-03 | 需要全部基础知识 |
| 05 | 04 | 需要理解启动流程 |
| 06 | 05 | 需要理解状态管理 |
| 07 | 06 | 需要理解 REPL 如何调用 query |
| 08 | 07 | 需要理解 Agent 循环中的消息处理 |
| 09 | 08 | 需要理解消息类型 |
| 10 | 07 | 需要理解 query 如何分发工具 |
| 11 | 10 | 需要理解 Tool 接口 |
| 12 | 11 | 需要理解只读工具作为对比 |
| 13 | 12 | 需要理解写入工具作为对比 |
| 14 | 10-13 | 需要理解多种工具后才能理解注册表 |
| 15 | 10 | 需要理解 Tool 接口中的权限字段 |
| 16 | 15 | 需要理解权限基础 |
| 17 | 07, 15 | 需要理解 Agent 循环和权限（prompt 中包含两者） |
| 18 | 17 | 需要理解 prompt 组装架构 |
| 19 | 17 | 需要理解 prompt 组装架构 |
| 20 | 17 | 需要理解记忆如何注入 prompt |
| 21 | 20 | 需要理解 SessionMemory 作为前置 |
| 22 | 20 | 需要理解记忆系统基础 |
| 23 | 10 | 需要理解工具系统（MCP 工具是工具的超集） |
| 24 | 23 | 需要 MCP 基础 |
| 25 | 10, 15 | 需要理解工具和权限 |
| 26 | 25 | 需要理解子 Agent 生成 |
| 27 | 25-26 | 需要理解 Agent 和 Task |
| 28 | 14 | 需要理解工具注册（插件扩展工具集） |
| 29 | 06 | 需要理解 REPL 交互 |
| 30 | 全部 | 总复习 |
附录 B：核心文件阅读优先级
第一梯队（必读，建立核心认知）：
Tool.ts— 工具接口定义query.ts— Agent 循环核心constants/prompts.ts— System Prompt 组装state/AppStateStore.ts— 状态结构
第二梯队（精读，理解子系统）：
tools/BashTool/bashSecurity.ts— 安全设计典范coordinator/coordinatorMode.ts— 多 Agent 编排services/autoDream/consolidationPrompt.ts— 记忆整合 promptservices/compact/compact.ts— 上下文压缩services/mcp/client.ts— MCP 客户端
第三梯队（选读，按兴趣方向）：
tools/AgentTool/AgentTool.tsx— 子 Agent 实现细节ink/renderer.ts— 终端渲染引擎utils/undercover.ts— Undercover 模式bridge/— claude.ai 集成buddy/— 宠物系统（了解产品设计思路）
