Skip to main content
Glama
deenesjakoruzh
halaprix

bd-explore

by halaprix
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

bd-explore

CI Python 3.10+ 零依赖 许可证: MIT

向 beads 仓库提问，就像 codegraph explore 向代码库提问一样：一次调用返回最相关的 beads 逐字原文——描述、笔记、评论、关闭原因——以及每条命中记录的关系邻域，在输出预算内。

填补了标准 bd CLI 的空白：bd search 仅覆盖标题，bd query 仅限结构化查询，没有任何搜索能覆盖笔记、评论和关闭原因——而这正是成熟仓库中大部分知识的所在之处。bd memories 也被索引（标准 CLI 会截断记忆正文；本工具返回完整内容）。

文档站点: https://halaprix.github.io/bd-explore/

$ bd-explore "why did we re-point SYRP status:open"

═══ SYRP-142 [OPEN · P1 · task · updated 2026-08-12]
    Re-point SYRP feed to the v2 oracle
    The v1 oracle staleness window regressed after the chain upgrade…
    COMMENT (ksz 2026-08-11):
    Decision: re-point rather than patch v1 — see close reason on SYRP-118.
    ── neighborhood ──
    blocked by: SYRP-139 — Oracle failover runbook [in_progress]
    child of: SYRP-100 — Oracle migration epic [in_progress]
    mentions: SYRP-118

主要特性

  • 深度逐字搜索：基于完整 Porter 词干提取的 FTS5 全文搜索，覆盖标题、描述、设计、验收标准、笔记、带日期作者评论、关闭原因及记忆。

  • 关系邻域图：展现一跳依赖关系（blocks、blocked-by、parent-child、supersedes、discovered-from、related）、文本间提及引用以及 GitHub issue/PR 链接（#NNN）。

  • 传递影响范围：查询传递依赖链（--blast <id>），在接触代码前即可查看阻塞项、下游依赖项及史诗层级。

  • 内置 Stdio MCP 服务器：零依赖 JSON-RPC 2.0 标准输入输出模型上下文协议（MCP）服务器，为现代 AI 编码助手提供 bd_explore 工具。

  • 多目标平台安装器：自动发现并配置 Claude Code、Gemini CLI、Antigravity IDE、OpenAI Codex、Cursor 及 AGENTS.md。

  • Beads 持久记忆注入：自动设置 beads 记忆（bd remember --key bd-explore），使每次 bd prime 会话都为代理注入 bd-explore 上下文。

  • 严格输出预算：输出字符预算（--budget 24000）防止在 LLM 工作流中上下文窗口溢出。

  • 零运行时依赖：纯 Python 3.10+ 标准库（sqlite3、json、argparse）。

Related MCP server: recall

安装

独立 Shell 安装器

将 bd-explore 安装到 ~/.local/bin 并自动配置检测到的代理平台：

# From repository clone
./install.sh

# Standalone uninstall
./install.sh --uninstall

Python 包安装

# Standard pip install
pip install .

# Editable install for development
pip install -e .

使用方法

CLI 搜索

# Free text search across all fields (porter-stemmed FTS)
bd-explore "why did we re-point SYRP"

# Compose field filters with free text (codegraph-style)
bd-explore "hash refresh status:open type:task priority:1"
bd-explore "swap oracle epic:rpm5"

# Target specific store or force reindex
bd-explore --store ~/Projects/my-project "auth refactor"
bd-explore --rebuild

# Control limits and output budget
bd-explore -n 3 --budget 16000 "database migration"

支持的过滤器

过滤器

语法/值

描述

status:

open, in_progress, closed, deferred, all

按状态过滤（all 会搜索已关闭的 beads，但排名较低）

type:

bug, feature, task, epic, chore

按问题类型过滤

priority:

0, 1, 2, 3, 4（或 P0..P4）

按优先级过滤

epic:

<id-or-suffix>

过滤属于某个史诗的问题

id:

<id-or-substring>

按 ID 匹配问题（子串/前缀）

非过滤器的词条（例如 foo:bar）会自动退化为全文搜索。 提示：当搜索字符串包含空格、过滤器冒号或与子命令同名的单词时，请使用引号（例如 bd-explore "serve refactor"）。

传递影响范围

计算任意 bead 的完整传递依赖图：

bd-explore --blast 9o32

输出：

  • 上游阻塞项：直接或间接阻塞该 bead 的所有问题。

  • 下游被阻塞项：直接或间接等待该 bead 的所有问题。

  • 史诗祖先链：直接及祖先史诗。

Stdio MCP 服务器

bd-explore 包含一个内置的 JSON-RPC 2.0 stdio MCP 服务器，用于代理集成。它同时支持换行分隔 JSON（NDJSON）和 HTTP 风格的 Content-Length: 头帧格式。

直接运行服务器：

bd-explore serve --mcp
# Or with explicit store:
bd-explore serve --mcp --store ~/Projects/my-project

MCP 工具: bd_explore

暴露 bd_explore 工具，包含以下模式：

  • query (string): 搜索查询字符串，可附带字段过滤器（status:open type:task）。

  • blast (string): 用于计算传递影响范围的 Bead ID。

  • limit (integer, 默认 5): 种子 beads 的最大数量。

  • budget (integer, 默认 24000): 输出字符预算上限。

  • store (string, 可选): 明确的存储路径或仓库目录。

多目标代理安装器

bd-explore install 会检测已安装的 AI 开发者工具，添加 MCP 配置，注入标记围栏包裹的代理指南，并注入 beads 持久记忆。

# Interactive setup (prompts for targets and location)
bd-explore install

# Automated non-interactive batch install
bd-explore install --yes

# Install for specific targets and location
bd-explore install --targets claude,gemini,cursor --location global --auto-allow --yes

# Uninstall configurations
bd-explore uninstall --yes

# Print MCP configuration snippet without modifying files
bd-explore print-config claude
bd-explore print-config cursor

支持的平台

平台

MCP 配置

指令与规则

Claude Code

~/.claude.json / .mcp.json

~/.claude/CLAUDE.md / CLAUDE.md

Gemini CLI / Antigravity CLI

~/.gemini/settings.json / .gemini/settings.json

~/.gemini/GEMINI.md / GEMINI.md

Antigravity IDE

~/.gemini/config/mcp_config.json

IDE 指令 / 工作区规则

OpenAI Codex

~/.codex/config.toml

~/.codex/AGENTS.md

Cursor

~/.cursor/mcp.json / .cursor/mcp.json

.cursor/rules/bd-explore.mdc

通用代理规则

—

~/.config/AGENTS.md / AGENTS.md

标记围栏指令

指令通过标记围栏安全注入，以便进行干净的更新和卸载：

<!-- BD_EXPLORE_START -->
## bd-explore

In repositories with a beads store (a `.beads/` directory exists at the repo root), reach for `bd-explore` BEFORE searching raw files or relying only on `bd search`:

- **MCP tool** (when available): `bd_explore` answers questions about beads/issues/decisions/memories verbatim — description, notes, comments, close reason, plus relationship neighborhood under an output budget.
- **Shell** (always works): `bd-explore "<query>"` (e.g. `bd-explore "why did we re-point SYRP status:open"`, `bd-explore --blast <id>`).

If there is no `.beads/` directory, skip bd-explore.
<!-- BD_EXPLORE_END -->

索引内容

内容

来源

备注

标题、描述、设计、验收标准

.beads/issues.jsonl

主要问题内容

笔记、关闭原因

.beads/issues.jsonl

关键上下文与事后分析

作者评论

.beads/issues.jsonl

带时间戳的对话历史

完整记忆正文

bd memories --json

持久记忆记录

显式依赖边

dependencies 数组

blocks、parent-child、supersedes、related 等

提及边

文本交叉引用

从问题文本中挖掘到的 bead ID 正则匹配

GitHub 引用

文本交叉引用

挖掘到的 #NNN 问题与 PR 引用

设计原则

  1. 派生且可丢弃。 读取 .beads/issues.jsonl（需要 export.auto: true）并将其构建到 ~/.cache/bd-explore/ 下的 SQLite FTS5 索引中，当导出发生变化时自动重建。beads 仓库仍然是唯一的事实来源；缓存可随意删除。

  2. 过时性是一等公民。 每条命中都标记为 [STATUS · P<n> · type · updated YYYY-MM-DD]。

  3. 默认包含已关闭的 beads。 历史记录是大部分价值的来源；在相同相关性下，已关闭命中的排名低于开放命中的排名。可使用 status:open 进行限定。

  4. 对上下文窗口友好。 严格执行输出字符预算，确保能舒适地融入代理对话中。

架构

探索管道位于一个深层模块之后；其他所有部分都适配它。

              CLI (cli.py)              MCP server (mcp.py)
                   │  thin adapters: args / JSON-RPC  │
                   └──────────────┬───────────────────┘
                                  ▼
                      Explorer (explorer.py)
        explore(query, …) → str   ·   blast(id, …) → str
     owns store discovery, index freshness, connection
       lifetime, defaults/clamping, canonical errors
                   ┌──────────────┴───────────────────┐
                   ▼                                  ▼
          index.py (SQLite FTS5,             search.py (BM25 search,
          mention mining, cache)             hydrate → pure render)

  • explorer.py —— 调用者唯一需要的接口：输入 explore() / blast()，输出格式化的文本，失败时返回 ExploreError。

  • index.py —— 将 .beads/issues.jsonl 和 bd memories 解析成派生的 SQLite FTS5 缓存，当导出发生变化时自动原子重建。

  • search.py —— BM25 搜索与查询解析；hydrate() 批量抓取邻域和标题（总共两次查询），render() 是纯函数，负责所有预算/截断逻辑。

  • installer/ —— 多目标平台适配器，位于通用的安装/卸载接口之后。

领域词汇表见 CONTEXT.md；仓库约定见 CLAUDE.md。

开发

# Run the full test suite (stdlib unittest — no test dependencies either)
PYTHONPATH=src python3 -m unittest discover tests -v

# Run one module / one case
PYTHONPATH=src python3 -m unittest tests.test_explorer
PYTHONPATH=src python3 -m unittest tests.test_render.TestRenderPure

# Editable install
pip install -e .

CI 在 Linux 和 macOS 上使用 Python 3.10–3.14 运行测试套件。发布历史见 CHANGELOG.md。

系统要求

  • Python 3.10+

  • 支持 FTS5 虚拟表的 SQLite（官方 CPython 发行版中已包含）

许可证

MIT 许可证。详情见 LICENSE。

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • EzRAG MCP Server

    benbjurstrom
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides semantic search and keyword search over Obsidian notes, along with direct note retrieval, allowing external AI agents to query and access the vault.
    19
    BSD Zero Clause

  • recall

    tools-for-agents
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables agents to query across all their memory stores (brain, team, reading, code) in one call, returning a token-budgeted, ranked briefing with results interleaved from each source.
    14 npm
    MIT

  • bd-graph MCP Server

    halaprix
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables coding agents to query a temporal knowledge graph derived from a beads issue tracker via read-only Cypher queries, exposing current rules, supersession chains, and provenance without LLM API keys.
    MIT

  • Codex Jev

    Hyper-AI-Lab
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables coding agents to discover, optionally rank, and exactly read bounded source-addressed evidence from large repositories and noisy logs, with local-only privacy controls and quota-aware recovery.
    1
    MIT