# Step 75: 全面源码巡礼收尾

一句话导读：把 75 步教学版能力映射到真实 Claude Code 约 2039 个源码文件，确认我们复原的是 agent runtime 的架构骨架。

# 一、这一步做了什么（What）

step75 是整个 claude-learn 的收官复盘：不加新功能，而是把从 REPL、工具、QueryEngine、Agent、MCP/LSP、安全底层、Bridge/Web、多会话一路写出来的教学版，对照真实 claude-code-src/src 的目录结构、入口和构建方式。

它还给出架构脑图和“如果继续做 step76+，最值得补什么”的清单。

# 二、面试官视角：为什么要做？（Why）

面试题：从 step01 写到 step72 已经很完整，为什么最后还要做一次全源码巡礼？

因为单点功能容易让人误以为“Claude Code 就是聊天 + 工具”。全源码巡礼能把视角拉回系统层：真实产品是一个 agent runtime，有内核、工具、权限、会话、UI、协议、构建、遥测、安全和多入口。

局部视角	全局视角
会调用 API	有 QueryEngine runtime
有几个工具	有工具生态和权限系统
有网页	有 Bridge/Remote/SDK surface
有日志	有隐私边界和遥测管线

# 三、原理：它是怎么工作的（How）

step75 的总架构：

用户输入 / Surface
  → createCore / 装配层
  → QueryEngine 无头内核
  → Tools / MCP / LSP / Web
  → Permissions / Sandbox / Hooks
  → Memory / Skills / Plugins
  → EngineEvent / SDKMessage
  → Session Storage / Cost / Telemetry

1
2
3
4
5
6
7
8

真实源码目录映射：

utils/       设置、权限、session、token、缓存、上下文
components/ 终端 UI、权限弹窗、消息组件
commands/   slash commands
tools/      Bash/Read/Write/Web/MCP/Agent
services/   API、MCP、analytics、compact、policy
bridge/     remote control / bridge 会话
remote/     远程 session 管理
entrypoints/ CLI、SDK、MCP 入口

1
2
3
4
5
6
7
8

阶段对照：

01-10  REPL/API/流式/持久化
11-20  工具系统与权限
21-29  prompt/token/cost/compact/model/style
30-34  QueryEngine 与事件流
35-45  Agent/Todo/Hooks/Skills/Plan/Context
46-53  Web/MCP/LSP/Plugins
57-63  权限/沙箱/缓存/设置/遥测
64-72  Ink/Web/Bridge/createCore/多会话
75     全源码巡礼

1
2
3
4
5
6
7
8
9

构建对照也很重要：教学版多为 Node + tsx；真实 restored 源码用 Bun，dev-entry.ts 先检查缺失 import，再进入 entrypoints/cli.tsx。

# 四、深入追问（面试常见 follow-up）

Q：这个项目最终复原的是 Claude Code 的全部吗？
A：不是。复原的是核心架构骨架：无头引擎、工具、权限、上下文、协议、多前端。真实产品还有大量生产纵深。

Q：最核心的一条主线是什么？
A：从脚本到 runtime：console + API → Tool Calling loop → QueryEngine → 多 surface + Bridge + session。

Q：如果继续做，优先补什么？
A：多会话持久化、取消/中断、统一控制协议、WebSocket 重连、成本状态恢复。它们都对应真实源码的纵深缺口。

Q：为什么真实源码有 2000 多文件，而教学版能压缩成 75 步？
A：教学版保留架构主干，砍掉平台兼容、灰度、采样、鉴权、复杂 UI、远程策略、构建裁剪等生产层。

# 五、踩坑 / 设计权衡

最后一步最容易写成“功能清单”。真正有价值的复盘是分清三类东西：我们抄对的形状、刻意简化的地方、未来最值得补的纵深。

# 六、与真实源码的对照

我们的实现	Claude Code 源码
`QueryEngine` 教学内核	`src/QueryEngine.ts` + transcript/status/abort
`ToolRegistry`	`src/tools/` 近 200 个工具相关文件
`CommandRegistry`	`src/commands/` 完整 slash command 系统
`createCore()`	bootstrap + SDK/Bridge/CLI 分层装配
`SessionManager`	remote/sessionStorage/cost restore
简单 Web UI	components/Ink/Web/Remote 多 surface
本地遥测 JSONL	analytics sink、采样、PII 分列

# 七、一句话总结

claude-learn 的最终价值，是把一个 2039 文件级别的真实 agent 工程拆成可手写、可运行、可对照的路线，让“会调 API 的脚本”和“真正 agent runtime”的边界清清楚楚。

# 下一节预告

主线到这里收束。如果继续扩展，最自然的下一步是 step76 多会话持久化，对齐真实 sessionStorage.ts。

← 源码对照③：内核 + 前端拆分