1. 项目概述

如果你和我一样,在日常开发中深度依赖AI助手(比如Cursor、Windsurf或者VS Code Copilot)进行结对编程,那你一定遇到过这个让人头疼的循环:每次开启一个新的对话,或者切换到不同的代码文件,你都得像个复读机一样,把项目的编码规范、命名约定、测试覆盖率要求、安全扫描规则再跟AI“唠叨”一遍。更别提团队协作时,每个人用的AI工具、提问方式、甚至对“代码质量”的理解都不同,最后产出的代码风格五花八门,Review起来简直是一场灾难。

这就是我当初动手开发 RuleFlow (全称 MCP Rules & Context Assistant)最直接的动力。它不是一个要取代AI助手的工具,而是一个让AI助手变得更“懂你”、更“懂你项目”的智能上下文管家。简单来说,RuleFlow的核心工作就是两件事: 规则治理 上下文记忆 。它能把你的项目规范(写在README、CONTRIBUTING.md里的那些条条框框)自动“喂”给AI,并且在多轮对话中持续记住这些规则和当前的开发上下文,确保AI生成的代码从一开始就符合标准,而不是等你Review时再打回去重改。

想象一下,你只需要在项目根目录运行一条 mcp-rules-assistant ingest-rules 命令,RuleFlow就会自动解析你的文档,提取出“函数注释必须用Google风格”、“单元测试覆盖率不得低于95%”、“禁止使用某些不安全函数”等要求,并将它们转化为AI能理解和执行的“门禁规则”。之后,无论你是在VS Code里用Copilot Chat,还是在Cursor里和Claude对话,这些规则都会作为背景知识被自动注入,AI助手给出的建议会自然而然地避开那些“坑”。这对于维护大型项目、确保代码库长期健康、以及在新成员快速上手时保持一致性,价值巨大。

2. 核心设计思路与架构解析

2.1 为什么选择 MCP (Model Context Protocol)?

RuleFlow的基石是Anthropic开源的 Model Context Protocol 。在决定技术栈时,我评估过几种方案:自己写一套IDE插件去劫持AI助手的输入输出、或者做一个中间代理服务器。前者兼容性差,每个IDE都要适配;后者则引入了网络延迟和复杂度。MCP完美地解决了这个问题。

MCP定义了一套标准协议,允许像RuleFlow这样的“服务器”(Server)向“客户端”(Client,如Cursor、Windsurf)动态提供工具(Tools)和上下文资源(Resources)。这意味着,RuleFlow无需关心用户具体用的是哪款IDE,只要IDE支持MCP(现在主流AI编程助手基本都支持了),RuleFlow就能以标准方式为其注入规则和上下文。这种设计让RuleFlow天生就具备了 跨平台、跨IDE 的能力,这也是项目能快速获得开发者认可的关键。

2.2 整体架构拆解

RuleFlow的架构清晰分为三层,追求高内聚、低耦合:

用户界面层 (IDE/CLI)
    |
    | (通过MCP协议通信)
    |
RuleFlow核心服务层
    ├── MCP服务器 (mcp_rules_assistant/server.py)
    ├── 规则引擎 (mcp_rules_assistant/engine/)
    │   ├── 摄取器 (Ingestor): 解析Markdown/YAML,提取结构化规则
    │   ├── 编译器 (Compiler): 将规则转化为可执行的检查逻辑或提示词模板
    │   └── 存储器 (Storage): 本地SQLite存储,管理规则集和会话历史
    ├── 上下文管理器 (mcp_rules_assistant/context/)
    │   ├── 会话记忆: 维护20轮滚动的对话历史
    │   ├── 项目状态感知: 跟踪当前文件、Git分支、修改范围
    │   └── 资源提供器: 将规则、诊断报告作为MCP Resource暴露
    └── 质量门禁 (mcp_rules_assistant/gates/)
        ├── 覆盖率门禁 (CoverageGate)
        ├── 代码风格门禁 (LintGate)
        ├── 安全扫描门禁 (SecurityGate)
        └── 门禁策略管理器 (PolicyManager)
    |
    |
数据与配置层
    ├── 本地SQLite数据库 (.ruleflow/cache.db)
    ├── 项目规则配置文件 (.ruleflow/config.yaml)
    └── 预定义规则模板 (rulesets/)

工作流程 可以这样理解:

  1. 初始化 :开发者运行 mcp-rules-assistant init ,工具在项目根目录创建 .ruleflow 文件夹和配置文件。
  2. 规则摄取 :运行 ingest-rules 命令,规则引擎开始扫描指定的文档。它会使用正则表达式和轻量级NLP(如基于spaCy或自定义模式)识别出“必须”、“禁止”、“应当”等约束性语句,并将其分类为 风格规则 安全规则 测试规则 等。
  3. 上下文绑定 :当开发者在IDE中打开项目,RuleFlow的MCP服务器启动。IDE(MCP客户端)会通过协议查询可用的 Resources 。RuleFlow将当前项目的规则集、最近的质量检查报告等作为资源提供出去。
  4. AI辅助 :当用户在IDE中向AI提问时,IDE会自动将这些资源作为上下文附加到用户的问题前。于是,AI在回答“如何实现这个函数”时,已经提前知道了“本项目要求函数有类型注解和文档字符串”。
  5. 质量守门 :在提交代码前,开发者或CI流水线可以运行 mcp-rules-assistant diagnose generate-ci 。门禁系统会调用对应的检查工具(如pytest, ruff, bandit),根据摄取到的规则阈值(如覆盖率98%)进行校验,不通过则阻止提交。

2.3 关键技术选型背后的思考

  • Python 3.10+ :选择Python是因为其在AI工具链生态中的绝对主导地位,丰富的库(如 pydantic 用于数据验证, click 构建CLI)能极大提升开发效率。要求3.10+是为了使用 match 语句、更精确的类型提示等现代特性,保证代码的清晰和健壮。
  • SQLite本地存储 :所有规则、会话历史都存储在项目下的 .ruleflow/cache.db 中。这是 隐私优先 设计的关键。你的项目规范和数据永远不会离开本地机器,避免了云服务的隐私风险和网络依赖。SQLite轻量、无需单独部署,非常适合这种桌面工具场景。
  • 20轮滚动记忆 :这是一个经过实践平衡的数字。太短的记忆(如5轮)无法维持复杂的讨论上下文;太长的记忆(如100轮)会消耗大量AI模型的上下文窗口(Token),挤占当前问题的空间,且可能引入过时信息。20轮能在记住近期关键决策和保持上下文“新鲜度”之间取得良好平衡。

实操心得:规则提取的准确性 最初的规则提取器只是简单做关键词匹配,结果把“这个函数 禁止 在线上环境使用”和“我们 禁止 提交未经测试的代码”都归类为同一类安全规则,闹了笑话。后来改进为基于依存句法分析的简单模式识别,先判断句子主干(主语、谓语、宾语),再结合领域关键词词典(如“覆盖率”、“注释”、“漏洞”),准确率大幅提升。如果你的项目文档结构清晰,使用 ## 代码规范 ### 安全要求 这样的标题,提取效果会更好。

3. 从零开始:安装与核心配置实战

3.1 跨平台一键安装详解

项目提供了 install.sh (Unix系)和 install.bat (Windows)脚本。我们深入看看这些脚本到底做了什么,以便你在遇到问题时能自己排查。

Linux/macOS ( install.sh ) 脚本拆解:

#!/bin/bash
set -e # 遇到任何错误立即停止,避免半安装状态

echo "正在安装 RuleFlow..."

# 1. 检查前置依赖
if ! command -v git &> /dev/null; then
    echo "错误: 未找到 git。请先安装 git。"
    exit 1
fi

if ! command -v python3 &> /dev/null; then
    echo "错误: 未找到 python3。请安装 Python 3.10 或更高版本。"
    exit 1
fi

# 2. 克隆仓库(如果当前目录不是仓库)
if [ ! -f "pyproject.toml" ]; then
    REPO_URL="https://github.com/efem1978/ruleflow.git"
    echo "正在克隆仓库..."
    git clone $REPO_URL
    cd ruleflow
fi

# 3. 创建并激活虚拟环境
echo "正在创建Python虚拟环境..."
python3 -m venv .venv
source .venv/bin/activate # 关键步骤:激活环境,后续pip安装会在此环境中

# 4. 升级pip并安装项目(可编辑模式)
echo "正在安装依赖..."
pip install --upgrade pip
pip install -e . # “-e”代表可编辑模式,方便开发者直接修改代码生效

# 5. 安装IDE钩子(核心步骤)
echo "正在配置MCP服务器到IDE..."
if command -v cursor &> /dev/null || [[ "$OSTYPE" == "darwin"* ]]; then
    # 检测到Cursor或macOS(可能安装有Cursor)
    mcp-rules-assistant install-hooks --ide cursor
elif [ -n "$VSCODE_PID" ] || command -v code &> /dev/null; then
    # 检测到VS Code
    mcp-rules-assistant install-hooks --ide vscode
else
    echo "未检测到支持的IDE。请手动配置。"
    echo "可运行 'mcp-rules-assistant install-hooks --ide <ide_name>' 手动安装。"
fi

echo "安装完成!请重启你的IDE。"

Windows ( install.bat ) 注意事项: Windows下的脚本逻辑类似,但有几个关键区别:

  1. 激活虚拟环境的命令是 .venv\Scripts\activate.bat (CMD)或 .venv\Scripts\Activate.ps1 (PowerShell)。
  2. 路径分隔符是反斜杠 \
  3. 建议在 Git Bash Windows Terminal 中执行,以获得更好的脚本兼容性。如果只有CMD,可能需要手动调整路径。

避坑指南:虚拟环境激活失败 这是最常见的问题。在Windows PowerShell中,执行策略可能阻止脚本运行。解决方法是以管理员身份打开PowerShell,执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser (选择 Y )。完成后,务必 重新打开一个终端窗口 ,再进入项目目录手动激活环境: .venv\Scripts\Activate.ps1 。看到命令行前缀变成 (.venv) PS> 才算成功。

3.2 项目初始化与规则摄取实战

安装完成后,进入你的项目目录(比如 ~/projects/my-awesome-api ),开始配置RuleFlow。

# 1. 初始化项目配置
mcp-rules-assistant init

这条命令会做几件事:

  • 在项目根目录创建隐藏文件夹 .ruleflow/
  • 生成默认配置文件 .ruleflow/config.yaml
  • 初始化一个本地的SQLite数据库 .ruleflow/cache.db

接下来,查看并编辑配置文件,让它符合你的项目要求:

# .ruleflow/config.yaml
project:
  name: "my-awesome-api"
  language: "python"
  version: "1.0.0"

rules:
  # 规则摄取源,支持通配符
  sources:
    - "README.md"
    - "docs/**/*.md"
    - "CONTRIBUTING.md"
    - ".github/CODE_OF_CONDUCT.md"
  # 忽略的文件或目录
  exclude:
    - "node_modules"
    - "**/*.min.js"

quality_gates:
  test_coverage:
    core_modules: 0.98  # 核心模块覆盖率要求98%
    other_modules: 0.95 # 其他模块覆盖率要求95%
  linting:
    enabled: true
    fail_on_warning: false # 警告是否阻塞提交?按需开启
  security_scan:
    enabled: true
    level: "medium" # 扫描强度:low, medium, high

context:
  memory_turns: 20
  include_git_context: true # 是否包含git分支、最近提交等信息

配置好后,开始最重要的步骤—— 规则摄取

# 2. 从文档中提取规则
mcp-rules-assistant ingest-rules

这个过程发生了什么?

  1. 引擎会读取 config.yaml sources 列表的所有文件。
  2. 对每个文件进行解析。对于Markdown,它会识别各级标题( # , ## )作为规则分类,提取列表项( - * 1. )和代码块旁的描述文本作为规则内容。
  3. 使用规则提取器分析文本。例如,当它读到“ 所有公开的函数和方法必须包含类型注解和Google风格的Docstring。 ”时,它会:
    • 分类: code_style -> documentation
    • 提取关键元素: scope: public_functions_and_methods , requirement: must_have , content: type_annotations_and_google_docstring
    • 生成一条结构化规则,并存入数据库。
  4. 最终,你会在终端看到类似摘要:“成功从5个文件摄取42条规则(风格: 18, 安全: 10, 测试: 14)”。

注意事项:如何编写易于摄取的文档? RuleFlow的提取器不是万能AI,它依赖于一定的文档结构。为了让提取更准确,建议你的项目文档:

  1. 使用清晰的标题 :如 ## 代码风格规范 ### 测试要求 ## 安全守则
  2. 约束条件使用强调语气 :多用“必须”、“禁止”、“应当”、“建议”,避免模糊表述。
  3. 具体化规则 :“错误处理必须记录日志”比“要做好错误处理”更好。
  4. 完成后,运行 mcp-rules-assistant list-rules 可以查看所有已摄取的规则,检查是否有误判或遗漏。

3.3 与你的IDE深度集成

RuleFlow的核心价值在于无缝的IDE体验。安装钩子后,你需要重启IDE。以VS Code/Cursor为例:

  1. 确保RuleFlow的MCP服务器正在运行(安装脚本通常已将其设置为后台服务或IDE插件)。
  2. 打开VS Code/Cursor的设置(JSON模式),你应该能看到自动添加的MCP服务器配置:
    {
      "mcpServers": {
        "ruleflow": {
          "command": "/path/to/your/project/.venv/bin/python",
          "args": [
            "-m",
            "mcp_rules_assistant.server"
          ],
          "env": {
            "RULEFLOW_PROJECT_PATH": "/path/to/your/project"
          }
        }
      }
    }
    
  3. 打开一个项目内的Python文件,尝试在AI聊天框中提问:“帮我写一个读取配置文件的函数。”
  4. 观察变化 :在AI回复之前,如果你查看开发者工具的网络请求(或某些IDE的调试信息),你会发现你的问题前面被自动附加了一段来自RuleFlow的上下文,内容可能就是“项目规范要求:函数需有类型注解和文档字符串;使用 pathlib 处理路径;...”。因此,AI生成的代码大概率会直接符合这些规范。

验证集成是否成功 : 在IDE终端中,你可以运行:

mcp-rules-assistant status

如果显示“MCP Server: Running”和“Connected IDEs: [‘cursor’]”,则表示集成成功。

4. 核心功能深度使用与定制

4.1 智能规则引擎:不止于文本匹配

RuleFlow的规则引擎是其大脑。它支持多种规则类型,并允许高级定制。

1. 基础规则类型:

  • 风格规则 (Style Rules) :源自代码风格指南。例如,“导入语句应按标准库、第三方库、本地库的顺序分组”。
  • 质量规则 (Quality Rules) :与代码健壮性相关。例如,“循环复杂度不得超过10”。
  • 安全规则 (Security Rules) :源自安全手册。例如,“禁止使用 eval() 函数”。
  • 测试规则 (Test Rules) :关于测试的约定。例如,“每个公共API必须包含单元测试”。

2. 自定义规则模板: 对于无法从文档中自动提取的复杂规则,你可以在 .ruleflow/ 目录下创建 custom_rules.yaml

- name: "database_connection_pool"
  type: "quality"
  description: "数据库连接必须使用连接池,且最大连接数不超过20"
  condition: "code" # 表示这条规则需要分析代码本身
  pattern: |
    # 这是一个伪代码模式,实际使用AST(抽象语法树)进行匹配
    CREATE_CONNECTION_PATTERN:
      - "mysql.connector.connect"
      - "psycopg2.connect"
      - "sqlite3.connect"
    WITHOUT_POOL_PATTERN: "pooling=False" 或 缺少 pool_size 参数
  action: "block" # 或 "warn", "suggest"
  message: "检测到直接创建数据库连接。请使用配置好的连接池,并设置最大连接数。"

然后,通过 mcp-rules-assistant ingest-rules --custom .ruleflow/custom_rules.yaml 导入。

3. 规则优先级与冲突解决: 当从多个文档来源提取的规则发生冲突时(比如README说“用双引号”,而某个内部文档说“用单引号”),RuleFlow默认遵循:

  • 来源优先级 CONTRIBUTING.md > docs/ 下的文件 > README.md
  • 规则作用域 :更具体的路径配置规则会覆盖更通用的规则。 你可以在 config.yaml 中调整 rules.priority 字段来定义优先级顺序。

4.2 上下文管理器:让AI拥有“记忆”

上下文管理器维护着一个动态的、滚动的“对话记忆池”。它不仅仅是保存聊天记录,而是进行了智能处理:

  1. 关键信息提取 :系统会自动从对话历史中提取出:已定义的关键变量名、已讨论过的设计决策(如“我们决定采用Repository模式”)、已识别出的问题(如“用户模块的认证逻辑有漏洞”)。
  2. 相关性加权 :离当前对话越近的轮次,权重越高。被多次提及的术语(如“ UserService ”)权重也会提高。
  3. Token预算管理 :MCP协议和AI模型都有上下文长度限制。上下文管理器会智能地修剪最旧的、权重最低的记忆,确保最重要的信息始终保留在上下文窗口内,并将总Token数控制在安全范围内。

你可以通过CLI与上下文交互:

# 查看当前的上下文摘要
mcp-rules-assistant context-summary

# 手动添加上下文条目(例如,记录一个临时决策)
mcp-rules-assistant context-add --text "临时决定:在v1.2版本前,兼容旧的API格式。"

# 清除所有上下文记忆(开始一个全新的思维链)
mcp-rules-assistant context-clear

4.3 质量门禁系统:自动化代码卫士

质量门禁是RuleFlow在CI/CD流程中发挥威力的地方。它不是一个新工具,而是你现有工具链(pytest, ruff, bandit)的 智能编排器和策略执行者

门禁工作流:

# 1. 生成CI配置文件(如GitHub Actions)
mcp-rules-assistant generate-ci

这条命令会根据你的 config.yaml 中的 quality_gates 设置,生成一个 .github/workflows/ruleflow-ci.yml 文件。这个工作流会在每次Pull Request时自动运行。

我们来看一个生成的GitHub Actions工作流示例:

name: RuleFlow Quality Gates
on: [pull_request]
jobs:
  quality-gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - name: Install RuleFlow
        run: pip install mcp-rules-assistant
      - name: Ingest Project Rules
        run: mcp-rules-assistant ingest-rules
      - name: Run Test Coverage Gate
        run: |
          # 它会调用 pytest --cov,并对比结果与配置的阈值(98%, 95%)
          mcp-rules-assistant check-gate test_coverage
        # 如果覆盖率不达标,这一步会失败,整个CI标记为失败
      - name: Run Linting Gate
        run: mcp-rules-assistant check-gate linting
      - name: Run Security Gate
        run: mcp-rules-assistant check-gate security_scan
      - name: Upload Detailed Report
        if: always() # 即使失败也上传报告
        uses: actions/upload-artifact@v4
        with:
          name: ruleflow-quality-report
          path: .ruleflow/reports/

2. 本地预检: 在提交代码前,你可以本地运行门禁,提前发现问题:

# 运行所有启用的门禁检查
mcp-rules-assistant diagnose --full

# 或者单独检查某一项
mcp-rules-assistant check-gate test_coverage --module src/core

diagnose 命令会生成一份详细的HTML报告,保存在 .ruleflow/reports/ 下,用浏览器打开可以直观地看到各项指标的通过情况、失败的具体位置和建议的修复方法。

实操心得:门禁阈值的设定 不要一开始就把覆盖率目标定在98%。对于一个遗留项目,可以从70%开始,然后每个迭代周期提高5%。在 config.yaml 中灵活设置不同模块的阈值。例如:

quality_gates:
  test_coverage:
    thresholds:
      “src/core/”: 0.98
      “src/utils/”: 0.90
      “legacy/”: 0.60 # 遗留代码库,逐步改进

这样既能保证核心代码质量,又给重构遗留代码留出了空间,避免了团队因无法达到过高标准而放弃使用门禁。

5. 高级场景与故障排查

5.1 多项目与工作区管理

如果你使用类似VS Code Workspace的功能,同时开发多个关联项目(比如一个前端库和一个后端服务),你可以为每个子项目单独配置RuleFlow,并在工作区级别进行聚合。

  1. 在每个子项目根目录运行 init ingest-rules
  2. 在工作区根目录创建一个 .vscode/ruleflow-workspace.json (如果是Cursor,可能是 .cursor/ruleflow-workspace.json ):
    {
      "projects": [
        {"path": "./backend", "name": "api-server"},
        {"path": "./frontend", "name": "web-app"}
      ],
      "sharedRules": ["./shared/docs/architecture-decisions.md"]
    }
    
  3. RuleFlow的MCP服务器在启动时会读取这个配置,当你在工作区内任何文件提问时,它会自动合并相关项目的规则和上下文,提供统一的辅助。

5.2 性能调优与问题排查

常见问题1:IDE响应变慢或AI回复延迟。

  • 可能原因 :规则太多或上下文记忆过长,导致每次提问前附加的提示词(Prompt)过大。
  • 排查与解决
    # 查看当前活动的规则数量和上下文大小
    mcp-rules-assistant status --verbose
    
    • 精简规则 :运行 mcp-rules-assistant list-rules --verbose ,检查是否有过于宽泛或重复的规则,可以通过编辑源文档或使用 rules.exclude 配置来过滤。
    • 调整记忆轮数 :在 config.yaml 中将 context.memory_turns 从20调低至10-15。
    • 检查MCP日志 :在IDE设置中启用MCP调试日志,查看服务器通信详情。

常见问题2:规则摄取不准确,漏掉或误判了很多条。

  • 可能原因 :项目文档的书写风格与RuleFlow的默认解析模式不匹配。
  • 解决
    1. 使用 --debug 标志运行摄取命令,查看详细解析过程:
      mcp-rules-assistant ingest-rules --debug
      
    2. 根据输出,调整你的文档结构,或者为RuleFlow编写一个小的 自定义解析插件 。RuleFlow支持插件系统,你可以参考 rulesets/ 目录下的例子,编写自己的 MyDocParser 来更好地理解你的文档格式。

常见问题3:CI/CD门禁失败,但本地检查通过。

  • 可能原因 :CI环境与本地环境存在差异(Python版本、依赖包版本、测试环境变量)。
  • 排查步骤
    1. 在CI日志中,找到RuleFlow生成的详细报告(通常是 .ruleflow/reports/ 下的JSON或HTML文件),下载并对比本地报告。
    2. 确保CI流水线中安装了与本地一致的项目依赖( pip install -e .[dev] )。
    3. 检查是否有测试依赖于本地文件或服务,在CI中需要模拟(Mock)。

5.3 扩展RuleFlow:自定义工具与集成

RuleFlow的MCP服务器不仅可以提供资源(Resources),还可以提供工具(Tools)。这意味着你可以让AI助手通过RuleFlow来执行一些自定义操作。

例如,你可以创建一个工具,让AI助手直接查询项目的待办事项(TODO)列表:

  1. 在项目中添加一个文件 mcp_rules_assistant/tools/todo_tool.py
    from mcp.server import Server
    import subprocess
    import re
    
    async def list_todos(server: Server):
        """一个让AI查询项目TODO列表的工具。"""
        # 使用grep(或ripgrep)查找代码中的TODO注释
        result = subprocess.run(
            ["rg", "-n", "--color=never", "TODO|FIXME|HACK", "."],
            capture_output=True,
            text=True,
            cwd=server.project_path
        )
        todos = result.stdout.splitlines()
        # 格式化返回给AI
        return {"todos": todos[:20]} # 只返回前20条,避免过长
    
  2. 在主服务器文件中注册这个工具。
  3. 重启RuleFlow服务后,你在IDE中就可以直接对AI说:“帮我看看这个项目还有哪些TODO?” AI会调用这个工具,获取列表并总结给你。

这种扩展性让RuleFlow从一个被动的规则执行者,变成了一个主动的项目智能中枢。

更多推荐