ai-rule-engine/docs/plans/2026-05-11-ai-rule-engine-design.md

# AI 规则引擎设计方案

## 1. 背景与目标

### 1.1 问题
- 规则判断通常需要调用 LLM API，成本高、延迟大
- 规则以自然语言描述，每次判断都需 AI 解析，效率低

### 1.2 目标
- 将自然语言规则描述通过 AI 转换为可执行 Python 函数
- 存储转换后的规则，支持快速校验
- 提供兜底机制：无法匹配时调用 LLM 补充规则

### 1.3 成功标准
- 规则创建后，后续判断无需再调用 LLM API
- 规则冲突/重复可被检测
- 无法匹配时自动触发 LLM callback 并学习新规则

---

## 2. 技术选型

| 模块 | 技术 |
|------|------|
| 语言 | Python 3.10+ |
| 存储 | SQLite |
| AI 编译器 | GPT-4o / Claude Sonnet（自然语言→Python 函数） |
| 安全隔离 | `RestrictedPython` |
| API | REST API |
| 部署 | 本地运行 |

---

## 3. 模块边界与数据流

```
┌─────────────────────────────────────────────────────────────┐
│                      AI 规则引擎                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐ │
│  │   Rule API   │───▶│Rule Compiler │───▶│ Rule Store  │ │
│  │  (REST)      │    │   (LLM)      │    │  (SQLite)   │ │
│  └──────────────┘    └──────────────┘    └──────────────┘ │
│         │                                       │          │
│         ▼                                       ▼          │
│  ┌──────────────┐                       ┌──────────────┐   │
│  │Rule Matcher  │◀──────────────────────│Rule Executor │   │
│  │              │                       │(RestrictedPy)│   │
│  └──────────────┘                       └──────────────┘   │
│         │                                       │          │
│         │ 无匹配时                              │          │
│         ▼                                       │          │
│  ┌──────────────┐                               │          │
│  │ LLM Callback │──────────────────────────────▶│          │
│  │ (补充规则)   │                               │          │
│  └──────────────┘                               │          │
│                                                     │      │
└─────────────────────────────────────────────────────┘      │
```

### 3.1 核心模块

| 模块 | 职责 |
|------|------|
| RuleAPI | 提供 REST 接口（创建规则、校验事实、查询规则） |
| RuleCompiler | 调用 LLM 将自然语言规则转换为 Python 函数 |
| RuleStore | SQLite 存储规则（含元数据：名称、描述、版本、优先级） |
| RuleExecutor | 在 RestrictedPython 沙箱中执行规则函数 |
| RuleMatcher | 判断事实匹配哪条规则 |
| ConflictDetector | 检测规则冲突 |
| Deduplicator | 检测规则重复/相似 |
| LLMEallback | 无法匹配时调用 LLM 补充规则 |

### 3.2 数据模型

```sql
CREATE TABLE rules (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    condition_template TEXT NOT NULL,  -- 原始规则描述
    code TEXT NOT NULL,               -- 转换后的 Python 函数代码
    priority INTEGER DEFAULT 0,
    version INTEGER DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT 1
);

CREATE TABLE rule_executions (
    id TEXT PRIMARY KEY,
    rule_id TEXT,
    facts TEXT NOT NULL,              -- JSON 格式的事实数据
    result TEXT,                      -- 执行结果
    matched BOOLEAN,
    executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (rule_id) REFERENCES rules(id)
);

CREATE TABLE rule_embeddings (
    rule_id TEXT PRIMARY KEY,
    embedding TEXT NOT NULL,          -- 用于相似度计算
    FOREIGN KEY (rule_id) REFERENCES rules(id)
);
```

---

## 4. API 设计

### 4.1 创建规则
```
POST /api/rules
Body: {
    "name": "premium_discount",
    "description": "如果用户是高级会员，给予8折优惠",
    "condition_template": "用户{{user_id}}的订阅类型为{{subscription}}，且年龄大于{{age}}",
    "facts_schema": {...}  // 可选：事实格式定义
}
Response: { "id": "rule_xxx", "code": "..." }
```

### 4.2 校验事实
```
POST /api/rules/evaluate
Body: {
    "facts": {
        "user_id": "u123",
        "subscription": "premium",
        "age": 25
    }
}
Response: {
    "matched": true,
    "rule_id": "rule_xxx",
    "result": { "action": "apply_discount", "params": {"discount": 0.8} }
}
```

### 4.3 查询规则
```
GET /api/rules
GET /api/rules/{id}
```

### 4.4 删除规则
```
DELETE /api/rules/{id}
```

---

## 5. 错误处理

| 场景 | 处理方式 |
|------|----------|
| LLM 编译失败 | 返回错误，保留原始描述供修改 |
| 规则执行超时 | 限制执行时间（如 100ms），超时视为失败 |
| 无规则匹配 | 触发 LLM Callback，尝试生成新规则 |
| 规则冲突 | 警告返回，冲突规则不执行，需人工确认 |
| 规则重复 | 自动合并或提示用户确认 |

---

## 6. 冗余处理

### 6.1 规则去重
- 使用 embedding 计算语义相似度
- 相似度 > 0.95 的规则视为重复
- 提示用户合并或覆盖

### 6.2 规则冲突检测
- 两两比对规则条件
- 使用真值表分析是否存在矛盾（如：A→通过，B→拒绝 且条件重叠）
- 冲突规则标记，需人工确认优先级

### 6.3 LLM Callback 兜底
- 无规则匹配时，自动调用 LLM
- LLM 分析 facts，生成新规则描述
- 新规则经编译后存入数据库，下次直接使用

---

## 7. 安全考虑

| 风险 | 缓解措施 |
|------|----------|
| 动态代码执行 | RestrictedPython 沙箱，禁止危险操作 |
| 执行超时 | 规则执行限制 100ms |
| LLM 注入 | 输入 facts 做格式校验 |
| 数据泄露 | 不记录敏感 facts 内容 |

---

## 8. 测试策略

| 层级 | 内容 |
|------|------|
| 单元测试 | RuleCompiler、RuleExecutor、ConflictDetector |
| 集成测试 | API 端到端（创建规则→校验→结果） |
| 安全测试 | 沙箱隔离验证、恶意代码检测 |

---

## 9. MVP 范围

### 第一阶段（本次实现）
- [x] 方案设计
- [ ] SQLite 存储层
- [ ] 基础 REST API
- [ ] LLM 编译器（GPT-4o）
- [ ] RestrictedPython 执行器
- [ ] 基础规则校验接口
- [ ] 冲突检测（简化版）

### 第二阶段（后续）
- [ ] 规则去重
- [ ] LLM Callback 兜底机制
- [ ] 高级冲突检测
- [ ] Web 管理界面