给 monorepo 里的调试助手划边界：只索引当前服务代码，跨包误报少八成

Q: 问：pnpm 的 `workspace:*` 协议和 yarn/npm 的 workspace 写法不同，上面的代码要改吗？

要改。workspace:* 是 pnpm 的协议格式，yarn classic 用 workspace: 前缀但版本号处理不同，yarn berry 和 npm workspaces 则通常直接用 * 或具体版本号。核心逻辑不变——从 package.json 的依赖声明里识别出哪些是本地包——但匹配规则需要根据你实际的包管理器调整。如果你的 monorepo 里依赖声明不规范（比如混用相对路径和包名），建议先统一依赖声明格式再做依赖图解析，否则闭包会漏掉一些本地包。

monorepo 里的调试助手最容易翻车的地方，不是模型不够聪明，而是它看到了太多不该看的东西。把索引范围收敛到“当前服务 + 它真实依赖的本地包”，跨包误报能直接砍掉一大半——我在两个项目里实测下来，误报率降了 78% 和 81%。

问题不在检索算法，在边界定义

大多数调试助手默认的策略是全仓索引。你问它“这个接口为什么返回 500”，它会把隔壁支付服务的异常处理代码、前端 SDK 的 fetch 封装、甚至根目录的 CI 脚本一起拉进来做上下文。检索结果一杂，模型就开始“联想”——把 A 服务的错误码和 B 服务的中间件逻辑硬凑成一个解释。

去年我给一个 12 个包的中型 monorepo 接调试助手，最开始用的就是全仓索引。一个订单服务的空指针报错，助手给出的第一条诊断指向了用户服务的权限校验函数，理由是“两者都调用了相同的 Redis key 前缀”。技术上说它没完全跑偏，但对我们修 bug 的人来讲，这是纯噪音。

核心问题不是向量检索的 recall 不够，而是索引边界和调试场景的认知边界不匹配。你调试的是订单服务，认知范围就应该限定在订单服务能直接触达的代码里。跨包误报的本质，是系统把“仓库里存在”当成了“当前调试上下文里相关”。

用依赖图代替目录约定

最直觉的做法是按目录划分：services/order 下的代码归订单服务，其他都不索引。但 monorepo 的现实是，共享包往往才是 bug 真正的藏身之处。订单服务调用 @repo/pricing 里的计价函数，函数内部有个除零问题——如果你把 @repo/pricing 排除在索引外，助手反而会开始瞎猜订单服务自己的代码。

正确做法是构建当前服务的传递依赖闭包。从 services/order/package.json 出发，解析 dependencies 和 devDependencies 里所有 workspace:* 或 @repo/* 开头的本地包，递归展开。最后得到的是一个有向无环图的子图，这个子图才是索引范围。

我在一个 pnpm workspace 项目里的实现是这样：

// index-scope.ts
import { readFileSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { globSync } from 'glob';

interface PkgJson {
  name: string;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
}

function resolveWorkspaceDeps(
  pkgPath: string,
  visited = new Set<string>()
): string[] {
  const pkgDir = dirname(pkgPath);
  const pkg: PkgJson = JSON.parse(readFileSync(pkgPath, 'utf-8'));
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
  const localDeps = Object.entries(deps)
    .filter(([, v]) => v.startsWith('workspace:'))
    .map(([name]) => name);

  const result: string[] = [pkgDir];

  for (const depName of localDeps) {
    // 在 monorepo 根目录下按包名定位
    const depPkgPath = globSync(`packages/*/${depName}/package.json`, {
      cwd: MONOREPO_ROOT,
      absolute: true,
    })[0];

    if (depPkgPath && !visited.has(depPkgPath)) {
      visited.add(depPkgPath);
      result.push(...resolveWorkspaceDeps(depPkgPath, visited));
    }
  }

  return result;
}

这段逻辑不复杂，但边界效果很明确：订单服务 + @repo/pricing + @repo/utils 进入索引，而用户服务、通知服务、前端应用全部排除。传递依赖闭包比“当前目录”宽，比“整个仓库”窄，正好卡在调试时你真正会跳转查看的代码范围上。

索引元数据里带上“归属标签”比过滤更灵活

光是构建索引范围还不够。如果你做的是团队级工具，不同开发者调试不同服务时，索引范围要能动态切换。这时候比较实用的做法是：索引全仓，但在每个 chunk 的元数据里标注它属于哪个包、被哪些服务传递依赖。查询时再根据当前调试的服务做过滤。

我在一个 20 多个包的 monorepo 里用了这个方案。每个代码块索引时附带两个字段：packageName 和 reachableFrom（后者是预计算的传递依赖反向映射）。查询订单服务的问题时，过滤条件是 reachableFrom 包含 @repo/order-service。

这个方案的好处是切换服务不用重建索引，坏处是索引体积会大一些，而且 reachableFrom 需要在每次依赖图变化时重新计算。团队里如果有人频繁改 package.json，这一步要放进 CI 或 pre-commit 钩子里。

实测数据：全仓索引 + 归属过滤的方案，和只索引依赖闭包的方案，误报率差距在 5% 以内。但前者在多人协作场景下的灵活性明显更好。如果你只是个人用或者团队规模小，直接做闭包索引就够了，没必要上元数据过滤。

跨包误报的真正重灾区是“类型相似”

边界划清楚了，还有一类误报会残留下来：不同包里结构相似的代码。比如订单服务和支付服务都有一个 createTransaction 函数，参数结构类似，都涉及金额计算。即使索引范围已经限定在订单服务，如果检索返回的 chunk 恰好是订单服务里一段和支付服务“长得很像”的代码，模型仍然可能混淆。

这类问题的解法不在索引层，而在提示词里注入包边界信息。调试助手生成诊断时，显式告诉它“你只能引用以下包中的代码：@repo/order-service、@repo/pricing、@repo/utils。如果你看到的问题可能源于其他包，请说明‘超出当前索引范围’而不是猜测。”

加上这个约束之后，模型的行为变化很明显。它不再硬凑一个跨包的解释，而是会明确说“这个错误可能来自 @repo/gateway 的中间件，但该包不在当前索引范围内，建议扩大范围后重新分析”。这种“诚实的无知”比一个看似合理但错误的诊断有价值得多。

误报率降八成的数字是怎么来的

我在两个项目上做了前后对比。项目 A 是 8 个包的 NestJS monorepo，项目 B 是 14 个包的 Next.js + tRPC monorepo。评估方式是从各自的历史 bug 库里抽 50 个真实问题，让调试助手在“全仓索引”和“依赖闭包索引”两种配置下分别生成诊断，人工标注是否“指向了正确的问题代码位置”。

项目 A 的误报率从 43% 降到 9%，项目 B 从 37% 降到 7%。平均下来降了大约八成。这个数字会随着 monorepo 规模、包间耦合程度、代码相似度而波动，但方向是确定的：边界越清晰，模型的诊断越可靠。

有一个值得注意的细节：在项目 B 里，剩下 7% 的误报几乎全部集中在两个包之间共享的一段数据库访问层代码。这段代码被 @repo/db 同时暴露给订单和库存服务，索引范围本身没错，但两个服务通过这段共享代码产生的耦合，让模型在定位“问题出在哪个服务调用链上”时仍然会犹豫。这类问题靠索引边界解决不了，要靠更细粒度的调用链追踪——这是另一个话题了。

常见问题

问：如果我的 monorepo 里服务之间通过消息队列通信，没有直接的 package.json 依赖，依赖闭包还管用吗？

不管用。依赖闭包只覆盖静态可解析的代码依赖（import/require）。如果你用 Kafka、RabbitMQ 或类似机制做服务间通信，消息契约定义所在的包（比如共享的 schema 包）通常会被双方引用，这时候闭包还能覆盖到契约代码。但如果消费者服务里的处理逻辑和生产者完全没有代码层面的引用关系，调试时你需要手动把消费方的包加入索引范围。这种情况建议在调试助手的配置里留一个 extraPackages 字段，按需手动扩展。

问：pnpm 的 workspace:* 协议和 yarn/npm 的 workspace 写法不同，上面的代码要改吗？

要改。workspace:* 是 pnpm 的协议格式，yarn classic 用 workspace: 前缀但版本号处理不同，yarn berry 和 npm workspaces 则通常直接用 * 或具体版本号。核心逻辑不变——从 package.json 的依赖声明里识别出哪些是本地包——但匹配规则需要根据你实际的包管理器调整。如果你的 monorepo 里依赖声明不规范（比如混用相对路径和包名），建议先统一依赖声明格式再做依赖图解析，否则闭包会漏掉一些本地包。

问：索引范围缩小后，调试助手会不会漏掉真正跨包的问题？

会，但这是有意的取舍。跨包问题（比如 A 服务的修改破坏了 B 服务的调用）在调试时通常不是从“单点报错”切入的，而是从集成测试失败、部署后的告警切入。这种场景下你应该用全仓索引或者手动指定多个服务作为调试范围。依赖闭包方案解决的是“我盯着一个服务的报错找原因”这个高频场景，而不是所有场景。我的建议是调试助手支持两种模式——单服务模式和全仓模式——默认用单服务，遇到跨包线索时一键切换。