场景库 SDK
这是什么 / 何时用
场景库将企业智能客服、售后和运营流程中的业务场景整理成可管理的名称、定义和有序分类路径。它适合在构建知识图谱前统一业务术语、维护产品目录和批量导入场景表;它不是模型生成的实体缓存,也不会因为新增场景就自动更新已经构建的 GraphRAG。场景分类可以绑定知识库及文档标签,使图谱构建与 Wiki 目录按同一业务组织方式工作。场景定义变化后,应显式启动后续索引任务,并检查其完成结果。
前置
安装精确版本 agentbase-node-sdk@2.12.0,使用项目 API Key。读取需要 scenarios.read,创建、编辑、导入、删除和知识绑定需要 scenarios.write;操作绑定的知识库还须满足对应资源约束。Key 只保存在服务端环境变量中,不传入浏览器。需要用户界面的管理流程可使用同版本 Console SDK;Web 用户端是否允许调用必须逐端点核对,不能直接照搬服务端权限。
使用骨架
初始化项目 Client 和 Scenarios,读取目录与目标分类。
创建分类和场景,保存返回 ID 与 revision,读取验证名称和完整路径。
编辑前重新获取 revision,提交更改后再次读回;不把旧列表中的版本当作最新版本。
批量导入先解析文件与预览冲突,再明确选择冲突策略和提交;导入按原子提交,校验失败时先修正再提交;成功后核对 created/updated/skipped 统计。
删除分类前读取影响预览和确认 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 对象,读取操作可独立执行,写入应在专用演示项目执行。
初始化与目录读取
- Node.js(Server)
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);创建并读回
- Node.js(Server)
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);更新与分页读取
- Node.js(Server)
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);文件解析
- Node.js(Server)
import { InputFile } from 'agentbase-node-sdk/file';
const parsed = await scenarios.parseImport({ file: InputFile.fromPath(process.env.AGENTBASE_SCENARIO_FILE) });
console.log(parsed);删除影响预览
- Node.js(Server)
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 });