## 一、背景：判定阶梯与「校验为什么要代码」

ecocompute-mlcube 是一个 LLM 推理能耗测量容器：钉死库版本、10 Hz 直读 NVML 功率、梯形积分算能耗，再用差分法把「模型加载的能耗」和「推理的能耗」分开。每份报告（`energy.json`）都要过一道校验，校验器给三级判定，故意分开命名：
- **schema-valid**：过 `schema/energy.schema.json` 结构校验

- **protocol-conformant**：结构对，且每条协议 v1.1 MUST 都成立（`--profile v1.1-core`）

- **dataset-eligible**：再叠加可入数据集的附加项（`--profile dataset-eligible`）

为什么 JSON Schema 不够？因为协议的核心约束是**跨字段的语义**：「`basis: measured` 的报告必须 `measurement_source: direct-nvml`」「NF4 报告必须携带同会话同卡的 FP16 基线臂」「thermal 块必须存在且诚实」——这些是 MUST，不是结构描述，Schema 表达不了。校验器用条款号报错（`[§4.1.4] basis: measured requires measurement_source: direct-nvml`），退出码也是阶梯式的：0 合规 / 1 结构对但有违规 / 2 结构就错 / 3 用法错误。
这个项目有一套社区复现飞轮：外部贡献者在自己 GPU 上跑容器、把报告提交到复现画廊、归档进数据集。提交的前提是报告至少 `protocol-conformant`。于是需求自然浮出水面：**复现者的仓库里应该有个 CI，push 报告文件就自动验，别等到提交时才被维护者打回**。校验器出 CI 版，就是把它包成一个可复用 GitHub Action。
## 二、第一个分岔：docker action 还是 composite action

GitHub Action 包装「一个已经容器化的工具」，最顺手的方案是 docker action——`runs: using: docker`，镜像一给，`args` 一接就完事。仓库里也确实有一个现成的、已发布到 ghcr 的官方镜像。
但先算一笔账。这个镜像是 CUDA + torch 的**约 10 GB** 级别——`publish-image.yml` 自己构建它时，都得先执行一步「Free disk space」：把 runner 预装的 Android SDK、.NET、Haskell 工具链整个删掉腾地方。一个外部复现者在自己仓库的 CI 里用这个 Action，意味着**每次 push 拉 10 GB 镜像，只为校验一个几十 KB 的 JSON**。GitHub 托管 runner 的磁盘和带宽撑得住几次先不说，这个体验本身就是灾难。
而校验器的真实依赖是什么？看代码：`tools/validate.py` 只 import 了 `jsonschema`，其余全是标准库；schema 路径用 `__file__` 相对解析（`REPO / "schema" / "energy.schema.json"`）。也就是说，**校验和测量是两个完全不同的工作负载**：测量需要整个 10 GB 的 CUDA 栈，校验只需要一个 Python 加一个 pip 包。
结论：composite action，四步：
runs:
  using: composite
  steps:
    - name: Check out the validator (tools/validate.py + schema)
      uses: actions/checkout@v7
      with:
        repository: hongping-zh/ecocompute-mlcube
        ref: ${{ inputs.validator-ref }}
        path: .ecocompute-validator
        persist-credentials: false
    - name: Set up Python
      uses: actions/setup-python@v7
      with:
        python-version: ${{ inputs.python-version }}
    - name: Install validator dependencies
      shell: bash
      run: pip install 'jsonschema>=4.0'
    - name: Validate report(s)
      shell: bash
      run: |
        status=0
        for f in ${{ inputs.report }}; do
          echo "::group::validate $f (${{ inputs.profile }})"
          if ! python .ecocompute-validator/tools/validate.py "$f" --profile ${{ inputs.profile }}; then
            status=1
            echo "::error file=$f::validation failed — see the group above for the violations"
          fi
          echo "::endgroup::"
        done
        exit $status

```整个过程约 20 秒：checkout 仓库（校验器本体 + schema 一起拿到，无需另传 schema 路径）、装一个 Python、pip 一个包、跑维护者每天跑的同一条命令。**校验器和维护者用的是同一份 `tools/validate.py`**——不是重写、不是移植，「同一把尺子」本身就是卖点。
## 三、输入设计：四个旋钮与版本哲学

Action 对外暴露四个输入，每个都有讲究：
- **`report`**（必填）：路径空格分隔、shell glob 展开。循环里故意不用 `set -e`——一份失败不中断，**全部验完再统一退出**，多报告的违规一次看全，比逐个 red 下去友好得多。

- **`profile`**：默认 `v1.1-core`（可比性地板），想验「可入数据集」就传 `dataset-eligible`。

- **`validator-ref`**：默认 `main`，文档建议正式使用时 pin 到 commit SHA 或 tag。这是 CI 可复现性的经典权衡：默认跟最新（修 bug 用户自动受益），文档教 pin（审计场景需要逐位复现）。**默认值属于日常使用者，pin 的自由度属于审计者**。

- **`python-version`**：给了但少有人会动——它存在的原因是这毕竟是别人的机器，别替人锁死。

外部仓库的使用方式就是标题里那三行：
- uses: hongping-zh/ecocompute-mlcube/.github/actions/validate-report@main
  with:
    report: ecocompute-out/energy.json
  `owner/repo/子目录@ref` 引用子目录 Action 是 GitHub 文档化的标准模式，调用方无需 fork、无需 Docker、无需 GPU。
  ## 四、自测 workflow：正反两向，缺一不可

Action 写完了，谁来证明它是对的？仓库自己加了一个自测 workflow，这里有两个设计点值得展开。
**第一：正向测试的目标文件不能想当然。** 仓库里现成有 `examples/` 目录，两份示例报告——但本地一跑，**两份都是故意不合规的**：一份是 dry-run 输出（schema 1.0 + 6 条违规，协议明说 estimate 路径不产生合规报告），一份是合成示意数据（`§4.1.4`：`basis: measured` 配不上 `measurement_source: direct-nvml`，诚实标注了 ILLUSTRATIVE）。这是这个项目的设计哲学——示例也要诚实标注身份，但它们显然不能当「必须通过」的 demo。真正的正向目标是测试 fixture：`tests/fixtures/conformant-v1.1.json`，校验器自己的单元测试拿它验证双 profile 零违规。
**第二：校验器的价值一半在「拒绝」，自测必须验证拒绝真的发生。** 只测「合规的能过」是半个测试——一个永远返回 success 的校验器也能过这种测试。于是自测加了负向：
- name: Known-invalid example must be rejected (v1.1-core)
  uses: ./.github/actions/validate-report
  continue-on-error: true
  id: reject
  with:
    report: examples/energy.no-gpu.json
- name: Assert the rejection happened
  if: steps.reject.outcome != 'failure'
  run: |
    echo "::error::the validator accepted examples/energy.no-gpu.json, ..."
    exit 1
  `continue-on-error` 让拒绝不炸整个 job，再用 `outcome != 'failure'` 断言它**确实失败了**——如果哪天有人改校验器改出了「什么都能过」，这个 workflow 变红。
还有一处细节：两个测试步都传 `validator-ref: ${{ github.sha }}` 而不是 `main`。这让它**兼任校验器自己的回归闸门**——PR 改了 `tools/validate.py`，自测验证的是被推上来的那个 commit，而不是远端 main 上某个跟这次改动无关的版本。测自己的改动，就引用自己的 SHA；引用 `main` 的自测测的是别人的代码。
最后一个小意外：负向步骤会在绿色的 run 里留下一条 `::error` 注解（"validation failed — see the group above"）。第一次看到会疑惑「绿灯里怎么有红叉」，但留着它是对的——那条注解恰好证明负向路径真实走过了，删除它反而让自测变成不可观测的。
## 五、上线前的本地预验：合同先于实现

自测 workflow 的断言（「fixture 必过」「no-gpu 必拒」）不是拍脑袋写的，是**先在本机用仓库的 Python 把三份报告各跑一遍、拿到真实判定之后**才落进 YAML 的：
no-gpu          → schema-valid，6 violations，exit 1
illustrative    → schema-valid，1 violation（§4.1.4），exit 1
conformant-v1.1 → 0 violations，exit 0（两个 profile 都是）
这一步看似多余——CI 反正会告诉你结果——但顺序反过来是两种完全不同的工作方式：先本地拿判定再写断言，是**合同先行**（断言描述已知事实，CI 只是执行它）；先写断言再推上去看绿不绿，是**用生产环境试错**。前者 10 分钟拿到确定性，后者把一次可以零成本的验证变成一轮 3–5 分钟的 CI 往返，而且红了以后你分不清是断言写错还是校验器坏了。
推送之后的结果顺理成章：自测 workflow **首跑 12 秒一次通过**，原有的 contract tests 和 Publish image 两个 workflow 照常全绿，分支保护的必需检查一项未动（新 workflow 不是必需检查，不阻塞单人直推流程）。
## 六、方法论沉淀

**1. 「包个 Action」的默认解，未必是对调用者友好的解。** 把工具包进 Action，最省事的路径是包装它现有的分发形态——容器项目就包镜像。但账要算在**调用者**头上：拉 10 GB 镜像校验一个 JSON，这个成本结构在「能跑」的外表下藏了很久，直到有人站在外部用户角度算账才现形。分发形态（镜像）和依赖形态（python + jsonschema）是两回事，Action 应该依赖后者。
**2. 校验类工具的自测必须双向。** 正向证明「该过的能过」，负向证明「该拒的真的拒了」。`continue-on-error` + `outcome` 断言是在 CI 里表达「预期失败」的干净写法——拒绝是校验器的一半价值，没被验证过的拒绝等于不存在。
**3. 合同先于实现。** 要在 CI 里断言一个工具的行为，先在本地拿到那个行为的真实样本。断言描述已知事实、CI 执行合同，和「断言碰运气、红了再查」是两种工程；前者让 CI 的第一次运行就成为验证，后者让它成为调试。
**4. CI 测试要测「被推上去的那个 commit」。** 自测引用 `validator-ref: ${{ github.sha }}` 而不是 `main`——否则每次自测运行测的都是远端 main 的快照，你的改动和验证它的测试在两个版本上各跑各的。这个坑在单仓库里以「本地路径 Action 默认就是当前 checkout」的形式天然免疫，但一旦你的自测显式引用远端 ref，它就会悄悄出现。


----
Action 代码在 [`.github/actions/validate-report/`](https://github.com/hongping-zh/ecocompute-mlcube/blob/main/.github/actions/validate-report/action.yml)，自测 workflow 在 [`.github/workflows/validate-reports.yml`](https://github.com/hongping-zh/ecocompute-mlcube/blob/main/.github/workflows/validate-reports.yml)，使用文档在 [CONTRIBUTING](https://github.com/hongping-zh/ecocompute-mlcube/blob/main/CONTRIBUTING.md)。如果你的仓库里有 EcoCompute 格式的能耗报告，三行 YAML 就能挂上同一把尺子。

ecocompute-mlcube 是一个 LLM 推理能耗测量容器：钉死库版本、10 Hz 直读 NVML 功率、梯形积分算能耗，再用差分法把「模型加载的能耗」和「推理的能耗」分开。每份报告（energy.json）都要过一道校验，校验器给三级判定，故意分开命名：

三行 YAML 把协议校验器搬进 CI：一个 GitHub Action 的设计与取舍

开源测量容器 ecocompute-mlcube 的协议校验器 tools/validate.py 负责判定一份能耗报告是 schema-valid、protocol-conformant 还是 dataset-eligible——JSON Schema 只能查结构，跨字段的协议 MUST（基线臂必须同卡同会话、thermal 顺序必须披露、idle 永不从差值中扣除）必须用代码查。社区复现者在提

开发工具

测试

云计算

为您的EcoCompute LLM推理能耗报告一键接入校验CI：复用官方`tools/validate.py`，支持v1.1-core与dataset-eligible双级判定，多报告统一扫描，全部违规一次列出。20秒完成校验，告别10GB镜像负担。内置双向自测确保拒绝逻辑可靠，CI测试即合同。

单元测试

Android

容器

Docker

Python

GitHub

JSON

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

三行 YAML 把协议校验器搬进 CI：一个 GitHub Action 的设计与取舍-腾讯云开发者社区-腾讯云

三行 YAML 把协议校验器搬进 CI：一个 GitHub Action 的设计与取舍

三行 YAML 把协议校验器搬进 CI：一个 GitHub Action 的设计与取舍

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐