Docs
文档目录

内容审核

这是什么 / 何时用

Moderation 在写入链路上对内容做前置审核:对象是数据表文本与存储桶图片。它与 rowSecurity 互补——rowSecurity 管谁能读写数据,Moderation 管写入的内容是否允许保存。

2.12.0 支持按配置审核存储桶图片;实际生效取决于平台与项目开关、桶配置和审核服务。上传路径读取图片字节,通过 Base64 适配器送审。异常后需核查对象及记录的清理状态,不能假定零残留。

2.9.0 新增:createConfig 支持 mode: 'post' | 'hybrid'(异步后置审核;平台开启二期后可在新建或更新配置时选择;关闭时新请求不接受这两种模式,已有配置执行时回退同步审核)与 requireManualReviewOnViolation(违规转人工复核,默认开启;关闭时违规文档为 private_hold 而非隔离)。文档读取返回 moderationStatus(checking / pending / published / quarantined / private_hold / action_error)与 moderationJobId;未发布文档的审核状态检查允许创建者、最后修改者及特权身份;实际读取仍需满足适用认证和数据库权限。含属性过滤条件的列表 total 可能高估。

前置

使用骨架

  1. 创建表文本审核配置(仅首次;对已有配置重复 create 会失败):

    moderation.createConfig({
      resourceType: ResourceType.Collections,   // 或 'collections'
      resourceId: '<tableId>',
      databaseId: '<databaseId>',               // collections 必填
     mode: 'pre',                              // 2.9.0 起可选 'post' | 'hybrid'(需平台开启审核二期;关闭时新建或更新不接受这两种模式)
     requireManualReviewOnViolation: true,     // 2.9.0:违规转人工复核(默认 true;false 时违规文档 private_hold)
      contentTypes: ['text'],                   // 首次 createConfig 必填
      enabled: true
    })
  2. 之后继续普通的 TablesDB 写入(createRow / updateRow 等):审核自动在写入链路执行——没有 moderate() 之类的显式方法。通过 → 写入成功;阻断 → 写入返回错误。

  3. 查配置 / 调整 / 删除:getConfig / updateConfig(改 enabled 或审核参数;仅切 enabled 可省略 contentTypes,原有配置保留)/ deleteConfig。

  4. 排查:listLogs({ queries: [Query.equal('result', 'block')], total: true }) 按 resourceType / resourceId / databaseId / result / timestamp / userId / contentType 筛选审核日志;getLog({ logId }) 查单条。

关键参数与返回

错误与边界

SDK 类别差异

示例指引

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

创建表文本审核配置

审核配置是服务端管理面:Web SDK 无 Moderation 服务(浏览器只感知写入成功/失败),JS Console SDK 亦无(控制台页面直接配置)。

import { Client, Moderation, ResourceType } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // 必须包含 /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);        // moderation.config.write
{
  const prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}
const moderation = new Moderation(client);

await moderation.createConfig({
    resourceType: ResourceType.Collections,   // 或 'collections'
    resourceId: 'tasks',
    databaseId: 'app-db',                     // collections 必填
    mode: 'pre',                              // v1 仅支持前置审核
    contentTypes: ['text'],                   // 首次 createConfig 必填
    enabled: true
});
// 仅首次:对已有配置重复 create 会失败;之后继续普通 TablesDB 写入即可

写入数据并触发审核

没有显式 moderate() 方法:配置生效后由普通 TablesDB 写入(createRow / updateRow)在链路上自动执行——通过则写入成功,阻断则写入返回审核错误。

import { TablesDB, ID } from 'agentbase-node-sdk';

const tablesDB = new TablesDB(client);   // client 同「创建表文本审核配置」卡

await tablesDB.createRow('app-db', 'tasks', ID.unique(), { title: '待审核的文本' });
// 通过:写入成功;阻断:写入报错 → 到「排查审核日志」卡定位原因

查配置、调整与删除

已有配置不要重复 createConfig(重复创建会失败):查 getConfig、调整/启停 updateConfig(仅切 enabled 时可省略 contentTypes,原有配置保留)、删除 deleteConfig。Web SDK 无 Moderation 服务。

这些操作各自独立;停用或删除会影响内容审核,请核对目标和影响后再执行。Node.js 与 Python 示例先在同一会话中定义查询块内的资源变量。

查询配置。

const tableResource = {
    resourceType: ResourceType.Collections,   // 或 'collections'
    resourceId: 'tasks',
    databaseId: 'app-db'
};

const current = await moderation.getConfig(tableResource);

停用审核,请确认影响。

await moderation.updateConfig({ ...tableResource, enabled: false });   // 关闭但保留配置

重新启用。

await moderation.updateConfig({ ...tableResource, enabled: true });    // 重新开启

删除配置,请确认不再需要。

await moderation.deleteConfig(tableResource);

排查审核日志

写入被阻断(TablesDB 写入返回审核错误)时,先查日志定位原因,再检查项目级审核开关与审核服务配置。Web SDK 无 Moderation 服务(浏览器只感知写入成功/失败)。

import { Query } from 'agentbase-node-sdk';

const blocked = await moderation.listLogs({
    queries: [Query.equal('result', 'block')],
    total: true
});   // 可按 resourceType / resourceId / databaseId / result / timestamp / userId / contentType 筛选
const one = await moderation.getLog({ logId: '<logId>' });