Console SDK(Node.js / JavaScript)
Console SDK 面向管理面调用方:Console 面板能力、组织与项目治理、跨项目运维自动化,认证用管理身份——邮箱密码 Session 或 短期 JWT。npm 坐标 agentbase-console-sdk@2.10.0。Java / Python / Go 面见同目录 java.md / python.md / go.md;浏览器前端用 Client SDK;服务端数据面用 Server SDK。
安装与初始化
npm install agentbase-console-sdk@2.10.0 --save-exact方式一:sdk 包装对象(推荐,自动管理端点与模式)
import { sdk, realtime } from 'agentbase-console-sdk';
sdk.forConsole.projects.list(/* 组织/控制台级调用 */);
sdk.forConsoleIn('default').health.get(); // 指定 region
sdk.forProject('default', '<projectId>').tablesDB.listRows(...); // 项目资源面,自动 setProject + setMode('admin')方式二:裸 Client(需要精细控制认证时)
import { Client } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('<consoleOrProjectId>'); // X-Appwrite-Project 头认证装载(三选一,互斥):
邮箱密码 Session:
account.createEmailPasswordSession({ email, password })后装载会话 cookie(自动登录流程拦截响应set-cookie并client.setCookie(...))。短期 JWT:
client.setJWT(token)——短期凭据,禁止写入日志。SQL 场景项目 API Key:
client.setProject('<应用项目ID>').setKey('<项目APIKey>')——供 Sql 服务 指向应用项目。
其他 setter:setMode('admin')、setLocale、setSelfSigned。
5 分钟上手(管理自动化)
const projects = sdk.forConsole.projects;
const project = await projects.create({
projectId: 'unique()', name: 'My Project', teamId: '<teamId>', region: 'default',
});
const key = await projects.createKey(project.$id, 'server key', [
'users.read', 'users.write', 'teams.read', 'teams.write',
]);
// key.secret 只在创建响应出现一次,立即交给服务端安全存储服务端拿 Key 接入 Server SDK;域名规则、迁移、备份等治理面继续用本页服务。
Console 专有 service
| 服务 | 覆盖 |
|---|---|
Organizations | 组织成员与账单等管理能力;作为导出类由 Console Client 单独实例化,不在 sdk.forConsole 包装对象上 |
Proxy | 站点/API/函数/重定向域名规则(createSiteRule / listRules / getRule / updateRuleVerification / deleteRule) |
Vcs | Git 集成:installation、仓库发现、分支列表、仓库内容、外部部署状态回写 |
Migrations | 迁移任务(Appwrite/Firebase/Supabase/NHost/AppBase/CSV 导入导出):创建、报告、重试、删除;另有 SchemaMigration(基于 TablesDB 的表结构计划/执行助手) |
Assistant | assistant.chat() 管理侧 AI 助手 |
Console | 平台元数据:listRegions / listTags、计划与资源查询、列/索引建议(suggestColumns / suggestIndexes)、变量 |
Admin | 平台管理:池/标签列表、存储迁移、项目表模式转换、项目删除审计与恢复 |
Activities / Backups / Domains | 事件流、备份策略与档案、域名资产 |
管理面端到端实战(建项目、签发 Key、注册 Web 平台、管理词库与执行 SQL)
以下示例演示在 Node.js 管理脚本中使用 agentbase-console-sdk@2.10.0 完成企业项目(如 enterprise-ai-hub-210)的自动化开通、Web 平台 CORS 域名白名单注册、项目级词库(Lexicons)创建绑定,以及通过 Console SDK 独有的 Sql 服务执行参数化 SQL 查询:
import { Client, Projects, Teams, Sql, ID, Scopes } from 'agentbase-console-sdk';
// 1. 初始化管理面 Client(先指向 console 项目完成组织与项目开通)
const consoleClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID ?? 'console')
.setJWT(process.env.APPBASE_ADMIN_JWT!); // 或使用 setCookie / setSession 装载管理员会话
const teams = new Teams(consoleClient);
const projects = new Projects(consoleClient);
// 2. 创建组织(Team)与 Shared V2 企业项目
const org = await teams.create({
teamId: '69c6d1aa00062e6bb60',
name: 'Agentbase 企业智能中台',
});
const project = await projects.create({
projectId: 'enterprise-ai-hub-210',
name: '企业智能客服与知识中台',
teamId: org.$id,
region: 'default', // 固定传 'default',不使用 Appwrite Cloud 的区域枚举
});
// 3. 为后端服务签发最小权限集合的 API Key(secret 仅在创建响应中返回一次)
const serverKey = await projects.createKey({
projectId: project.$id,
name: 'prod-backend-service-key',
scopes: [
Scopes.UsersRead,
Scopes.UsersWrite,
Scopes.TablesRead,
Scopes.TablesWrite,
Scopes.RowsRead,
Scopes.RowsWrite,
Scopes.KnowledgebasesRead,
Scopes.KnowledgebasesWrite,
],
});
console.log('请立即安全保存 API Key Secret:', serverKey.secret);
// 4. 注册前端 Web 平台域名(开启浏览器 CORS 信任,仅 Console Session/JWT 可调)
await projects.createPlatform({
projectId: project.$id,
type: 'web',
name: 'Enterprise Support Portal',
hostname: 'support.enterprise.example.com',
});
// 5. 切换 Client 到目标项目并使用 Sql 服务执行参数化查询(JS Console SDK 独有能力)
const projectSqlClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
.setProject(project.$id)
.setKey(serverKey.secret);
const sql = new Sql(projectSqlClient);
const queryResult = await sql.query({
databaseId: 'enterprise_biz_db',
query: 'SELECT ticketNo, title, status, priority FROM customer_tickets WHERE status = ? ORDER BY `$createdAt` DESC LIMIT ?',
params: ['open', 20],
});
console.log('SQL 命中行数:', queryResult.rowCount, '是否截断:', queryResult.truncated);
// 6. 项目级词库(Lexicons)管理与知识库绑定(本地开发版提供 Lexicons 类;已发布 2.10.0 包使用 client.call)
await projectSqlClient.call('post', new URL(`${projectSqlClient.config.endpoint}/lexicons`), {
'content-type': 'application/json',
}, {
lexiconId: 'lex_enterprise_synonyms',
name: '企业核心产品同义词词典',
tokenizerProfile: 'native-v1',
});
await projectSqlClient.call('put', new URL(`${projectSqlClient.config.endpoint}/knowledgebases/kb_enterprise_support/lexicons`), {
'content-type': 'application/json',
}, {
enabled: true,
bindings: [
{ lexiconId: 'lex_enterprise_synonyms', priority: 1 },
{ lexiconId: 'lex_support_stopwords', priority: 2 },
],
});Console SDK 与 Server SDK、Client Web SDK 选型对比
| 维度 | Console SDK(agentbase-console-sdk@2.10.0) | Server SDK(agentbase-node-sdk@2.10.0) | Client Web SDK(agentbase-web-sdk@2.10.0) |
|---|---|---|---|
| 核心定位 | 组织与项目生命周期治理、平台注册、域名规则、迁移、备份、SQL 终端 | 业务后端数据面读写、用户管理、RAG 知识库、Memory、模型网关与可观测上报 | 浏览器端用户登录会话、受 RLS 保护的数据读写与 Realtime 实时订阅 |
| 鉴权凭据 | 管理员 Session Cookie / 短期 JWT(SQL 场景支持项目 API Key) | 项目 API Key(X-Appwrite-Key,跳过 RLS) | 终端用户 Session Cookie / JWT(严格执行 RLS 行级权限) |
| 独占能力 | Organizations、Projects.create/createKey/createPlatform、Proxy、Vcs、Migrations、Admin、Backups、Sql | Users.createToken(Custom Token 签发)及全量项目级服务端批处理 | Account 浏览器 OAuth 跳转登录、Realtime WebSocket 订阅(与 Console 共享实时能力) |
版本与 SDK 支持
已发布 npm 坐标固定为
agentbase-console-sdk@2.10.0(及内部镜像@alipay/agentbase-console-sdk@2.10.0),安装校验详见 ../integration.md。词库管理可通过 REST 接口操作(包括
/v1/lexicons、/v1/lexicons/{lexiconId}/entries、/v1/lexicons/{lexiconId}/preview、/v1/lexicons/{lexiconId}/import、/v1/lexicons/{lexiconId}/export、/v1/lexicons/{lexiconId}/references、/v1/knowledgebases/{knowledgeBaseId}/lexicons与/v1/agent-runtime/agents/{agentId}/lexicons);在已发布2.10.0npm 包中可直接通过client.call调用上述 REST 路径。
功能面导航(治理域 → 服务)
| 域 | 服务与方法要点 | 功能文档 |
|---|---|---|
| 组织 | Organizations:成员、账单地址、发票、充值、组织 Key、listUsageAggregates({ organizationId });由 new Organizations(client) 实例化 | ../organization.md、../usage.md |
| 项目生命周期 | Projects.create({ projectId, name, teamId, region: 'default', poolTag }) / get / update / delete / list | ../overview.md |
| 项目 Key 与平台 | projects.createKey(scope 小写点分串,secret 仅创建时可见)、createDevKey、createPlatform / listPlatforms(仅 Console Session)、updateOAuth2 | ../overview.md |
| 配额与限频 | 项目 projects.getQuotaLimits / updateQuotaLimits;账号 account.getQuotaLimits / updateQuotaLimits / deleteQuotaLimits(无 listLimitsProjects);/limits 经 client.call | ../limits.md |
| 三级用量 | sdk.forConsole.account / sdk.forConsole.projects 与独立 Organizations 服务的 listUsageAggregates()(最近 30 个 UTC 日) | ../usage.md |
| 项目资源面 | TablesDB / Sql / Sites / Functions / Storage / Messaging / Memory(含项目配置与回滚)/ Users / Teams / Tokens / LLMGateway(含用量)/ Webhooks / Graphql / Avatars / Locale / Health | 各功能页(../misc/webhooks.md 等) |
| SQL | Sql.query / Sql.execute(JS Console SDK 独有;Java / Python / Go Console 面见各自页说明) | ../databases/sql-proxy.md |
| 站点与域名 | Sites 全集 + Proxy 域名规则 + Domains | ../sites.md |
| 实时 | realtime.forProject(region, channels, cb) / realtime.forConsole(...) | ../realtime.md |
| 平台运维 | Admin / Backups / Activities / Health(含管理面队列检查) | ../misc/webhooks.md |
错误与边界
错误模型:
AppBaseException(code/type)。平台注册(
createPlatform)与组织查询等 Console-only 操作不能用项目 API Key;项目资源操作建议在setProject(应用项目)后进行。Console Session cookie 与 OAuth 测试 Session 相互隔离;JWT 短期有效,过期需重新签发。
示例指引
JavaScript Console 初始化与典型调用:../examples/javascript.md