diff --git a/MEMORY.md b/MEMORY.md index 9b93d7e..b845f7a 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -2,3 +2,9 @@ - 当前暂无已提炼的长期记忆。 - 在这里记录跨会话稳定生效的偏好、架构决策和最佳实践。 + +--- + +## 时间线索引 + +- [2026-05-11](memory/2026-05-11.md) — AI 规则引擎设计方案确认 diff --git a/docs/plans/2026-05-11-ai-rule-engine-design.md b/docs/plans/2026-05-11-ai-rule-engine-design.md new file mode 100644 index 0000000..3123508 --- /dev/null +++ b/docs/plans/2026-05-11-ai-rule-engine-design.md @@ -0,0 +1,221 @@ +# 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 管理界面 diff --git a/memory/2026-05-11.md b/memory/2026-05-11.md new file mode 100644 index 0000000..6f8db35 --- /dev/null +++ b/memory/2026-05-11.md @@ -0,0 +1,40 @@ +# 2026-05-11 + +## 纪要 + +- AI 规则引擎项目启动 + +## 决策 + +### AI 规则引擎技术选型 +- **技术栈**: Python 3.10+ / SQLite / REST API / 本地运行 +- **AI 编译器**: GPT-4o / Claude Sonnet +- **安全隔离**: RestrictedPython +- **规则形式**: Python 函数 + 安全隔离执行 + +**为什么方案 A(轻量级自研)而非方案 B(规则引擎库)?** +- AI 生成 Python 函数链路最短,灵活度最高 +- MVP 阶段快速验证核心价值 +- 后续可按需替换执行层 + +### 核心功能优先级 +1. SQLite 存储层 +2. 基础 REST API +3. LLM 编译器 +4. RestrictedPython 执行器 +5. 基础规则校验 +6. 冲突检测(简化版) + +### 冗余处理范围 +- 规则去重(embedding 相似度) +- 规则冲突检测(真值表分析) +- LLM Callback 兜底(无匹配时自动补充规则) + +## 问题与修复 + +(暂无) + +## 待办 + +- [ ] Phase 2: 编写实现计划 +- [ ] Phase 3: TDD 实现