本章总览

「流程」章节把分散在各文件的逻辑串成故事：从开机到第一次 tool call，从权限弹窗到上下文压缩。适合第二遍复习时用。

总览图

渲染图表中…

学完本章你应该能

  • 能口述启动流程 5 步
  • 能画出 Agent 主循环与压缩触发点
  • 理解工具执行与权限检查的先后顺序

核心概念（先读懂这些）

流程图 vs 架构图

架构图看静态边界；流程图看时间顺序。读源码时建议：先 ARCH 后 FLOW，先知道「有哪些角色」再知道「谁先谁后」。

压缩是流程中的分支

不是独立功能，而是主循环在 token 超预算时的自救路径。CompactBoundaryMessage 是流程中的「章节分隔符」。

建议学习步骤

  1. 按启动→循环→工具→压缩顺序各读一段
  2. 对照 permissions 流程图
  3. 在终端跑一次 /compact 观察行为

应用启动流程（时序图）

渲染图表中…

Agent 主循环（活动图）

渲染图表中…

工具执行流水线

渲染图表中…

上下文压缩流程

渲染图表中…

权限检查流程

渲染图表中…

MCP 工具发现

渲染图表中…

会话恢复 /resume

渲染图表中…

启动流程（文字版）

用户执行 claude
    │
    ├─ cli.tsx: --version? → 直接打印版本退出
    │
    ├─ init.ts: 配置/遥测/GrowthBook 初始化
    │
    ├─ main.tsx: Commander 解析参数
    │   ├─ OAuth 认证检查
    │   ├─ MCP 服务器预连接
    │   ├─ 插件/Skills 加载
    │   └─ 工具/命令注册
    │
    ├─ 模式分支
    │   ├─ 交互式 → launchRepl() → REPL.tsx
    │   ├─ --print/-p → QueryEngine (headless)
    │   └─ SDK → QueryEngine API
    │
    └─ 等待用户输入

Agent 主循环（文字版）

query.ts while(true): compact 准备 → API streaming → needsFollowUp? → tools/next_turn 或 stop hooks/Terminal

工具执行（文字版）

StreamingToolExecutor 收到 tool_use block
    │
    ├─ findToolByName(tools, name)
    │
    ├─ isConcurrencySafe?
    │   ├─ 是 → 与同类并行执行
    │   └─ 否 → 等待队列清空后独占执行
    │
    ├─ canUseTool(tool, input)
    │   ├─ bypass → 直接执行
    │   ├─ plan mode → 仅允许只读工具
    │   └─ default → 弹窗 / yolo classifier
    │
    ├─ runToolUse(tool, input, context)
    │   ├─ Progress messages 流式 yield
    │   └─ 返回 tool_result
    │
    └─ applyToolResultBudget() 截断过大结果

上下文压缩（文字版）

tokenCount(messages) > threshold
    │
    ├─ compactConversation()
    │   ├─ 选取待压缩消息范围
    │   ├─ 调用 Claude 生成摘要
    │   └─ 替换为 CompactBoundaryMessage + 摘要
    │
    ├─ runPostCompactCleanup()
    │   └─ 清理 file state / memory refs
    │
    └─ 继续 query 循环 (messages 已缩短)

权限检查（文字版）

canUseTool(tool, input)
    ├─ permissionMode == bypassPermissions? → allow
    ├─ permissionMode == plan? → 仅只读工具 allow
    ├─ getDenyRuleForTool() 匹配? → deny
    ├─ yolo classifier (AI 判断)? → allow/deny
    └─ 弹窗 PermissionRequest → 用户决定

MCP 工具发现

启动时 prefetchAllMcpResources()
    ├─ 读取 .mcp.json / settings
    ├─ 连接 stdio/SSE/HTTP 服务器
    ├─ listTools() + listResources()
    └─ 合并到 getTools() 返回的工具池

会话恢复 /resume

用户 /resume
    ├─ sessionStorage.load(sessionId)
    ├─ 恢复 messages[] + compact boundaries
    ├─ 恢复 FileStateCache
    └─ 继续 REPL 循环

本章小结与延伸

把流程记成故事，读代码时就不会迷失在文件海洋里。 继续学习：