~/.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() 生成器循環(huán)                     src/query.ts:219
  ├─ API 調(diào)用（通過 copilot-api 代理）
  ├─ 流式接收 text / thinking / tool_use
  ├─ 執(zhí)行工具 → 發(fā)回結(jié)果
  └─ Turn 完成
  │
  ▼
setMessages(updatedMessages)           React state 更新
  │
  ▼
React 重新渲染 REPL
  │
  ▼
useLogMessages() useEffect 觸發(fā)       src/hooks/useLogMessages.ts:19  ← ★ 關(guān)鍵觸發(fā)點
  │
  ▼
recordTranscript(newMessages)          src/utils/sessionStorage.ts:1408
  ├─ 1. 去重：跳過已在 messageSet 中的 UUID
  ├─ 2. 清洗：cleanMessagesForLogging() 剝離僅 UI 的數(shù)據(jù)
  │
  ▼
Project.insertMessageChain()           src/utils/sessionStorage.ts:993
  ├─ 3. 首次 user/assistant 消息 → materializeSessionFile()
  │     創(chuàng)建 JSONL 文件，刷新緩沖的前導(dǎo)條目
  ├─ 4. 每條消息：加蓋元數(shù)據(jù)戳（sessionId, cwd, version, gitBranch）
  │
  ▼
Project.appendEntry()                  src/utils/sessionStorage.ts:1128
  ├─ 5. 去重：UUID 已存在則跳過
  ├─ 6. 遠(yuǎn)程持久化：persistToRemote()（如果啟用）
  │
  ▼
Project.enqueueWrite()                 src/utils/sessionStorage.ts:606
  ├─ 7. 推入內(nèi)存寫隊列（最多緩沖 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()         ← 調(diào)度微任務(wù)（合并多次快速寫入為一次刷新）
  │
  ▼
drainWriteQueue()       ← 條目批量打包成塊（MAX_CHUNK_BYTES）
  │                       每個塊 = 一次 fs.appendFileSync 調(diào)用
  ▼
appendToFile()          ← 實際的同步磁盤 I/O（在微任務(wù)上運行，不阻塞渲染幀）

<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": "..."
  }
}

類型                    出現(xiàn)次數(shù)    說明
─────────────────────────────────────────────────────
assistant               64       AI 的每次響應(yīng)（含工具調(diào)用的中間步驟）
user                    35       你的每次輸入
permission-mode         15       權(quán)限模式（隨消息序列化寫入）
mode                    15       會話模式（隨元數(shù)據(jù)刷新重復(fù)寫入）
ai-title                15       AI 生成的標(biāo)題（每次元數(shù)據(jù)刷新重寫）
last-prompt             14       最近一次 prompt（每次元數(shù)據(jù)刷新重寫）
system                   7       系統(tǒng)注入提醒
file-history-snapshot    7       每個 turn 結(jié)束的文件快照
attachment               6       工具/Agent/MCP 列表通告

user (uuid: A, parentUuid: null)
  ↑
assistant (uuid: B, parentUuid: A)
  ↑
assistant (uuid: C, parentUuid: B)    ← tool_use 響應(yīng)
  ↑
user (uuid: D, parentUuid: C)         ← tool_result
  ↑
assistant (uuid: E, parentUuid: D)    ← 繼續(xù)
  ↑
...

// 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 結(jié)束）            │
│                                                      │
│  中頻寫入（每個 turn / compact 時寫）                  │
│  ├─ last-prompt（覆蓋寫入）                            │
│  └─ mode（切換時寫）                                   │
│                                                      │
│  低頻寫入（用戶主動操作時寫）                           │
│  ├─ custom-title, tag（/rename, /tag）                │
│  ├─ agent-name, agent-color, agent-setting            │
│  ├─ summary（compact 時）                              │
│  ├─ pr-link（關(guān)聯(lián) PR 時）                              │
│  └─ worktree-state（進(jìn)入/退出 worktree 時）            │
│                                                      │
│  僅在 ant 內(nèi)網(wǎng)（USER_TYPE === 'ant'）                   │
│  ├─ task-summary（后臺 fork 生成）                     │
│  ├─ queue-operation（命令隊列變更）                     │
│  ├─ speculation-accept（推測加速追蹤）                  │
│  ├─ content-replacement（內(nèi)容替換持久化）               │
│  ├─ attribution-snapshot（代碼歸屬追蹤）                │
│  └─ marble-origami-commit / snapshot（上下文折疊）     │
└──────────────────────────────────────────────────────┘