会话与消息流

这一篇讲的是「一轮对话是怎么跑起来的」——你按下发送之后，消息去了哪里、为什么有时候会排队、 队列为什么会停下来、目标模式和计划模式各自卡在什么地方等你确认。 这里覆盖三条主线：消息流（发送 → 排队 → 调度 → 落库）、目标与计划（验收契约门控、计划审批）、 以及会话级操作（分叉、参考会话、还原点、历史导入）。

所有字段名、枚举值、界面文案与默认值都来自应用仓库的真实代码，不写代码里不存在的东西。 凡是代码本身就自相矛盾或者存在明显缺口的地方，本文会直接点出来，并在18. 排查表里给出判断方法。

1. 会话的三层模型

先把名词对齐。Spark 的对话不是「一个会话 = 一串消息」，而是三层：会话 → 轮次 → 事件。很多看起来奇怪的行为，根源都在这层结构上。

为什么要注意这层结构：因为几乎所有「消息级」操作实际作用在轮次上， 而不是单条消息上。比如删除一条助手消息，数据库会把同一轮的user_message + assistant_message 一起删掉（见13. 删除消息）。

1.1 turnId 是这一整套功能的通用语言

turnId 同时出现在这些地方，理解了它就理解了这一篇的大半：

• 队列里每一项的标识（SessionQueuedTurn.turnId）；
• 分叉的锚点（anchorTurnId，见 14. 会话分叉）；
• 编辑最后一轮的入参（session:rewind-last-turn）；
• 删除消息时用来反查整个轮次；
• 错误暂停状态里指向「是哪一轮失败」（failedTurnId）。

2. 发一条消息会发生什么

按下发送后，渲染进程调用的是 session:submit-turn。 主进程把它交给 SessionService.dispatchTurn()，然后分三种走向。

2.1 两个发送通道，持久性不同

这个差异有实际后果。只有走 submit-turn 的轮次会写进turn_requests；应用重启后，恢复逻辑只能找回status = 'accepted' 的行。也就是说：IM 消息或定时任务如果恰好排在队列里， 重启后会被静默丢弃——没有事件、没有报错、界面上也看不到痕迹。

2.2 started 不等于「已经在跑」

SessionSendTurnResponse 的注释写的是「Turn 是否立即开始执行（false 表示排队中）」， 但代码实际语义更松：持久化路径下，会话空闲时 dispatchTurn 会先把轮次入队，用 setTimeout 调度，然后立刻返回started: true。所以 started: true 的真实含义是 「已受理并即将开跑」，不是「执行器已经在运行」。

真正判断「在不在跑」要看 session:get-queue 返回的running，或者会话状态 running。

2.3 排队时，你的消息气泡会消失

这是第一次遇到时最容易困惑的地方：发送时消息会立刻以半透明的「乐观气泡」出现， 但如果轮次判定为排队（started: false），这个气泡会被移除。

• commitOptimisticUserMessage(..., started=false) 直接把气泡过滤掉；
• 队列快照里出现的 turnId 也会让乐观气泡被剥掉；
• 消息此时只存在于队列面板里，等轮次真正开跑、写入user_message 事件后，才作为正式消息回到对话流。

所以「我发的消息不见了」通常不是丢了，而是去看队列面板（见下一节）。

3. 排队：两层结构

队列不是一个对象，而是两层——一层在内存里，一层在数据库里。两者覆盖范围不同， 这是理解后面所有队列行为的关键。

3.1 持久行的完整字段

turn_requests (
id             TEXT PRIMARY KEY,   -- 就是 turnId
session_id     TEXT NOT NULL,      -- FK -> sessions(id) ON DELETE CASCADE
payload_json   TEXT NOT NULL,      -- JSON.stringify(PendingTurn)
status         TEXT NOT NULL DEFAULT 'accepted',
error_message  TEXT,
created_at     TEXT NOT NULL,
updated_at     TEXT NOT NULL
)

status 枚举：accepted / running / completed / failed / cancelled。 轮次进入终态时 payload_json 会被清空成 ''， 所以事后无法从这张表回读出当时的消息原文。

4. 队列面板能做什么

队列面板出现在输入框上方。默认可折叠，折叠按钮文案是显示队列 / 隐藏队列，带当前条数。 并且只在瞬间上有两条以上排队项时才显示头部的拖拽提示与「清空队列」按钮。

4.1 单项操作

每一项右侧还会显示该排队轮次起跑时将使用的模型（模型：X 或Provider：X · 模型：Y）。这个快照是在入队时冻结的。

4.2 批量操作

• 头部提示 拖动调整执行顺序；
• 清空队列（执行中显示 清空中…）， 提示为 取消全部排队消息，不影响当前正在执行的任务—— 这句话是准确的：清空只动队列数组，不碰正在运行的执行器。

4.3 拖拽排序在重启后会丢失

这是本篇最需要记住的队列行为之一。reorderQueuedTurns 只重排内存里的 pendingTurns 数组并广播，不写数据库，也不更新 updated_at。 而重启恢复是按 created_at ASC, id ASC 重新入队的。

结论：你把第 3 项拖到第 1 项，在应用本次运行期间有效； 重启应用后顺序会回到按入队时间排列。

4.4 「编辑」排队项后模型可能变

排队项在入队时冻结了一份运行配置快照。但「编辑」是把内容取回输入框、 取消原项、由你重新发送——新轮次用的是输入框当前的 Provider / 模型， 不是原来那一项的快照。如果中间换过模型，重新发送时会用新模型。

5. 队列出错暂停与恢复

5.1 什么会暂停队列

只有一个触发条件：出现 status: 'error' 的 agent_status 事件，且此时内存队列非空。

暂停状态的结构是：

SessionQueuePauseState {
reason: 'turn_error'      // 目前是单值字面量
failedTurnId?: string
errorMessage?: string
pausedAt: string
}

5.2 暂停时你会看到什么

队列面板顶部出现一条横幅：当前回复出错，队列已暂停（内容未丢失）。后面有两个按钮：

如果失败的那条消息无法安全还原（内部隐藏轮次、远程消息、或原文已取不到），重试 会被禁用，提示变成 失败消息无法安全还原， 此时只能选「跳过继续」或手动重发。

5.3 发送一条新消息也会解除暂停

协议注释里写的是「普通发送路径不受影响」，但代码实际上是这样的： 只要发出的是可见的用户轮次，就判定为「队列已恢复」， 然后解除暂停、把会话状态改回 idle。resumePausedQueue 这个标志控制的是排在队首还是队尾， 不是「是否解除暂停」。

所以横幅挂着的时候直接输入新消息并发送，也会让队列继续跑——新消息排在队尾。 顺序是安全的：重快照和持久化写入都发生在解除暂停之前。

5.4 重启后的恢复

应用启动时会跑一遍恢复，顺序是：

1. status = 'running' 的行统一标记为失败，错误信息Turn interrupted by application restart，不重新排队；
2. status = 'accepted' 的行解析回 PendingTurn 重新入队，enqueuedAt 取 created_at；
3. 对会话状态为 error 的会话，读最近 32 条 agent_status 事件， 回溯出暂停原因并重建暂停态；
4. 然后调度下一轮。

暂停在重启后的权威来源是会话状态（sessions.status = 'error'）， 而不只是内存里的闸门对象。

6. 调度与并发

全局并发 6 没有任何设置项或 IPC 可以调——它是个常量。 如果第六个会话在跑、第七个会话的消息进来了，它就会排队等待。

另外，队列没有深度上限：pendingTurns 和turn_requests 都不限条数。

顺带区分一个容易混淆的名字：skipIfSessionRunning 是定时任务的开关，不是队列开关。它默认开启，判断「忙不忙」时会把 排队中的轮次也算作忙。

7. 目标模式（Goal）与验收契约

目标模式让会话持续围绕一个目标自我迭代，而不是一轮一问一答。 它的核心设计是先定验收标准再开工——没有明确验收标准就不允许开始执行。

7.1 /goal 命令族

目标存在 session_goals 表里，状态枚举共 7 个：active / paused / completed / failed / cleared / stopped_by_budget / pending_contract。其中前四个是「当前目标」的判定集合。

7.2 验收契约门控

触发条件是唯一的：运行模式为 spark-loop（默认）且没有显式提供 successCriteria。

因为 /goal 命令只能传「目标描述 + 附件」，传不了验收标准， 所以从界面创建的目标都会走契约门控。流程是：

1. 目标状态置为 pending_contract；
2. 发出一条 goal_contract_drafting 事件；
3. 跑一次隐藏轮次起草契约（该轮次在对话流里显示为目标模式：生成验收标准）；
4. 起草提示词明确要求「先不要动手实现」，并必须以一个机器可读代码块结尾。

契约块的格式是固定的三行：

```spark-goal-contract
success_criteria: <逗号分隔的可验收条件>
constraints: <逗号分隔的约束，可为空>
validation: <逗号分隔的验证命令，可为空>
```

解析规则（这些细节决定了契约能不能被识别）：

• 正则不区分大小写、非贪婪——第一个结束围栏就收尾；
• 键名大小写不敏感并去空格；success_criteria 也接受successcriteria 这种连写；
• 值是逗号切分、去空格、去空项；
• 每行以第一个冒号切分键值，所以行首的 - 项目符号会 让这一行被静默忽略；
• 没有 success_criteria 或它为空 → 整个契约解析失败。 失败后目标停留在 pending_contract，goal_contract_proposed 事件也不会发出。

另外，validation.checklist 这个字段虽然类型和卡片里都有， 但没有任何代码会写入它——契约解析器只产出 commands。 所以契约卡片上的「检查清单」区块实际上不会出现。

7.3 契约卡片

契约起草完成后，对话流里出现一张内联卡片，标题是目标验收契约，右上角徽标三态：待确认 / 已确认 / 已拒绝。

卡片按字段展示：目标、验收标准、约束、验证命令、检查清单（后者不会出现，见上）。

如果点确认时契约缺验收标准，会提示契约缺少验收标准或已失效，未能启动目标。，目标继续停在 pending_contract。

会话的 Git 面板里也有一份目标区块，按钮文案不同： 待确认时是 确认契约 / 拒绝， 之后是 暂停、恢复（或预算停止后显示 继续）、完成、清除。

7.4 spark-goal-status 块

目标进入执行循环后，每一轮迭代的提示词都要求模型以这样一个块结尾：

```spark-goal-status
status: continue|completed|blocked|failed
phase: review|act|validate
summary: <一句话>
evidence: <逗号分隔的证据>
next_step: <下一步或留空>
```

status 只接受这四个值——写成别的（或漏写）会导致整块被丢弃， 本轮什么记录都不会产生。

phase 写错不会导致整块失败——会被静默强制成 validate。界面上的阶段文案是复盘 / 执行 / 验证。

这个块只在轮次正常完成（completed）时才会被解析； 轮次以 error 或 cancelled 结束时不会走这段后处理。

7.5 目标与队列的关系

目标激活（active 且 spark-loop）时，用户消息会排队， 不会插进迭代中间。下一个迭代开始时，队列里的消息会被「排空」并注入到迭代提示词里， 标注为「上一轮迭代以来收到的补充指令（当作目标更新，不是重置）」。

能被注入的只有纯文本用户轮次，以下情况会留在队列里等正常执行：

• 命令轮次（/ 开头的命令）；
• 隐藏轮次（内部自动执行的）；
• 带附件的、带 Skill 的、带参考会话的、带 @ 指定 Agent 的；
• 运行时配置（Agent / 适配器 / 权限模式 / 推理强度等）与基线不一致的。

每次迭代最多注入 8 条消息，每条截断到 2000 字符。

另外，只要存在「当前目标」，就不能修改会话的工作流绑定， 提示是当前目标仍在进行中，暂时不能修改工作流。注意 pending_contract 也算「当前目标」——契约没确认前同样改不了工作流。

8. 目标的预算与熔断

默认预算是 { maxConsecutiveFailures: 3, noProgressLimit: 3 }，不设轮次上限、不设运行时长上限、不设费用上限—— 设计取向是让模型自驱跑到完成，只保留两个「卡死」熔断。

命中任何一个后，目标置为 stopped_by_budget 并发goal_budget_stopped 事件，之后不会自动继续—— 需要你手动恢复，恢复后开始一个新的预算周期。

另外提醒：codex-native 模式与自定义预算从界面走不到。 只有 session:set-goal 这个 IPC 能传 mode / budget / constraints，而渲染进程没有任何地方调用它。 实际用起来，所有目标都是 spark-loop + 上面的默认预算。

9. 计划模式审批

在 claude-plan 模式下，Agent 不会直接动手：它先调研、产出一份实施计划、 提交，然后立即停止等你审批。

9.1 事件

• plan_proposed：携带 Markdown 格式的计划文本。当前轮次就此结束（状态 completed），不会再调用工具。
• plan_rejected：拒绝是一个「已决议」标记，会写入事件流。 历史回放（切换会话、重开会话）时据此清掉待审批状态，避免已拒绝的计划重新弹出审批面板。

计划文本的来源有两处：优先取工具入参里的 plan 字段； 新版 CLI 是把计划写到 .claude/plans/*.md 文件，这时会回退到 本轮的计划文件内容。完全相同的重复提交会被折叠。

9.2 审批面板

批准成功的提示是计划已批准，已切换为自动执行模式； 拒绝的提示是已拒绝计划，未执行。

9.3 审批闸门会阻塞队列

存在待审批计划时，会话被加入一个「等待计划审批」集合，队列不会自动推进。这个闸门在三个地方被检查： 队列调度、全局调度、以及轮次结束后的续跑判断。

闸门的解除方式有两条，任选其一即可：

• 调用 session:reject-plan 拒绝计划；
• 直接切换权限模式——代码把「切换 permissionMode」视为用户已做出选择， 会顺带解除闸门并推进队列。

这是个很实用的逃生口：如果计划面板因为某种原因点不动了， 在输入框切一下权限模式，被卡住的队列就会继续跑。

注意拒绝后不需要你补发一条消息——闸门解除时就会去调度队列。

10. 消息级操作

把鼠标悬停到任意一条消息上，会出现一条操作栏。操作栏在鼠标移入前opacity: 0 且 pointer-events: none， 用户消息靠右、助手消息靠左。进入多选模式时整条栏会被隐藏。

10.1 悬停操作栏

按钮的渲染顺序是固定的，但是否出现取决于消息角色：

助手消息没有「编辑」和「重发」，这是设计如此—— 你只能编辑自己发出去的内容。

值得强调：「重发」和「重试」都不会自动重跑。 悬停栏的重发、发送失败气泡上的重试、错误卡片上的重新尝试， 走的都是同一条路径：把内容塞回输入框并聚焦，等你按发送。 失败的那一轮仍然留在历史里。

另外，没有「重新生成」这个功能——应用里不存在这个动作。

10.2 右键菜单

右键消息弹出的菜单结构是固定的，用户消息和助手消息使用同一套构建逻辑：

菜单项点击后立即执行并关闭菜单，没有二级确认。 另外在消息气泡之外的普通文本选区上右键，会多出一个引用对话，用于把选中的文字带进下一轮。

10.3 多选

从右键菜单进入多选后，出现一条工具栏：

• 左侧计数：已选 N 条；
• 全选 —— 注意它故意排除仍在流式输出的消息；
• 全不选；
• 复制（成功后变 已复制）——批量复制格式是发言对象：正文，条目之间空行分隔；
• 删除（危险样式）；
• 取消。

10.4 乐观气泡与发送失败

发送时先插入一个乐观气泡再发请求，这样界面不会卡顿。 它的状态机是：

发送失败时输入框里的草稿会恢复，所以内容不会丢。

11. 内部轮次的可见性

定时任务、目标迭代、命令续跑这些系统自动发起的轮次也会进对话流， 但它们的输入提示词通常不应该给你看。处理规则是「投影式脱敏」： 只在渲染时替换，不改动原始数据。

具体投影规则：

• 如果轮次提供了安全的展示文本（userMessageDisplayContent）， 原始内容块会被替换成这段文本；
• 如果标记为隐藏且没有安全展示文本，这条用户消息从对话流里整条消失（助手回复仍然保留）；
• 提示词检查器里，取不到安全文本时统一显示内部提示已隐藏；
• 历史上 Telegram 远程连接的固定提示词前缀会被专门脱敏。

12. 编辑最后一轮消息

只能编辑最后一轮。这不是限制没做完，而是刻意的设计： 编辑采用的是「前缀回退并删除被替换轮」的做法，如果允许编辑历史中间某一轮， 就必须处理「后面那些轮怎么办」——当前实现选择直接拒绝。

行内编辑器的键盘约定：Enter 提交、Shift+Enter 换行、Esc 取消；按钮是 取消 / 发送（提交中显示 发送中…）。

12.1 点发送之后到底发生了什么

调用 session:rewind-last-turn，它会先删后发：

1. 删除该轮全部 agent_events；
2. 删除该轮的 turn_requests 记录；
3. 删除该轮的 turn_perf_metrics；
4. 轮转 Codex 原生线程代号、清空 Spark 账本绑定；
5. 删除该会话的全部摘要；
6. 会话状态置回 idle 并清掉「上次运行结果」；
7. 最后才用新文本发出新轮次。

渲染进程会收到一条 transcript_retraction 事件，据此把这一轮从本地列表里摘掉。

12.2 会被拒绝的情况

一个体验上的坑：界面判断「忙不忙」时不看队列， 所以队列里有活时编辑按钮照样显示。 你要等到敲完新文本按发送，才会收到会话仍有待处理消息，请先处理或清空队列 的报错（草稿会保留）。

13. 删除消息

删除是硬删除——直接 DELETE FROM agent_events， 没有软删标记、没有回收站、没有撤销。

13.1 删一条消息会连带整轮

如果你删的是 user_message 或 assistant_message， 系统会把同一轮的所有消息事件一起删掉，避免留下半截轮次。 纯工具事件（tool_call / tool_result / file_change） 可以单独删，因为它们不影响轮次边界。

13.2 删除是「浅」的，编辑是「深」的

两者对连续性数据的处理完全不同：

编辑路径的代码注释里写得很清楚：只删事件是不够的，否则下一轮会继续 resume 到 包含旧轮次的上游上下文。这个论断同样适用于删除路径——但删除路径没有做这些清理。

实践建议：如果你希望「这条消息及其上下文影响一起消失」， 用编辑而不是删除。删除更适合清掉一段不该留在记录里的内容。

14. 会话分叉与血缘

分叉会创建一个独立的会话副本，把源会话到某个锚点为止的已完成历史 物化复制过去。两个会话之后各自独立演进。

14.1 两个入口

对话框标题是从此处分支，正文说明 「创建一个独立会话副本 …… 将复制《某会话》从开始到第 N 轮的已完成历史」， 底部提示「新会话会继承当前会话的工作区和运行配置，但不会继续源会话正在执行的任务」， 确认按钮是复制会话。

新会话标题默认是 源标题 · 分支，最多 200 字符。

14.2 锚点是「轮次」，不是「消息」

虽然按钮叫「从此处分支」并挂在某条消息上，实际传的是该消息所属的 turnId。这带来两条重要规则：

• 不指定锚点时，取最后一个已完成轮次；
• 指定的轮次如果没有「完成」（仍在运行，或根本不存在），会直接报错只能从已完成的会话轮次处分支；当前轮次仍在运行或不存在。

什么叫「已完成轮次」有严格定义：必须有终态 agent_status（idle / completed / cancelled / error）、 必须有用户消息、且该用户消息不是隐藏轮次。 所以目标迭代、定时任务这类内部轮次永远不会成为分叉锚点。

一个反直觉的行为：源会话正在运行时也能分叉，但此时副本是空的——因为没有任何已完成的轮次，fork_cutoff_seq 为 0。 界面会提示源会话仍在运行；副本只复制到最近一个已完成轮次。

14.3 复制了什么、没复制什么

复制的：

• 会话行上的：kind、project_id、工作区、 规则包、权限配置，以及整套运行配置（Provider、模型、Agent 适配器、Agent、权限模式、聊天模式、推理强度）；
• 事件白名单：用户/助手/团队成员/子代理消息、工具调用与结果、终态状态事件、 文件变更、终端输出、产物文件、计划提案与拒绝、错误、运行时信号、重试轨迹；
• 附件——附件是内嵌在用户消息事件里的，所以跟着一起过去，且指向同一批磁盘文件；
• 工作流绑定（会生成新的绑定实例标识，但不复制历史运行记录）。

不复制的：

事件复制时会重新编号：新事件 ID、seq 从 0 重排、sdkSessionId 被删除；但源会话的 run_id 与 turn_id 会保留，便于追溯。

记忆不需要复制——记忆是按 user/project/agent 作用域存的， 不是按会话，两个会话看到的是同一份。

14.4 元数据会被整体继承（一个真实的坑）

分叉时 metadata_json 是原样复制的。这会带来几个副作用：

• 源会话如果打过彩色标签，副本会继承标签，因而出现在置顶区—— 尽管 pinned_at 已经被重置为 null， 但侧栏的置顶判定是「有置顶时间或有标签」；
• 副本会继承源会话的「上次运行结果」，侧栏按结果筛选时新副本可能被错误归类；
• 副本会继承 worktree 信息，于是标题栏会显示「运行在隔离 worktree」， 并且和源会话共用同一个物理工作目录；
• 副本会继承「已开启还原点」标志，但还原点事件并没有复制——见下一节。

14.5 血缘关系

session_lineage 表的字段：

session_lineage (
child_session_id      TEXT PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
parent_session_id     TEXT NOT NULL,        -- 刻意不加外键
fork_anchor_turn_id   TEXT,
fork_cutoff_seq       INTEGER NOT NULL CHECK (fork_cutoff_seq >= 0),
source_title_snapshot TEXT NOT NULL,
created_at            TEXT NOT NULL
)

父会话刻意不加外键：删掉源会话，副本的血缘记录仍在， 界面显示「来源不可用」；血缘是链式的——从副本再分叉， 指向的是副本而不是最初的根。

分叉会同时写入 stream:session:created 事件并把新会话返回给调用方， 两边都会做去重，不会出现重复条目。

没有的功能：会话不支持导出、分享、另存为模板； 也没有任何斜杠命令或工具能分叉会话——只有上面那两个界面入口。

15. 参考会话

参考会话让另一个会话的内容作为只读资料被当前会话引用， 解决「我不想把两边合并成一条对话流，但希望 Agent 能读到那边的结论」。

入口：侧栏会话右键菜单里的添加到对话。

15.1 结构与约束

每条参考记录钉在源会话的某个已完成轮次边界（snapshot_seq）， 状态枚举 active / revoked / unavailable。

上限是每个目标会话 10 条 active 记录，超出会报错。 这个额度是累计的，而界面里的选择器只检查「本次选了几条」， 并且界面没有任何撤销或刷新参考的入口。 因此理论上存在死路：分散在多轮里累计挂满 10 条之后，你既加不了新的、也删不掉旧的。

参考内容不会自动注入提示词。Agent 只有通过三个只读工具才能读到：referenced_sessions_list、referenced_session_read、referenced_session_search。

另有一张 session_reference_audit 审计表记录attach / update_snapshot / revoke / read 动作与操作者，但它只有写入方、没有读取方—— 目前没有任何界面或接口会展示这份审计。

16. 代码还原点

还原点不是会话快照，而是工作区文件系统的 git 快照， 用来撤销 Agent 对代码的改动。两者很容易被混淆。

16.1 怎么工作

• 实现方式：临时索引 + git add -A + write-tree + commit-tree，然后写一个refs/spark/checkpoints/<sessionId>/<checkpointId> 引用。不会碰你真实的索引和 HEAD，也天然遵守 .gitignore。
• 每个会话最多保留 20 个还原点，超出会被裁掉。
• 捕获时机是每个轮次执行器开跑之前，并且要同时满足三个条件： 会话打开了还原点开关（默认关闭）、工作区是 git 仓库、 工作树相对上一个还原点有变化。
• 捕获失败不会影响轮次执行，只记录日志。
• 标签用的是你当轮的消息文本（截断到 80 字符）。

16.2 还原

还原前会自动先做一次备份，标签是还原前自动备份； 然后用 git restore --source=<ref> --worktree -- .， 这是非破坏性的。

会被阻止的情况：工作区不再是 git 仓库、ref 已不存在、 或者另一个会话正用同一工作区且有活跃轮次。

操作入口：代码还原点时间线面板、对话流里的还原点卡片， 以及 /checkpoint 命令族（别名 cp）：on / off / status / list / restore。

没有 session:restore-checkpoint 这样的 IPC 通道—— 还原是走斜杠命令路径执行的。

17. 历史导入

「导入对话历史」把你在其他 CLI / 桌面里跑过的会话搬进 Spark， 之后可以继续对话。支持三个来源。

17.1 三个入口

• 侧栏项目工具栏的上传图标，提示「从 Claude、Codex、ZCode 导入继续会话」；
• 命令面板里的导入对话历史；
• 设置 → 导入与恢复 → 导入。

17.2 扫描哪些路径

大文件做了保护：超过 8 MiB 的文件只读头部 512 KiB + 尾部 128 KiB 来取元信息； ZCode 桌面版的 JSON 因为不能截断，超过 64 MiB 会被静默跳过（只写日志，界面不会提示，来源仍然显示「可用」）。

17.3 四步流程

1. 扫描：打开即自动并行扫三个来源，画面显示正在检索本机会话，三张来源卡片分别显示扫描会话索引 / 扫描完成 / 来源不可用。 扫描有无缓存决定是否直接跳到选择页。
2. 选择：来源页签带数量、搜索框（匹配标题、项目、 源会话 ID、工作目录）、项目筛选、时间筛选 （全部时间 / 最近 7 天 / 最近 30 天 / 最近 90 天）、显示已导入复选框、重新检索本机会话。右侧预览面板可以仅看用户消息、专注预览，并提供加载完整会话。
3. 导入：显示正在导入会话与进度条，逐条上报<当前> / <总数> · <标题>。
4. 完成：显示 成功导入 / 跳过（已导入） / 失败 三行统计，以及 继续导入 / 完成。

17.4 导入后的会话长什么样

• 事件会重新生成 ID、seq 从 0 重排、按用户轮次生成新的 turnId；
• 有活动但缺终态的轮次会补一条agent_status: completed， 摘要文本是 Imported history turn completed；
• 会话的创建/更新时间会被改写成原始对话的首末时间戳，这样侧栏能按原始时间排序；
• 来源信息写进元数据：importedFrom 加 importHistory（含来源、源会话 ID、源文件、导入时间）；
• 工作目录按原对话的 cwd 匹配，不存在就自动创建， 标为 projectKind: 'imported'；取不到 cwd 时落到一个叫导入历史 的兜底工作区；
• Provider 按来源挑：Claude 优先本地 Claude CLI，Codex 优先本地 Codex CLI， ZCode 按里面的提示字段分流。一个都找不到时直接报错没有可用的 Provider，请先在「Providers」中添加。

17.5 几个需要注意的点

• 导入后的会话在界面上没有任何标记。importedFrom 数据是写了的，也通过会话摘要暴露出来了， 但渲染进程里零处引用——你分不清哪条是导入的，除非点进去看内容。
• 去重不区分来源。已导入集合是一个扁平的「源会话 ID」集合， 不按来源分组。极小概率下不同来源的 ID 撞车，会被误判为「已导入」。
• 扫描结果有进程级缓存，不会自动失效。重新打开对话框会直接复用上次结果，需要手动点重新检索本机会话。
• 自己 Spark 产生的会话会出现在 Codex 页签里， 并标记为已导入（无法再次导入）。看着奇怪，但这是刻意处理—— 避免把自己刚跑过的会话又导一遍。
• 导入的轮次是可以编辑的。导入器不写turnSource / userMessageVisibility， 而这两个字段正是「不可编辑」的判据。所以对导入会话的最后一轮做编辑， 会把那一轮从库里真删掉再重发。

18. 排查表