Bottle Shop End of Trade Web Application

SSOT-RULE-ENGINE-TEMPLATE

一个智能 AI 驱动的开发框架，将单一事实来源（SSOT）项目状态管理、上下文感知规则引擎和模型上下文协议（MCP）集成相结合，打造可自我组织、不断学习的开发环境。

🎯 概览

SSOT-RULE-ENGINE-TEMPLATE 通过以下功能改进你的开发工作流：

• 🧠 持久化 AI 记忆：基于知识图谱的项目理解能力，随时间不断成长
• 📋 集中式状态管理：为所有项目信息提供单一事实来源
• 🎛️ 上下文感知 AI 行为：可根据项目需求调整的动态规则系统
• 🔧 高级 AI 能力：提供专用 MCP 服务，增强推理和分析能力
• 📊 智能项目跟踪：自动监控进度并生成文档
• 📈 高级分析：实时监控项目健康状况并洞察性能表现

✨ 主要功能

🏗️ SSOT（单一事实来源）系统

• 在 .cursor/CORE/SSOT/ 中集中管理项目状态
• 自动记录项目历史并跟踪进度
• 通过触发器系统智能编排工作流
• 通过快照和恢复功能实现项目可移植性

🎯 规则引擎

• 通过 .mdc 文件实现上下文感知的 AI 行为
• 应用全局规则和特定文件规则
• 自动生成并暂存规则
• 强制执行一致的开发标准

🚀 MCP 集成

• 知识图谱服务：持久化的实体关系项目建模
• 序贯思维服务：多步推理与问题解决
• 文件系统服务：增强文件系统操作与分析能力

🔄 智能工作流

• 自动初始化和分析项目
• 智能理解代码库并生成文档
• 准备 GitHub 并优化代码仓库
• 全面的测试与质量保障

📈 高级分析系统

• 实时项目健康评分（0-100 分）
• 提供实时可视化效果的交互式 Web 控制面板
• 多维度分析（SSOT、MCP、规则、项目结构）
• 智能推荐引擎，提供优先级建议
• 跟踪开发速度并分析趋势
• 监控系统性能并提供优化洞察

🚀 快速开始

前置条件

• Node.js（v16 或更高版本）
• npm 或 yarn
• 具备 AI 能力的 Cursor IDE

安装

新项目

1. 在 Cursor 聊天中描述你的项目，然后初始化：

!!-INIT-.ENGINE-!!

2. 安装 MCP 服务：

!!-INSTALL-MCP-!!

3. 构建知识图谱：

!!-BUILD-KG-!!

现有项目

1. 分析现有代码库：

!!-ADD-.ENGINE-!!

2. 安装 MCP 服务：

!!-INSTALL-MCP-!!

3. 构建知识图谱：

!!-BUILD-KG-!!

🎮 核心命令

命令	用途	适用时机
!!-INIT-.ENGINE-!!	初始化新项目 （自动启动控制面板）	提供项目描述后
!!-ADD-.ENGINE-!!	添加到现有项目 （自动启动控制面板）	用于现有代码库
!!-INSTALL-MCP-!!	安装 MCP 服务	执行 INIT 或 ADD 后
!!-BUILD-KG-!!	构建知识图谱	安装 MCP 后
!!-LAUNCH-DASHBOARD-!!	启动带有可视化规则引擎的分析控制面板	随时手动启动控制面板
!!-ANALYZE-PROJECT-!!	运行全面的项目分析	详细评估健康状况时
!!-VIEW-DASHBOARD-!!	在浏览器中打开分析控制面板	快速访问控制面板
!!-HEALTH-CHECK-!!	快速系统评估	快速查看状态时
!!-UPDATE-SSOT-!!	同步项目状态	重大变更后
!!-CREATE-PORTABLE-!!	创建项目快照	用于备份或传输
!!-LOAD-PORTABLE-!!	加载项目快照	用于恢复状态
!!-UPDATE-DOCS-!!	更新文档	用于同步文档
!!-PREPARE-GITHUB-!!	为 GitHub 做准备	上传到代码仓库前

📁 项目结构

.cursor/
├── CORE/
│   ├── SSOT/                   # Single Source of Truth files
│   │   ├── .ENGINE             # Central workflow orchestrator
│   │   ├── .INIT               # Project initialization
│   │   ├── .CONTEXT            # High-level overview
│   │   ├── .FACTS              # Technical decisions
│   │   ├── .MEMORY             # Component summaries
│   │   ├── .HISTORY            # Activity log
│   │   ├── .CONTINUE           # Next steps
│   │   └── .PROGRESS           # Task tracking
│   ├── MCP/                    # MCP server implementations
│   │   ├── knowledge-graph/    # Graph database server
│   │   ├── sequentialthinking/ # Reasoning server
│   │   └── filesystem/         # File operations server
│   ├── RULE-ENGINE/            # Generated rules staging
│   ├── MEMORY/                 # Persistent memory storage
│   ├── PROMPTS/                # System prompts
│   ├── ANALYTICS/              # Analytics engine and dashboard
│   │   ├── analytics_engine.py # Project health analysis
│   │   ├── dashboard.py        # Web dashboard with visual rule engine
│   │   ├── startup.py          # Dashboard auto-launch script
│   │   ├── USER-RULES-TEMPLATE.md # Template for easy USER-RULES setup
│   │   └── dashboard/          # Generated dashboard files
│   └── DOCS/                   # Documentation
├── rules/                      # Active rule files
├── mcp.json                    # MCP configuration
└── launch-dashboard.py         # Quick dashboard launcher

🔧 配置

MCP 服务配置

此模板包含三个预配置的 MCP 服务：

1. 知识图谱服务 - 持久化项目记忆
2. 顺序思考服务 - 高级推理能力
3. 文件系统服务 - 增强文件操作

配置由触发系统自动处理。

规则引擎配置

规则定义在带有 frontmatter 的 .mdc 文件中：

---
description: Rule description
globs: **/*.js, **/*.ts
alwaysApply: false
---

# Rule Content
Your guidelines and instructions...

📊 示例用例

Web 应用开发

# Describe your Flask/Django/Express app, then:
!!-INIT-.ENGINE-!!
!!-INSTALL-MCP-!!
!!-BUILD-KG-!!

集成现有代码库

# For any existing project:
!!-ADD-.ENGINE-!!
!!-INSTALL-MCP-!!
!!-BUILD-KG-!!

团队协作

# Create portable state for sharing:
!!-CREATE-PORTABLE-!!

# Team member loads state:
!!-LOAD-PORTABLE-!!

项目分析与监控

# Quick health assessment:
!!-HEALTH-CHECK-!!

# Comprehensive analysis:
!!-ANALYZE-PROJECT-!!

# Launch interactive dashboard with visual rule engine:
!!-LAUNCH-DASHBOARD-!!

# Open dashboard in browser (if already running):
!!-VIEW-DASHBOARD-!!

# Manual launch options:
python launch-dashboard.py                    # Quick launcher from project root
python .cursor/CORE/ANALYTICS/startup.py     # Direct startup script

仪表板功能：

• 📊 分析选项卡：实时健康评分和项目指标
• ⚙️ 规则引擎选项卡：可视化规则管理界面
• 📋 USER-RULES 选项卡：复制模板，轻松完成设置
• 🗂️ SSOT 选项卡：系统状态监控和文件检查

🎯 优势

面向开发者

• 持久化上下文：AI 会在不同会话间记住你的项目
• 智能协助：提供上下文感知的建议和代码生成
• 自动化文档：自动更新项目文档
• 质量保证：统一的编码标准和最佳实践

面向团队

• 知识共享：在团队成员间轻松传递上下文
• 新成员入职：帮助新开发者快速了解项目结构
• 标准执行：确保团队遵循一致的开发模式
• 进度跟踪：全面记录项目历史并监控进度

面向项目

• 降低技术债务：持续监控并改进质量
• 改善架构：由 AI 指导架构决策和重构
• 增强测试：智能生成测试并分析覆盖率
• 文档：始终保持项目文档最新
• 健康监控：实时评估项目健康状况并分析趋势
• 性能洞察：提供可执行的优化建议
• 可视化分析：通过交互式仪表板全面管理项目

📈 高级功能

知识图谱查询

系统会为你的项目构建全面的知识图谱：

• 实体：文件、函数、类、模块、配置
• 关系：依赖、调用、实现、包含
• 观察项：注释、指标、模式、决策

高级分析仪表板

实时监控项目并获取洞察：

• 健康评分：采用 0-100 分制全面评估项目健康状况
• 系统分析：SSOT（30%）、MCP（30%）、规则（25%）、常规（15%）明细
• 交互式可视化：图表、关系图和实时数据显示
• 智能建议：按优先级排序的改进建议
• 开发速度：活动跟踪和生产力指标
• Web 界面：支持响应式布局和自动刷新的仪表板

# Launch analytics dashboard
cd .cursor/CORE/ANALYTICS
python dashboard.py  # Opens browser automatically

# Generate static reports
python analytics_engine.py  # Creates JSON and Markdown reports

项目可移植性

创建和恢复完整的项目快照：

• 完整保留 SSOT 状态
• 备份和恢复知识图谱
• 传输规则配置
• 跨环境兼容

GitHub 集成

自动准备代码仓库：

• 智能生成 .gitignore
• 同步文档
• 代码质量检查
• 准备发布

🛠️ 故障排除

MCP 服务问题

# Check MCP server status
npm run build  # In each MCP server directory

# Restart servers
# Restart Cursor IDE

SSOT 同步

# Update SSOT after major changes
!!-UPDATE-SSOT-!!

# Rebuild Knowledge Graph if needed
!!-BUILD-KG-!!

规则引擎问题

• 检查 rules/ 目录中的 .mdc 文件语法
• 确认 glob 模式与目标文件匹配
• 查看 CORE/RULE-ENGINE/ 中的规则暂存情况

分析仪表板问题

# Generate dashboard without starting server
cd .cursor/CORE/ANALYTICS
python dashboard.py --generate-only

# Start dashboard on custom port
python dashboard.py --port 8080 --no-browser

# Run analytics analysis only
python analytics_engine.py

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 使用 SSOT 系统跟踪开发进度
4. 使用 !!-UPDATE-DOCS-!! 更新文档
5. 使用 !!-PREPARE-GITHUB-!! 做好提交准备
6. 提交 Pull Request

📄 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

🙏 致谢

• Model Context Protocol（MCP） - 感谢其提供基础服务器架构
• Cursor AI - 感谢其提供智能 IDE 集成
• Anthropic - 感谢其提供先进的 AI 推理能力

📞 支持

• 文档：参见 DOCS/Comprehensive Documentation.md
• 问题：通过 GitHub Issues 报告问题
• 讨论：在 GitHub Discussions 中提出问题和想法

🗺️ 路线图

• 可视化知识图谱探索器
• 高级分析和指标
• 与热门开发工具集成
• 扩展多语言支持
• 基于云的知识图谱同步
• 基于机器学习的项目预测
• 团队协作分析
• CI/CD 流水线集成

---

立即开始借助 AI 驱动的开发，打造更智能的体验！ 🚀