Judges Panel

评审团

一个 MCP（模型上下文协议）服务，提供由 45 位专业评审组成的评审团，用于评估 AI 生成的代码——无论评审的是哪个项目，都能充当独立的质量关卡。它结合了确定性模式匹配与 AST 分析（即时、离线、零大模型调用）以及由大模型驱动的深度评审提示词，让你的 AI 助手能够以专家角色分析全部 45 个领域。

亮点：

• 包含一个用于决策发布、以通俗语言总结风险并排列修复优先级的 **App Builder 工作流（3 步）**演示——请参阅试用演示。
• 包含具有策略配置、证据校准、专业反馈、置信度评分和不确定性报告的 V2 上下文感知评估。
• 包含公开仓库 URL 报告，可克隆仓库、运行完整评审团并输出整合后的 Markdown 报告。
• 200 多个确定性自动修复补丁（参见 src/patches/index.ts），以及由大模型驱动的深度评审。

🧪 printHelp 中的许多命令仍处于实验阶段或路线图规划中。默认情况下，我们仅显示 GA 命令。设置 JUDGES_SHOW_EXPERIMENTAL=1 可显示尚未完善的命令；这些命令可能尚未接入。

🔰 软件包

• CLI：@kevinrabun/judges-cli → 二进制文件 judges（使用 npx @kevinrabun/judges-cli eval --file app.ts）。
• MCP/API：@kevinrabun/judges → 编程接口 + MCP 服务（npm install @kevinrabun/judges）。
• VS Code 扩展：参见 vscode-extension/。
• GitHub Action：uses: KevinRabun/judges@main（参见 CI 快速入门）。

---

快速入门

CLI（单次运行）

# Using the CLI package (recommended)
npx @kevinrabun/judges-cli eval --file src/app.ts

# Show GA commands only (default)
npx @kevinrabun/judges-cli --help

# Show experimental/roadmap commands
echo "JUDGES_SHOW_EXPERIMENTAL=1" >> $GITHUB_ENV
npx @kevinrabun/judges-cli --help

# License scan (supply-chain & license compliance)
npx @kevinrabun/judges-cli license-scan --dir .

**CLI 与 API：**如果想在应用中嵌入 Judges（MCP/API），请安装 @kevinrabun/judges。如需使用命令行，请使用 @kevinrabun/judges-cli（二进制文件 judges）。

GitHub Action

name: Judges
on: [pull_request, push]
jobs:
  judges:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: KevinRabun/judges@main
        with:
          path: .
          diff-only: true           # evaluate only changed lines in PRs (default true)
          fail-on-findings: true    # fail on critical/high findings
          upload-sarif: true        # upload SARIF to GitHub Code Scanning

编程接口（包含 MCP 服务）

npm install @kevinrabun/judges

import { evaluateCode } from "@kevinrabun/judges/api";
const verdict = evaluateCode("const password = 'ProdSecret';", "typescript");
console.log(verdict.overallVerdict, verdict.overallScore);

MCP 服务

MCP 服务通过 stdio 运行，由你的 MCP 客户端（VS Code、Claude Desktop 等）启动。 在 MCP 设置中配置它（例如 mcp.json）：

{
  "servers": {
    "judges": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kevinrabun/judges"]
    }
  }
}

也可以直接运行服务：

npx @kevinrabun/judges
# Starts the MCP server on stdio

配置文件：.judgesrc.json（支持通过 expandEnvPlaceholders 替换 ${ENV_VAR}）。参见配置。

---

为什么选择 Judges？

AI 代码生成器（Copilot、Cursor、Claude、ChatGPT 等）能快速编写代码，却经常产生不安全的默认设置、缺失的身份验证、硬编码的密钥和糟糕的错误处理。人工审查者能发现其中一部分问题，但没人能始终如一地审查 45 个维度。

	ESLint / Biome	SonarQube	Semgrep / CodeQL	Judges
范围	风格 + 部分错误	错误 + 代码异味	安全模式	45 个领域：安全、成本、合规、无障碍、API 设计、云、UX，……
面向 AI 生成代码	否	否	部分支持	专为 AI 输出的失效模式打造
设置	每个项目单独配置	服务端 + 扫描器	云端或本地	一条命令：npx @kevinrabun/judges-cli eval file.ts
自动修复补丁	部分支持	否	否	200 多个确定性补丁——即时、离线
面向非技术人员的输出	否	仪表板	否	使用 What/Why/Next 的通俗易懂的问题说明
原生支持 MCP	否	否	否	是——可在 Copilot、Claude、Cursor 中使用
SARIF 输出	否	是	是	是——可上传到 GitHub Code Scanning
成本	免费	$$$$	免费/付费	免费 / MIT

Judges 并不能取代代码检查工具——它覆盖代码检查工具未涵盖的维度：身份验证策略、数据主权、成本模式、无障碍、特定框架的反模式，以及跨多个文件的架构问题。

---

快速开始

前置要求：Node.js >=18（建议 >=20），并可使用 npx。judges CLI 二进制文件随 @kevinrabun/judges-cli 一同发布（推荐），也可通过 npx @kevinrabun/judges 使用。

软件包：

• CLI： npm install -g @kevinrabun/judges-cli（或 npx @kevinrabun/judges-cli ...）
• MCP/API： npm install @kevinrabun/judges

将 @kevinrabun/judges 用于 MCP 服务和编程 API。需要使用 judges 终端命令时，请使用 @kevinrabun/judges-cli。

立即试用（无需克隆）

# Install the CLI globally
npm install -g @kevinrabun/judges-cli

# Evaluate any file
judges eval src/app.ts

# Pipe from stdin
cat api.py | judges eval --language python

# Single judge
judges eval --judge cybersecurity server.ts

# SARIF output for CI
judges eval --file app.ts --format sarif > results.sarif

# HTML report with severity filters and dark/light theme
judges eval --file app.ts --format html > report.html

# Fail CI on findings (exit code 1)
judges eval --fail-on-findings src/api.ts

# Suppress known findings via baseline
judges eval --baseline baseline.json src/api.ts

# Use a named preset
judges eval --preset security-only src/api.ts

# Use a config file
judges eval --config .judgesrc.json src/api.ts

# Set a minimum score threshold (exit 1 if below)
judges eval --min-score 80 src/api.ts

# One-line summary for scripts
judges eval --summary src/api.ts

# Agentic skills (orchestrated judge sets)
judges skill ai-code-review --file src/app.ts
judges skill security-review --file src/api.ts --format json
judges skill release-gate --file src/app.ts
judges skills   # list available skills

> Full catalog: [`docs/skills.md`](docs/skills.md)


# List all 45 judges
judges list

其他 CLI 命令

# Interactive project setup wizard
judges init

# Preview auto-fix patches (dry run)
judges fix src/app.ts

# Apply patches directly
judges fix src/app.ts --apply

# License compliance scan (copyleft/unknown detection)
judges license-scan --format json --risk high

# Watch mode — re-evaluate on file save
judges watch src/

# Project-level report (local directory)
judges report . --format html --output report.html

# Evaluate a unified diff (pipe from git diff)
git diff HEAD~1 | judges diff

# Analyze dependencies for supply-chain risks
judges deps --path . --format json

# Run GitHub App server (zero-config PR reviews)
judges app serve --port 4567

# Run GitHub PR review (gh CLI required)
judges review --pr 123 --repo owner/name --diff-only

# Auto-tune presets and configs
judges tune --dir . --apply

# Create a baseline file to suppress known findings
judges baseline create --file src/api.ts -o baseline.json

# Generate CI template files
judges ci-templates --provider github
judges ci-templates --provider gitlab
judges ci-templates --provider azure
judges ci-templates --provider bitbucket

# Generate per-judge rule documentation
judges docs
judges docs --judge cybersecurity
judges docs --output docs/

# Install shell completions
judges completions bash   # eval "$(judges completions bash)"
judges completions zsh
judges completions fish
judges completions powershell

# Install pre-commit hook
judges hook install

# Uninstall pre-commit hook
judges hook uninstall

🔎 提示：CLI 帮助现在默认仅显示 GA 命令。要查看实验性/路线图命令，请运行：

JUDGES_SHOW_EXPERIMENTAL=1 judges --help

GitHub App（可自托管的 webhook）

以零配置的 GitHub App 形式运行 PR 审查工具：

# Run the webhook server locally
judges app serve --port 4567

必需的环境变量：

• JUDGES_APP_ID – GitHub App ID
• JUDGES_PRIVATE_KEY 或 JUDGES_PRIVATE_KEY_PATH – PEM 私钥
• JUDGES_WEBHOOK_SECRET – 签名验证密钥

可选：

• JUDGES_MIN_SEVERITY（默认值：medium）
• JUDGES_MAX_COMMENTS（默认值：25）
• JUDGES_TEST_DRY_RUN=1，用于避免在测试期间发起实时网络请求

本地测试时，可以通过 ngrok http 4567 暴露 http://localhost:4567/webhook，并据此配置 GitHub App 的 webhook URL。

在 GitHub Actions 中使用

只需零配置，即可将 Judges 添加到 CI 工作流中：

# .github/workflows/judges.yml
name: Judges Code Review
on: [pull_request]

jobs:
  judges:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write  # only if using upload-sarif
    steps:
      - uses: actions/checkout@v4
      - uses: KevinRabun/judges@main
        with:
          path: src/api.ts        # file or directory
          format: text             # text | json | sarif | markdown
          upload-sarif: true       # upload to GitHub Code Scanning
          fail-on-findings: true   # fail CI on critical/high findings

可用输出供后续步骤使用：verdict、score、findings、critical、high、sarif-file。

使用 Docker（无需 Node.js）

# Build the image
docker build -t judges .

# Evaluate a local file
docker run --rm -v $(pwd):/code judges eval --file /code/app.ts

# Pipe from stdin
cat api.py | docker run --rm -i judges eval --language python

# List judges
docker run --rm judges list

或用作 MCP 服务

1. 安装并构建

git clone https://github.com/KevinRabun/judges.git
cd judges
npm install
npm run build

2. 试用演示

运行随附的演示，查看全部 45 个评审器如何评估一个刻意编写得有缺陷的 API 服务：

npm run demo

该演示会评估 examples/sample-vulnerable-api.ts——这是一个故意包含大量安全漏洞、性能反模式和代码质量问题的文件——并打印完整的评估结果，其中包括每个评审器的评分和发现。

演示现在还包含 **App Builder 工作流（3 步）**部分。只需运行一次，即可同时获得评审团输出和工作流输出：

• 发布决策（Ship now / Ship with caution / Do not ship）
• 主要风险的通俗易懂摘要
• 优先级排序的修复任务，以及可由 AI 修复的 P0/P1 项

工作流输出示例（已截断）：

╔══════════════════════════════════════════════════════════════╗
║             App Builder Workflow Demo (3-Step)             ║
╚══════════════════════════════════════════════════════════════╝

  Decision       : Do not ship
  Verdict        : FAIL (47/100)
  Risk Counts    : Critical 24 | High 27 | Medium 55

  Step 2 — Plain-Language Findings:
  - [CRITICAL] DATA-001: Hardcoded password detected
      What: ...
      Why : ...
      Next: ...

  Step 3 — Prioritized Tasks:
  - P0 | DEVELOPER | Effort L | DATA-001
      Task: ...
      Done: ...

  AI-Fixable Now (P0/P1):
  - P0 DATA-001: ...

评审团输出示例（已截断）：

╔══════════════════════════════════════════════════════════════╗
║           Judges Panel — Full Tribunal Demo                 ║
╚══════════════════════════════════════════════════════════════╝

  Overall Verdict : FAIL
  Overall Score   : 43/100
  Critical Issues : 15
  High Issues     : 17
  Total Findings  : 83
  Judges Run      : 33

  Per-Judge Breakdown:
  ────────────────────────────────────────────────────────────────
  ❌ Judge Data Security              0/100    7 finding(s)
  ❌ Judge Cybersecurity              0/100    7 finding(s)
  ❌ Judge Cost Effectiveness        52/100    5 finding(s)
  ⚠️  Judge Scalability              65/100    4 finding(s)
  ❌ Judge Cloud Readiness           61/100    4 finding(s)
  ❌ Judge Software Practices        45/100    6 finding(s)
  ❌ Judge Accessibility              0/100    8 finding(s)
  ❌ Judge API Design                 0/100    9 finding(s)
  ❌ Judge Reliability               54/100    3 finding(s)
  ❌ Judge Observability             45/100    5 finding(s)
  ❌ Judge Performance               27/100    5 finding(s)
  ❌ Judge Compliance                 0/100    4 finding(s)
  ⚠️  Judge Testing                  90/100    1 finding(s)
  ⚠️  Judge Documentation            70/100    4 finding(s)
  ⚠️  Judge Internationalization     65/100    4 finding(s)
  ⚠️  Judge Dependency Health        90/100    1 finding(s)
  ❌ Judge Concurrency               44/100    4 finding(s)
  ❌ Judge Ethics & Bias             65/100    2 finding(s)
  ❌ Judge Maintainability           52/100    4 finding(s)
  ❌ Judge Error Handling            27/100    3 finding(s)
  ❌ Judge Authentication             0/100    4 finding(s)
  ❌ Judge Database                   0/100    5 finding(s)
  ❌ Judge Caching                   62/100    3 finding(s)
  ❌ Judge Configuration Mgmt         0/100    3 finding(s)
  ⚠️  Judge Backwards Compat         80/100    2 finding(s)
  ⚠️  Judge Portability              72/100    2 finding(s)
  ❌ Judge UX                        52/100    4 finding(s)
  ❌ Judge Logging Privacy            0/100    4 finding(s)
  ❌ Judge Rate Limiting             27/100    4 finding(s)
  ⚠️  Judge CI/CD                    80/100    2 finding(s)

3. 运行测试

npm test

运行自动化测试，覆盖所有评审器、AST 解析器、Markdown 格式化器和边缘情况。

4. 连接到编辑器

VS Code（推荐 — 零配置）

从 Marketplace 安装 Judges Panel 扩展。它提供：

• 每次保存文件时的行内诊断和快速修复
• @judges 聊天参与者 — 在 Copilot Chat 中输入 @judges，或直接要求“审查 judges panel”，Copilot 会自动路由请求
• 自动配置的 MCP 服务 — Copilot 无需任何设置即可使用全部 45 个专家角色提示词

code --install-extension kevinrabun.judges-panel

VS Code — 手动 MCP 配置

如果你更喜欢显式的工作区配置（或希望未安装扩展的团队成员也能受益），请创建 .vscode/mcp.json：

{
  "servers": {
    "judges": {
      "command": "npx",
      "args": ["-y", "@kevinrabun/judges"]
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "judges": {
      "command": "npx",
      "args": ["-y", "@kevinrabun/judges"]
    }
  }
}

Cursor / 其他 MCP 客户端

对任何兼容 MCP 的客户端使用相同的 npx 命令：

{
  "command": "npx",
  "args": ["-y", "@kevinrabun/judges"]
}

5. 在 GitHub Copilot PR 审查中使用 Judges

可以 — 用户可以将 Judges 纳入基于 GitHub 的审查工作流，但有一个重要限制：

• GitHub 上托管的 copilot-pull-request-reviewer 目前无法像 VS Code 那样直接附加任意本地 MCP 服务。
• 实际做法是在每个 PR 的 CI 中运行 Judges，发布报告或检查结果，并让 Copilot 和人工审查者在审查时使用这些输出。

选项 A（推荐）：PR 工作流检查 + 报告工件

创建 .github/workflows/judges-pr-review.yml：

name: Judges PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  judges:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install
        run: npm ci

      - name: Generate Judges report
        run: |
          npx tsx -e "import { generateRepoReportFromLocalPath } from './src/reports/public-repo-report.ts';
          const result = generateRepoReportFromLocalPath({
            repoPath: process.cwd(),
            outputPath: 'judges-pr-report.md',
            maxFiles: 600,
            maxFindingsInReport: 150,
          });
          console.log('Overall:', result.overallVerdict, result.averageScore);"

      - name: Upload report artifact
        uses: actions/upload-artifact@v4
        with:
          name: judges-pr-report
          path: judges-pr-report.md

这样，每个 PR 都会生成可复现的 Judges 输出，供团队（以及 Copilot）参考。

选项 B：在仓库中添加 Copilot 自定义指令

添加 .github/instructions/judges.instructions.md，并写入如下指导：

When reviewing pull requests:
1. Read the latest Judges report artifact/check output first.
2. Prioritize CRITICAL and HIGH findings in remediation guidance.
3. If findings conflict, defer to security/compliance-related Judges.
4. Include rule IDs (e.g., DATA-001, CYBER-004) in suggested fixes.

这有助于使 Copilot 的反馈与 Judges 的发现保持一致。

---

CLI 参考

所有命令都支持使用 --help 查看用法详情。

judges eval

使用全部 45 个评审器或单个评审器评估文件。

标志	说明
--file <path> / 位置参数	要评估的文件
--judge <id> / -j <id>	单个评审器模式
--language <lang> / -l <lang>	语言提示（根据扩展名自动检测）
--format <fmt> / -f <fmt>	输出格式：text、json、sarif、markdown、html、pdf、junit、codeclimate、github-actions
--output <path> / -o <path>	将输出写入文件
--fail-on-findings	如果判定结果为 FAIL，则以代码 1 退出
--baseline <path> / -b <path>	JSON 基线文件 — 忽略已知发现
--summary	打印单行摘要（非常适合脚本使用）
--config <path>	加载 .judgesrc / .judgesrc.json 配置文件
--preset <name>	使用指定预设（所有 22 个选项见命名预设）
--min-score <n>	如果总分低于此阈值，则以代码 1 退出
--verbose	打印计时和调试信息
--quiet	隐藏非必要输出
--no-color	禁用 ANSI 颜色

judges init

交互式向导，用于生成项目配置：

• .judgesrc.json — 规则自定义、禁用的评审器、严重性阈值
• .github/workflows/judges.yml — GitHub Actions CI 工作流
• .gitlab-ci.judges.yml — GitLab CI 流水线（可选）
• azure-pipelines.judges.yml — Azure Pipelines（可选）

judges fix

预览或应用确定性发现对应的自动修复补丁。

标志	说明
位置参数	要修复的文件
--apply	将补丁写入磁盘（默认：试运行）
--judge <id>	限定为单个评审器的发现

judges watch

持续重新评估保存的文件。

标志	说明
位置参数	要监视的文件或目录（默认：.）
--judge <id>	单个评审器模式
--fail-on-findings	如果任何评估失败，则以非零状态退出

judges report

对本地目录运行完整的项目级审查。

标志	描述
positional	目录路径（默认：.）
--format <fmt>	输出格式：text、json、html、markdown
--output <path>	将报告写入文件
--max-files <n>	要分析的最大文件数（默认：600）
--max-file-bytes <n>	跳过大于此大小的文件（默认：300000）

judges hook

管理 Git pre-commit 钩子，在暂存文件上运行 Judges。

judges hook install    # add pre-commit hook
judges hook uninstall  # remove pre-commit hook

检测 Husky（.husky/pre-commit），并在未检测到时回退到 .git/hooks/pre-commit。使用基于标记的注入方式，因此不会覆盖现有钩子。

judges diff

仅评估统一差异中的更改行（例如，git diff 输出）。

标志	描述
--file <path>	从文件读取差异，而非从 stdin 读取
--format <fmt>	输出格式：text、json、sarif、junit、codeclimate
--output <path>	将输出写入文件

git diff HEAD~1 | judges diff
judges diff --file changes.patch --format sarif

judges deps

分析项目依赖项中的供应链风险。

标志	描述
--path <dir>	要扫描的项目根目录（默认：.）
--format <fmt>	输出格式：text、json

judges deps --path .
judges deps --path ./backend --format json

judges baseline

创建基线文件，以便在后续评估中抑制已知问题。

judges baseline create --file src/api.ts
judges baseline create --file src/api.ts -o .judges-baseline.json

judges ci-templates

为常用提供商生成 CI/CD 配置模板。

judges ci-templates --provider github   # .github/workflows/judges.yml
judges ci-templates --provider gitlab   # .gitlab-ci.judges.yml
judges ci-templates --provider azure    # azure-pipelines.judges.yml
judges ci-templates --provider bitbucket # bitbucket-pipelines.yml (snippet)

judges docs

以 Markdown 格式生成各审查器的规则文档。

标志	描述
--judge <id>	为单个审查器生成文档
--output <dir>	为每个审查器生成单独的 .md 文件

judges docs                          # all judges to stdout
judges docs --judge cybersecurity    # single judge
judges docs --output docs/judges/    # write files to directory

judges completions

生成 Shell 补全脚本。

eval "$(judges completions bash)"        # Bash
eval "$(judges completions zsh)"         # Zsh
judges completions fish | source         # Fish
judges completions powershell            # PowerShell (Register-ArgumentCompleter)

命名预设

使用 --preset 应用预先配置的评估设置：

预设	描述
strict	所有严重级别、所有审查器 — 最全面的检查
lenient	仅检查高危和严重问题 — 快速且聚焦
security-only	聚焦安全 — 禁用非安全审查器（成本、可扩展性、文档、a11y、i18n、UX 等）
startup	跳过合规、数据主权、i18n 审查器 — 快速推进
compliance	仅检查合规、数据主权、身份验证 — 聚焦监管要求
performance	仅检查性能、可扩展性、缓存、成本效益
react	针对 React/Next.js 应用调优 — 启用无障碍访问、XSS 防护
express	针对 Express.js API 调优 — 中间件安全、身份验证、CORS、速率限制
fastapi	针对 Python FastAPI 调优 — 输入验证、异步模式、API 安全
django	针对 Django 应用调优 — 模板安全、ORM 误用、CSRF
spring-boot	针对 Java Spring Boot 调优 — 注入、配置、Actuator 安全
rails	针对 Ruby on Rails 调优 — 批量赋值、CSRF、SQL 注入
nextjs	针对 Next.js 调优 — 服务端/客户端安全、API 路由、SSR/ISR
terraform	针对 Terraform/OpenTofu IaC 调优 — 基础设施安全、合规
kubernetes	针对 K8s 清单调优 — 安全上下文、RBAC、资源限制
onboarding	首次采用时使用的智能默认设置 — 抑制噪声较多的规则
fintech	金融服务 — PCI DSS、密码学、身份验证、审计
healthtech	医疗健康 — HIPAA 合规、数据主权、加密、审计跟踪
saas	多租户 SaaS — 租户隔离、速率限制、可扩展性
government	政府/公共部门 — 合规、数据主权、身份验证
open-source	开源项目 — 文档、向后兼容性、安全、依赖项健康状况
ai-review	AI 生成代码审查 — 幻觉检测、安全、身份验证、正确性

judges eval --preset security-only src/api.ts
judges eval --preset strict --format sarif src/app.ts > results.sarif

CI 输出格式

JUnit XML

为 Jenkins、Azure DevOps、GitHub Actions 或 GitLab 测试结果查看器生成 JUnit XML：

judges eval --format junit src/api.ts > results.xml

每个评审器对应一个 <testsuite>，每项发现都对应一个 <testcase>；对于严重或高严重性的问题，使用 <failure>。

CodeClimate / GitLab Code Quality

为 GitLab Code Quality 或类似工具生成 CodeClimate JSON：

judges eval --format codeclimate src/api.ts > codequality.json

评分徽章

为 README 生成 SVG 或文本徽章：

import { generateBadgeSvg, generateBadgeText } from "@kevinrabun/judges/badge";

const svg = generateBadgeSvg(85);          // shields.io-style SVG
const text = generateBadgeText(85);        // "✓ judges 85/100"
const svg2 = generateBadgeSvg(75, "quality"); // custom label

---

评审面板

评审器	领域	规则前缀	评估内容
数据安全	数据安全与隐私	DATA-	加密、PII 处理、密钥管理、访问控制
网络安全	网络安全与威胁防御	CYBER-	注入攻击、XSS、CSRF、身份验证漏洞、OWASP Top 10
成本效益	成本优化与资源效率	COST-	算法效率、N+1 查询、内存浪费、缓存策略
可扩展性	可扩展性与性能	SCALE-	无状态设计、水平扩展、并发、瓶颈
云就绪性	云原生架构与 DevOps	CLOUD-	12-Factor 合规性、容器化、优雅关停、IaC
软件实践	软件工程最佳实践与安全 SDLC	SWDEV-	SOLID 原则、类型安全、错误处理、输入验证
无障碍性	无障碍性（a11y）	A11Y-	WCAG 合规性、屏幕阅读器支持、键盘导航、ARIA
API 设计	API 设计与契约	API-	REST 规范、版本控制、分页、错误响应
可靠性	可靠性与韧性	REL-	错误处理、超时、重试、断路器
可观测性	监控与诊断	OBS-	结构化日志、运行状况检查、指标、追踪
性能	运行时性能	PERF-	N+1 查询、同步 I/O、缓存、内存泄漏
合规性	法规与许可证合规性	COMP-	GDPR/CCPA、PII 保护、同意、数据保留、审计跟踪
数据主权	数据、技术与运营主权	SOV-	数据驻留、跨境传输、供应商密钥管理、AI 模型可移植性、身份联合、断路器、审计跟踪、数据导出
测试	测试质量与覆盖率	TEST-	测试覆盖率、断言、测试隔离、命名
文档	文档与开发者体验	DOC-	JSDoc/docstrings、魔法数字、TODO、代码注释
国际化	i18n 与本地化	I18N-	硬编码字符串、区域设置处理、货币格式化
依赖项健康度	供应链与依赖项	DEPS-	版本固定、已弃用的软件包、供应链
并发	并发与线程安全	CONC-	竞态条件、无界并行、缺少 await
伦理与偏见	AI/ML 公平性与伦理	ETHICS-	人口统计逻辑、暗黑模式、包容性语言
可维护性	代码可维护性与技术债务	MAINT-	any 类型、魔法数字、深层嵌套、死代码、文件长度
错误处理	错误处理与容错	ERR-	空 catch 块、缺少错误处理器、错误被吞掉
身份验证	身份验证与授权	AUTH-	硬编码凭据、缺少身份验证中间件、令牌置于查询参数中
数据库	数据库设计与查询效率	DB-	SQL 注入、N+1 查询、连接池、事务
缓存	缓存策略与数据新鲜度	CACHE-	无界缓存、缺少 TTL、缺少 HTTP 缓存标头
配置管理	配置与密钥管理	CFG-	硬编码密钥、缺少环境变量、配置验证
向后兼容性	向后兼容性与版本控制	COMPAT-	API 版本控制、破坏性更改、响应一致性
可移植性	平台可移植性与供应商独立性	PORTA-	特定于操作系统的路径、供应商锁定、硬编码主机
用户体验	用户体验与界面质量	UX-	加载状态、错误消息、分页、破坏性操作
日志隐私	日志隐私与数据脱敏	LOGPRIV-	日志中的 PII、记录令牌、结构化日志、脱敏
速率限制	速率限制与流量控制	RATE-	缺少速率限制、无界查询、退避策略
CI/CD	CI/CD 流水线与部署安全性	CICD-	测试基础设施、lint 配置、Docker 标签、构建脚本
代码结构	结构分析	STRUCT-	圈复杂度、嵌套深度、函数长度、死代码、类型安全
Agent 指令	Agent 指令 Markdown 质量与安全性	AGENT-	指令层级、冲突检测、不安全的覆盖指令、范围、验证、策略指导
AI 代码安全	AI 生成代码的质量与安全性	AICS-	提示词注入、不安全的大模型输出处理、调试默认值、缺少验证、对 AI 响应进行不安全的反序列化
框架安全	特定框架的安全性与最佳实践	FW-	React hooks 排序、Express 中间件链、Next.js SSR/SSG 陷阱、Angular/Vue 生命周期模式、Django/Flask/FastAPI 安全性、Spring Boot 安全性、ASP.NET Core 身份验证与 CORS、Go Gin/Echo/Fiber 模式
IaC 安全	基础设施即代码	IAC-	Terraform、Bicep、ARM 模板配置错误、硬编码密钥、缺少加密、网络/IAM 规则权限过宽
安全性	整体安全态势	SEC-	全面安全评估——不安全的数据流、弱加密、不安全的反序列化
幻觉检测	AI 幻觉 API 与导入项验证	HALLU-	检测 AI 代码生成器生成的幻觉 API、虚构导入项和不存在的模块
意图对齐	代码与注释对齐及存根检测	INTENT-	检测声明意图与实现之间的不匹配、占位存根、仅包含 TODO 的函数
API 契约符合性	API 设计与 REST 最佳实践	API-	API 端点输入验证、REST 符合性、请求/响应契约一致性
多轮连贯性	代码连贯性与一致性	COH-	自相矛盾的模式、重复定义、死代码、命名不一致
模型指纹检测	AI 代码来源与模型归属	MFPR-	检测特定 AI 代码生成器特有的风格指纹
过度工程化	简洁性与实用性	OVER-	不必要的抽象、过度包装、过早泛化、过于复杂的模式
逻辑审查	语义正确性与逻辑完整性	LOGIC-	条件反转、死代码、名称与函数体不匹配、差一错误、不完整的控制流
误报审查	误报检测与发现准确性	FPR-	元评审器，用于审查基于模式的发现是否存在误报：字符串字面量上下文、注释/docstring 匹配、测试脚手架、IaC 模板门控

---

工作原理

该评审系统分为三层：

1. 基于模式的分析 — 所有工具（evaluate_code、evaluate_code_single_judge、evaluate_project、evaluate_diff）都会使用正则表达式模式匹配进行启发式分析，以捕获常见反模式。这一层即时、确定性，并完全离线运行，不会调用任何外部 API。

2. 基于 AST 的结构分析 — 代码结构评审器（STRUCT-* 规则）使用真正的抽象语法树解析，精确衡量圈复杂度、嵌套深度、函数长度、参数数量、死代码和类型安全，而这些精度是正则表达式无法达到的。所有受支持的语言——TypeScript、JavaScript、Python、Rust、Go、Java、C# 和 C++——均通过 tree-sitter WASM 语法解析器进行解析（编译为 WebAssembly 的真实语法树，在进程内运行，无原生依赖）。当 WASM 语法解析器不可用时，会使用作用域跟踪结构解析器作为后备方案。无需外部 AST 服务。

3. LLM 驱动的深度分析（提示词） — 该服务提供 MCP 提示词（例如 judge-data-security、judge-cybersecurity），将每位评审专家的角色设定作为系统提示词提供。当由基于 LLM 的客户端（Copilot、Claude、Cursor 等）使用时，宿主 LLM 会进行更深入、能结合上下文的概率分析，超越静态模式所能检测的范围。每位评审器上的 systemPrompt 正是在此发挥作用——Judges 本身不会调用 LLM，但会提供专家评审标准，让你的 AI 助手能够充当 45 位专业评审。

---

按组合设计

Judges Panel 是一个双层评审系统：提供即时的确定性工具（离线运行，无需 API 密钥）进行模式和 AST 分析；还提供 45 个专家角色 MCP 提示词，连接 AI 客户端后即可启用 LLM 驱动的深度分析。它并非试图充当 CVE 扫描器或代码检查工具。这些功能应由专用 MCP 服务提供，并由 AI Agent 与 Judges 协同编排。

内置 AST 分析

与早期版本建议另用独立 AST MCP 服务不同，Judges Panel 现在开箱即提供真正基于 AST 的结构分析：

• TypeScript、JavaScript、Python、Rust、Go、Java、C#、C++ — 全部使用统一的 tree-sitter WASM 引擎进行解析，以实现完整的语法树分析（函数、复杂度、嵌套、死代码、类型安全）。当 WASM 语法解析器不可用时，会回退到作用域跟踪结构解析器

代码结构评审器（STRUCT-*）使用这些解析器进行精确衡量：

规则	指标	阈值
STRUCT-001	圈复杂度	每个函数 > 10（高）
STRUCT-002	嵌套深度	> 4 层（中）
STRUCT-003	函数长度	> 50 行（中）
STRUCT-004	参数数量	> 5 个参数（中）
STRUCT-005	死代码	无法到达的语句（低）
STRUCT-006	弱类型	any、dynamic、Object、interface{}、unsafe（中）
STRUCT-007	文件复杂度	总圈复杂度 > 40（高）
STRUCT-008	极高复杂度	每个函数 > 20（严重）
STRUCT-009	参数过多	> 8 个参数（高）
STRUCT-010	函数长度过长	> 150 行（高）

推荐的 MCP 技术栈

当 AI 编码助手连接到多个 MCP 服务时，每个服务都能发挥其专长：

┌─────────────────────────────────────────────────────────┐
│                   AI Coding Assistant                   │
│              (Claude, Copilot, Cursor, etc.)            │
└──────┬──────────────────┬──────────┬───────────────────┘
       │                  │          │
       ▼                  ▼          ▼
  ┌──────────────┐  ┌────────┐  ┌────────┐
  │   Judges     │  │  CVE / │  │ Linter │
  │   Panel      │  │  SBOM  │  │ Server │
  │ ─────────────│  └────────┘  └────────┘
  │ 44 Heuristic │   Vuln DB     Style &
  │   judges     │   scanning    correctness
  │ + AST judge  │
  └──────────────┘
   Patterns +
   structural
   analysis

层级	功能	示例服务
评审团	45 位评审组成的质量门禁——安全模式、AST 分析、成本、可扩展性、无障碍、合规性、主权、伦理、依赖项健康度、Agent 指令治理、AI 代码安全、框架安全	本服务
CVE / SBOM	对照实时数据库扫描漏洞——已知 CVE、许可证风险、供应链	OSV、Snyk、Trivy、Grype MCP 服务
代码检查	特定语言的风格与正确性规则	ESLint、Ruff、Clippy MCP 服务
运行时分析	测量运行中代码的内存、CPU 和延迟	自定义性能分析 MCP 服务

实际应用

当你问 AI 助手 “这段代码可以用于生产环境吗？” 时，Agent 可以：

1. 评审团 → 扫描硬编码密钥、缺失的错误处理、N+1 查询、无障碍方面的不足、合规性问题，并且通过 AST 分析复杂度、检测死代码并标记深度嵌套的函数
2. CVE 服务 → 检查 package.json 中的每个依赖项是否存在已知漏洞
3. 代码检查服务 → 执行团队风格规则，发现特定语言中的常见问题

每个服务都会返回结构化的发现结果。AI 会综合所有信息，生成一份单一且可执行的评审——无需任何一个服务包揽所有工作。

---

MCP 工具

evaluate_v2

运行 V2 上下文感知评审团评估，旨在将反馈质量提升至首席工程师／架构师级别的评审水平：

• 策略配置校准（default、startup、regulated、healthcare、fintech、public-sector）
• 上下文摄取（架构说明、约束、标准、已知风险、数据边界模型）
• 运行时证据挂钩（测试、覆盖率、延迟、错误率、漏洞数量）
• 按评审者／领域聚合专业反馈
• 置信度评分并明确报告不确定性

支持：

• 代码模式：code + language
• 项目模式：files[]

参数	类型	必需	说明
code	string	条件必需	单文件模式的源代码
language	string	条件必需	单文件模式的编程语言
files	array	条件必需	项目模式的 { path, content, language }[]
context	string	否	高层评审上下文
includeAstFindings	boolean	否	包含 AST／代码结构发现结果（默认值：true）
minConfidence	number	否	纳入发现结果的最低置信度（0-1，默认值：0）
policyProfile	enum	否	default、startup、regulated、healthcare、fintech、public-sector
evaluationContext	object	否	结构化架构／约束上下文
evidence	object	否	用于校准置信度的运行时／运维证据

evaluate_app_builder_flow

为技术和非技术相关人员运行 3 步应用构建工作流：

1. 评审团审查（代码／项目／差异）
2. 将主要风险翻译成通俗易懂的语言
3. 按优先级排列修复任务，并提取可由 AI 修复的 P0/P1 问题

支持：

• 代码模式：code + language
• 项目模式：files[]
• 差异模式：code + language + changedLines[]

参数	类型	必填	说明
code	string	条件必填	完整源内容（代码／差异模式）
language	string	条件必填	编程语言（代码／差异模式）
files	array	条件必填	项目模式下的 { path, content, language }[]
changedLines	number[]	否	差异模式中发生变更的行号，从 1 开始
context	string	否	可选的业务／技术背景
maxFindings	number	否	翻译后的主要问题数量上限（默认值：10）
maxTasks	number	否	生成的任务数量上限（默认值：20）
includeAstFindings	boolean	否	包含 AST／代码结构问题（默认值：true）
minConfidence	number	否	纳入问题所需的最低置信度（0-1，默认值：0）

evaluate_public_repo_report

克隆一个公开代码仓库 URL，对符合条件的源文件运行完整评审团，并生成汇总的 Markdown 报告。

参数	类型	必填	说明
repoUrl	string	是	公开代码仓库 URL（https://...）
branch	string	否	可选分支名称
outputPath	string	否	写入报告 Markdown 的可选路径
maxFiles	number	否	分析的文件数量上限（默认值：600）
maxFileBytes	number	否	文件大小上限，单位为字节（默认值：300000）
maxFindingsInReport	number	否	输出中的详细问题数量上限（默认值：150）
credentialMode	string	否	凭据检测模式：standard（默认）或 strict
includeAstFindings	boolean	否	包含 AST／代码结构问题（默认值：true）
minConfidence	number	否	纳入问题所需的最低置信度（0-1，默认值：0）
enableMustFixGate	boolean	否	启用针对高置信度危险问题的必修复门槛摘要（默认值：false）
mustFixMinConfidence	number	否	触发必修复门槛所需的置信度阈值（0-1，默认值：0.85）
mustFixDangerousRulePrefixes	string[]	否	用于门槛匹配的可选危险规则前缀（例如：AUTH、CYBER、DATA）
keepClone	boolean	否	将克隆的代码仓库保留在磁盘上以供检查

快速示例

通过 CLI 生成报告：

npm run report:public-repo -- --repoUrl https://github.com/microsoft/vscode --output reports/vscode-judges-report.md

# stricter credential-signal mode (optional)
npm run report:public-repo -- --repoUrl https://github.com/openclaw/openclaw --credentialMode strict --output reports/openclaw-judges-report-strict.md

# judge findings only (exclude AST/code-structure findings)
npm run report:public-repo -- --repoUrl https://github.com/openclaw/openclaw --includeAstFindings false --output reports/openclaw-judges-report-no-ast.md

# show only findings at 80%+ confidence
npm run report:public-repo -- --repoUrl https://github.com/openclaw/openclaw --minConfidence 0.8 --output reports/openclaw-judges-report-high-confidence.md

# include must-fix gate summary in the generated report
npm run report:public-repo -- --repoUrl https://github.com/openclaw/openclaw --enableMustFixGate true --mustFixMinConfidence 0.9 --mustFixDangerousPrefix AUTH --mustFixDangerousPrefix CYBER --output reports/openclaw-judges-report-mustfix.md

# opinionated quick-start mode (recommended first run)
npm run report:quickstart -- --repoUrl https://github.com/openclaw/openclaw --output reports/openclaw-quickstart.md

通过 MCP 客户端调用：

{
  "tool": "evaluate_public_repo_report",
  "arguments": {
    "repoUrl": "https://github.com/microsoft/vscode",
    "branch": "main",
    "maxFiles": 400,
    "maxFindingsInReport": 120,
    "credentialMode": "strict",
    "includeAstFindings": false,
    "minConfidence": 0.8,
    "enableMustFixGate": true,
    "mustFixMinConfidence": 0.9,
    "mustFixDangerousRulePrefixes": ["AUTH", "CYBER", "DATA"],
    "outputPath": "reports/vscode-judges-report.md"
  }
}

典型响应摘要包括：

• 总体判定和平均分
• 已分析文件数量和问题总数
• 各评审员的评分表
• 风险最高的问题和得分最低的文件

报告片段示例：

# Public Repository Full Judges Report

Generated from https://github.com/microsoft/vscode on 2026-02-21T12:00:00.000Z.

## Executive Summary
- Overall verdict: WARNING
- Average file score: 78/100
- Total findings: 412 (critical 3, high 29, medium 114, low 185, info 81)

get_judges

列出所有可用的评审员及其领域和说明。

evaluate_code

提交代码以供完整评审团评估。全部 45 位评审员会独立评估并返回综合判定。

参数	类型	必填	说明
code	string	是	要评估的源代码
language	string	是	编程语言（例如：typescript、python）
context	string	否	有关代码的其他背景信息
includeAstFindings	boolean	否	包含 AST／代码结构问题（默认值：true）
minConfidence	number	否	纳入问题所需的最低置信度（0-1，默认值：0）
config	object	否	内联配置（参见配置）

evaluate_code_single_judge

将代码提交给指定评审器，进行有针对性的审查。

参数	类型	必填	描述
code	string	是	要评估的源代码
language	string	是	编程语言
judgeId	string	是	参见下方的评审器 ID
context	string	否	补充上下文
minConfidence	number	否	纳入结果的最低发现置信度（0-1，默认值：0）
config	object	否	内联配置（参见配置）

evaluate_project

提交多个文件进行项目级分析。全部 45 个评审器都会评估每个文件，并通过跨文件架构分析检测代码重复、错误处理不一致和依赖循环。

参数	类型	必填	描述
files	array	是	{ path, content, language } 对象数组
context	string	否	可选的项目上下文
includeAstFindings	boolean	否	纳入 AST/代码结构方面的发现（默认值：true）
minConfidence	number	否	纳入结果的最低发现置信度（0-1，默认值：0）
config	object	否	内联配置（参见配置）

evaluate_diff

仅评估代码差异中的变更行。会运行全部 45 个评审器检查完整文件，但只筛选出现在指定行上的发现。非常适合 PR 审查和增量分析。

参数	类型	必填	描述
code	string	是	完整的文件内容（变更后）
language	string	是	编程语言
changedLines	number[]	是	已变更的行号（从 1 开始）
context	string	否	有关变更的可选上下文
includeAstFindings	boolean	否	纳入 AST/代码结构方面的发现（默认值：true）
minConfidence	number	否	纳入结果的最低发现置信度（0-1，默认值：0）
config	object	否	内联配置（参见配置）

analyze_dependencies

分析依赖清单文件，以检查供应链风险、版本固定问题、仿冒包指示因素和依赖管理规范。支持 package.json、requirements.txt、Cargo.toml、go.mod、pom.xml 和 .csproj 文件。

参数	类型	必填	描述
manifest	string	是	依赖清单文件的内容
manifestType	string	是	文件类型：package.json、requirements.txt 等
context	string	否	可选上下文

evaluate_git_diff

仅评估 git 差异中的变更行。提供 repoPath 获取实时 git 差异，或提供 diffText 使用预先计算的统一差异。

参数	类型	必填	描述
repoPath	string	条件必填	git 仓库的绝对路径
base	string	否	用于比较差异的 Git 引用（默认值：HEAD~1）
diffText	string	条件必填	预先计算的统一差异文本
confidenceFilter	number	否	发现的最低置信度阈值（0–1）
autoTune	boolean	否	应用基于反馈的自动调优（默认值：false）
maxPromptChars	number	否	大模型提示词的最大字符数（默认值：100000，0 = 不限）
config	object	否	内联配置

re_evaluate_with_context

将先前的发现作为上下文重新运行审查，以便迭代优化。支持争议解决、注入开发者上下文，以及按关注领域筛选。

参数	类型	必填	说明
code	string	是	要重新评估的源代码
language	string	是	编程语言
disputedRuleIds	string[]	否	开发者认为属于误报并提出异议的规则 ID
acceptedRuleIds	string[]	否	开发者认可的规则 ID
developerContext	string	否	对开发者意图的自由格式说明
focusAreas	string[]	否	要重点关注的特定领域（例如，["security"]）
confidenceFilter	number	否	最低置信度阈值（默认值：0.5）
filePath	string	否	用于感知上下文评估的文件路径
deepReview	boolean	否	包含大模型深度审查提示词部分
relatedFiles	array	否	跨文件上下文 { path, snippet, relationship? }[]
maxPromptChars	number	否	大模型提示词的最大字符数（默认值：100000，0 = 不限）

其他 MCP 工具

工具	说明
evaluate_file	从磁盘读取文件并提交给完整评审组。根据扩展名自动检测语言。
evaluate_code_streaming	流式评估——每位评审完成后立即返回其结果，并提供实时汇总。
evaluate_focused	仅运行指定的评审器。完成初次全面评估后，可用此工具重新检查特定领域。
evaluate_batch	单次调用评估多个代码文件。返回每个文件的判定结果及汇总统计信息。
evaluate_then_fix	评估代码并自动为所有发现的问题生成修复补丁，支持自动修复。
evaluate_with_progress	评估时提供进度回调，适用于耗时较长的评估。
evaluate_policy_aware	使用命名配置文件（startup、regulated、healthcare、fintech、public-sector）进行符合策略要求的评估。
fix_code	评估代码并应用所有可用的自动修复补丁。返回已修复代码，以及已应用／剩余问题摘要。
explain_finding	用通俗语言解释一项发现，提供 OWASP／CWE 参考、风险背景和修复指导。
triage_finding	设置一项发现的分诊状态（accepted-risk、deferred、wont-fix、false-positive），并记录归属信息。
record_feedback	记录用户反馈（true-positive、false-positive、wont-fix），以校准置信度分数。
get_finding_stats	发现项生命周期统计：未解决、已修复、重复出现和已分诊的数量及趋势。
get_suppression_analytics	分析抑制模式：按规则统计误报率、抑制率和自动抑制候选项。
list_triaged_findings	列出已分诊的发现项，也可按分诊状态筛选。
benchmark_gate	根据质量阈值运行基准测试。返回通过／失败结果，以及 F1、精确率和召回率指标。
run_benchmark	运行完整的基准测试套件，并按评审器、类别和难度细分结果。
scaffold_judge	生成新增评审器所需的样板文件：定义、评估器框架和注册代码。
scaffold_plugin	生成插件入门模板，包含自定义规则、评审器和生命周期钩子。
session_status	当前评估会话状态：评估次数、框架、判定历史和稳定性。
list_files	列出工作区中的文件和目录，用于探索项目。
read_file	读取工作区中的文件内容。

Judge IDs

data-security · cybersecurity · security · cost-effectiveness · scalability · cloud-readiness · software-practices · accessibility · api-design · api-contract · reliability · observability · performance · compliance · data-sovereignty · testing · documentation · internationalization · dependency-health · concurrency · ethics-bias · maintainability · error-handling · authentication · database · caching · configuration-management · backwards-compatibility · portability · ux · logging-privacy · rate-limiting · ci-cd · code-structure · agent-instructions · ai-code-safety · framework-safety · iac-security · hallucination-detection · intent-alignment · multi-turn-coherence · model-fingerprint · over-engineering · logic-review · false-positive-review

---

MCP 提示词

每个审查器都对应一个用于大模型深度分析的提示词：

提示词	描述
judge-data-security	深度数据安全审查
judge-cybersecurity	深度网络安全审查
judge-cost-effectiveness	深度成本优化审查
judge-scalability	深度可扩展性审查
judge-cloud-readiness	深度云就绪度审查
judge-software-practices	深度软件实践审查
judge-accessibility	深度无障碍/WCAG 审查
judge-api-design	深度 API 设计审查
judge-reliability	深度可靠性与弹性审查
judge-observability	深度可观测性与监控审查
judge-performance	深度性能优化审查
judge-compliance	深度法规合规审查
judge-data-sovereignty	深度数据、技术与运营主权审查
judge-testing	深度测试质量审查
judge-documentation	深度文档质量审查
judge-internationalization	深度国际化（i18n）审查
judge-dependency-health	深度依赖项健康状况审查
judge-concurrency	深度并发与异步安全审查
judge-ethics-bias	深度伦理与偏见审查
judge-maintainability	深度可维护性与技术债务审查
judge-error-handling	深度错误处理审查
judge-authentication	深度身份验证与授权审查
judge-database	深度数据库设计与查询审查
judge-caching	深度缓存策略审查
judge-configuration-management	深度配置与密钥审查
judge-backwards-compatibility	深度向后兼容性审查
judge-portability	深度平台可移植性审查
judge-ux	深度用户体验审查
judge-logging-privacy	深度日志隐私审查
judge-rate-limiting	深度速率限制审查
judge-ci-cd	深度 CI/CD 流水线审查
judge-code-structure	深度基于 AST 的结构分析审查
judge-agent-instructions	深度审查 Agent 指令 Markdown 的质量与安全性
judge-ai-code-safety	深度审查 AI 生成代码的风险：提示注入、不安全的大模型输出处理、调试默认值、缺少验证
judge-framework-safety	深度审查特定框架的安全性：React hooks、Express 中间件、Next.js SSR/SSG、Angular/Vue、Django、Spring Boot、ASP.NET Core、Flask、FastAPI、Go 框架
judge-iac-security	深度审查基础设施即代码安全性：Terraform、Bicep、ARM 模板配置错误
judge-security	深度全面审查安全态势：不安全的数据流、弱加密、不安全的反序列化
judge-hallucination-detection	深度审查 AI 幻觉生成的 API、虚构的导入项、不存在的模块
judge-intent-alignment	深度审查代码与注释的一致性、存根检测、占位函数
judge-api-contract	深度审查 API 契约符合性、输入验证、REST 最佳实践
judge-multi-turn-coherence	深度审查代码连贯性：自相矛盾、重复定义、死代码
judge-model-fingerprint	深度审查 AI 代码来源与模型归属指纹
judge-over-engineering	深度审查不必要的抽象、过度封装、过早泛化
judge-logic-review	深度审查逻辑正确性、语义不匹配以及 AI 生成代码中的死代码
judge-false-positive-review	元审查器审查基于模式的发现项，以检测误报并评估准确性

---

配置

在项目根目录中创建 .judgesrc.json（或 .judgesrc）文件，以自定义评估行为。请参阅 .judgesrc.example.json 获取可直接复制粘贴的模板，或参考 JSON Schema 获取完整的 IDE 自动补全支持。

{
  "$schema": "https://github.com/KevinRabun/judges/blob/main/judgesrc.schema.json",
  "preset": "strict",
  "minSeverity": "medium",
  "disabledRules": ["COST-*", "I18N-001"],
  "disabledJudges": ["accessibility", "ethics-bias"],
  "ruleOverrides": {
    "SEC-003": { "severity": "critical" },
    "DOC-*": { "disabled": true }
  },
  "languages": ["typescript", "python"],
  "format": "text",
  "failOnFindings": false,
  "baseline": "",
  "regulatoryScope": ["GDPR", "PCI-DSS", "SOC2"],
  "consensusThreshold": 0.7
}

字段	类型	默认值	描述
$schema	string	—	用于 IDE 验证的 JSON Schema URL
preset	string	—	命名预设（全部 22 个选项请参阅命名预设）
minSeverity	string	"info"	要报告的最低严重级别：critical · high · medium · low · info
disabledRules	string[]	[]	要抑制的规则 ID 或前缀通配符（例如 "COST-*", "SEC-003"）
disabledJudges	string[]	[]	要完全跳过的 Judge ID（例如 "cost-effectiveness"）
ruleOverrides	object	{}	按规则 ID 或通配符指定的规则覆盖项 — { disabled?: boolean, severity?: string }
languages	string[]	[]	将分析范围限制为特定语言（空值 = 全部语言）
format	string	"text"	默认输出格式：text · json · sarif · markdown · html · pdf · junit · codeclimate · github-actions
failOnFindings	boolean	false	当判定结果为 fail 时返回退出代码 1 — 适用于 CI 门禁
baseline	string	""	基线 JSON 文件的路径 — 匹配的发现项将被抑制
plugins	string[]	[]	导出自定义 Judge 的插件模块说明符（npm 包或相对路径）
judgeWeights	object	{}	用于汇总评分的各 Judge 加权重要性（例如 { "cybersecurity": 2.0 }）
failOnScoreBelow	number	—	运行通过所需的最低分数（0–100）；可与 failOnFindings 配合使用
regulatoryScope	string[]	—	纳入范围的监管框架（例如 ["GDPR", "PCI-DSS"]）。仅引用范围外框架的发现项将被抑制。运行 judges list --frameworks 可查看支持的值。
consensusThreshold	number	—	共识抑制阈值（0–1）。如果达到此比例的 Judge 未报告任何发现项，则抑制少数 Judge 报告的发现项。建议在 CI 中使用 0.7。
escalationThreshold	number	—	置信度阈值（0–1），低于此阈值的发现项将标记为需要人工审核
overrides	array	[]	按路径指定的配置覆盖项（例如 [{ "files": "**/*.test.ts", "disabledJudges": ["documentation"] }]）
customRules	array	[]	用户自定义的、基于正则表达式的业务逻辑验证规则

所有评估工具（CLI 和 MCP）均可通过 --config <path> 或内联 config 参数接受相同的配置字段。

---

高级功能

内联抑制

使用注释指令直接在源代码中抑制特定发现项：

const x = eval(input); // judges-ignore SEC-001
// judges-ignore-next-line CYBER-002
const y = dangerousOperation();
// judges-file-ignore DOC-*    ← suppress globally for this file

支持的注释样式：//、#、/* */。支持以逗号分隔的规则 ID 和通配符（*、SEC-*）。

自动修复补丁

某些发现项会在 patch 字段中包含可由机器应用的补丁：

模式	自动修复
new Buffer(x)	→ Buffer.from(x)
http:// URL（非 localhost）	→ https://
Math.random()	→ crypto.randomUUID()

补丁包含 oldText、newText、startLine 和 endLine，可用于自动应用。

跨评估器去重

当多个 Judge 标记同一问题时（例如，Data Security 和 Cybersecurity 都检测到第 15 行存在 SQL 注入），系统会自动对发现项去重。保留严重级别最高的发现项，并在描述中添加交叉引用（例如，“也由以下规则识别：CYBER-003”）。

人工关注指南

每次裁决评估都会包含一个 humanFocusGuide，将发现分为三类，供人工审查者参考：

类别	说明	使用时机
✅ 信任	置信度高（≥80%），有证据支持，并通过 AST/污点分析确认的发现	直接采取行动——这些发现有强有力的自动化证据
🔍 核验	置信度较低或基于缺失情况得出的发现	运用你的判断——问题可能存在于项目的其他位置
🔦 盲区	自动化分析无法评估的领域	将人工审查时间集中在这些方面

盲区根据代码特征检测得出：复杂分支逻辑、外部服务调用、财务计算、PII 处理、状态机和复杂正则表达式。该指南会显示在 CLI 文本/Markdown 输出、JSON/SARIF 输出和 GitHub Action 步骤摘要中。

法规范围

在 .judgesrc 中配置适用于项目的法规框架：

{ "regulatoryScope": ["GDPR", "PCI-DSS", "SOC2"] }

仅引用范围外框架的发现会被抑制。未引用法规的一般代码质量发现始终会保留。运行 judges list --frameworks 查看全部 17 个受支持的框架（GDPR、CCPA、HIPAA、PCI-DSS、SOC2、SOX、COPPA、FedRAMP、NIST、ISO27001、ePrivacy、DORA、NIS2、EU-AI-Act 等）。

自我学习式修订

LLM 基准测试系统会为误报率较高的评审器自动生成精确率修订内容。这些由数据驱动的修正会注入提示词，随着基准测试的持续运行提升准确性。

自我学习流程：

1. 运行基准测试 → 分析器找出精确率低于 70% 的评审器
2. 生成有针对性的修订内容（例如：“评审器 ERR：不要将使用框架错误处理中间件的干净 Express 代码标记为问题”）
3. 下一次运行基准测试时加载修订内容 → 精确率提升
4. 运行 judges codify-amendments，将修订内容永久写入分发的软件包

污点流分析

引擎会执行跨过程污点跟踪，追踪数据从用户可控来源（例如 req.body、process.env）经转换后流向安全敏感接收点（例如 eval()、exec()、SQL 查询）的路径。污点流用于提高真阳性发现的置信度，并在检测到清理操作时抑制误报。

正向信号检测

展现良好实践的代码会获得评分加成（最高 +15）：

信号	加成
参数化查询	+3
安全标头（helmet）	+3
身份验证中间件（passport 等）	+3
正确的错误处理	+2
输入验证库（zod、joi 等）	+2
速率限制	+2
结构化日志记录（pino、winston）	+2
CORS 配置	+1
严格模式 / strictNullChecks	+1
测试模式（describe/it/expect）	+1

框架感知规则

评审器包含针对 Express、Django、Flask、FastAPI、Spring、ASP.NET、Rails 等框架的专用检测。框架中间件（例如 helmet()、express-rate-limit、passport.authenticate()）会被识别为缓解措施，从而减少误报。

跨文件导入解析

在项目级分析中，导入会跨文件解析。如果某个文件从项目中的另一个文件导入安全中间件模块，系统会自动降低相关缺少安全控制的发现的置信度。

---

评分

每个评审器都会对代码进行 0 到 100 分的评分：

严重程度	扣分
严重	−30 分
高	−18 分
中	−10 分
低	−5 分
信息	−2 分

判定逻辑：

• FAIL — 存在任何严重发现，或评分 < 60
• WARNING — 存在任何高严重程度发现、任何中严重程度发现，或评分 < 80
• PASS — 评分 ≥ 80，且没有严重、高或中严重程度发现

整体裁决评分是全部 45 个评审器评分的平均值。只要有任何一个评审器判定失败，整体判定就会失败。

---

项目结构

judges/
├── src/
│   ├── index.ts              # MCP server entry point — tools, prompts, transport
│   ├── api.ts                # Programmatic API entry point
│   ├── cli.ts                # CLI argument parser and command router
│   ├── types.ts              # TypeScript interfaces (Finding, JudgeEvaluation, etc.)
│   ├── config.ts             # .judgesrc configuration parser and validation
│   ├── errors.ts             # Custom error types (ConfigError, EvaluationError, ParseError)
│   ├── language-patterns.ts  # Multi-language regex pattern constants and helpers
│   ├── judge-registry.ts     # Unified JudgeRegistry — single source of truth for all judges
│   ├── plugins.ts            # Plugin API façade (delegates to JudgeRegistry)
│   ├── scoring.ts            # Confidence scoring and calibration
│   ├── dedup.ts              # Finding deduplication engine
│   ├── fingerprint.ts        # Finding fingerprint generation
│   ├── comparison.ts         # Tool comparison benchmark data
│   ├── cache.ts              # Evaluation result caching
│   ├── calibration.ts        # Confidence calibration from feedback data
│   ├── fix-history.ts        # Auto-fix application history tracking
│   ├── ast/                  # AST analysis engine (built-in, no external deps)
│   │   ├── index.ts          # analyzeStructure() — routes to correct parser
│   │   ├── types.ts          # FunctionInfo, CodeStructure interfaces
│   │   ├── tree-sitter-ast.ts    # Tree-sitter WASM parser (all 8 languages)
│   │   ├── structural-parser.ts  # Fallback scope-tracking parser
│   │   ├── cross-file-taint.ts   # Cross-file taint propagation analysis
│   │   └── taint-tracker.ts      # Single-file taint flow tracking
│   ├── evaluators/           # Analysis engine for each judge
│   │   ├── index.ts          # evaluateWithJudge(), evaluateWithTribunal(), evaluateProject(), etc.
│   │   ├── shared.ts         # Scoring, verdict logic, markdown formatters
│   │   └── *.ts              # One analyzer per judge (45 files)
│   ├── formatters/           # Output formatters
│   │   ├── sarif.ts              # SARIF 2.1.0 output
│   │   ├── html.ts               # Self-contained HTML report (dark/light theme, filters)
│   │   ├── junit.ts              # JUnit XML output (Jenkins, Azure DevOps, GitHub Actions)
│   │   ├── codeclimate.ts        # CodeClimate/GitLab Code Quality JSON
│   │   ├── diagnostics.ts        # Diagnostics formatter
│   │   └── badge.ts              # SVG and text badge generator
│   ├── commands/             # CLI subcommands
│   │   ├── init.ts               # Interactive project setup wizard
│   │   ├── fix.ts                # Auto-fix patch preview and application
│   │   ├── watch.ts              # Watch mode — re-evaluate on save
│   │   ├── report.ts             # Project-level local report
│   │   ├── hook.ts               # Pre-commit hook install/uninstall
│   │   ├── ci-templates.ts       # GitLab, Azure, Bitbucket CI templates
│   │   ├── diff.ts               # Evaluate unified diff (git diff)
│   │   ├── deps.ts               # Dependency supply-chain analysis
│   │   ├── baseline.ts           # Create baseline for finding suppression
│   │   ├── completions.ts        # Shell completions (bash/zsh/fish/PowerShell)
│   │   ├── docs.ts               # Per-judge rule documentation generator
│   │   ├── feedback.ts           # False-positive tracking & finding feedback
│   │   ├── benchmark.ts          # Detection accuracy benchmark suite
│   │   ├── rule.ts               # Custom rule authoring wizard
│   │   ├── language-packs.ts     # Language-specific rule pack presets
│   │   └── config-share.ts       # Shareable team/org configuration
│   ├── presets.ts            # Named evaluation presets (strict, lenient, security-only, …)
│   ├── patches/
│   │   └── index.ts              # 201 deterministic auto-fix patch rules
│   ├── tools/                # MCP tool registrations
│   │   ├── register.ts           # Tool registration orchestrator
│   │   ├── register-evaluation.ts    # Evaluation tools (evaluate_code, etc.)
│   │   ├── register-workflow.ts      # Workflow tools (app builder, reports, etc.)
│   │   ├── prompts.ts            # MCP prompt registrations (per-judge prompts)
│   │   └── schemas.ts            # Zod schemas for tool parameters
│   ├── reports/
│   │   └── public-repo-report.ts   # Public repo clone + full tribunal report generation
│   └── judges/               # Judge definitions (id, name, domain, system prompt)
│       ├── index.ts          # Side-effect imports + re-exports (JUDGES, getJudge, getJudgeSummaries)
│       └── *.ts              # One self-registering definition per judge (45 files)
├── scripts/
│   ├── generate-public-repo-report.ts  # Run: npm run report:public-repo -- --repoUrl <url>
│   ├── daily-popular-repo-autofix.ts   # Run: npm run automation:daily-popular
│   └── debug-fp.ts                     # Debug false-positive findings
├── examples/
│   ├── sample-vulnerable-api.ts  # Intentionally flawed code (triggers all judges)
│   ├── demo.ts                   # Run: npm run demo
│   └── quickstart.ts             # Quick-start evaluation example
├── tests/
│   ├── judges.test.ts            # Core judge evaluation tests
│   ├── negative.test.ts          # Negative / FP-avoidance tests
│   ├── subsystems.test.ts        # Subsystem integration tests
│   ├── extension-logic.test.ts   # VS Code extension logic tests
│   └── tool-routing.test.ts      # MCP tool routing tests
├── grammars/                 # Tree-sitter WASM grammar files
│   ├── tree-sitter-typescript.wasm
│   ├── tree-sitter-cpp.wasm
│   ├── tree-sitter-python.wasm
│   ├── tree-sitter-go.wasm
│   ├── tree-sitter-rust.wasm
│   ├── tree-sitter-java.wasm
│   └── tree-sitter-c_sharp.wasm
├── judgesrc.schema.json      # JSON Schema for .judgesrc config files
├── server.json               # MCP Registry manifest
├── package.json
├── tsconfig.json
└── README.md

---

脚本

命令	描述
npm run build	将 TypeScript 编译到 dist/
npm run dev	监听模式 — 保存时重新编译
npm test	运行完整测试套件
npm run demo	运行示例审议演示
npm run report:public-repo -- --repoUrl <url>	为公开仓库 URL 生成完整审议报告
npm run report:quickstart -- --repoUrl <url>	使用针对快速上手优化的高信号报告默认设置
npm run automation:daily-popular	每天分析最多 10 个轮换的热门仓库，并为每个仓库最多创建 5 个修复 PR
npm start	启动 MCP 服务
npm run clean	删除 dist/
judges init	交互式项目设置向导
judges fix <file>	预览自动修复补丁（添加 --apply 以写入）
judges watch <dir>	监听模式 — 文件保存时重新评估
judges report <dir>	为本地目录生成完整审议报告
judges hook install	安装 Git 提交前钩子
judges diff	根据统一差异评估已更改的行
judges deps	分析依赖项的供应链风险
judges baseline create	创建用于抑制问题项的基线
judges ci-templates	生成 CI 流水线模板
judges docs	生成各评审器的规则文档
judges completions <shell>	Shell 补全脚本
judges feedback submit	将问题项标记为真阳性、假阳性或不予修复
judges feedback stats	显示假阳性率统计数据
judges benchmark run	运行检测准确率基准测试套件
judges rule create	交互式自定义规则创建向导
judges rule list	列出自定义评估规则
judges pack list	列出可用的语言包
judges config export	将配置导出为可共享的软件包
judges config import <src>	导入共享配置
judges compare	将评审器与其他代码审查工具进行比较
judges list	列出全部 45 个评审器及其领域和描述
judges list --frameworks	列出支持的监管框架及 .judgesrc 的用法
judges codify-amendments	将自我学习的修订内容写入评审器源文件

---

每日热门仓库自动修复

此仓库包含一个定时工作流 .github/workflows/daily-popular-repo-autofix.yml，该工作流会：

• 从默认的 100 多个热门仓库池中每天选取最多 10 个仓库（或使用手动提供的目标），
• 针对受支持的源语言运行完整的 Judges 评估，
• 仅应用保守的单行修复，以减少匹配的问题数量，
• 为每个仓库最多创建 5 个 PR，并注明 Judges 和目标仓库，
• 除非仓库为公开仓库，且可使用现有 GitHub 身份验证创建 PR，否则跳过该仓库（不使用额外的身份验证流程）。
• 将运行上限设为每天 10 个仓库、每个仓库 5 个 PR。

每次运行都会写入 daily-autofix-summary.json（或 SUMMARY_PATH），其中包含每个仓库的遥测数据，包括：

• runAggregate — 精简的运行级汇总数据和跨仓库优先级最高的规则，
• runAggregate.totalCandidatesDiscovered 和 runAggregate.totalCandidatesAfterLocationDedupe — 表示尝试修复前消除了多少重叠项，
• runAggregate.totalCandidatesAfterPriorityThreshold — 应用最低优先级分数后保留的候选项，
• runAggregate.dedupeReductionPercent — 按位置去重后的减少百分比，便于快速跟踪运行效率，
• runAggregate.priorityThresholdReductionPercent — 去重后经过最低优先级筛选的减少百分比，
• priorityRulePrefixesUsed — 优先级排序时使用的危险规则前缀，
• minPriorityScoreUsed — 纳入候选项时采用的最低 candidatePriorityScore，
• candidatesDiscovered、candidatesAfterLocationDedupe 和 candidatesAfterPriorityThreshold — 每个仓库在各筛选阶段后的候选项数量，
• topPrioritizedRuleCounts — 排名候选项中最常见的规则 ID，
• topPrioritizedCandidates — 排名前列的候选项示例（规则、严重程度、置信度、文件、行号、优先级分数）。

可选的运行时控制：

• AUTOFIX_MIN_PRIORITY_SCORE — 去重后候选项所需的最低优先级分数（默认值：0，即禁用）。

必需的密钥：

• JUDGES_AUTOFIX_GH_TOKEN — 具有为目标仓库创建分叉、推送更改和创建 PR 权限的 GitHub 令牌。

手动运行：

gh workflow run "Judges Daily Full-Run Autofix PRs" -f targetRepoUrl=https://github.com/owner/repo

---

程序化 API

Judges 可作为库使用（不只是通过 MCP）。从 @kevinrabun/judges/api 导入：

import {
  evaluateCode,
  evaluateProject,
  evaluateCodeSingleJudge,
  getJudge,
  JUDGES,
  findingsToSarif,
} from "@kevinrabun/judges/api";

// Full tribunal evaluation
const verdict = evaluateCode("const x = eval(input);", "typescript");
console.log(verdict.overallScore, verdict.overallVerdict);

// Single judge
const result = evaluateCodeSingleJudge("cybersecurity", code, "typescript");

// SARIF output for CI integration
const sarif = findingsToSarif(verdict.evaluations.flatMap(e => e.findings));

包导出

入口点	描述
@kevinrabun/judges/api	程序化 API（默认）
@kevinrabun/judges/server	MCP 服务入口点
@kevinrabun/judges/sarif	SARIF 2.1.0 格式化器
@kevinrabun/judges/junit	JUnit XML 格式化器
@kevinrabun/judges/codeclimate	CodeClimate/GitLab Code Quality JSON
@kevinrabun/judges/badge	SVG 和文本徽章生成器
@kevinrabun/judges/diagnostics	诊断信息格式化器
@kevinrabun/judges/plugins	插件系统 API（参见插件指南）
@kevinrabun/judges/fingerprint	问题指纹工具
@kevinrabun/judges/comparison	工具对比基准测试

SARIF 输出

将问题转换为 SARIF 2.1.0，以用于 GitHub Code Scanning、Azure DevOps 和其他 CI/CD 工具：

import { findingsToSarif, evaluationToSarif, verdictToSarif } from "@kevinrabun/judges/sarif";

const sarif = verdictToSarif(verdict, "src/app.ts");
fs.writeFileSync("results.sarif", JSON.stringify(sarif, null, 2));

---

自定义错误类型

所有抛出的错误都继承自 JudgesError，并带有机器可读的 code 属性：

错误类	代码	触发条件
ConfigError	JUDGES_CONFIG_INVALID	.judgesrc 格式错误或内联配置无效
EvaluationError	JUDGES_EVALUATION_FAILED	Judge 未知、分析器崩溃
ParseError	JUDGES_PARSE_FAILED	源代码或输入数据无法解析

import { ConfigError, EvaluationError } from "@kevinrabun/judges/api";
try {
  evaluateCode(code, "typescript");
} catch (e) {
  if (e instanceof ConfigError) console.error("Config issue:", e.code);
}

---

许可证

MIT