本章总览
系统架构是整站最重要的一章。这里用分层图解释：用户的一行输入如何穿过 CLI、REPL、query 循环，最终触达工具与 API。
总览图
渲染图表中…
学完本章你应该能
- 画出四层架构：入口 / 引擎 / 能力 / 表现
- 说出每一层的职责边界
- 理解 REPL 与 QueryEngine 两种模式差异
核心概念（先读懂这些）
分层是为了隔离变化
入口层处理 argv/OAuth；引擎层只关心 messages + tools 循环；工具层扩展能力；UI 层只渲染 StreamEvent。换 UI 不应改 query，加工具不应改 CLI。
AsyncGenerator 是架构主轴
query() 不返回一次性结果，而是 yield 事件流。REPL 订阅这些事件更新屏幕，SDK 订阅后转发给宿主应用——同一引擎，多种消费者。
建议学习步骤
- 对照分层图从上到下读一遍
- 在目录树里找到对应文件夹
- 进入「查询引擎」章节深入主循环
常见误区
注意
不要把 components 简单等同于「前端」——它是终端 UI，没有 DOM
分层架构
渲染图表中…
四层架构（组件图）
渲染图表中…
模块依赖关系（概览）
渲染图表中…
部署形态对比
渲染图表中…
各层职责详解
入口层
entrypoints · cli · screens · main.tsx
查询引擎
query.ts · QueryEngine.ts · query/
工具系统
tools/ · Tool.ts · services/tools/
命令系统
commands/ · commands.ts
服务层
services/
UI 层
components/ · ink/ · hooks/
基础设施
utils/ · state/ · bridge/ · memdir/
技术栈
| 层面 | 技术 | 说明 |
|---|---|---|
| 语言 | TypeScript 5 + TSX | strict mode, ESM imports |
| UI | Ink (React for CLI) | ANSI 终端渲染 |
| 构建 | Bun bundler | feature() 编译期 DCE → 12MB bundle |
| API | @anthropic-ai/sdk | Messages API streaming |
| 协议 | MCP | Model Context Protocol 外部工具 |
| 状态 | AppState + bootstrap/state | 会话级 + 全局状态 |
| 存储 | ~/.claude/projects/ | JSON 会话持久化 |
| 特性开关 | GrowthBook + feature() | 远程 + 编译期双轨 |
目录结构全景
src/
├── entrypoints/ CLI/MCP/SDK 入口
├── main.tsx REPL 引导 (4684行)
├── query.ts 主 Agent 循环
├── QueryEngine.ts SDK 查询引擎
├── Tool.ts 工具接口定义
├── tools.ts 工具注册表
├── commands.ts 斜杠命令聚合
├── cli/ CLI 基础设施
├── screens/ REPL 屏幕
├── components/ Ink UI 组件 (406文件)
├── hooks/ React Hooks (105)
├── ink/ 终端引擎扩展
├── tools/ 51 工具实现
├── commands/ 87 斜杠命令
├── services/ 22 服务子系统
├── utils/ 基础设施 (570文件, 18万行)
├── bridge/ Desktop 桥接
├── state/ 应用状态
├── memdir/ 记忆目录
├── skills/ 内置 Skills
├── tasks/ 后台任务
└── types/ 类型定义
本章小结与延伸
架构主干：cli → main → query 循环 → tools/services → Ink UI。下一章精读 query 引擎。 继续学习：