Beadsbd search命令深度指南跨标题、描述与 ID 的快速议题检索【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd search是 Beads 议题追踪器Dolt 驱动的多会话编码代理持久任务记忆系统中面向快速文本检索的核心命令。本指南以 search.md 技能文档为骨架结合 cmd/bd/search.go 与 internal/storage/issueops/search.go 的源码实现系统讲解bd search的基本用法、全部过滤参数、排序与 JSON 输出以及与bd list的选型边界帮助你掌握一条零前置条件、即输即查的议题检索路径。1.bd search是什么在 Beads 中议题issue以 Dolt 数据库为存储底座跨会话持久化天然适用于多会话、带依赖关系的编码代理工作流参见 SKILL.md。当工作跨越会话、需要恢复上下文、或想确认某个问题是否已被发现/提交/修复时bd search是最直接的入口它用一条简单文本查询同时匹配议题的标题title、描述description与 ID它是**探索式查询exploratory query**的首选不要求你像bd list那样先指定搜索字段它被专门优化为低上下文占用当通过 MCP 调用时search比list消耗更少的 token对 LLM/Agent 更友好。从命令实现看cmd/bd/search.gosearchCmd属于issues命令组Use定义为search [query]其Long描述明确说明默认搜索**所有状态包括已关闭**的议题ID 类查询如bd-123、hq-319走快速精确/前缀匹配文本查询匹配标题描述搜索可通过--desc-contains显式启用。2. 基本用法bd search authentication bug # 全文检索标题 描述 ID bd search login --status open # 只查 open 状态 bd search database --label backend bd search bd-5q # 按部分议题 ID 检索快速前缀匹配查询参数既支持位置参数多个词自动用空格拼接也支持--query标志替代。若两者都为空命令会打印帮助并报错search query is required见 cmd/bd/search.go对应行为由 search_test.go 中的TestSearchCommand_MissingQueryShowsHelp验证先向 stderr 输出错误再展示帮助最终以退出码 1 结束。2.1 工作原理bd search的查询会出现在议题的任意下列字段中即命中议题标题Issue title议题描述Issue description议题 ID支持部分匹配与bd list必须显式指定搜索字段不同bd search自动覆盖全部文本字段搜索速度更快、对探索式场景更直观。ID 类查询使用快速精确/前缀匹配路径见 search.go 注释例如bd search bd-5q可以直接定位到以该前缀开头的议题这正是 Agent 恢复上下文时最常用的技巧之一。3. 过滤参数全表search命令的过滤参数远不止技能文档列出的基础项。以下表格汇总了 cmd/bd/search.goinit()中注册的全部标志参数简写说明取值范围 / 默认值--query查询词位置参数的替代任意文本--status-s按状态过滤open, in_progress, blocked, deferred, closed, all支持逗号分隔做 OR默认搜索所有状态含 closed--assignee-a按指派者过滤用户名--type-t按类型过滤bug, feature, task, epic, chore, decision, merge-request, molecule, gate--label-l按标签过滤AND必须全部包含可重复--label-any按标签过滤OR至少包含一个可重复--limit-n限制结果条数默认50--sort排序字段priority, created, updated, closed, status, id, title, type, assignee--reverse-r反转排序布尔--long每个议题输出多行详情布尔--jsonJSON 格式输出布尔全局标志--created-after/--created-before创建时间范围YYYY-MM-DD或 RFC3339--updated-after/--updated-before更新时间范围同上--closed-after/--closed-before关闭时间范围同上--priority-min/--priority-max优先级范围闭区间0-4或P0-P4--desc-contains描述子串大小写不敏感文本--notes-contains笔记子串大小写不敏感文本--external-contains外部引用子串大小写不敏感文本--empty-description描述为空/缺失的议题布尔--no-assignee未指派议题布尔--no-labels无标签议题布尔--metadata-field按元数据字段过滤keyvalue可重复见下--has-metadata-key拥有某元数据键的议题键名3.1 关于默认搜索所有状态的设计决策源码中有一段值得注意的设计注释cmd/bd/search.goissue 编号 bd-t5yexbd search默认不排除已关闭议题。其理由是真实世界中最常见的查询是这个问题是否已经被发现/提交/修复过——如果静默排除 closed 议题就会得到错误的不存在答案。这与早期 hq-319 的 open-only 默认相反当时以扫描范围为代价换取正确性当性能敏感时应显式使用--status open缩小范围或在大型数据库中将--limit调大。同理--status为空时匹配所有状态但--status open及--status all会先加载存储的bd status自定义状态配置再做映射cmd/bd/search.go。依赖阻塞dependency-blocked的议题建议使用bd blocked命令查询而非仅靠search的状态过滤。3.2 优先级、日期与元数据过滤优先级范围通过--priority-min/--priority-max指定0critical1high2medium3low4backlog传入值会经 internal/validation 的ValidatePriority校验后映射为PriorityMin/PriorityMax过滤条件cmd/bd/search.go。日期类标志支持YYYY-MM-DD或 RFC3339由parseTimeFlag解析后填充CreatedAfter等字段cmd/bd/search.go。元数据过滤是较新的能力GH#1406--metadata-field keyvalue可重复传入键名经storage.ValidateMetadataKey校验后存入MetadataFields映射--has-metadata-key则筛选存在某元数据键的议题cmd/bd/search.go。这为自定义工作流如按 sprints、环境、里程碑等自定义字段归档提供了结构化过滤手段。4. 实战示例4.1 基础搜索# 查找所有提到 auth 或 authentication 的议题 bd search auth # 搜索性能类 open 议题 bd search performance --status open # 查找数据库相关的 bug bd search database --type bug4.2 组合过滤# 查找关于 login 的 open 后端议题 bd search login --status open --label backend # 搜索 Alice 的 refactor 任务 bd search refactor --assignee alice --type task # 查找最近的 bug限制 10 条 bd search bug --status open --limit 10 # 优先级 0-2 范围内的安全相关议题 bd search security --priority-min 0 --priority-max 2 # 2025 年之后创建的 open bug bd search bug --status open --created-after 2025-01-01 # 描述中包含 endpoint 的 API 议题 bd search api --desc-contains endpoint # 未指派且无标签的清理工作 bd search cleanup --no-assignee --no-labels4.3 排序输出# 按优先级排序的 bugP0 在前 bd search bug --sort priority # 按最近更新排序的 feature bd search feature --sort updated # 按优先级排序、最低优先在前 bd search refactor --sort priority --reverse # 按创建时间排序、最新在前 bd search task --sort created --reverse注意排序在存储层完成Go 侧会调用workapi.SortIssues(issues, sortBy, reverse)cmd/bd/search.go对返回结果做最终排序--sort支持priority, created, updated, closed, status, id, title, type, assignee九个字段。4.4 JSON 输出# 获取 JSON 结果用于程序化处理 bd search api error --json # 与 jq 配合做高级过滤 bd search memory --json | jq .[] | select(.priority 1)JSON 模式下命令会为每条结果附加标签labels、依赖计数dependency/dependent count与评论计数comment count封装为IssueWithCounts结构输出cmd/bd/search.go。若标签或计数加载失败命令只会向 stderr 打印警告而不中断输出——这对管道化脚本尤为重要。4.5 输出格式紧凑格式默认每条议题一行形如ID [P优先级] [类型] 状态 指派者 [标签] - 标题长格式--long每个议题多行额外展示 Assignee 与 Labels便于人眼阅读详情cmd/bd/search.go无结果输出No issues found matching query。5.bd search与bd list如何选择技能文档给出了一张直接的对比表这里结合 list.md 的说明展开命令最佳适用场景默认上限上下文占用bd search快速文本检索、探索式查询50低对 LLM 高效bd list高级过滤、精确查询无高返回全部结果何时用bd search想通过关键词快速找到议题正在探索议题数据库不确定具体字段通过 LLM/MCP 使用 Beads希望最小化上下文消耗。何时用bd list需要高级过滤日期范围、优先级范围等——不过请注意search也原生支持这些标志需要无上限的全量结果需要特殊输出格式--format digraph、--format dot等图格式需要按指定字段精确过滤--title、--title-contains等。简单经验法则先search缩小范围再show id深入详情。bd search的默认--limit 50在大型数据库中既保证了响应速度也防止 MCP 调用产生超大输出。6. 源码实现纵深一条查询的完整旅程理解bd search的底层实现有助于预判它在大型库上的行为边界。整条调用链为bd searchCLI →store.SearchIssues(ctx, query, filter)→searchInTx→searchTableInTxT逐表查询 合并。6.1 双表合并issues 与 wispsBeads 将议题持久化在 durable 的 issues 表中同时存在 ephemeral 的 wisps 表临时/无历史议题。searchInTxinternal/storage/issueops/search.go统一处理若filter.Ephemeral为 true只查 wisps 表空表或缺表时回落到 issues 表默认Ephemeral nil下先查 issues 表再探测 wisps 表是否为空非空则合并两侧结果合并时按 ID 去重wisps 表中的记录优先于 issues 表中同 ID 记录临时覆盖持久对应 be-iabdi 的数据一致性策略合并前对两侧各自排序后的结果拼接再按同一排序键重排确保--limit截断取到的是全局 Top-N 而非某一侧的任意前缀。6.2 性能优化Pattern Bid-shrink当--limit为正且投影为宽列时搜索走Pattern BsearchTablePatternBTinternal/storage/issueops/search.go先执行一次廉价的SELECT id扫描拿到有序、限长后的 ID 列表再对存活的行做批量获取与完整水合labels/deps。这在大型语料库中避免了为被 LIMIT 丢弃的行流式读取六个大 TEXT 列description、design、acceptance_criteria、notes、payload、waiters是bd search能在海量议题上保持低延迟的关键issueLiteProjection还提供了连这些重列都不读的 lite 变体。6.3 防御性上限EffectiveSearchLimit 与 MaxRowsEffectiveSearchLimitinternal/storage/issueops/search.go规定了 SQL LIMIT 的取值逻辑limit0, maxRows0时无 LIMITlimitN时返回 N在配置了 MaxRows 防御上限时返回cap1以便EnforceMaxRowsCap通过扫描行数发现越界并返回ErrTooManyRows。所有searchInTx的退出路径在交给调用方之前都会先trimToSearchLimit再检查上限避免每侧独立 LIMIT、合并后静默超限的假阳性be-x42v.4 round-4/5 的修复。这些行为在 internal/storage/dolt/queries_test.go 中有大量用例覆盖如TestSearchIssues_ByTitle、TestSearchIssues_ByID、TestSearchIssues_LimitFilter、TestSearchIssues_LabelFilter等跨后端embedded dolt 与 dolt server也通过 internal/storage/dolt/search_parity_test.go 保证行为一致。6.4 测试印证search_test.go 的TestSearchWithDateAndPriorityFilters用三个 security 相关议题bug/feature/task 混合、含已关闭议题验证了优先级范围、创建时间、更新时间、关闭时间以及组合过滤的语义测试注释特别指出auth是子串匹配会命中authentication与automated——提醒你在使用关键词时留意子串匹配的宽泛性。7. 最佳实践小结确认历史用bd search 关键词先确认是否已有人处理过默认包含 closed 的结果不会给出错误的不存在答案按 ID 恢复上下文bd search bd-5q这类部分 ID 前缀匹配是 Agent 从压缩compaction后恢复会话的最快路径大库注意收敛在大型数据库中主动加--status open或调大--limit避免被默认 50 条截断或触发 MaxRows 防御上限机器消费用 JSON--json jq 可完成priority、status等字段的二次过滤且 JSON 输出已附依赖与评论计数结构化检索交给bd list需要无上限结果、图输出digraph/dot或按字段精确过滤时切换bd list探索式、低上下文场景始终优先bd search。作为 Beads 技能体系commands中与bd list、bd show互补的检索三件套之一bd search以最少心智负担、最低上下文成本覆盖了日常议题检索的大多数场景是编码代理与人类开发者都应该最先掌握的 Beads 命令之一。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考