Ranex Framework

🚀 Ranex社区版

Ranex社区版是一个专为Python打造的AI原生治理框架，它能够让AI生成的代码具备生产就绪能力，助力开发者更高效地构建和管理项目。

🚀 快速开始

安装

# 运行安装脚本（创建虚拟环境）
./install.sh

# 激活虚拟环境
source .venv/bin/activate

或者手动安装：

python3 -m venv .venv
source .venv/bin/activate
pip install ranex_core-0.0.1-cp312-cp312-manylinux_2_28_x86_64.whl

初始化项目

cd your-project
ranex init
ranex scan

在代码中使用

from ranex import Contract

@Contract(feature="orders")
async def process_order(order_data, *, _ctx=None):
    """
    状态机强制：待处理 → 已确认 → 处理中 → 已发货 → 已交付
    """
    _ctx.transition("Confirmed")
    # ... 你的业务逻辑
    return {"status": "confirmed"}

✨ 主要特性

✅ 包含20项特性

📦 安装指南

本软件包包含以下内容：

community-edition/
├── ranex_core-*.whl          # Rust核心 + Python包（PyO3）
├── ranex_mcp                 # MCP服务器二进制文件（21MB）
├── ranex-cli                 # CLI二进制文件（4MB）
├── ranex/                    # Python源代码（包含在wheel中）
│   ├── __init__.py          # @Contract装饰器
│   ├── cli.py               # CLI命令
│   ├── errors.py            # 错误类型
│   ├── logging.py           # 日志工具
│   ├── simulation.py        # 全息甲板模拟
│   └── templates.py         # 项目模板
├── docs/                    # 文档（20篇指南）
├── mcp_config.json          # MCP配置模板
├── MCP_SETUP.md             # MCP设置指南
├── README.md                # 本文件
├── QUICK_START.md           # 5分钟快速入门指南
├── install.sh               # 简易安装脚本（创建虚拟环境）
└── LICENSE                  # MIT许可证

💻 使用示例

基础用法

from ranex import Contract

@Contract(feature="orders")
async def process_order(order_data, *, _ctx=None):
    """
    状态机强制：待处理 → 已确认 → 处理中 → 已发货 → 已交付
    """
    _ctx.transition("Confirmed")
    # ... 你的业务逻辑
    return {"status": "confirmed"}

高级用法

# 安装MCP服务器
cp ranex_mcp /usr/local/bin/

# 添加到Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "ranex": {
      "command": "/usr/local/bin/ranex_mcp"
    }
  }
}

🔧 技术细节

1. 状态机验证

防止AI跳过业务逻辑步骤：

# app/features/orders/state.yaml
feature: orders
initial_state: Pending

states:
  Pending: { description: "新订单" }
  Confirmed: { description: "订单已确认" }
  Processing: { description: "正在准备" }
  Shipped: { description: "运输中" }
  Delivered: { description: "已完成", terminal: true }
  Cancelled: { description: "已取消", terminal: true }

transitions:
  - { from: Pending, to: Confirmed }
  - { from: Pending, to: Cancelled }
  - { from: Confirmed, to: Processing }
  - { from: Processing, to: Shipped }
  - { from: Shipped, to: Delivered }

当AI违反规则时的情况：

StateTransitionError: [orders] 🛑 非法状态转换
  当前状态: Pending
  尝试转换: Pending → Delivered
  允许转换: Pending → [Confirmed, Cancelled]

2. 安全扫描（7种模式）

ranex scan

检测内容包括：

• SQL注入
• 命令注入（os.system）
• 硬编码密钥
• 弱加密（MD5、SHA1）
• 不安全的反序列化（pickle）
• 路径遍历
• 不安全的随机数

3. 导入验证（仿冒包检测）

from ranex_core import ImportValidator

validator = ImportValidator()
result = validator.check_package("reqests")  # 标记仿冒包！

4. CLI命令

ranex init          # 初始化项目
ranex scan          # 安全 + 架构扫描
ranex arch          # 架构验证
ranex fix           # 自动修复
ranex doctor        # 健康检查
ranex task          # 工作流管理（状态/设计/构建）
ranex context       # 生成AI对齐提示
ranex verify        # 全息甲板模拟测试
ranex db            # 数据库工具
ranex graph         # 生成Mermaid图表
ranex bench         # 性能基准测试
ranex stress        # 压力测试
ranex update-rules  # 刷新AI治理规则

5. MCP服务器（AI集成）

ranex_mcp二进制文件为AI助手提供了10种工具：

# 安装MCP服务器
cp ranex_mcp /usr/local/bin/

# 添加到Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "ranex": {
      "command": "/usr/local/bin/ranex_mcp"
    }
  }
}

社区版MCP工具：

• validate_file_structure - 架构验证
• validate_transition - 状态机检查
• check_import - 仿冒包检测
• security_scan - SAST（7种模式）
• detect_antipattern - 代码异味检测（5种模式）
• list_db_aliases - 数据库配置
• validate_sql - SQL验证
• validate_intent - 歧义检测
• check_function_exists - 语义搜索（TF-IDF）
• get_active_persona - 查看角色

完整的设置指南请参阅 MCP_SETUP.md。

⬆️ 升级到团队版

如果您有更多需求，团队版包含以下额外特性：

联系我们：sales@ranex.dev

📄 许可证

本项目采用MIT许可证，可自由用于个人和商业项目。

🆘 支持

• 文档：ranex.dev/docs
• 问题反馈：GitHub Issues

Ranex v0.0.1社区版 © 2025 Ranex项目