📊 数据集模块使用指南

📁 源码位置: dataset.ts（没权限找刘慧涛开）

DatasetPlugin 是一个封装了常见 CRUD 操作的插件类，继承自 Dataset，主要用于与统一的 Storage API 进行交互。

它提供了简洁的接口来操作数据集（collection），并自动处理了 Base64 编码数据集名称、平台 token 注入、返回结果解包等通用逻辑。

特性一览

• 添加单条 / 批量添加记录
• 更新单条记录（必须提供 id）
• 删除单条 / 批量删除
• 分页查询（支持排序、条件）
• 普通条件查询（不分页）
• 统一处理返回数据结构
• 自动注入平台 token
• 数据集名称自动 Base64 编码

快速开始

在 Agent 脚本中，可以直接通过 scp.dataset 访问数据集模块：

// 使用 scp.dataset 调用各种方法
await scp.dataset.add('collectionId', '数据集名称', { /* 数据 */ })
await scp.dataset.queryPage('collectionId', '数据集名称', { page: 0, count: 10 })

API 参考

add - 添加记录

async add(
  collectionId: string,
  collectionName: string,
  params: AddCmdData | AddCmdData[]
): Promise<ApiResponse>

参数

参数	类型	必填	说明
collectionId	string	是	数据集唯一标识（通常是表名或 key）
collectionName	string	是	数据集显示名称（会 Base64 后传给后端）
params	AddCmdData | AddCmdData[]	是	单对象或对象数组，禁止包含 id

限制

• 禁止传入空对象 {}
• 禁止在添加数据中包含 id 字段
• 每个对象至少包含一个属性

示例

// 单条添加
await scp.dataset.add('user', '用户信息', {
  username: 'alice',
  age: 28,
  role: 'editor'
})

// 批量添加
await scp.dataset.add('user', '用户信息', [
  { username: 'bob', age: 25 },
  { username: 'carol', age: 30 }
])

update - 更新记录

async update(
  collectionId: string,
  collectionName: string,
  params: UpdateCmdData
): Promise<ApiResponse>

参数

参数	类型	必填	说明
collectionId	string	是	数据集标识
collectionName	string	是	数据集名称
params	UpdateCmdData	是	必须包含 id，至少再有一个其他字段

限制

• id 必须存在且不能为空
• 除了 id 外，至少要更新一个字段

示例

await scp.dataset.update('user', '用户信息', {
  id: '64f8a2b3c...',
  age: 29,
  status: 'active'
})

delete - 删除记录

async delete(
  collectionId: string,
  collectionName: string,
  id: string | string[]
): Promise<ApiResponse>

参数

参数	类型	必填	说明
collectionId	string	是	数据集标识
collectionName	string	是	数据集名称
id	string | string[]	是	id 或 id 数组

示例

// 删除单条
await scp.dataset.delete('user', '用户信息', '64f8a2b3c...')

// 批量删除
await scp.dataset.delete('user', '用户信息', ['id1', 'id2', 'id3'])

queryPage - 分页查询

async queryPage(
  collectionId: string,
  collectionName: string,
  params: QueryPageCmdData
): Promise<ApiResponse>

默认参数

{
  count: 10,     // 每页条数
  page: 0,       // 页码（从 0 开始）
  order: '',     // 排序字段，如 createTime-、age+
  query: 2       // 默认查询模式（建议保持）
}

示例

// 第一页，每页 20 条，按创建时间降序
await scp.dataset.queryPage('user', '用户信息', {
  page: 0,
  count: 20,
  order: 'createTime-',
  status: 'active'
})

// 模糊搜索名字包含 "张"
await scp.dataset.queryPage('user', '用户信息', {
  count: 15,
  page: 1,
  name: '张'           // 根据后端是否支持 @like 等
})

query - 普通条件查询（不分页）

async query(
  collectionId: string,
  collectionName: string,
  params: QueryCmdData
): Promise<ApiResponse>

示例

await scp.dataset.query('user', '用户信息', {
  role: 'admin',
  status: 'active'
})

返回数据结构

所有方法返回的 ApiResponse 经过处理后，常见结构如下：

{
  data: any[],           // 记录数组
  total?: number,        // 分页查询时存在，表示总条数
  // 其他后端可能返回的字段...
}

完整示例

// 添加
const res = await scp.dataset.add('product', '商品表', {
  name: '无线耳机',
  price: 299,
  stock: 100
})

// 更新
await scp.dataset.update('product', '商品表', {
  id: res.data[0].id,
  price: 279,
  stock: 85
})

// 分页查询
const page = await scp.dataset.queryPage('product', '商品表', {
  page: 0,
  count: 10,
  order: 'createTime-',
  category: 'electronics'
})

console.log('总条数:', page.total)
console.log('数据:', page.data)

// 删除
await scp.dataset.delete('product', '商品表', res.data[0].id)

注意事项

• collectionId 和 collectionName 必须与后端注册一致
• 依赖 this.$API.env.scpEndpoint 和 token 配置正常
• queryPage 中的 query: 2 含义需参考后端文档
• 批量操作（add / delete）性能更优，建议优先使用数组形式
• 查询条件是否支持 like、>、in 等操作符，取决于后端实现

如有特定场景或高级用法需求，请提供更多上下文。