1. 项目概述当AI写代码时我们到底在“审查”什么如果你和我一样在过去一年里深度使用过Cursor、Claude Code或者GitHub Copilot你肯定经历过这种时刻AI助手“唰唰唰”地生成了一大段看起来逻辑清晰、注释完备的代码你满心欢喜地让它继续或者让另一个AI模型比如切到GPT-4再问一次“这段代码有问题吗”来“审查”。结果呢很多时候第二个AI会煞有介事地指出一些格式问题或者提出一些不痛不痒的优化建议但对于代码里那个隐蔽的逻辑缺陷或与项目架构根本冲突的设计它们都默契地保持了沉默。这感觉就像让同一个学生做完试卷后再让他自己批改自己的卷子——他很可能发现不了自己知识体系里的盲区。这正是kroq86/rule-based-verifier这个项目试图解决的核心痛点。它不是一个功能更强大的AI也不是一个更复杂的提示词工程框架。相反它提出了一种堪称“叛逆”的工作流哲学将质量审查的权威从概率性的AI“意见”交还给确定性的、可执行的“规格说明”。简单说就是用测试用例、代码规范检查Lint、甚至语义搜索这些能给出“是/否”答案的工具作为代码是否合格的最终守门员。AI的角色被严格限定在这些自动化检查无法覆盖的“残余”领域比如架构权衡、模块耦合度评估等需要人类经验介入的高层决策。这个项目本身是一个实现了Model Context Protocol (MCP)的服务器。你可以把它理解为一个“工具包”通过MCP协议挂载到你的AI编码助手比如Cursor上。当AI生成或修改代码后这个服务器不会用另一个LLM去“思考”代码好不好而是直接启动你项目里预设的测试套件、运行Lint检查并把确定性的结果通过/失败及具体信息反馈给AI。它强制建立了一条“代码 vs. 意图”的验证回路而不是“代码 vs. 另一个模型的看法”。2. 核心理念与设计哲学拆解2.1 问题根源相关而非独立的失败传统软件工程中我们引入代码审查、静态分析、自动化测试等多重关卡是基于一个基本假设这些关卡失效的原因是独立的。一个开发者可能漏看一个边界条件但静态分析工具可能恰好能捕获它测试用例可能覆盖不全但代码审查者凭经验能发现端倪。这种独立性的叠加能显著降低缺陷逃逸的概率。然而当审查者和创作者都是基于相同训练数据分布的大型语言模型时这个假设就崩塌了。LLM们倾向于犯相关性的错误。它们可能共享对某个API用法的误解或者都倾向于使用某种看似优雅但存在潜在风险的模式。让AI生成代码再让另一个甚至同一个AI去审查本质上是在让系统用同一套有偏见的认知框架去检查它自己的输出。这就像用同一把刻度不准的尺子反复测量一个物体然后取平均值——你无法得到真实尺寸只是巩固了误差。rule-based-verifier的解决方案直指要害绕过这种“自我指涉”的循环。它不关心AI“认为”代码是否正确它只关心代码是否满足一系列预先定义、明确无误的客观标准。这些标准就是你的测试、你的Lint规则、你的API契约。它们是“意图”的机器可读表述。2.2 “策略优先小步快跑验证驱动”的工作流项目文档中概括的工作流——Policy First, Small Steps, Verification——是精髓所在。策略优先在写第一行代码之前先定义“好代码”的标准。这包括项目的代码规范.eslintrc.js,pyproject.toml等、测试框架的选择与约定、以及关键的架构约束。这些策略被编码进配置文件和项目规则中成为不可动摇的“法律”。小步快跑鼓励AI进行小范围的、目标明确的修改。一次只修复一个bug只添加一个功能。这降低了单次变更的复杂度使得后续的验证更加聚焦和高效。验证驱动每一个小步之后立即触发验证。验证不是可选的“之后再做”而是工作流的核心环节。通过MCP这个验证过程可以无缝、自动地集成到AI助手的交互中。这种工作流将人类开发者从重复性的、低层次的代码审查中解放出来转而扮演更重要的角色架构师和熔断器。人类负责制定最初的“策略”Policy并在AI遇到验证无法解决的模糊地带比如两个同样满足测试但设计哲学不同的方案时做出最终裁决。项目中的AGENTS.md文件详细规定了这种人机“结对编程”的交互模型包括何时应该由人类介入的“熔断”条件。注意这里有一个关键的心态转变。我们不是在“训练”或“指导”AI写出完美代码而是在设计一个系统这个系统能利用AI的生成能力同时用自动化的验证机制来约束其输出范围使其始终被锚定在可接受的轨道内。你是系统的设计师而不是AI的校对员。3. 项目结构深度解析与部署实践3.1 核心目录与文件一览让我们打开项目仓库看看各个部分是如何具体支撑起上述理念的。mcp/这是项目的核心一个用Python实现的MCP服务器。它的名字就叫rule-based-verifier。其功能被严格限定在“有边界的验证”内健康检查提供服务器状态查询。文件读取与搜索允许AI在设定的工作空间根目录由RULE_BASED_WORKSPACE_ROOT环境变量定义下读取文件或进行内容搜索。这为AI提供了上下文但注意搜索范围被显式绑定防止它漫无目的地遍历系统文件。运行测试与Lint这是杀手级功能。服务器可以执行项目内的测试命令如pytest,npm test和代码规范检查命令如ruff check,eslint。执行结果标准输出、错误码会结构化地返回给AI。.cursor/rules/这里存放的是Cursor IDE的“项目规则”。这些规则是AGENTS.md中所述高层策略在Cursor这个具体环境下的体现。它们通常是alwaysApply类型的规则例如“所有Python函数必须包含类型注解”、“禁止使用某个已废弃的库”等。AI在编辑本项目代码时会自动遵守这些规则。.cursor/mcp.json这是将MCP服务器配置到Cursor的关键文件。它告诉Cursor“这里有一个本地可用的MCP服务器它的启动脚本和参数是什么。” 项目提供了一个启动脚本mcp/scripts/run-docker-mcp.sh这个脚本巧妙地解决了Docker挂载路径的常见问题。Dockerfile项目提供了容器化部署方案并已构建多架构镜像支持amd64和arm64即常见的Intel/AMD芯片和苹果M系列芯片发布到GitHub Container Registry (GHCR)。这保证了运行环境的一致性。emacs/为使用Doom Emacs编辑器的用户提供了配置片段体现了项目对多编辑器生态的考虑。3.2 两种运行方式详解3.2.1 使用Docker运行推荐用于生产/集成这是最简单、最干净的方式避免了本地Python环境依赖的困扰。# 1. 拉取最新的Docker镜像 docker pull ghcr.io/kroq86/rule-based-verifier:latest # 2. 运行容器将你需要验证的项目目录挂载到容器的 /workspace # 假设你的项目在 /home/user/my_project cd /home/user/my_project docker run -i --rm \ -v $PWD:/workspace \ -e RULE_BASED_WORKSPACE_ROOT/workspace \ ghcr.io/kroq86/rule-based-verifier:latest关键参数解析-v $PWD:/workspace这是Docker的卷挂载。它将你当前的项目目录映射到容器内的/workspace路径。非常重要后续所有文件读取、测试运行都是针对容器内的这个/workspace目录进行的。-e RULE_BASED_WORKSPACE_ROOT/workspace这个环境变量告诉MCP服务器它的工作空间根目录在哪里。这里设置为容器内的/workspace即我们刚刚挂载进来的项目目录。-i和--rm-i保持标准输入打开这对于MCP的stdio通信是必须的--rm让容器在停止后自动删除避免积累无用容器。运行后这个容器会启动MCP服务器并通过标准输入输出stdio等待客户端如Cursor连接。它自己不会主动做任何事情直到收到来自客户端的工具调用请求。3.2.2 本地开发与调试如果你需要修改或扩展这个验证服务器就需要在本地运行。# 1. 进入mcp目录 cd mcp # 2. 使用uv一个快速的Python包管理器和解析器同步依赖 # 如果未安装uv请先通过 pip install uv 或官方脚本安装 uv sync # 3. 激活虚拟环境并运行服务器 # 注意项目明确建议使用直接调用python的方式而非 uv run以确保stdio传输稳定。 .venv/bin/python -u run_server.py # 4. 运行项目自身的测试这本身就是一个“验证”行为 .venv/bin/python -m pytest # 5. 尝试运行Lint检查 # 服务器内置了自动探测逻辑先检查 RULE_BASED_LINT_CMD 环境变量 # 如果没有则尝试寻找并运行 ruff check (Python) 或 npm run lint (Node.js)。 # 你可以手动设置环境变量来指定命令。 RULE_BASED_LINT_CMDblack --check --diff . .venv/bin/python -u run_server.py实操心得路径与权限的坑在本地开发时最大的挑战是模拟Docker内的路径环境。run_server.py中执行命令如pytest时它是在当前工作目录下执行的。如果你在mcp/目录下运行服务器但你的测试文件在项目根目录那么pytest很可能找不到测试。因此在本地调试时你需要确保正确设置了RULE_BASED_WORKSPACE_ROOT环境变量并且在该目录下启动你的测试/Lint命令。这比Docker方案要更小心地处理路径问题。3.3 与Cursor IDE的集成实战这是让整个工作流“活”起来的关键一步。目标是将我们运行的MCP服务器作为工具提供给Cursor内的AI通常是Claude 3.5 Sonnet。确保MCP服务器在运行首先通过上述Docker或本地方式启动rule-based-verifier服务器。记住它将在stdio上等待连接。配置CursorCursor需要通过.cursor/mcp.json文件来发现这个服务器。这个文件的内容通常如下{ mcpServers: { rule-based-verifier: { command: bash, args: [ ${workspaceFolder}/mcp/scripts/run-docker-mcp.sh ], env: { RULE_BASED_WORKSPACE_ROOT: ${workspaceFolder} } } } }配置解析command: 指定为bash因为我们用一个shell脚本来启动Docker容器。args: 参数是脚本的路径。${workspaceFolder}是Cursor提供的变量指向当前打开的项目根目录。这确保了无论项目在什么位置Cursor都能找到脚本。env: 设置环境变量。这里将工作空间根目录设置为项目根目录。理解启动脚本的魔法为什么需要run-docker-mcp.sh而不是直接在args里写docker run ...原因在CONTRIBUTING.md中有提及Docker的-v(volume) 挂载在传递绝对路径时可能很脆弱尤其是当路径包含符号链接或特殊字符时。这个启动脚本的作用之一就是解析并规范化当前工作目录的绝对路径然后将其安全地传递给docker run -v命令。它充当了一个可靠的适配器。在Cursor中使用配置完成后重启Cursor。当你在Chat界面与AI助手交流时理论上AI就可以调用rule-based-verifier提供的工具了。例如你可以说“请帮我写一个函数来计算斐波那契数列然后运行一下项目的测试看看有没有问题。” AI在生成代码后可以主动调用“运行测试”工具并将结果反馈给你。重要提示根据我的实测经验Cursor对MCP工具调用的支持有时不够稳定或明显。AI可能不会主动调用或者你需要非常明确的指令。更可靠的方式是将验证环节设计到你的工作流指令中。例如在给AI提需求时最后加上“请完成上述修改并使用可用的MCP工具运行单元测试和Lint检查确保所有检查通过后再告诉我。” 这相当于把验证环节变成了需求的一部分。4. 验证工具链的定制与扩展4.1 理解内置的验证行为rule-based-verifier服务器的核心是几个工具Toolsread_file: 读取文件。search_files: 在工作空间内搜索内容。run_tests: 运行测试。run_lint: 运行代码规范检查。其中run_tests和run_lint的行为是可以定制和扩展的。run_tests默认情况下它可能会尝试寻找并运行常见的测试命令如pytest、npm test、cargo test等。其具体逻辑在服务器的源代码中定义。为了获得确定性的行为最佳实践是在你的项目根目录放置一个明确的测试脚本如scripts/test.sh然后在服务器配置或环境变量中指向它。run_lint它的逻辑是首先检查RULE_BASED_LINT_CMD环境变量。如果设置了就执行这个命令。如果未设置则尝试自动探测先找Python的ruff如果存在则执行ruff check .否则找Node.js的package.json中的lint脚本。如果都未找到则返回失败提示用户配置。4.2 如何定制你的验证规则项目的威力在于“规则”Rule部分。这分为两个层面层面一Cursor项目规则 (.cursor/rules/)这些是写在.cursor/rules/目录下的.md文件。它们直接影响Cursor内置AI的行为模式。例如你可以创建一个python-style.md--- description: “Python代码风格与质量规则” alwaysApply: true --- - 所有函数和公共方法必须包含Google风格的类型注解Type Hints。 - 禁止使用 print 语句进行调试应使用 logging 模块。 - 导入必须分组标准库、第三方库、本地库每组之间用空行分隔。 - 错误处理应使用明确的异常类型避免裸露的 except:。当AI在本项目中编写代码时它会尽力遵守这些规则从源头上减少风格问题。层面二MCP验证工具规则这是通过配置MCP服务器或你的项目构建脚本来实现的。例如你希望run_tests工具不仅运行单元测试还运行集成测试和生成覆盖率报告。创建统一脚本在项目根目录创建scripts/verify.sh。#!/bin/bash set -e # 遇到任何错误即停止 echo 运行单元测试 pytest tests/unit --covmyapp --cov-reportterm-missing echo 运行集成测试 pytest tests/integration echo 运行代码风格检查 ruff check . black --check --diff . mypy myapp echo 安全检查 bandit -r myapp配置环境变量在启动MCP服务器时设置RULE_BASED_TEST_CMD如果服务器支持或覆盖run_tests工具的逻辑让其执行./scripts/verify.sh。对于run_lint你可以设置RULE_BASED_LINT_CMD为./scripts/lint.sh其中包含所有你想要的Lint检查。通过这种方式你定义了一个黄金标准的验证流水线。AI每次调用验证工具实际上是在对这个黄金标准负责。这比依赖AI模糊的“代码质量”概念要可靠得多。4.3 扩展添加新的验证工具如果你需要超出“测试”和“Lint”的验证比如检查API设计是否符合OpenAPI规范、检查依赖许可证、或者运行性能基准测试你可以扩展这个MCP服务器。修改run_server.py在工具定义部分添加一个新的Tool。例如添加一个check_openapi工具。实现工具逻辑在对应的处理函数中使用subprocess运行一个像spectral lint openapi.yaml这样的命令。重建Docker镜像将你的新依赖如npm install -g stoplight/spectral添加到Dockerfile中然后重新构建和发布镜像。这样你的AI助手就获得了检查API规范的能力。整个系统的边界和能力完全由你定义的可执行验证集决定。5. 人机协作工作流的设计与实战5.1 解读AGENTS.md结对编程模型与熔断机制AGENTS.md文件是这个项目的“宪法”它规定了人类和AI如何协作。其核心是一个增强的结对编程模型。AI作为驾驶员AI负责执行具体的编码任务如实现函数、修复错误、编写测试。它拥有调用所有MCP工具读文件、运行验证的权限。人类作为领航员人类负责高层次决策。包括制定计划在任务开始前与AI共同拆解需求定义验收条件即哪些验证必须通过。审查验证结果当AI运行测试或Lint失败时人类需要解读失败信息判断是AI的理解有误还是测试用例本身需要更新。执行熔断当AI陷入循环多次尝试无法通过验证、或提出的解决方案触及架构边界如引入一个新的重型依赖、或进入验证工具无法覆盖的模糊领域如两个设计模式的取舍时人类必须介入做出明确指令或直接接手。“熔断器”模式是这个工作流安全的关键。它防止AI在错误的方向上浪费大量时间。例如你可以设定规则如果AI连续3次提交的代码都无法通过单元测试工作流自动暂停并高亮提示人类领航员介入检查。AGENTS.md中可能包含了这类状态机或决策树的描述。5.2 实战场景模拟让我们模拟一个完整的场景“为现有用户登录API添加一个速率限制功能”。策略与计划阶段人类主导人类我们需要给/api/login端点添加速率限制每个IP每分钟最多10次尝试。请使用我们已有的redis客户端和rate-limiter-flexible库。请先分析现有代码结构然后给出实现计划。AI调用read_file查看相关路由文件和库的引入方式我看到了登录路由在auth/routes.py项目已使用redis和rate-limiter-flexible。计划是a) 修改路由文件在登录处理函数前添加限流中间件b) 编写一个单元测试模拟高频请求并断言第11次请求返回429状态码c) 更新API文档。小步实施与验证阶段AI驱动人类监督AI我将开始第一步添加限流中间件。这是修改后的auth/routes.py代码片段。展示代码人类好的请先运行项目的Lint检查确保代码风格符合要求。AI调用run_lint工具Lint检查通过无错误和警告。AI现在我将编写单元测试。创建了test_rate_limit.py。展示代码人类请运行相关的测试特别是你刚修改的认证模块的测试。AI调用run_tests工具运行pytest auth/tests/ -v。结果所有现有测试通过新的速率限制测试也通过。AI第二步完成。现在进行第三步更新API文档中的/api/login部分。展示修改模糊决策与熔断阶段人类介入AI在编写测试时我发现模拟Redis行为比较复杂。我提出了两种方案A) 使用unittest.mock模拟整个Redis客户端B) 使用一个内存存储的测试专用限流器。方案A更贴近真实环境但测试较慢方案B更快但与生产环境略有差异。请领航员决策。人类这是一个验证工具无法判断的架构/测试哲学问题选择方案A。我们追求测试的真实性速度可以接受。请继续。最终验收人类请运行整个测试套件并确保Lint检查通过。AI调用run_tests和run_lint全部通过。人类工作完成。代码已就绪可提交。在这个流程中AI承担了所有具体的、可验证的执行工作而人类专注于计划、裁决模糊问题和最终验收。验证工具测试、Lint充当了客观的、无需争辩的质量关卡。6. 常见问题、排查与进阶思考6.1 问题排查速查表问题现象可能原因解决方案Cursor无法连接MCP服务器1. MCP服务器未运行。2..cursor/mcp.json路径或配置错误。3. 启动脚本权限不足或执行失败。1. 在终端运行docker ps检查容器或确认本地Python进程在运行。2. 检查mcp.json中command和args的路径是否正确。使用绝对路径或${workspaceFolder}变量。3. 给启动脚本加执行权限chmod x mcp/scripts/run-docker-mcp.sh并尝试在终端直接运行该脚本看是否有报错。AI无法调用“运行测试”工具1. 工具未在MCP服务器中正确暴露或命名。2. Cursor的AI模型未正确识别可用工具。3. 项目目录下没有测试命令或测试框架。1. 检查MCP服务器的日志确认工具列表已发送给客户端。2. 在Cursor Chat中尝试更明确的指令如“请使用名为‘run_tests’的工具”。有时需要重启Cursor。3. 确保项目根目录有可运行的测试命令如pytest。可以在MCP服务器运行目录下手动执行测试命令进行验证。测试/Lint在容器内运行失败1. Docker挂载路径错误容器内找不到项目文件。2. 容器内缺少项目依赖如Node_modules, Python包。3. 测试命令依赖于特定环境变量或服务如数据库。1. 检查docker run -v的参数确保宿主机的项目目录正确挂载到容器的/workspace。2. 项目依赖需要在宿主机安装并挂载到容器或者使用多阶段构建将依赖打入镜像。这是一个高级话题CONTRIBUTING.md有提及。3. 在Docker运行命令中通过-e传递所需环境变量或使用docker-compose链接服务。验证速度很慢每次AI调用工具都启动一个新的测试/Lint进程如果项目很大会很耗时。考虑优化1. 让验证工具运行增量的测试如pytest -k “特定测试名”。2. 在MCP服务器层面实现简单的缓存机制例如如果文件未更改则返回上一次的Lint结果。但这需要修改服务器代码。6.2 进阶思考语义追踪与未来项目提到了一个有趣的预览功能Solution Semantic Trace。打开solution_semantic_trace.html文件你会看到一个可视化的界面。我理解这是将一次完整的“AI编码会话”进行结构化记录和展示的工具。它记录了什么可能包括人类的初始指令、AI的分解计划、每一步生成的代码、每次调用验证工具读文件、运行测试等的输入输出、以及最终的结果。价值何在这提供了可审计性和可学习性。对于团队来说可以回顾AI是如何一步步解决问题的哪里走了弯路哪里的人类干预是关键。这比看最终的Git提交历史要丰富得多。它也是调试AI工作流、优化提示词和验证规则的宝贵数据源。这个特性指向了AI辅助编程的未来不仅仅是生成代码而是生成一个完整的、可复现的解决方案推导过程。这极大地增强了透明度和信任度。6.3 局限性与我个人的体会使用rule-based-verifier一段时间后我总结了几个关键体会和它的局限它不是银弹而是纪律的执行者它不能保证AI写出天才般的代码但能强制保证代码满足你定义的基本标准测试通过、风格一致。这已经解决了80%的日常协作问题。对项目成熟度有要求如果你的项目本身缺乏良好的测试覆盖和清晰的代码规范那么这个工具的作用会大打折扣。你需要先投入时间建立这些“客观标准”。人类角色的升级你的工作从“写代码/改代码”变成了“定义规则、设计工作流、做出关键决策”。这要求你有更高的抽象思维和系统设计能力。如果你享受这种角色它会非常棒如果你只想埋头写代码可能会觉得它增加了流程复杂度。集成体验有待提升目前MCP在各类IDE/编辑器中的集成度参差不齐工具调用的触发不够智能和自然。这需要整个生态的进一步发展。最后再分享一个小技巧你可以从一个小点开始实践。不必一开始就搭建完整的MCP服务器。可以先在你的团队中严格执行“任何AI生成的代码块在放入代码库前必须通过现有测试套件和Lint检查”这条规则手动执行验证。当你体会到这种纪律带来的好处后再引入rule-based-verifier这样的自动化工具就会水到渠成。它的本质是将一种优秀的工程实践通过协议和工具固化到了人机协作的流程之中。