造了个 AI 编程工具的统一入口：kshell（Go + Wails，开源）

一个轻量级 agent 工作台：自动发现你本机装的所有 AI 编程 CLI，把它们的散落会话、工作区、终端和远程服务器收进一个界面。 Go 1.23+ / Wails v2 / React 19 / Bubbletea，Windows · macOS · Linux，MIT 协议。

一、先说说我为什么想造这个工具

不知道你有没有这种感觉------过去一年我装了太多 AI 编程工具。

Claude Code、Codex CLI、Gemini CLI、Cursor、OpenCode，还有些公司内部封装的。它们每一个都有自己的脾气：

• 会话记录散落在完全不同的目录，用完全不同的格式存着；
• 有的存 JSONL，有的干脆存进 SQLite；
• 想恢复一个三天前的会话？先猜猜它写到哪个文件里去了；
• 我有 12 个项目在跑不同的工具，切一次要开三个终端窗口。

某天我算了一下：我花在"找会话"上的时间，比花在"写代码"上的还多。

市面上的工具要么是"再实现一个 AI 对话协议"，要么是绑定死一个生态。而我想要的其实特别朴素：

别再让我记路径了。扫我的磁盘，把所有工具的会话列出来，让我一键回去。

于是有了 kshell。

二、核心设计：发现 → 选择 → 交付

kshell 的定位只有三个动词：

发现（Discovery）  →  扫磁盘，找出已装工具 + 工作区 + 历史会话
选择（Selection）  →  统一的列表 / 网格视图，跨工具横向比较
交付（Delivery）   →  把会话交还给原生 CLI 继续跑

第三步是刻意的设计选择，值得展开讲。

为什么不自己实现对话协议？

Claude Code 有自己的 ACP、Codex 有自己的 resume 参数、Cursor 又是一套。每家都在长出自己的方言。

kshell 的立场是：不重复实现对话能力，把会话交还给工具自己的 CLI。

• 终端路径 ：点击会话 → 拼出 claude --resume <id> 或 codex resume <id>，扔进 ConPTY/PTY 跑原生交互界面，退出后回到 kshell；
• 聊天路径（ACP） ：对已接入 ACP 的工具（Claude Code、Cursor、CodeBuddy）走 Agent Client Protocol，在窗口内直接对话；工具不支持 ACP 时自动回退到终端。

这样做的收益是显而易见的：kshell 不追着各家协议跑，工具升级了它大概率还活着。而且工具本身的新特性（新的 diff 算法、新的工具调用能力）你第一时间就能用上。

三、架构：一条单向的数据流

providers  →  discovery  →  ui / desktop
（识别工具、解析会话）  （扫描与缓存）  （呈现）

整个后端只有 217 个 Go 文件、约 3.4 万行代码，模块划分很克制：

模块	职责	代码量
internal/desktop	Wails 绑定层（58 个文件，桌面端最大头）	~10000 行
internal/providers	各工具适配 + Provider 接口	~5300 行
internal/discovery	扫描与缓存	~2400 行
internal/terminal	ConPTY/PTY 终端后端	~2000 行
internal/remote	SSH 连接存储与候选扫描	~1900 行
internal/ui	Bubbletea TUI 三视图	~2500 行
internal/acp / internal/chat	Agent Client Protocol 客户端	~2600 行

3.1 Provider 接口：加新工具不用改代码

这是整个项目最想拿出来讲的设计。

type Provider interface {
    ID() string
    DisplayName() string
    DetectSpec(home string) DetectSpec
    SessionRoots(home string) []string
    SessionFilePattern() string
    ParseSession(path string, head []byte) (*Session, error)
    NewSessionCmd(ws string, bin string) Launch
    ResumeCmd(s Session, bin string) Launch
}

实现这个接口，你的工具就被 kshell 纳管了。但内置四工具是硬编码的------因为每家的检测与 resume 都有历史包袱，配置表达不了。

真正有意思的是那些可选接口，它们解决了"文件遍历这套抽象不够用"的现实：

// 工具的 TUI 要跟随 kshell 的浅/深主题
type Themer interface { ThemeArgs(...) ([]string, map[string]string, string) }

// 「会话不在文件里」------比如 opencode 把会话存进了 SQLite
type SessionEnumerator interface {
    EnumerateSessions(home string, bin string) ([]Session, error)
}

// glob 盖不住的深层文件，比如 CodeBuddy 的 subagents/*.jsonl
type PathMatcher interface {
    MatchSessionRel(rel string) bool
}

SessionEnumerator 是我最满意的一个。 opencode 新版把 JSON 会话迁进了 ~/.local/share/opencode/opencode.db，文件遍历这套假设直接失效。kshell 的处理不是加特例，而是让 provider 自己声明"我能枚举"：

opencodeSessionsSQL = `select id, directory as cwd, title, time_created as created, time_updated as updated from session where parent_id is null and time_archived is null order by time_updated desc`

⚠️ 这里有个坑，我自己也踩了：这条 SQL 必须写成单行。 Windows 上 opencode 是 npm 的 .cmd 包装脚本，命令行最终交给 cmd.exe 重解析，多行 SQL 会在换行处被截断------症状是"一条会话都查不出来"，而且日志里看不出任何异常。代码注释里已经写死了这条规矩：

// 必须写成**单行**：... 换行只影响可读性，绝不要为了排版拆行。

3.2 YAML 声明新工具：零代码扩展

不想写 Go？直接在 ~/.kshell/providers.yaml 里声明：

providers:
  - id: mytool
    name: MyTool
    detect:
      command: mytool
      dirs: ["~/.mytool"]
    sessions:
      glob: ~/.mytool/projects/*/*.jsonl
      format: jsonl
    fields:
      cwd: cwd
      id: sessionId
      timestamp: timestamp
      title: message.content
    resume:
      args: ["--resume", "{id}"]
    verified: false          # 声明式配置一律标未实测

MergeProviders 合并时内置同 ID 优先 ------用户配置可以扩展，但不能篡改内置工具的行为。verified: false 这个字段是刻意的：声明式配置没经过实测，UI 上会明确标出，避免用户误以为和内置工具一样可靠。

3.3 只读文件头部：性能上的关键决策

Claude Code / Codex 的 JSONL 会话动辄好几 MB。kshell 全程只读文件头部字节，各家上限不同：

• codex：256 KB
• gemini：2 MB

解析出的元数据（ID、cwd、时间、标题）对这个量级完全够用。整读多 MB 的 JSONL 是纯粹的浪费。

3.4 缓存：mtime + size 双重门控

每次刷新都全盘解析 JSONL 是不可接受的。kshell 的两级缓存都用 mtime + size 双因子判定是否复用：

// internal/discovery/index.go:79
return ok && entry.MTime == mtime && entry.Size == size

为什么两个因子都要？只比 mtime 会漏掉"同一时间戳内被等量改写"的情况；只比 size 会漏掉"内容变了但长度没变"。两者都相同才认为文件未变。

再往上还有一层 snapshot.json 支撑秒开 + 后台刷新------用户看到的是上次的完整结果，同时后台在重扫，扫完再原子替换。感知延迟基本为零。

3.5 终端退出：drain 机制与那 40% 的输出

这是踩过坑才有的代码。

桌面端关闭终端时，直接 Close() ConPTY 会丢掉约 40% 的尾部输出------agent 刚吐完一整段回复，你一关窗口，最后几句就没了。

正确做法是 drain：

延迟 80--500ms → 持续收取剩余输出 → 输出排空后再关闭

延迟时长的逻辑是：既要给子进程留出写完缓冲区的时间，又不能让"关终端"这个操作感觉卡顿。

顺便区分两个容易混淆的东西：

• drain 是"关闭终端时排空缓冲区"；
• ~/.kshell/exit.signal 是"桌面版轮询该文件优雅退出"。

后者是给构建脚本用的，而且构建过程不会退出正在运行的实例------你可以一边用着旧版本一边重新构建。

四、SSH：安全上的几条硬规矩

远程管理这块我定了很明确的底线：

• 始终走系统 ssh 二进制 ，加 -o BatchMode=yes，复用 ~/.ssh/config、ssh-agent、ProxyJump、known_hosts；
• 不传密码，不绕过主机密钥校验；
• 私钥只存路径 ，绝不把密钥内容落盘到 connections.yaml。

候选扫描还做了置信度分级：

来源	置信度
~/.ssh/config	高
.env* / Spring application*.yml	中
docker-compose / Makefile / deploy*.sh / ansible	低
README 等文档	低

低置信度候选默认不勾选 ，必须人工确认后才写入 connections.yaml。自动猜出来的服务器直接给你连上，等于把"连错机器执行 rm -rf"的风险前置到扫描阶段了。

五、两个入口，无模式开关

入口	技术	产物
桌面端	Wails v2 + React 19 + xterm	kshell-desktop
TUI	Bubbletea	kshell

TUI 的定位不是"降级方案"，而是键盘流的老手会真的喜欢的形态：

┌ kshell  ●claude ●codex ○gemini        ws: ~/projects/demo ─┐
│ [Sessions] Files  Remote                    (Tab 切换)      │
├──────────────────────┬──────────────────────────────────────┤
│ WORKSPACES           │ PREVIEW                              │
│ ▸ demo          12   │ 会话摘要 / 文件内容 / ssh 输出        │
├──────────────────────┴──────────────────────────────────────┤
│ ↑↓ 移动  ⏎ 进入  / 搜索  n 新建  r 重扫  ? 帮助  q 退出     │
└─────────────────────────────────────────────────────────────┘

n 新建会话、r 重新扫描、/ 搜索过滤、? 帮助------全键盘可达。

六、目前支持的工具

工具	会话存储	终端 resume	ACP 聊天
Claude Code	~/.claude/projects/<slug>/*.jsonl	已验证	claude-agent-acp
Codex CLI	~/.codex/sessions/**/*.jsonl	已验证	走终端
Cursor	~/.cursor/projects/*/agent-transcripts/	内置	cursor-acp
CodeBuddy	~/.codebuddy/projects/*/*.jsonl	已验证	CLI --acp
Gemini CLI	~/.gemini/tmp/	推断，未实测	走终端
OpenCode	SQLite（opencode db ... --format json）	内置（--session）	走终端

⚠️ 表格里的"已验证"和"推断，未实测"是有意区分的。 工具升级会改会话格式，我不敢替厂商打包票。凡是我本机没真实跑过的，都老实标出来。

检测上的一个坑：Cursor 的 shim 会被删光

Cursor 官方更新器会周期性清空安装目录里的入口 shim，只留下 node.exe + index.js 本体。这时候在 PATH 上 Detect 必然落空。

kshell 的兜底策略是：在各个 InstallDirs 里找 node.exe 与主脚本都存活的组合：

// shim 全部落空时，Detect 会在 InstallDirs 各目录里找
// node.exe 与主脚本存活的组合作为最后兜底（Source=node-entry）。
NodeEntryScript string

于是 Detection 里多了一个 BinArgs 来承载入口前缀参数：

// BinPath 指向 node.exe 时为 [主脚本名]，普通可执行文件为 nil。
// 启动与版本探测都须先拼上这组参数。
BinArgs []string

这里又踩过一次坑：最初版本没拼 BinArgs，子进程继承了别的 cwd，找不到主脚本。所以启动和版本探测都必须先拼上这组参数 ------现在有回归测试盯着（TestDetectAllCarriesBinArgs，还特意隔离了 PATH 以免依赖本机环境）。

七、前端：一个 Store + 常驻 xterm

前端架构刻意做得很薄：

• 单一 Zustand store （state/store.ts），页签状态持久化到 localStorage；
• 所有后端调用经 lib/api.ts → 生成的 window.go.desktop.App；
• 后端推送经 EventsOn：terminal:data / scan:done / chat:update。

有一个性能细节值得单独说：xterm 实例常驻挂载（terminalRegistry），切页签只隐藏不销毁。

早期版本切走终端页签就销毁 xterm，切回来时缓冲区、滚动位置、ANSI 状态全丢，重建还有闪烁。改成常驻挂载后，切页签是零成本操作。

前端 106 个 TS/TSX 文件，106 个测试配套------npm test 走 vitest jsdom 环境。

八、工程实践

测试：206 个 _test.go

Go 侧 206 个测试文件，覆盖重点在容易回归的地方：会话解析、路径匹配、缓存门控、忽略规则继承。

go build ./...
go vet ./...
go test ./... -count=1

前端另跑 npm test / npm run build。

顺手修掉的两个真 bug

继承忽略（inherited ignore） ：gitignore 命中的是目录时，其下的子项也要继承忽略状态。第一版只判断直接命中，导致"文件树里显示了本该隐藏的文件"。

嵌套 git 的中间层徽章 ：仓库套仓库时，中间那层 .git 目录应该显式标出来------只标最外层会让人误以为整棵子树归属同一个仓库。

这两个 bug 都不是逻辑复杂，而是测试没覆盖到组合场景。修完之后补了回归用例。

构建

# TUI → dist\kshell.exe
.\build.ps1

# 桌面端 → dist\kshell-desktop.exe（自动构建 frontend）
.\build.ps1 -Desktop

build.ps1 -Desktop 不会请求正在运行的旧实例退出 ，构建期间你可以继续用旧版本。dist 拷贝若因 kshell-desktop.exe 被占用失败，脚本会提示你从托盘退出后重试。

版本

目前 v0.1.3。232 次提交，MIT 协议。

九、明确不做的事

先说清楚不做什么，比列功能更有诚意：

• ❌ SFTP / 文件传输 ------系统 scp 就够
• ❌ 端口转发 ------ssh -L 是成熟方案
• ❌ 云同步------会话文件本机就有，同步等于制造第二份真相
• ❌ 再实现一遍各家对话协议------这是最大的技术债来源，绕开

十、怎么用

下载：GitHub Releases 或 GitCode Releases，桌面端还可以在「设置 → 通用 → 关于」里检查更新，升级优先走 GitCode 国内源。

从源码构建：

git clone https://github.com/kaiys202212/kshell.git
cd kshell
go install github.com/wailsapp/wails/v2/cmd/wails@latest   # 桌面端需要

.\build.ps1            # TUI
.\build.ps1 -Desktop   # 桌面端

写在最后

这个项目从一个具体的痛点长出来：AI 编程工具越多，"找回自己的会话"就越难。

我没有试图造一个更强的 AI 编程工具，而是造了一个中立的入口。谁家工具好用就用谁，kshell 只负责让你能看见它们、方便地回到它们。

如果你也在同时用好几个 AI CLI，欢迎来试，也欢迎提 issue------尤其是新的工具适配，那是最容易一起把事情做好的地方。

仓库地址 ：github.com/kaiys202212...

---