Semcheck：用AI自动保持代码与文档同步的神器

为什么你的代码和文档总是不一致？

作为开发者，你是否经历过这些痛苦时刻？

1. 修改了函数逻辑却忘记更新文档
2. 团队新人按过时文档调用API导致故障
3. 代码评审时发现实现与设计文档存在分歧
4. 技术债务清单中总躺着“更新文档”这项任务

规范漂移（Spec Drift） 正是这些问题的根源。传统解决方案依赖人工检查，既耗时又容易遗漏。而今天介绍的Semcheck工具，通过AI技术实现了自动化规范检查，让代码与文档保持同步变得简单可靠。

---

什么是Semcheck？

Semcheck是一款基于Go语言开发的轻量级CLI工具，它利用大语言模型（LLM）自动检测代码实现与规范文档的一致性。它的核心价值在于：

✅ 实时同步检测 – 当规范或代码变更时自动触发检查
✅ 多模型支持 – 兼容OpenAI/Anthropic/本地LLM等多种AI引擎
✅ 无缝集成 – 完美适配Git预提交钩子和CI/CD流水线
✅ 精准定位 – 明确标识规范与实现不符的具体位置

就像《办公室》梗图表达的：“公司要你找出这两张图的区别——Semcheck会说：它们完全相同！”

---

工作原理揭秘

三层核心架构

graph TD
    A[配置文件] --> B(文件处理器)
    C[代码/文档] --> B
    B --> D[AI对比引擎]
    D --> E[检测报告]

1. 配置层（semcheck.yaml）
   定义规则关联实现文件与规范文档：

   rules:
     - name: "geoJSON-check"
       files:
         include: "src/geojson/*.ts"  # 实现文件
         exclude: "*_test.ts"
       specs:
         - path: "https://www.rfc-editor.org/rfc/rfc7946.txt"  # 在线规范
   

2. 匹配引擎
   自动建立三类文件的映射关系：

   • 规范文件（Spec）
   • 实现文件（Impl）
   • 忽略文件（.gitignore配置）

3. AI对比内核
   采用智能上下文分析：

   // 示例代码：规范检查核心逻辑
   func CompareSpec(specContent, implContent string) (bool, string) {
       prompt := fmt.Sprintf("对比规范：%s\n与实现：%s", specContent, implContent)
       return aiClient.Query(prompt)
   }
   

---

五分钟上手实践

安装步骤

# 安装Go 1.24+环境
brew install go

# 安装Semcheck
go install github.com/rejot-dev/semcheck@latest

初始化配置

semcheck -init  # 生成semcheck.yaml

配置文件示例

version: "1.0"
provider: openai
model: gpt-4.1
api_key: ${OPENAI_API_KEY}  # 从环境变量读取

rules:
  - name: config-validation
    files:
      include: "internal/config/*.go"
    specs:
      - path: "docs/config-spec.md"

运行检测

# 检查所有规则
semcheck

# 仅检查特定文件
semcheck src/utils.go

# 预提交检查（推荐！）
semcheck --pre-commit

---

实际应用场景

场景1：API接口变更

当修改Swagger文档时：

 paths:
   /user:
     get:
-      summary: Get all users
+      summary: Query active users

Semcheck自动关联到对应的控制器代码，确保实现同步更新。

场景2：RFC规范更新

检测代码是否符合最新RFC标准：

specs:
  - path: "https://www.rfc-editor.org/rfc/rfc9110.txt"  # HTTP/1.1规范

场景3：团队协作保障

新人提交PR时，CI流水线自动运行：

# GitHub Actions配置
jobs:
  semcheck:
    steps:
      - uses: rejot-dev/semcheck@main
        with:
          config-file: semcheck.yaml
        env:
          OPENAI_API_KEY: ${{ secrets.API_KEY }}

---

技术优势解析

与传统方法的对比

检测方式	准确性	时效性	维护成本
人工审查	中	低	高
单元测试	高	中	高
Semcheck	高	高	低

智能处理能力

1. 上下文提取 – 自动过滤测试文件(*_test.go)和注释
2. 差异定位 – 精确到函数级别的变更比对
3. 批量处理 – 并发检查多个规则，大幅提升效率

---

开发者实践建议

最佳配置方案

# 高效配置技巧
timeout: 30  # 超时设置(秒)
fail_on_issues: true  # 发现问题时终止流程

# 规则优化提示
prompt: |  
  仅检查已实现的功能项，忽略标记为TODO的部分

调试技巧

# 查看处理过程
SEMCHECK_DEBUG=1 semcheck

# 自检工具规范
semcheck specs/semcheck.md  # 用工具检查自身规范

性能优化

• 单个规则关联文件≤5个（减少AI上下文负担）
• 使用本地LLM(Ollama)规避网络延迟
• 启用--pre-commit仅检查暂存文件

---

常见问题解答

Q：会泄露公司代码吗？

不会。Semcheck支持本地模型(Ollama)，敏感代码无需外传。云端API调用也仅发送必要片段。

Q：如何处理大型代码库？

采用分规则策略：

rules:
  - name: auth-module   # 认证模块
    files: pkg/auth/*.go
    specs: docs/auth.md
    
  - name: payment-module # 支付模块
    files: pkg/payment/*.go
    specs: docs/payment.md

Q：AI判断出错了怎么办？

可通过提示词校准：

prompt: |
  注意：我们的实现使用蛇形命名法(snake_case)，
  RFC文档中的驼峰命名法(camelCase)不是错误

---

未来演进方向

根据开发路线图，即将推出：

journey
    title Semcheck演进路线
    section 2024 Q3
      本地LLM优化 --> 规则分组检查
    section 2024 Q4
      问题溯源功能 --> GitHub Action增强

---

现在就行动！

三步开启规范守护：

1. 安装工具：go install github.com/rejot-dev/semcheck@latest
2. 生成配置：semcheck -init
3. 添加预提交钩子：

   # .git/hooks/pre-commit
   #!/bin/sh
   semcheck --pre-commit || exit 1
   

技术债不会自动消失，但规范漂移可以自动拦截。让Semcheck成为你代码库的“规范守门人”。