1. 从一条报错说起：为什么资源库深度搜索这么难
你接手一个陌生仓库，CI 挂了，日志里只有一行TypeError: Cannot read properties of undefined (reading 'tenantId')。你知道问题大概在某个鉴权中间件里，但仓库有 3000 多个文件、十几个 workspace 包，grep tenantId出来 200 多处命中。这时候你真正需要的不是「代码补全」，而是资源库深度搜索与问题定位：把自然语言描述的故障，映射到具体文件、具体函数、具体那一行。
传统做法是关键词检索加人工跳转。grep只能匹配字面量，tenantId在 DTO、ORM 实体、测试 mock 里到处都是，你没法用一条正则表达「哪个函数在请求上下文缺失时读了 tenantId」。而 LLM 天然擅长理解自然语言意图，问题在于：光有模型不够，模型得会调工具。它需要先看目录结构，再按文件名缩小范围，然后搜函数定义、搜类定义、看调用链，一步步把候选集收敛。这个多阶段过程，就是 RepoSearcher 这类探索代理要解决的事。
ToolTrain 的思路很直接：不让模型一次性猜答案，而是训练它「有效地使用工具去探索」。它分两阶段——先用拒绝采样做监督微调，只保留那些真正走到正确代码位置的轨迹；再用工具集成强化学习，把「是否命中正确代码段」和「排序是否合理」当作奖励信号。结果是 ToolTrain-7B 在函数级定位上能压过一些 32B 规模的框架，函数级 Recall@5 达到 68.55，配合补丁生成模型后修复成功率最高 31.6%。
这篇不聊论文细节，聊怎么把这套链路落到你自己的仓库里：怎么配检索参数、怎么建索引、怎么发一次查询、报错怎么排。适合需要快速定位依赖与故障根因的后端、全栈、SRE 同学。下面所有配置都可以直接复制改路径使用。
2. 前置准备：TaoToken 接入与 RepoSearcher 工具链配置
要让 LLM 驱动 RepoSearcher 做深度搜索，第一步是把模型调用通道打通。我这边统一走 TaoToken 的 OpenAI 兼容接口，Base URL 用https://taotoken.net/api，模型 ID 按你订阅的来选。先拿 Key：打开 https://taotoken.net/api-keys ，新建一个 Key 并复制，注意它只显示一次。
拿到 Key 之后，建议先做一次最小连通性验证，别等配完一堆检索参数才发现鉴权失败。用 curl 发一条最简单的 chat 请求：
export TAOTOKEN_API_KEY="sk-你的key" curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-7-sonnet", "messages": [{"role": "user", "content": "reply with ok"}], "max_tokens": 16 }'返回里能看到choices[0].message.content就说明通道没问题。如果返回 401，先检查 Key 有没有多余空格、有没有带Bearer前缀。
接下来是 RepoSearcher 侧。它本质是一个轻量探索代理，对外暴露几类工具：文件结构检索、函数搜索、类搜索、文件内容读取。你要做的是把这些工具注册给模型，并约束模型的调用格式。推荐用 JSON Schema 描述工具，模型输出 tool_call 后由你的执行器落地。一个最小工具定义长这样：
{ "name": "search_function", "description": "在资源库中按函数名或语义关键词搜索函数定义，返回文件路径、行号、签名", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "函数名或语义描述"}, "language": {"type": "string", "enum": ["ts", "js", "py", "go", "java"]}, "top_k": {"type": "integer", "default": 10} }, "required": ["query"] } }工具集建议至少包含四个：list_tree（按深度列目录）、search_file（按文件名/路径匹配）、search_function、search_class。RepoSearcher 论文里强调「避免冗余搜索」，落到工程上就是给每个工具加top_k上限，并在系统提示里明确「每次只调一个工具，拿到结果再决定下一步」。这样模型不会一口气并发十个搜索把上下文撑爆。
模型选择上，做定位任务优先选推理能力强的。你可以先在 https://taotoken.net/models 里对比几个候选，用同一批报错跑一遍看命中率。我实测下来，函数级定位对模型的多阶段推理能力很敏感，7B 级别如果没经过工具训练，很容易在第二步就调错工具。
3. 可复制配置：索引、查询参数与 settings 片段
这一节是核心，直接给可复制的配置。先建索引。深度搜索的前提是有一份结构化的仓库索引，否则每次查询都全量扫文件，延迟高且噪声大。我用一个repo_index.json存三类条目：文件、函数、类。
{ "repo_root": "/workspace/your-service", "index_version": "1.0", "entries": [ { "type": "file", "path": "src/middleware/auth.ts", "lang": "ts", "tokens": ["auth", "middleware", "tenant", "jwt"] }, { "type": "function", "name": "resolveTenant", "path": "src/middleware/auth.ts", "line": 42, "signature": "function resolveTenant(req: Request): Tenant", "calls": ["getTenantFromHeader", "getTenantFromToken"] }, { "type": "class", "name": "TenantResolver", "path": "src/tenant/resolver.ts", "line": 8, "methods": ["resolve", "fallback"] } ] }索引生成脚本用 tree-sitter 或语言自带的 AST 解析器都行，关键是tokens字段要包含语义关键词，别只放标识符。比如resolveTenant的 tokens 里加上tenant、context、missing，这样自然语言查询「请求上下文缺失时读 tenant」才能命中。
然后是查询参数。RepoSearcher 的检索分两阶段：粗召回 + 精排。粗召回用 BM25 或向量检索拿 top 50，精排交给 LLM 判断哪个函数最可能是根因。参数配置如下：
{ "retrieval": { "coarse_top_k": 50, "fine_top_k": 5, "bm25_weight": 0.6, "vector_weight": 0.4, "min_score": 0.15 }, "agent": { "max_steps": 8, "tool_call_timeout_ms": 15000, "allow_parallel_tools": false, "stop_on_confidence": 0.85 }, "llm": { "base_url": "https://taotoken.net/api", "model": "claude-3-7-sonnet", "temperature": 0.1, "max_tokens": 2048 } }max_steps: 8是经验值。步数太少，模型还没收敛就停了；太多，容易在无关文件里打转。temperature: 0.1是为了让工具调用格式稳定，定位任务不需要创造性。allow_parallel_tools: false很重要——并行调用会让模型拿到一堆结果却理不清顺序，反而降低准确率。
如果你用 Claude Code 做本地探索，可以在项目根目录放.claude/settings.json，把检索工具挂进去：
{ "mcpServers": { "reposearcher": { "command": "node", "args": ["./tools/reposearcher-mcp.js"], "env": { "REPO_ROOT": "/workspace/your-service", "INDEX_PATH": "./repo_index.json", "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的key", "MODEL_ID": "claude-3-7-sonnet" } } } }这里三件套必须齐全：Base URL 指向https://taotoken.net/api，Key 用你刚建的，Model ID 写你实际订阅的模型。少任何一个，MCP 启动时就会报连接失败。配好后重启 Claude Code，用/mcp命令能看到 reposearcher 处于 connected 状态。
4. 验证请求：从报错到定位的完整流程
配置好了，跑一次真实定位。假设报错是：
TypeError: Cannot read properties of undefined (reading 'tenantId') at resolveTenant (src/middleware/auth.ts:47:18)第一步，把报错和仓库索引一起喂给 RepoSearcher。构造查询请求：
curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-7-sonnet", "temperature": 0.1, "messages": [ {"role": "system", "content": "你是 RepoSearcher 代理。可用工具：list_tree, search_file, search_function, search_class, read_file。每次只调一个工具，最多 8 步。找到最可能的根因函数后输出 JSON：{\"file\":..., \"function\":..., \"line\":..., \"reason\":...}"}, {"role": "user", "content": "报错：TypeError: Cannot read properties of undefined (reading tenantId) at resolveTenant (src/middleware/auth.ts:47:18)。请定位根因。"} ], "tools": [ {"type": "function", "function": {"name": "search_function", "parameters": {"type": "object", "properties": {"query": {"type": "string"}, "top_k": {"type": "integer"}}, "required": ["query"]}}}, {"type": "function", "function": {"name": "read_file", "parameters": {"type": "object", "properties": {"path": {"type": "string"}, "start": {"type": "integer"}, "end": {"type": "integer"}}, "required": ["path"]}}} ] }'模型第一轮大概率会调search_function，query 是resolveTenant。你的执行器返回索引里的候选：
[ {"name": "resolveTenant", "path": "src/middleware/auth.ts", "line": 42, "signature": "function resolveTenant(req: Request): Tenant"}, {"name": "resolveTenantFromToken", "path": "src/tenant/token.ts", "line": 15} ]第二轮模型会调read_file读src/middleware/auth.ts的 40-60 行。读到：
function resolveTenant(req: Request): Tenant { const header = req.headers['x-tenant-id']; if (header) return getTenantFromHeader(header); const token = req.auth?.token; // 第 46 行 return getTenantFromToken(token); // 第 47 行，token 为 undefined }第三轮模型输出定位结果：
{ "file": "src/middleware/auth.ts", "function": "resolveTenant", "line": 46, "reason": "req.auth 在未鉴权请求中为 undefined，第 46 行取 token 得到 undefined，第 47 行传入 getTenantFromToken 后内部读 tenantId 抛错。根因是缺少 req.auth 的空值保护。" }整个过程 3 步，耗时约 4 秒。对比人工 grep：grep -rn "tenantId" src/返回 200+ 行，你得逐个看；而 RepoSearcher 直接收敛到第 46 行。这就是资源库深度搜索的价值——不是搜得更快，是搜得更准。
验证成功的标志有三个：定位到的行号与报错栈一致、reason 里解释了数据流、输出的 JSON 能被你的下游补丁生成器直接消费。如果模型只返回「可能在 auth.ts」这种模糊结论，说明max_steps太小或索引 tokens 不够，回到第 3 节调参。
5. 常见报错排查：401、local proxy failed 与 reading choices
配这套链路，报错基本集中在四个地方。我按出现频率排一下，每个都给对照现象和修法。
401 Unauthorized。现象是 curl 或 MCP 启动后第一次请求就失败，返回{"error":{"message":"invalid api key"}}。原因通常是 Key 复制时带了换行、或者环境变量没导出到 MCP 进程。检查echo $TAOTOKEN_API_KEY | wc -c，正常应该是 51 左右（sk-加 48 位）。如果 MCP 里读不到，把 Key 直接写进settings.json的 env 字段做临时验证，确认是环境变量问题后再改回引用。
local proxy failed / connection refused。现象是 MCP 日志里出现local proxy failed to connect或ECONNREFUSED 127.0.0.1:xxxx。这通常是你本地起了个转发进程但没启动，或者 Base URL 写成了http://localhost。正确做法是 Base URL 直接写https://taotoken.net/api，不要经过任何本地转发。检查settings.json里TAOTOKEN_BASE_URL的值，确保是完整 HTTPS 地址且没有多余路径。
reading 'choices' of undefined。现象是代码里response.choices[0]报Cannot read properties of undefined。这说明请求根本没返回标准结构，多半是 HTTP 状态码非 200 但你没检查。修法是在解析前先判断：
const res = await fetch(`${BASE_URL}/v1/chat/completions`, {...}); if (!res.ok) { const text = await res.text(); throw new Error(`LLM request failed ${res.status}: ${text}`); } const data = await res.json(); const content = data.choices?.[0]?.message?.content; if (!content) throw new Error(`empty choices: ${JSON.stringify(data)}`);这样报错会直接告诉你真实原因，而不是在choices上二次崩溃。
OAuth / token expired。如果你用的是 Claude Code 自带的 OAuth 登录而不是 API Key，可能会遇到OAuth token expired。这时候要么重新登录，要么切到 API Key 模式。在settings.json里显式配TAOTOKEN_API_KEY并删掉 OAuth 相关字段，重启即可。注意 API Key 和 OAuth 不要混用，混用会导致鉴权头冲突。
还有一个隐蔽的坑：模型返回的 tool_call 参数是字符串而不是对象。有些模型会把arguments序列化成"{\"query\":\"resolveTenant\"}"，你直接当对象用就会undefined。修法是统一做一次JSON.parse并 try/catch：
let args; try { args = typeof call.function.arguments === 'string' ? JSON.parse(call.function.arguments) : call.function.arguments; } catch (e) { throw new Error(`bad tool args: ${call.function.arguments}`); }排障时建议开 debug 日志，把每一步的 tool_call 和返回都打出来。RepoSearcher 的准确率高度依赖工具返回质量，如果search_function返回的候选里根本没有正确函数，模型再强也定位不到。这时候要回头检查索引是否覆盖了该文件、tokens 是否包含语义词。
6. 把检索链路固定下来：从一次性调试到日常工具
跑通一次之后，别停在手动 curl。把上面这套封装成一个 CLI，日常直接reposearch "报错信息"就能出定位结果。封装时注意三点：索引增量更新、结果缓存、置信度阈值。
索引增量更新用文件 mtime 判断，只重解析改动过的文件，3000 文件的仓库全量重建约 20 秒，增量通常 1 秒内。结果缓存按「报错栈 + 仓库 commit hash」做 key，同一个 commit 下重复查询直接返回，省 token 也省时间。置信度阈值设 0.85，低于这个值就让模型继续探索而不是强行输出，避免给出错误定位误导修复。
如果你要长期跑 Agent 做批量问题定位，建议走 Coding Plan 而不是按次调 API，成本更可控。入口在 https://taotoken.net/coding-plan ，适合需要持续对仓库做深度检索的场景。单次验证模型能力的话，用模型对话页 https://taotoken.net/models 直接试就行。接入文档在 https://taotoken.net/doc ，里面有完整的参数说明和错误码对照表。
最后说个实际经验：ToolTrain 这类方法的效果，七成取决于工具返回的质量，三成才是模型本身。我踩过的坑是花大量时间调 prompt，结果发现是索引里漏了一个关键文件。所以先把repo_index.json的覆盖率做到 95% 以上，再谈模型选型和参数调优。定位准确率上不去的时候，先查索引，再查工具返回格式，最后才怀疑模型。
