repowise 故障排查完全指南：从 `doctor` 诊断到索引修复与 Agent 联调

repowise doctor、repowise status与repowise init --resume是这套代码库智能索引工具的"体检三件套"：本文以 TROUBLESHOOTING.md 为骨架，结合仓库源码深入讲解安装、索引、Agent 回答三大类常见故障的根因与修复路径。读完你将对 repowise 的诊断命令、索引恢复机制、存储一致性校验（SQL ↔ 向量存储 ↔ 全文索引）以及 API Key 管理有可落地的实操能力。

快速诊断：先跑一遍体检，再动手修

遇到任何问题，优先从三个命令开始，而不是凭经验乱试：

repowise doctor # install, API keys, index drift, store health, wired agents repowise doctor --repair # fix what it safely can repowise status # what is indexed, and how far behind HEAD

• repowise doctor对当前仓库运行一整套健康检查；
• repowise doctor --repair尝试自动修复它能安全修复的问题；
• repowise status展示已索引的内容以及落后HEAD的距离。

从源码看，doctor的检查清单远比文档列出的更细。入口在 command.py，支持--repair、--workspace/-w（对工作区每个仓库逐一检查）、--no-workspace与--format table|json（json 模式为只读，与--repair互斥，且任一检查失败时以退出码 1 结束，便于 CI 集成）。

单仓库的实际检查项定义在 repo_checks.py，依次覆盖：

doctor在一致性判定上非常严谨：低于信息下限（information floor）的页面、被 exclude 规则排除的文件、代表失败模型页的 stub 页都会被刻意排除在 missing 判定之外（repo_checks.py），因为"它们本就不该出现在索引里"不等于漂移；而 decision 记录与页面向量共用decision:<id>命名空间，SQL 侧必须把它们计入孤儿判定，否则每次检查都会误报（repo_checks.py）。

--repair到底修什么、不修什么

doctor --repair的修复边界非常明确：

• 修复 SQL ↔ 向量/FTS 的漂移：全文索引侧先批量删除孤儿再补索引缺失页；向量侧用"当初构建该存储的那个 embedder"（而非硬编码 mock）重新嵌入缺失页、删除孤儿向量（repo_checks.py）；
• 重新注册卡死的 Claude Code MCP 条目：检测到注册路径失效或命令二进制消失时，通过register_with_claude_code修复（repo_checks.py）；
• 刷新所有已接线 Agent 的配置：调用refresh_wired_agents重写各 Agent 的接线文件（repo_checks.py）。

但它不会重写过期页面——那是repowise update的职责。如果检查后只有 stale pages 而没有存储漂移，--repair会明确告诉你"没有可修的存储漂移"，并给出repowise generate --stale（更便宜的 model-written 页刷新）与repowise update --full（权威 reconcile，会退役不再被选中的页面）两条指引（repo_checks.py）。

安装问题：PATH、残缺安装与 Windows 编码

repowise: command not found

安装目录不在PATH上，按安装方式分别处理：

• uv：执行uv tool update-shell后开新 shell；uv tool dir --bin可打印 bin 目录；
• pipx：执行pipx ensurepath后开新 shell；
• pip：把python3 -m site --user-base下的 scripts 目录（macOS/Linux 为bin，Windows 为Scripts）加入PATH。

Agent 宿主是按名字启动repowise的，所以修好PATH后必须重启宿主（VS Code、Claude Code、Codex 等），否则 MCP 配置里按名字解析的可执行文件依然找不到。

"Provider X requires the 'Y' package"

每个 provider SDK 都随 repowise 一起发布，出现这个报错说明安装损坏或不完整。临时应急：pip install <package>；根治：重装 repowise（uv tool install --reinstall repowise或pip install --force-reinstall repowise）。

Windows 上乱码符号或编码错误

CLI 会自行把输出切到 UTF-8，并对控制台画不出的字形用占位符替换，因此正常运行不会因编码错误中断。若包装脚本或旧 shell 仍失败，执行前设置PYTHONIOENCODING=utf-8（PowerShell 写法：$env:PYTHONIOENCODING = "utf-8"）。

索引问题：中断恢复、超大仓库与成本控制

init 中断或页面缺失：--resume是唯一正解

provider 故障或限流可能让个别页面生成失败，但整轮运行仍"完成"。repowise init --resume只补写缺失的页面，对已存在的页面不会发起任何模型调用，即使你中途切换了 provider 也一样——因为 resume 机制以向量存储为"已写入页面的台账"，读到有向量就跳过（repo_checks.py 对 stub 页的注释详细解释了这一机制）。在 init 命令定义 中，--resume的语义是"跳过向量存储中已生成的页面，从上次中断处继续；在完全索引的仓库上是安全 no-op"。

Doctor 报告零页面

即使无 key 运行也会写出页面（结构化 wiki），所以空 wiki 意味着运行根本没有完成。运行repowise init --resume即可。

超大仓库的内存与时间问题

按效果大致排序的四档手段（都定义在 init 命令 中）：

repowise init --yes --no-prose --mode fast # graph and essential git only; backfill later REPOWISE_PARSE_WORKERS=2 repowise init # fewer parse processes, less memory repowise init -x vendor/ -x 'generated/**' # exclude what you never edit repowise init --max-file-pages 2000 # cap file pages, highest importance first

逐项说明：

• --mode fast：管道深度降为"图 + 必要 git 信号"，跳过 per-file blame、co-change 与 LLM 文档，适合超大仓库首轮快速建索引，之后再回填（init_cmd/command.py）；
• REPOWISE_PARSE_WORKERS：解析池默认最多 8 个 worker 进程，每个 worker 持有自己的解析器，所以降低 worker 数是最直接的省内存杠杆。该上限定义在 ingestion.py（_MAX_PARSE_WORKERS = 8），且REPOWISE_PARSE_WORKERS可在两个方向上覆盖上限——在 16 核机器上 8 worker 反而比 16 worker 更快，因为每个 worker 的导入与语法树构建成本在小文件批次上无法摊薄，还会成倍吃内存（同文件注释给出了实测对比）。非正值会被忽略并告警，空值视为"未设置"；
• -x/--exclude PATTERN：gitignore 风格模式，可重复指定（init_cmd/command.py）；
• --max-file-pages N：限制文件页数量、按重要性从高到低取。省略时由大小策略决定（普通仓库不动，超大仓库设上限）；传 0 表示"每个合格文件一页，不论多少"。该值会写入config.yaml，后续运行沿用（init_cmd/command.py）。

索引成本超出预期

用这三组开关在动手前就摸清成本与范围：

repowise init --dry-run # 打印生成计划与成本估算，不写 wiki repowise init --test-run # 只对 PageRank 前 10 的文件生成，快速验证 repowise init --skip-tests --skip-infra # 缩小分析范围

• --dry-run会展示生成计划与成本估算但不写 wiki——注意它会预热解析与去重缓存（这是派生数据，不算"写了 wiki"）（init_cmd/command.py）；
• --test-run仅生成 PageRank 前 10 的文件（init_cmd/command.py）；
• 若触发 provider 限流，降低--concurrency（默认最大并发 LLM 调用数为 10，见 init_cmd/command.py）。

回答与 Agent 联调：工具不可见、旧版本回答、空结果与语义搜索

Agent 看不到 repowise 工具

大多数宿主只在启动时读取一次 MCP 配置。按顺序执行：重启宿主→repowise doctor --repair→ 对宿主重新执行repowise agents add --target=<id> --yes。

doctor对这一场景有专门的两层检查：静态的"注册条目是否僵死"（全局~/.claude/settings.json里的mcpServers.repowise可能指向已删除的目录或已删除 venv 里的命令二进制，导致每次 Claude Code 会话中 MCP server 静默失败，见 repo_checks.py）与动态的"MCP 冒烟测试"（真的启动注册的 server 并完成一次往返，区分"接好了但不工作"与"根本没接"，见 repo_checks.py）。

Agent 从旧版本代码回答

每条 MCP 响应都携带索引时对应的 commit，并在落后HEAD时给出告警。修复：运行repowise update。防止复发的手段是保留init安装的 post-commit 钩子（repowise hook install可恢复它），或运行repowise watch。详见 AUTO_SYNC.md——该文档给出了四种索引保鲜方式的对比：post-commit 钩子（本地单人推荐）、文件监视器（repowise watch，默认 2 秒防抖，--debounce 5000可调）、GitHub/GitLab webhook（团队共享 server）、以及轮询兜底，无论哪种方式，SessionStart 钩子都会汇报 indexed commit 与HEAD的差距。

空结果不等于"不存在"

空结果的含义是"在已分析的内容中没找到"，并非总是"不存在"。要点：

• 空的调用者列表会附带*_basis字段，说明该语言的调用图解析到了多大比例；
• _meta报告degraded的响应意味着索引的一部分加载失败；
• 在断定"没有符号调用它"或"没有问题"之前，先读这两个字段。

语义搜索无结果或告警embedder.mock_active

embedder.mock_active说明没有配置真实 embedder，搜索退化为纯全文。修复两步：

1. 设置REPOWISE_EMBEDDER（例如gemini、openai或ollama）；
2. 用repowise reindex重建向量存储。

reindex只发起 embedding 调用、不做任何 LLM 调用，因此便宜且快；它同时也能修复损坏的向量存储。从 reindex_cmd.py 看，该命令支持--embedder（可选值gemini、openai、openrouter、ollama、edenai、mock、auto，默认auto，auto 会读取REPOWISE_EMBEDDER与 API key），并会把决策记录一并重新嵌入。repowise serve也会在启动前读取REPOWISE_EMBEDDER（见 serve_cmd.py），所以 embedder 配置对所有读取路径是统一的。

FAQ：Key、花费与常见疑问

需要 API key 吗？

不需要。无 key 时 repowise 也能构建依赖图、git 历史、代码健康分、死代码、变更风险与基于结构渲染的完整 wiki；所有 MCP 工具都可用，get_answer与search_codebase从结构化页面作答。配置 key（或使用ollama、claude_cli、codex_cli这类无需 key 的 provider）则额外获得模型撰写的子系统页面、决策挖掘（decision mining）、repowise ask与 dashboard 聊天。

key 放在哪里？

放在.repowise/.env（已被 gitignore）。generate、update与 MCP server 都会加载它。repowise init默认会把运行时所带的 key 存入该文件，除非传--no-save-key——该选项的源码注释解释了默认开启的原因："脚本化 init 成功后必须留下一个 MCP server 能应答的仓库，key 否则会随设置它的 shell 一起丢失；--no-save-key适用于 key 按进程注入的场景（CI secret、共享机器）"（init_cmd/command.py）。

--yes会花钱吗？

只有当 key 可用且你没传--no-prose时才会。repowise init --yes --no-prose永不调用模型。--prose/--no-prose开关在 init_cmd/command.py 定义（旧的--docs-mode llm|deterministic已弃用，llm等价--prose、deterministic等价--no-prose）。

Dashboard 不显示仓库

API 与 dashboard 必须使用同一个数据库。检查 API 侧的REPOWISE_DB_URL与 dashboard 侧的REPOWISE_API_URL。repowise serve会把两者一起运行，所以这个问题只会在分开运行两者时出现。

如何卸载 repowise？

repowise uninstall --dry-run # 列出它写过的所有东西 repowise uninstall # 交互式询问要移除什么

索引默认不被选中移除，因为重建它成本最高。从 uninstall_cmd.py 看，卸载命令刻意没有--yes——非交互路径必须显式命名范围（--all或--keep-index），以名称本身作为同意；没有终端且没有范围标志时，它只打印清单、什么都不删、以非零退出码结束。交互清单按组呈现：Agent 配置、生成的托管块（CLAUDE.md/AGENTS.md中的托管段落）、仓库索引（会提示重建成本）、机器级状态（登录、缓存、遥测偏好）。

排障心法：从"症状"映射到"检查项"

把本文内容浓缩成一张速查表，遇到问题先对号入座：

这套诊断链路以doctor的十多项检查为仪表盘、以--resume/--repair/update/reindex四个修复命令为手术刀，覆盖了从安装、索引到 Agent 联调的全部常见故障面。建议把repowise doctor纳入日常巡检与 CI 门禁（--format json在检查失败时以退出码 1 结束，天然适合流水线），让索引健康问题在影响 Agent 回答质量之前就被发现。