claude-harness — Deconstructing Claude Code

All Articles

深度解析文章

Claude Code 架构与内部实现的源码导读。

架构解析01

全景：512,000 行代码的 AI CLI 是怎么构建的

从泄露事件出发，带你第一次打开 Claude Code 庞大的代码库，建立从 CLI 入口到 LLM 引擎的完整心智模型

约 8 分钟

核心机制02

查询引擎：一次对话的完整生命周期

深入 QueryEngine.ts 和 query.ts，追踪一次对话从用户输入到最终响应的完整旅程，理解异步生成器驱动的流式查询循环

约 25 分钟

工具系统03

工具系统：AI 如何安全地与外部世界交互

深入 Claude Code 的 40+ 工具系统——从类型定义到并发执行到六层权限评估，理解 AI 如何安全地操作外部世界

约 23 分钟

并发模型04

流式工具执行器：如何安全地让 AI 同时操作多个工具

深入 StreamingToolExecutor 的并发模型——isConcurrencySafe 声明、队列调度、Sibling Abort 级联取消、进度缓冲与有序发射

约 30 分钟

安全机制05

权限系统：在"自主"与"安全"之间走钢丝

深入 Claude Code 的多层权限评估——从 Hook 预审到自动化分类器到规则匹配，理解 AI 工具安全的工程实现

约 23 分钟

内存管理06

上下文管理：当百万 Token 也不够用时

深入 Claude Code 的上下文压缩策略——从 token 估算到反应式压缩到工具摘要，理解长对话的上下文管理工程

约 22 分钟

性能优化07

启动性能：一个重型 CLI 如何做到快速冷启动

深入 Claude Code 的启动优化——并行预取、编译期死代码消除、动态惰性加载、性能剖析，理解大型 CLI 的冷启动工程

约 20 分钟

架构解析08

多 Agent 编排：Coordinator 模式如何让多个 AI 协同工作

深入 Claude Code 的多 Agent 架构——Coordinator/Worker 角色分离、AgentTool 生成机制、任务通知、Scratchpad 共享、Team swarm 模式

约 23 分钟

核心机制09

持久化记忆：如何让 AI 跨会话记住你

深入 Claude Code 的记忆系统——MEMORY.md 索引、四种记忆类型、自动提取、记忆注入与去重、团队记忆同步

约 24 分钟

源码解析10

Bridge 系统：CLI 与 IDE 的双向通信架构

深入 Claude Code 的 Bridge 系统——CLI 与 IDE 扩展的双向通信、JWT 认证、会话管理、容量唤醒机制

约 24 分钟

源码解析11

MCP 协议集成：如何让 AI 工具连接一切

深入 Claude Code 的 MCP 集成——Server 生命周期管理、动态工具生成、Resource/Prompt 支持、Agent 间 Server 继承

约 20 分钟

源码解析12

插件与技能：三层可扩展性架构

深入 Claude Code 的可扩展性设计——Skill 的 Markdown frontmatter 配置、Plugin 两级注册、MCP Server 动态加载，三层如何统一管理

约 25 分钟

源码解析13

OAuth 与认证：从 Keychain 到 Token 刷新的全链路

深入 Claude Code 的认证架构——API Key、OAuth 2.0、JWT、macOS Keychain 集成、Token 刷新调度

约 20 分钟

源码解析14

终端 UI 框架：用 React 构建命令行界面

深入 Claude Code 的 React/Ink 终端 UI——渲染管线、140+ 组件架构、Markdown 终端渲染、实时进度、权限对话框

约 19 分钟

源码解析15

键绑定与 Vim 模式：在 CLI 中实现编辑器级交互

深入 Claude Code 的键绑定系统和 Vim 模式——自定义快捷键、Chord 组合、穷举类型状态机、模态编辑的 TypeScript 实现

约 24 分钟

源码解析16

屏幕系统：全屏交互模式的设计

深入 Claude Code 的全屏系统——Doctor 诊断、Resume 会话恢复、REPL 屏幕，以及对话模式与全屏模式的切换机制

约 15 分钟

源码解析17

状态管理：没有 Redux 的 React 状态架构

深入 Claude Code 的极简状态管理——不到 35 行的自定义 Store、Object.is 变更检测、细粒度订阅

约 12 分钟

源码解析18

遥测与可观测性：OpenTelemetry 在 CLI 中的应用

深入 Claude Code 的遥测架构——OpenTelemetry 惰性加载、性能剖析、GrowthBook Feature Flag、隐私考量

约 13 分钟

源码解析19

配置系统：Schema 验证、迁移与多来源合并

深入 Claude Code 的配置架构——Zod Schema、多来源优先级合并、版本化迁移、远程管理配置

约 12 分钟

源码解析20

Feature Flag 与条件编译：编译期的代码消除术

深入 Bun 的编译期 Feature Flag——feature() API、死代码消除、运行时 vs 编译期 Flag 的选择标准

约 9 分钟

源码解析21

文件操作三剑客：Read、Write、Edit 的设计哲学

深入 Claude Code 的文件操作工具——三工具分离的设计决策、多格式读取、精确替换模型、权限差异

约 13 分钟

源码解析22

BashTool：让 AI 安全执行 Shell 命令

深入 BashTool 的安全执行架构——沙箱机制、命令分类、超时管理、AbortSignal 集成、后台执行

约 12 分钟

源码解析23

搜索系统：Glob + Grep + 全文搜索的组合拳

深入 Claude Code 的搜索工具组合——GlobTool 模式匹配、GrepTool ripgrep 集成、ToolSearchTool 延迟发现

约 11 分钟

源码解析24

Web 工具：AI 如何访问互联网

深入 Claude Code 的网络访问工具——WebFetchTool 内容获取、WebSearchTool 搜索、代理配置、安全考量

约 9 分钟

源码解析25

LSP 集成：Language Server Protocol 如何增强 AI 编码

深入 Claude Code 的 LSP 集成——为 AI 提供类型信息和诊断，而非为人类提供 IDE 功能

约 9 分钟

源码解析26

Buddy 系统：代码库里的宠物养成游戏

深入 Claude Code 的 Buddy 彩蛋——确定性随机数生成器、Mulberry32 PRNG、稀有度加权分布、Bones vs Soul

约 15 分钟

源码解析27

输出样式系统：让终端输出也有品牌感

深入 Claude Code 的输出样式——主题系统、Markdown 终端渲染、语法高亮、品牌一致性

约 15 分钟

源码解析28

远程执行与定时触发：Headless AI Agent

深入 Claude Code 的远程能力——远程会话、Server 模式、Cron 定时任务、RemoteTrigger、SDK headless 模式

约 11 分钟

源码解析29

会话管理：中断、恢复与共享

深入 Claude Code 的会话持久化——磁盘存储、/resume 恢复、Teleport 跨设备迁移、/share 分享

约 11 分钟

源码解析30

API 客户端：与 Anthropic API 的深度集成

深入 Claude Code 的 API 客户端——流式响应处理、模型选择与降级、Beta API、Token 计数与成本追踪、重试逻辑

约 10 分钟

源码解析31

错误处理与自愈：AI 如何从失败中恢复

深入 Claude Code 的错误恢复机制——query.ts 恢复状态机、工具失败处理、网络重试、用户中断、/doctor 自检

约 11 分钟