AgentbaseDocs
文档目录

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 头

认证装载(三选一,互斥):

其他 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)
VcsGit 集成:installation、仓库发现、分支列表、仓库内容、外部部署状态回写
Migrations迁移任务(Appwrite/Firebase/Supabase/NHost/AppBase/CSV 导入导出):创建、报告、重试、删除;另有 SchemaMigration(基于 TablesDB 的表结构计划/执行助手)
Assistantassistant.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)管理与知识库绑定(源码树 packages/sdks/console-web 提供 Lexicons 类,或经 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、SqlUsers.createToken(Custom Token 签发)及全量项目级服务端批处理Account 浏览器 OAuth 跳转登录、Realtime WebSocket 订阅(与 Console 共享实时能力)

事实源与版本对齐说明

功能面导航(治理域 → 服务)

域服务与方法要点功能文档
组织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 等)
SQLSql.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

错误与边界

示例指引

事实源