Claude Code JSONL 的使用小结

~/.claude/projects/<project-dir-hash>/<sessionId>.jsonl

用户输入 prompt 并回车
  │
  ▼
handlePromptSubmit()                  src/utils/handlePromptSubmit.ts:120
  │
  ▼
executeUserInput()                     src/utils/handlePromptSubmit.ts:396
  │
  ▼
processUserInput()                     src/utils/processUserInput/processUserInput.ts:85
  ├─ 斜杠命令 → processSlashCommand()
  ├─ Bash 模式 → processBashCommand()
  └─ 普通文本 → processTextPrompt() → createUserMessage()
  │
  ▼
onQuery()                              REPL.tsx 中定义
  │
  ▼
query() 生成器循环                     src/query.ts:219
  ├─ API 调用（通过 copilot-api 代理）
  ├─ 流式接收 text / thinking / tool_use
  ├─ 执行工具 → 发回结果
  └─ Turn 完成
  │
  ▼
setMessages(updatedMessages)           React state 更新
  │
  ▼
React 重新渲染 REPL
  │
  ▼
useLogMessages() useEffect 触发       src/hooks/useLogMessages.ts:19  ← ★ 关键触发点
  │
  ▼
recordTranscript(newMessages)          src/utils/sessionStorage.ts:1408
  ├─ 1. 去重：跳过已在 messageSet 中的 UUID
  ├─ 2. 清洗：cleanMessagesForLogging() 剥离仅 UI 的数据
  │
  ▼
Project.insertMessageChain()           src/utils/sessionStorage.ts:993
  ├─ 3. 首次 user/assistant 消息 → materializeSessionFile()
  │     创建 JSONL 文件，刷新缓冲的前导条目
  ├─ 4. 每条消息：加盖元数据戳（sessionId, cwd, version, gitBranch）
  │
  ▼
Project.appendEntry()                  src/utils/sessionStorage.ts:1128
  ├─ 5. 去重：UUID 已存在则跳过
  ├─ 6. 远程持久化：persistToRemote()（如果启用）
  │
  ▼
Project.enqueueWrite()                 src/utils/sessionStorage.ts:606
  ├─ 7. 推入内存写队列（最多缓冲 50 条或 1 秒后刷新）
  │
  ▼
drainWriteQueue() → appendToFile()    src/utils/sessionStorage.ts:645
  │
  ▼
appendEntryToFile()                    src/utils/sessionStorage.ts:2572
  └─ 8. fs.appendFileSync(path, jsonLine + '\n')  ← 实际磁盘写入

enqueueWrite()          ← 立即返回 Promise（不阻塞 UI）
  │
  ▼
scheduleDrain()         ← 调度微任务（合并多次快速写入为一次刷新）
  │
  ▼
drainWriteQueue()       ← 条目批量打包成块（MAX_CHUNK_BYTES）
  │                       每个块 = 一次 fs.appendFileSync 调用
  ▼
appendToFile()          ← 实际的同步磁盘 I/O（在微任务上运行，不阻塞渲染帧）

<sessionId>/agents/<agentId>.jsonl

// src/utils/sessionStorage.ts:1224-1228
const isAgentSidechain = entry.isSidechain && entry.agentId !== undefined
const targetFile = isAgentSidechain
  ? getAgentTranscriptPath(asAgentId(entry.agentId!))
  : sessionFile

export type Entry =
  | TranscriptMessage        // 4 种子类型：user, assistant, attachment, system
  | SummaryMessage            // type: 'summary'
  | CustomTitleMessage        // type: 'custom-title'
  | AiTitleMessage            // type: 'ai-title'
  | LastPromptMessage         // type: 'last-prompt'
  | TaskSummaryMessage        // type: 'task-summary'
  | TagMessage                // type: 'tag'
  | AgentNameMessage          // type: 'agent-name'
  | AgentColorMessage         // type: 'agent-color'
  | AgentSettingMessage       // type: 'agent-setting'
  | PRLinkMessage             // type: 'pr-link'
  | FileHistorySnapshotMessage    // type: 'file-history-snapshot'
  | AttributionSnapshotMessage    // type: 'attribution-snapshot'
  | QueueOperationMessage     // type: 'queue-operation'
  | SpeculationAcceptMessage      // type: 'speculation-accept'
  | ModeEntry                 // type: 'mode'
  | WorktreeStateEntry        // type: 'worktree-state'
  | ContentReplacementEntry   // type: 'content-replacement'
  | ContextCollapseCommitEntry     // type: 'marble-origami-commit'
  | ContextCollapseSnapshotEntry   // type: 'marble-origami-snapshot'

{
  "type": "user",
  "parentUuid": "...",
  "uuid": "750ccbae-...",
  "message": {
    "role": "user",
    "content": "explain the architecture..."
  },
  "permissionMode": "default",
  "origin": { "kind": "human" },
  "promptSource": "typed",
  "userType": "external",
  "entrypoint": "cli",
  "cwd": "/Users/zhanghongkui/Documents/cc-haha-main",
  "sessionId": "964aa807-...",
  "version": "2.1.183",
  "gitBranch": "HEAD"
}

{
  "type": "assistant",
  "parentUuid": "750ccbae-...",
  "uuid": "b917be23-...",
  "message": {
    "role": "assistant",
    "content": [
      { "type": "text", "text": "Let me explore the codebase..." },
      { "type": "tool_use", "id": "toolu_...", "name": "codegraph_explore", "input": {...} }
    ],
    "usage": { "input_tokens": 50000, "output_tokens": 1200 },
    "stop_reason": "tool_use",
    "model": "deepseek-v4-pro"
  }
}

{
  "type": "system",
  "parentUuid": "...",
  "message": {
    "role": "user",
    "content": "<system-reminder>Content was truncated to fit context limit...</system-reminder>"
  }
}

{
  "type": "attachment",
  "parentUuid": "750ccbae-...",
  "attachment": {
    "type": "agent_listing_delta",
    "addedTypes": ["claude", "Explore", "Plan", "general-purpose", ...],
    "addedLines": ["- claude: Catch-all for any task...", ...],
    "isInitial": true,
    "showConcurrencyNote": true
  }
}

{
  "type": "ai-title",
  "sessionId": "964aa807-...",
  "aiTitle": "Understanding Claude Code Architecture"
}

{
  "type": "custom-title",
  "sessionId": "964aa807-...",
  "customTitle": "My Architecture Study"
}

{
  "type": "last-prompt",
  "sessionId": "964aa807-...",
  "lastPrompt": "explain the architecture of this project"
}

{
  "type": "mode",
  "sessionId": "964aa807-...",
  "mode": "normal"
}

{
  "type": "permission-mode",
  "sessionId": "964aa807-...",
  "permissionMode": "default"
}

{
  "type": "file-history-snapshot",
  "messageId": "750ccbae-...",
  "snapshot": {
    "messageId": "...",
    "trackedFileBackups": {},
    "timestamp": "2026-06-19T04:21:13.170Z"
  },
  "isSnapshotUpdate": false
}

{
  "type": "worktree-state",
  "sessionId": "...",
  "worktreeSession": {
    "originalCwd": "...",
    "worktreePath": "...",
    "worktreeName": "...",
    "worktreeBranch": "...",
    "sessionId": "..."
  }
}

类型                    出现次数    说明
─────────────────────────────────────────────────────
assistant               64       AI 的每次响应（含工具调用的中间步骤）
user                    35       你的每次输入
permission-mode         15       权限模式（随消息序列化写入）
mode                    15       会话模式（随元数据刷新重复写入）
ai-title                15       AI 生成的标题（每次元数据刷新重写）
last-prompt             14       最近一次 prompt（每次元数据刷新重写）
system                   7       系统注入提醒
file-history-snapshot    7       每个 turn 结束的文件快照
attachment               6       工具/Agent/MCP 列表通告

user (uuid: A, parentUuid: null)
  ↑
assistant (uuid: B, parentUuid: A)
  ↑
assistant (uuid: C, parentUuid: B)    ← tool_use 响应
  ↑
user (uuid: D, parentUuid: C)         ← tool_result
  ↑
assistant (uuid: E, parentUuid: D)    ← 继续
  ↑
...

// src/utils/sessionStorage.ts:1242-1243
const isNewUuid = !messageSet.has(entry.uuid)
if (isAgentSidechain || isNewUuid) {
  void this.enqueueWrite(targetFile, entry)
  if (!isAgentSidechain) {
    messageSet.add(entry.uuid)
  }
}

┌──────────────────────────────────────────────────────┐
│  高频写入（每条消息都写）                              │
│  ├─ user / assistant / system / attachment           │
│  ├─ permission-mode（随消息序列化）                    │
│  └─ file-history-snapshot（每个 turn 结束）            │
│                                                      │
│  中频写入（每个 turn / compact 时写）                  │
│  ├─ last-prompt（覆盖写入）                            │
│  └─ mode（切换时写）                                   │
│                                                      │
│  低频写入（用户主动操作时写）                           │
│  ├─ custom-title, tag（/rename, /tag）                │
│  ├─ agent-name, agent-color, agent-setting            │
│  ├─ summary（compact 时）                              │
│  ├─ pr-link（关联 PR 时）                              │
│  └─ worktree-state（进入/退出 worktree 时）            │
│                                                      │
│  仅在 ant 内网（USER_TYPE === 'ant'）                   │
│  ├─ task-summary（后台 fork 生成）                     │
│  ├─ queue-operation（命令队列变更）                     │
│  ├─ speculation-accept（推测加速追踪）                  │
│  ├─ content-replacement（内容替换持久化）               │
│  ├─ attribution-snapshot（代码归属追踪）                │
│  └─ marble-origami-commit / snapshot（上下文折叠）     │
└──────────────────────────────────────────────────────┘