Beans 架构全景图:Go CLI、Bubbletea TUI 与 SvelteKit 前端如何协作?完整指南

原创2026-10-22 10:51:071,841 阅读

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 服务器:

  1. GraphQL API:Gin 路由将 /api/graphql 交给 gqlgen 生成的可执行 schema,定义在 internal/graph/schema.graphqls,支持查询、变更与订阅
  2. WebSocket 推送:通过 graphql-transport-ws 协议,Bean 变化、Agent 状态、工作区 Git 状态都会实时推送给浏览器
  3. 托管前端: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 审查与终端,全部由这条订阅链路实时驱动。

五、数据一致性:文件监听 + 订阅如何打通三方

三条界面看似独立,数据却永远一致,关键在于这个闭环:

  1. 写:任何界面(CLI 命令、TUI 按键、Web 按钮)最终都调用 beancore.Core 写回 .beans/*.md
  2. 感知:beancore 的文件监听器捕获磁盘变化(无论来自哪个入口,甚至来自你手动编辑)
  3. 推:Web 端通过 GraphQL 订阅经 WebSocket 把变更事件推给 SvelteKit 前端;TUI 通过内部消息通道刷新
  4. 并发:更新携带 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 都值得一读。🚀

登录后查看全文
beans