最近在多款 AI 编程助手之间来回切换时一个很现实的痛点越来越明显Claude Code、Codex、Grok、OpenCode 这些工具各自的会话记录都散落在终端缓冲区、本地 JSONL 日志或各自的数据目录里。想厘清“某个问题让哪个模型看过、另一个模型是怎么回答的、最终又是哪版方案被采纳”往往要反复翻终端回滚、复制粘贴、重新整理非常低效。本文要解决的就是这个问题如何把 Claude、Codex、Grok、OpenCode 的会话统一保存进一个“无限画布”Infinite Canvas让原本线性的、容易丢失的对话日志变成一张可缩放、可移动、可点击交互的知识地图。我会从核心概念讲起然后给出完整的 Python 转换脚本覆盖环境准备、会话导出、格式转换、画布导入全流程最后附上常见的安装与报错排查思路。文章适合正在使用 AI 编程助手、希望做会话复盘和知识沉淀的开发者即使目前只安装了其中一两个工具也可以直接套用这套思路。读完你不仅能把会话保存下来还能自己扩展画布生成规则把不同工具的会话按时间轴或按项目分泳道排列。1. 背景与核心概念1.1 为什么 AI 编程会话难以沉淀Claude Code、Codex、OpenCode 这类终端型 AI 编程助手本质上都是“对话即开发工具”你在终端里发指令模型读代码、改代码、执行命令再把结果反馈给你。每次交互产生的对话记录隐藏着问题的上下文、调试思路、方案取舍是比代码本身更宝贵的过程数据。但问题在于这些会话默认是“一次性”的。终端缓冲区滚动几千行后早期内容就被冲走虽然部分工具会落盘保存 JSONL 日志但日志格式不统一、字段复杂普通人很难直接阅读。更麻烦的是多工具混用时Claude Code 的解决方案和 Codex 的解决方案互相独立缺少一个统一视角来对比、串联、回放。1.2 Infinite Canvas 是什么Infinite Canvas无限画布是一种 UI 交互范式画布没有固定边界用户可以在二维平面上自由平移、缩放放置任意数量的节点。常见的产品包括 tldraw、Excalidraw、Figma、Miro也包括 Obsidian 的 Canvas 核心插件。用在 AI 会话管理上无限画布的优势非常明显。它可以放下几十次、上百次对话节点不会像终端一样被滚动条限制节点之间可以用连线表达“上下文延续”“方案对比”“错误修复”等关系而且画布本身就是结构化 JSON 数据可以由脚本自动生成。换句话说无限画布是 AI 会话日志的一种理想“可视化落点”。1.3 本文要构建的系统想象这样一个流程Claude Code、Codex、Grok、OpenCode 在各自工具中产生会话。我们把会话导出为 Markdown 或 JSONL 文件。用脚本清洗、提取关键文本。脚本把这些文本生成无限画布文件本文以 Obsidian Canvas 的.canvasJSON 格式为例。在 Obsidian、tldraw 或 Excalidraw 中打开得到一张可以缩放、拖拽、标注的“AI 协作全景图”。这个流程不依赖某个工具的私有格式只要会导出文本或 JSON就能接入自己的画布生成脚本。下面我们逐步实现。2. 环境准备与工具版本说明2.1 运行环境本文示例在以下环境中验证通过操作系统Windows 10/11、macOS、Linux 均可Python3.8 及以上版本Node.js16 及以上版本如果使用 npm 安装 CLI 工具终端PowerShell、bash、zsh 均可版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。如果你本机还没有安装 Python需要先去官网下载并加入 PATH后面运行转换脚本时要用到。2.2 安装 AI 编程助手Claude Code、Codex、OpenCode 的安装方式各不相同最常用的方式是 npm 全局安装命令形如# Claude Code npm install -g anthropic-ai/claude-code # Codex CLI npm install -g openai/codex # OpenCode npm install -g opencode-ai注意不同工具更新速度很快包名可能随版本变化安装前建议以官方 README 为准。也有部分工具提供原生安装脚本比如# 示例使用官方安装脚本 curl -fsSL https://example.com/install.sh | bashGrok 的情况略有不同它既有独立的 Web/App 产品也在部分场景下作为模型能力开放。本文重点不是讨论 Grok 本身怎么安装而是假设你已经通过某个渠道使用过 Grok 并产生了对话内容需要把相关内容导出保存。实际使用渠道请以官方文档为准。2.3 安装无限画布客户端我推荐首选 Obsidian因为它的 Canvas 文件是纯 JSON可以直接用脚本生成且支持 Markdown 文本节点非常适合展示技术会话。你只需要从 Obsidian 官网下载客户端并安装。新建一个知识库Vault。在知识库内任意目录创建一个.canvas文件Obsidian 会自动用 Canvas 视图打开。如果你不想用 Obsidian也可以尝试tldraw在线白板支持导出.tldr/.tldraw文件。Excalidraw开源白板使用.excalidrawJSON 格式。Figma / FigJam更偏设计协作适合团队画布。不过这些工具的 JSON 字段不够稳定本文为了让大家能直接复现重点使用 Obsidian Canvas 格式。2.4 推荐项目结构后面的实战会创建一个独立的目录建议结构如下canvas-session-saver/ ├── sessions/ # 存放导出的会话文件 │ ├── claude_session.md │ ├── codex_session.md │ ├── grok_session.md │ └── opencode_session.md ├── scripts/ │ ├── convert_to_canvas.py # 核心转换脚本 │ └── export_sessions.sh # 会话文件整理脚本可选 └── output/ └── ai-sessions.canvas # 生成的画布文件先手动创建目录后续步骤会往里填充内容。3. 核心原理从会话日志到无限画布3.1 会话数据从哪里来不同工具产生的会话文件格式不同但大方向一致Claude Code历史版本会在用户目录下按项目保存 JSONL 会话日志每条记录包含用户输入、模型输出、命令执行结果等。Codex CLI会在数据目录下保存会话记录内容同样以 JSON 或 JSONL 为主。OpenCode开源终端编码助手会话数据保存在本机数据目录中。Grok如果是 Web/App 使用通常需要手动复制对话内容再保存为 Markdown。无论哪种方式只要我们能拿到“人能读懂的文本”就可以统一处理。最简单的方法是在各工具界面里手动复制对话粘贴成 Markdown 文件更自动化的方式是用脚本读取 JSONL 日志并提取字段。本文的转换脚本同时支持.md和.jsonl两种输入便于读者按实际条件接入。3.2 Obsidian Canvas 的 JSON 结构Obsidian Canvas 文件是 JSON核心字段只有nodes和edges两个数组。节点node可以是文本、文件、分组连线edge表示节点之间的语义关系。最小示例{ nodes: [ { id: hello-node, type: text, text: ## 这是一个文本节点, x: 100, y: 100, width: 300, height: 200 } ], edges: [] }字段说明id节点唯一标识字符串即可。type节点类型text表示文本节点group表示分组。text文本内容支持 Markdown 语法。x、y节点左上角在画布中的坐标。width、height节点宽高。连线字段{ edges: [ { id: edge-1, fromNode: hello-node, fromSide: bottom, toNode: other-node, toSide: top } ] }fromSide/toSide可取top、bottom、left、right表示从哪个方向引出连线。Obsidian 会自动渲染成带箭头的连接线。理解了这两个数组脚本生成画布就非常简单。3.3 从线性日志到二维画布的映射会话原本是线性的一问一答、一进一出。映射到无限画布时有两种常见布局泳道布局每个 AI 工具占一列泳道同一工具下的多次会话沿纵向排列横向可以对比不同工具对同一个问题的处理方式。时间线布局所有会话按时间顺序横向排列适合复盘一次完整项目的推进过程。本文示例脚本使用两列网格布局把每个会话拆成“标题节点 内容节点”再用连线连接。学会之后可以自行改成泳道布局只调整坐标计算逻辑即可。4. 完整实战把 4 种 AI 会话保存到无限画布4.1 准备示例会话文件先在sessions目录下创建 4 个 Markdown 文件。这里以真实场景为例内容可以简化但结构要保持一致标题用#开头正文自然分段。第一个示例文件sessions/claude_session.md# Claude Code 会话修复页面白屏问题 - 时间2025-06-01 10:00 - 任务定位前端页面白屏 用户页面打开后一直白屏控制台没有明显报错。 助手先检查路由配置和入口文件的挂载逻辑重点排查 main.tsx 是否渲染了根组件。 用户发现 App.tsx 里某个 hook 抛异常导致整个树卸载。 助手给错误边界组件加上 fallback UI避免整个应用崩溃。第二个示例文件sessions/codex_session.md# Codex 会话优化列表接口性能 - 时间2025-06-01 11:20 - 任务接口响应速度从 2s 降到 300ms 用户分页查询 10 万条数据很慢。 助手检查是否缺少索引建议给 where 条件字段加复合索引并优化 count 查询。 用户加了索引之后只提升了一半。 助手进一步使用覆盖索引减少回表同时把 sort 字段也加入索引。第三个示例文件sessions/grok_session.md# Grok 会话总结日志中的错误模式 - 时间2025-06-01 14:05 - 任务从最近 1 小时错误日志里归纳规律 用户日志里频繁出现 ECONNRESET。 助手ECONNRESET 通常表示连接被对端重置可能是服务端 keep-alive 超时、负载均衡空闲断开或客户端未及时消费响应。 用户大量请求集中在网关访问如何处理。 助手建议调整空闲连接回收时间客户端增加重试机制并做指数退避。第四个示例文件sessions/opencode_session.md# OpenCode 会话补充单元测试 - 时间2025-06-01 16:40 - 任务为订单服务补充核心用例 用户给 OrderService 里的 createOrder 方法写单测。 助手先 mock 库存接口和事务管理器再验证正常创建、库存不足、参数异常三条路径。 用户测试运行时报 500是 mock 没生效。 助手检查测试类是否加了 ExtendWith(MockitoExtension.class)并确认 MockBean 的注入位置。这几个文件内容可以按真实情况替换。核心是每个文件代表一次独立会话标题清晰、正文有上下文。4.2 编写核心转换脚本在scripts目录下创建convert_to_canvas.py完整代码如下。这个脚本做四件事遍历sessions目录下的.md和.jsonl文件。对.jsonl文件做轻量解析提取文本内容。为每个会话生成一个“标题节点”和一个“内容节点”并用连线连接。输出output/ai-sessions.canvas文件。#!/usr/bin/env python3 将多个 AI 编程助手会话文件转换为无限画布文件。 输出格式Obsidian Canvas JSON (.canvas) 支持输入Markdown (.md)、JSONL (.jsonl) import json import re from pathlib import Path # ------------- 配置项 ------------- SESSIONS_DIR Path(__file__).resolve().parent.parent / sessions OUTPUT_DIR Path(__file__).resolve().parent.parent / output OUTPUT_FILE OUTPUT_DIR / ai-sessions.canvas NODE_WIDTH 520 # 内容节点宽度 NODE_HEIGHT 360 # 内容节点高度 TITLE_WIDTH 220 # 标题节点宽度 GAP_X 100 # 横向间距 GAP_Y 120 # 纵向间距 MAX_TEXT_LENGTH 2000 # 单节点最大文本长度 def clean_text(text: str, max_len: int MAX_TEXT_LENGTH) - str: 去掉多余空行并截断过长的文本避免画布节点过大。 lines [line.rstrip() for line in text.splitlines()] cleaned [] blank False for line in lines: if not line.strip(): if not blank: cleaned.append() blank True else: cleaned.append(line) blank False result \n.join(cleaned).strip() if len(result) max_len: result result[:max_len] \n\n...(已截断完整内容请查看原始文件) return result def extract_first_title(file_path: Path, content: str) - str: 从 Markdown 内容中提取一级标题没有则使用文件名。 m re.search(r^#\s(.)$, content, re.MULTILINE) if m: return m.group(1).strip() title file_path.stem.replace(_, ).replace(-, ).title() return title def extract_text_from_obj(obj): 递归提取 JSONL 会话文本。 不同工具的 JSONL 字段不同这里兼容了 content/text/message 等常见字段。 if isinstance(obj, str): return obj if isinstance(obj, list): return \n.join(extract_text_from_obj(item) for item in obj if item) if isinstance(obj, dict): for key in (content, text, message): if key in obj: value obj[key] if isinstance(value, str) and value.strip(): return value if isinstance(value, (dict, list)): inner extract_text_from_obj(value) if inner and inner.strip(): return inner parts [] for value in obj.values(): if isinstance(value, (dict, list, str)): text extract_text_from_obj(value) if text and text.strip(): parts.append(text) return \n.join(parts) return def load_session_text(file_path: Path) - str: 根据文件扩展名读取会话文本。 suffix file_path.suffix.lower() if suffix .jsonl: parts [] with file_path.open(r, encodingutf-8, errorsignore) as fp: for line in fp: line line.strip() if not line: continue try: obj json.loads(line) except json.JSONDecodeError: continue text extract_text_from_obj(obj) if text and text.strip(): parts.append(text.strip()) return \n.join(parts) # 默认按 Markdown 读取 return file_path.read_text(encodingutf-8, errorsignore) def build_canvas(session_files: list) - dict: nodes [] edges [] x, y 0, 0 for index, file_path in enumerate(session_files): content load_session_text(file_path) title extract_first_title(file_path, content) body clean_text(content) title_node_id ftitle-node-{index} content_node_id fcontent-node-{index} # 标题节点 nodes.append({ id: title_node_id, type: text, text: f## {title}\n\n源文件{file_path.name}, x: x, y: y, width: TITLE_WIDTH, height: 90, }) # 内容节点 nodes.append({ id: content_node_id, type: text, text: body, x: x TITLE_WIDTH 30, y: y, width: NODE_WIDTH, height: NODE_HEIGHT, }) # 连线标题节点右侧 - 内容节点左侧 edges.append({ id: fedge-{index}, fromNode: title_node_id, fromSide: right, toNode: content_node_id, toSide: left, }) # 两列排布偶数索引放左列奇数索引放右列 if index % 2 1: x 0 y NODE_HEIGHT GAP_Y else: x TITLE_WIDTH NODE_WIDTH 30 GAP_X return {nodes: nodes, edges: edges} def main(): OUTPUT_DIR.mkdir(parentsTrue, exist_okTrue) session_files sorted( f for f in SESSIONS_DIR.iterdir() if f.is_file() and f.suffix.lower() in (.md, .markdown, .jsonl) ) if not session_files: raise SystemExit( f未在 {SESSIONS_DIR} 目录下找到 .md 或 .jsonl 会话文件请先准备会话数据。 ) canvas_data build_canvas(session_files) with OUTPUT_FILE.open(w, encodingutf-8) as fp: json.dump(canvas_data, fp, ensure_asciiFalse, indent2) print(f已生成无限画布文件{OUTPUT_FILE}) print( f包含 {len(session_files)} 个会话 f{len(canvas_data[nodes])} 个节点 f{len(canvas_data[edges])} 条连线。 ) if __name__ __main__: main()代码里需要注意几个关键点。第一clean_text会统一压缩空行并把超过MAX_TEXT_LENGTH的文本截断。这是为了避免某个超大会话让画布节点变得无法操作实际项目中可以根据需要调大这个值。第二extract_text_from_obj是一个“启发式”解析器会递归查找content、text、message等常见字段。由于不同工具、不同版本的 JSONL 结构差异很大真正接入时建议先打印一条日志样本再调整字段优先级。第三坐标计算采用两列网格。偶数索引的会话放在左列奇数索引放在右列右列排满后回到左列并换行。这种布局简单清晰后续改成泳道布局只需调整这里的坐标公式。4.3 可选会话文件整理脚本如果你从工具数据目录直接拷贝 JSONL 文件可以准备一个scripts/export_sessions.sh把散落的会话复制到sessions目录。脚本本身很简单重点是可以根据实际路径调整#!/usr/bin/env bash # 将指定目录下的 JSONL 会话文件复制到项目 sessions 目录 set -euo pipefail SESSION_SOURCE_DIR${1:-$HOME/.codex/sessions} DEST_DIR$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd)/sessions mkdir -p $DEST_DIR find $SESSION_SOURCE_DIR -name *.jsonl -mtime -30 -exec cp {} $DEST_DIR/ \; echo 已将会话文件复制到 $DEST_DIR ls -lh $DEST_DIR注意~/.codex/sessions只是示例路径不同工具的数据目录可能完全不同。你可以先用下面的命令在用户目录下定位会话相关目录find $HOME -maxdepth 4 -type d \( -name sessions -o -name projects \) 2/dev/null不建议盲目录扫描全盘那样会碰到权限问题而且会复制到大量无关文件。4.4 运行脚本并验证结果回到项目根目录运行cd canvas-session-saver python scripts/convert_to_canvas.py正常输出已生成无限画布文件/your/path/canvas-session-saver/output/ai-sessions.canvas 包含 4 个会话8 个节点4 条连线。如果没有输出而是报错请优先检查sessions目录下是否放入了示例文件以及 Python 版本是否满足要求。用文本编辑器打开output/ai-sessions.canvas你会看到类似下面的 JSON 内容{ nodes: [ { id: title-node-0, type: text, text: ## Claude Code 会话修复页面白屏问题\n\n源文件claude_session.md, x: 0, y: 0, width: 220, height: 90 }, { id: content-node-0, type: text, text: # Claude Code 会话修复页面白屏问题\n\n- 时间2025-06-01 10:00\n- 任务定位前端页面白屏\n\n用户..., x: 250, y: 0, width: 520, height: 360 } ], edges: [ { id: edge-0, fromNode: title-node-0, fromSide: right, toNode: content-node-0, toSide: left } ] }看到这个结构说明数据层已经成功了。4.5 导入 Obsidian 无限画布打开 Obsidian进入新建的知识库把output/ai-sessions.canvas文件拖入文件面板中的任意目录。Obsidian 会自动识别并打开一个画布视图。在画布里你能看到左侧是每个会话的标题节点。右侧是会话正文节点。标题节点右侧到正文节点左侧有一条连线。你可以用鼠标拖拽缩放双击标题节点修改名称或者在空白处右键新建文本节点做批注。因为这个画布是 Obsidian 库内文件你可以在笔记中直接引用[[ai-sessions.canvas]]也可以把画布嵌入到每日笔记或项目笔记中。如果想换到 tldraw 或 Excalidraw思路是一样的写一个 JSON 转换器把nodes/edges映射到对应产品的元素结构即可。核心工作永远是“把会话文本清洗规整”后续格式转换只是适配层。5. 常见问题与排查思路AI 编程助手 无限画布的链路中最常踩的坑反而在“会话数据获取”和“工具安装”环节。下面整理了几个高频问题。问题现象常见原因解决思路claude不是内部或外部命令或无法识别为 cmdletnpm 全局目录未加入 PATH找到 npm 全局 bin 目录并加入系统 PATH或重新安装 Node.jserror: claude native binary not installed原生二进制安装脚本未执行成功删除旧安装后重装检查 npm 安装权限或改用官方安装脚本Codex 请求失败提示 local proxy failed配置的模型服务 baseURL 无法访问、认证过期检查 baseURL、API Key、网络连通性确认服务商可用.canvas文件打开后一片空白JSON 结构不合法或字段缺失用 JSON 校验工具检查确保 nodes 每项包含 id/type/text/x/y/width/height中文内容在画布里乱码文件编码不是 UTF-8转换脚本统一使用encodingutf-8写入原始文件也保存为 UTF-8会话过多画布非常卡节点数量太多或单节点文本过长按时间/项目拆分多张画布调低 MAX_TEXT_LENGTH其中第一个问题最常见。Node.js 安装后npm install -g会把命令安装到全局目录但这个目录可能不在系统 PATH 中。Windows 下排查方式如下npm prefix -g输出结果就是全局前缀目录把其中的node_modules/.binWindows 下通常为%APPDATA%\npm加入 PATH再重新打开终端输入claude --version验证。第二个问题常见于系统权限受限的环境。claude native binary not installed这个报错提示原生二进制没有安装成功通常是 npm 安装过程中postinstall脚本没有运行可能是被安全软件拦截也可能是磁盘权限不足。可尝试以管理员身份运行安装命令或使用官方提供的安装脚本。第三个问题与“会话保存”关系不算直接但会卡住会话数据的生成。Codex CLI 允许配置不同的模型服务端点如果你改写过model_providers请求失败时优先检查 baseURL 是否能访问以及远端服务是否与当前模型兼容。有些开发者会把 Codex 接到兼容 OpenAI API 的第三方模型服务这时候认证方式和限流策略要以对应平台的政策为准。6. 最佳实践与工程建议把 AI 会话保存到无限画布本质上是在建立一套个人/团队的知识沉淀系统。以下几个建议可以让这套系统长期好用。第一统一会话文件命名。建议用“工具_日期_主题”格式例如claude_20250601_白屏修复.md。命名规范能让转换脚本自动生成的标题更清晰也方便脚本按日期筛选最近会话。文件名尽量不要包含特殊符号避免跨平台兼容问题。第二进入画布前先脱敏。终端会话往往包含真实路径、密钥、API Token、内部 IP 等信息。建议在导出后先做一轮脱敏处理比如把 token 替换成***把公司内部域名替换成example.com。可以写一个简单的正则替换函数放到转换脚本里在生成画布节点前执行。第三按项目或按周分片。无限画布虽然“无限”但节点过多时 Obsidian 自身的渲染压力会上升而且知识地图一旦太密就失去了“可视化”的价值。我的经验是一个画布控制在 20 到 50 个会话节点之间超过后按周或按项目拆成多张画布再画布之间用链接互相跳转。第四把自动化做成定时任务。如果每天都会产生大量会话可以考虑用 cronmacOS/Linux或“任务计划程序”Windows每天凌晨跑一次convert_to_canvas.py把前一天的新会话追加到画布中。追加的难点在于不能重复生成已有节点可以在生成脚本里维护一个“已处理文件哈希表”只处理新增或变化的文件。第五尽量从源头导出结构化数据。手动复制粘贴虽然能用但容易丢字段。更推荐从 JSONL 日志中提取结构化信息比如会话开始时间、模型回复耗时、执行命令、报错信息等把它们作为节点的属性存入画布。这样后期可以做统计例如“哪个模型的回答被采纳最多”“哪类报错反复出现”。第六画布文件也应该纳入版本控制。sessions目录和output目录建议纳入 Git这样画布内容可以回溯。如果会话包含敏感信息可以考虑把原始日志放进.gitignore只提交脱敏后的画布文件。另一个做法是使用 Git LFS避免仓库体积过快膨胀。第七把画布变成团队知识库入口。在 Obsidian 中可以在画布顶部添加一个“导航节点”用链接指向相关需求文档、代码仓库地址、线上监控面板。这样画布就不只是会话回放而是一张完整的“问题处理作战图”。新成员接手任务时直接打开画布就能快速了解之前讨论过什么、踩过什么坑。第八关注官方导出能力变化。Claude Code、Codex、OpenCode 都在快速迭代会话存储路径、文件格式、导出命令都可能变化。建议把“会话生命周期管理”作为一个独立需求来维护而不是写死某个固定路径。最稳妥的方式是封装一个适配层为每个工具提供单独的导出函数再统一交给画布生成模块。7. 总结与下一步实践本文从“AI 会话难以沉淀”这个痛点出发介绍了 Infinite Canvas 的概念并完整实现了“Claude Code / Codex / Grok / OpenCode 会话 → Markdown/JSONL → Obsidian Canvas”的转换链路。你已经掌握各 AI 编程助手会话数据的基本来源和导出思路。Obsidian Canvas JSON 文件的核心结构。用 Python 脚本把多个会话文件转换为无限画布的完整方法。常见安装报错和画布文件问题的排查方向。会话知识沉淀的工程化建议。下一步可以继续做的方向很多你可以改进脚本把两列网格改成按工具分泳道也可以加入 WordCloud 或统计分析从大量会话中提炼高频问题还可以把画布接入团队知识库让每一次调试过程都变成可检索的组织资产。如果本文对你有帮助建议先按照 4.1 到 4.5 节的步骤跑通最小流程再逐步替换成你自己的会话数据。动手之后你会发现“保存会话”这件事值得认真对待。 将Claude、Codex等AI编程助手会话统一导入无限画布的实现方法
最近在多款 AI 编程助手之间来回切换时一个很现实的痛点越来越明显Claude Code、Codex、Grok、OpenCode 这些工具各自的会话记录都散落在终端缓冲区、本地 JSONL 日志或各自的数据目录里。想厘清“某个问题让哪个模型看过、另一个模型是怎么回答的、最终又是哪版方案被采纳”往往要反复翻终端回滚、复制粘贴、重新整理非常低效。本文要解决的就是这个问题如何把 Claude、Codex、Grok、OpenCode 的会话统一保存进一个“无限画布”Infinite Canvas让原本线性的、容易丢失的对话日志变成一张可缩放、可移动、可点击交互的知识地图。我会从核心概念讲起然后给出完整的 Python 转换脚本覆盖环境准备、会话导出、格式转换、画布导入全流程最后附上常见的安装与报错排查思路。文章适合正在使用 AI 编程助手、希望做会话复盘和知识沉淀的开发者即使目前只安装了其中一两个工具也可以直接套用这套思路。读完你不仅能把会话保存下来还能自己扩展画布生成规则把不同工具的会话按时间轴或按项目分泳道排列。1. 背景与核心概念1.1 为什么 AI 编程会话难以沉淀Claude Code、Codex、OpenCode 这类终端型 AI 编程助手本质上都是“对话即开发工具”你在终端里发指令模型读代码、改代码、执行命令再把结果反馈给你。每次交互产生的对话记录隐藏着问题的上下文、调试思路、方案取舍是比代码本身更宝贵的过程数据。但问题在于这些会话默认是“一次性”的。终端缓冲区滚动几千行后早期内容就被冲走虽然部分工具会落盘保存 JSONL 日志但日志格式不统一、字段复杂普通人很难直接阅读。更麻烦的是多工具混用时Claude Code 的解决方案和 Codex 的解决方案互相独立缺少一个统一视角来对比、串联、回放。1.2 Infinite Canvas 是什么Infinite Canvas无限画布是一种 UI 交互范式画布没有固定边界用户可以在二维平面上自由平移、缩放放置任意数量的节点。常见的产品包括 tldraw、Excalidraw、Figma、Miro也包括 Obsidian 的 Canvas 核心插件。用在 AI 会话管理上无限画布的优势非常明显。它可以放下几十次、上百次对话节点不会像终端一样被滚动条限制节点之间可以用连线表达“上下文延续”“方案对比”“错误修复”等关系而且画布本身就是结构化 JSON 数据可以由脚本自动生成。换句话说无限画布是 AI 会话日志的一种理想“可视化落点”。1.3 本文要构建的系统想象这样一个流程Claude Code、Codex、Grok、OpenCode 在各自工具中产生会话。我们把会话导出为 Markdown 或 JSONL 文件。用脚本清洗、提取关键文本。脚本把这些文本生成无限画布文件本文以 Obsidian Canvas 的.canvasJSON 格式为例。在 Obsidian、tldraw 或 Excalidraw 中打开得到一张可以缩放、拖拽、标注的“AI 协作全景图”。这个流程不依赖某个工具的私有格式只要会导出文本或 JSON就能接入自己的画布生成脚本。下面我们逐步实现。2. 环境准备与工具版本说明2.1 运行环境本文示例在以下环境中验证通过操作系统Windows 10/11、macOS、Linux 均可Python3.8 及以上版本Node.js16 及以上版本如果使用 npm 安装 CLI 工具终端PowerShell、bash、zsh 均可版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。如果你本机还没有安装 Python需要先去官网下载并加入 PATH后面运行转换脚本时要用到。2.2 安装 AI 编程助手Claude Code、Codex、OpenCode 的安装方式各不相同最常用的方式是 npm 全局安装命令形如# Claude Code npm install -g anthropic-ai/claude-code # Codex CLI npm install -g openai/codex # OpenCode npm install -g opencode-ai注意不同工具更新速度很快包名可能随版本变化安装前建议以官方 README 为准。也有部分工具提供原生安装脚本比如# 示例使用官方安装脚本 curl -fsSL https://example.com/install.sh | bashGrok 的情况略有不同它既有独立的 Web/App 产品也在部分场景下作为模型能力开放。本文重点不是讨论 Grok 本身怎么安装而是假设你已经通过某个渠道使用过 Grok 并产生了对话内容需要把相关内容导出保存。实际使用渠道请以官方文档为准。2.3 安装无限画布客户端我推荐首选 Obsidian因为它的 Canvas 文件是纯 JSON可以直接用脚本生成且支持 Markdown 文本节点非常适合展示技术会话。你只需要从 Obsidian 官网下载客户端并安装。新建一个知识库Vault。在知识库内任意目录创建一个.canvas文件Obsidian 会自动用 Canvas 视图打开。如果你不想用 Obsidian也可以尝试tldraw在线白板支持导出.tldr/.tldraw文件。Excalidraw开源白板使用.excalidrawJSON 格式。Figma / FigJam更偏设计协作适合团队画布。不过这些工具的 JSON 字段不够稳定本文为了让大家能直接复现重点使用 Obsidian Canvas 格式。2.4 推荐项目结构后面的实战会创建一个独立的目录建议结构如下canvas-session-saver/ ├── sessions/ # 存放导出的会话文件 │ ├── claude_session.md │ ├── codex_session.md │ ├── grok_session.md │ └── opencode_session.md ├── scripts/ │ ├── convert_to_canvas.py # 核心转换脚本 │ └── export_sessions.sh # 会话文件整理脚本可选 └── output/ └── ai-sessions.canvas # 生成的画布文件先手动创建目录后续步骤会往里填充内容。3. 核心原理从会话日志到无限画布3.1 会话数据从哪里来不同工具产生的会话文件格式不同但大方向一致Claude Code历史版本会在用户目录下按项目保存 JSONL 会话日志每条记录包含用户输入、模型输出、命令执行结果等。Codex CLI会在数据目录下保存会话记录内容同样以 JSON 或 JSONL 为主。OpenCode开源终端编码助手会话数据保存在本机数据目录中。Grok如果是 Web/App 使用通常需要手动复制对话内容再保存为 Markdown。无论哪种方式只要我们能拿到“人能读懂的文本”就可以统一处理。最简单的方法是在各工具界面里手动复制对话粘贴成 Markdown 文件更自动化的方式是用脚本读取 JSONL 日志并提取字段。本文的转换脚本同时支持.md和.jsonl两种输入便于读者按实际条件接入。3.2 Obsidian Canvas 的 JSON 结构Obsidian Canvas 文件是 JSON核心字段只有nodes和edges两个数组。节点node可以是文本、文件、分组连线edge表示节点之间的语义关系。最小示例{ nodes: [ { id: hello-node, type: text, text: ## 这是一个文本节点, x: 100, y: 100, width: 300, height: 200 } ], edges: [] }字段说明id节点唯一标识字符串即可。type节点类型text表示文本节点group表示分组。text文本内容支持 Markdown 语法。x、y节点左上角在画布中的坐标。width、height节点宽高。连线字段{ edges: [ { id: edge-1, fromNode: hello-node, fromSide: bottom, toNode: other-node, toSide: top } ] }fromSide/toSide可取top、bottom、left、right表示从哪个方向引出连线。Obsidian 会自动渲染成带箭头的连接线。理解了这两个数组脚本生成画布就非常简单。3.3 从线性日志到二维画布的映射会话原本是线性的一问一答、一进一出。映射到无限画布时有两种常见布局泳道布局每个 AI 工具占一列泳道同一工具下的多次会话沿纵向排列横向可以对比不同工具对同一个问题的处理方式。时间线布局所有会话按时间顺序横向排列适合复盘一次完整项目的推进过程。本文示例脚本使用两列网格布局把每个会话拆成“标题节点 内容节点”再用连线连接。学会之后可以自行改成泳道布局只调整坐标计算逻辑即可。4. 完整实战把 4 种 AI 会话保存到无限画布4.1 准备示例会话文件先在sessions目录下创建 4 个 Markdown 文件。这里以真实场景为例内容可以简化但结构要保持一致标题用#开头正文自然分段。第一个示例文件sessions/claude_session.md# Claude Code 会话修复页面白屏问题 - 时间2025-06-01 10:00 - 任务定位前端页面白屏 用户页面打开后一直白屏控制台没有明显报错。 助手先检查路由配置和入口文件的挂载逻辑重点排查 main.tsx 是否渲染了根组件。 用户发现 App.tsx 里某个 hook 抛异常导致整个树卸载。 助手给错误边界组件加上 fallback UI避免整个应用崩溃。第二个示例文件sessions/codex_session.md# Codex 会话优化列表接口性能 - 时间2025-06-01 11:20 - 任务接口响应速度从 2s 降到 300ms 用户分页查询 10 万条数据很慢。 助手检查是否缺少索引建议给 where 条件字段加复合索引并优化 count 查询。 用户加了索引之后只提升了一半。 助手进一步使用覆盖索引减少回表同时把 sort 字段也加入索引。第三个示例文件sessions/grok_session.md# Grok 会话总结日志中的错误模式 - 时间2025-06-01 14:05 - 任务从最近 1 小时错误日志里归纳规律 用户日志里频繁出现 ECONNRESET。 助手ECONNRESET 通常表示连接被对端重置可能是服务端 keep-alive 超时、负载均衡空闲断开或客户端未及时消费响应。 用户大量请求集中在网关访问如何处理。 助手建议调整空闲连接回收时间客户端增加重试机制并做指数退避。第四个示例文件sessions/opencode_session.md# OpenCode 会话补充单元测试 - 时间2025-06-01 16:40 - 任务为订单服务补充核心用例 用户给 OrderService 里的 createOrder 方法写单测。 助手先 mock 库存接口和事务管理器再验证正常创建、库存不足、参数异常三条路径。 用户测试运行时报 500是 mock 没生效。 助手检查测试类是否加了 ExtendWith(MockitoExtension.class)并确认 MockBean 的注入位置。这几个文件内容可以按真实情况替换。核心是每个文件代表一次独立会话标题清晰、正文有上下文。4.2 编写核心转换脚本在scripts目录下创建convert_to_canvas.py完整代码如下。这个脚本做四件事遍历sessions目录下的.md和.jsonl文件。对.jsonl文件做轻量解析提取文本内容。为每个会话生成一个“标题节点”和一个“内容节点”并用连线连接。输出output/ai-sessions.canvas文件。#!/usr/bin/env python3 将多个 AI 编程助手会话文件转换为无限画布文件。 输出格式Obsidian Canvas JSON (.canvas) 支持输入Markdown (.md)、JSONL (.jsonl) import json import re from pathlib import Path # ------------- 配置项 ------------- SESSIONS_DIR Path(__file__).resolve().parent.parent / sessions OUTPUT_DIR Path(__file__).resolve().parent.parent / output OUTPUT_FILE OUTPUT_DIR / ai-sessions.canvas NODE_WIDTH 520 # 内容节点宽度 NODE_HEIGHT 360 # 内容节点高度 TITLE_WIDTH 220 # 标题节点宽度 GAP_X 100 # 横向间距 GAP_Y 120 # 纵向间距 MAX_TEXT_LENGTH 2000 # 单节点最大文本长度 def clean_text(text: str, max_len: int MAX_TEXT_LENGTH) - str: 去掉多余空行并截断过长的文本避免画布节点过大。 lines [line.rstrip() for line in text.splitlines()] cleaned [] blank False for line in lines: if not line.strip(): if not blank: cleaned.append() blank True else: cleaned.append(line) blank False result \n.join(cleaned).strip() if len(result) max_len: result result[:max_len] \n\n...(已截断完整内容请查看原始文件) return result def extract_first_title(file_path: Path, content: str) - str: 从 Markdown 内容中提取一级标题没有则使用文件名。 m re.search(r^#\s(.)$, content, re.MULTILINE) if m: return m.group(1).strip() title file_path.stem.replace(_, ).replace(-, ).title() return title def extract_text_from_obj(obj): 递归提取 JSONL 会话文本。 不同工具的 JSONL 字段不同这里兼容了 content/text/message 等常见字段。 if isinstance(obj, str): return obj if isinstance(obj, list): return \n.join(extract_text_from_obj(item) for item in obj if item) if isinstance(obj, dict): for key in (content, text, message): if key in obj: value obj[key] if isinstance(value, str) and value.strip(): return value if isinstance(value, (dict, list)): inner extract_text_from_obj(value) if inner and inner.strip(): return inner parts [] for value in obj.values(): if isinstance(value, (dict, list, str)): text extract_text_from_obj(value) if text and text.strip(): parts.append(text) return \n.join(parts) return def load_session_text(file_path: Path) - str: 根据文件扩展名读取会话文本。 suffix file_path.suffix.lower() if suffix .jsonl: parts [] with file_path.open(r, encodingutf-8, errorsignore) as fp: for line in fp: line line.strip() if not line: continue try: obj json.loads(line) except json.JSONDecodeError: continue text extract_text_from_obj(obj) if text and text.strip(): parts.append(text.strip()) return \n.join(parts) # 默认按 Markdown 读取 return file_path.read_text(encodingutf-8, errorsignore) def build_canvas(session_files: list) - dict: nodes [] edges [] x, y 0, 0 for index, file_path in enumerate(session_files): content load_session_text(file_path) title extract_first_title(file_path, content) body clean_text(content) title_node_id ftitle-node-{index} content_node_id fcontent-node-{index} # 标题节点 nodes.append({ id: title_node_id, type: text, text: f## {title}\n\n源文件{file_path.name}, x: x, y: y, width: TITLE_WIDTH, height: 90, }) # 内容节点 nodes.append({ id: content_node_id, type: text, text: body, x: x TITLE_WIDTH 30, y: y, width: NODE_WIDTH, height: NODE_HEIGHT, }) # 连线标题节点右侧 - 内容节点左侧 edges.append({ id: fedge-{index}, fromNode: title_node_id, fromSide: right, toNode: content_node_id, toSide: left, }) # 两列排布偶数索引放左列奇数索引放右列 if index % 2 1: x 0 y NODE_HEIGHT GAP_Y else: x TITLE_WIDTH NODE_WIDTH 30 GAP_X return {nodes: nodes, edges: edges} def main(): OUTPUT_DIR.mkdir(parentsTrue, exist_okTrue) session_files sorted( f for f in SESSIONS_DIR.iterdir() if f.is_file() and f.suffix.lower() in (.md, .markdown, .jsonl) ) if not session_files: raise SystemExit( f未在 {SESSIONS_DIR} 目录下找到 .md 或 .jsonl 会话文件请先准备会话数据。 ) canvas_data build_canvas(session_files) with OUTPUT_FILE.open(w, encodingutf-8) as fp: json.dump(canvas_data, fp, ensure_asciiFalse, indent2) print(f已生成无限画布文件{OUTPUT_FILE}) print( f包含 {len(session_files)} 个会话 f{len(canvas_data[nodes])} 个节点 f{len(canvas_data[edges])} 条连线。 ) if __name__ __main__: main()代码里需要注意几个关键点。第一clean_text会统一压缩空行并把超过MAX_TEXT_LENGTH的文本截断。这是为了避免某个超大会话让画布节点变得无法操作实际项目中可以根据需要调大这个值。第二extract_text_from_obj是一个“启发式”解析器会递归查找content、text、message等常见字段。由于不同工具、不同版本的 JSONL 结构差异很大真正接入时建议先打印一条日志样本再调整字段优先级。第三坐标计算采用两列网格。偶数索引的会话放在左列奇数索引放在右列右列排满后回到左列并换行。这种布局简单清晰后续改成泳道布局只需调整这里的坐标公式。4.3 可选会话文件整理脚本如果你从工具数据目录直接拷贝 JSONL 文件可以准备一个scripts/export_sessions.sh把散落的会话复制到sessions目录。脚本本身很简单重点是可以根据实际路径调整#!/usr/bin/env bash # 将指定目录下的 JSONL 会话文件复制到项目 sessions 目录 set -euo pipefail SESSION_SOURCE_DIR${1:-$HOME/.codex/sessions} DEST_DIR$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd)/sessions mkdir -p $DEST_DIR find $SESSION_SOURCE_DIR -name *.jsonl -mtime -30 -exec cp {} $DEST_DIR/ \; echo 已将会话文件复制到 $DEST_DIR ls -lh $DEST_DIR注意~/.codex/sessions只是示例路径不同工具的数据目录可能完全不同。你可以先用下面的命令在用户目录下定位会话相关目录find $HOME -maxdepth 4 -type d \( -name sessions -o -name projects \) 2/dev/null不建议盲目录扫描全盘那样会碰到权限问题而且会复制到大量无关文件。4.4 运行脚本并验证结果回到项目根目录运行cd canvas-session-saver python scripts/convert_to_canvas.py正常输出已生成无限画布文件/your/path/canvas-session-saver/output/ai-sessions.canvas 包含 4 个会话8 个节点4 条连线。如果没有输出而是报错请优先检查sessions目录下是否放入了示例文件以及 Python 版本是否满足要求。用文本编辑器打开output/ai-sessions.canvas你会看到类似下面的 JSON 内容{ nodes: [ { id: title-node-0, type: text, text: ## Claude Code 会话修复页面白屏问题\n\n源文件claude_session.md, x: 0, y: 0, width: 220, height: 90 }, { id: content-node-0, type: text, text: # Claude Code 会话修复页面白屏问题\n\n- 时间2025-06-01 10:00\n- 任务定位前端页面白屏\n\n用户..., x: 250, y: 0, width: 520, height: 360 } ], edges: [ { id: edge-0, fromNode: title-node-0, fromSide: right, toNode: content-node-0, toSide: left } ] }看到这个结构说明数据层已经成功了。4.5 导入 Obsidian 无限画布打开 Obsidian进入新建的知识库把output/ai-sessions.canvas文件拖入文件面板中的任意目录。Obsidian 会自动识别并打开一个画布视图。在画布里你能看到左侧是每个会话的标题节点。右侧是会话正文节点。标题节点右侧到正文节点左侧有一条连线。你可以用鼠标拖拽缩放双击标题节点修改名称或者在空白处右键新建文本节点做批注。因为这个画布是 Obsidian 库内文件你可以在笔记中直接引用[[ai-sessions.canvas]]也可以把画布嵌入到每日笔记或项目笔记中。如果想换到 tldraw 或 Excalidraw思路是一样的写一个 JSON 转换器把nodes/edges映射到对应产品的元素结构即可。核心工作永远是“把会话文本清洗规整”后续格式转换只是适配层。5. 常见问题与排查思路AI 编程助手 无限画布的链路中最常踩的坑反而在“会话数据获取”和“工具安装”环节。下面整理了几个高频问题。问题现象常见原因解决思路claude不是内部或外部命令或无法识别为 cmdletnpm 全局目录未加入 PATH找到 npm 全局 bin 目录并加入系统 PATH或重新安装 Node.jserror: claude native binary not installed原生二进制安装脚本未执行成功删除旧安装后重装检查 npm 安装权限或改用官方安装脚本Codex 请求失败提示 local proxy failed配置的模型服务 baseURL 无法访问、认证过期检查 baseURL、API Key、网络连通性确认服务商可用.canvas文件打开后一片空白JSON 结构不合法或字段缺失用 JSON 校验工具检查确保 nodes 每项包含 id/type/text/x/y/width/height中文内容在画布里乱码文件编码不是 UTF-8转换脚本统一使用encodingutf-8写入原始文件也保存为 UTF-8会话过多画布非常卡节点数量太多或单节点文本过长按时间/项目拆分多张画布调低 MAX_TEXT_LENGTH其中第一个问题最常见。Node.js 安装后npm install -g会把命令安装到全局目录但这个目录可能不在系统 PATH 中。Windows 下排查方式如下npm prefix -g输出结果就是全局前缀目录把其中的node_modules/.binWindows 下通常为%APPDATA%\npm加入 PATH再重新打开终端输入claude --version验证。第二个问题常见于系统权限受限的环境。claude native binary not installed这个报错提示原生二进制没有安装成功通常是 npm 安装过程中postinstall脚本没有运行可能是被安全软件拦截也可能是磁盘权限不足。可尝试以管理员身份运行安装命令或使用官方提供的安装脚本。第三个问题与“会话保存”关系不算直接但会卡住会话数据的生成。Codex CLI 允许配置不同的模型服务端点如果你改写过model_providers请求失败时优先检查 baseURL 是否能访问以及远端服务是否与当前模型兼容。有些开发者会把 Codex 接到兼容 OpenAI API 的第三方模型服务这时候认证方式和限流策略要以对应平台的政策为准。6. 最佳实践与工程建议把 AI 会话保存到无限画布本质上是在建立一套个人/团队的知识沉淀系统。以下几个建议可以让这套系统长期好用。第一统一会话文件命名。建议用“工具_日期_主题”格式例如claude_20250601_白屏修复.md。命名规范能让转换脚本自动生成的标题更清晰也方便脚本按日期筛选最近会话。文件名尽量不要包含特殊符号避免跨平台兼容问题。第二进入画布前先脱敏。终端会话往往包含真实路径、密钥、API Token、内部 IP 等信息。建议在导出后先做一轮脱敏处理比如把 token 替换成***把公司内部域名替换成example.com。可以写一个简单的正则替换函数放到转换脚本里在生成画布节点前执行。第三按项目或按周分片。无限画布虽然“无限”但节点过多时 Obsidian 自身的渲染压力会上升而且知识地图一旦太密就失去了“可视化”的价值。我的经验是一个画布控制在 20 到 50 个会话节点之间超过后按周或按项目拆成多张画布再画布之间用链接互相跳转。第四把自动化做成定时任务。如果每天都会产生大量会话可以考虑用 cronmacOS/Linux或“任务计划程序”Windows每天凌晨跑一次convert_to_canvas.py把前一天的新会话追加到画布中。追加的难点在于不能重复生成已有节点可以在生成脚本里维护一个“已处理文件哈希表”只处理新增或变化的文件。第五尽量从源头导出结构化数据。手动复制粘贴虽然能用但容易丢字段。更推荐从 JSONL 日志中提取结构化信息比如会话开始时间、模型回复耗时、执行命令、报错信息等把它们作为节点的属性存入画布。这样后期可以做统计例如“哪个模型的回答被采纳最多”“哪类报错反复出现”。第六画布文件也应该纳入版本控制。sessions目录和output目录建议纳入 Git这样画布内容可以回溯。如果会话包含敏感信息可以考虑把原始日志放进.gitignore只提交脱敏后的画布文件。另一个做法是使用 Git LFS避免仓库体积过快膨胀。第七把画布变成团队知识库入口。在 Obsidian 中可以在画布顶部添加一个“导航节点”用链接指向相关需求文档、代码仓库地址、线上监控面板。这样画布就不只是会话回放而是一张完整的“问题处理作战图”。新成员接手任务时直接打开画布就能快速了解之前讨论过什么、踩过什么坑。第八关注官方导出能力变化。Claude Code、Codex、OpenCode 都在快速迭代会话存储路径、文件格式、导出命令都可能变化。建议把“会话生命周期管理”作为一个独立需求来维护而不是写死某个固定路径。最稳妥的方式是封装一个适配层为每个工具提供单独的导出函数再统一交给画布生成模块。7. 总结与下一步实践本文从“AI 会话难以沉淀”这个痛点出发介绍了 Infinite Canvas 的概念并完整实现了“Claude Code / Codex / Grok / OpenCode 会话 → Markdown/JSONL → Obsidian Canvas”的转换链路。你已经掌握各 AI 编程助手会话数据的基本来源和导出思路。Obsidian Canvas JSON 文件的核心结构。用 Python 脚本把多个会话文件转换为无限画布的完整方法。常见安装报错和画布文件问题的排查方向。会话知识沉淀的工程化建议。下一步可以继续做的方向很多你可以改进脚本把两列网格改成按工具分泳道也可以加入 WordCloud 或统计分析从大量会话中提炼高频问题还可以把画布接入团队知识库让每一次调试过程都变成可检索的组织资产。如果本文对你有帮助建议先按照 4.1 到 4.5 节的步骤跑通最小流程再逐步替换成你自己的会话数据。动手之后你会发现“保存会话”这件事值得认真对待。