scenario-admin-analytics

Scenario 管理分析

概述

将 Scenario MCP 使用数据转化为答案、CSV、Markdown、带图表的 PDF 或离线仪表盘。所有 Scenario 数据收集均通过 MCP 完成。报告脚本不得直接调用 API、SDK，不得抓取浏览器数据，也不得包含凭据。使用 scenario 技能进行连接设置。如果此处提到的某项同级技能不在你可用的技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若以无人值守方式运行，则根据工具架构继续操作，并指出这一缺失。

通过 teams_list 查找客户，并在需要时使用 projects_list({team_id})。沿用用户选定的范围。如果有多个名称匹配，请根据发现的选项询问用户；若以无人值守方式运行，则使用任务中明确指定的团队 / 项目 ID 对，否则停止并列出选项。绝不要默默选择第一个。对于整个组织范围的请求，请使用 scope:"team"，并提供一个可访问的上下文项目。这仅涵盖凭据可访问的项目，不会授予额外访问权限。对于单个项目，请使用 scope:"project"（默认值）；project_id 提供身份验证上下文和默认分析筛选条件。project_ids 用于选择该团队内的其他项目，且不能与 scope:"team" 同时使用。对选定的 ID 去重。不要将团队总计与其项目小计相加，也不要汇总各项目的独立用户数。

快速参考

问题	MCP 用量数据	计算方式
排名前三的模型	modelUsages	按 totalCU 排序查看 CU，或按 totalJobs 排序查看频次；两者都展示。
三个月内所有模型的 CU	添加 modelUsages.daily	导出每个模型，并按 UTC 月份对时间桶分组。
谁消耗的 CU 最多？	consumption、entities	按 value 排名；将 userId 与 entities.users[].id 关联。
每位用户使用最多的模型	对每个 user_ids ID 重复调用限定范围的 usage	对每个响应中的模型排名；包含 CU 和任务数。
十个模型中排名前五的用户	相同的逐用户查询	先选出总体排名前十的模型，再分别列出每个模型中排名前五的用户。
解释差异	usages.daily、activity	检查已记录的证据；如需完整活动记录，沿 activityPagination.nextOffset 一直获取，直到为 null。

缺少或架构过期时，使用 scenario_tools_search({query:"usage",limit:1}) 探查当前架构。通常直接调用可见的 usage。如果目录中只有工具目录项，则使用 scenario_tool_execute_read({name:"usage",parameters:{...}})，不要使用 arguments。部署后，主机可能仍保留旧的直接调用签名：如果最新目录显示存在缺失字段，请使用该读取执行器及其架构，或重新连接。旧的主机签名并不能证明某项功能不存在。调用应以公开的 usage 参考文档和实时目录为依据。

始终设置开始和结束日期。范围边界包含在内：完整的 3 月结束于 2026-03-31T23:59:59.999Z。说明时间桶使用 UTC。对于没有指定日期的问题，假设查询最近 30 个完整日，并说明时间范围；对于“最近三个月”，假设查询最近三个完整日历月，并说明时间范围。未指定日期的 API 调用默认查询 31 天，而非整个生命周期。当天的数据为暂定值。API 会强制执行其范围限制；不要臆造固定上限。如果 API 拒绝较大的范围，请拆分为不重叠的含端点区间，保留各区间的来源，并合并可加总的指标，但不要累加唯一身份数。

先获取摘要 JSON；生成报告时添加 include:["modelUsages.daily","entities"]。短时间范围的时间桶可能比每日更精细；按时间戳聚合后再按 UTC 日汇总，并剔除重复时间戳。activity 按批次分页，每批最多 100 条，使用 activity_offset；按照返回的下一个偏移量继续获取，不要猜测是否已获取完整。各活动页面会重复摘要：只计一次。常规排名不要使用活动记录。

记账与置信度

totals.totalCU 对 consumption[].value 求和，该值已扣除折扣。原始 consumption[].total 等于 value + discount，尚未扣除折扣。模型的 totalCU 对时间桶的 cost 求和，该值也已扣除折扣：切勿再次扣除 discount。API 密钥的 CU 是其中一部分。保留小数、零值、已全额折扣的行和负值。作业数衡量模型执行次数，而非成功生成的资产数。

验证回显的 scope 和日期；检查消耗量是否与总 CU 一致、时间桶是否与模型汇总一致，以及每位用户的模型汇总是否与未筛选的模型数据一致。scope 回显记录了已应用的筛选条件，但不能证明可以访问每个客户项目。直接说明已确认的范围和结果。不要在数据已验证后继续沿用旧的“消耗量未经验证”警告。

模型序列衡量生成活动，不包括单独记录的退款和非模型操作。因此，模型 CU 不一定等于总体消耗 CU。展示测得的差额，但不要断言其原因；如果有人要求解释，请检查用量部分。切勿将差额分配给模型、对重叠的用量类型类别求和，或用作业计费快照代替消耗量。如果检查失败，只暂不提供受影响的归因，报告确切的不匹配情况，并通过 MCP 调查。

对于用户/模型矩阵，每个 consumption[].userId 都要查询一次，且查询范围和时段保持一致，包括零值或负值行。切勿按比例合并相互独立的用户汇总和模型汇总。声称覆盖完整前，先核对所有模型 CU 和作业数；如果缺少身份信息，请调查 MCP 身份/活动元数据，不要凭空归因。通过返回的实体解析名称；如果缺少名称且接收者需要识别用户，请发现 team_members_list 并按 ID 关联其返回的电子邮件。内部保留稳定 ID，并在元数据能够识别 API 身份时将其区分开来。身份类型未知时，就保持未知。如果“使用最多”未指定指标，则按作业数排名并展示 CU；明确要求按 CU 排名时，则按 CU 排名。用稳定 ID 确定性地打破并列。Top-N 行同时包含这两个指标。

缓存、输出与环境回退

检查功能，而非产品名称。处理文件和 Python 时，请使用随附的 离线辅助脚本；Agent 负责收集 MCP 数据，脚本仅转换本地快照。阅读本地报告，了解数据封装、命令、依赖项、支持的筛选条件和缓存验证。仪表板模板采用了 Scenario 公共网站的暖纸色、炭灰色和陶土色配色，并使用本地字体回退方案。

按连接/账户命名空间、架构版本、团队、上下文项目、范围、所选项目/用户 ID、确切日期、分区和活动偏移量缓存。默认 TTL 为 1 小时；“刷新”会绕过缓存。用户/模型相关问题还需要新鲜的逐用户快照。保留原始检索时间戳；重新导入导出文件不会使其变成新数据。仅包含摘要的数据无法回答新的趋势问题。过期数据可用于明确标注的历史/离线回答。连接变更或核算/范围修正会使受影响的缓存失效。将私有快照保存在代码库之外，省略凭据和不必要的个人数据，并按要求删除。检索时间不代表上游数据是最新的。

使用临时执行环境时，请使用会话文件并说明其有效期。若有 MCP 但没有文件/执行能力，请直接回答小型问题，并提供 Markdown 或带围栏的 CSV；缓存仅限会话期间。如果无法生成 PDF，在支持的情况下提供可在本地打印的 HTML。绝不要声称未保存的文件或未渲染的 PDF 已存在。没有 MCP 时，使用提供的先前 MCP 快照，并注明其来源和时间，或说明连接不可用；不存在其他 Scenario 数据入口。

优先直接回答问题，并注明范围、日期、指标和检索时间。报告应包含已消耗 CU、模型任务、模型广度、集中度、趋势、身份排名和核对情况。辅助脚本支持按 CU/任务排序、配置每位用户的模型数、生成月度 CSV，以及在存在逐用户时间分桶时按用户/模型/日期筛选仪表板。整个期间的总体消耗和身份消耗应与筛选后的生成活动分开标注。刷新仪表板需要再次通过 MCP 获取数据；绝不要将客户数据作为此技能的一部分发布。

将不支持的请求列在“Not available through MCP”下，指出缺少的证据及任何受支持的替代方案。仅凭使用情况无法确定 ROI、节省的时间、工单归因、已交付输出的采用情况、历史符合条件的席位数量或留存率。权限错误、空结果、覆盖不完整和不支持的指标是不同的结果。

操作示例

2026 年 9 月 17 日的请求：“在所有项目中，按 CU 列出每位用户排名前五的模型及作业数量，提供三个月的 CSV 和 PDF。”

1. 确定团队和一个可访问的上下文项目。指定 6 月 1 日至 8 月 31 日，即最近三个完整日历月。如有需要，查询当前使用情况架构。
2. 检查精确缓存，包括用户覆盖情况。若未命中，则调用 usage({team_id:"<selected team>",project_id:"<context project>",scope:"team",start_date:"2026-06-01T00:00:00Z",end_date:"2026-08-31T23:59:59.999Z",include:["modelUsages.daily","entities"],response_format:"json"})。 占位符取自查询结果。
3. 对每个消费身份，使用 user_ids:["<returned identity ID>"] 重复该查询。保存每个完整的 {query,response,fetched_at} 封套。核验日期、范围和逐模型对账情况。不要将这些用户总数加到父级总数中。
4. 导入父级和每位用户的封套，然后使用 --rank-by cu --top-models-per-user 5 --pdf 生成结果。返回答案、完整的模型／月度 CSV 及每位用户的排名。之后关于前三名或按作业排名的问题，离线复用这些新鲜快照。
5. 将 PDF 的每一页渲染为图像，并在交付前检查版式；若无法进行视觉核验，应予以说明。使用已知总数测试仪表板筛选条件。客户资料保留在本地。

常见错误

• 将认证项目视为唯一可能的分析筛选条件，或假设团队范围会授予更广泛的权限。
• 使用不包含结束日期的日期范围、终身用量假设、过时架构或修复前缓存的数据。
• 重复扣除折扣、将 API 子集相加，或强行要求模型活动量等于总消耗量。
• 将猜测的退款原因、按比例关联的用户／模型数据或不完整历史记录报告为完整用量。
• 未提供分母就把 CU 称为“采用率”、公开客户快照，或使用非 MCP 备用方案。