src 顶层模块地图

这页按 src 的顶层结构记录各模块的真实职责和它们在运行链路中的位置，用来先建立“地形图”。

先看体量分布

根据当前代码树统计，src 中体量最大的几个域是：

模块 规模特征 说明
src/utils 500+ 文件级模块 基础设施总线，权限、shell、settings、session、telemetry、插件、swarm 都在这里。
src/components 300+ UI 文件 终端界面不是薄壳，而是带消息语义、权限对话、任务面板和设置系统的完整 TUI。
src/commands 200+ 命令文件 slash command 很多，但它们大多是控制面，不直接承载底层执行。
src/tools 180+ 工具文件 工具是模型能力面的主体，文件操作、shell、agent、MCP、任务、计划模式都在这里。
src/services 130+ 服务文件 API、MCP、compact、memory、analytics、plugins、policy 等平台逻辑。

顶层关键文件

路径 作用
src/main.tsx 进程主入口，负责预取、初始化、参数解析、模式选择和会话装配。
src/entrypoints/init.ts 启动期安全初始化，配置系统、网络代理、mTLS、遥测、scratchpad、清理钩子。
src/bootstrap/state.ts 启动期全局状态与会话级 latch，记录模型、路径、成本、遥测、plan/auto 状态等。
src/query.ts 主 agent 回合，负责模型流、工具执行、恢复、压缩和继续回合。
src/Tool.ts 定义工具接口、ToolUseContext、权限与 UI 渲染契约，是工具系统核心抽象。
src/tools.ts 汇总所有内建工具，按环境、权限、MCP、ToolSearch 策略组装能力面。
src/Task.ts 统一任务类型、状态、ID 规则和后台任务基础字段。
src/commands.ts Slash command 注册入口，把内建命令、技能、插件命令和 MCP 命令统一成一个命令池。
src/context.ts 生成用户/系统上下文，负责把 git 状态、CLAUDE.md、当前日期等注入 prompt。
src/replLauncher.tsx 交互式 REPL 启动封装。
src/interactiveHelpers.tsx 交互式渲染、setup/trust 对话、错误退出、根组件装配。
src/QueryEngine.ts 非 TUI/程序化场景下的查询引擎封装。

按运行链路看 src

1. 启动与模式判定

目录 作用
src/bootstrap 会话级全局状态、统计和启动期共享状态。
src/entrypoints 不同运行入口与初始化逻辑。
src/constants 面向运行时和 prompt 的常量。
src/context.ts prompt 级上下文组装。
src/setup.ts setup 与环境辅助。

2. 主循环与运行时

目录 作用
src/query query loop 的配置、token budget、stop hooks 等子模块。
src/state AppState、store、状态变更监听。
src/hooks 运行时 hook 体系，包括工具前后置、会话后处理、通知和权限桥。
src/services/tools 工具调度、流式执行、并发安全控制。

3. 能力面与后台执行

目录 作用
src/tools 文件、shell、agent、task、MCP、Web、计划模式等所有模型可见工具。
src/tasks 本地 shell、本地 agent、远程 agent、teammate、dream 等后台任务实现。
src/skills 内建技能内容与加载。
src/plugins 内建插件和插件入口。

4. 上下文、记忆与压缩

目录 作用
src/services/compact 自动压缩、手动压缩、微压缩、压缩后清理。
src/services/SessionMemory 会话级 memory 文件维护。
src/services/extractMemories 从对话中抽取长期 memory。
src/services/PromptSuggestion prompt suggestion 与 speculation。
src/services/autoDream 后台整理/自动 dream。
src/memdir memory 目录布局、扫描和持久化格式。

5. UI、命令与交互外壳

目录 作用
src/commands slash commands 的实现与路由。
src/components 消息、输入、权限、任务、设置、diff、MCP、teams 等 Ink/React 组件。
src/ink 终端 UI 基础设施与底层事件/布局。
src/screens 页面级视图，尤其是 REPL.tsx。
src/keybindings 快捷键定义与解析。
src/vim Vim 模式支持。
src/voice 语音输入与语音模式入口。
src/buddy 伴随式 observer/companion。

6. 集成与平台

目录 作用
src/services/api 模型 API、bootstrap、文件 API、重试、请求日志与 cache telemetry。
src/services/mcp MCP 配置、连接、工具/资源/命令接入、channel/elicitation。
src/services/lsp LSP 服务管理、诊断注册与反馈。
src/services/oauth OAuth 客户端与认证流程。
src/services/plugins 插件安装、更新、CLI 集成。
src/services/policyLimits 策略限制加载与刷新。
src/services/remoteManagedSettings 远程托管设置同步与安全检查。
src/services/settingsSync 设置同步。
src/services/teamMemorySync 团队 memory 同步。
src/remote 远程会话管理、WebSocket、远程权限桥。
src/server 直连/服务端 session 创建。
src/bridge CCR bridge、session spawner、远程控制运行时。
src/cli 结构化 I/O、远端 I/O、SSE/WebSocket/Hybrid transport。
src/upstreamproxy 上游代理能力。

7. 基础设施与支撑

目录 作用
src/utils 权限、安全、shell、session、settings、storage、telemetry、plugins、swarm 等通用基础设施。
src/types 共享类型与生成类型。
src/schemas 输入输出 schema。
src/native-ts 性能/原生绑定。
src/migrations 配置与状态迁移。
src/moreright 侧向实验能力。

一条典型调用链

  1. main.tsx 预取系统资源并调用 init()。
  2. 启动期装配 settings、policy、plugins、MCP、commands、tools、初始 AppState。
  3. 交互式模式进入 replLauncher.tsx -> components/App.tsx -> screens/REPL.tsx。
  4. REPL 收集用户输入，调用 query.ts 发起一轮 agent 执行。
  5. query.ts 通过 Tool.ts/tools.ts 暴露工具池，并把工具调用交给 services/tools/*。
  6. 长时执行被转成 tasks/*，上下文膨胀时进入 services/compact/*，记忆相关工作经 SessionMemory/extractMemories 走 forked agent。
  7. 结果最终回到消息流、任务流和 AppState，再由 components/* 和 ink/* 渲染出来。

建议先读的文件

如果只想抓主干，优先看这些位置：

  1. src/main.tsx
  2. src/entrypoints/init.ts
  3. src/bootstrap/state.ts
  4. src/query.ts
  5. src/Tool.ts
  6. src/tools.ts
  7. src/services/tools/toolOrchestration.ts
  8. src/utils/forkedAgent.ts
  9. src/utils/task/framework.ts
  10. src/services/compact/compact.ts
  11. src/services/mcp/useManageMCPConnections.ts