配置 vibator
参考：npx vibator docs configuration 会打印配置格式，
npx vibator docs rules 会打印每条规则及其选项和默认值。
本技能是工作流程；那些文档才是契约。
配置是一项发现任务：正确的配置取决于项目实际包含的内容。先检查，再编写，最后运行。
基本原则
- 绝不要为了通过而削弱门禁。 关闭规则、放宽其阈值或排除一个文件，只是因为当前不通过，这会隐藏问题而非修复问题。请修复发现的问题，或者让规则保持失败并说明原因。唯一的逐行逃逸是
// vibator-ignore: <reason>，且必须提供原因。 - 只配置与默认值不同的部分。 每条规则在无任何配置时都会以其默认严重级别运行。一个重申所有默认值的配置会掩盖真正重要的修改行。
include和exclude会替换规则的默认值。 它们不会合并。在缩小范围之前，请先复制你仍需要的默认值。- 绝不要设置
recommended: false来让运行通过。 这会禁用配置未明确指出的所有规则，包括那些已通过的规则。该选项存在的目的是为了明确表达一种人工选择，而这种选择应由人来决定。 - 项目扩展的配置不是你可以编辑的。 预设规定了一个供多个项目共用的标准。请在本地配置差异部分，或者请人类修改预设。绝不要通过编辑
node_modules下的文件来压制发现的问题；下次安装都会替换它。
步骤
-
从一个有效文件开始。 如果不存在
vibator.json，运行npx vibator init；它会写入$schema行，让编辑器能够进行验证。然后运行npx vibator list可以查看每条规则及其默认值。在编写自己的规则之前，检查项目是否已扩展了一个预设，或者是否存在可供扩展的预设（package.json中的@scope/quality类型包，或跨兄弟仓库重复的相同配置）。扩展预设优于重写它；参见下面的“在共享预设上构建”。 -
先运行一次，无配置：
npx vibator --reporter json。这会显示哪些规则通过、哪些失败、以及哪些因缺少选项而崩溃。在诊断之前先查看数量；一条有 400 个发现项的规则需要一个决策，而不是今天修复 400 个问题（参见步骤 6）。 -
发现默认关闭的规则需要什么。 每条规则之所以关闭，是因为它无法在没有项目知识的情况下运行。查找它们：
locale-parity：找到语言环境目录（locales/、i18n/、public/locales/）。注意布局：每个语言环境一个目录（layout: "directory-per-locale"）还是每个语言环境一个文件（"file-per-locale"），以及哪个语言环境是源语言。codegen-drift：读取package.json中的脚本以查找生成器（db:generate、openapi、graphql-codegen），并找到每个生成器写入的路径。为每个生成器配置一个条目，包含name、command、paths。banned-patterns：阅读项目的审查约定（CONTRIBUTING、风格文档、反复出现的审查评论）。每个符合“永远不要做 X”模式的模式都应作为一个条目，带有自己的message、expected和fix，其编写应像内置规则一样谨慎。no-deprecated-apis：列出 tsconfig 文件；一个 monorepo 希望每个应被检查的项目都在options.projects中。
-
使用
guidelines将现有项目文档关联到规则上。 如果仓库中存在AGENTS.md、CLAUDE.md或包含规则强制执行的标准的风格文档，请映射它："guidelines": {"AGENTS.md": ["tsdoc-coverage"]}。只有在项目的标准替换了附带的指导方针而非添加上下文时，才使用每条规则的docs字段。 -
对分开的标准使用数组形式。 一条规则可以多次运行，每次使用不同的 glob 和选项：
"max-file-size": [ {"include": ["src/**"], "options": {"maxKb": 256}}, {"include": ["assets/**"], "options": {"maxKb": 4096}} ] -
在遗留代码库上使用
--changed增量采用，而不是削弱规则。 立即检查新工作（npx vibator --changed，或在 CI 中使用--since origin/main检查整个 PR 的差异），同时逐步减少历史积压。对于有大量发现项的规则，临时使用warn：发现项仍可见但不阻塞构建。不要用off来表示“稍后处理”。 -
验证结果。 运行
npx vibator并确认：每个启用的规则都运行了（崩溃的规则是配置错误，其消息会指出缺少什么），剩余的发现项是真实的，并且npx vibator explain <rule>为你覆盖的任何内容显示了正确的指导方针。
在共享预设上构建
extends 接受以 . 开头或包说明符的路径，相对于声明它的文件进行解析。后面的条目覆盖前面的，并且文件自身的设置覆盖所有扩展。
{
"extends": ["@acme/quality/vibator.json"],
"rules": { "max-file-size": "warn" }
}
合并遵循 Biome 的行为，因此该工具栈的用户可以预期其工作方式。有两个需要正确理解的结果：
- 纯严重级别会保留所有其他内容。 在设置了
maxKb和include的预设上编写"max-file-size": "warn"只会更改严重级别；预算和 glob 会被继承。你无需重新声明它们，而重新声明正是项目悄然偏离预设的方式。 - 数组替换而非连接。 要向继承的
allow或patterns列表添加一个条目，请编写你想要的完整列表。这是有意为之：它使得移除继承的条目成为可能。
只编写差异部分。一个重复预设已说内容的配置与一个与之矛盾的配置无法区分，并且下一次预设更新不会触及你复制的字段。
一个以精选集合形式构建的预设会设置 "recommended": false 并列出它想要的规则。在这种预设下，未命名的规则不会运行，因此在断定某规则缺失之前请检查这一点。
指导方针路径的解析方式相同：预设声明的 docs 和 guidelines 条目相对于预设解析，因此发现项指向与其一起提供的文档。你自己的路径仍相对于项目根目录解析。
严重级别策略
error：确定性规则，误报率接近零。warn：可能对未见过的代码库判断错误的规则（env-example-sync匹配文本；prefer-array-methods无法区分数组和Set），以及拥有大量积压的规则在临时采用时。off：仅用于不适用的规则（没有语言环境意味着没有locale-parity），绝不用作通过的方式。
常见错误
- 编写
include从而丢失了规则的默认排除项（测试、.d.ts）。 - 在严重级别覆盖旁边重复预设的选项，以为纯严重级别会丢弃它们。实际上不会，并且复制的副本会停止跟踪预设。
- 启用了
codegen-drift却使用了需要环境不提供的服务或密钥的生成器。该规则会真正运行命令。 - 在
guidelines中将每个文档映射到每条规则。只映射那些实际陈述该规则的标准的文档。 - 编辑配置以结束失败的运行，而不是修复发现的问题。如果人类要求设置门禁，只有人类才能决定降低它。