codebase-exploration

使用 Repowise 探索代码库

此项目具有 Repowise 智能层。在使用 grep 和阅读原始源代码来了解代码库之前，优先使用 Repowise MCP 工具——它们能返回文档、所有权、历史记录、决策和图结构，而这些信息无法仅靠读取文件获得；通常一次往返即可，而不必多次查询。

不同问题该用哪个工具

你想要……	调用
初步了解不熟悉的仓库	get_overview() — 架构摘要、关键模块、入口点、Git 状态和知识图谱。有了全貌后就无需再调用。
直接回答“X 如何／在哪里／为何起作用”	get_answer(question="…")：综合答案，附带引用和一个 confidence 可信度信号。将搜索 → 阅读 → 推理的循环合并为一步。
查找符号、文件或模糊概念	search_codebase(query="…") — 混合搜索。mode="auto" 会将标识符路由到已索引的符号命中（symbol_id／行范围 → 传给 get_symbol），将路径路由到文件页面（→ get_context），将普通文本路由到语义维基搜索（每个命中都会报告 search_method：embedding 或 bm25）。使用 mode=symbol|path|concept|hybrid 强制选择分支；使用 symbol_kind 缩小符号范围。
获取指定文件／符号的速览卡片	get_context(targets=[…]) — 标题、摘要、签名、热点标记、主要调用方、决策标题、symbol_ids（没有 symbol_id 的条目格式为 path::name）。一次调用即可批量查询多个目标。
获取某个符号的实际源代码	get_symbol("path/to/file.py::Name") — 返回带行范围的精确字节内容。比 Read 加偏移计算更省事。使用 get_context 返回的 symbol_id。

推荐流程

1. 遇到不熟悉的新区域 → 调用一次 get_overview()。
2. 有具体问题 → 先调用 get_answer(question=…)。
   • 可信度高 → 直接作答，并引用路径。
   • 可信度为 medium／low → 通过 get_context 查询 best_guesses[0].file 或 fallback_targets[0]，再用 get_symbol 获取字节内容。
3. 有指定的符号或路径 → 调用 search_codebase(query="Name") / search_codebase(query="path/to/file.py")；符号命中直接传给 get_symbol，文件命中传给 get_context。
4. 想了解概念涉及的更多文件 → 调用 search_codebase，再对命中结果批量调用 get_context，最后仅对实际需要查看代码主体的结果调用 get_symbol。

只有当已索引的上下文未涵盖用户询问的具体细节时，才使用自己的文件读取和搜索工具。

可信度信号——以下情况需要核实

• 存在 _meta.stale_warning（索引与 HEAD 不一致），或
• confidence 为 medium／low，或
• 结果的 search_method 为 bm25。

否则，响应就是最新的——可直接据此采取行动。

错误处理

• “No repositories found. Run 'repowise init' first.” → 建议运行 /repowise:init。 如果此仓库是临时克隆、测试夹具或工作树，请添加 --no-editor-setup： 否则，init 会将用户唯一的全局 repowise MCP 条目重新指向该仓库。
• MCP 工具不可用 → 如果已安装插件，优先使用对应的 CLI 斜杠命令（/repowise:ask、/repowise:context、/repowise:symbol、 /repowise:search），而不是盲目使用 grep。
• get_answer／search_codebase 返回空结果 → 仓库可能使用了模板渲染的维基。改用显式路径调用 get_context，并说明由模型编写的页面（repowise generate，或通过 LLM 提供方运行 /repowise:init）可解锁更丰富的文档和语义搜索。
• 工具完全无法连接 → 可能尚未安装 repowise 二进制文件；建议运行 /repowise:init。