Beans 架构全景图:Go CLI、Bubbletea TUI 与 SvelteKit 前端如何协作?完整指南
Beans 架构全景图:Go CLI、Bubbletea TUI 与 SvelteKit 前端如何协作?完整指南
Beans 是一款将任务以 Markdown 文件形式存在代码仓库旁的扁平文件 issue tracker(问题追踪器)。它最特别的地方在于:同一套 Go 代码,既输出命令行工具 beans,又能启动 Bubbletea 打造的终端 TUI,还能以 Web 服务身份托管一个 SvelteKit 前端。这篇文章带你拆解这三者如何围绕同一个数据内核协作,看完你会对它的整体架构一目了然。🌰
一、架构总览:三个入口,一个数据内核
Beans 的架构可以用"一个内核 + 三个外壳"来概括:
| 组件 | 入口 | 技术栈 | 面向场景 |
|---|---|---|---|
| CLI | beans 命令 |
Go + cobra | 人类手动操作、AI 编码代理调用 |
| TUI | beans tui 命令 |
Go + Bubbletea | 终端内浏览与管理任务 |
| Web | beans serve 启动 |
Go + Gin + SvelteKit + GraphQL | 浏览器看板、Agent 对话、工作区管理 |
无论哪个入口,读写的数据都是项目根目录下 .beans/ 中的 Markdown 文件。核心状态管理集中在 pkg/beancore/core.go,它提供线程安全的内存存储 + 文件系统持久化 + 文件监听:启动时把全部 Bean 读入内存,修改后落盘,并通过 fsnotify 监听外部变化(比如你用编辑器手改了文件),实现"文件即数据库"。
二、Go CLI:人类与 AI 代理共享的命令入口
CLI 是 Beans 使用最广泛的界面。入口只有寥寥数行,见 cmd/beans/main.go:它创建根命令、注册核心子命令并执行。
常用命令包括:
beans init:初始化.beans/数据目录与.beans.yml配置beans list/beans show:列出、查看任务beans create/beans update/beans archive:增删改与归档beans prime:向 AI 编码代理输出项目任务上下文
值得注意的设计:CLI 并不"直连文件",而是复用与 Web 端相同的 GraphQL 数据访问层 pkg/beangraph/resolver.go 中的 CoreResolver。这意味着三种界面共享同一套校验逻辑(类型层级、循环引用、ETag 并发控制),行为天然一致。
三、Bubbletea TUI:终端里的图形化任务看板
想离开纯文本?执行 beans tui(入口见 cmd/beans-tui/main.go)即可进入基于 Bubbletea 的交互式界面,实现位于 internal/tui/tui.go。
它遵循 Bubbletea 的 Model-Update-View 事件循环:
- 列表视图 + 详情视图:键盘驱动,支持
g t等按键和弦(key chord)快速跳转 - 多列布局:终端宽度 ≥ 120 列时自动切换双栏,右侧为 Markdown 预览
- 选择器面板:标签、状态、类型、父任务、阻塞关系一应俱全
- 实时刷新:订阅 beancore 的文件监听事件,外部文件一改动,界面即时更新
TUI 内部同样持有 CoreResolver 实例做数据操作,与 CLI 完全同源。
四、SvelteKit 前端:GraphQL 驱动的控制台
执行 beans serve 后(实现见 internal/commands/serve.go),Go 程序变身 Web 服务器:
- GraphQL API:Gin 路由将
/api/graphql交给 gqlgen 生成的可执行 schema,定义在 internal/graph/schema.graphqls,支持查询、变更与订阅 - WebSocket 推送:通过
graphql-transport-ws协议,Bean 变化、Agent 状态、工作区 Git 状态都会实时推送给浏览器 - 托管前端:SvelteKit 构建产物在编译期被嵌入 Go 二进制(internal/web/embed.go 中的
//go:embed dist/*),因此单文件即可部署
前端 frontend/src/lib/graphqlClient.ts 使用 urql + graphql-ws:普通请求走 HTTP,订阅自动升级走 WebSocket,断线指数退避重连。页面上能看到的看板(frontend/src/routes/planning/board/+page.svelte)、规划视图、Agent 聊天面板、diff 审查与终端,全部由这条订阅链路实时驱动。
五、数据一致性:文件监听 + 订阅如何打通三方
三条界面看似独立,数据却永远一致,关键在于这个闭环:
- 写:任何界面(CLI 命令、TUI 按键、Web 按钮)最终都调用
beancore.Core写回.beans/*.md - 感知:beancore 的文件监听器捕获磁盘变化(无论来自哪个入口,甚至来自你手动编辑)
- 推:Web 端通过 GraphQL 订阅经 WebSocket 把变更事件推给 SvelteKit 前端;TUI 通过内部消息通道刷新
- 并发:更新携带 ETag,检测冲突避免覆盖
一句话总结:Markdown 文件是唯一事实源,beancore 是唯一守门人,GraphQL 是唯一广播站。
六、目录导航:快速定位关键模块
| 想了解 | 看这里 |
|---|---|
| 数据内核与持久化 | pkg/beancore/ |
| CLI 命令实现 | internal/commands/ |
| TUI 界面模型 | internal/tui/ |
| GraphQL 模式与解析器 | internal/graph/、pkg/beangraph/ |
| SvelteKit 前端组件 | frontend/src/lib/components/ |
| Web 嵌入与端口分配 | internal/web/embed.go、internal/portalloc/ |
结语
Beans 的架构启示在于:它没有为 CLI、TUI、Web 各写一套存储逻辑,而是把状态收敛到 beancore 这个扁平文件内核,让 GraphQL 层同时服务人类界面与 AI 代理。无论是新手想了解"一个 Go 项目如何长出一个 Web 前端",还是开发者想借鉴多端数据同步方案,Beans 都值得一读。🚀