内容
监考
**一个 CI 质量门，针对产品质量的原则进行不仅仅是代码风格。CI](https://github.com/invigil/invigil/actions/workflows/ci.yml/badge.svg)](https://github.com/invigil/invigil/actions/workflows/ci.yml)
[](LICENSE)
[](https://pypi.org/project/invigil/)
[](https://github.com/marketplace/actions/invigil-product-quality-gateDocker](https://.io/badge/ghcr-invigil%2Finvigil6ed?logo=Color=white)](https.com/invigil/in/pkgs/container/invigil)
[](https://scorecard.dev/viewer/?uri=github.com/invigil/invigil)
[](https://github.com/invigil/invigil)
[](https://github.com/invigil/invigil#when-your-user-is-an-agent)
代码检查工具检查你的**代码**。Dependabot 检查你的**依赖项**。**没有工具检查你的项目是否易于理解** —— 是否有人可以冷启动并立即使用：十分钟内启动，遇到错误时有提示修复方法，当天在 PyPI 上安装，README 文件仍然是登录页面而不是 600 行的墙。
这就是每个开源项目在有人新发现它时面临的测试 —— 新工程师，或越来越多地，具有上下文窗口而不是耐心的 AI 代理。如果他们无法在 10 分钟内达到“hello world”，他们就会离开。如果 PyPI 上的制品损坏，因为 CI 只测试源代码树，他们就会离开。如果错误消息是沉默的堆栈跟踪，他们就会离开。
Invigil 将这些承诺转化为机械的、精确的修复报告检查，并在 CI 中运行 —— 这样项目就可以自我证明。
> *监考* —— 监督考试并执行其规则。
---
## Invigil 在你的技术栈中的位置
Invigil 不会取代现有的工具；它弥补了现有工具留下的产品质量差距。
| 工具 | 关注点 | 缺失的内容（Invigil 捕获） |
|---|---|---|
| **代码检查工具 / SonarQube** | 代码风格、静态错误、复杂性 | 已发布的制品是否实际启动？README 是否易于理解？ |
| **Dependabot / Renovate** | 保持依赖项更新 | 是否在 CI 中强制执行锁定文件？是否存在版本矩阵？ |
| **OpenSSF Scorecard** | 供应链安全（分支规则、令牌） | 项目是否有快速入门？故障模式是否可操作？ |
| **Invigil** | 产品质量、可读性、错误处理 | （Invigil 依赖上述工具并强制执行它们的存在） |
---
## 为什么
你已经编写了原则；你只需要手动执行它。每次 Invigil 检查失败，都会告诉你**有什么问题，为什么重要，以及修复的确切命令** —— 因为一个无法告诉你如何通过的门与它试图捕获的错误错误消息模式相同。
它针对七个**门**进行评分，每个门都是对不同冷启动读者的易读性承诺：
| 门 | 承诺 |
|---|---|
| **G1** | 任何冷启动的人都能在干净的机器上成功运行 |
| **G2** | 每种故障模式都会告诉用户修复方法 |
| **G3** | 已发布的制品每天都会经过机器验证 |
| **G4** | 供应链证据是公开的（Scorecard ≥7，签名发布，SBOM） |
| **G5** | 所有五个门都打开并有文档（新人、操作员、贡献者、企业、AI） |
| **G6** | 在没有人工干预的情况下，第一个外部贡献者被合并 |
| **G7** | 被你无法控制的项目引用/集成 |
存储库只有在所有 ≤ n 的门的强制性检查都通过时，才能**达到** `Gn`，并根据其加权分数获得字母等级。
## 安装
一个工具，四个入口 —— 选择一个与你的运行环境相匹配的：
| 通道 | 适用场景 | 一行命令 |
|---|---|---|
| **PyPI** | 本地运行、Python 友好的 CI | `pip install invigil` |
| **GitHub Action** | GitHub PRs | `uses: invigil/invigil@v1` |
| **Docker（ghcr）** | GitLab、Jenkins、任何非 Python CI | `docker run --rm -v "$PWD:/repo" ghcr.io/invigil/invigil score /repo` |
| **pre-commit** | 每次提交的离线检查 | 钩子 `invigil-layout`、`invigil-secrets`（如下） |
| **MCP 服务器** | 代理（Claude Code，任何 MCP 客户端） | `pip install "invigil[mcp]"` → `invigil mcp` |
每个版本都附带所有签名的制品：cosign 签、sdist 和容器镜像，以及 SPDX SBOM —— 可使用 `cosign verify` 与 GitHub OIDC 身份验证。
## 快速入门
在任何存储库上本地运行：
```bash
pip install invigil
invigil score . # 人类可读的记分卡 + 每个故障的确切修复方法
invigil score . --format markdown # PR 评论就绪的表格
invigil score . --format json # 机器可读
```
将其添加到 CI 中作为仅报告门（发布记分卡评论 + 徽章，绝不会阻止 PR）：
```yaml
# .github/workflows/quality-gate.yml
name: 质量门
on: [pull_request]
permissions: { contents: read, pull-requests: write }
jobs:
invigil:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: invigil/invigil@v1 # 原则记分卡
with:
enforce: "false" # 在成绩稳定之前切换到 true
```
当你准备好让它阻止低于目标门的合并时，切换 `enforce: "true"`（或在 `.invigil.yml` 中设置 `project.enforce: true`）。
该操作将渲染的报告和徽章作为步骤输出公开 —— 将记分卡输送到作业摘要中，或在 shields.io 可以访问的位置发布徽章 JSON：
```yaml
- uses: invigil/invigil@v1
id: invigil
with: { comment: "false" }
- run: cat "${{ steps.invigil.outputs.report }}" >> "$GITHUB_STEP_SUMMARY"
# steps.invigil.outputs.badge → shields.io 端点 JSON 的路径
```
## 工作原理
两层，与原则相符：
- **静态原则记分卡** （每个 PR，秒级）—— 检查存储库文件系统和 GitHub 元数据：LICENSE、README 长度、`.env.example`、深健康端点、全局错误 ID 处理程序、SHA 固定的操作、强制执行的锁定文件、覆盖率门、每日发布的制品烟雾测试、≥5 个 good-first-issues、文档索引、`llms.txt`/`AGENTS.md` 等。发出文本 / JSON / Markdown / shields.io 徽章。
- **冷启动门** （夜间，可重用 - `invigil stranger`）—— 在干净的运行器上，安装并启动您声明的每个**已发布**制品，并在 10 分钟预算内探测其核心表面。Web 服务获得 HTTP 探测；CLI 镜像（带有 `command:` 的制品）运行至完成并必须退出 0。一个可重用的工作流取代了 60 行的 `smoke-published.yml` 每个存储库复制粘贴：
```yaml
# .github/workflows/stranger-gate.yml: 冷启动门:
schedule: [{ cron: "0 3 * * *" }]
workflow_dispatch:
jobs:
stranger:
uses: invigil/in/.github/workflows/stranger-gate.yml@v1
```
### 通过 PR 修复（Dependabot 的易）
选择加入机器人，该机器人会在工作分支上应用 Invigil 的机械修复并打开批处理 PR**治理脚手架、代理上下文文件、配置内置三个防噪仅限选择加入，一个稳定分支意味着一个 PR不五个），以及关闭未合并的 PR 是一个”，机器人尊重 它在您删除 `invigil/fixes`之前保持沉默。
```yaml
# .github/workflows/legibility-fixes.yml
name: 易读性修复
on:
schedule: [{ cron: "0 6 1 * *" }] # 每月 - 这些是一次性脚手架，而不是依赖项
workflow_dispatch:
jobs:
fix:
uses: invigil/invigil/.github/workflows/fix-pr.yml@v1
```
，它运行 `inv --fix --pr-mode`：修复引擎的 CI 锁定在受保护分支上保持不变 - `--pr-mode` 仅在非默认分支上允许修复，因此任何自动化的操作都不会在没有人类合并 PR 的情况下登陆到 `main`。
## 配置
在存储库根目录下添加一个 `.invigil.yml`。对于静态记分卡来说它是可选的（适用默认设置），启动门来说是必需的（它声明了启动和探测的内容）。完整模式见 [`schema/invigil.schema.json`](schema/invigil.schema.json)；示例见 [`examples/`](examples/)。
```yaml
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 被构建为零摩擦：
- **用于 pre-commit 的快速离线组** —— 每个检查都标记为 `local`/`network`/`heavy`invigil check layout` 在 ~120ms 内运行文件系统检查，无需网络：
```yaml
# .pre-commit-config.yaml
- repo: https://github.com/invigil/invigil
rev: v1 # 跟踪最新的 v1.x.y
hooks: [{ id: invigil-layout }, { id: invigil-secrets }]
```
更重的、依赖网络的检查（`scorecard`，冷启动门）保留在 CI 中。`invigil score --offline` / `--layer local` / `--group supply-chain` 以任意方式切片。
- **配置文件，因此它会弯曲而不是分叉。** `profile: strict | progressive | light`，加上每个检查的 `weights`、`optional`（ding 无门控）和 `thresholds.fail_on`。使其成为您的原则，而不是硬编码的原则。
- **设计时具有弹性。** scorecard.dev 超时是一个 SKIP，不会影响评分 - 绝不会从 A 降级到 C，也绝不会崩溃构建。
- **AI 时代原生。** `ai` 组检查您的 `llms.txt`/`AGENTS.md` 不会泄漏秘密，并且代理代码会声明其工具清单 - 如果代理被提示注入，第一个“爆炸半径”切片。
## 当你的用户是代理时
现在，易读性有两个受众。冷启动时到达您存储库的读者通常是一个 AI 代理：它具有上下文窗口而不是耐心，出口代码而不是直觉，并且它只对存储库以机器可读的方式声明的内容采取行动。`ai` 检查组评估该表面 - 不仅仅是 `llms.txt`/`AGENTS.md` 的**存在**，而是代理是否可以实际对其采取行动：
| 检查 | 对代理的承诺 |
|---|---|
| `agents-md-actionable` | 您的 `AGENTS.md` / `CLAUDE.md` 包含可运行的代码块，而不是散文 |
| `llms-txt-shape` | `ll` 是规范形状的，适合 10 KB 的上下文预算 |
| `agent-context-fresh` | 代理指令不会比它们描述的源代码更新 90 天以上 |
| `readme-heading-hierarchy` | README 块清晰（一个 H1，真正的 H2 部分） |
| `exit-codes-documented` | CLI 的退出代码已枚举 - 代理根据代码分支，而不是散文 |
| `llms-no-secrets` | 机器可读的表面不会泄漏凭证 |
| `agent-scope-visibility` | 代理代码声明其工具清单（爆炸半径前提条件） |
它的输出有两个制品：一个 **`ai-ready` 徽章** （shields 端点，由 `--badges-dir` 发出）和 **`invigil score --format llm`** —— 一个确定性的报告，大小约为 1 KB，由代理读取：一个健康的存储库成本为两行上下文。
### MCP 服务器
代理不必分发 - Invigil 原生支持 MCP（`mcp-name: iovigil/invig）：
```bash install "invigil]" # 可选的额外依赖；核心保持零依赖igil mcp io 服务器
```
```json
// 例如 .mcp.json for Claude Code - 任何 MCP 客户端都有效
{ "mcpServers": { "invigil": { "command": "uvx", "args": ["--from", "invigil[mcp]", "invigil", "mcp"] } } }
```
三个只读工具：`evaluate_repo` （记分卡，`llm` 或 `json` 格式），`check_group` （一个快速的离线组）和 `preview_fixes` （变异计划 - 代理使用其自己的编辑工具应用更改，因此此处不写入任何内容）。
## 原则
Invigil 编码了一个特定的产品质量原则（沉默用户原则及其五项纪律）：**投诉的缺失并不是问题的缺失 - 响亮的信号项目收到的。** 您在发布时进行测试；用户在依赖项漂移和注册表更改后到达。只有自动化在那时是清醒的。Invigil 就是这种自动化。
## 贡献
欢迎提出问题和 PR - 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [good first issues](https://github.com/invigil/invigil/labels/good%20first%20issue)。Invigil 在 CI 中自我评分（`self-score` 作业）；降低 Invigil 自己评分的 PR 不会合并。
许可证
Apache-2.0 -阅 [LICENSE)。
