大家好，我是 Chendestiny。
【导读】一个解决"AI 编程助手会话孤岛"问题的开源 Skill：装进
~/.agents/skills/后，对任意 Agent 说一句"同步会话"即可触发，十多家的会话互通，任何一家的对话可以在另一家打开继续聊；还带一个本地可视化面板（ass web），全部会话摊在一张时间轴上看。
GitHub：github.com/Chendestiny…
目前支持 dsh、zcode、hermes、Claude Code CLI、codex CLI、opencode、workbuddy、qoder、openclaw、cursor、trae、MiniMax Code、Pi Agent、Gemini CLI、Cline、MiMo-Code、Kimi Code、Grok Build、GitHub Copilot
先看怎么用：两句话
装好之后，你在任何 AI Agent 里（dsh、zcode、hermes、Claude Code、codex...）发两句话就够了：
帮我安装 agent-session-sync：
irm https://raw.githubusercontent.com/Chendestiny/agent-session-sync/main/install.ps1 | iex
用 session-sync skill 同步会话到 dsh，按它的纪律跑完闭环
第一句安装，一行命令落位 ~/.agents/skills/session-sync，自动桥接进 WorkBuddy / Claude Code 等各家自有的 skills 目录（它们并不认通用位），并注册全局快捷命令 ass；第二句触发，Agent 会按 Skill 里的纪律执行：沙箱自检 → 两道人工确认 → dry-run 看计划 → 落盘 → 校验 → 挂分组闭环。你只需要在确认菜单上按两次回车。
装完随时可以：ass web 打开本地可视化面板（19 张源卡官方图标跑马灯、时间轴、会话列表、导出、备份、目录绑定），ass doctor 一键体检+自修复（缺依赖自动装、skills 桥接/命令坏了自己补）。
不喜欢对话式？手动也是三条命令的事，见下文「5 分钟上手」。
痛点：会话孤岛
我的日常是多个 AI Agent 混着用：codex CLI、Claude Code、opencode、hermes、zcode、workbuddy、qoder、openclaw、cursor、trae、dsh、MiniMax Code、Pi Agent、Gemini CLI、Cline。每家都把会话存在自己的私有格式里，互相是孤岛。
最疼的场景很具体：在 A 家聊到一半的上下文，想在 B 家继续。比如在 zcode 里做了半天的架构分析，想在 dsh 里接着问，只能复制粘贴，工具调用、思维链全丢。换工具等于记忆清零。
去找现成工具，发现这个赛道 2025 年末才萌芽，全网只有几个两位数 star 的项目（session-migrate、ctxmv 等），且都只覆盖西式 CLI。于是自己动手，写着写着变成了一个完整开源项目。
agent-session-sync 是什么
一个 Python CLI 工具，同时打包成标准 Skill（安装即落位 ~/.agents/skills/session-sync，dsh / zcode / hermes 等都能发现）。核心能力：
- 19 家全读：codex / Claude Code / opencode / hermes / zcode / workbuddy / qoder / openclaw / cursor / trae / dsh / MiniMax Code / Pi Agent / Gemini CLI / Cline / MiMo-Code / Kimi Code / Grok Build / GitHub Copilot 的会话全部解析成统一格式
- 10 家可写：会话导入后可在原 App 里打开、续聊（zcode / qoder / openclaw / cursor / trae 只读）
- 持续同步而非一次性迁移：幂等、增量、断点续推、Markdown 归档
| 能力 | |
|---|---|
| 读取 | 19 家存储格式全逆向，工具调用往返/推理全保真 |
| 写入 | dsh · codex · Claude Code · hermes · opencode · workbuddy · MiniMax Code · Pi Agent · Gemini CLI · Cline |
| 归档 | 统一 Markdown 导出 |
架构：A→C→B，不是 190 条直连
十九家互通，直觉方案是点对点：19×10 = 190 条路径，每条都要维护格式映射、幂等、增量，根本不可维护。
实际架构是 hub-and-spoke，本地规范库 ~/.session-sync 居中：
| A · 读取源（19 家） | C · 归一化 | B · 写入目标（10 家 + 归档） |
|---|---|---|
| codex · Claude Code · dsh · hermes · workbuddy · opencode · MiniMax Code · Pi Agent · Gemini CLI · Cline · zcode · qoder · openclaw · cursor · trae · MiMo-Code · Kimi Code · Grok Build · GitHub Copilot（后 9 家只读） | IR（turns）+ 规范库 ~/.session-sync | dsh · codex · Claude Code · hermes · opencode · workbuddy · MiniMax Code · Pi Agent · Gemini CLI · Cline + Markdown |
19 读 + 10 写 = 29 个适配器，190 条直连消失；新接一家成本 O(1)，写一个 reader 或 writer 就行。
~/.session-sync/
├── sessions/<source>/<id>.json ← 统一格式：工具调用/推理/轮次全保真
├── .agentsync-state.json ← 各源 pull 水位（增量基准）
└── push-<target>-state.json ← 每目标 push 水位（断点续推）
两个取舍：
- pull 永远安全，push 谨慎执行。pull 只读各 App、只写规范库，在 hermes 里拉 hermes 自己的会话也不用退出 App。push 才写目标存储，每目标独立水位，被中断后换任何 Agent 重跑一条命令即续。
- 单向不回写。会话以确定性 id（uuid5）写入目标，重复执行不重复导入；但目标的续聊绝不合并回源，双向的分叉和列表污染是实测出来的不归路。
5 分钟上手
# 安装（一行，装完即 Skill）
irm https://raw.githubusercontent.com/Chendestiny/agent-session-sync/main/install.ps1 | iex
# 之后对任意 Agent 说「同步会话」即可触发；手动用法：
cd ~\.agents\skills\session-sync
python sync.py selftest # 沙箱自检，全绿再动真数据
python sync.py status # 十九家存储探测 + 会话统计总览
# 全局快捷命令（装完即有）：
ass web # 可视化面板：19 卡官方图标/时间轴/会话列表/导出/备份/目录绑定
ass doctor # 一键体检+自修复（依赖自动装/桥接/命令自愈）
把 workbuddy 和 zcode 的会话导入 dsh 继续聊：
python sync.py to-dsh --source workbuddy,zcode --scope inc --apply
# 完整闭环 = 导入 → 退出 dsh → attach-dsh --apply（挂分组+标题）→ 重启 dsh
或者走规范库路线（断点续推）：
python sync.py pull # 全部源 → ~/.session-sync（安全，免退出任何 App）
python sync.py push --target dsh --apply # 规范库 → dsh，中断了重跑即续
反向也一行：to-codex / to-claude / to-hermes / to-opencode / to-workbuddy / to-minimax / to-pi / to-gemini / to-cline。
人在回路：给全自动装刹车
这个工具的典型用法是对任意 AI Agent 说一句"同步会话"。全自动写入没有刹车是危险的，所以同步前强制两道确认：
── 确认 1/2 · 同步哪些来源区 ─────────────
1) 全部（19 家） ← 回车默认
2) zcode 3) hermes 4) codex ...
── 确认 2/2 · 同步多少数据 ─────────────
1) 仅增量 ← 回车默认
2) 最近 7 天 / 3) 最近 30 天 / 4) 全部历史（需二次确认）
规则：交互终端弹菜单；Agent 代跑（非交互）必须显式写参数，参数即确认，缺参直接拒绝。历史全量另有二次拦截：交互弹 y/N，非交互必须拿到人给的 --confirm-history。Agent 绝不自行拍板全量。
开发中踩过的坑
十九家存储没有一家有官方文档，全部真库逆向。挑几个有代表性的：
1. codex 的 resume 列表不扫文件
rollout 文件落位了，codex resume 的选择器里就是看不到。翻库发现 0.137 的列表读 ~/.codex/state_5.sqlite 的 threads 索引表，每行带 rollout_path 指针。写入器落盘时同步登记索引（cwd 要 \\?\ 前缀、时间戳是字符串秒），问题解决。
2. hermes 列表显示"0条消息"
消息行明明在库里、格式也对。取证发现列表 UI 读的是 sessions 表的计数列（message_count / tool_call_count / source），不是去 count 消息表。写入器创建时填、追加后实测刷新。
3. opencode 桌面版是事件溯源渲染
最惨烈的一战，连剥六层 schema 校验才让会话点得开：
{messageID} → 缺 event/event_sequence 事件流（1.18 新增，桌面回放事件渲染）
Missing info.agent → 消息必须是完整原生形状（user 带 agent/model/summary…）
Missing parts[0].time → part 补 time{start,end}
Expected object → 工具参数必须是对象不是 JSON 字符串
Missing state.title → tool state 对齐原生六键
Expected ToolState → ToolState 是按 status 的可辨识联合，failed 分支形状不同
六层全部固化进写入器和回归断言。agentctxsync 的 1.17 写入配方在 1.18 面前全军覆没。逆向结论要带版本号。
4. Claude Code 的 thinking 块不能写
CC 自家的 thinking 块带 signature 校验，外来块有整条消息被拒的风险。写入器跳过 thinking，文本与工具往返完整保留。
5. zcode：一个反例
写入方向实现过，246 个会话导入"成功"，然后旧会话时间错乱、部分渲染空白。清理善后备份齐全，方向整体移除，zcode 永久只读。不是所有门都该推开，活库写入的验证成本远超收益时，放弃是工程判断。
6. gemini 的回复是"碎片"，还会被自己删掉
模型回复落盘不是完整的 {text} 块，而是流式字符串碎片数组，"是"、"的"、"，"一个一存。更狠的是 Gemini CLI 启动时会清理"过期"会话：导入时照搬了源会话的原始时间戳，第二天打开 Gemini，导入的会话被它自己当垃圾删了。两处都修了，碎片统一拼接，时间戳一律写"现在"，retention 关掉。
7. opencode 的跨家重复"双胞胎"
防环清单上线前写入 opencode 的会话没有登记，读取器认不出是导入 → 同步 opencode→dsh 时被当原生带出 → dsh 里出现 [zcode] SonarQube 和 [opencode] SonarQube 双胞胎。修复靠反推法：用写入器的确定性 uuid5 对全源会话重铸 id，命中库里未标记的就是老写入，自动补登记。这步现在做进了 ass doctor，每次体检自动跑。
完整的 62 条踩坑记录在仓库 docs/pitfalls.md，按家分组"坑 → 现象 → 修复"。
技术栈
| 组件 | 选型 | 说明 |
|---|---|---|
| 语言 | Python 3.10+ | 唯一第三方依赖 zstandard（dsh 压缩格式） |
| 幂等 | uuid5 确定性 id | 同一源会话重复/跨模式导入不重复 |
| 存储 | 无服务、纯本地 | 规范库就是一个目录，零守护进程 |
| 仪表盘 | 标准库 HTTP + tkinter | ass web 可视化/导出/目录绑定，仅绑 127.0.0.1 |
| 自修复 | ass doctor | 依赖自动装、增量基准备份重建、skills 桥接/命令自愈、防环清单反推审计 |
| 备份 | IR 快照 + 原始库快照 | 会话级快照可跨家幂等还原；加密读不动的源（如 trae CN）自动转整库文件留档 |
| 防环 | uuid5 版本位 + 旁路清单 + import-* 前缀 | 导入的会话永不回流成环；标题一律带 [来源] 前缀 |
| 测试 | 194 项沙箱自检 + 48 格真库矩阵回归 | 每个修过的 bug 都变成回归断言 |
为什么开源
这个项目 90% 的代码是和 AI 结对写出来的，我做决策、取证、验收，它做实现和初诊。逆向私有格式这件事没有捷径，但真库取证加 AI 结对，一家一家啃下来是可能的。
与其躺在我的机器里吃灰，不如开源出来，给同样几个工具混着用的人。
GitHub：github.com/Chendestiny…
觉得有用给个 Star 就是最大的支持。
