Docs
文档目录

场景库 SDK

这是什么 / 何时用

场景库将企业智能客服、售后和运营流程中的业务场景整理成可管理的名称、定义和有序分类路径。它适合在构建知识图谱前统一业务术语、维护产品目录和批量导入场景表;它不是模型生成的实体缓存,也不会因为新增场景就自动更新已经构建的 GraphRAG。场景分类可以绑定知识库及文档标签,使图谱构建与 Wiki 目录按同一业务组织方式工作。场景定义变化后,应显式启动后续索引任务,并检查其完成结果。

前置

安装精确版本 agentbase-node-sdk@2.12.0,使用项目 API Key。读取需要 scenarios.read,创建、编辑、导入、删除和知识绑定需要 scenarios.write;操作绑定的知识库还须满足对应资源约束。Key 只保存在服务端环境变量中,不传入浏览器。需要用户界面的管理流程可使用同版本 Console SDK;Web 用户端是否允许调用必须逐端点核对,不能直接照搬服务端权限。

使用骨架

  1. 初始化项目 Client 和 Scenarios,读取目录与目标分类。

  2. 创建分类和场景,保存返回 ID 与 revision,读取验证名称和完整路径。

  3. 编辑前重新获取 revision,提交更改后再次读回;不把旧列表中的版本当作最新版本。

  4. 批量导入先解析文件与预览冲突,再明确选择冲突策略和提交;导入按原子提交,校验失败时先修正再提交;成功后核对 created/updated/skipped 统计。

  5. 删除分类前读取影响预览和确认 token,确认后提交;场景删除携带 revision。

关键参数与返回

参数 / 方法契约
categories有序字符串数组,表达完整目录路径;不能把 售后/退款 一个字符串当作两个层级
name / definition业务场景名称与描述,创建时 name 必填,definition 默认空字符串
scenarioId创建时可选,默认 unique();自行指定时应稳定保存以便核对重复提交
revision更新/删除场景、修改分类名称和知识绑定时使用当前版本,防止覆盖他人变更
limit / offset列表分页;search 按名称搜索,includeDescendants 控制是否包含子分类
createCategory传完整 categories;返回分类对象,保存其 ID 与 revision
updateKnowledgeBinding传 categoryId、revision,以及知识库/标签路径或绑定集合
parseImport / previewImport / import文件解析、变更预览、真正提交三个不同阶段;不能把预览视为已保存
getCategoryDeletionImpact / deleteCategory先读取影响和 token,再确认删除;过期或状态变化后重新预览

Scenario 返回 ID、revision、名称、定义及目录路径;ScenarioList 返回场景集合与分页统计。预览返回逐条处置建议,提交原子生效;成功后核对 created/updated/skipped 与预期一致。分类与场景分别管理,移动分类或更名涉及现有子项,应先检查影响。

错误与边界

400/422 时检查目录数组、字段长度、文件映射和冲突策略;401/403 时核对项目身份与 scopes;404 时检查当前项目和资源是否已被删除;409 时先重新读取 revision 与当前内容,再决定重新编辑。删除影响预览失效后重新获取 token,不绕过确认。网络错误后先按已保存 ID 或目录查重,再决定是否重新创建,避免重复业务场景。分页必须读取后续页,首屏统计不是全部结果。

SDK 类别差异

本页示例使用 Node Server SDK 的对象参数签名。Console SDK 用于管理场景,需要当前 Console 身份和目标项目上下文。Java、Python、Go 的命名和参数顺序以同版本生成面为准,本页不将 Node 对象参数直接改写为未核实的其它语言调用。REST 完整字段、HTTP 状态与方法映射见 场景 API。

各语言调用示例

以下操作使用 Node.js;每段共享初始化后的 scenarios 对象,读取操作可独立执行,写入应在专用演示项目执行。

初始化与目录读取

import { Client, Scenarios } from 'agentbase-node-sdk';
const client = new Client().setEndpoint(process.env.AGENTBASE_ENDPOINT)
 .setProject(process.env.AGENTBASE_PROJECT_ID).setKey(process.env.AGENTBASE_API_KEY);
const scenarios = new Scenarios(client);
const categories = await scenarios.listCategories({ limit: 25, offset: 0 });
console.log(categories);

创建并读回

await scenarios.createCategory({ categories: ['Customer support', 'Refunds'] });
const created = await scenarios.create({ categories: ['Customer support', 'Refunds'],
 name: 'Refund eligibility', definition: 'Determine whether a delivered order is eligible for refund.' });
const current = await scenarios.get({ scenarioId: created.$id });
console.log(current.name, current.revision);

更新与分页读取

const saved = await scenarios.update({ scenarioId: current.$id,
 revision: current.revision, definition: 'Check delivery date, return window and payment status.' });
const page = await scenarios.list({ limit: 25, offset: 0,
 categories: ['Customer support'], includeDescendants: true });
console.log(saved.revision, page);

文件解析

import { InputFile } from 'agentbase-node-sdk/file';
const parsed = await scenarios.parseImport({ file: InputFile.fromPath(process.env.AGENTBASE_SCENARIO_FILE) });
console.log(parsed);

删除影响预览

const impact = await scenarios.getCategoryDeletionImpact({ categoryId: process.env.AGENTBASE_SCENARIO_CATEGORY_ID });
console.log(impact);

预览并提交导入

import { ConflictPolicy } from 'agentbase-node-sdk';
if (parsed.sheets.some(sheet => sheet.errors.length)) throw new Error('Correct invalid rows first');
const entries = parsed.sheets.flatMap(sheet => sheet.entries);
const preview = await scenarios.previewImport({ entries, conflictPolicy: ConflictPolicy.Skip });
console.log(preview);

提交前核对 preview 的 created/updated/skipped,再单独执行下面提交段。

const imported = await scenarios.import({ entries, conflictPolicy: ConflictPolicy.Skip });
console.log(imported.created, imported.updated, imported.skipped);

确认删除

const categoryId = process.env.AGENTBASE_SCENARIO_CATEGORY_ID;
const reviewed = await scenarios.getCategoryDeletionImpact({ categoryId });
console.log(reviewed.categories, reviewed.scenarios);

确认影响范围后才执行删除;状态变化后重新预览,不复用旧 token。

await scenarios.deleteCategory({ categoryId, token: reviewed.token });

示例指引

安装与版本 · Node 初始化 · JavaScript 示例