scenario-team-admin

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scenario Team Administration

Scenario团队管理

Overview

概述

Enterprise teams govern Scenario from the same agent that generates on it: which models anyone may run, who is on the team and in which projects, how much each member may spend, and which API keys exist with which roles. Every tool here is catalog-only:
scenario_tools_search
returns the schema and lane, and
scenario_tool_execute_read
/
write
/
delete
runs it with
{name, parameters}
, scope ids inside
parameters
(see the
scenario
skill). Two facts decide most failures before any argument does: the identity behind the call, since team-level writes need a human team admin over OAuth and refuse API keys, and the list mode the team runs, since the same model-access edit means the opposite thing in blocklist and allowlist mode.
teams_list
already tells you both: each team row carries
modelsManagement
, its model lists,
plan
, and
context.userRole
. A credential that reaches one team and one project has its scope; more than one is a stop-and-list, per the
scenario
skill. If a sibling skill named here is missing from your available skills, ask the user to install it (
npx skills add scenario-labs/skills --skill <name>
); unattended, proceed from tool schemas and flag the gap.
企业团队可通过用于生成内容的同一个Agent来治理Scenario:包括谁可以运行哪些模型、团队成员名单及所属项目、每位成员的消费额度,以及存在哪些角色的API密钥。此处的所有工具均为目录式:
scenario_tools_search
返回schema和通道(lane),
scenario_tool_execute_read
/
write
/
delete
通过
{name, parameters}
执行工具,权限范围ID位于
parameters
中(参见
scenario
skill)。大多数故障在传入参数前就由两个因素决定:一是调用背后的身份——团队级别的写入操作需要通过OAuth认证的人类团队管理员执行,拒绝API密钥调用;二是团队运行的列表模式——同一项模型访问编辑操作在blocklist和allowlist模式下的效果完全相反。
teams_list
可以同时告知这两个信息:每个团队条目都包含
modelsManagement
(其模型列表)、
plan
和
context.userRole
。仅关联一个团队和一个项目的凭证具有明确的权限范围;若关联多个,则需按
scenario
skill的要求暂停并列出范围。如果你的可用技能中缺少此处提到的关联技能,请让用户安装(
npx skills add scenario-labs/skills --skill <name>
);在无人值守模式下,可基于工具schema继续操作并标记缺失的技能。

Quick reference

快速参考

TaskToolLaneNotes
Read model access
model_access_get
readMode plus the team's active list;
project_id
adds that project's list alongside it
Change model access
model_access_update
write
level
team
or
project
; exactly one of
add_models
,
remove_models
Team roster
team_members_list
readMembers and pending invitations
Invite
team_members_add
write1 to 32
emails
,
role
, optional
project_ids
joined on acceptance
Roles and spend caps
team_members_update
write
member_ids
1 to 32;
role
and/or
max_consumption
Remove from the team
team_members_remove
deleteAlso withdraws invitations; access ends immediately
Project roster
project_members_list
,
_add
,
_update
,
_remove
read, write, deleteRoles
admin
(Owner),
editor
(Contributor),
reader
(Viewer)
API keys
api_keys_list
,
api_key_get
,
api_key_update
,
api_key_delete
read, write, deleteProject scope;
api_key_create
returns the portal link and nothing else
Who spent what
usage
read (default tools)Per-user and per-model consumption in the default response
任务工具通道说明
读取模型访问权限
model_access_get
read返回模式及团队的生效列表;传入
project_id
可同时显示对应项目的列表
修改模型访问权限
model_access_update
write
level
为
team
或
project
;必须传入
add_models
或
remove_models
中的一个
团队成员名单
team_members_list
read成员及待处理邀请
邀请成员
team_members_add
write1至32个
emails
、
role
,可选
project_ids
(接受邀请后自动加入)
角色与消费上限
team_members_update
write
member_ids
数量1至32;可设置
role
和/或
max_consumption
移除团队成员
team_members_remove
delete同时撤回邀请;访问权限立即终止
项目成员名单
project_members_list
、
_add
、
_update
、
_remove
read、write、delete角色包括
admin
(所有者)、
editor
(贡献者)、
reader
(查看者)
API密钥
api_keys_list
、
api_key_get
、
api_key_update
、
api_key_delete
read、write、delete项目范围;
api_key_create
仅返回门户链接,无其他内容
消费统计
usage
read(默认工具)默认返回按用户和按模型的消耗数据

Model access: read the mode before editing

模型访问:编辑前先读取模式

model_access_get
returns
models_management
and only the mode's active list; the inactive stored list is never surfaced. In blocklist mode (the default) every catalog model is available except those on the team or project blocklist, and the two lists block as a union. In allowlist mode a model is available only when it sits on both the team and the project allowlist; a project with an empty allowlist denies every model, and a project with no allowlist configured falls back to the team list.
model_access_update
edits whichever list the mode makes active, so
add_models
blocks in blocklist mode and allows in allowlist mode: read the mode first, every time. Switching the mode is not available through MCP; it lives in the web app's team settings, so locking a team down to an approved set starts with the user flipping to allowlist there. Unattended, that switch is a stop-and-report: log that the lock waits on it and the exact calls that follow, and take the blocklist-safe partial (blocking the named unwanted models at project level), saying that other projects stay open. Narrowing a list the credential can edit is in scope when the task states the target set:
remove_models
runs after the adds succeed, so the list never ends empty.
level: "team"
needs a team admin over OAuth, and the server refuses API keys on that endpoint.
level: "project"
takes the projects to edit in
projects
(1 to 200) and needs the admin role on every one of them: one unauthorized project fails the whole request and nothing updates, and a single-project key can only edit its own project's list.
project_id
on the call is tenant context for OAuth sessions, never the target. In allowlist mode a project admin can add only models already on the team allowlist (a project list narrows the catalog, never widens it), removing a base model from a team allowlist cascade-removes the trained models built on it, and a team-level add validates every id, one unknown id failing the whole call.
updated: false
means the diff was a no-op, not an error. A blocked model disappears from what members can run, and the error a member sees when running one anyway is a restriction, not moderation (see
scenario-moderation
).
model_access_get
返回
models_management
及当前模式下的生效列表;未启用的存储列表不会对外展示。在blocklist模式(默认)下,目录中的所有模型都可用,除了团队或项目blocklist中的模型,两个列表的封禁范围取并集。在allowlist模式下,模型只有同时存在于团队和项目的allowlist中才可用;如果项目的allowlist为空,则拒绝所有模型;如果项目未配置allowlist,则回退到团队列表。
model_access_update
会编辑当前模式下的生效列表,因此
add_models
在blocklist模式下是封禁模型,在allowlist模式下是放行模型:每次操作前务必先读取模式。模式切换无法通过MCP完成,需要在Web应用的团队设置中操作,因此若要将团队锁定为仅使用批准的模型集,需先由用户在Web端切换到allowlist模式。在无人值守模式下,遇到需要切换模式的情况应暂停并报告:记录锁定操作需等待模式切换,以及后续要执行的具体调用,同时先执行blocklist模式下的安全部分操作(在项目层级封禁指定的不需要的模型),并说明其他项目仍保持开放。当任务明确指定目标模型集时,收窄凭证可编辑的列表属于操作范围:
remove_models
会在添加操作成功后执行,因此列表永远不会为空。
level: "team"
需要通过OAuth认证的团队管理员权限,服务器会拒绝该端点的API密钥调用。
level: "project"
需在
projects
参数中传入要编辑的项目(1至200个),且需要在每个项目上都拥有admin角色:只要有一个项目未授权,整个请求就会失败,所有项目都不会更新;单项目密钥只能编辑自身项目的列表。调用中的
project_id
是OAuth会话的租户上下文,不是操作目标。
在allowlist模式下,项目管理员只能添加已在团队allowlist中的模型(项目列表只能收窄目录范围,不能扩大);从团队allowlist中移除基础模型会级联移除基于该模型训练的所有模型;团队级别的添加操作会校验每个ID,只要有一个未知ID就会导致整个调用失败。
updated: false
表示差异为空,操作无变化,不是错误。被封禁的模型会从成员可运行的列表中消失,成员若尝试运行被封禁的模型,收到的错误是权限限制提示,而非内容审核提示(参见
scenario-moderation
)。

Members and spend caps

成员与消费上限

team_members_update
takes
member_ids
from
team_members_list
and sets
role
(
admin
or
member
),
max_consumption
, or both. The cap is in Creative Units over the current billing period: a value of zero or more caps,
-1
is unlimited, and
null
clears the per-member override so the team-wide default applies. Roles can be set by a team admin over OAuth or a team-scoped API key with the
team.members.manage
scope; caps need a real team admin, and a key that tries is refused per member. Demoting the last admin fails server-side. The bulk member tools process one row at a time and report an outcome per member; a response with
status: "partial"
is finished by calling again with its
remaining
list.
team_members_add
invites 1 to 32 emails at
role
(default
member
) and joins them to
project_ids
on acceptance; outcomes are
invited
,
failed
, or
skipped
with the reason (already a member, already invited, seat limit reached).
project_id
on the call grants nothing. Like role changes, inviting takes a team admin over OAuth or a team-scoped key with
team.members.manage
; a project-scoped key gets a permission error. A pending invitation carries no member id, so its cap waits for acceptance.
project_members_add
takes people already on the team, as user ids or emails (emails need
team_id
to resolve), with a required project role.
Removal is the delete lane and immediate:
team_members_remove
ends the person's access everywhere and withdraws pending invitations,
project_members_remove
leaves team membership and other projects untouched. List first, confirm the exact names with the user, then remove; unattended, remove only the members the task instructions name.
team_members_update
接收来自
team_members_list
的
member_ids
,可设置
role
(
admin
或
member
)、
max_consumption
,或同时设置两者。消费上限以当前计费周期内的Creative Unit为单位:大于等于0的值表示上限,
-1
表示无限制,
null
表示清除成员级别的覆盖设置,使用团队默认值。
角色设置可由通过OAuth认证的团队管理员执行,或由具有
team.members.manage
权限的团队范围API密钥执行;但消费上限设置必须由真实的团队管理员操作,使用API密钥尝试设置会被逐成员拒绝。降级最后一个admin的操作会在服务端失败。批量成员工具每次处理一条记录,并逐成员返回结果;若响应中
status: "partial"
,可使用返回的
remaining
列表再次调用以完成剩余操作。
team_members_add
可邀请1至32个邮箱,设置
role
(默认
member
),并在对方接受邀请后将其加入
project_ids
指定的项目;操作结果包括
invited
、
failed
或
skipped
,并附带原因(已是成员、已被邀请、席位已满)。调用中的
project_id
不会授予任何权限。与角色变更类似,邀请操作需要通过OAuth认证的团队管理员,或具有
team.members.manage
权限的团队范围密钥;项目范围的密钥调用会返回权限错误。待处理的邀请没有成员ID,因此其消费上限需等对方接受邀请后才能设置。
project_members_add
用于添加已在团队中的人员,可传入用户ID或邮箱(邮箱需要
team_id
来解析),并必须指定项目角色。
移除操作属于delete通道,且立即生效:
team_members_remove
会终止用户在所有地方的访问权限,并撤回待处理的邀请;
project_members_remove
则不会影响用户的团队成员身份和其他项目的权限。操作前请先列出名单,与用户确认具体人员后再移除;在无人值守模式下,仅移除任务指令中明确指定的成员。

API keys

API密钥

api_keys_list
and
api_key_get
are project-scoped and return each key's
id
,
api_key_id
, name, status, scope, role, projects, and creation date, plus a
manage_keys_url
; team-scoped keys are not attached to projects and never appear here, only in the portal.
api_key_update
changes a key's
role
to
admin
,
editor
,
reader
, or a custom
;
-separated scope list (the reference's example is
assets.read;models.run
); name, status, and usage limits are portal-only, and a limit takes an Enterprise plan and a human admin. Creation is deliberately not an MCP operation:
api_key_create
returns the portal link, the secret is shown once there, and it never passes through the conversation (the
scenario
skill's rule on secrets holds here).
api_key_delete
takes the key as
key_id
(either the
id
or the
api_key_id
from the listing), cannot be undone, needs a project admin, and refuses the key the current session is authenticated with: list, confirm the exact key with the user, then delete; unattended, delete only a key the task instructions name and exactly one key matches.
api_keys_list
和
api_key_get
是项目范围的接口,返回每个密钥的
id
、
api_key_id
、名称、状态、权限范围、角色、所属项目和创建日期,以及
manage_keys_url
;团队范围的密钥不关联项目,因此不会出现在此处,仅在门户中可见。
api_key_update
可将密钥的
role
修改为
admin
、
editor
、
reader
,或自定义的分号分隔权限列表(参考示例为
assets.read;models.run
);密钥名称、状态和使用限制仅能在门户中修改,且使用限制需要企业版计划和人类管理员权限。
密钥创建特意不设为MCP操作:
api_key_create
仅返回门户链接,密钥明文仅在门户中显示一次,永远不会经过对话传输(
scenario
skill的密钥规则在此处同样适用)。
api_key_delete
接收
key_id
作为参数(可以是列表中的
id
或
api_key_id
),操作不可撤销,需要项目admin权限,且会拒绝删除当前会话认证使用的密钥:操作前请先列出密钥,与用户确认具体密钥后再删除;在无人值守模式下,仅删除任务指令中明确指定且匹配结果唯一的密钥。

Who spent what

消费统计

usage
is in the default toolset and returns a summary by default: headline CU totals, per-user consumption, per-model CU and job counts sorted descending, and per-asset-kind counts, bounded by
start_date
and
end_date
(ISO dates);
project_id
filters the figures, so a single-project credential ranks spend inside that project, not across the team. An undated call returns project-lifetime figures, so always pass the range:
totals
and the per-user
consumption
rows (
userId
,
total
) follow
start_date
and
end_date
, and a member ranking comes from those rows. The per-day series (
include: ["usages.daily"]
per usage type,
["modelUsages.daily"]
per model) carry no user dimension;
nsfwUsages
adds moderation totals and
activity
the raw event log. Never attribute spend by adding up your own calls. Read consumption before setting caps: both are in CU over the billing period, and a cap below what a member has already spent stops them at once.
usage
属于默认工具集,默认返回汇总数据:CU总消耗、按用户统计的消耗、按模型统计的CU和任务数(降序排列)、按资产类型统计的数量,数据范围由
start_date
和
end_date
(ISO格式日期)限定;传入
project_id
可过滤数据,因此单项目凭证只能统计该项目内的消费排名,而非全团队。
未传入日期的调用会返回项目全生命周期的数据,因此请务必传入时间范围:
totals
和按用户的
consumption
行(
userId
、
total
)都基于
start_date
和
end_date
,成员排名可从这些行中得出。每日数据系列(按使用类型传入
include: ["usages.daily"]
,按模型传入
["modelUsages.daily"]
)不包含用户维度;
nsfwUsages
会返回内容审核统计,
activity
返回原始事件日志。
绝对不要通过累加自身调用的方式统计消费。设置消费上限前请先读取消耗数据:两者都以计费周期内的CU为单位,如果上限低于成员已消耗的额度,会立即停止其使用权限。

Worked example: lock a project to approved models and cap the contractors

示例:将项目锁定为批准的模型集,并设置外包人员消费上限

  1. scenario_tools_search
    with
    query="model access"
    , then
    query="team members"
    : schemas and lanes for the calls below.
  2. scenario_tool_execute_read
    with
    name: "model_access_get"
    ,
    parameters: {"team_id", "project_id"}
    . The team is in blocklist mode, so "only these three models" is not expressible: tell the user to switch the team to allowlist in the web app's team settings, then re-read; unattended, log the gap with the calls below and stop, blocking any models the task names as unwanted at project level in the meantime.
  3. In allowlist mode, the team list first:
    scenario_tool_execute_write
    with
    name: "model_access_update"
    ,
    parameters: {"team_id", "project_id", "level": "team", "add_models": [<the three ids>]}
    ; this is the call that needs the caller to be a team admin over OAuth (
    context.userRole
    on the
    teams_list
    row says whether they are). Then the project:
    level: "project"
    ,
    projects: [<project id>]
    , the same
    add_models
    , which succeeds only because the team list now carries them.
  4. scenario_tool_execute_read
    with
    name: "team_members_list"
    : the two contractors' member ids.
    scenario_tool_execute_write
    with
    name: "team_members_update"
    ,
    parameters: {"team_id", "project_id", "member_ids": [<two ids>], "max_consumption": 2000}
    . On
    status: "partial"
    , call again with
    remaining
    .
  5. scenario_tool_execute_read
    with
    name: "api_keys_list"
    for the project. A render-farm key running as
    admin
    is narrowed with
    api_key_update
    ,
    role: "assets.read;models.run"
    , and any key nobody can account for is deleted only after the user confirms it by name.
  6. Confirm:
    model_access_get
    with
    project_id
    shows the project list
    configured
    with the three ids; later in the period,
    usage
    with the date range and
    include: ["usages.daily"]
    shows the contractors' consumption against the cap.
  1. 调用
    scenario_tools_search
    ,先传入
    query="model access"
    ,再传入
    query="team members"
    :获取后续调用所需的schema和通道信息。
  2. 调用
    scenario_tool_execute_read
    ,传入
    name: "model_access_get"
    ,
    parameters: {"team_id", "project_id"}
    。如果团队处于blocklist模式,则无法实现“仅允许这三个模型”的需求:告知用户需在Web应用的团队设置中将团队切换为allowlist模式,然后重新读取;在无人值守模式下,记录该限制及后续待执行的调用并暂停,同时先在项目层级封禁任务中指定的不需要的模型。
  3. 切换到allowlist模式后,先配置团队列表:调用
    scenario_tool_execute_write
    ,传入
    name: "model_access_update"
    ,
    parameters: {"team_id", "project_id", "level": "team", "add_models": [<三个模型ID>]}
    ;该调用需要调用者是通过OAuth认证的团队管理员(可通过
    teams_list
    条目中的
    context.userRole
    判断)。然后配置项目列表:
    level: "project"
    ,
    projects: [<项目ID>]
    ,传入相同的
    add_models
    ,只有团队列表已包含这些模型时,项目级操作才会成功。
  4. 调用
    scenario_tool_execute_read
    ,传入
    name: "team_members_list"
    :获取两位外包人员的成员ID。调用
    scenario_tool_execute_write
    ,传入
    name: "team_members_update"
    ,
    parameters: {"team_id", "project_id", "member_ids": [<两个ID>], "max_consumption": 2000}
    。如果返回
    status: "partial"
    ,使用
    remaining
    列表再次调用。
  5. 调用
    scenario_tool_execute_read
    ,传入
    name: "api_keys_list"
    获取项目的密钥列表。对于一个以
    admin
    身份运行的渲染农场密钥,使用
    api_key_update
    将其权限收窄为
    role: "assets.read;models.run"
    ;对于无人认领的密钥,需由用户按名称确认后再删除。
  6. 验证:调用
    model_access_get
    并传入
    project_id
    ,确认项目列表已
    configured
    这三个ID;在计费周期后期,调用
    usage
    并传入日期范围和
    include: ["usages.daily"]
    ,查看外包人员的消耗与上限的对比。

Common mistakes

常见错误

  • Editing model access without reading
    models_management
    :
    add_models
    blocks in one mode and allows in the other.
  • Trying to lock a team to a short list while in blocklist mode: that is an allowlist job, and the mode switch is a web-app setting.
  • Team-level writes through an API key: refused by design; the caller is a human team admin over OAuth.
  • arguments
    instead of
    parameters
    on the executor: dropped silently and surfaced as a scope error (see
    scenario
    ).
  • Setting caps with a
    team.members.manage
    key: it can change roles, not caps.
  • Reading an undated
    usage
    call as the period's spend: its figures are project-lifetime. Pass
    start_date
    and
    end_date
    , rank members from the dated
    consumption
    rows, and use the per-day series only to cross-check a period total, since it carries no user dimension.
  • Expecting
    api_keys_list
    to show team-scoped keys: they exist only in the portal.
  • Passing
    project_id
    to
    team_members_add
    to grant project access:
    project_ids
    grants;
    project_id
    is tenant context.
  • Deleting a key or removing a member without listing and confirming first: the delete lane is irreversible, and
    api_key_delete
    refuses the session's own key.
  • 未读取
    models_management
    就编辑模型访问权限:
    add_models
    在两种模式下的作用完全相反(一种是封禁,一种是放行)。
  • 在blocklist模式下尝试将团队锁定为少量模型:这是allowlist模式的功能,模式切换需在Web应用中设置。
  • 通过API密钥执行团队级写入操作:这是设计上的拒绝规则,必须由通过OAuth认证的人类团队管理员调用。
  • 执行器中使用
    arguments
    而非
    parameters
    :参数会被静默丢弃,并表现为权限范围错误(参见
    scenario
    skill)。
  • 使用具有
    team.members.manage
    权限的密钥设置消费上限:该密钥只能修改角色,不能设置上限。
  • 将未传日期的
    usage
    调用结果当作当期消费:其数据是项目全生命周期的。请传入
    start_date
    和
    end_date
    ,从带日期的
    consumption
    行中得出成员排名,每日数据系列仅用于交叉验证周期总消耗,因为它不包含用户维度。
  • 期望
    api_keys_list
    显示团队范围的密钥:这类密钥仅在门户中存在。
  • 向
    team_members_add
    传入
    project_id
    来授予项目权限:授予项目权限的参数是
    project_ids
    ;
    project_id
    只是租户上下文。
  • 未先列出并确认就删除密钥或移除成员:delete通道的操作不可逆,且
    api_key_delete
    会拒绝删除当前会话使用的密钥。