gate

gate

让整个 nugehs 工具链给出一个可发布／不可发布的判定。

gate 会针对一个仓库运行 aiglare、 bouncer、 tieline 和 repoctx，并将它们各自的结果 整合为一个标准化判定。每个工具都会回答不同的“能否发布？”问题——gate 正是让它们最终 对答案达成一致的地方。

npx @nugehs/gate                      # audit the current repo
npx @nugehs/gate ./service --ci       # fail the build on a blocking verdict
npx @nugehs/gate --json               # the unified verdict, machine-readable

        ┌──────────────────────────────────────────────┐
        │                   gate                         │
        │   one config · one verdict · one report        │
        └──────────────────────────────────────────────┘
            │            │            │            │
        aiglare       bouncer      tieline      repoctx
       red/amber/    pass/fail/   matched/     PASS/WARN/
         green        unknown      drift         FAIL
            │            │            │            │
            └──── normalize to pass · warn · fail ─────┘
                          │
                  ✗ FAIL   ⚠ WARN   ✓ PASS

报告内容

  gate · /path/to/repo

  ✗  AI governance    fail      2 red · 1 amber · 13 green · 1 blocking side-effect
  ·  Compliance       skipped   not configured (run `bouncer init`)
  ·  Contract drift   skipped   not configured (run `tieline init`)
  ⚠  Merge readiness  warn      1 of 8 checks need attention

  verdict: FAIL — 1 blocking · 1 warn · 2 skipped

每个工具的原生结果都会统一转换为以下状态：

状态	含义
pass	检查已运行且未发现问题
warn	已运行，发现值得关注的问题——但不会阻止发布
fail	已运行，发现会阻止发布的问题
unknown	已运行，但无法确定——明确不代表通过
skipped	不适用／未针对此仓库配置
error	无法运行该工具，或工具返回了无效结果

顶层判定取实际运行的各个领域中最严重的状态（skipped 不计入）。unknown 和 error 会汇总为 warn，确保不会悄无声息地被当作通过。

各方结果如何映射

工具	原生信号	→ gate
aiglare	副作用接收端出现红色风险	fail；任何红色／琥珀色风险 → warn
bouncer	发现 fail（缺少必需控制项）	fail；任何 unknown 控制项 → unknown
tieline	drift > 0（FE 调用没有对应的 BE 路由）	fail；unverifiable > 0 → warn
repoctx	合并判定为 FAIL／BLOCK	fail；WARN → warn

gate 运行 aiglare 时不带 --ci，并自行得出阻止发布的判定， 这样工具就不会因在刷新管道前调用 process.exit() 而截断 提交给我们的报告。

没有检查任何内容，不代表通过。 如果所有领域都被跳过或取消选择 （例如，使用 --skip 跳过全部领域，或 --only 中存在拼写错误），gate 会报告 NO CHECKS RAN（ok:false），并在 --ci 下失败——配置错误不会 悄无声息地让 gate 变绿。

关于 repoctx + 本地模式。 repoctx 的合并就绪检查只能通过 GitHub 等主机 验证审核状态（批准、CODEOWNERS、必需检查）。在本地运行时，它会将这些状态报告为 WARN，因此在干净的本地仓库中，gate 经常会显示 merge readiness: warn。这是 repoctx 如实说明 它在本地无法检查的内容，并不代表你的更改有问题。

CLI

gate [path] [options]

  --json            Emit the unified verdict as JSON
  --ci              Exit non-zero when the gate fails (blocking by default)
  --strict          Treat WARN/UNKNOWN as blocking too
  --only <list>     Run only these tools (aiglare,bouncer,tieline,repoctx)
  --skip <list>     Skip these tools
  -h, --help        Show this help

gate mcp            Start the MCP server (stdio)

默认情况下，只有 fail 判定会在 --ci 下阻止流程——可放心采用，无需担心警告 淹没团队。希望警告也阻止流程时，可添加 --strict。

工具解析

gate 不会打包这四个工具；而是在运行时查找它们。每个工具都会按以下顺序查找，命中即停止：

1. GATE_<TOOL>_BIN 环境变量（显式指定的覆盖项）
2. 已安装的 @nugehs/<tool> 包（来自 node_modules）
3. 同级目录中的检出版本 ../<tool>（本地开发）

无法解析的工具会报告为 skipped，不会直接导致失败—— 因此，在只使用部分工具链的仓库中运行 gate 也很安全。

在 CI 中

- run: npx @nugehs/gate . --ci

如需机器可读的记录，--json 会输出完整判定（架构版本、 各领域结果、计数和阻止原因），可用于仪表板或审计证据。

MCP

gate 也是一个 MCP 服务，因此 Agent 可以通过一次调用询问“这个可以发布吗？”—— 获得统一的判定结果，而不是使用四个单独的工具。

gate mcp                 # stdio JSON-RPC server
npx @nugehs/gate mcp

工具：

工具	返回内容
gate_check	仓库的统一判定结果（path，以及可选的 only/skip/ci/strict）
list_checks	gate 执行的四项检查，以及每项检查所属的领域和回答的问题

注册清单：server.json（io.github.nugehs/gate）。

编辑器扩展

同一份标准化判定结果也驱动 VS Code / Cursor 扩展 （clients/vscode）——将 gate 从 CI 左移到 编辑器中：

• gate 自带 Activity Bar 容器中的判定控制台和检查树；
• 针对已定位问题的内联诊断、悬停提示、快速修复（静音 / 打开文档）和 CodeLens；
• 面向 AI 的门禁——@gate 聊天参与者、可在宣布“完成”前调用 gate_check 工具的 Agent 模式，以及 MCP 服务提供程序——因此，编写代码的 助手会接受与 CI 相同的 gate 检查；
• 保存时经防抖触发运行，并支持取消正在进行的运行和多根工作区。

路线图

gate 是共用的主干。同一份 JSON 已用于驱动 CLI、--ci 门禁、 MCP 服务以及上文的编辑器扩展。下一个基于同一份 JSON 的客户端：

• Web 控制台——基于 JSON 的仓库 / PR 判定面板，整合四个 *-web 网站。

许可证

MIT © Oluwasegun Olumbe