参考文献：https://ccb.agent-aura.top/docs/introduction/architecture-overview

一、 交互层（Interaction / Presentation Layer）

• 大白话比喻：“前台接待与显示屏”。就像餐厅的前台或服务员，负责把你说的话（输入）接进来，再把厨房做好的菜（AI 回复、工具执行结果）漂漂亮亮地端到你面前。它不关心菜怎么做，只管收发和显示。

• 专业术语描述：基于 src/screens/REPL.tsx（React/Ink 终端 UI）实现。负责 终端 UI 渲染、用户输入捕获（processUserInput）、消息展示、斜杠命令解析、文件/图片附件处理，是用户与系统交互的直接接口。

二、 编排层（Orchestration Layer）

• 大白话比喻：“宴会统筹经理”。接到前台传来的订单后，经理负责安排桌号（会话状态）、记账算成本、把对话记录归档（持久化），决定什么时候该让后厨（核心循环）出手，并管理整个用餐流程的节奏。

• 专业术语描述：由 src/QueryEngine.ts实现。管理 多轮对话生命周期、消息数组与上下文状态、ToolPermissionContext、文件历史快照（undo）、成本追踪（accumulateUsage/getTotalCost）、Transcript 序列化到磁盘（recordTranscript，支持 --resume）。是 REPL 与 query() 之间的中间编排器。

三、 核心循环层（Agentic Loop / Core Loop Layer）

• 大白话比喻：“大厨的主脑循环”。大厨拿到菜单（prompt + 上下文）后，不断重复：想一想下一步干啥 → 调用帮工（工具）动手 → 看结果 → 再想… 直到菜做完（任务结束）。这是让 AI 变“自主智能体”的核心引擎。

• 专业术语描述：由 src/query.ts的 query()AsyncGenerator + while(true) 状态机实现。每轮迭代执行：上下文预处理管道（applyToolResultBudget → snipCompact → microCompact → contextCollapse → autoCompact）→ 流式 API 调用（deps.callModel()，收集 assistantMessages/toolUseBlocks）→ 工具执行（StreamingToolExecutor 并行 / runTools 串行）→ 终止/继续判定（needsFollowUp）。通过 State类型在迭代间传递消息、跟踪压缩与恢复状态。

四、 工具层（Tool / Action Layer）

• 大白话比喻：“大厨的双手和专用帮工”。脑子想好“切菜、改文件、跑命令”，但得靠实实在在的手和工具去动刀动锅。不同帮工（读文件、写文件、跑 shell、搜代码、调子 Agent）各有各的规矩和上岗证（权限）。

• 专业术语描述：工具抽象在 src/Tool.ts（Tool<Input, Output, Progress>接口，含 validateInput() → canUseTool() → checkPermissions() → call() → ToolResult链），具体 50+ 工具由 src/tools.ts的 getAllBaseTools()组装，并经 filterToolsByDennyRules()权限过滤后注入 API。支持 MCP 外部工具扩展（通过 mcpInfo标记来源、server 级 blanket deny），是 AI 能力边界与权限即边界（Permission as Boundary）​ 的核心落地层。

五、 通信层（Communication / API Layer）

• 大白话比喻：“对外联络专线 & 传菜流”。不管大厨多厉害，要和真正的 Claude 模型厨房搭上线，得靠这条专线，并且支持“边做边传”（流式），还能自动换备用厨房（模型降级）。

• 专业术语描述：实现于 src/services/api/claude.ts。提供 与 Claude API 的流式通信（AsyncGenerator<BetaRawMessageStreamEvent>），支持 7 种 Provider（Anthropic Direct / AWS Bedrock / Google Vertex / Foundry / OpenAI 兼容 / Gemini / Grok xAI）。核心方法 deps.callModel()处理 Prompt Cache（cache_control）、thinking blocks、multi-turn tool use，模型降级时标记 tombstone 并重试流式请求，决定系统响应的实时性与模型接入能力。

一句话串起来：

你在 交互层​ 说话 → 编排层​ 管好会话/成本/记录 → 核心循环层​ 不断“想→调工具→看结果” → 工具层​ 真去动文件/跑命令（过权限门禁）→ 通信层​ 流式连 Claude 模型要决策。这就是 Claude Code 五层架构的“从大白话到专业内核”的全景。