invigil

Invigil

验证从安装到首次成功使用的路径——面向人和 Agent。

软件包可能成功安装，却仍无法运行第一个有用的命令。Invigil 将仓库质量检查与冷启动门禁结合起来，后者会运行声明的操作，并报告诊断故障所需的证据。

开发中的新功能： 在发布前、源代码检出目录之外验证指定的 Python wheel。现有的评分卡、已发布制品检查和 Agent 工具仍可使用。wheel 验证功能尚未发布；pip install invigil 和下方的发布固定版本尚不包含此功能。

试用首次使用演示（源码预览版）

在支持 venv 的 Linux 系统上，使用 Python 3.11+ 和源码预览分支：

git clone --branch feat/wheel-first-use-preview https://github.com/invigil/invigil.git
cd invigil
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python examples/first-use-demo/run.py

此演示离线运行，并检查真实的 wheel。两个 wheel 都能安装；其中一个缺少必需的数据文件，因此无法运行首次使用命令。添加该文件后，同一项检查便可通过。演示会输出失败信息，并将 JSON 报告保存到临时目录中。 这是一个合成示例，并非对上游项目当前版本的描述。

演示详情 · 验证你自己的 wheel · CI 工作流模板

预览版需要指定明确的命令，并可选择指定预期输出。成功运行只能证明该操作在记录的环境中正常运行；它不能保证一般情况下的发布安全。请在不含凭据的一次性工作进程中运行不熟悉的制品——Python venv 并非安全沙箱。

invigilate —— 监考并执行考试规则。

---

Invigil 如何融入你的技术栈

Invigil 不会取代你现有的工具，而是弥补它们留下的产品质量缺口。

能力	作用
仓库评分卡	检查文档、配置和质量规范；提出修复建议
已发布制品冷启动门禁	运行已配置的软件包／容器操作和 HTTP 探测
本地 wheel 首次使用验证（尚未发布）	验证候选制品；记录其哈希值、阶段和依赖项
现有的代码检查工具、扫描器和测试	与 Invigil 配合，继续检查代码正确性和安全性

干净安装冒烟脚本也能检测到相同的打包缺陷。Invigil 致力于让这类工作流更易于配置，并使不同项目的报告保持一致。

---

Why

评分卡会检查项目是否便于新手和 Agent 理解。 每项未通过的静态检查都会附上建议的命令或修改。执行报告 会保留失败步骤和输出；它们无法推断每个应用的所有根本原因。

七道关卡涵盖入门、错误、制品验证、 供应链证据、受众文档、贡献和采用情况。评分总结的是已实现的仓库检查；它并不能证明制品 已成功执行。执行证据请使用冷启动关卡。

Install

已发布的渠道——选择符合运行环境的渠道：

渠道	适用场景	单行命令
PyPI	本地运行、适用于 Python 的 CI	pip install invigil
GitHub Action	GitHub PR	uses: invigil/invigil@v1
Docker (ghcr)	GitLab、Jenkins，以及任何非 Python CI	docker run --rm -v "$PWD:/repo" ghcr.io/invigil/invigil score /repo
pre-commit	每次提交时进行离线检查	hooks invigil-layout、invigil-secrets（见下文）
MCP server	Agent（Claude Code、任何 MCP 客户端）	pip install "invigil[mcp]" → invigil mcp

每个版本都会发布所有签名制品：经 cosign 签名的 wheel、sdist 和容器镜像，以及 SPDX SBOM——可通过针对 GitHub OIDC 身份的 cosign verify 进行验证。

Quick Start

以下命令使用已发布的评分卡。验证 wheel 时，请使用上方的源预览。

在任何仓库中本地运行：

pip install invigil
invigil score .            # human-readable scorecard + the exact fix for every failure
invigil score . --format markdown   # a PR-comment-ready table
invigil score . --format json       # machine-readable

将其添加到 CI，作为仅报告的关卡（发布评分卡评论和徽章，从不阻止 PR）：

# .github/workflows/quality-gate.yml
name: Quality gate
on: [pull_request]
permissions: { contents: read, pull-requests: write }
jobs:
  invigil:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1        # v7.0.1
      - uses: invigil/invigil@7f31330715bb7e42f26032ce3e921fcf78d4acea        # v1.7.1
        with:
          enforce: "false"              # flip to true once the grade is stable

准备好在目标关卡以下阻止合并时，将 enforce: "true"（或在 .invigil.yml 中设置 project.enforce: true）。

为什么要使用 SHA？ invigil/invigil@v1 可以正常使用，并跟踪最新的 v1.x.y，但 Invigil 自己的 actions-sha-pinned 检查（G3）也会因浮动标签而失败。请固定 SHA，并让 Dependabot 更新这些固定值；它会读取末尾的注释。

该 Action 会将报告和两个徽章作为步骤输出提供——将评分卡传入作业 摘要，并在 shields.io 能够访问的位置发布徽章 JSON：

      - uses: invigil/invigil@7f31330715bb7e42f26032ce3e921fcf78d4acea        # v1.7.1
        id: invigil
        with: { comment: "false" }
      - run: cat "${{ steps.invigil.outputs.report }}" >> "$GITHUB_STEP_SUMMARY"
      # outputs.badge → grade badge JSON · outputs.ai-badge → ai-ready badge JSON

How it works

分为两层，与规范相对应：

• 静态规范评分卡（每个 PR 运行，耗时数秒）——检查仓库文件系统和 GitHub 元数据：LICENSE、README 长度、.env.example、深度健康检查端点、全局错误 ID 处理器、固定 SHA 的 Actions、强制使用的 lockfile、覆盖率关卡、每日已发布制品 冒烟测试、≥5 个适合新手的问题、文档索引、llms.txt/AGENTS.md 等。输出文本 / JSON / Markdown / shields.io 徽章。
• 冷启动关卡（每晚运行，可复用——invigil stranger）——在干净的 Runner 上，安装 并启动已配置的已发布制品，并探测其声明的接口。 新增的本地 wheel 路径还会为设置、安装和首次使用设置每个 wheel 的单一预算上限，并记录各阶段结果；旧有路径保持原有行为。Web 服务会接受 HTTP 探测；CLI 镜像（带有 command: 的制品） 会一直运行到完成，并且必须以 0 退出。一个可复用的工作流即可替代每个仓库反复复制的 60 行 smoke-published.yml：

# .github/workflows/stranger-gate.yml
name: Cold-start gate
on:
  schedule: [{ cron: "0 3 * * *" }]
  workflow_dispatch:
jobs:
  stranger:
    uses: invigil/invigil/.github/workflows/stranger-gate.yml@7f31330715bb7e42f26032ce3e921fcf78d4acea  # v1.7.1

Fix by PR

可选的修复工作流会在工作分支上应用机械化修复，并创建一个批量 PR。它使用 invigil score --fix --pr-mode； 受保护分支的安全措施仍然有效。关闭其 PR 且不合并后，在工作分支被删除前，系统会遵从这一操作。配置和限制请参阅 CLI 参考。

Configuration

在仓库根目录放置 .invigil.yml。静态评分卡可选此文件（会应用合理的默认值），冷启动关卡则必须提供此文件（用于声明要启动和探测的内容）。完整 架构见 schema/invigil.schema.json；示例见 examples/。

version: 1
project:
  name: my-app
  language: python
  min_gate: G4
  enforce: false
artifacts:
  - type: pypi
    name: "my-app[all]"
  - type: ghcr
    image: ghcr.io/me/my-app:latest
    port: 8000
probes:
  - { url: "/", expect_status: 200 }
  - { url: "/api/things", expect_json_count: { min: 5 } }
boot_budget_minutes: 10

轻量且模块化

开发者会绕过的关卡毫无价值，因此 Invigil 致力于实现零摩擦：

• 适用于提交前检查的快速离线分组 — 每项检查都标记为 local/network/heavy。 invigil check layout 无需联网即可运行文件系统检查，耗时约 120ms：

  # .pre-commit-config.yaml
  - repo: https://github.com/invigil/invigil
    rev: v1        # tracks the latest v1.x.y
    hooks: [{ id: invigil-layout }, { id: invigil-secrets }]
  

  更耗时且依赖网络的检查（scorecard、Cold-Start Gate）则留在 CI 中。 invigil score --offline / --layer local / --group supply-chain 可按任意方式筛选。

• 灵活适配，而非分叉。 profile: strict | progressive | light、每项检查的 weights、optional（发出提示但不阻断）、thresholds.fail_on — 打造你自己的准则。

• 韧性源于设计。 scorecard.dev 超时会被视为 SKIP，不计入评分 — 不会造成 A 到 C 的虚假降级，也不会导致构建崩溃。

  → 准则与各道关卡对此有完整说明。

当用户是 Agent 时

可读性如今面向两类受众。冷不丁来到你仓库的读者，往往是 AI Agent：它依赖上下文窗口而非耐心， 依赖退出码而非直觉，而且只会根据仓库中以机器可读形式声明的内容采取行动。ai 检查组 评估的正是这类信息 — 不只是检查是否存在 llms.txt/AGENTS.md，还会确认 Agent 能否 据此实际采取行动：

检查项	对 Agent 的承诺
agents-md-actionable	你的 AGENTS.md/CLAUDE.md 包含可运行的围栏命令，而不是纯文字说明
llms-txt-shape	llms.txt 符合规范格式，且能适配 10 KB 的上下文预算
agent-context-fresh	Agent 指令不会比其描述的源内容旧 90 天以上
readme-heading-hierarchy	README 分块清晰（一个 H1，真正的 H2 章节）
exit-codes-documented	CLI 的退出码均有列出 — Agent 根据退出码分支，而不是解读文字
llms-no-secrets	机器可读信息中不泄露凭据
agent-scope-visibility	Agent 代码声明其工具清单（这是评估影响范围的前提）

由此会生成两种产物。invigil score --format llm — 一份确定性报告，大小约 1 KB，专为 Agent 阅读而构建：健康的仓库只占用它两行上下文。还有一枚 ai-ready 徽章， 这是一个 shields.io 端点，可放入你自己的 README：

invigil score . --format ai-badge --output badges/ai-ready.json   # commit this

![AI-ready](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/badges/ai-ready.json)

在 CI 中，Action 会为你生成该徽章 — steps.<id>.outputs.ai-badge 是指向同一 JSON 的路径。

MCP 服务

Agent 不必调用 shell — Invigil 原生支持 MCP（mcp-name: io.github.invigil/invigil）：

pip install "invigil[mcp]"    # optional extra; the core CLI stays zero-dep
invigil mcp                   # stdio server

// e.g. .mcp.json for Claude Code — any MCP client works
{ "mcpServers": { "invigil": { "command": "uvx", "args": ["--from", "invigil[mcp]", "invigil", "mcp"] } } }

提供三个只读工具：evaluate_repo（评分报告，支持 llm 或 json 格式）、 check_group（一个快速离线检查组）以及 preview_fixes（--fix 会应用的修改计划 — Agent 使用自己的编辑工具应用更改，因此此处不会写入任何内容）。

准则

没有人抱怨不代表没有问题 — 沉默是项目收到的最强烈负面信号。 这就是「沉默用户准则」，Invigil 正是用来落实它的：各道关卡的含义及调优方法。

稳定性

Invigil 目前处于 Alpha 阶段，docs/stability.md 明确说明了这意味着什么： CLI、退出码、JSON 结构、徽章 JSON 和 MCP 工具已足够稳定，可用于自动化；单项检查的判定结果则不稳定， 且每份报告都包含 doctrine_version，帮助你区分仓库出现了退步还是评判标准发生了变化。

参与贡献

欢迎提交 Issue 和 PR — 请参阅 CONTRIBUTING.md 和 适合新手的 Issue。Invigil 会在 CI 中评估自身；目前自评分数仅供报告。另请参阅范围明确的 新手任务 和基准测试任务。

许可证

Apache-2.0 — 详见 LICENSE。