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項目