不只命令行：我把跨 Agent 会话同步做成了桌面应用

应用名：Agent Session Sync （桌面版）

当前版本：1.3.2

下载：GitHub Releases v1.3.2

同源 CLI / MCP 包：cross-agent-sync（命令 ass）

上一篇掘金写的是 npm 包 / MCP：换 Claude、Codex、Cursor 时怎么把上下文搬过去。

这篇只讲桌面应用：同样的本机会话数据，换成可视化界面------看占用、按项目翻历史、点开会话、可选清理。

文中截图来自本机 1.3.2 构建；若你发文时要换图，可直接替换 docs/desktop-shots/ 下对应文件，或把文中图片换成你自己的。

一、需求：为什么还要做一个 App？

命令行和 MCP 解决的是「在 Agent 对话里接上一次」。日常还有另一类问题，CLI 不够顺手：

场景	痛点
本机装了很多 Agent	不知道谁占了多少盘、哪个项目聊得最多
想回看某次提问	要记 `ass list` / `ass inputs`，路径和引用麻烦
磁盘告急	Cursor / Codex 会话目录涨到 GB 级，想安全清掉旧会话
给同事演示	希望打开窗口就能看，而不是敲一串命令
扩展非内置 Agent	想改 `customAgents`，又不想手改 JSON

所以桌面版的目标很明确：

看得见：本机 Agent、会话数、磁盘占用、按项目聚合。
点得开：点进项目 → 点开会话 → 看用户输入 / 全部信息 / 智能体结论。
动得少 ：对 Agent 原始会话只读；写操作只进本工具自己的目录，且每次确认。
清得掉（可选）：文件型会话可移到废纸篓，不清共享 SQLite 库。

一句话：CLI/MCP 负责「交接」；桌面 App 负责「巡检与回看」。

二、设计

2.1 和 CLI 的关系

桌面端不重新实现一套解析器。架构是：

text 复制代码

Electron 窗口（原生 HTML/CSS/JS）
        │  preload 窄 API
        ▼
主进程 IPC + 短时缓存
        │ ELECTRON_RUN_AS_NODE=1
        ▼
子进程跑 runtime/cli.js（和 npm 包同一套 adapters）
        │ 只消费 JSON
        ▼
本机各 Agent 会话目录（只读）

取舍：

不 import dist：配置路径在模块加载时就定死，子进程最干净。
零前端框架：界面是 vanilla UI，打包体积和心智负担都小。
Electron + electron-builder：本机无完整 Xcode / 无 Rust 时，可比 SwiftUI、Tauri 更快落地；macOS arm64 DMG + Windows x64 安装包/zip。

2.2 信息架构（五个入口）

页	干什么
概览	KPI + Agent 数据源表 + 会话数 / 磁盘占用图
项目	指定仓库：会话列表、任务、项目笔记、右侧会话抽屉
全部项目	卡片浏览本机有会话的仓库，可改显示名
清理	按 Agent 选文件型会话，移到废纸篓
设置	路径 / 版本 / 扩展 Agent（customAgents） / 只读说明

2.3 几条硬原则

源数据只读、可自证

不改 Claude / Codex / Cursor 等会话文件；写决策、任务、别名只进

~/.local/share/agent-session-sync。
建议 ≠ 授权；工具过程 ≠ 结论

和 CLI 一致：笔记有授权/核对概念；抽屉里智能体回答会藏掉 ▸ Bash: 等工具轮，尽量只留结论。
清理有边界

只清「一个文件/目录 = 一条会话」的来源；Cursor / OpenCode / Trae / 灵码等共享 SQLite 不在桌面里删------避免误伤整库。
显示名只影响本 App

项目/会话的 ✎ 写 desktop-aliases.json，不改磁盘目录名，也不改 Agent 原生标题。

三、界面一览

3.1 概览

本机有哪些 Agent、是否可读、MCP 是否已接入、各占多少盘。下方有会话数分布与磁盘占用（两者按同一 Agent 顺序对齐）。

若图里还在「正在扫描...」，刷新等几秒即可；Cursor 首次全量扫描会慢一些。

3.2 全部项目

按仓库卡片浏览，带 Agent 徽章；点进卡片进入「项目」页。可用 ✎ 设显示名。

3.3 项目

选中一个仓库后：会话 / 任务 / 决策数量，会话表，下方任务与项目笔记。点击某条会话，右侧弹出抽屉。

会话抽屉：

Tab：用户输入 · 全部信息 · 智能体回答（摘要 / 全文）
每 Tab 可搜索，命中高亮
最近消息在上；助手默认折到两行
智能体侧过滤工具/思考过程，优先看结论

3.4 清理

选 Agent → 列出可清理会话 → 单条或全部清理（进废纸篓，可恢复）。

3.5 设置

路径、版本，以及 扩展 Agent ：用表单增删改 customAgents，写入

~/.config/agent-session-sync/config.json，与 CLI 共用。弹窗高度随窗口自适应，底部按钮始终可见。

四、怎么用

4.1 下载与安装

从 Releases · v1.3.2 下载：

平台	文件
macOS Apple Silicon	`Agent-Session-Sync-1.3.2-arm64.dmg`（或 `.zip`）
Windows x64	`Agent-Session-Sync-1.3.2-setup-x64.exe`（或免安装 zip）

macOS（未做 Developer ID 签名）

打开 DMG，拖到「应用程序」
推出 DMG ，在「应用程序」里 右键 → 打开
若提示无法验证：系统设置 → 隐私与安全性 →「仍要打开」
若误报「已损坏」：xattr -cr "/Applications/Agent Session Sync.app" 后再右键打开

详细说明见仓库 desktop/安装说明.md。

Windows

未签名，SmartScreen 选「更多信息 → 仍要运行」即可。

4.2 推荐操作路径

打开 App → 概览，点刷新，看本机 Agent 与磁盘。
全部项目 找目标仓库，点进项目。
点某条会话，右侧切换「用户输入 / 全部信息 / 智能体回答」，需要时搜索关键字。
磁盘紧了 → 清理，只清确认过的文件型会话；清空废纸篓后才真正腾空间。
有非内置 Agent → 设置 → 扩展 Agent 按 jsonl / json / sqlite 填映射；保存后回概览刷新。

4.3 和 CLI / MCP 怎么配合

你想...	用谁
在对话里说「继续某某任务」自动接上下文	装 MCP：`ass install`，在 Claude / Codex 等里用
扫一眼本机、回看历史、清磁盘	桌面 App
脚本 / CI / 终端里批量交接	`ass brief` / `ass inputs` / `ass task`

数据是同一套：App 读的也是本机会话；笔记、任务写在同一数据目录。

桌面 App 不会替你跑 ass install（避免把 Electron 路径写进 MCP 配置）。

五、设计之外的一点体会

做桌面版之前，以为难点是「把 CLI 图画出来」。真正磨人的是：

扫描成本 ：Cursor 库很大，首屏不能干等 15s------所以有 --fast、缓存、后台预热。
计数口径 ：卡片写 31、点进去只有 9，往往是默认 limit=15；桌面端必须显式拉全量再用 keys 对齐。
展示诚实：工具过程刷屏会淹没结论；「已损坏」多半是签名时机错了（必须 afterPack 再进 DMG）。

这些和 MCP 包是同一套产品观：能少猜就少猜，读不到就明说，写之前先确认。

六、相关链接

桌面安装包：github.com/lhbDesign/c...
源码仓库：github.com/lhbDesign/c...
npm CLI/MCP：www.npmjs.com/package/cro...
上一篇（MCP/CLI 向）：同仓库 掘金-跨Agent会话同步实践.md（若你本地有）