repowise search 实战指南：关键词全文、符号定位与语义检索一网打尽

repowise search 是 RepoWise 提供的统一检索命令，覆盖三种典型诉求：对已渲染 wiki 页面的关键词全文检索（默认模式）、按名称解析代码符号到文件与行号（--mode symbol）、以及配置了 embedder 后的自然语言语义检索（--mode semantic）。全文与符号模式无需任何 LLM API Key，init --index-only 之后即可立即使用。读完本文你将掌握该命令的完整参数、三种模式的适用场景、Workspace 多仓库作用域，以及它底层与 search_codebase MCP 工具的等价关系。

前置条件与索引准备

使用 repowise search 前需要满足两点：

1. 一个已经建立了 wiki 索引的 Git 仓库（索引通过 repowise init 建立）；
2. repowise 命令已加入 PATH。官方推荐的安装方式为 uv tool install repowise，也可以直接从本仓库源码同步：uv sync --all-packages。

在目标仓库中建立纯索引（不依赖 LLM、不写散文页面）：

cd /path/to/your-repo
repowise init --index-only --yes

--index-only 表示仅从代码结构渲染 wiki 索引，不调用模型生成散文内容，因此整个流程无需任何 LLM API Key。从当前仓库源码看，该选项在 init_cmd/command.py 中已被标记为"弃用但保留"的别名：--index-only 与 --docs 属于上一代拼写，新拼写是 --no-prose（无模型、纯结构索引）与 --prose（模型撰写子系统页面），二者仍然可用并映射到相同的内部逻辑；--mode fast 也会在 CLI 侧隐式等价于 index-only（见 init_cmd/command.py）。

如果仓库尚未建立索引，repowise search 不会静默返回空结果，而是打印明确指引（源码见 search_cmd.py）：

No indexed repos to search. Run 'repowise init' first.

JSON 输出格式下同样会返回 {"query": ..., "mode": ..., "results": []} 以保证 stdout 契约不中断。

1. 全文检索（默认模式）

默认模式在渲染后的 wiki 页面上做关键词检索，建立索引后即可立即使用：

repowise search "rate limiting"
repowise search "pipeline" --limit 5

第一条执行最朴素的关键词全文检索；第二条通过 --limit 把返回条数限制为 5。--limit 的默认值是 10（源码见 search_cmd.py）。

结果按相关度评分排序，命中以表格呈现，包含 Score / Title / Type / Path / Snippet 五列，其中 Snippet 在表格中截断到 50 字符以便阅读，而 JSON 输出不截断（见 search_cmd.py）。

输出格式与完整字段

除默认的富文本表格外，命令支持 --format json 以结构化方式输出，便于脚本消费；--full 则直接返回底层工具未投影的原始字典（含 sources、confidence_score、page_id、调用元信息 _meta 等）。默认投影字段为 score / title / page_type / path / snippet，这是该命令一直以来的载荷契约，折叠重构后被刻意保留（见 search_cmd.py）。

project() 还会附加几个影响"如何解读答案"的键（见 search_cmd.py）：

• candidates：命中结果解析出的可打开文件去重列表（有些结果是页面而非文件，这个列表告诉你该读哪些文件）；
• exact_match 与 note：标识符查询未命中任何索引符号时仍会返回模糊近邻，note 用于提示不要锚定在某一个结果上；
• grep_hint：零结果时的恢复路径提示（如 rg 命令）；
• index：索引新鲜度提示（stale_warning、index_behind、index_age_days 等，见 search_cmd.py）。

2. 符号检索：按名称定位代码

关键词检索之外，repowise search 还能把符号名解析到具体的文件路径与行号：

repowise search "run_pipeline" --mode symbol
repowise search "AuthService" --mode symbol --limit 10

符号模式直接查询符号索引（wiki_symbols 风格的符号表），返回符号的 name、qualified_name、kind（函数/类/方法等）、file、line，以及关键的 symbol_id——这个 ID 是 repowise symbol 命令继续深挖该符号的入口（见 search_cmd.py）。

符号结果在表格中单独成组渲染（列：Name / Qualified Name / Kind / File / Line），即使与页面结果在 hybrid 模式中交错出现，也会按结果类型分组展示而非强行拼进同一张表（见 search_cmd.py）。当没有任何符号匹配时，终端会打印 No symbols matching '<query>'。

精确匹配的保护

底层检索对"查询恰好是某个符号名"的场景有特殊处理：精确命中（包括 path::Symbol 形式的限定符号）会被稳定地提升到结果头部（_protect_exact_symbols，见 tool_search.py）；同时 --mode symbol 未命中时仍可能返回模糊近邻，此时输出中的 exact_match 标记与 note 会明示"这不是精确命中"。

3. 语义检索（可选）

当仓库配置了 embedder 后，可以用自然语言进行语义检索，直接命中含义相近而非字面相同的页面：

repowise search "how are errors handled" --mode semantic

embedder 是在 repowise init / repowise reindex 阶段配置的（init 提供 --embedder <name> 选项，见 init_cmd/command.py），配置后索引会附带语义向量。

需要特别注意：未配置 embedder 时，--mode semantic 不会报错，而是自动回退到全文结果，并打印明确告警。告警文案在 search_cmd.py 中定义：

No embedder configured for this repo, so there is no semantic index to search.
Showing full-text results instead. Set an embedder key and run repowise reindex for semantic search.

这一回退判断依据底层 payload 的 _meta.semantic_search 是否为 false（向量腿无法参与排序时的标记）。因此如果你希望稳定地只做字面匹配，应显式使用 --mode fulltext 或干脆依赖默认模式；只有确认已配置 embedder 并完成 reindex 后，--mode semantic 才是真正的语义检索。

4. Workspace 多仓库作用域

在 RepoWise Workspace 场景下，repowise search 默认只检索主仓库（primary repo），通过两个开关控制作用域：

repowise search "auth" --repo backend     # 只搜 workspace 中别名为 backend 的仓库
repowise search "auth" --all              # 展开到所有已索引仓库

• --repo <alias>：指定 workspace 配置中的仓库别名，隐式进入 workspace 模式；别名不存在时直接报 Unknown repo alias: <alias>（见 search_cmd.py）；
• --all：对每个已索引仓库各发起一次检索，再把排序后的列表融合成一个结果集（见 search_cmd.py）；
• --no-workspace：即使从 workspace 目录内调用，也强制退回单仓库模式。

--all 的融合采用基于排名的 RRF 融合而非直接比较原始分数：每个仓库对自己的结果独立打分，分数只在仓库内部可比，因此跨仓库融合的是"排名位置"。融合参数 _WORKSPACE_RRF_K = 60 与底层联邦检索 _federated_search 使用同一常量，保证 CLI 展开检索与 MCP 联邦检索的排序口径一致（见 search_cmd.py）。融合后的结果集还会重算 candidates、grep_hint、note 等元信息（grep_hint/note 只有在所有应答仓库一致时才附加），并报告整个展开的最差索引新鲜度（_worst_freshness）。单个仓库检索失败不会拖垮整个 --all，其余仓库照常返回答案。

多仓库结果表会额外增加 Repo 列，JSON 输出则在每条结果上附带 repo 字段。

5. 底层原理：CLI 与 search_codebase MCP 工具的等价性

从源码结构看，repowise search 在重构后已成为 search_codebase MCP 工具的一个"薄适配层"（见 search_cmd.py）：旧版命令自带检索逻辑（FTS 查询、向量查询、符号 LIKE、workspace 融合），这些能力如今全部由 search_codebase 承担——它通过 RRF 融合全文与向量两条检索腿而非二选一、遵循每个仓库的 exclude 与 tombstone 配置、对未要求决策/测试内容的查询降低相关页面权重、并能把"长得像标识符"的查询自动路由到符号索引。于是 CLI 的答案与 MCP 的答案是同一条答案。

两条设计被刻意保留以保证兼容性：

1. 标志词表不变：--mode fulltext|semantic|symbol 依然有效且仍是 --help 文档化的拼写，同时工具自身的 auto|concept|path|hybrid 也被接受为附加选择（见 search_cmd.py），因此任何既有脚本都不会因折叠而破坏。底层工具的合法模式集合为 {"auto", "concept", "symbol", "path", "hybrid"}（见 _query_shape.py）。
2. 模式别名映射：fulltext 与 semantic 都映射到工具的 concept 模式（见 search_cmd.py）——concept 分支通过 RRF 融合全文与向量两腿，天然是二者的后继；在无向量的索引上它会自行丢弃向量腿（_safe_vector），恰好对应旧版 --mode semantic 手工回退到全文的位置。

底层 search_codebase 的完整签名（见 tool_search.py）为：

search_codebase(
    query="", limit=5, page_type=None, kind=None,
    repo=None, mode="auto", symbol_kind=None, pattern=None,
)

其中 mode="auto" 会按查询形状自动路由：标识符查询搜符号索引（返回 symbol_id、路径与行号边界，供 get_symbol 使用）、路径查询解析为文件（供 get_context 使用）、散文查询走 wiki 语义搜索、混合查询走 hybrid（符号命中在前，文件支撑页面在后）。决策类页面除非查询是 why 形状，否则排在文件页面之下。检索之外，工具还附带新鲜度加分 _FRESHNESS_TIEBREAK = 0.03（对 90 天内活跃命中加权 0.5、30 天内加权 1.0，见 tool_search.py），让近期活跃内容在得分相近时靠前。

6. 冒烟检查清单

按以下步骤验证环境就绪与行为正确：

步骤	预期结果
repowise search "pipeline" --limit 3	Wiki 命中带评分返回（无匹配时返回空结果而非报错）
repowise search "<符号名>" --mode symbol	返回符号表，含文件路径与行号
无索引仓库直接 search	明确报错，指引先运行 repowise init

第三行对应的是源码中的"没有任何可搜索引仓库"分支：命令打印黄色提示并（在 JSON 模式下）返回空结果结构，绝不会把"没搜到"与"搜不了"混为一谈——后者通过错误信息与退出码区分。

相关文档

• CLI 参考：repowise search（完整命令参数与选项）
• 快速上手（索引初始化与首个搜索的完整流程）
• MCP get_answer（编辑器内基于检索的合成问答：get_answer 内部复用同一套检索并返回带引用的答案，适合"如何/在哪里/为什么"类问题；而 search_codebase 适合原始排名命中、标识符解析与范围限定）