AI Adapter 简介
@kupola/ai-adapter— 将自然语言转换为结构化操作的 AI 引擎。
什么是 AI Adapter？
AI Adapter 是 Kupola 的独立扩展包，提供自然语言 → 结构化命令 → UI 联动的完整链路。
你可以用它来：
- 让用户用自然语言操作你的应用（"查询张三"、"删除员工李四"、"执行月末统计"）
- 将用户输入自动路由到对应的查询、操作或流程引擎
- 无缝集成 Kupola UI 组件（Table、Modal、Form、Notification 等）
- 接入任意 LLM 后端（OpenAI、Claude、Ollama 等）获得更精准的意图识别
- 在执行前用中间件集中拦截敏感 query/action/flow，并给用户显示无权限提示
架构总览
🗣️ 用户输入
文本 / 语音转文字
↓
🧠 意图解析 IntentParser
AI 后端 （可选）
规则引擎 （内置）
↓
🔍 查询引擎
QueryEngine
只读查询 · 缓存 · 分页
⚙️ 执行引擎
ActionEngine
增删改 · 确认 · 撤销
🔁 流程引擎
FlowEngine
多步骤 · 持久化 · 学习
↓
📡 EventBus
on / once / wildcard / emit
🔧 Middleware
RateLimiter · AuthGuard · DevTools
↓
🎨 Kupola UI 组件
TableModalFormNotificationTimelineProgress
↓
💬 AIPanel
对话面板 · 进度条 · 时间线
📊 AIDashboard
数据卡片 · 聚合 · 自动刷新
🎙️ VoiceController
唤醒词 · 指令映射 · TTS
安装
bash
npm install @kupola/ai-adapter
@kupola/core ^3.0.0和@kupola/platform ^3.0.0作为 peer dependency 自动要求安装。
快速开始
js
import { AIAdapter } from '@kupola/ai-adapter';
const adapter = new AIAdapter();
// 1. 注册查询处理器
adapter.query.register('employee', async (params) => {
return await fetch(`/api/employees?q=${params.keyword}`).then(r => r.json());
});
// 2. 注册操作处理器
adapter.action.register('addEmployee', {
handler: async (p) => fetch('/api/employees', { method: 'POST', body: JSON.stringify(p) }),
confirm: true,
label: '添加员工',
});
// 3. 定义可重复流程
adapter.flow.define('发工资条', {
steps: [
{ label: '获取数据', handler: async (data) => fetchSalary(data) },
{ label: '发送通知', handler: async (data) => notify(data) },
],
});
// 4. 处理自然语言输入
const result = await adapter.process('查询张三');
console.log(result.message); // 🔍 Found 1 employee record(s).
// 5. 列出和执行流程
const flows = await adapter.flow.list();
console.log(flows); // [{ name: '发工资条', createdAt: '2026-07-01', lastRunAt: '2026-07-25' }]
await adapter.flow.execute('发工资条', { month: '2026-07' });核心概念
| 概念 | 说明 | 对应类 |
|---|---|---|
| 意图解析 | 将自然语言转为结构化命令 | IntentParser / RuleBasedParser |
| 查询引擎 | 处理只读数据查询，支持缓存、分页、聚合 | QueryEngine |
| 执行引擎 | 处理写操作（增删改），支持确认、撤销、审计、操作依赖 | ActionEngine |
| 流程引擎 | 处理多步骤可重复流程，支持持久化（localStorage）、自动学习 | FlowEngine |
| 事件总线 | 标准化 pub/sub，支持 once() / wildcard() | EventBus |
| 中间件 | 可扩展的处理管道，内置速率限制、权限守卫、DevTools 日志 | adapter.use() |
| UI 组件 | 对话面板（含我的流程 tab）、数据看板、语音交互 | AIPanel / AIDashboard / VoiceController |
安全模型
2.0.3 之后，AI Adapter 还提供集中式 capability 注册：项目可以一次性声明资源、权限、参数规则、返回字段和 handler，让权限校验、参数过滤和结果脱敏都围绕同一份能力定义执行。
js
adapter.capability.register({
engine: 'query',
type: 'roles',
roles: ['admin'],
permissions: ['role:read'],
paramsSchema: { keyword: 'string' },
resultFields: ['id', 'name', 'code'],
handler: async (params, context) => api.get('/api/roles', params, context),
});2.0.3 之后，AI Adapter 会先把输入解析为结构化命令，再进入中间件管道。这意味着 createAuthGuard 可以在任何 handler 执行前，基于 engine、type、flow name、角色和权限码集中拦截。
js
adapter.use(createAuthGuard({
rules: [
{ engine: 'query', type: 'roles', roles: ['admin'], permissions: ['role:read'] },
{ engine: 'action', types: ['delete_user'], roles: ['admin'] },
],
}));WARNING
前端权限只用于交互拦截和提示，不能替代后端鉴权。业务 API 必须继续校验登录态、角色、菜单权限和数据权限；前端被绕过时，服务端应返回 401 或 403。
双语支持
内置规则引擎同时支持中文和英文：
js
// 中文
await adapter.process('查询张三上个月出勤');
await adapter.process('添加员工李四');
await adapter.process('执行月末统计');
// 英文
await adapter.process('search attendance records');
await adapter.process('add employee John');
await adapter.process('run monthly report');