跳至主要內容

Monorepo 测试入口漂移检查

Monorepo 测试入口漂移检查

同一个测试文件从 package 目录、workspace 根目录、CI 脚本或临时 npx vitest run ... 入口运行时，可能解析到不同的 alias、构建产物或环境变量。AI 修改跨包代码后，如果只跑“看起来一样”的命令，容易把 stale dist、漏 alias 或旧 fixture 当成真实通过。

何时使用

用在这些场景：

  • monorepo 中一个 package 改了源码，另一个 package 的测试依赖它；
  • package-level test 通过，但 workspace-level ad-hoc command 失败或结果不一致；
  • 测试命令会从 dist/、workspace alias、exports 或 symlink 中选择不同入口；
  • 你准备把命令输出写进 summaries/hermes/YYYY-MM-DD.md，需要说明“这个 proof 到底覆盖了哪个入口”。

如果只是单包内部函数改动，且 package script、CI script 和本地命令完全一致，不必套完整流程；记录 package script 和输出即可。

5 分钟漂移雷达

检查点问题通过标准
Entry point我跑的是 package script、workspace root 还是 ad-hoc file list？记录完整命令和当前目录。
Source vs dist依赖包解析到源码还是已构建产物？说明 alias、build 步骤或 package export。
Failure shape如果失败，它暴露的是业务断言、解析入口还是旧构建产物？失败输出能改变下一步计划。
Re-run path修复后是否重跑同一条失败命令？同一入口从红变绿，另补必要 package script。
Handoff下一轮如何避免误判？写出 Next safe command。

推荐执行顺序

  1. 先冻结 human hypothesis：写一句话，例如“workspace 根目录运行跨包 Vitest 可能绕过 package alias，导致 UI 测试读到 stale core dist”。
  2. 跑真实失败入口：不要马上改配置，先运行暴露问题的命令，并保存最小失败输出。
  3. 标记解析路径：判断失败来自源码逻辑、测试 fixture、alias 缺失、构建产物陈旧，还是环境变量不同。
  4. 只修入口差异：如果问题是入口漂移，优先补 workspace config、统一 script 或显式 build step，不要顺手改业务逻辑。
  5. 重跑同一入口：修复后先跑原失败命令，再跑 package-level command 或 typecheck，证明没有只修一个入口。
  6. 写接力：记录下次应先跑哪条命令、是否需要先 build、哪些 dirty path 没接管。

练习卡片模板

Observation:
Human hypothesis before agent:
Failing / risky command:
Failure output or mismatch:
Source-vs-dist decision:
Minimal change:
Verification after edit:
What I learned that the agent did not own:
Decision: Continue / Narrow / Stop / Switch
Next safe command:
Ownership boundary:

示例：跨包 Vitest alias

Observation: skills UI selection test needs keywords generated by skills-core.
Human hypothesis before agent: running cross-package Vitest from skills/apps may resolve @skills-manager/core to stale dist unless workspace aliases point to src.
Failing / risky command: npx vitest run packages/skills-core/test/skills-core.test.ts packages/skills-ui/test/selection.test.ts
Failure output or mismatch: Chinese keyword search returned [] before rebuilding core dist.
Source-vs-dist decision: this is an entrypoint drift, not a search algorithm feature gap.
Minimal change: add workspace-level Vitest aliases to source entry files.
Verification after edit: rerun the same workspace command, then run the UI package test script.
Decision: Continue
Next safe command: from skills/apps, run the workspace Vitest command before relying on package-only proof.
Ownership boundary: do not touch existing unrelated skills-installers, desktop, TUI or docs dirty paths.

常见反模式

  • 只补业务测试：实际问题是入口解析到旧 dist，却继续扩 feature tests。
  • 只跑 package script：package script 通过，但 cron 或接力者常用 workspace command 仍会失败。
  • 只 build 后重跑：build 能让 stale dist 变绿，但没有修复下一次从 workspace root 运行时的入口漂移。
  • 不记录 cwd：同一命令在不同目录含义不同，最终 notebook 无法复核。

交付标准

  • 最终记录必须包含当前目录、真实命令、失败或风险形态、修复后同一入口的输出；
  • 若新增配置，说明它只改变测试入口解析，不改变业务运行时行为；
  • 不能把本机绝对路径写进文档或 notebook；
  • 如果没有失败输出、风险入口或可复核命令，Decision: Stop / Switch，不要继续扩测试配置。
Copyright © 2026 naijoug