设计一个代码库问答系统（对着私有仓库问）

把仓库里的代码文件切块，用 embedding 建索引，问的时候检索相关代码片段拼进 prompt 回答，并给出文件路径和行号。切块的时候尽量按函数或类的边界切，别拦腰切断。仓库更新用 webhook 触发增量索引。权限按仓库维度过滤。

框架是对的，但它把代码当成了另一种文档。代码的三个特殊性——标识符查询、引用关系、变更历史——一个都没体现，追问一压就空。

① 先问四个问题：仓库数量和总行数？主要用户是新人上手、还是老手排查？问题类型的分布长什么样——这是最关键的一问，因为不同类型要不同的检索方式。代码能不能出网、权限按仓库还是按目录？

② 基线：先不建索引。 对绝大多数团队，最土也最有效的基线是代理式检索——让模型自己 grep、读文件、顺着引用爬，加上强制引用到文件与行号。理由很实在：零索引维护、永远是最新的代码、代码不出网。这套基线能到什么水平：定位类和局部逻辑类问题基本够用；不够用的是「跨模块的语义搜索」和「为什么这么写」。

③ 加挂，每样说代价：

• 按查询类型分三条通道（这是本题的主结构）：

  定位类  「XX 函数在哪定义 / 谁调用了它」 → 符号索引（定义-引用图），精确、便宜、可完全信任
  语义类  「处理超时的逻辑在哪」          → 语义检索，因为没有共同关键词
  解释类  「这段为什么这么写」            → 需要 git blame + PR/commit 描述，代码里根本没有答案
  

  第三条通道最容易被忽略，也最能体现是否做过：「为什么」的答案不在代码里，在变更历史和讨论里。把 commit 信息、PR 描述、关联的 issue 一起索引，才答得了这类问题。

• 语义索引（如果决定上）。解决什么：跨模块的模糊语义查询，公开数据里语义检索相对纯 grep 的问答准确率大约高一成多，且仓库越大优势越明显。代价是什么：新鲜度——索引流水线跟不上活跃团队的提交速度，开发者查询时拿到的可能是几小时甚至几周前的快照；再加上代码要做向量化（合规）和大仓的建索引成本。什么时候不该用：仓库高频变动、代码不能出网、或者问题以定位类为主时。

• 代码专用的切块：按语法结构切（函数、类、方法），并且每个块要带上「上下文头」——文件路径、所属类、导入语句、以及函数签名。因为一段函数体脱离了这些信息几乎无法理解。代价：块之间有冗余，索引体积变大。

• 「哪个在跑」的元信息（这是代码问答最隐蔽的失败模式）。仓库里同时存在废弃实现、灰度分支、历史遗留，代码本身不会说哪个是活的。做法是把可获得的运行时信号接进来：部署配置、特性开关状态、最近有没有被调用的埋点数据、以及一份人工维护的「已废弃目录清单」。代价：这份元信息要维护；收益：它挡住的是「改错对象」这类最难发现的错误。

• 权限：按仓库和目录做前置过滤，且注意过滤后要放大召回再重排；引用要回查权限，不能给出用户看不到的文件链接。

④ 评测：评测集按查询类型分层（定位 / 语义 / 解释 / 跨模块），因为它们的失败原因完全不同，混在一起的总分没有指导意义。定位类有标准答案，可以自动判分；解释类只能人工或 judge，且 judge 要有校准集。零成本信号里最有用的是引用点击率（用户点开引用去核对，说明答案可核查）和重问率。线上还要盯一个专属信号：答案引用的文件是不是已被删除或已废弃——这是索引陈旧最直接的暴露方式。

⑤ 演进：出现「跨模块语义查询占比明显上升」→ 才上语义索引；出现「解释类问题占比高」→ 优先接变更历史而不是加强代码检索；出现「新人上手场景占主导」→ 该做的其实是生成并维护架构文档，而不是继续加强问答。退路：如果索引新鲜度长期跟不上（错误引用率超阈值），退回纯代理式检索。