代码组织架构：

以下是 src/ 下各顶层目录及其作用的汇总表：

目录	作用
assistant	助手模式（Assistant Mode）相关逻辑，包括模式判断、云端会话发现与历史拉取
bootstrap	全局运行时启动状态，保存会话 ID、项目根目录、Token 计数等启动期快照
bridge	Remote Control / Bridge 远程控制桥接，负责与 CCR 云端通信、会话拉起、权限回调与 JWT 刷新
buddy	输入框旁的「伙伴」宠物精灵（Companion），含精灵生成、渲染与提示词注入
cli	非交互式 CLI 与结构化输出，含打印模式、NDJSON I/O、远程 I/O 及子命令处理器
commands	所有斜杠命令实现（如 /help、/config、/login、/mcp），由根目录 commands.ts 统一注册
components	终端 UI（Ink/React）组件库，含主应用壳、对话框、权限请求、消息列表等 TUI 元素
constants	跨模块共享常量：API 限制、系统提示前缀、工具名、OAuth、文件路径等
context	React Context 提供者，管理通知队列、弹层、统计、邮箱消息、语音与 FPS 等 UI 横切状态
coordinator	协调者模式（Coordinator Mode），定义多 Agent 团队编排下的工具白名单与 worker 代理配置
entrypoints	应用启动入口与 SDK 类型定义，含 CLI 引导（cli.tsx）、初始化流程及 Agent SDK 公共类型
hooks	React 自定义 Hook 集合，覆盖输入历史、权限审批、文件建议、通知等 REPL 交互逻辑
ink	定制版终端渲染引擎（Ink fork），负责屏幕缓冲、ANSI 解析、文本测量与终端 I/O
jobs	后台任务分类器（当前多为 stub），用于对任务做自动分类
keybindings	键盘快捷键系统：默认绑定、用户自定义加载、按键解析与上下文感知的动作解析
memdir	记忆目录（Memory）子系统，管理 MEMORY.md、自动记忆扫描、团队记忆路径与相关提示词
migrations	一次性配置迁移脚本，将旧版全局配置或模型默认值迁移到新版 settings.json
moreright	内部「右侧面板」功能的 Hook 桩（外部构建用 stub），开源版本中为空实现
native-ts	原生 Rust/NAPI 模块的纯 TypeScript 移植版，含模糊文件搜索、布局、颜色差分等
outputStyles	从 .claude/output-styles/*.md 加载自定义输出风格提示词，供用户/项目级定制回复风格
plugins	内置插件注册表，管理可通过 /plugin 启用/禁用的捆绑插件（技能、Hook、MCP 等）
proactive	主动式 Agent 模式的全局状态机，控制激活/暂停/上下文阻塞及订阅通知
query	查询引擎子模块：不可变查询配置、依赖注入、状态转移、Token 预算与停止 Hook
remote	远程会话 WebSocket 管理，连接 CCR 后端、转发 SDK 消息并桥接权限请求
schemas	共享 Zod 校验模式，主要为 Hook 事件 schema，用于打破 settings 与 plugins 之间的循环依赖
screens	顶层屏幕组件：主 REPL 界面、诊断页（Doctor）、恢复会话页
server	Direct Connect 直连服务端，通过 WebSocket 接收远程控制消息并处理权限请求
services	后端服务层大集合：分析埋点、API 调用、OAuth、上下文压缩、语音 STT、MCP、策略限制等
skills	Agent 技能加载与内置技能注册，支持从目录/MCP 发现并初始化技能
ssh	SSH 远程会话管理（当前多为占位），预留给 SSH 隧道/远程开发场景
state	应用级 React 状态存储，用轻量 subscribe 模式管理 REPL 全局 UI 状态
tasks	后台任务类型与实现：本地 Shell、Agent、远程 Agent、工作流、MCP 监控、Dream 任务等
tools	Agent 可调用的工具集：Bash、文件读写/编辑、子 Agent、用户提问、计划模式等
types	全项目共享 TypeScript 类型：消息、命令、权限、Hook、插件、工具等核心数据结构
upstreamproxy	CCR 容器内上游代理配置：读取会话 Token、启动 CONNECT→WebSocket 中继、设置代理环境变量
utils	通用工具函数大库：认证、设置、权限、消息映射、会话存储、模型选择、Shell 执行等
vim	Vim 风格输入编辑：动作（motions）、操作符（operators）、文本对象与状态转移，用于输入框 Vi 模式
voice	语音模式开关与鉴权检查，通过特性门控和 OAuth 令牌判断是否可用语音输入

补充说明

src/ 根目录还有一些核心文件不属于上述子目录，但同样重要：

文件/模块	作用
main.tsx	CLI 主入口，参数解析与启动流程
query.ts	主查询循环（与模型对话的核心引擎）
commands.ts	斜杠命令注册表
tools.ts	工具注册与聚合
Tool.ts	工具抽象基类
replLauncher.tsx	启动交互式 REPL
dev-entry.ts	开发环境入口

体量最大的目录：services/（业务能力）、utils/（底层工具）、tools/（Agent 工具）、commands/（斜杠命令）、components/（TUI 组件）。

占位/stub 目录：jobs/、ssh/、moreright/ 等在当前还原版中尚未完整实现，属于预留或内部功能桩。

 Claude Code src/ 的整体架构图，从启动入口到核心引擎、UI、能力与外部连接分层说明。

总体分层架构

 核心查询循环（Query Loop）

这是整个应用的心脏：query.ts 中的 query() 异步生成器。

模块依赖关系（简化）

关键数据流总结

阶段	路径	说明
启动	cli.tsx → init.ts → main.tsx	快速路径（--version）→ 加载配置/OAuth/策略 → 解析参数
交互 UI	replLauncher → App → REPL	Ink 渲染终端，hooks 管理输入/权限/通知
对话引擎	REPL → query() → services/api	异步生成器驱动多轮对话与工具循环
工具执行	query → Tool.ts → tools/*	权限门控后执行 Bash/文件/子 Agent 等
命令处理	用户 /xxx → commands/* → 可能 bypass query	配置、登录、MCP 等本地操作
远程模式	bridge ↔ remote ↔ server	WebSocket 连接 CCR，权限桥接
记忆注入	memdir + skills + outputStyles	在 system prompt 构建阶段合并进上下文

目录在架构中的定位（修正版）

mindmap
  root((Claude Code src))
    入口
      entrypoints
      main.tsx
      dev-entry.ts
    表现层
      ink
      screens
      components
      hooks
      state
      context
    核心
      query.ts
      query/
      bootstrap/
    能力
      tools/
      commands/
      skills/
      plugins/
      tasks/
    服务
      services/api
      services/oauth
      services/mcp
      services/compact
      services/analytics
    远程
      bridge/
      remote/
      server/
      cli/
    基础
      utils/
      types/
      constants/
      migrations/

子模块

 Remote Control（远程控制）」桥接层

src/bridge 就是 Claude Code 的「远程控制基础设施」——连接本地 CLI 与 claude.ai，让会话可以在网页端被查看、操控和审批。

src/bridge 是 Claude Code 的「Remote Control（远程控制）」桥接层，负责把本地终端里的 Claude Code 会话，和 claude.ai 上的远程控制服务（CCR，Claude Code Remote）连起来，实现双向通信。在本地跑 claude，别人（或你自己）可以在网页端 claude.ai 上查看会话、发消息、审批工具权限等；本地 CLI 负责真正执行代码和工具。

本地 Claude Code CLI  ←→  src/bridge  ←→  claude.ai / CCR 后端

主要模块分工

• replBridge.ts / initReplBridge.ts — REPL 侧桥接初始化，把本地消息、工具活动同步到远程，并接收远程输入
• bridgeMain.ts — remote-control 守护进程主逻辑（注册环境、轮询任务、spawn 子会话）
• remoteBridgeCore.ts — 较新的「无 Environment API」直连路径（OAuth → /v1/code/sessions/{id}/bridge）
• bridgeApi.ts / workSecret.ts — 与后端 Environments API 通信、解析 work secret
• bridgeMessaging.ts — 入站/出站消息协议（文本、工具开始、结果、错误等）
• bridgePermissionCallbacks.ts — 远程审批工具权限时的回调
• createSession.ts / sessionRunner.ts — 创建远程会话、在本地 spawn Claude 子进程
• trustedDevice.ts / jwtUtils.ts — 可信设备、JWT 刷新
• bridgeEnabled.ts — 功能开关（需 claude.ai 订阅 + GrowthBook 特性门控）
• types.ts — 协议类型定义（WorkSecret、SpawnMode 等）

和项目其他部分的关系

• src/hooks/useReplBridge.tsx — React REPL UI 里启动/管理桥接
• src/cli/print.ts — SDK -p 模式下的远程控制
• src/commands/bridge/ — /remote-control 斜杠命令
• src/tools/SendMessageTool — 通过桥接发消息

两种启动方式：

模式	入口	说明
REPL 桥接	/remote-control 命令，或 REPL 自动连接	把当前这一个交互式会话挂到远程
Bridge 守护进程	claude remote-control	常驻 worker，可拉起多个子会话（支持 worktree / 同目录等）

src/cli 与 src/commands 的职责划分

两者都和「命令」有关，但指的是不同层级的命令，面向的场景也不一样。src/commands 是「聊天里的斜杠命令」；src/cli 是「进程怎么跑起来」——无头模式、传输、Shell 子命令 handler。都叫 command，但一个是会话内 UX，一个是 CLI 运行时。

目录	实际是什么	典型用法
src/commands	REPL 会话内斜杠命令（/help、/login、/compact）	在聊天界面里输入 /xxx
src/cli	进程级 CLI 基础设施（无头模式、传输层、子命令 handler）	claude -p、claude auth login、claude mcp list

src/commands — 会话里的斜杠命令

这是 REPL 交互模式下的命令系统，用户在对话里输入 / 触发。

• 在 commands.ts 里通过 getCommands() 统一注册
• 命令类型包括：
  • local — 纯逻辑，无 UI
  • local-jsx — 带 React/Ink 界面（如 /login、/help）
  • prompt — 转成 prompt 发给模型（如 /review）
• 约 200+ 个模块，覆盖配置、会话、插件、远程控制等

src/cli — Shell 级 CLI 运行时

这是 启动 Claude Code 进程时用的底层能力，不负责 /xxx 斜杠路由。

主要模块：

文件/目录	作用
print.ts	无头/SDK 模式（claude -p）的主循环，约 5500 行
structuredIO.ts / remoteIO.ts	SDK 模式的输入输出格式（JSON、stream-json）
transports/	远程桥接传输（SSE、WebSocket、CCR 客户端）
handlers/	Commander 子命令的实现（auth、mcp、plugins 等）
exit.ts	CLI 退出码与错误输出

main.tsx 用 Commander.js 解析 argv，再动态 import cli/handlers/*：

claude auth login → cli/handlers/auth.ts

claude mcp list → cli/handlers/mcp.tsx

claude -p "..." → cli/print.ts

特点：面向脚本/CI/SDK，输出到 stdout，一般不启动完整 REPL TUI。

用户启动 claude
    │
    ├─ main.tsx (Commander 解析 argv)
    │     ├─ claude auth/mcp/plugin ...  →  src/cli/handlers/*
    │     ├─ claude -p (print 模式)       →  src/cli/print.ts
    │     └─ claude (默认 REPL)           →  launchRepl()
    │
    └─ REPL 里输入 /help、/login ...
              →  src/commands/* (经 commands.ts 路由)

总结

Claude Code 是一个以 query.ts 查询循环 为核心、Ink/React TUI 为界面、tools/ + commands/ + skills/ 为 Agent 能力、services/ 为后端服务的终端 AI 编程助手；支持本地 REPL、非交互 CLI、Agent SDK 和 Remote Control 多种运行模式。

PS:宠物

src/buddy 这个代码中主要实现的是什么功能？

src/buddy 实现的是 Buddy / Companion（伙伴宠物） 功能：在 CLI 输入框旁显示一只 ASCII 精灵宠物，偶尔用气泡说话，并可通过 /buddy 命令孵化与管理。

文件	职责
types.ts	物种、稀有度、属性等类型与常量
companion.ts	基于 userId 的随机生成与读取逻辑
sprites.ts	ASCII 精灵绘制
CompanionSprite.tsx	React/Ink UI 组件
prompt.ts	主模型 system prompt 集成
useBuddyNotification.tsx	启动提示与输入高亮

整体由 特性开关 BUDDY 控制（feature('BUDDY')），未开启时相关逻辑基本不运行。

可孵化的随机伙伴（Companion）

• 用户通过 /buddy 命令「孵化」一只伙伴（命令实现在 src/commands/buddy/，当前仓库里可能未完整还原）。
• 伙伴分两层数据：
  • Bones（外观骨架）：物种、稀有度、眼睛、帽子、是否闪光、五项属性（DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK）——由 userId 哈希确定性随机生成，不写入配置，防止篡改稀有度。
  • Soul（灵魂）：名字、性格描述——由模型生成后持久化到 config.companion

src/buddy 是 Claude Code CLI 的彩蛋式陪伴宠物系统——随机孵化、ASCII 动画、偶尔评论对话，并与主 AI 助手分工协作，而不是替代主助手。