Lovrabet 帮助中心

简体中文

English

简体中文

English

主题

Changelog ​

本文档汇总 @lovrabet/sdk（lovrabet-node-sdk）2026 年 1 月–8 月的版本变更，涵盖 v1.2.5 至 v1.4.3 共 13 个正式版本。

INFO

当前最新版本：v1.4.3（2026-08-07）｜包名：@lovrabet/sdk ｜数据来源：Git commit diff

v1.4.3（2026-08-07） ​

INFO

运行态 OCR 识别与文件服务（client.services）

✨ feat：新增 client.services 运行态服务命名空间

LovrabetClient 新增 services 命名空间，统一承载运行态 OCR 识别与文件上传/取用能力，包含 ocr 与 file 两个客户端。

✨ feat：OCR 识别 services.ocr.recognize

传入公开可访问的图片/文件 URL 与识别类型，返回文本、按行结果与结构化键值数据；OcrType 枚举覆盖通用、发票、身份证、银行卡、营业执照、行驶证、车牌、表格等 11 种类型。

TypeScript
const res = await client.services.ocr.recognize({
  url: 'https://example.com/invoice.png',
  type: OcrType.Invoice,
});
// { requestId, type, text, lines, kvData }

✨ feat：文件上传与取用 services.file.upload / queryUrl

upload 接收 Blob/File 上传并返回 filePath；queryUrl 凭 filePath 取回访问地址，支持 download 与 longTerm 选项。文件服务支持 cookie 与 client-ak 鉴权模式，不支持 OpenAPI。

TypeScript
const uploaded = await client.services.file.upload({
  file: blob,
  fileName: 'report.pdf',
});
const { fileUrl } = await client.services.file.queryUrl({
  filePath: uploaded.filePath!,
});

v1.4.2（2026-06-27） ​

INFO

aggregate 聚合参数 column 对齐

🐞 fix：aggregate 聚合参数对齐为 column

聚合字段统一使用 column，旧 field 写法作为向下兼容别名仍可使用；缺失 column 时抛出 INVALID_AGGREGATE_COLUMN。

TypeScript
model.aggregate({
  aggregate: [{ type: 'SUM', column: 'amount' }],
});
// 旧写法 field 仍兼容：
// model.aggregate({ aggregate: [{ type: 'SUM', field: 'amount' }] });

v1.4.1（2026-04-12） ​

INFO

$notNull 条件运算符 + 前期 breaking change 收尾

✨ feat：添加 $notNull 条件运算符

ConditionOperator 类型新增 $notNull，用于字段的非空判断。

TypeScript
// 使用示例
model.getList({
  filter: {
    field: { $notNull: true }
  }
})

同时补充了 filter 单元测试用例。

v1.4.0（feature/cli-client 分支） ​

INFO

⚠️ 包含 BREAKING CHANGE，请注意向后兼容性问题

✨ feat：Client AK 鉴权模式 + batchCreate

新增 authMode 显式分流机制，支持三种认证模式：

authMode说明使用场景
openapiOpenAPI 签名认证Node.js 服务端，明确使用 AccessKey
client-akClient AK 鉴权（新增）新一代 BFF/SQL 客户端
cookie（默认）WebAPI Cookie 认证浏览器/服务端，默认方式

BREAKING CHANGE（重要）：

未设置 authMode 时，默认走 cookie（WebAPI），不再仅凭 accessKey/token 推断 OpenAPI。

✨ feat：batchCreate 批量创建（1～1000 条）

AbstractBaseModel 新增 batchCreate 方法：

TypeScript
// 一次创建最多 1000 条
model.batchCreate([
  { name: '张三', age: 25 },
  { name: '李四', age: 30 }
])
  • WebAPI 请求体为数组
  • OpenAPI 使用 paramList（与服务端契约对齐）

✨ feat：新增 ClientAKModel、ClientAkAuth

src/api/ 下新增 client-ak-bff-client.ts 和 client-ak-sql-client.ts，提供 client-ak 前缀的 SQL/BFF 客户端能力。

ModelFactory 重构：按 authMode 选择对应模型实现，职责更清晰。

v1.3.8（feature/cli-client 分支） ​

INFO

Q1 changelog 文档补充 + 环境映射日志静默

主要是文档补充和日志级别调整，无功能变更。

v1.3.7（2026-04-03） ​

INFO

配置命名对齐 + API 调用体验优化 + 参数透传 bug fix

✨ feat：runtimeDomain 替代 serverUrl

ClientConfig.serverUrl → @deprecated，新增 runtimeDomain 字段，与 rabetbase-cli 的 .rabetbase.json 命名对齐。

getBaseUrl() 优先级链：

  1. runtimeDomain（新增）
  2. serverUrl（兼容保留，两者同时存在时 runtimeDomain 优先）
  3. window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN（SSR 注入）
  4. getApiEndpoint(env)（环境兜底）

默认环境从 online → production（online 自动映射为 production）。

✨ feat：update() / delete() 对象合并写法

<grid> <column width-ratio="0.500000"> 旧写法（仍兼容）

TypeScript
await model.update(1001, { name: '张三' });
await model.delete(1001);

</column> <column width-ratio="0.500000"> 新写法（推荐）

TypeScript
await model.update({ id: 1001, name: '张三' });
await model.delete({ id: [1001, 1002] });

</column> </grid>

内部检测：typeof idOrData === 'object' && !Array.isArray(idOrData) 走对象分支，解构出 id 后与 ...rest 合并。

🐛 fix：createClient() ModelsConfig 透传

createClient({ appCode, models }) 模式原先只解构这两个字段，runtimeDomain / token 等额外字段被静默丢弃。修复为 const { appCode, models, ...rest } = config，rest 展开到最终配置。

v1.3.6（2026-03-16） ​

INFO

自定义 headers、批量操作、ListResponse 类型重构、5 项 bug fix

<grid> <column width-ratio="0.500000"> ✨ feat

  • 自定义请求头：ClientConfig.options 新增 headers: Record<string, string>，用于注入 X-Invoke-Source、追踪 ID 等- 批量 update/delete：id 参数扩展为 string | number | (string | number)[]，内部 join(',')，上限 1000 条 </column> <column width-ratio="0.500000"> 🐛 fix
  • ListResponse 类型对齐服务端：tableData / paging / tableColumns 必选，移除虚构的 total / currentPage / pageSize，新增 Paging 接口- OpenAPI SQL 防御性校验：models[0] 非空检查，抛 INVALID_MODEL_CONFIG- Cookie 显式检测：新增 hasExplicitCookie()，修复 Node.js 环境误判- aggregate 方法映射：OpenApiModel.methodMap 补全- LovrabetError override 修复 </column> </grid>

♻️ refactor：环境变量统一

新增 development 环境（dev.lovrabet.com），online → production、dev → development 自动映射。新增 getApiEndpoint() / getAvailableEnvironments() 工具函数。

v1.3.4（2026-03-07） ​

INFO

OpenAPI 模式补齐 aggregate 能力

✨ feat：OpenAPI 模式支持 aggregate

移除 OpenApiModel 上的 aggregate override，改为继承 AbstractBaseModel 基类实现。supportedOperations 新增 'aggregate'，OpenAPI 与 WebAPI 共享同一套聚合查询逻辑。

v1.3.5 为补丁发布，无功能变更。

v1.3.2（2026-03-06） ​

INFO

Node.js 环境显式 Cookie 认证，服务端 SDK 可脱离浏览器使用

✨ feat：ClientConfig 新增 cookie?: string

CookieAuth 重构为双模式：

<grid> <column width-ratio="0.500000"> 浏览器环境

  • credentials: 'include' 自动携带- 无额外 header- isValid() = isBrowser </column> <column width-ratio="0.500000"> Node.js 环境
  • cookie 字符串注入 Cookie header- credentials: 'include' 仅浏览器启用- isValid() = hasExplicitCookie </column> </grid>

v1.3.3 为补丁发布，无功能变更。

v1.3.1（2026-01-25） ​

INFO

getOne 方法参数兼容性增强

✨ feat：getOne() 对象格式传参

TypeScript
model.getOne(123);           // 数字 ID
model.getOne('abc');         // 字符串 ID
model.getOne({ id: 123 });   // 对象格式（新增）

内部 typeof idOrParams === 'object' 时解构出 id，完全向后兼容。

v1.3.0（2026-01-24） ​

INFO

架构升级版本：API 拆分为独立客户端模块，BFF 接口有 Breaking Change

⚠️ Breaking：BFF 客户端接口变更

移除 FxResult<T> 包装层，execute() 直接返回业务数据 T：

<grid> <column width-ratio="0.500000"> 旧写法

TypeScript
const result = await client.bff
.execute('getBundleTemplates');
if (result.success) {
console.log(result.data);
}

</column> <column width-ratio="0.500000"> 新写法

TypeScript
const templates = await client.bff
.execute({
  scriptName: 'getBundleTemplates',
});
// 失败直接抛 LovrabetError

</column> </grid>

迁移要点：result.success 检查 → try-catch。

✨ feat：safe() / sqlSafe() 错误处理

Go 风格的 { data, error } 返回模式，sqlSafe() 自动解包 execResult：

TypeScript
const { data, error } = await safe(model.filter(params));
const { data, error } = await sqlSafe(client.sql.execute({ sqlCode }));

♻️ refactor：API 拆分为独立客户端

客户端路径职责
SqlClientclient.sqlSQL 查询 execute({ sqlCode, params })
BffClientclient.bffBFF 端点 execute({ scriptName, params })
UserClientclient.user用户 API getList()

client.api 保留为兼容别名层。

✨ feat：SortOrder 类型增强

SortOrderValue 联合类型，同时兼容枚举和字符串字面量：

TypeScript
orderBy: [{ field: 'createTime', order: SortOrder.DESC }]
orderBy: [{ field: 'createTime', order: 'desc' }]  // 新增

♻️ refactor：filter 参数格式统一

所有 filter 参数统一放入 paramMap。新增 isDevelopment() 环境检测，开发环境 getList() 输出性能提示引导使用 filter()。

✨ feat：新增 fx 接口

client.api.fx() BFF 调用入口，去掉 filter 的 yt 前缀过滤。

v1.2.7（2026-01-12） ​

INFO

SSR 全局配置注入支持

✨ feat：getBaseUrl() 三级优先级

HttpClient.getBaseUrl() 改为 public：

  1. config.serverUrl（本地开发 / 私有化部署）
  2. window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN（SSR 注入）
  3. getApiEndpoint(env)（环境兜底）

LovrabetClient.getBaseUrl() 改为透传，消除重复逻辑。新增 global.d.ts 类型声明。

v1.2.8 为补丁发布，无功能变更。

v1.2.5（2026-01-06） ​

INFO

聚合查询 + 错误处理体系重构 + 智能诊断 + 安全校验

✨ feat：聚合查询 aggregate()

支持 SUM / COUNT / AVG / MIN / MAX。类型系统新增：AggregateParams、AggregateField、AggregateType、JoinConfig、HavingCondition。

WebAPI 通过 YT_PARAM_MAP 映射参数名；OpenAPI 抛 OPENAPI_OPERATION_NOT_SUPPORTED。

✨ feat：结构化错误处理

  • LovrabetError 构造器改为 options 对象，新增 description 字段
  • 所有错误抛出点返回结构化上下文（模型清单、有效范围、示例代码）
  • toJSON() 包含 description

✨ feat：LLM 友好智能诊断

processResponse 智能解析服务端错误：

  • 字段缺失 → 提示必填项
  • 字段不存在 → 检查拼写 + MCP 工具推荐
  • 401 → 登录态、appCode 权限、CORS 排查方向
  • 超时 → 包含 url / method / timeout 上下文

✨ feat：datasetCode 格式验证

模型解析优先级：dataset_ 前缀 > alias > 动态创建。强制 32 位十六进制校验，禁止已有配置时静默创建动态模型。

v1.2.6 为补丁发布，无功能变更。

版本总览 ​

版本日期featfixrefactorBreaking关键变更
v1.4.308-07300—client.services 运行态服务：OCR 识别（11 种类型）、文件上传与取用
v1.4.206-27010—aggregate 参数对齐 column，兼容旧 field
v1.4.104-12300—Client AK 鉴权（client-ak）；batchCreate 批量创建；$notNull 运算符
v1.3.704-03310—runtimeDomain 替代 serverUrl；update/delete 对象合并写法；createClient 透传修复
v1.3.603-16251—自定义 headers；批量 update/delete（1000 条）；ListResponse 类型重构；环境变量统一
v1.3.403-07100—OpenAPI 模式支持 aggregate
v1.3.203-06100—Node.js 显式 cookie 参数，CookieAuth 双模式重构
v1.3.101-25100—getOne 对象格式传参
v1.3.001-24403YESAPI 拆分为 SqlClient / BffClient / UserClient；BFF 移除 FxResult<T>；safe/sqlSafe；SortOrder 字面量支持
v1.2.701-12100—getBaseUrl() 三级优先级；SSR 全局配置注入
v1.2.501-06400—aggregate() 聚合查询；LovrabetError 结构化错误；LLM 智能诊断；datasetCode 格式校验

基于飞书知识库同步生成，内容以飞书源文档为准

Lovrabet · 启智云图