brevio-core

brevio-core

在合并前捕获编码 Agent 反复犯的错误：无需调用模型或 API 密钥的拉取请求门禁。

将以下内容保存为 .github/workflows/brevio-core.yml：

name: brevio-core
on:
  pull_request:
  merge_group:
permissions:
  contents: read
  pull-requests: write     # the comment on the pull request
  security-events: write   # the upload to code scanning
jobs:
  brevio-core:
    name: brevio-core
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          fetch-depth: 0
      - uses: Brevio-Ventures/[email protected]
        with:
          sarif: true

它能捕获代码审查中反复发现的 Agent 编写代码问题：

• 将密钥写入源代码、对输入使用 eval，以及对外部数据进行 any 类型断言；
• 用 @ts-ignore 屏蔽类型错误，以及捕获后丢弃异常；
• 端到端测试中使用固定时长的休眠、图片缺少替代文本，以及键盘无法触发的点击处理程序。

无需 API 密钥，也不调用模型。scan、Agent 钩子和 MCP 服务均不使用网络，也不会发送任何内容。

这些是针对变更所添加行的逐行模式检查，不是 AST 或数据流分析。规则目录包含 123 条规则：brevio-core scan 检查 8 条已扫描规则；另外 115 条是文档化规则， 供审查和 Agent 参考，目前此软件包还没有对应的扫描器。每条发现都会链接到其 规则页面，说明它捕获的问题、原因，以及错误和正确示例。

无需安装即可运行

版本 0.6.0，要求 Python 3.10 或更高版本，无运行时依赖。在代码仓库中扫描变更所添加的行：

uvx [email protected] scan --diff

pipx run --spec brevio-core==0.6.0 brevio-core scan --diff

或者先安装，再以相同方式运行：

pip install brevio-core==0.6.0

brevio-core scan --diff

也可以从 GitHub 发布页下载 brevio-core.pyz，确认其构建来源， 然后使用任意 python3 运行：

gh attestation verify brevio-core.pyz --repo Brevio-Ventures/brevio-core
python3 brevio-core.pyz scan --diff

若要扫描整个文件，请指定文件名；若不指定，则扫描当前文件夹：

brevio-core scan

一步完成设置

brevio-core init --dry-run

--dry-run 会以差异形式显示 brevio-core init 将写入的内容，但不会写入任何内容。init 会写入一个类似上方的拉取请求 工作流（固定到此版本）、一段写入 AGENTS.md 的 Agent 规则，以及一个基线文件，使得 首次本地运行不会产生发现项。--with precommit,hook,mcp 会添加 pre-commit 配置项、Agent 钩子和 MCP 服务 配置。它会在写入前询问（--yes 可跳过询问），绝不重写已有文件，并在 .brevio/init.json 中记录写入的内容；brevio-core init --undo 会移除它写入且你未曾修改的内容。

在已有发现项的代码仓库中采用

brevio-core baseline                 # record the findings the repository has now in .brevio/baseline.json
brevio-core scan                     # report only the findings that are not in the baseline
brevio-core scan --fail-on none      # report them but never fail, for a trial week
brevio-core scan --fail-on all       # leave the baseline out: every finding fails

基线条目记录文件、规则和该行文本的哈希，而不是行号，因此移动某一行不会让它变成新发现项。提交此文件。修复后再次运行 baseline，已修复的条目便会消失。文件每行保存一个条目，并按顺序排列，因此不同分支添加的条目可以顺利合并。

有理由地忽略一条发现项

// brevio-core: ignore R9.2 -- the generated client has no type for this field
// @ts-ignore

注释写在对应行或上一行，用于忽略该行上的规则。没有 -- reason 就不会生效，扫描也会对此发出警告；若规则 ID 不存在，也会发出警告。汇总行会统计被忽略的数量，SARIF 会将每条忽略记录及其理由作为抑制项携带，供代码扫描工具显示。

只有人可以忽略门禁。Agent 钩子和 MCP 工具从不接受忽略注释 （--forbid-ignores）；差异扫描会将变更新增的每条忽略注释和基线条目报告为发现项，并标记为“新增抑制项：需要人工审查”，直到审查者通过 --allow-new-suppressions 批准。

为拉取请求生成报告

brevio-core scan --diff origin/main --format markdown 会将发现项打印为 Markdown 表格，列出规则、文件和行号， 以及原因，供作业摘要或拉取请求评论使用。--rules-url BASE 会将每个规则 ID 链接到 BASE 后接该 ID 的规则页面。代码仓库中的路径和行号都会经过转义，因此文件名无法添加提及或链接。

为团队配置

在仓库根目录放置一个 brevio-core.toml，并在任何需要单独设置的文件夹中再放置一个。对于某个文件，从根目录到其所在文件夹的配置文件会依次生效，因此离文件最近的配置优先。

extends = "policy/brevio-core.toml"   # an org policy, read first (see below)
select = ["R9", "R13.1"]              # the rules that run: an ID, a group or a glob (default: every rule)
ignore = ["R6.3"]                     # rules that do not run
exclude = ["generated/**", "*.pb.ts"] # paths not scanned, relative to this file's folder
level = "warn"                        # the level of every rule (default: error)

[rules."R13.1"]
level = "error"                       # the level of one rule

[[overrides]]
paths = ["legacy/**"]                 # relative to this file's folder
ignore = ["R9.1"]                     # rules that do not run on these paths
rules = ["R9"]                        # the rules the level applies to (default: every rule)
level = "warn"

较近的配置文件会替换 select 和 ignore；exclude 和 [[overrides]] 会累加；对于同一层级，最后一个指定规则的设置生效。未知键、错误的值或格式有误的文件会导致扫描以用法错误停止，而匹配不到任何规则的规则模式会发出警告。将规则 ID 写成带引号的表名，例如 [rules."R13.1"]。

每次扫描都会跳过项目保留但并非自行编写的代码：依赖项和构建产物（node_modules/、dist/、build/、.next/、虚拟环境）、供应商目录（vendor/、third_party/、third-party/）、压缩文件（*.min.js、*.min.mjs、*.min.cjs、*.min.css）、打包分块（*.chunk.js、*.bundle.js、chunk-*.js，以及以十六进制哈希结尾的名称，例如 index-<hash>.js），还有前两行长度超过 500 个字符的任何文件。通过命令行指定的文件会按要求进行扫描。无论是否通过名称指定，规则都不会读取 TypeScript 声明文件（*.d.ts、*.d.mts、*.d.cts）：其中只有类型，没有可运行的代码。使用 exclude 排除更多内容，例如生成的代码或使用其他名称的第三方目录。

brevio-core config src/app.ts 会显示适用于某个文件或文件夹的配置：配置来源文件、是否已排除，以及其中会运行的每条规则及其级别和状态（供工具使用时加上 --json）。

brevio-core scan --fail-on error（在 Action 中使用 fail-on: error）只会因错误级别的发现而失败，并会报告警告级别的发现；默认值 --fail-on new 则会因任何新的发现而失败，不论其级别如何。预览规则不会导致扫描失败（参见 RULES-STABILITY.md）。配置可以关闭规则，因此，差异扫描会将新增或修改 brevio-core.toml 的变更报告为新的抑制项，处理方式与忽略注释相同。

使用 extends 设置组织策略

extends 会先读取策略文件，再读取指定该策略的文件；策略中的路径相对于策略文件所在的文件夹。

• extends = "policy/brevio-core.toml"：签入仓库的文件，由你自己的历史记录固定版本。
• extends = "policy@<commit SHA>"：处于该提交的 Git 检出文件夹，例如子模块。
• extends = "<git URL>@<commit SHA>"：.gitmodules 中 URL 与该 URL 相同、且处于该提交的子模块。

extends 只会读取检出中已有的文件：brevio-core 不会获取策略（scan、Agent 钩子和 MCP 服务均不使用网络，也不会发送任何内容）。如果检出缺失或处于其他提交，扫描会停止并说明原因；运行 git submodule update --init 即可修复。要切换到新策略，请在同一个拉取请求中更新子模块和 SHA。

推出使用

1. 观察。 在 CI 中运行一周 brevio-core scan --fail-on none：报告所有问题，但不会导致失败。
2. 对新增问题发出警告。 运行 brevio-core baseline 记录现有问题，在 brevio-core.toml 中设置 level = "warn"，并运行 --fail-on error：新的发现会显示在拉取请求中，但不会阻止合并。
3. 阻止新增问题。 将你信任的规则逐一提高到 level = "error"，或者使用 [[overrides]] 指定已准备就绪的路径。这些规则发现的新问题现在会导致检查失败。
4. 收紧策略。 修复基线条目，然后再次运行 brevio-core baseline 将其移除；将最后几条规则提高到错误级别，接着恢复默认的 --fail-on new。

GitHub Enterprise Server

该工具可配合从 GitHub 发布版本获取并签入仓库的 .pyz 使用，也可配合 PyPI 镜像安装 pip。此功能未经测试：目前还没有人在 GitHub Enterprise Server 上运行过它。

在你的 Agent 中使用

三种方式，全部在本地运行：不调用模型，也不需要 API 密钥。

将扫描接入你的编码 Agent。 在项目文件夹中：

brevio-core hook install

它会查找在文件夹中或计算机上配置的编码 Agent，并为每个 Agent 接入扫描，因此每次编辑都会根据规则进行检查。它还会安装 Agent 技能（skills/brevio-core/SKILL.md），告诉 Agent 何时运行命令以及如何解读发现的问题。它会替换任何较旧的技能文本，重复运行也不会造成任何变化。

将其作为 MCP 服务运行。 将以下内容添加到任何支持通过 stdio 使用 MCP 服务的客户端的 mcpServers 块中（不同客户端的设置文件不同，但结构相同）：

{
  "mcpServers": {
    "brevio-core": {
      "command": "brevio-core",
      "args": ["mcp"]
    }
  }
}

如果未进行全局安装，请使用 "command": "uvx" 和 "args": ["[email protected]", "mcp"]。在项目文件夹中启动客户端：服务只会读取该文件夹。可用工具包括 scan（扫描路径或指定 diff 基准）、explain（指定规则 ID，返回规则页面）、list_rules 和 learn（将已修复的缺陷编译为防护规则）。

从修复中学习。 brevio-core learn 会将上一次修复转化为防护规则。有关 learn、hook install、gain、add 和 mcp，请参见 docs/agent-tools.md。

ESLint、Biome 和 typescript-eslint 未覆盖的内容

代码检查工具会检查代码的编写方式：语法、类型和风格。Agent 常犯的一些错误对它们来说都是合法代码，而这些规则正是用来查找这类问题的。请参阅规则页面：

与 ESLint、Semgrep 和 CodeQL 相比

brevio-core 可以补充它们；请继续使用它们。

• 它们的优势。 它们会解析代码，因此可以识别类型、语法树，以及 Semgrep 和 CodeQL 中跨行、跨文件流动的数据。它们的规则多得多，编辑器集成也更完善。brevio-core 会逐行匹配你新增代码中的模式，因此可能漏掉分散在多行中的错误，也可能将上下文中其实没有问题的行标记出来。
• 它带来的功能。 根据编码 Agent 反复犯的错误挑选规则；在每次编辑后运行扫描的 Agent 钩子；Agent 可以调用的 MCP 服务；可将一次修复转化为本地防护规则的 learn；以及为人和 Agent 编写的规则说明页面。无需配置，也没有依赖项。

使用

brevio-core scan src/                 # files or folders
brevio-core scan --diff origin/main   # only the lines added against a base
brevio-core scan --diff --sarif out.sarif

没有发现问题时，退出代码为 0；有发现时为 1；用法错误时为 2。

修复有唯一正确修复方式的问题

brevio-core scan --fix --dry-run    # print the fixes as a unified diff, write nothing
brevio-core scan --fix              # rewrite the files in place, then scan again
brevio-core scan --fix --diff main  # fix only the lines your change adds

只有在某条规则存在唯一正确的改写方式时，才会提供修复器；修复由代码执行，从不使用模型：@ts-ignore 注释会改为 @ts-expect-error，而不带参数的 Python except: 会改为 except BaseException:，两者捕获的内容相同。其他所有发现都会报告并留给你处理，尤其是硬编码密钥。命令会显示已修复和仍未解决的问题，只要还有未解决的问题就会失败。再次运行不会产生任何变化。MCP 服务还提供 fix 工具，返回相同的 diff，并且只有在收到请求时才会写入。

GitHub Action

顶部的工作流会扫描拉取请求新增的代码行。它会将报告写入作业摘要，并在更改的文件中标记每个发现的问题。设置 pull-requests: write 后，只要还有问题，它就会更新拉取请求中的一条评论；问题全部解决后，会将评论标记为已解决。来自 fork 的拉取请求只会获得摘要。设置 sarif: true 和 security-events: write 后，它会将发现的问题上传到代码扫描。无需密钥，也不需要 API 密钥。标签 v0.6.0 会准确运行 brevio-core 0.6.0。若要始终跟进每次发布，请写入 uses: Brevio-Ventures/brevio-core@v0；若要固定到某个提交，请参见 SECURITY-REVIEW.md。它会在 pull_request、merge_group 和 push 事件上运行，并拒绝其他事件。

pre-commit

repos:
  - repo: https://github.com/Brevio-Ventures/brevio-core
    rev: v0.6.0
    hooks:
      - id: brevio-core

规则

每条规则在 docs/rules 下都有一个页面，介绍它会捕获什么、原因是什么，以及应改用什么写法。

本项目不作出的声明

此版本未发布任何基准测试。待有可复现的基准测试后，其方法和数据将与测试结果一同发布。

问题与支持

请在 GitHub Discussions 中提问并提出规则建议；如需报告 Bug 和误报，请使用相应表单提交问题。我们会尽力提供支持，并在一周内首次回复 （SUPPORT.md）。

项目

• 安全审查：供安全团队了解它会运行、读取和写入哪些内容
• 贡献指南（需要签署确认），介绍此仓库的导出方式以及贡献如何回流
• 治理：哪些内容会保持开放，以及如何添加维护者；下一版本的路线图
• 安全
• 隐私
• 行为准则
• 商标政策

由 Brevio 制作。