bot-gate:基于 Rust 生态的 CI/CD 质量门禁 CLI 项目

---

🤔 这是什么

BotGate 是 Rust 项目的质量门禁。它把格式、编译、Lint、测试、文档、供应链、覆盖率、代码度量和运行时检查组织为稳定流程，让本地与 CI 使用同一条命令、同一套判定规则和同一种报告契约。

每次运行交付两类结果：

结果	作用
门禁结论	区分阻塞性步骤的通过、失败、blocked、timed-out、skipped 与 planned。
审计证据	保存结构化报告、开发者摘要、逐步骤日志和 CI 投影。

BotGate 是门禁事实来源：它负责运行检查并确定最终状态。RustBot Skills、Agent 或其他诊断工具可以读取报告解释并修复问题，但不能覆盖门禁结论。

内置场景配置从快速反馈逐步扩展到发布前深度验证；项目特有规则则通过 bot-gate.toml 中的自定义任务 DAG 接入。阻塞性步骤决定报告和进程退出状态，非阻塞性步骤保留发现证据而不单独使门禁失败。

场景配置	使用时机	核心检查
fast	本地快速反馈	fmt、check、clippy、metric
pr	PR / 合并阻塞门禁	fast、test、doc-test、doc-check、供应链
nightly	定时发现	pr、coverage、doc-test、doc-check、Fuzz
deep	发布前或重大变更	pr、coverage、doc-test、doc-check、Miri、sanitizer、Valgrind
unsafe	unsafe / FFI 专项	平台可用的运行时分析工具
custom	项目自定义流程	[[tasks]] 声明的 DAG

---

🛠️ 安装

BotGate 自身需要 Rust 1.89+、edition 2024 和 Cargo。

项目工具链同样推荐 rustc 1.89+；低版本会提示 warning，--strict 模式下阻断。

从 crates.io 安装当前版本：

cargo install bot-gate --version 1.4.0 --locked
bot-gate --version

不同场景配置依赖的工具不同。安装后可检查当前场景的就绪状态：

bot-gate tools check pr

从源码安装：

git clone https://gitcode.com/xuanwu/bot-gate.git
cd bot-gate
cargo install --path . --locked

更新到 stable 最新版或只预览更新计划：

bot-gate update
bot-gate update --dry-run --format json

核心 CLI、Cargo 检查、报告和更新路径支持 Linux、macOS 与 Windows。不同平台对 Miri、sanitizer、Valgrind 等运行时工具的支持不同；tools check 和 doctor 会给出当前机器上的真实能力，而不是按平台名称推测。

---

🚀 快速开始

进入 Rust 项目或工作区，先运行本地快速门禁：

bot-gate run fast

提交 PR 或接入 required gate 时：

bot-gate run pr --locked

不在目标项目目录时显式指定路径：

bot-gate run pr --project /path/to/project --locked

需要先确认会执行什么，而不启动命令：

bot-gate plan pr --format markdown

运行结束后先看终端结论，再按需打开 .botgate/report.md；自动化与 Agent 应读取 .botgate/report.json 和 .botgate/artifacts.json。失败时可使用：

bot-gate report explain <STEP>
bot-gate report fix-plan

如果只记住四个命令：

场景	命令
本地快速反馈	bot-gate run fast
PR 阻塞门禁	bot-gate run pr --locked
定时问题发现	bot-gate run nightly
发布前深度验证	bot-gate run deep

---

🗺️ 能力地图

flowchart LR
    A[fast<br/>fmt + check + clippy + metric] --> B[pr<br/>test + doc-test + doc-check + supply chain]
    B --> C[nightly<br/>coverage + doc-test + doc-check + fuzz]
    B --> D[deep<br/>coverage + doc-test + doc-check + runtime analysis]
    E[unsafe<br/>risk audit] --> D
    F[custom task DAG] --> G[project-specific gate]
    A --> H[统一报告与退出码]
    B --> H
    C --> H
    D --> H
    G --> H

能力	BotGate 如何处理
统一执行	类型化命令树负责解析、帮助生成和命令分发，选项只在实际生效的作用域出现。
工具就绪状态	区分已安装、必选、可选和平台不支持，并在安装后复查版本或帮助信息。
自定义任务	支持依赖、输入、产物、缓存和阻塞策略；未知依赖与循环在执行前拒绝。
Nightly Fuzz	自动发现 cargo-fuzz target，为每个 target 固定预算、资源、corpus、artifact 和复现证据。
资源调度	用固定工作线程池、DAG 就绪队列与 CPU/内存/I/O/网络/Cargo 预算控制并发。
诊断归一	把测试、文档、Clippy、供应链、metric 和运行时工具投影为同一诊断模型。
机器边界	JSON、JSONL、TOML 独占 stdout；人类可读输出、Markdown、SARIF、JUnit 等从统一 UI 边界生成。
Agent 路由	报告携带状态、原因、位置、owner、推荐 Skill 和 MCP tool。

---

🧭 命令与配置

常用命令

常用入口按任务组织：

任务	命令
执行或预览	run、plan
工具准备	tools list/check/install、doctor
阅读结果	report show/explain/fix-plan/compare/history
配置管理	config init/validate/effective/explain/schema/web
安装维护	update、completions、man

实时参数与默认值以 bot-gate <command> --help 为准，完整命令参考见命令行指南。

最小配置

配置不是第一次运行的前提。团队准备固定的默认策略时，可生成并校验 bot-gate.toml：

bot-gate config init --preset ci
bot-gate config validate bot-gate.toml
bot-gate config explain

最小配置通常只需要声明场景配置与可复现选项：

profile = "pr"
features = "default"
all-targets = true
locked = true
jobs = 4

自定义任务

项目命令可声明为自定义任务：

profile = "custom"

[[tasks]]
name = "unit"
program = "cargo"
args = ["test", "--lib", "--locked"]
inputs = ["src/**/*.rs", "Cargo.toml", "Cargo.lock"]

[[tasks]]
name = "package"
program = "cargo"
args = ["package", "--locked"]
depends-on = ["unit"]

program 与 args 直接交给操作系统，不解析 shell 管道、重定向、变量展开或 &&。完整字段、缓存语义与优先级见配置和自定义任务。

自定义任务支持在单次运行中临时传入或替换参数，不修改项目配置。单任务可在 -- 后传递原始参数；多个任务可用重复的 --task 参数块分别传参：

bot-gate run <task> -- <arg>...
bot-gate run --task <task-a> --task-arg=<value> \
  --task <task-b> --task-args-json='["<value>"]'

BotGate 自己的选项放在 -- 之前；参数只对本次运行生效，并按原始 argv 传给对应任务。

Nightly Fuzz

Nightly 会把 cargo-fuzz 作为一等组件运行；Deep 默认不包含 Fuzz，可通过 profile-components-add = ["fuzz"] 显式加入。存在标准 fuzz/Cargo.toml 时 target 自动发现；通常只需要固定每个 target 的预算：

profile = "nightly"

[fuzz]
max-total-time-secs = 60
input-timeout-secs = 10
sanitizer = "address"
jobs = 1

cargo install cargo-fuzz --version 0.13.2 --locked
bot-gate tools check fuzz
bot-gate run fuzz

可写 corpus、编译目录和 crash artifact 位于 .botgate/fuzz。旧项目没有 Fuzz 工程时，隐式 Nightly 明确跳过；显式 run fuzz 和严格模式 fail-closed。完整配置、平台和复现语义见配置中的 Nightly Fuzz。

---

📦 报告与 CI

默认产物位于 .botgate/：

产物	用途
report.json	完整机器契约、门禁状态和 Agent 路由证据。
report.md	面向开发者和评审者的摘要。
artifacts.json	报告、日志和其他产物的位置、状态与校验信息。
events.jsonl	按时间记录执行事件。
logs/	保存每个步骤的原始 stdout/stderr。
history/	支持历史趋势和报告比较。

人类输出默认对每个步骤最多展示 25 条失败详情，并指向完整证据；可通过 --output-item-limit <N> 或配置项 output-item-limit 在 1..=1000 内调整。机器报告、SARIF、annotations、JUnit、artifacts 和原始日志不受该展示上限截断。没有源码位置时不会伪造位置。

BotGate 1.3.3 的 Report、artifact、baseline、command-plan 和配置 Schema 使用 1.3.3；读取端继续兼容既有 1.2.0、1.3.0、1.3.1 和 1.3.2 契约。metric 集成推荐 BotMetric 1.2.3，同时兼容其 analysis-report-1.2.3.json、已发布的 1.2.2、1.2.1、1.2.0 和无版本报告 URI。1.2.3 的结构化 compiler_diagnostics 会与既有 metric diagnostics 一起投影；有位置和无位置诊断都会保留，未知位置类型会拒绝。消费者必须显式校验支持的版本，不能通过改写版本号混用旧报告。

check 默认将 Cargo 结构化 rustc warning 视为阻断性门禁结果；报告保留诊断原始 level = warning 和真实命令退出码，步骤与 Gate 状态会据此失败。

退出码

自动化应同时读取退出码和 .botgate/report.json，不要解析人类可读文本：

• 0：通过
• 1：阻塞性命令失败
• 2：CLI、配置或契约错误
• 3：blocked 或 timed-out
• 4：skipped 或 planned

CI 中建议让 PR 只运行确定性的阻塞性门禁，把依赖网络、nightly 和平台敏感检查拆为独立作业，并始终保存 .botgate/：

- run: cargo install bot-gate --version 1.4.0 --locked
- run: bot-gate run pr --locked --sarif --junit
- uses: upload-artifact
  if: ${{ always }}
  with:
    name: bot-gate-report
    path: .botgate/

平台运行器、工具版本、缓存和产物保留策略由接入方负责。完整 CI、报告与 Schema 约定见报告与数据契约和CI 与工程质量。

---

📚 文档

入口	适合解决的问题
使用手册	从安装到门禁接入的完整阅读路径。
安装与第一次运行	准备 CLI、工具和首个场景配置。
命令行指南	查询完整命令、参数与输出限制。
配置项目策略	固定组件、功能特性、文档、Fuzz、缓存和资源规则。
自定义任务	建模 DAG、输入、产物与阻塞策略。
工具与平台	理解就绪状态和平台能力。
报告与契约	接入 JSON、Schema、日志和退出码。
资源感知调度	调整并发、预算与 Cargo 双层调度。
诊断系统	理解组件错误以及人类可读与机器可读投影。
v1.2.3 发布说明	check warning 阻断、诊断去重与可配置输出条目。
v1.3.0 发布说明	配置 Web 面板、Profile Overlay 与配置 Schema 1.3.0。
v1.3.1 发布说明	Nightly Fuzz 一等公民、有限预算执行与结构化证据。
v1.3.2 发布说明	BotMetric 1.2.2、Fast 最小门禁策略、受管 C 风险函数与 Web 配置适配。
v1.3.3 发布说明	Doc Test、Doc Check 与分层文档质量门禁。
v1.3.4 发布说明	文档诊断边界与 missing-docs 默认阻断策略。
v1.4.0 发布说明	默认配置文件名、BotMetric 1.3 默认策略与 Max Clippy 策略更新。

官方仓库位于 GitCode。安全问题请按照 SECURITY.md 的私密报告流程提交。