【免费下载链接】beansA CLI-based, flat-file issue tracker for humans and robots. 项目地址https://gitcode.com/gh_mirrors/bean/beans点击查看免费下载Beans 是一款基于 CLI 的平文件 Issue 追踪工具支持人类与 AI 编码代理共同管理任务。它的全文搜索功能背后是一套基于 Bleve 内存索引引擎 BM25 相关性评分算法的轻量级实现无需数据库即可实现毫秒级检索。本文带你快速看懂 Beans 全文搜索的完整原理。一、整体架构平文件数据 内存索引Beans 把所有任务称为 bean存储为.beans/目录下的 Markdown 文件。为了支持快速搜索它在运行时维护一份内存索引核心代码位于 internal/search/index.go// Index wraps a Bleve in-memory index for searching beans. type Index struct { index bleve.Index }关键设计选择设计点实现方式好处存储介质bleve.NewMemOnly()纯内存索引零磁盘 I/O启动快数据来源.beans/目录下的 Markdown 文件数据即文档人机器都能读评分算法BM25Bleve v2.5.0排序比 TF-IDF 更符合直觉初始化策略首次搜索时懒加载不影响冷启动速度索引只关心每个 bean 的四个字段type beanDocument struct { ID string json:id Slug string json:slug Title string json:title Body string json:body }二、索引映射standard 分词器与字段区分创建索引时Beans 为不同字段设置了不同的 mapping见 internal/search/index.go#L35-L64idkeyword类型——精确存储、不参与分词因为 ID 是检索结果的主键slug/title/bodytext类型使用standard标准分词器会做小写化、去标点、按词切分等处理这是全文搜索能理解自然语言的基础。同时显式关闭了动态字段IndexDynamic false保证索引结构紧凑、行为可预测。三、BM25 评分算法为什么排序更准Beans 在索引映射中显式启用了 BM25 评分模型// Use BM25 scoring algorithm (available in Bleve v2.5.0) // BM25 provides better relevance ranking than TF-IDF, especially for: // - Handling term frequency saturation (repeated terms dont over-boost) // - Normalizing for document length (short docs arent unfairly penalized) indexMapping.ScoringModel bm25BM25 相比传统 TF-IDF 有两个核心优势词频饱和term frequency saturation一个词在文档中出现 3 次和 30 次相关性并不会成倍增长。BM25 的 $k_1$ 参数让词频收益递减避免堆砌关键词的文档霸占榜首文档长度归一化短文档不会因为词少而被 TF-IDF 不公平地压低排名长文档也不会因为词多而占便宜。$b$ 参数控制长度惩罚的强度。直观地说搜索 login 时标题里精准命中一次的 bean会稳定排在一个 body 里反复出现 login 五次的 bean 前面——这更符合人类对相关的预期。 BM25 支持从 Bleve v2.5.0 起可用Beans 依赖的是 v2.5.6见 go.mod处于稳定支持区间。四、索引的生命周期懒加载与增量同步索引并非启动时一次性构建而是跟随 bean 数据全生命周期同步。核心逻辑在 pkg/beancore/core.go 中① 懒初始化——首次调用Core.Search()时才创建索引并把已有 bean 批量灌入// ensureSearchIndexLocked initializes the in-memory search index if not already created. func (c *Core) ensureSearchIndexLocked() error { ... if err : c.searchIndex.IndexBeans(allBeans); err ! nil { return fmt.Errorf(populating search index: %w, err) } ... }批量写入使用 Bleve 的BatchAPI比逐条Index更高效见 internal/search/index.go#L122-L137。② 增量同步——后续每个数据变更点都会顺带维护索引均为 best-effort失败仅告警不阻塞主流程触发场景位置索引操作新建 beanCore.CreateIndexBean更新 beanCore.UpdateIndexBean覆盖旧版本删除 beanCore.DeleteDeleteBean磁盘文件外部变更pkg/beancore/watcher.go 文件监听IndexBean/DeleteBean全量重载Core.Loadcore.go关闭旧索引并重建③ 搜索时释放锁Bleve 本身线程安全因此Search只短暂持锁取出索引引用实际检索在锁外进行避免阻塞其他读写。五、搜索入口Bleve 查询语法与 GraphQL 过滤器Index.Search直接采用Bleve 查询字符串语法internal/search/index.go#L92-L120query : bleve.NewQueryStringQuery(queryStr)这意味着用户在查询框里可以写语法示例含义普通词login精确词匹配模糊匹配login~、login~21~2 个编辑距离通配符auth*前缀匹配短语user login连续短语匹配布尔user AND password、a OR b组合条件字段限定title:login、body:auth只在指定字段内搜请求返回时只取id字段searchRequest.Fields []string{id}默认上限DefaultSearchLimit 1000 条拿到 ID 后再回查内存中的 bean map保证结果与最新数据一致。对外暴露的入口是 GraphQLbeans查询的search过滤参数其注释详细列出了上述语法见 internal/graph/schema.graphqls 与 pkg/beangraph/model/models_gen.go#L122-L135。解析链路非常短GraphQL filter.search └─ CoreResolver.Beans (pkg/beangraph/queries.go) └─ Core.Search(query) └─ search.Index.Search → Bleve BM25 打分排序如果指定了search参数就以搜索结果作为候选集起点否则使用全部 bean再叠加状态、类型等过滤器。六、测试用例里的搜索行为internal/search/index_test.go 和 pkg/beancore/search_test.go 覆盖了主要行为几个典型例子标题优先三条 bean 中只有aaa1的标题含 AuthenticationSearch(Authentication)精准返回[aaa1]正文命中Search(JWT)通过 body 内容找到目标 beanslug 参与搜索Search(auth)命中 slug 为auth-feature的 bean更新即生效标题从 Original Title 改为 Updated Title 后旧词搜不到、新词能搜到通配符Search(auth*)同时命中 Authentication 与 Authorization不区分词干注意区分于 Automation懒加载先Create再Search首次搜索会自动索引已有数据外部变更重建直接手写.md文件后调用Load()索引被重建并能搜到新文件内容。七、小结一张图看懂 Beans 全文搜索.beans/*.md (平文件) │ Load / 文件监听 ▼ 内存 bean map (Core) ◄───┐ Create / Update / Delete │ 懒初始化 │ ▼ │ Bleve 内存索引 ────────────┘ • standard 分词器 (slug/title/body) • keyword 存储 (id) • BM25 评分模型 ▲ │ QueryString 语法 (通配/短语/布尔/字段/模糊) GraphQL search 过滤器 ──► 返回 ID 列表 ──► 回查内存 bean要点回顾 数据是平文件索引是纯内存bleve.NewMemOnly两者通过懒加载 增量同步保持一致 BM25 解决了词频饱和与文档长度偏差问题让最相关排最前 查询层直接复用 Bleve 查询字符串语法用户零学习成本 从单词匹配到模糊、通配、字段限定均有测试用例保障。这套平文件 内存全文索引的组合让 Beans 在不引入任何数据库的前提下同时服务人类 CLI、TUI 和 AI 代理的检索需求——对任务规模在数千级别的个人项目和小团队而言这正是恰到好处的工程取舍。赞分享【免费下载链接】beansA CLI-based, flat-file issue tracker for humans and robots. 项目地址https://gitcode.com/gh_mirrors/bean/beans点击查看免费下载相关推荐Opengist代码搜索与索引技术Bleve和Meilisearch实现原理详解Opengist代码搜索与索引技术Bleve和Meilisearch实现原理详解 Opengist作为自托管的代码片段管理平台其强大的 代码搜索与索引 功能后端Langchain-Chatchat向量检索技术BM25KNN混合搜索算法详解Langchain Chatchat向量检索技术BM25KNN混合搜索算法详解 引言为什么需要混合检索 在处理本地知识库问答时传统的向量检索KNN人工智能AI 应用RAGAI Agent本地部署后端原神玩家必备Snap.Hutao开源工具箱的5个关键优势原神玩家必备Snap.Hutao开源工具箱的5个关键优势 如果你正在寻找一款能真正提升原神游戏体验的桌面工具Snap.Hutao开源工具箱绝对值得你深入了解桌面应用游戏开发上一篇nbdev 版本演进与技术解析从 CHANGELOG 看 Jupyter 笔记本驱动的软件开发生态下一篇Navicat Premium Mac无限试用终极指南简单三步重置14天试用期创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考