学习路径
不要试图一次看完整仓，先建立“可改动、可排障、可扩展”的心智模型
这条路线假设读者已经是资深工程师。目标不是记住目录，而是在有限时间内得到足够强的结构理解，能够安全进入修改和排障。
本页回答什么问题
- 第一次读这套代码，先看哪里最值钱？
- 什么时候该看启动，什么时候该直接看 query 内核？
- 怎样避免在 REPL 和 utils 海里迷路？
- 每个阶段结束后，自己应该能回答哪些问题？
阶段 1：建立启动与产品轮廓
- 看
src/main.tsx - 看
src/setup.ts - 看
src/entrypoints/init.ts - 补看
src/replLauncher.tsx与src/interactiveHelpers.tsx
阶段目标：你应该能回答程序如何启动、REPL 如何落地、环境准备为什么要独立成层。
阶段 2：吃透共享执行内核
- 看
src/QueryEngine.ts - 看
src/query.ts - 看
src/services/api/claude.ts
阶段目标：你应该能清楚区分 REPL 路径和 headless/SDK 路径，并说清
QueryEngine 与 query() 的职责边界。阶段 3：理解工具、权限与任务如何闭环
- 看
src/tools.ts与src/Tool.ts - 看
src/services/tools/toolOrchestration.ts、StreamingToolExecutor.ts、toolExecution.ts - 看
src/hooks/useCanUseTool.tsx与src/utils/permissions/* - 看
src/Task.ts与一个代表性任务实现，例如LocalShellTask.tsx
阶段目标：你应该能回答一个 tool_use 从模型输出到实际执行、权限审批、结果回写和任务更新的完整路径。
阶段 4：理解 REPL 与运行态集成
- 看
src/screens/REPL.tsx - 看
src/utils/handlePromptSubmit.ts - 看
src/state/AppState.tsx与AppStateStore.ts
阶段目标：你应该能回答 REPL 为什么是复杂度热点，以及
AppState 为什么比普通前端 state 更像运行时容器。阶段 5：理解扩展与多 agent
- 看
src/utils/plugins/pluginLoader.ts与loadPluginCommands.ts - 看
src/services/mcp/config.ts与client.ts - 看
src/skills/loadSkillsDir.ts - 看
src/tools/AgentTool/runAgent.ts
阶段目标：你应该能解释插件、MCP、skills 为什么必须区分，以及子 agent 为什么像“带资源边界的子运行时”。