Skip to content

01-project-overview.md

Latest commit

 

History

History
130 lines (94 loc) · 5.26 KB

01-project-overview.md

File metadata and controls

130 lines (94 loc) · 5.26 KB

01. 项目总览

所属层级：第一层「先理解 Claude Code 是什么」

建议前读：00. 快照与边界

建议后读：02. 目录导览与阅读顺序 或 03. 启动与主循环

这篇讲什么

这一章给你一张大图：Claude Code 这套源码快照里，主要能力有哪些，分层如何组织，信息在系统里大致怎么流动。

先给结论

从当前快照看，Claude Code 不是“单一聊天 CLI”，而是一套围绕终端工作流构建的 agentic CLI 平台。它至少包含这些主轴：

  • 一个 Commander.js 驱动的 CLI 入口。
  • 一个 React + Ink 终端 UI。
  • 一套可扩展的 slash command 系统。
  • 一套更底层的 tool 调用系统。
  • 一个负责会话、上下文、消息、工具循环的 QueryEngine。
  • 一整层权限、安全和计划模式控制。
  • 多种扩展面：技能、插件、MCP、LSP、Bridge、Remote、子代理。

源码依据

Mermaid 图：项目总体架构图

flowchart TD
    A[启动层\nmain.tsx] --> B[交互层\nApp / REPL / Ink]
    A --> C[命令层\ncommands.ts]
    A --> D[工具层\ntools.ts]
    B --> E[状态层\nAppState]
    C --> E
    D --> F[执行层\nQueryEngine]
    E --> F
    A --> G[扩展层\nplugins / skills / MCP / LSP]
    A --> H[远程层\nbridge / remote]
    D --> I[多代理与任务\nAgentTool / tasks]
    G --> C
    G --> D
    H --> B
    H --> F
    I --> F
Loading

能力地图

从目录和注册表看，项目至少覆盖以下能力面：

能力面 主要位置 作用
CLI 启动与入口 src/main.tsx 解析参数、初始化系统、启动 REPL 或其他路径
Slash 命令 src/commands.ts、src/commands/ 用户直接输入的命令式操作入口
Tool 调用 src/tools.ts、src/tools/ 模型或系统可调用的能力单元
会话与推理循环 src/QueryEngine.ts、src/query/ 维护消息、上下文、工具调用和结果汇总
UI 与交互 src/components/、src/screens/ Ink/React 终端界面
权限与安全 src/utils/permissions/ 模式切换、规则、审批和危险操作防护
扩展体系 src/skills/、src/plugins/、src/services/mcp/、src/services/lsp/ 技能、插件、MCP、LSP
远程与集成 src/bridge/、src/remote/ IDE/远程控制、CCR 会话
多代理与任务 src/tools/AgentTool/、src/tasks/ 子代理、后台任务、team/teammate 协作

分层理解方式

可以把这个项目粗略理解成五层。

1. 启动层

由 src/main.tsx 驱动。它负责：

  • 尽早触发一些预取型副作用。
  • 初始化配置、分析、策略限制、远程管理设置等。
  • 组装命令、工具、MCP、插件、代理定义。
  • 根据启动参数进入 REPL、remote、assistant、bridge 等分支。

2. 交互层

由 src/components/App.tsx、src/screens/ 和 src/components/ 组成，基于 React + Ink。用户看到的对话、弹窗、设置页、Doctor 页等都在这一层。

3. 命令层

用户直接在交互界面中输入 /help、/login、/plugin、/mcp、/tasks 等 slash 命令时，会进入 src/commands.ts 管理的命令系统。命令可分成 prompt 型、local 型、local-jsx 型三类。

4. 工具层

更底层的是 tool。它比命令更像“可被模型调用的动作能力”，例如 BashTool、FileReadTool、AgentTool、MCPTool。它们统一由 src/tools.ts 注册。

5. 执行与状态层

src/QueryEngine.ts 负责跨轮次维护消息、文件缓存、用量、工具调用上下文等。全局 UI 状态则由 src/state/AppStateStore.ts 描述。

一条典型数据流

可以把一次交互简化理解为：

用户输入
  -> CLI/REPL 接收
  -> 命令系统或普通消息处理
  -> QueryEngine 组装系统上下文与用户上下文
  -> 模型生成内容 / tool call
  -> Tool 执行
  -> 结果写回消息流和状态
  -> Ink UI 渲染结果

如果中间涉及远程会话、MCP、插件技能或子代理，这条链会被横向扩展，但基本骨架仍然成立。

为什么这个项目值得单独写文档

这个快照体量很大，src/ 下有 1902 个文件、约 512685 行源码。只看目录很难迅速建立“哪里是核心，哪里是挂件，哪里是实验性功能”的判断，所以文档的价值主要在于：

  • 帮你先画出能力边界。
  • 告诉你从哪几个入口开始看最省时间。
  • 帮你区分命令、工具、扩展和远程系统各自的职责。

下一步建议

读完这一章，下一步优先看：

  1. 02-repo-map-and-reading-order.md
  2. 03-startup-and-main-loop.md