import-claude-session
把外部机器导出的 Claude Code 原生 session 日志(.jsonl)导入本机,让 universe-editor 的 Agents 视图能加载/恢复该会话。当用户拿来一个别处产生的 claude session jsonl、说「导入会话 / 让编辑器能加载这个 session / 转换 session 格式」时使用。
SKILL.md.claude/skills/import-claude-session/SKILL.md
GitHub导入外部 Claude session 到本机编辑器
机制(先懂再操作)
- 对话内容只存 agent 侧 Claude Code 原生 transcript:
<CLAUDE_CONFIG_DIR ?? ~/.claude>/projects/<slug>/<sessionId>.jsonl(vendor/claude-agent-acp/src/acp-agent.ts的findTranscriptFile)。编辑器不复制对话内容。 - slug =
cwd.replace(/[^a-zA-Z0-9]/g, "-")(cwd 里所有非字母数字字符变-)。 - 编辑器会话列表元数据由 hydrate sweep 调 fork 的
session/list自动 upsert,不需要手写;触发时机 = 打开 Agents 视图 / 工作区切换 / 手动刷新。 - resume 时 agent 进程以 entry.cwd 为工作目录、SDK 按 slug 定位 jsonl,所以文件落盘位置与行内
cwd字段必须一致——从外部机器导入时必须改写行内cwd为本机目标工作区路径。 - jsonl 格式要求:一行一个 JSON;消息行
type: "user"|"assistant"必须有字符串uuid,parentUuid链完整(parent 在 child 前);system/attachment/file-history-snapshot/queue-operation/last-prompt/mode等非消息行被兼容忽略。
头号坑:MAX_ENTRIES=100 淘汰
编辑器历史按 lastUsedAt 降序只留 100 条(apps/editor/src/renderer/services/acp/session/acpSessionHistory.ts 的 MAX_ENTRIES),lastUsedAt 取自会话最后一条真实消息的 timestamp。导入的会话若比现存最老条目还旧,merge 后立刻被淘汰,怎么刷新都看不到(真实案例,2026-07)。因此脚本默认把最后一条消息的 timestamp 拨到现在——这是必要步骤,不是美化。
操作步骤
用 skill 目录下的脚本一把梭(纯 node 标准库,无依赖):
node .claude/skills/import-claude-session/import-session.mjs \
<源文件.jsonl> <目标工作区绝对路径> \
[--title "会话标题"] [--branch 分支名] [--keep-timestamps] [--force]
脚本自动完成:
- 逐行解析校验(消息行 uuid / parentUuid 链完整性,有断裂会警告)
- 改写所有行内顶层
cwd为目标工作区(规范化:绝对路径 + 盘符大写) gitBranch改为目标目录当前分支(git rev-parse自动探测,可用--branch覆盖)- 把最后一条消息的 timestamp 拨到现在(逃过 MAX_ENTRIES 截断;
--keep-timestamps可关) --title时在文件头注入 summary 行(注意:SDK 可能仍按自己的摘要覆盖标题,属正常)- 按 slug 规则写到
~/.claude/projects/<slug>/<sessionId>.jsonl(已存在需--force)
验证
- 目标工作区在编辑器里打开 → Agents 视图 → 刷新。
- 会话应出现在列表最顶部(lastUsedAt = 现在)。标题可能是
--title注入的,也可能是 SDK 自己算的摘要。 - 点击会话走
session/load重放完整历史(含跨 compact 边界),确认消息 / tool_use / thinking 正常。
排查(看不到会话时)
按顺序查:
- 用 vendor 的 SDK 直接验证发现:
cd vendor/claude-agent-acp && node -e "import('@anthropic-ai/claude-agent-sdk').then(m=>m.listSessions({dir:'<目标cwd>'}).then(s=>console.log(s.length, s.find(x=>x.sessionId==='<sid>'))))"。SDK 看不到 → 文件位置/slug/格式问题。 - 查编辑器历史存储是否收了它:
grep -l "<sessionId>" "$APPDATA/Universe Editor/workspaces/"*.json(dev 模式是Universe Editor - Dev)。只出现在workbench.recentFiles= 编辑器没收。 - 编辑器没收的最大原因就是上面的 MAX_ENTRIES 淘汰——确认导入时没加
--keep-timestamps,且刷新动作发生在文件落盘之后。
注意
- 不改写消息正文里的旧机器路径引用(历史内容保持原样)。
- 同一 sessionId 已在目标目录存在时需
--force覆盖。 - 源文件可以是 Claude Code CLI / SDK / 另一台机器的 universe-editor 产生的任意原生 session jsonl。