Claude Code 本地源码解读——claw-code项目路径D:\file\project\bigmodel\claw-code-main参考源码泄露版本Claude Code v2.1.88总代码规模51.2万行TS4756个源文件因npm打包遗留.map源码映射文件完整暴露工程代码文档目录项目基础概况与整体分层架构项目目录结构完整拆解附源码文件示例应用完整7阶段启动全流程核心主入口main.tsx会话核心引擎QueryEngine 对话闭环数据流工具系统底层实现40内置工具、权限沙箱模型、代码示例状态管理、服务层、多智能体协调子系统详解两种运行模式REPL交互式 / Print一次性模式对比工程化设计亮点、技术栈、可复用设计模式总结一、项目基础概况与整体分层架构1.1 项目基础信息产品定位Anthropic 企业级终端AI编程助手基于ReactInk实现终端TUI交互支持文件读写、Shell执行、LSP代码分析、MCP第三方工具、多智能体协作运行时Bun替代Node.js利用编译期feature()做功能门控、死代码裁剪入口文件src/main.tsx4683行总大小785KB基于Commander.js解析50CLI启动参数泄露背景2026年3月发布npm包时未过滤.mapsourcemap映射文件完整TS源码对外暴露核心设计思想七层分层架构、高内聚低耦合、统一工具抽象、多层安全权限管控、流式LLM对话循环1.2 七层分层总架构自上而下┌─────────────────────────────────────────────────────────────┐ │ ① 用户交互层 (TUI) │ │ Ink 渲染引擎 ← REPL.tsx ← App.tsx ← 各 UI 组件 │ ├─────────────────────────────────────────────────────────────┤ │ ② 核心引擎层 │ │ QueryEngine.ts / query.ts — LLM 对话编排 │ │ 消息历史 | API 调用 | 流式响应 | Token 管理 │ ├─────────────────────────────────────────────────────────────┤ │ ③ 工具执行层 │ │ BashTool | FileRead/Write/Edit | GlobTool | GrepTool │ │ AgentTool | MCPTool | LSP* | REPLTool | SkillTool ... │ ├─────────────────────────────────────────────────────────────┤ │ ④ 服务支持层 │ │ API 层 | MCP 客户端 | OAuth | Analytics | autoDream │ │ LSP 管理 | 策略限制 | 远程设置 | 上下文压缩 │ ├─────────────────────────────────────────────────────────────┤ │ ⑤ 集成与桥接层 │ │ bridge/ (IDE 集成) | coordinator/ (Swarm多智能体) │ ├─────────────────────────────────────────────────────────────┤ │ ⑥ 状态管理层 │ │ AppState → AppStateStore → store.ts │ ├─────────────────────────────────────────────────────────────┤ │ ⑦ 启动与配置层 │ │ main.tsx → init.ts → setup.ts → config/ │ └─────────────────────────────────────────────────────────────┘分层职责说明交互层终端可视化UI处理键盘输入、消息渲染、权限弹窗仅负责展示无业务逻辑核心引擎层整个项目核心管理会话历史、调用Claude官方API、处理流式SSE响应、驱动工具循环调用工具执行层所有文件/系统/代码/搜索能力统一抽象是LLM落地操作的执行载体服务层封装外部依赖鉴权、遥测、MCP协议、上下文压缩、LSP语言服务桥接协调层IDE插件对接、多智能体任务分发调度状态层全局会话、工具执行、UI状态统一响应式管理启动配置层程序初始化、环境检测、配置加载、命令行参数解析二、项目目录结构完整拆解claw-code-main/src/源码根目录src/完整结构每个目录附核心文件与代码示例src/ ├── main.tsx # CLI 总入口 (Commander.js ~50 个 CLI flag) ├── QueryEngine.ts # 核心 LLM 对话引擎项目核心 ├── query.ts # query() 函数API 调用与流式处理 ├── Tool.ts # 工具抽象基类与类型定义 ├── setup.ts # 会话初始化设置 ├── commands.ts # Slash 交互命令注册/clear /compact /exit │ ├── tools/ # 40 工具实现工具执行层核心 │ ├── BashTool/ │ │ ├── BashTool.tsx # Shell执行主逻辑 │ │ ├── bashSecurity.ts # 命令风险检测 │ │ └── bashPermissions.ts # bash权限校验 │ ├── FileReadTool/ │ ├── FileWriteTool/ │ ├── FileEditTool/ │ ├── AgentTool/ # 多智能体调度工具 │ ├── MCPTool/ │ ├── GlobTool/ │ ├── GrepTool/ │ └── ... │ ├── state/ # 全局状态管理第六层 │ ├── AppState.tsx │ ├── AppStateStore.ts │ └── store.ts │ ├── services/ # 后端服务第四层 │ ├── api/ # Claude API 调用层 │ ├── mcp/ # MCP 协议客户端 │ ├── analytics/ # 事件埋点日志 │ ├── autoDream/ # 会话记忆自动整理系统 │ ├── compact/ # Token上下文压缩 │ ├── lsp/ # LSP 语言服务器管理 │ └── oauth/ # OAuth 企业单点登录 │ ├── bridge/ # IDE集成桥接层第五层 │ ├── bridgeMain.ts │ ├── replBridge.ts │ ├── coordinator/ # 多智能体协调调度 │ └── coordinatorMode.ts │ ├── buddy/ # 彩蛋宠物系统 │ └── utils/ # 通用工具函数 ├── permissions/ # 全局权限工具 ├── hooks/ # React生命周期钩子2.1 核心基础文件代码示例示例1src/Tool.ts 工具统一抽象基类所有工具必须实现该接口实现标准化调度// src/Tool.ts export type Tool { name: string description: string inputJSONSchema: ToolInputJSONSchema // 上下文判断工具是否启用 isEnabled: (context: ToolUseContext) boolean // 是否只读工具只读不会触发文件修改权限弹窗 isReadOnly: boolean // 权限校验逻辑 canUse: (ctx: ToolUseContext, input: Recordstring,any) PromiseToolPermissionResult // 工具执行入口 call: (input: Recordstring,any, ctx: ToolUseContext) Promisestring } // 权限行为枚举 export type PermissionBehavior allow | ask | deny export interface ToolPermissionResult { behavior: PermissionBehavior reason?: string }示例2src/state/store.ts 自定义响应式状态库不使用Redux/Zustand自研轻量状态容器// src/state/store.ts export function createStoreT(initialState: T) { let state initialState const listeners new Set(state: T, prevState: T) void() return { getState: () state, setState: (updater: (prev: T) T) { const prev structuredClone(state) state updater(prev) // 通知所有订阅者更新UI listeners.forEach(l l(state, prev)) }, subscribe: (listener) { listeners.add(listener) return () listeners.delete(listener) } } }三、应用完整7阶段启动全流程main.tsx 主线程序启动全部逻辑集中在src/main.tsx整体分为7大阶段每个阶段附带源码位置与执行逻辑。阶段0模块并行预热导入即执行无阻塞文件头部并行启动慢IO操作充分利用模块加载等待时间提升启动速度// main.tsx 1-20行 模块级副作用 import { profileCheckpoint } from ./utils/startupProfiler.js profileCheckpoint(main_tsx_entry) // 启动性能埋点计时 import { startMdmRawRead } from ./utils/settings/mdm/rawRead.js startMdmRawRead() // 并行读取企业MDM配置 import { startKeychainPrefetch } from ./utils/secureStorage/keychainPrefetch.js startKeychainPrefetch() // 预加载macOS密钥链API密钥阶段1main() 环境安全与参数预处理源码行号约590-840核心工作系统安全加固、URL链路解析、客户端类型区分核心逻辑清单Windows 开启NoDefaultCurrentDirectoryInExePath1防止PATH劫持漏洞注册SIGINT/进程退出信号实现终端优雅关闭解析cc://远程连接链接、DeepLink唤起会话识别三种特殊模式KAIROS后台助手模式、SSH远程会话、-p一次性打印模式区分客户端类型cli / vscode插件 / sdk-py / sdk-ts 远程客户端阶段2run() Commander CLI框架初始化使用Commander.js注册50启动参数核心preAction钩子作为全局初始化入口// main.tsx run() 核心代码 async function run(): PromiseCommanderCommand { const program new CommanderCommand() .configureHelp(createSortedHelpConfig()) .enablePositionalOptions() // 所有命令执行前统一初始化 program.hook(preAction, async (thisCommand) { await ensureMdmSettingsLoaded() await ensureKeychainPrefetchCompleted() await init() // 全局初始化核心函数 await initSinks() // 日志埋点初始化 runMigrations() // 配置版本迁移 v1~v11 void loadRemoteManagedSettings() // 企业远程配置非阻塞 void loadPolicyLimits() // 全局策略限制非阻塞 }) // 注册核心CLI参数 program .option(-p, --print, Print response and exit) .option(--bare, Minimal lightweight mode) .option(--model model, Specify llm model for session) .option(--permission-mode mode, Tool permission policy) .action(async (prompt, options) { // 阶段4会话业务逻辑入口 }) }阶段3init() 全局基础初始化entrypoints/init.tsmemoize单例函数全局仅执行一次完成底层环境、网络、代理、IDE检测执行流程图init_function_start │ ├──► enableConfigs() // 启用配置系统 ├──► applySafeConfigEnvironmentVariables() // 加载安全环境变量 ├──► applyExtraCACertsFromConfig() // 自定义HTTPS证书 ├──► setupGracefulShutdown() // 进程退出监听 │ ├──► 初始化埋点统计 动态加载FeatureFlag ├──► populateOAuthAccountInfoIfNeeded() // OAuth账户信息预加载 ├──► initJetBrainsDetection() // IDE环境检测 ├──► detectCurrentRepository() // 自动识别Git仓库 │ ├──► configureGlobalMTLS() // 双向TLS企业加密 ├──► configureGlobalAgents() // HTTP代理配置 ├──► preconnectAnthropicApi() // 预连接Claude接口减少首包延迟 │ ├──► initUpstreamProxy() // 上游代理服务 └──► setShellIfWindows() // Windows自动切换GitBash阶段4action() 会话参数解析最复杂3000行逻辑解析所有CLI入参区分运行模式、加载MCP配置、初始化LSP、权限上下文核心分支--bare极简模式跳过绝大多数初始化轻量运行KAIROS后台常驻模式启动持久化智能体后台解析模型、权限、工具黑白名单、会话恢复参数--continue/--resume并行加载Slash命令、自定义Agent智能体配置调用setup()完成会话专属初始化阶段5setup() 会话级专属初始化setup.ts每个独立会话单独执行隔离多会话环境核心校验Node版本校验最低v18项目Git根目录自动识别锁定工作区信任弹窗校验首次打开项目需确认信任目录否则不加载.claude自定义配置Git worktree、tmux多会话隔离支持文件监听Watcher、会话记忆系统初始化API密钥安全预取、配置快照缓存阶段6分支路由三种运行入口setup完成后根据参数分流三种执行路径┌─────────────────┐ │ action() 结束 │ │ 进入分支逻辑 │ └────────┬────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐ │ --print (-p) │ │ --continue │ │ 默认REPL交互会话 │ │ 一次性打印模式 │ │ 会话恢复模式 │ │ │ └───────┬───────┘ └───────┬───────┘ └─────────┬─────────┘ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐ │ runHeadless() │ │ 加载历史对话 │ │ 初始化空会话 │ │ (print.ts) │ │ processResumed│ │ │ │ 创建QueryEngine│ │ Conversation │ │ │ │ 单次调用API │ │ 恢复消息历史 │ │ │ │ 输出结果退出 │ │ │ │ │ └───────────────┘ └─────────┬─────┘ └─────────┬─────────┘ │ │ └─────────┬─────────┘ ▼ ┌───────────────────┐ │ launchRepl() │ │ │ │ App REPL / │ │ /App │ └───────────────────┘阶段7REPL终端交互循环启动launchRepl.tsx仅交互式模式执行基于Ink渲染终端UI挂载输入监听完整对话闭环入口// replLauncher.tsx 核心代码 export async function launchRepl( root: Root, appProps: AppWrapperProps, replProps: REPLProps, renderAndRun: (root: Root, element: React.ReactNode) Promisevoid ): Promisevoid { // 动态懒加载UI组件不阻塞初始化 const { App } await import(./components/App.js) const { REPL } await import(./screens/REPL.js) // Ink渲染终端界面 await renderAndRun(root, App {...appProps} REPL {...replProps} / /App ) }REPL渲染完成后异步后台预加载非阻塞资源用户信息、项目上下文、文件统计、MCP远程配置等不阻塞用户输入。四、会话核心引擎QueryEngine 对话闭环数据流QueryEngine.ts是整个项目核心一个实例对应一个独立会话持有完整消息历史、Token用量、工具缓存所有LLM对话、工具调用循环均由该类驱动。4.1 QueryEngine 核心数据结构// QueryEngine.ts 类定义 export class QueryEngine { private config: QueryEngineConfig // 工具、MCP、模型全局配置 private mutableMessages: Message[] // 会话完整消息历史用户/助手/工具返回 private abortController: AbortController // 流式请求中断控制器 private permissionDenials: SDKPermissionDenial[] // 用户拒绝工具权限记录 private totalUsage: NonNullableUsage // 累计token消耗统计 private readFileState: FileStateCache // 文件读取缓存减少重复IO }4.2 核心函数 submitMessage 完整8步执行流程用户输入触发入口AsyncGenerator流式输出实时内容支持边推边渲染UIsubmitMessage 开始 │ ├──► 1. 构建完整System Prompt │ ├── 基础角色提示词 安全约束 │ ├── 所有启用工具JSON Schema描述 │ ├── MCP第三方工具定义 │ ├── 项目CLAUDE.md、会话记忆上下文 │ └── 多智能体Coordinator调度上下文 │ ├──► 2. 处理用户输入 │ ├── Slash命令解析 /clear /compact /exit │ ├── 图片、附件文件解析 │ └── 消息优先级队列管理 │ ├──► 3. 标准化API请求消息 │ ├── 历史消息格式转换为Claude SDK标准格式 │ ├── 附加Git状态、系统环境上下文 │ ├──► 4. 发起流式SSE API请求 │ └── streamMessage() 建立长连接分块返回模型输出 │ ├──► 5. 流式分块处理 │ ├── 普通文本块 → 实时yield推送UI渲染 │ ├── thinking思考块 → 展示模型思考过程 │ └── tool_use工具调用块 → 进入工具执行分支 │ ├──► 6. 工具执行循环核心闭环 │ ├── 根据tool名称匹配对应Tool实例 │ ├── 执行canUse权限校验allow/ask/deny │ │ ├ allow → 直接执行tool.call() │ │ ├ ask → 暂停弹出终端权限弹窗等待用户确认 │ │ └ deny → 记录拒绝终止本次工具调用 │ ├── 工具执行结果封装为ToolResult消息插入历史 │ └── 回到步骤3携带工具结果再次请求LLM多轮循环 │ ├──► 7. 会话后置处理 │ ├── 统计token消耗校验预算上限 │ ├── 判断上下文长度触发compact自动压缩历史 │ ├── 持久化会话记录到本地缓存 │ └──► 8. 对话一轮结束返回完整消息4.3 全局对话数据流总图┌─────────┐ ┌─────────────┐ ┌─────────────────┐ │ 用户 │────►│ 键盘输入 │────►│ REPL.tsx │ │ │ │ (Ink TUI) │ │ (UI 渲染层) │ └────▲────┘ └─────────────┘ └────────┬────────┘ │ │ │ ① 用户输入 prompt │ │ ▼ │ ┌─────────────────┐ │ │ QueryEngine. │ │ │ submitMessage() │ │ └────────┬────────┘ │ │ │ ② 构建完整上下文 │ │ (System Prompt History) ▼ │ ┌─────────────────┐ │ │ Claude API │ │ │ (streamMessage)│ │ └────────┬────────┘ │ │ │ ③ 流式 SSE 响应 │ │ ┌────────┴────────┐ │ ▼ ▼ │ ┌─────────────┐ ┌─────────────────┐ │ │ 文本内容 │ │ tool_use 块 │ │ │ → 直接展示 │ │ → 进入工具分支 │ │ └──────┬──────┘ └────────┬────────┘ │ │ │ │ │ ┌─────────┴─────────┐ │ │ ▼ ▼ │ │ ┌────────────┐ ┌──────────────┐ │ │ │ 权限检查 │ │ 执行工具 │ │ │ │ CanUseTool │───►│ Tool.call() │ │ │ └────────────┘ └──────┬───────┘ │ │ │ │ │ ┌────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ 工具执行结果 │ │ │ │ ToolResult │ │ │ └────────┬────────┘ │ │ │ │ └──────────────┘ │ │ │ ④ 更新消息历史 │ │ (追加 assistant tool_result) ▼ │ ┌─────────────────┐ │ │ 上下文检查 │ │ │ - Token 超限? │──是──► Compact │ │ - 预算耗尽? │──是──► 停止 │ │ - 达到 max-turns│──是──► 退出 │ └────────┬────────┘ │ │ 否 │ ⑤ 如果还有 tool_use │ │ 回到步骤 ② 循环 │ │ ▼ │ ┌─────────────────┐ └──────────────────────────────┤ 渲染最终结果 │ │ 展示给用户 │ └─────────────────┘五、工具系统底层实现src/tools/工具是LLM落地操作的核心载体内置40工具统一实现Tool接口分层权限沙箱双重安全防护。5.1 工具分类总表工具类别代表工具核心能力安全特性文件操作FileReadTool/FileWriteTool/FileEditTool读取、写入、精准代码替换路径遍历拦截、只读校验系统命令BashTool/PowerShellTool执行终端命令、交互式REPL命令语义风险检测、自动沙箱代码分析LSPTool语法解析、函数跳转、错误检测仅读取代码禁止修改搜索工具GrepTool/GlobTool/WebSearchTool全局文本检索、文件匹配、联网搜索无写入风险默认allow权限多智能体AgentTool子智能体任务分发、团队协作独立会话隔离第三方扩展MCPTool对接自定义MCP服务插件配置白名单管控5.2 BashTool 完整代码分层示例风险最高工具目录结构BashTool/ ├── BashTool.tsx (160KB) # 主工具执行入口 ├── bashSecurity.ts (102KB) # 命令风险语义解析 ├── bashPermissions.ts (98KB) # 权限分级校验 ├── pathValidation.ts (43KB) # 路径非法操作拦截 ├── readOnlyValidation.ts (68KB) # 只读模式限制 ├── prompt.ts (21KB) # 权限弹窗UI文本 └── UI.tsx (25KB) # 终端进度展示组件bashSecurity.ts 风险检测示例代码// bashSecurity.ts 命令风险识别 export function parseCommandRisk(cmd: string): RiskLevel { const dangerousPatterns [ /rm\s-rf/, /chmod\s777/, /sudo\srm/, /\/etc\/|\/usr\//, /curl.*\|bash/ ] for (const reg of dangerousPatterns) { if (reg.test(cmd)) return high } return low }风险等级为high时自动强制进入沙箱执行同时触发用户二次确认弹窗。5.3 三层权限安全模型工具全局权限permission-modeCLI参数全局控制accept-all/auto/deny-all工具独立权限每个工具内置canUse函数区分只读/修改/高危操作会话临时权限单次会话临时禁用指定工具不修改全局配置权限三种行为allow自动执行无需弹窗ask弹出终端确认框用户同意后执行deny直接拒绝返回工具执行失败信息六、子系统模块深度解析6.1 状态管理系统src/state架构自定义Store React Context 混合无第三方状态库轻量化、可序列化持久化AppStateStore全局单例存储保存会话、UI、工具执行全局数据AppState.tsxReact Context Provider向所有UI组件注入状态细粒度拆分SessionState会话状态、ToolState工具运行状态、UiState弹窗/输入状态响应式机制subscribe订阅状态变更自动刷新Ink终端UI6.2 服务层核心子系统src/services/compact 上下文压缩当消息历史Token超限自动精简历史对话保留关键逻辑降低API开销autoDream 记忆整理会话闲置后台异步总结对话长期记忆持久化减少重复上下文占用mcp MCP协议客户端标准化第三方插件接入统一和内置工具调度逻辑lsp 语言服务管理自动启动对应语言LSP获取代码定义、报错、补全信息analytics 埋点系统记录工具调用、模型切换、权限交互企业审计日志6.3 coordinator 多智能体协调coordinatorMode.ts实现Swarm集群智能体主智能体拆分复杂任务分发给子AgentTool子会话各子智能体独立上下文隔离互不干扰任务完成汇总结果合并返回主对话流通过FeatureFlagCOORDINATOR_MODE控制是否启用默认关闭减少token消耗七、两种运行模式对比REPL / Print7.1 核心差异对照表对比项REPL交互式模式claudePrint一次性模式claude -p启动入口launchRepl()runHeadless()UI渲染Ink完整终端交互界面无UI纯标准输出流会话生命周期持续多轮对话历史持久化单次请求执行后销毁会话状态管理React Context AppStateStore仅QueryEngine内部临时状态适用场景本地开发持续对话、调试CI脚本、自动化流水线、批量任务资源占用常驻进程缓存文件/Git上下文一次性进程执行后释放内存7.2 Print模式核心简化逻辑// print.ts runHeadless 简化流程 export async function runHeadless(prompt: string, options: CliOptions) { // 直接创建临时QueryEngine跳过全部UI初始化 const engine new QueryEngine(config) // 单次流式请求收集全部输出 const fullOutput [] for await (const chunk of engine.submitMessage(prompt)) { if (chunk.type text) fullOutput.push(chunk.text) } // 直接打印结果进程退出 console.log(fullOutput.join()) process.exit(0) }八、工程化设计亮点与技术栈总结8.1 核心技术栈运行时Bun编译期Feature Flag、死代码消除UIReact Ink终端组件渲染类型TypeScript5 Zod全量数据校验CLI解析Commander.js状态自研Store无第三方依赖构建Bun Bundle打包代码规范Biome替代Prettier、ESLint自定义规则8.2 可复用设计模式可迁移至自研大模型工具工具注册表模式统一抽象Tool基类自动注册所有工具新增工具无需修改核心调度逻辑权限中间件模式工具执行前置统一校验分层拦截风险操作流式生成器对话AsyncGenerator实现实时输出UI分片渲染等待无卡顿并行预热启动模块加载阶段并行执行IO慢操作大幅降低冷启动耗时功能门控FeatureFlag编译期裁剪未启用功能减少打包体积上下文自动压缩动态Token管理解决大上下文窗口超限问题8.3 架构优势总结分层解耦UI、引擎、工具、服务职责完全隔离单独迭代维护安全完善权限校验、命令沙箱、路径防护、操作审计多层防护扩展性强MCP插件、自定义Slash命令、多智能体集群易于扩展性能优化预连接API、文件缓存、并行初始化、懒加载UI组件企业级适配MDM远程配置、SSO单点、策略限制、审计日志原生支持8.4 开发借鉴建议小型AI编程工具简化七层架构保留「入口初始化-对话引擎-工具系统」三层核心安全优先复刻工具分层权限模型高危操作强制二次确认交互体验参考Ink终端TUI实现流式实时输出提升用户体感轻量化改造移除KAIROS后台、多智能体、MCP等高级Feature降低工程复杂度
Claude Code 本地源码解读——claw-code
发布时间：2026/7/6 1:24:47
Claude Code 本地源码解读——claw-code项目路径D:\file\project\bigmodel\claw-code-main参考源码泄露版本Claude Code v2.1.88总代码规模51.2万行TS4756个源文件因npm打包遗留.map源码映射文件完整暴露工程代码文档目录项目基础概况与整体分层架构项目目录结构完整拆解附源码文件示例应用完整7阶段启动全流程核心主入口main.tsx会话核心引擎QueryEngine 对话闭环数据流工具系统底层实现40内置工具、权限沙箱模型、代码示例状态管理、服务层、多智能体协调子系统详解两种运行模式REPL交互式 / Print一次性模式对比工程化设计亮点、技术栈、可复用设计模式总结一、项目基础概况与整体分层架构1.1 项目基础信息产品定位Anthropic 企业级终端AI编程助手基于ReactInk实现终端TUI交互支持文件读写、Shell执行、LSP代码分析、MCP第三方工具、多智能体协作运行时Bun替代Node.js利用编译期feature()做功能门控、死代码裁剪入口文件src/main.tsx4683行总大小785KB基于Commander.js解析50CLI启动参数泄露背景2026年3月发布npm包时未过滤.mapsourcemap映射文件完整TS源码对外暴露核心设计思想七层分层架构、高内聚低耦合、统一工具抽象、多层安全权限管控、流式LLM对话循环1.2 七层分层总架构自上而下┌─────────────────────────────────────────────────────────────┐ │ ① 用户交互层 (TUI) │ │ Ink 渲染引擎 ← REPL.tsx ← App.tsx ← 各 UI 组件 │ ├─────────────────────────────────────────────────────────────┤ │ ② 核心引擎层 │ │ QueryEngine.ts / query.ts — LLM 对话编排 │ │ 消息历史 | API 调用 | 流式响应 | Token 管理 │ ├─────────────────────────────────────────────────────────────┤ │ ③ 工具执行层 │ │ BashTool | FileRead/Write/Edit | GlobTool | GrepTool │ │ AgentTool | MCPTool | LSP* | REPLTool | SkillTool ... │ ├─────────────────────────────────────────────────────────────┤ │ ④ 服务支持层 │ │ API 层 | MCP 客户端 | OAuth | Analytics | autoDream │ │ LSP 管理 | 策略限制 | 远程设置 | 上下文压缩 │ ├─────────────────────────────────────────────────────────────┤ │ ⑤ 集成与桥接层 │ │ bridge/ (IDE 集成) | coordinator/ (Swarm多智能体) │ ├─────────────────────────────────────────────────────────────┤ │ ⑥ 状态管理层 │ │ AppState → AppStateStore → store.ts │ ├─────────────────────────────────────────────────────────────┤ │ ⑦ 启动与配置层 │ │ main.tsx → init.ts → setup.ts → config/ │ └─────────────────────────────────────────────────────────────┘分层职责说明交互层终端可视化UI处理键盘输入、消息渲染、权限弹窗仅负责展示无业务逻辑核心引擎层整个项目核心管理会话历史、调用Claude官方API、处理流式SSE响应、驱动工具循环调用工具执行层所有文件/系统/代码/搜索能力统一抽象是LLM落地操作的执行载体服务层封装外部依赖鉴权、遥测、MCP协议、上下文压缩、LSP语言服务桥接协调层IDE插件对接、多智能体任务分发调度状态层全局会话、工具执行、UI状态统一响应式管理启动配置层程序初始化、环境检测、配置加载、命令行参数解析二、项目目录结构完整拆解claw-code-main/src/源码根目录src/完整结构每个目录附核心文件与代码示例src/ ├── main.tsx # CLI 总入口 (Commander.js ~50 个 CLI flag) ├── QueryEngine.ts # 核心 LLM 对话引擎项目核心 ├── query.ts # query() 函数API 调用与流式处理 ├── Tool.ts # 工具抽象基类与类型定义 ├── setup.ts # 会话初始化设置 ├── commands.ts # Slash 交互命令注册/clear /compact /exit │ ├── tools/ # 40 工具实现工具执行层核心 │ ├── BashTool/ │ │ ├── BashTool.tsx # Shell执行主逻辑 │ │ ├── bashSecurity.ts # 命令风险检测 │ │ └── bashPermissions.ts # bash权限校验 │ ├── FileReadTool/ │ ├── FileWriteTool/ │ ├── FileEditTool/ │ ├── AgentTool/ # 多智能体调度工具 │ ├── MCPTool/ │ ├── GlobTool/ │ ├── GrepTool/ │ └── ... │ ├── state/ # 全局状态管理第六层 │ ├── AppState.tsx │ ├── AppStateStore.ts │ └── store.ts │ ├── services/ # 后端服务第四层 │ ├── api/ # Claude API 调用层 │ ├── mcp/ # MCP 协议客户端 │ ├── analytics/ # 事件埋点日志 │ ├── autoDream/ # 会话记忆自动整理系统 │ ├── compact/ # Token上下文压缩 │ ├── lsp/ # LSP 语言服务器管理 │ └── oauth/ # OAuth 企业单点登录 │ ├── bridge/ # IDE集成桥接层第五层 │ ├── bridgeMain.ts │ ├── replBridge.ts │ ├── coordinator/ # 多智能体协调调度 │ └── coordinatorMode.ts │ ├── buddy/ # 彩蛋宠物系统 │ └── utils/ # 通用工具函数 ├── permissions/ # 全局权限工具 ├── hooks/ # React生命周期钩子2.1 核心基础文件代码示例示例1src/Tool.ts 工具统一抽象基类所有工具必须实现该接口实现标准化调度// src/Tool.ts export type Tool { name: string description: string inputJSONSchema: ToolInputJSONSchema // 上下文判断工具是否启用 isEnabled: (context: ToolUseContext) boolean // 是否只读工具只读不会触发文件修改权限弹窗 isReadOnly: boolean // 权限校验逻辑 canUse: (ctx: ToolUseContext, input: Recordstring,any) PromiseToolPermissionResult // 工具执行入口 call: (input: Recordstring,any, ctx: ToolUseContext) Promisestring } // 权限行为枚举 export type PermissionBehavior allow | ask | deny export interface ToolPermissionResult { behavior: PermissionBehavior reason?: string }示例2src/state/store.ts 自定义响应式状态库不使用Redux/Zustand自研轻量状态容器// src/state/store.ts export function createStoreT(initialState: T) { let state initialState const listeners new Set(state: T, prevState: T) void() return { getState: () state, setState: (updater: (prev: T) T) { const prev structuredClone(state) state updater(prev) // 通知所有订阅者更新UI listeners.forEach(l l(state, prev)) }, subscribe: (listener) { listeners.add(listener) return () listeners.delete(listener) } } }三、应用完整7阶段启动全流程main.tsx 主线程序启动全部逻辑集中在src/main.tsx整体分为7大阶段每个阶段附带源码位置与执行逻辑。阶段0模块并行预热导入即执行无阻塞文件头部并行启动慢IO操作充分利用模块加载等待时间提升启动速度// main.tsx 1-20行 模块级副作用 import { profileCheckpoint } from ./utils/startupProfiler.js profileCheckpoint(main_tsx_entry) // 启动性能埋点计时 import { startMdmRawRead } from ./utils/settings/mdm/rawRead.js startMdmRawRead() // 并行读取企业MDM配置 import { startKeychainPrefetch } from ./utils/secureStorage/keychainPrefetch.js startKeychainPrefetch() // 预加载macOS密钥链API密钥阶段1main() 环境安全与参数预处理源码行号约590-840核心工作系统安全加固、URL链路解析、客户端类型区分核心逻辑清单Windows 开启NoDefaultCurrentDirectoryInExePath1防止PATH劫持漏洞注册SIGINT/进程退出信号实现终端优雅关闭解析cc://远程连接链接、DeepLink唤起会话识别三种特殊模式KAIROS后台助手模式、SSH远程会话、-p一次性打印模式区分客户端类型cli / vscode插件 / sdk-py / sdk-ts 远程客户端阶段2run() Commander CLI框架初始化使用Commander.js注册50启动参数核心preAction钩子作为全局初始化入口// main.tsx run() 核心代码 async function run(): PromiseCommanderCommand { const program new CommanderCommand() .configureHelp(createSortedHelpConfig()) .enablePositionalOptions() // 所有命令执行前统一初始化 program.hook(preAction, async (thisCommand) { await ensureMdmSettingsLoaded() await ensureKeychainPrefetchCompleted() await init() // 全局初始化核心函数 await initSinks() // 日志埋点初始化 runMigrations() // 配置版本迁移 v1~v11 void loadRemoteManagedSettings() // 企业远程配置非阻塞 void loadPolicyLimits() // 全局策略限制非阻塞 }) // 注册核心CLI参数 program .option(-p, --print, Print response and exit) .option(--bare, Minimal lightweight mode) .option(--model model, Specify llm model for session) .option(--permission-mode mode, Tool permission policy) .action(async (prompt, options) { // 阶段4会话业务逻辑入口 }) }阶段3init() 全局基础初始化entrypoints/init.tsmemoize单例函数全局仅执行一次完成底层环境、网络、代理、IDE检测执行流程图init_function_start │ ├──► enableConfigs() // 启用配置系统 ├──► applySafeConfigEnvironmentVariables() // 加载安全环境变量 ├──► applyExtraCACertsFromConfig() // 自定义HTTPS证书 ├──► setupGracefulShutdown() // 进程退出监听 │ ├──► 初始化埋点统计 动态加载FeatureFlag ├──► populateOAuthAccountInfoIfNeeded() // OAuth账户信息预加载 ├──► initJetBrainsDetection() // IDE环境检测 ├──► detectCurrentRepository() // 自动识别Git仓库 │ ├──► configureGlobalMTLS() // 双向TLS企业加密 ├──► configureGlobalAgents() // HTTP代理配置 ├──► preconnectAnthropicApi() // 预连接Claude接口减少首包延迟 │ ├──► initUpstreamProxy() // 上游代理服务 └──► setShellIfWindows() // Windows自动切换GitBash阶段4action() 会话参数解析最复杂3000行逻辑解析所有CLI入参区分运行模式、加载MCP配置、初始化LSP、权限上下文核心分支--bare极简模式跳过绝大多数初始化轻量运行KAIROS后台常驻模式启动持久化智能体后台解析模型、权限、工具黑白名单、会话恢复参数--continue/--resume并行加载Slash命令、自定义Agent智能体配置调用setup()完成会话专属初始化阶段5setup() 会话级专属初始化setup.ts每个独立会话单独执行隔离多会话环境核心校验Node版本校验最低v18项目Git根目录自动识别锁定工作区信任弹窗校验首次打开项目需确认信任目录否则不加载.claude自定义配置Git worktree、tmux多会话隔离支持文件监听Watcher、会话记忆系统初始化API密钥安全预取、配置快照缓存阶段6分支路由三种运行入口setup完成后根据参数分流三种执行路径┌─────────────────┐ │ action() 结束 │ │ 进入分支逻辑 │ └────────┬────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐ │ --print (-p) │ │ --continue │ │ 默认REPL交互会话 │ │ 一次性打印模式 │ │ 会话恢复模式 │ │ │ └───────┬───────┘ └───────┬───────┘ └─────────┬─────────┘ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐ │ runHeadless() │ │ 加载历史对话 │ │ 初始化空会话 │ │ (print.ts) │ │ processResumed│ │ │ │ 创建QueryEngine│ │ Conversation │ │ │ │ 单次调用API │ │ 恢复消息历史 │ │ │ │ 输出结果退出 │ │ │ │ │ └───────────────┘ └─────────┬─────┘ └─────────┬─────────┘ │ │ └─────────┬─────────┘ ▼ ┌───────────────────┐ │ launchRepl() │ │ │ │ App REPL / │ │ /App │ └───────────────────┘阶段7REPL终端交互循环启动launchRepl.tsx仅交互式模式执行基于Ink渲染终端UI挂载输入监听完整对话闭环入口// replLauncher.tsx 核心代码 export async function launchRepl( root: Root, appProps: AppWrapperProps, replProps: REPLProps, renderAndRun: (root: Root, element: React.ReactNode) Promisevoid ): Promisevoid { // 动态懒加载UI组件不阻塞初始化 const { App } await import(./components/App.js) const { REPL } await import(./screens/REPL.js) // Ink渲染终端界面 await renderAndRun(root, App {...appProps} REPL {...replProps} / /App ) }REPL渲染完成后异步后台预加载非阻塞资源用户信息、项目上下文、文件统计、MCP远程配置等不阻塞用户输入。四、会话核心引擎QueryEngine 对话闭环数据流QueryEngine.ts是整个项目核心一个实例对应一个独立会话持有完整消息历史、Token用量、工具缓存所有LLM对话、工具调用循环均由该类驱动。4.1 QueryEngine 核心数据结构// QueryEngine.ts 类定义 export class QueryEngine { private config: QueryEngineConfig // 工具、MCP、模型全局配置 private mutableMessages: Message[] // 会话完整消息历史用户/助手/工具返回 private abortController: AbortController // 流式请求中断控制器 private permissionDenials: SDKPermissionDenial[] // 用户拒绝工具权限记录 private totalUsage: NonNullableUsage // 累计token消耗统计 private readFileState: FileStateCache // 文件读取缓存减少重复IO }4.2 核心函数 submitMessage 完整8步执行流程用户输入触发入口AsyncGenerator流式输出实时内容支持边推边渲染UIsubmitMessage 开始 │ ├──► 1. 构建完整System Prompt │ ├── 基础角色提示词 安全约束 │ ├── 所有启用工具JSON Schema描述 │ ├── MCP第三方工具定义 │ ├── 项目CLAUDE.md、会话记忆上下文 │ └── 多智能体Coordinator调度上下文 │ ├──► 2. 处理用户输入 │ ├── Slash命令解析 /clear /compact /exit │ ├── 图片、附件文件解析 │ └── 消息优先级队列管理 │ ├──► 3. 标准化API请求消息 │ ├── 历史消息格式转换为Claude SDK标准格式 │ ├── 附加Git状态、系统环境上下文 │ ├──► 4. 发起流式SSE API请求 │ └── streamMessage() 建立长连接分块返回模型输出 │ ├──► 5. 流式分块处理 │ ├── 普通文本块 → 实时yield推送UI渲染 │ ├── thinking思考块 → 展示模型思考过程 │ └── tool_use工具调用块 → 进入工具执行分支 │ ├──► 6. 工具执行循环核心闭环 │ ├── 根据tool名称匹配对应Tool实例 │ ├── 执行canUse权限校验allow/ask/deny │ │ ├ allow → 直接执行tool.call() │ │ ├ ask → 暂停弹出终端权限弹窗等待用户确认 │ │ └ deny → 记录拒绝终止本次工具调用 │ ├── 工具执行结果封装为ToolResult消息插入历史 │ └── 回到步骤3携带工具结果再次请求LLM多轮循环 │ ├──► 7. 会话后置处理 │ ├── 统计token消耗校验预算上限 │ ├── 判断上下文长度触发compact自动压缩历史 │ ├── 持久化会话记录到本地缓存 │ └──► 8. 对话一轮结束返回完整消息4.3 全局对话数据流总图┌─────────┐ ┌─────────────┐ ┌─────────────────┐ │ 用户 │────►│ 键盘输入 │────►│ REPL.tsx │ │ │ │ (Ink TUI) │ │ (UI 渲染层) │ └────▲────┘ └─────────────┘ └────────┬────────┘ │ │ │ ① 用户输入 prompt │ │ ▼ │ ┌─────────────────┐ │ │ QueryEngine. │ │ │ submitMessage() │ │ └────────┬────────┘ │ │ │ ② 构建完整上下文 │ │ (System Prompt History) ▼ │ ┌─────────────────┐ │ │ Claude API │ │ │ (streamMessage)│ │ └────────┬────────┘ │ │ │ ③ 流式 SSE 响应 │ │ ┌────────┴────────┐ │ ▼ ▼ │ ┌─────────────┐ ┌─────────────────┐ │ │ 文本内容 │ │ tool_use 块 │ │ │ → 直接展示 │ │ → 进入工具分支 │ │ └──────┬──────┘ └────────┬────────┘ │ │ │ │ │ ┌─────────┴─────────┐ │ │ ▼ ▼ │ │ ┌────────────┐ ┌──────────────┐ │ │ │ 权限检查 │ │ 执行工具 │ │ │ │ CanUseTool │───►│ Tool.call() │ │ │ └────────────┘ └──────┬───────┘ │ │ │ │ │ ┌────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ 工具执行结果 │ │ │ │ ToolResult │ │ │ └────────┬────────┘ │ │ │ │ └──────────────┘ │ │ │ ④ 更新消息历史 │ │ (追加 assistant tool_result) ▼ │ ┌─────────────────┐ │ │ 上下文检查 │ │ │ - Token 超限? │──是──► Compact │ │ - 预算耗尽? │──是──► 停止 │ │ - 达到 max-turns│──是──► 退出 │ └────────┬────────┘ │ │ 否 │ ⑤ 如果还有 tool_use │ │ 回到步骤 ② 循环 │ │ ▼ │ ┌─────────────────┐ └──────────────────────────────┤ 渲染最终结果 │ │ 展示给用户 │ └─────────────────┘五、工具系统底层实现src/tools/工具是LLM落地操作的核心载体内置40工具统一实现Tool接口分层权限沙箱双重安全防护。5.1 工具分类总表工具类别代表工具核心能力安全特性文件操作FileReadTool/FileWriteTool/FileEditTool读取、写入、精准代码替换路径遍历拦截、只读校验系统命令BashTool/PowerShellTool执行终端命令、交互式REPL命令语义风险检测、自动沙箱代码分析LSPTool语法解析、函数跳转、错误检测仅读取代码禁止修改搜索工具GrepTool/GlobTool/WebSearchTool全局文本检索、文件匹配、联网搜索无写入风险默认allow权限多智能体AgentTool子智能体任务分发、团队协作独立会话隔离第三方扩展MCPTool对接自定义MCP服务插件配置白名单管控5.2 BashTool 完整代码分层示例风险最高工具目录结构BashTool/ ├── BashTool.tsx (160KB) # 主工具执行入口 ├── bashSecurity.ts (102KB) # 命令风险语义解析 ├── bashPermissions.ts (98KB) # 权限分级校验 ├── pathValidation.ts (43KB) # 路径非法操作拦截 ├── readOnlyValidation.ts (68KB) # 只读模式限制 ├── prompt.ts (21KB) # 权限弹窗UI文本 └── UI.tsx (25KB) # 终端进度展示组件bashSecurity.ts 风险检测示例代码// bashSecurity.ts 命令风险识别 export function parseCommandRisk(cmd: string): RiskLevel { const dangerousPatterns [ /rm\s-rf/, /chmod\s777/, /sudo\srm/, /\/etc\/|\/usr\//, /curl.*\|bash/ ] for (const reg of dangerousPatterns) { if (reg.test(cmd)) return high } return low }风险等级为high时自动强制进入沙箱执行同时触发用户二次确认弹窗。5.3 三层权限安全模型工具全局权限permission-modeCLI参数全局控制accept-all/auto/deny-all工具独立权限每个工具内置canUse函数区分只读/修改/高危操作会话临时权限单次会话临时禁用指定工具不修改全局配置权限三种行为allow自动执行无需弹窗ask弹出终端确认框用户同意后执行deny直接拒绝返回工具执行失败信息六、子系统模块深度解析6.1 状态管理系统src/state架构自定义Store React Context 混合无第三方状态库轻量化、可序列化持久化AppStateStore全局单例存储保存会话、UI、工具执行全局数据AppState.tsxReact Context Provider向所有UI组件注入状态细粒度拆分SessionState会话状态、ToolState工具运行状态、UiState弹窗/输入状态响应式机制subscribe订阅状态变更自动刷新Ink终端UI6.2 服务层核心子系统src/services/compact 上下文压缩当消息历史Token超限自动精简历史对话保留关键逻辑降低API开销autoDream 记忆整理会话闲置后台异步总结对话长期记忆持久化减少重复上下文占用mcp MCP协议客户端标准化第三方插件接入统一和内置工具调度逻辑lsp 语言服务管理自动启动对应语言LSP获取代码定义、报错、补全信息analytics 埋点系统记录工具调用、模型切换、权限交互企业审计日志6.3 coordinator 多智能体协调coordinatorMode.ts实现Swarm集群智能体主智能体拆分复杂任务分发给子AgentTool子会话各子智能体独立上下文隔离互不干扰任务完成汇总结果合并返回主对话流通过FeatureFlagCOORDINATOR_MODE控制是否启用默认关闭减少token消耗七、两种运行模式对比REPL / Print7.1 核心差异对照表对比项REPL交互式模式claudePrint一次性模式claude -p启动入口launchRepl()runHeadless()UI渲染Ink完整终端交互界面无UI纯标准输出流会话生命周期持续多轮对话历史持久化单次请求执行后销毁会话状态管理React Context AppStateStore仅QueryEngine内部临时状态适用场景本地开发持续对话、调试CI脚本、自动化流水线、批量任务资源占用常驻进程缓存文件/Git上下文一次性进程执行后释放内存7.2 Print模式核心简化逻辑// print.ts runHeadless 简化流程 export async function runHeadless(prompt: string, options: CliOptions) { // 直接创建临时QueryEngine跳过全部UI初始化 const engine new QueryEngine(config) // 单次流式请求收集全部输出 const fullOutput [] for await (const chunk of engine.submitMessage(prompt)) { if (chunk.type text) fullOutput.push(chunk.text) } // 直接打印结果进程退出 console.log(fullOutput.join()) process.exit(0) }八、工程化设计亮点与技术栈总结8.1 核心技术栈运行时Bun编译期Feature Flag、死代码消除UIReact Ink终端组件渲染类型TypeScript5 Zod全量数据校验CLI解析Commander.js状态自研Store无第三方依赖构建Bun Bundle打包代码规范Biome替代Prettier、ESLint自定义规则8.2 可复用设计模式可迁移至自研大模型工具工具注册表模式统一抽象Tool基类自动注册所有工具新增工具无需修改核心调度逻辑权限中间件模式工具执行前置统一校验分层拦截风险操作流式生成器对话AsyncGenerator实现实时输出UI分片渲染等待无卡顿并行预热启动模块加载阶段并行执行IO慢操作大幅降低冷启动耗时功能门控FeatureFlag编译期裁剪未启用功能减少打包体积上下文自动压缩动态Token管理解决大上下文窗口超限问题8.3 架构优势总结分层解耦UI、引擎、工具、服务职责完全隔离单独迭代维护安全完善权限校验、命令沙箱、路径防护、操作审计多层防护扩展性强MCP插件、自定义Slash命令、多智能体集群易于扩展性能优化预连接API、文件缓存、并行初始化、懒加载UI组件企业级适配MDM远程配置、SSO单点、策略限制、审计日志原生支持8.4 开发借鉴建议小型AI编程工具简化七层架构保留「入口初始化-对话引擎-工具系统」三层核心安全优先复刻工具分层权限模型高危操作强制二次确认交互体验参考Ink终端TUI实现流式实时输出提升用户体感轻量化改造移除KAIROS后台、多智能体、MCP等高级Feature降低工程复杂度
