iblai-vibe-agent-analytics

用途

iblai-vibe-agent-analytics 用于在 Next.js 应用中添加智能体的 Analytics 标签页（AgentAnalyticsTab）。该标签页是一个启动器（launcher），而不是仪表盘：它按单个智能体（per agent）范围，为每个分析报告显示一张卡片，点击卡片时调用宿主的 onNavigate(value)，由宿主路由到对应报告，并将范围限定到该智能体。报告本身是来自 /iblai-vibe-analytics 的 AnalyticsLayout 页面。它是 agent-settings 系列中的一个标签页，由 /iblai-vibe-agent 索引。

主要能力

以卡片形式展示分析报告入口：Overview、Users、Topics、Transcripts、Memory、Costs、Audit、Data Reports。
卡片值（value）与 AnalyticsLayout 的路由对应："" 表示 Overview，users、topics、transcripts、memory、financial（Costs）、audit、reports（Data Reports）。
支持通过 excludeTabs 隐藏宿主没有对应路由的卡片（例如 vibe-starter 中没有 Memory 和 Audit 路由）。
支持通过 tabs 属性替换卡片列表（从 DEFAULT_ANALYTICS_HUB_TABS 开始自定义 label、icon 或顺序）。
组件本身不调用任何 API，也不读取 AgentSettingsProvider，仅需要 onNavigate。

使用方式

前置条件

已完成认证配置（/iblai-vibe-auth，或 vibe-starter）。
安装 @iblai/iblai-js@^2.36.2（解析为 @iblai/web-containers 1.41.1）。
准备好分析落地页：vibe-starter 的 /admin/analytics/*，或 /iblai-vibe-analytics 中按智能体范围的布局（“One agent instead of the org”），挂载在 /agents/<uuid>/dashboards。
一个真实的智能体 UUID（需向用户询问，切勿自行编造）。

第 1 步：检查环境

在项目根目录查找 iblai.env，需包含 PLATFORM、DOMAIN 和 TOKEN。若缺失，提示用户下载模板并填写：

curl -o iblai.env https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/iblai.env

第 2 步：挂载 AgentAnalyticsTab

该标签页不获取数据，也不读取 AgentSettingsProvider，只需要 onNavigate。将每张卡片的 value 映射到已有路由，并排除没有的路由：

// app/(app)/agents/[mentorId]/analytics/page.tsx "use client";

import { AgentAnalyticsTab } from "@iblai/iblai-js/web-containers/next"; import { useParams, useRouter } from "next/navigation";

export default function AgentAnalyticsPage() { const router = useRouter(); const { mentorId } = useParams<{ mentorId: string }>();

return ( <div className="flex h-full flex-col bg-white"> <AgentAnalyticsTab // vibe-starter has no Memory or Audit analytics routes. excludeTabs={["memory", "audit"]} onNavigate={(value) => router.push(/admin/analytics${value ? /${value} : ""}?agent=${mentorId}) } /> </div> ); }

若使用 /iblai-vibe-analytics 的按智能体范围布局，则改为路由到 /agents/${mentorId}/dashboards/${value}（Overview 用 …/dashboards），并去掉已添加报告的 excludeTabs。注意不要把 dashboards 放在 /agents/<uuid>/analytics/ 下：该路由就是本 hub，Overview 卡片（value 为 ""）会路由回它。除非查看者拥有 /mentors/{mentorDbId}/#view_audit_logs（/iblai-vibe-rbac），否则隐藏 audit，与 OS 行为一致。在模态框中，先关闭模态框再 router.push。

第 3 步：修改卡片（可选）

没有 labels 属性：文案来自 SDK 的 i18n（analyticsTabLabels.*）。要修改卡片的文本、图标或顺序，传入自己的 tabs（从 DEFAULT_ANALYTICS_HUB_TABS 开始）：

import { AgentAnalyticsTab, DEFAULT_ANALYTICS_HUB_TABS, } from "@iblai/iblai-js/web-containers/next";

<AgentAnalyticsTab tabs={DEFAULT_ANALYTICS_HUB_TABS.map((t) => t.value === "financial" ? { ...t, label: "Spend" } : t, )} onNavigate={(value) => console.log("open", value)} />;

第 4 步：使用 MCP 工具进行自定义

get_component_info("AgentAnalyticsTab") get_component_info("AnalyticsLayout")

AgentAnalyticsTab 属性

从 @iblai/iblai-js/web-containers/next 导入。

属性	类型	必填	说明
onNavigate	(value: string) => void	是	以卡片的 value 调用；由宿主执行导航
tabs	AnalyticsHubTab[]（{ value, label, description, icon? }）	否	替换卡片。默认为本地化的标准集合
excludeTabs	string[]	否	要隐藏的卡片 value（例如无权限时的 audit）

卡片 value（与 AnalyticsLayout 路由一致）："" Overview、users、topics、transcripts、memory、financial（Costs）、audit、reports（Data Reports）。

平台数据

该标签页本身不调用任何 API。它打开的页面会读取分析端点，并将 mentor_unique_id 设为该智能体：相关 hooks 见 /iblai-vibe-analytics，REST 对应版本见 /iblai-api-analytics。

第 5 步：验证

在告知用户工作就绪前，先运行 /iblai-vibe-ops-test：

pnpm build —— 必须零错误通过。
pnpm test —— vitest 必须通过。
按 /iblai-vibe-ops-test 的说明，以管理员身份在浏览器中访问 /agents/<uuid>/analytics：卡片应渲染；逐一点击，均不得 404，且每个都落到该智能体的报告；查看控制台；检查手机宽度。

适用场景

在 Next.js 应用中为单个智能体提供分析报告入口。
需要将分析报告按智能体范围限定，并交由宿主应用路由。
需要隐藏某些报告卡片（如无权限的 audit，或宿主没有路由的报告）。

限制与注意事项

按设计它是一个 hub：OS 会在其编辑智能体模态框中渲染此标签页，并离开对话框进入整页分析。要嵌入仪表盘本身，请使用 /iblai-vibe-analytics。
每张卡片都需要有对应路由：排除应用不提供的任何 value，否则点击会 404。
vibe-starter 的标签条会丢弃 ?agent=：其 app/(app)/admin/analytics/layout.tsx 在路由标签时不带查询参数，因此落到报告后切换标签会显示整个组织。若需保持范围，请在其 onTabChange 中携带 ?agent=。
品牌指南：BRAND.md。
通用设置（品牌、约定、环境文件、验证）：见 docs/skill-setup.md。

技能介绍

用途