@sciexpr/ai

AI Provider SPI 接口 + 内置回退。

安装

npm install @sciexpr/ai

SPI 接口

4 个 Provider 接口：

接口	用途
IAICompletionProvider	智能补全
IKnowledgeBaseProvider	知识库查询
IAINormalizerProvider	AI 输出规范化
IAIFormatterProvider	AI 格式化

AIPipeline

import { AIPipeline } from '@sciexpr/ai'

const pipeline = new AIPipeline({
  completionProvider: new MyOpenAIProvider(),
  knowledgeBaseProvider: new MyKBProvider(),
})

// 补全
await pipeline.getCompletions({ currentInput: '\\alp', cursorPosition: 4, expressionType: 'math' })

// 知识库
await pipeline.queryKnowledge({ query: 'Carbon' })

内置回退（离线可用）

实现	功能
BuiltinCompletionProvider	3000+ 符号匹配
BuiltinKnowledgeBase	118 元素 + 符号表
BuiltinNormalizer	正则规范化
BuiltinFormatter	规则格式化

OpenAI 接入示例

import OpenAI from 'openai'
import { BUILTIN_PROMPTS } from '@sciexpr/ai'

class OpenAIProvider implements IAICompletionProvider {
  id = 'openai'; name = 'GPT-4'
  async complete(ctx) {
    const res = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [
        { role: 'system', content: BUILTIN_PROMPTS.completion.system },
        { role: 'user', content: `Complete: ${ctx.currentInput}` },
      ],
    })
    return JSON.parse(res.choices[0].message.content)
  }
}

无头函数调用：chatToFormula

chatToFormula() 是面向 「自然语言 → 公式」 的纯函数入口，不依赖任何 UI 组件 （Vue / React / Node 均可直接调用）。它一次性完成：

1. 消息组装 — 自动注入默认 System Prompt（KaTeX / mhchem 规范）；
2. LLM 调用 — provider 支持流式时自动走 chatStream（打字机效果），否则回退 chat；
3. 结果清理 — sanitizeFormulaResponse() 剥离代码围栏、$$ 定界符、AI 前导语等。

import { chatToFormula, OpenAICompatProvider } from '@sciexpr/ai'

const provider = new OpenAICompatProvider({
  baseURL: 'https://api.deepseek.com/v1',
  apiKey: 'sk-...',
  model: 'deepseek-chat',
})

const { cleaned, raw, streamed } = await chatToFormula({
  provider,
  prompt: '生成一元二次方程的求根公式，并解析',
  signal: abortController.signal,   // 可选：取消请求
  onStream: (acc) => console.log(acc), // 可选：流式增量回调
})

console.log(cleaned) // 清理后的 Markdown / 公式

其他导出：

API	说明
sanitizeFormulaResponse(text)	清理 LLM 原始输出
buildFormulaMessages(prompt, systemPrompt?)	组装 system + user 消息
DEFAULT_FORMULA_SYSTEM_PROMPT	公式生成默认 System Prompt（可被 systemPrompt 覆盖）
FORMULA_USER_PROMPT_PREFIX	公式生成默认 user 消息前缀
EXPERIMENT_SYSTEM_PROMPT	实验方案生成 System Prompt（ELN 实验需求场景，内置常量）
EXPERIMENT_USER_PROMPT_PREFIX	实验方案生成 user 消息前缀
ChatToFormulaOptions / ChatToFormulaResult	类型定义

import {
  chatToFormula, OpenAICompatProvider,
  EXPERIMENT_SYSTEM_PROMPT, EXPERIMENT_USER_PROMPT_PREFIX,
} from '@sciexpr/ai'

// ELN 实验需求 → 实验方案（直接引用内置 Prompt 常量）
const { cleaned } = await chatToFormula({
  provider: new OpenAICompatProvider({ baseURL: 'https://api.deepseek.com/v1', apiKey: 'sk-...', model: 'deepseek-chat' }),
  prompt: '【化学名称 / 反应体系】甲醇制烯烃（MTO），SAPO-34 分子筛\n【反应条件】温度 480℃，常压',
  systemPrompt: EXPERIMENT_SYSTEM_PROMPT,
  userPromptPrefix: EXPERIMENT_USER_PROMPT_PREFIX,
})

| ChatToFormulaOptions / ChatToFormulaResult | 类型定义 |

支持的接口协议（ApiProtocol）

协议	端点	Provider 实现	典型服务
'chat-completions'	POST {baseURL}/chat/completions	OpenAICompatProvider	OpenAI / DeepSeek / Ollama / vLLM / 绝大多数国内厂商
'messages'	POST {baseURL}/v1/messages	AnthropicCompatProvider	Anthropic Claude / StepFun 阶跃星辰 / 兼容代理
'responses'	POST {baseURL}/responses	ResponsesCompatProvider	OpenAI 新一代接口（gpt-5 系列）

协议类型 ApiProtocol = 'chat-completions' | 'messages' | 'responses' 与厂商名解耦 —— 同一厂商可能提供多种协议（如 OpenAI 同时提供 chat-completions 与 responses）， 判断依据应为「协议」而非「厂商名」。

import { ResponsesCompatProvider } from '@sciexpr/ai'

// Responses API（OpenAI 新一代接口）
const provider = new ResponsesCompatProvider({
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'sk-...',
  model: 'gpt-5',
})
const result = await provider.chat([
  { role: 'system', content: '你是科学表达式助手' },
  { role: 'user', content: '生成质能方程' },
])

Provider 配置项（AIProviderConfig）

字段	类型	默认	说明
baseURL	string	—	API 根地址（自动拼接 /v1/messages 或 /chat/completions）
apiKey	string	—	API Key
model	string	—	模型名称
authType	'x-api-key' | 'bearer'	'x-api-key'	Anthropic 认证方式：官方用 x-api-key；StepFun 等国内兼容服务必须 'bearer'（否则 401，且 anthropic-version 头不在其 CORS 白名单）
maxTokens	number	2048	最大生成 token 数；推理模型 + 长输出建议调大（如 8192）
streamThinking	boolean	false	流式输出思考过程：开启后 thinking_delta 以 \u0002...\u0003 标记包裹 yield，sanitizeFormulaResponse 会自动剥离

⚠️ 安全提示：请勿将 API Key 硬编码在源码中，建议通过环境变量或运行时配置注入。