Docs
文档目录

组织

这是什么 / 何时用

组织是 Agentbase 管理面的顶层协作单元:项目归属在组织下,成员与角色在组织上管理,组织级 API Key、计划 / 账单 / 用量也挂在组织维度。API 层的组织对应 canonical Team ID(teamId);Console 页面地址里的 organization-{organizationId} 是 Organization 公开 ID,两者可能不同,自动化时不要混用。何时用:搭建团队工作区、成员进出场、组织级凭据与账单/用量治理。

前置

使用骨架

  1. 创建组织:Console 或 Console SDK 创建组织(内部即创建 Team),得到 canonical teamId;页面地址为 {consoleOrigin}/console/organization-{teamId}。

  2. 成员与角色:向组织 Team 邀请成员(Teams.createMembership,支持 email / userId / phone),用 Teams.listMemberships / getMembership 查询,Teams.updateMembership 调整角色,Teams.updateMembershipStatus 处理接受/加入状态,Teams.deleteMembership 移除;成员操作留痕在 Teams.listLogs。

  3. 组织 API Key:Console SDK 的 Organizations service 提供组织 Key 的创建 / 列表 / 更新 / 删除(createKey / listKeys / getKey / updateKey / deleteKey)。注意:SDK 存在这些方法不代表目标实例一定开放对应路由;只有目标环境已通过受支持渠道交付了有效 Organization API Key 时才使用 Key 路径,否则用 Owner Session 或短期 Owner JWT(组织项目治理见 project-governance.md)。

  4. 计划与账单(托管环境):Organizations.getPlan / listInvoices / getInvoice / getInvoiceDownload、账单地址、积分与估算(getAvailableCredits / addCredit / estimationUpdatePlan 等)。

  5. 组织用量(2.6.0):organizations.listUsageAggregates({ organizationId }) 返回组织维度最近 30 个 UTC 日的标准 Meter 聚合;quantity: null 表示缺失,不得当 0。

  6. 能力查询:Organizations.getScopes、Organizations.listRegions 查询组织可用的 scope 与区域。

关键参数与返回

调用关键参数返回 / 说明
创建组织组织名称等组织对象(canonical Team ID、成员、计划等元数据)
Teams.createMembershipteamId、roles[]、email(可选) / userId(可选) / phone(可选)、url(可选;邀请跳转)、name(可选)Membership(含确认状态 confirm)
Organizations.createKey组织 ID、名称、scopes、过期等Key 元数据;secret 只在创建响应出现一次
Organizations.listUsageAggregatesorganizationIdMeterUsageList(range: '30d',四 Meter,带 complete/freshnessAt/reason)
Organizations.getScopes / listRegions组织 ID可用 scope 列表 / 可用 region(2.6.0 为 default)

错误与边界

SDK 类别差异

各语言调用示例

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

创建组织(Teams)

组织内部即 Team:Console SDK Teams.create 创建后 team.$id 即 canonical Team ID;REST 对应 POST /v1/teams。组织管理不经 Server / Client SDK。

import { Client, Account, Teams, ID } from 'agentbase-console-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)               // 必须包含 /v1
    .setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID!);    // 'console' 或环境实际 Console project ID
const account = new Account(client);
await account.createEmailPasswordSession({
    email: process.env.APPBASE_OWNER_EMAIL!,
    password: process.env.APPBASE_OWNER_PASSWORD!
});

const teams = new Teams(client);
const team = await teams.create({
    teamId: ID.unique(),
    name: 'Acme Inc'
});
// team.$id 即 canonical Team ID:页面地址 {consoleOrigin}/console/organization-{teamId};
// 后续自动化一律用 team.$id,不要用页面公开 organizationId

成员与角色(Teams)

Console SDK 管理组织 Team 成员(组织管理不经 Server / Client SDK);REST 对应 teams 域端点(teams.read / teams.write scope)。

import { Client, Account, Teams } from 'agentbase-console-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)               // 必须包含 /v1
    .setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID!);    // 'console' 或环境实际 Console project ID
const account = new Account(client);
await account.createEmailPasswordSession({
    email: process.env.APPBASE_OWNER_EMAIL!,                  // 当前账号需具备组织管理角色
    password: process.env.APPBASE_OWNER_PASSWORD!
});

const teams = new Teams(client);
const membership = await teams.createMembership({
    teamId: '<canonical-team-id>',        // canonical Team ID,不是页面公开 organizationId
    roles: ['developer'],
    email: 'bob@example.com',             // email / userId / phone 至少提供其一
    url: 'https://<console-origin>/join', // 邀请回跳 URL(可选)
    name: 'Bob'
});
// membership.confirm=false 表示待对方确认;后续 updateMembership 调角色、updateMembershipStatus
// 处理确认、deleteMembership 移除、listMemberships / getMembership 查询,留痕见 Teams.listLogs

组织 API Key(Organizations)

仅 JS Console SDK 提供(Java Console SDK 无 Organizations service,REST 亦无文档化端点);SDK 存在这些方法不代表目标实例开放对应路由。

const organizations = new Organizations(client);   // client 初始化与认证见上一卡

const key = await organizations.createKey({
    organizationId: '<canonical-team-id>',
    name: 'ci-automation',
    scopes: ['projects.read', 'projects.write']
});
console.log(key.secret);   // secret 只在创建响应出现一次,立即入库保存
// 轮换面:listKeys / getKey / updateKey / deleteKey;过期等其余参数以 SDK 方法签名为准

计划与账单(托管环境)

托管环境的计划 / 账单 / 积分能力仅 JS Console SDK 提供(Java Console SDK 无 Organizations service,REST 无文档化端点);账单地址与发票下载也可在 Console 页面操作。

const organizations = new Organizations(client);   // client 初始化与认证见上一卡

// 计划与账单方法面(参数以 agentbase-console-sdk 方法签名为准):
// organizations.getPlan({ organizationId })                 // 当前计划
// organizations.listInvoices({ organizationId })            // 发票列表
// organizations.getInvoice / getInvoiceDownload             // 单张发票与下载
// organizations.getAvailableCredits({ organizationId })     // 可用积分
// organizations.addCredit / estimationUpdatePlan            // 充值 / 变更估算

组织用量聚合(2.6.0)

organizations.listUsageAggregates 返回组织维度最近 30 个 UTC 日的标准 Meter 聚合(组织用量属管理面,仅 Console SDK 与管理 REST 承载)。

const usage = await organizations.listUsageAggregates({ organizationId: '<organizationId>' });
// 返回 MeterUsageList:range '30d',四个 Meter(storage_bytes / bandwidth_bytes / users_total / function_executions)
// quantity: null 表示缺失,不得当 0;complete=false 表示数据未闭合

能力查询(scopes / regions)

scope 与区域查询仅 JS Console SDK 提供(Java Console SDK 无 Organizations service,REST 亦无文档化端点);入参为组织 ID。

// organizations.getScopes:入参组织 ID,返回组织可用 scope 列表
// organizations.listRegions:入参组织 ID,2.6.0 返回 default 区域
// 两者入参形态(位置参数或对象)以 agentbase-console-sdk 方法签名为准

示例指引