RuleFlow:基于MCP协议的AI编程助手规则治理与上下文记忆系统
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/)
工作流程 可以这样理解:
- 初始化 :开发者运行
mcp-rules-assistant init,工具在项目根目录创建.ruleflow文件夹和配置文件。 - 规则摄取 :运行
ingest-rules命令,规则引擎开始扫描指定的文档。它会使用正则表达式和轻量级NLP(如基于spaCy或自定义模式)识别出“必须”、“禁止”、“应当”等约束性语句,并将其分类为风格规则、安全规则、测试规则等。 - 上下文绑定 :当开发者在IDE中打开项目,RuleFlow的MCP服务器启动。IDE(MCP客户端)会通过协议查询可用的
Resources。RuleFlow将当前项目的规则集、最近的质量检查报告等作为资源提供出去。 - AI辅助 :当用户在IDE中向AI提问时,IDE会自动将这些资源作为上下文附加到用户的问题前。于是,AI在回答“如何实现这个函数”时,已经提前知道了“本项目要求函数有类型注解和文档字符串”。
- 质量守门 :在提交代码前,开发者或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下的脚本逻辑类似,但有几个关键区别:
- 激活虚拟环境的命令是
.venv\Scripts\activate.bat(CMD)或.venv\Scripts\Activate.ps1(PowerShell)。 - 路径分隔符是反斜杠
\。 - 建议在 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
这个过程发生了什么?
- 引擎会读取
config.yaml中sources列表的所有文件。 - 对每个文件进行解析。对于Markdown,它会识别各级标题(
#,##)作为规则分类,提取列表项(-,*,1.)和代码块旁的描述文本作为规则内容。 - 使用规则提取器分析文本。例如,当它读到“ 所有公开的函数和方法必须包含类型注解和Google风格的Docstring。 ”时,它会:
- 分类:
code_style->documentation - 提取关键元素:
scope: public_functions_and_methods,requirement: must_have,content: type_annotations_and_google_docstring - 生成一条结构化规则,并存入数据库。
- 分类:
- 最终,你会在终端看到类似摘要:“成功从5个文件摄取42条规则(风格: 18, 安全: 10, 测试: 14)”。
注意事项:如何编写易于摄取的文档? RuleFlow的提取器不是万能AI,它依赖于一定的文档结构。为了让提取更准确,建议你的项目文档:
- 使用清晰的标题 :如
## 代码风格规范、### 测试要求、## 安全守则。- 约束条件使用强调语气 :多用“必须”、“禁止”、“应当”、“建议”,避免模糊表述。
- 具体化规则 :“错误处理必须记录日志”比“要做好错误处理”更好。
- 完成后,运行
mcp-rules-assistant list-rules可以查看所有已摄取的规则,检查是否有误判或遗漏。
3.3 与你的IDE深度集成
RuleFlow的核心价值在于无缝的IDE体验。安装钩子后,你需要重启IDE。以VS Code/Cursor为例:
- 确保RuleFlow的MCP服务器正在运行(安装脚本通常已将其设置为后台服务或IDE插件)。
- 打开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" } } } } - 打开一个项目内的Python文件,尝试在AI聊天框中提问:“帮我写一个读取配置文件的函数。”
- 观察变化 :在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拥有“记忆”
上下文管理器维护着一个动态的、滚动的“对话记忆池”。它不仅仅是保存聊天记录,而是进行了智能处理:
- 关键信息提取 :系统会自动从对话历史中提取出:已定义的关键变量名、已讨论过的设计决策(如“我们决定采用Repository模式”)、已识别出的问题(如“用户模块的认证逻辑有漏洞”)。
- 相关性加权 :离当前对话越近的轮次,权重越高。被多次提及的术语(如“
UserService”)权重也会提高。 - 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,并在工作区级别进行聚合。
- 在每个子项目根目录运行
init和ingest-rules。 - 在工作区根目录创建一个
.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"] } - 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的默认解析模式不匹配。
- 解决 :
- 使用
--debug标志运行摄取命令,查看详细解析过程:mcp-rules-assistant ingest-rules --debug - 根据输出,调整你的文档结构,或者为RuleFlow编写一个小的 自定义解析插件 。RuleFlow支持插件系统,你可以参考
rulesets/目录下的例子,编写自己的MyDocParser来更好地理解你的文档格式。
- 使用
常见问题3:CI/CD门禁失败,但本地检查通过。
- 可能原因 :CI环境与本地环境存在差异(Python版本、依赖包版本、测试环境变量)。
- 排查步骤 :
- 在CI日志中,找到RuleFlow生成的详细报告(通常是
.ruleflow/reports/下的JSON或HTML文件),下载并对比本地报告。 - 确保CI流水线中安装了与本地一致的项目依赖(
pip install -e .[dev])。 - 检查是否有测试依赖于本地文件或服务,在CI中需要模拟(Mock)。
- 在CI日志中,找到RuleFlow生成的详细报告(通常是
5.3 扩展RuleFlow:自定义工具与集成
RuleFlow的MCP服务器不仅可以提供资源(Resources),还可以提供工具(Tools)。这意味着你可以让AI助手通过RuleFlow来执行一些自定义操作。
例如,你可以创建一个工具,让AI助手直接查询项目的待办事项(TODO)列表:
- 在项目中添加一个文件
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条,避免过长 - 在主服务器文件中注册这个工具。
- 重启RuleFlow服务后,你在IDE中就可以直接对AI说:“帮我看看这个项目还有哪些TODO?” AI会调用这个工具,获取列表并总结给你。
这种扩展性让RuleFlow从一个被动的规则执行者,变成了一个主动的项目智能中枢。
更多推荐

所有评论(0)