scenario-team-admin

场景团队管理

概述

企业团队可以通过生成内容所用的同一个 Agent 管理 Scenario：任何人可以运行哪些模型、团队成员及其所在项目、每位成员的消费上限，以及有哪些 API 密钥和对应角色。这里的所有工具仅供目录查询：scenario_tools_search 返回架构和通道，scenario_tool_execute_read / write / delete 则使用 {name, parameters} 执行工具，作用域 ID 放在 parameters 中（参见 scenario 技能）。大多数失败在检查参数前就已由两个因素决定：调用者身份，因为团队级写入需要使用 OAuth 的人工团队管理员身份，并且不接受 API 密钥；以及团队使用的列表模式，因为在屏蔽列表模式和允许列表模式下，同一项模型访问权限编辑的含义恰好相反。teams_list 已包含这两类信息：每个团队行都带有 modelsManagement、模型列表、plan 和 context.userRole。凭证只覆盖一个团队和一个项目时，其作用域就是这两者；如果涉及多个团队或项目，则应停止并列出范围，参见 scenario 技能。如果此处提到的相关技能未包含在你可用的技能中，请让用户安装该技能（npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作并指出这一缺失。

快速参考

任务	工具	通道	备注
读取模型访问权限	model_access_get	读取	模式及团队当前列表；project_id 会同时添加该项目的列表
更改模型访问权限	model_access_update	写入	level 为 team 或 project；add_models、remove_models 必须且只能指定一个
团队成员名单	team_members_list	读取	成员和待处理的邀请
邀请	team_members_add	写入	emails 为 1 至 32 个，role，可选的 project_ids 会在接受邀请后关联
角色和消费上限	team_members_update	写入	member_ids 为 1 至 32 个；可设置 role 和/或 max_consumption
从团队中移除	team_members_remove	删除	也会撤回邀请；访问权限立即终止
项目成员名单	project_members_list、_add、_update、_remove	读取、写入、删除	角色 admin（所有者）、editor（贡献者）、reader（查看者）
API 密钥	api_keys_list、api_key_get、api_key_update、api_key_delete	读取、写入、删除	项目作用域；api_key_create 只返回门户链接
项目	project_get、project_create、project_update、project_delete	读取、写入、写入、删除	创建需要使用 OAuth 的团队管理员身份，并计入计划的项目数量上限
谁消费了什么	usage	读取（默认工具）	默认响应中包含按用户和模型统计的消费情况

模型访问：编辑前先查看模式

model_access_get 会返回 models_management 和仅当前模式的有效列表；非当前模式下存储的列表不会显示。在封锁名单模式（默认）下，除团队或项目封锁名单上的模型外，目录中的所有模型都可用，两个列表的封锁规则取并集。在允许名单模式下，只有同时出现在团队和项目允许名单上的模型才可用；项目允许名单为空时会拒绝所有模型，项目未配置允许名单时则回退到团队列表。

model_access_update 会编辑由当前模式决定的列表，因此在封锁名单模式下，add_models 会封锁模型；在允许名单模式下，则会允许模型：每次操作前都要先读取模式。无法通过 MCP 切换模式；此设置位于 Web 应用的团队设置中，因此要将团队限制为一组获批模型，用户必须先在那里切换到允许名单模式。若无人值守，这项切换就意味着停止并报告：记录该限制仍待切换，以及后续要执行的确切调用，并采取封锁名单模式下安全的部分操作（在项目级别封锁指定的不需要的模型），同时说明其他项目仍保持开放。如果任务明确指定了目标集合，则可以收窄凭证有权编辑的列表：remove_models 会在添加成功后执行，因此列表不会变空。 level: "team" 需要使用 OAuth 并具备团队管理员权限，且服务会拒绝该端点上的 API 密钥。level: "project" 通过 projects 指定要编辑的项目（1 到 200 个），并且需要在每个项目上都具备管理员角色：只要有一个项目未获授权，整个请求就会失败且不会更新任何内容；单项目密钥只能编辑其自身项目的列表。调用中的 project_id 是 OAuth 会话的租户上下文，绝不是目标项目。在允许名单模式下，项目管理员只能添加已在团队允许名单中的模型（项目列表只能收窄目录，不能扩大范围）；从团队允许名单中移除基础模型会连带移除基于它构建的训练模型；团队级别的添加会验证每个 ID，任何一个 ID 未知都会导致整个调用失败。updated: false 表示差异为空操作，并非错误。被封锁的模型将不再出现在成员可运行的模型中；成员尝试运行这类模型时看到的错误属于访问限制，而非内容审核（参见 scenario-moderation）。

成员与支出上限

team_members_update 接受来自 team_members_list 的 member_ids，并设置 role（admin 或 member）、max_consumption，或同时设置两者。上限以当前计费周期内的 Creative Units 为单位： 值为零或更大表示设置上限，-1 表示不设上限，null 会清除该成员的单独覆盖值，改用 团队默认值。团队管理员可通过 OAuth 或具有 team.members.manage 范围的团队级 API 密钥设置 角色；设置上限则需要真正的团队管理员，密钥尝试设置时会被逐个拒绝。降级最后一位管理员会在 服务端失败。批量成员工具逐行处理，并逐个成员报告结果；如果响应的 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 解析），并且必须指定项目角色。

移除操作会删除访问权限并立即生效：team_members_remove 会终止该人员对所有资源的访问并撤回 待处理的邀请；project_members_remove 则不会影响团队成员身份和其他项目。先列出成员，再向用户 确认准确姓名，然后移除；在无人监督的情况下，只移除任务说明中指定的成员。

API 密钥

api_keys_list 和 api_key_get 的作用范围限定于项目，会返回每个密钥的 id、api_key_id、名称、 状态、范围、角色、项目和创建日期，以及 manage_keys_url；团队级密钥不关联任何项目，因此不会 显示在这里，只能在门户中查看。api_key_update 可将密钥的 role 更改为 admin、editor、 reader，或自定义的、以 ; 分隔的范围列表（参考示例为 assets.read;models.run）；名称、状态 和用量限制只能在门户中设置，且设置用量限制需要 Enterprise 计划和人工管理员。创建密钥特意 不作为 MCP 操作提供：api_key_create 会返回门户链接，密钥只会在那里显示一次，绝不会经过对话 传递（此处同样遵守 scenario 技能关于密钥的规则）。api_key_delete 使用 key_id 指定密钥 （可使用列表中的 id 或 api_key_id），删除后无法撤销，需要项目管理员权限，并且会拒绝删除 当前会话用于身份验证的密钥：先列出密钥，向用户确认准确密钥，然后删除；在无人监督的情况下， 只删除任务说明中指定且仅有一个匹配项的密钥。

项目

projects_list（默认工具集）用于查找现有项目；只有找不到匹配项时才创建。 project_create 需要 team_id、name 和 privacy_mode；描述需通过后续的 project_update 设置。调用时需要通过 OAuth 授权的人类团队管理员（不接受 API 密钥），并会占用 套餐的项目限额，达到限额后调用会被拒绝：报告限额，切勿删除项目腾出空间。如果调用成功，从此将返回的 project.id 作为 project_id 传入。如果团队没有项目，API 会先创建一个默认项目，即使调用被拒绝，该项目也会保留：之后检查 projects_list，并提议使用 project_update 为其重命名，而不是保留两个项目（无人值守时：报告情况，不做任何更改）。

• 隐私。 在 project_create 或 project_update 中设置 privacy_mode: true，会限制非管理员成员只能查看自己创建的资产和模型；项目管理员和团队管理员仍可查看所有内容。关闭该设置后，所有成员都能查看所有内容：请先向用户确认；无人值守时，仅当任务说明明确要求时才执行。
• 重命名。 project_update 只会更改传入的字段：name、description（最多 2,000 个字符）、privacy_mode、avatar_asset_id。访问权限、模型列表和信用额度上限请使用上述工具或 Web 应用管理。
• 删除。 project_delete 通过删除专用通道执行，操作不可撤销，并会一并删除该项目的模型、生成记录、API 密钥和记忆。请先通过 project_get 确认项目名称和 ID。调用时使用 project_id 指定目标；只要还有其他人拥有该项目的角色，或仍关联有密钥，删除请求就会被拒绝：报告仍留在项目中的人员并询问用户；未经单独确认，切勿移除成员或删除密钥来解除限制。创建者默认以管理员身份加入（auto_join），因此其他人无法删除该项目。无人值守时，仅删除任务说明中指定且恰好只有一个匹配项的项目；若请求被拒绝，则报告情况并停止。

谁花了多少

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 计量，若限额低于某位成员已经花费的数量，该成员会立即受到限制。

操作示例：将项目限制为已批准的模型，并为承包商设置消费上限

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"}。团队处于黑名单模式，因此无法表达“仅允许这三个模型”：告知用户在 Web 应用的团队设置中将团队切换为白名单模式，然后重新读取；若无人值守，则通过下文的调用记录这一限制并停止操作，同时暂时在项目级别屏蔽任务指定为不需要的任何模型。
3. 在白名单模式下，先更新团队列表：使用 scenario_tool_execute_write，参数为 name: "model_access_update"、 parameters: {"team_id", "project_id", "level": "team", "add_models": [<the three ids>]}；此调用要求调用方通过 OAuth 具备团队管理员权限（teams_list 行中的 context.userRole 会显示是否具备该权限）。然后更新项目：设置 level: "project"、 projects: [<project 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": [<two ids>], "max_consumption": 2000}。若返回 status: "partial"，则使用 remaining 再次调用。
5. 使用 scenario_tool_execute_read，参数为 name: "api_keys_list"，查看该项目的 API 密钥。以 admin 身份运行的渲染农场密钥，应使用 api_key_update 将其权限收窄为 role: "assets.read;models.run"；对于无人能说明用途的密钥，只有在用户按名称确认后才能删除。
6. 确认：调用 model_access_get 并提供 project_id，确认项目列表的状态为 configured，且包含这三个 ID；在本周期稍后，调用 usage 并提供日期范围和 include: ["usages.daily"]，查看承包商相对于消费上限的用量。

常见错误

• 未先读取 models_management 就修改模型访问权限：add_models 在一种模式下会屏蔽模型，在另一种模式下则会允许模型。
• 在黑名单模式下尝试将团队限制为一个较短的列表：这应通过白名单模式实现，而模式切换属于 Web 应用设置。
• 通过 API 密钥进行团队级写入：此操作按设计会被拒绝；调用方必须是通过 OAuth 认证的团队管理员。
• 在执行器中使用 arguments 而非 parameters：该参数会被静默丢弃，并显示为作用域错误（参见 scenario）。
• 使用 team.members.manage 密钥设置消费上限：它可以更改角色，但不能设置消费上限。
• 将未指定日期的 usage 调用结果当作本周期支出：其中数据是项目整个生命周期的累计值。传入 start_date 和 end_date，根据带日期的 consumption 行对成员排序，并仅将每日序列用于交叉核对周期总额，因为该序列不包含用户维度。
• 预期 api_keys_list 会显示团队级密钥：这类密钥只存在于门户中。
• 通过向 team_members_add 传入 project_id 来授予项目访问权限：应使用 project_ids 授予权限；project_id 是租户上下文。
• 未先列出并确认就删除密钥或移除成员：删除通道的操作不可逆，而且 api_key_delete 会拒绝删除当前会话使用的密钥。