Boardreadyops

BoardReadyOps 可检查 KiCad 项目、生成制造产物，并将检查结果和校验和打包为放行证据包。签名是可选的；校验和及自行报告的源指纹不能单独证明导出的 Gerber/Excellon 文件来自经过审查的提交。请参阅源到导出文件的溯源契约和 issue #771。CLI 和 GitHub Action 支持 JSON、SARIF、Markdown、HTML、JUnit 及工作流注释输出。

• 不能取代 KiCad DRC/ERC：除原生 kicad-cli DRC/ERC 检查外，还会检查 BOM 生命周期、封装一致性、引脚映射契约和供应商预检。
• 不必取代 KiBot：可独立运行，也可与 KiBot/产物自动化工具配合使用，增加治理、PR 硬件差异比较、可选的签名证据清单及交接包。
• 源代码处理本地优先：CLI 命令和目标仓库中的 GitHub Actions 工作流会在你自己的环境中处理 KiCad 源代码。托管功能可能会保留运行元数据、规范化检查结果和链接；启用前，请查看文档中说明的数据处理方式和执行边界。

Generate → Validate → Decide → Package → Optional Attestation → Review → Handoff

安装

npm i -g boardreadyops

仓库中准备的版本： [email protected]。这是此源代码修订中的软件包版本，并不表示该版本已发布。 请查看 npm 和 GitHub Releases，了解最新的公开版本。安装前，请验证所选版本的二进制文件、 SHA256SUMS、SBOM 及运行时兼容性。历史验证快照和待处理事项请参阅 发行渠道验证。

运行时支持

BoardReadyOps 仅支持 Node.js 24 LTS。不再支持或通过 CI 测试更早的 Node 主版本。我们会跟踪 Node.js 26 Current，但在其达到 LTS 且完成依赖项验证之前，不会将其列入 engines.node 支持范围或纳入 CI。

KiCad CLI 兼容性已在 KiCad 10.0 上通过 CI 测试，最新验证的补丁版本为 10.0.6。KiCad 9.0 仍是最低支持版本，但上游已宣布其 EOL，因此不再通过 CI 测试。机器可读的政策和生成的支持表位于 docs/support-matrix.md。

通过脚本安装

当所选 GitHub Release 包含匹配的二进制资源和 SHA256SUMS 时，Linux 和 macOS 发布版二进制文件会通过可验证校验和的 shell 安装程序进行安装：

curl -fsSL https://raw.githubusercontent.com/oaslananka/boardreadyops/main/install.sh | sh

Windows x64 发布版二进制文件使用相同的发布资源和校验和流程：

irm https://raw.githubusercontent.com/oaslananka/boardreadyops/main/install.ps1 | iex

安装程序会下载发布资源和 SHA256SUMS，然后将 boardreadyops 放入本地命令路径。二进制资源是否可用取决于具体发布版本；请查看最新发布版本，了解当前资源列表。相同二进制资源的 Homebrew 公式模板位于 Formula/boardreadyops.rb；该模板会使用 SHA256SUMS 中已发布的 macOS 和 Linux 校验和进行填充。 这些安装程序已通过验证，可用于包含完整二进制资源列表、SHA256SUMS 和 SBOM 的最新发布版本。发布 Tap 仍有待维护者跟进。

定位

BoardReadyOps 提供两种使用模式：

端到端流水线 — 使用 boardreadyops generate 通过 kicad-cli 生成 Gerber 文件、钻孔文件、BOM、CPL/位置文件和 PDF，然后使用 boardreadyops release prepare 进行验证、打包证据并生成签名的发布决策。

仅验证门禁 — 使用 KiBot 或其他生成器生成制造输出，然后使用 BoardReadyOps 验证这些输出是否存在、是否与 KiCad 项目匹配、是否符合供应商/配置要求，以及是否能够支持可重复的发布决策。

有关流水线拆分方案，请参阅 Release readiness and KiBot integration；有关 v2 功能，请参阅路线图。

快速开始

# Validate existing manufacturing outputs
boardreadyops check .
boardreadyops plan . --format json > build/agent-plan.json

# Generate artifacts and prepare a full release
boardreadyops generate . --profile jlcpcb
boardreadyops release prepare . --profile jlcpcb --output build/release

# Verify a release bundle and create a vendor handoff package
boardreadyops release verify build/release
boardreadyops handoff create build/release --profile jlcpcb

# Optional: export actual Gerber/Excellon bytes as an unsigned, locally verified ZIP
# Requires KiCad CLI 10, exactly one PCB project and a clean checkout; ignore build/ in Git
boardreadyops release archive . --reviewed-source-sha "$(git rev-parse HEAD)"

release archive 命令会验证本地源文件和输出文件的字节内容，并报告生成的 ZIP 校验和。它不会生成可信的工作流证明、加密签名、供应商签署或云交付链接。

如果 npm 能解析该软件包，npx boardreadyops --help 也可以正常使用。

GitHub Action

name: BoardReadyOps

on:
  pull_request:
  push:
    branches: [main]

jobs:
  boardreadyops:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: oaslananka/boardreadyops@9bc8a075d885ad1182e2ad4fcd4c9160f8160c94 # v1.31.2
        with:
          config: boardreadyops.yml
          mode: enforce
          fail-on: high

为确保可复现性，示例固定使用经过审查的 v1.31.2 发布提交。 浮动的 v1 别名便于选择自动接收次要/补丁更新，但随着稳定版本发布，该别名会指向不同版本。

上传 SARIF 需要 security-events: write。发布请求评论需要 pull-requests: write。

如果工作流应在 BoardReadyOps 运行时中携带 KiCad CLI，而不是单独安装 KiCad，请使用完整容器 Action：

      - uses: oaslananka/boardreadyops/apps/container@9bc8a075d885ad1182e2ad4fcd4c9160f8160c94 # v1.31.2
        with:
          config: boardreadyops.yml
          require-kicad: "true"
          mode: enforce

同一镜像也可作为 CLI 运行：

docker run --rm ghcr.io/oaslananka/boardreadyops-full:v1 --help

v1 和 latest 容器标签会指向最新发布的镜像。请查看发布渠道验证，了解当前摘要和清单列表。

可复现演示

在连接代码库之前，请先查看已签入的黄金演示源文件。 损坏的电路板包含五项问题，会阻止发布；修复后的电路板则解决了这些问题。

boardreadyops run examples/golden-demo/broken
boardreadyops run examples/golden-demo/fixed

这些是可复现的源文件测试夹具，并非托管在外部的拉取请求。有关预期证据和决策，请参阅黄金演示演练。

CLI

boardreadyops run --json build/findings.json --sarif build/findings.sarif.json .
boardreadyops check .
boardreadyops check manufacturing.jobset-outputs .
boardreadyops plan . --format json
boardreadyops doctor
boardreadyops schema config

boardreadyops plan 是面向编码和硬件 Agent 的机器可读工作流。它会输出 JSON 操作，其中包含问题证据、修复步骤、安全自动修复标记和验证命令，让 Agent 无需抓取人工报告即可修复 KiCad、BOM、引脚映射、制造输出或发布元数据问题。请参阅 Agent 规划输出。

npm 包会从已提交的 CLI 构建包 dist/cli/index.cjs 中提供 boardreadyops 二进制文件。

配置

创建 boardreadyops.yml：

version: 1
mode: warn
projects:
  - path: .
    pinmap: firmware/pins.yml
    bom: bom/board.csv
    variants:
      - name: production
        bom: bom/prod.csv
rules:
  bom.missing-mpn:
    enabled: true
    severity: high
    ignore-refs: ["TP*", "FID*"]
  bom.variant-consistency:
    enabled: true
  manufacturing.jobset-outputs:
    enabled: true
  manufacturing.outputs-present:
    enabled: true
    required: [gerber, drill, position, pdf]
fail-on: high
report:
  sarif: build/boardreadyops.sarif.json
  json: build/boardreadyops.findings.json
  markdown: build/boardreadyops.report.md
  html: build/boardreadyops.report.html

配置架构已提交至 schemas/config.schema.json。

支持的检查

• KiCad DRC 和 ERC 报告规范化。
• BOM 完整性、生命周期、DNP 一致性、变体一致性和封装不匹配检查。
• 引脚映射格式、冲突、未映射引脚和网络标签检查。
• 制造输出、钻孔覆盖率、制造说明、拼板合理性、层叠和作业集检查。
• 设计外形和铜箔平衡检查。
• 发布修订版本、版本格式、标签和变更日志检查。

本地开发

corepack pnpm install --frozen-lockfile
corepack pnpm run lint
corepack pnpm run typecheck
corepack pnpm run test
corepack pnpm run build
corepack pnpm run verify:dist
corepack pnpm run docs

本仓库有意将 dist/action/index.cjs 和 dist/cli/index.cjs 纳入版本控制，以便 GitHub Action 和 npm 包无需用户构建即可运行。

路线图

BoardReadyOps 正从验证关卡发展为完整的硬件发布操作系统。请参阅 docs/ROADMAP.md 了解里程碑计划，参阅 Public Roadmap Project 了解当前执行情况，并参阅 issue #191 了解路线图的排序安排。

链接

• 仓库：https://github.com/oaslananka/boardreadyops
• 问题：https://github.com/oaslananka/boardreadyops/issues
• 公开路线图：https://github.com/users/oaslananka/projects/21
• 路线图排序：https://github.com/oaslananka/boardreadyops/issues/191
• 安全公告：https://github.com/oaslananka/boardreadyops/security/advisories/new

许可证

当前由项目编写的源代码依据 PolyForm Noncommercial 1.0.0 许可。商业用途需要单独的书面许可；请参阅 商业许可。早期的 MIT 版本仍保留发布时适用的 MIT 权利；请参阅 许可信息。

第三方声明会生成在 NOTICE 中。完整容器镜像会依据适用的 GPL 条款再分发 KiCad，并在镜像中保留 KiCad 许可证文本。