Semcheck如何用AI大模型验证代码规范？2026年最新工具指南

Semcheck 是一款利用大语言模型（LLM）来验证您的代码实现是否符合设计规范的工具。您可以通过内联注释直接将规范链接到代码，或者定义语义规则来描述代码应如何与规范对齐。建议在提交或合并代码前将其作为最终检查步骤使用。

核心特性

• 非侵入式：无需修改现有代码或规范文件 (Non-intrusive: no changes required to existing code or specification files)
• 自带模型：支持 OpenAI、Anthropic、Gemini、Cerebras 以及 Ollama（本地运行） (Bring Your Own Model: supports OpenAI, Anthropic, Gemini, Cerebras and Ollama (local))
• 支持远程规范文件：例如 https://www.rfc-editor.org/rfc/rfc7946.txt (Supports remote specification files (e.g., https://www.rfc-editor.org/rfc/rfc7946.txt))
• 易于设置：使用 semcheck -init 命令快速初始化 (Easy setup with semcheck -init)

安装指南

前置条件

• Go 1.24 或更高版本
• golangci-lint：（可选，用于开发）
• Just：（可选，用于开发）

安装步骤

通过以下命令安装最新版本的 Semcheck：

go install github.com/rejot-dev/semcheck@latest

配置

Semcheck 需要一个配置文件。您可以使用 -init 标志以交互方式生成一个：

semcheck -init

此命令将创建一个 semcheck.yaml 文件。请根据您的项目需求编辑此文件。

链接规范与实现

Semcheck 支持两种不同的模式来将规范文件链接到实现代码，这两种模式可以结合使用。

1. 内联规范引用

使用特殊的注释语法在代码中直接链接规范。

# semcheck:rfc(8259)
class JsonParser:
    def parse(self, data: bytes):
        # ... 实现代码

内联引用支持以下几种命令：

semcheck:file(./local/spec.md)  # 链接仓库内的本地文件，路径相对于 semcheck 工作目录
semcheck:url(https://example.com/docs/api)  # 链接到远程文档
semcheck:rfc(8259)  # 链接到 rfc-editor.org 上 RFC 文档的简写形式

使用片段/锚点

您可以使用 URL 片段来定位结构化文档（HTML 和 Markdown）中的特定部分：

# 链接到 HTML 文档的特定章节
# semcheck:url(https://www.rfc-editor.org/rfc/rfc7946.html#section-3.1.1)

# 使用标题文本链接到 Markdown 文档的特定章节
# semcheck:file(./docs/api-spec.md#authentication)

# 对 RFC 文档同样有效
# semcheck:rfc(8259#section1)

对于 HTML 文档，片段的工作方式与浏览器导航相同，它们会定位具有匹配 id 或 name 属性的元素。对于 Markdown 文档，您可以使用标题文本作为片段标识符（空格和特殊字符会被转换为锚点格式）。

2. 规则

在您的 Semcheck 配置中定义规则，将规范文件链接到实现文件。Semcheck 会为每条规则运行一次 LLM，在预提交模式下，则只针对包含已修改文件的规则运行。为了获得最佳效果，请尽量保持每条规则涉及的文件数量较少，LLM 在上下文聚焦时表现最佳。

规则配置示例：

rules:
  - name: "config-spec"
    enabled: true
    files:
      include:
        - "./internal/config/*.go"
      exclude:
        - "*_test.go"
    specs:
      - path: "config-spec.md"

  - name: "geojson"
    description: "Ensure GeoJSON implementation matches RFC 7946"
    enabled: true
    files:
      include:
        - "packages/geojson/src/*.ts"
      exclude:
        - "*.test.ts"
    specs:
      - path: "https://www.rfc-editor.org/rfc/rfc7946.txt"
    prompt: |
      Our GeoJSON implementation is incomplete; only check implemented features.

使用方法

基础用法

# 创建配置文件
semcheck -init

# 检查所有规范/实现规则
semcheck

# 传递需要检查的特定文件，
# semcheck 会根据规则判断需要进行哪些比较
semcheck spec.md

# 可以传递实现文件和规范文件
semcheck impl.go

# 在暂存文件上运行（预提交检查）
semcheck -pre-commit

# 使用自定义配置文件
semcheck -config my-config.yaml file1.go

# 也可以使用双破折号语法传递标志
semcheck --config my-config.yaml

# 显示帮助信息
semcheck -help

忽略文件

Semcheck 使用顶层的 .gitignore 文件来确定在处理过程中跳过哪些文件。如果您没有使用 Git，也可以创建一个遵循与 .gitignore 文件相同语义的 .semignore 文件。

GitHub Actions 集成

Semcheck 可以在 GitHub Actions 工作流中使用，以检查代码中的语义问题。

可用的配置选项：

• config-file：Semcheck 配置文件的路径
• fail-on-issues：如果发现问题，是否使 Action 失败
• semcheck-version：要使用的 Semcheck 版本
• go-version：要使用的 Go 版本

工作流配置示例：

on:
  pull_request:
    branches:
      - main

jobs:
  semcheck:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run semcheck
        uses: rejot-dev/semcheck@main
        with:
          config-file: semcheck.yaml
          fail-on-issues: false
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} # 或其他提供商的 API 密钥，可在 semcheck.yaml 中配置

模型评估

在 evals 目录下提供了一个（相对）基础的评估套件，用于衡量模型和提示词随时间的准确性。要了解哪些模型/提供商能获得最佳结果，请查看评估结果：

常见问题（FAQ）

Semcheck如何验证代码是否符合规范？

Semcheck通过内联注释或配置规则将规范链接到代码，利用大语言模型自动验证实现与规范的一致性，支持本地文件和远程URL规范。

Semcheck支持哪些大语言模型？

支持OpenAI、Anthropic、Gemini、Cerebras及Ollama（本地运行）等多种LLM提供商，用户可自带模型灵活选择。

如何在CI/CD流程中集成Semcheck？

可通过GitHub Actions集成，在提交或合并代码前作为最终检查步骤，支持预提交模式仅检查修改文件，提升开发效率。