iblai-agent-history

用途

iblai-agent-history 用于向 Next.js 应用添加智能体（Agent）的 History 标签页，即对话历史界面。该标签页支持评分、摘要、主题标签，并提供筛选功能，可按用户、日期范围、情感和主题过滤。它还包含对话预览、分页插槽以及可选的导出能力。它是更广泛的 agent-settings 家族中的一个标签，家族内所有标签共享同一个 AgentSettingsProvider 包装器。

主要能力

展示对话历史，包含评分、摘要、主题标签。
提供筛选：用户、日期范围、情感、主题。
包含对话预览。
支持分页插槽（需自行传入分页组件，否则不渲染分页 UI）。
可选导出功能，通过 onExport 回调返回当前筛选条件。
支持通过 renderMessageContent 自定义 AI 消息的富文本渲染，默认纯文本。
支持通过 labels 覆盖用户可见文案。

使用方式

前置条件：

必须先完成鉴权设置（/iblai-auth）。
需配置 MCP 服务器与技能（@iblai/mcp 于 .mcp.json）。
AgentSettingsProvider 必须包裹路由。若尚未设置，参见 /iblai-agent-setting 第 2 步。
需向用户索取真实的 mentorId（代理 UUID），不得自行编造。

第 1 步：检查环境。检查项目根目录是否存在 iblai.env，其中包含 PLATFORM、DOMAIN、TOKEN 变量。若文件不存在或缺少这些变量，需告知用户下载模板：

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

第 2 步：挂载 AgentHistoryTab。基础用法：

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

import { AgentHistoryTab } from "@iblai/iblai-js/web-containers/next";

export default function AgentHistoryPage() {
  return (
    <div className="flex h-full flex-col bg-white">
      <AgentHistoryTab />
    </div>
  );
}

带 Markdown 渲染与导出：

import ReactMarkdown from "react-markdown";

<AgentHistoryTab
  renderMessageContent={(content) => <ReactMarkdown>{content}</ReactMarkdown>}
  onExport={(filters) => {
    console.log("export with filters", filters);
  }}
  isExporting={false}
/>;

带分页：

<AgentHistoryTab
  PaginationComponent={({ currentPage, totalPages, onPageChange, disabled }) => (
    <MyPagination
      page={currentPage}
      total={totalPages}
      onChange={onPageChange}
      disabled={disabled}
    />
  )}
/>;

第 3 步：自定义文案（可选）：

import { AgentHistoryTab } from "@iblai/iblai-js/web-containers/next";

<AgentHistoryTab
  labels={{
    header: { title: "Mentor conversations" },
  }}
/>;

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

get_component_info("AgentHistoryTab")
get_component_info("AgentSettingsProvider")

AgentHistoryTab 属性

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

labels：类型 DeepPartial<HistoryTabLabels>，非必填，覆盖用户可见字符串。
renderMessageContent：(content: string) => ReactNode，非必填，将 AI 消息渲染为富文本，默认纯文本。
PaginationComponent：ComponentType<{ currentPage, totalPages, onPageChange, disabled, disableNumberedButtons? }>，非必填，自定义分页；不提供则不渲染分页 UI。
onExport：(filters: ChatHistoryFilter) => void，非必填，点击导出时以当前筛选条件调用。
isExporting：boolean，非必填，表示是否正在导出。

相关导出：从 @iblai/iblai-js/web-containers/next 导出 HistoryTabLabels（完整文案包的类型）。

第 5 步：验证。在告知用户工作就绪前运行 /iblai-ops-test：

pnpm build 必须零错误通过。
pnpm test，vitest 必须通过。
启动开发服务器并做触碰测试：

pnpm dev &
npx playwright screenshot http://localhost:3000/agents/<id>/history /tmp/agent-history.png

品牌与实现约定

不得为 ibl.ai SDK 组件添加自定义样式、颜色或 CSS 覆盖。SDK 组件自带样式，须保持原样。
除非用户明确要求，不得实现深色模式。
围绕 SDK 组件构建自定义 UI 时，使用 ibl.ai 品牌：
- 主色：#0058cc；渐变：linear-gradient(135deg, #00b0ef, #0058cc)
- 按钮：bg-gradient-to-r from-[#2563EB] to-[#93C5FD] text-white
- 字体：系统无衬线字体栈；样式：shadcn/ui new-york 变体
遵循组件层级：优先使用 ibl.ai SDK 组件（@iblai/iblai-js），其余使用 shadcn/ui（npx shadcn@latest add <component>）。当存在 ibl.ai 或 shadcn 等价组件时，不得编写自定义组件。两者共享同一 Tailwind 主题，并自动以 ibl.ai 品牌色渲染。
遵循 BRAND.md 中的颜色、排版、间距和组件样式。
完成所有工作后，启动开发服务器（pnpm dev），以便用户在 http://localhost:3000 查看结果。
iblai.env 不是 .env.local 的替代品，它只保存 3 个简写变量（DOMAIN、PLATFORM、TOKEN）。Next.js 仍从 .env.local 读取运行时环境变量。
使用 pnpm 作为默认包管理器。若未安装 pnpm，则回退到 npm。
通用设置（品牌、约定、环境文件、验证）参见 docs/skill-setup.md。

重要注意事项

Redux store 必须包含 mentorReducer 和 mentorMiddleware。
initializeDataLayer()：5 个参数（v1.2+）。
@reduxjs/toolkit：通过 next.config.ts 中的 webpack 别名去重。
对等依赖：必须安装 sonner 和 @iblai/iblai-web-mentor（pnpm add sonner @iblai/iblai-web-mentor）。
共享 provider：AgentSettingsProvider 必须在布局层级包裹路由。完整片段参见 /iblai-agent-setting 第 2 步。
品牌指南：BRAND.md。

适用场景与限制

适用于在基于 Next.js 与 ibl.ai 平台构建的应用中，为智能体添加对话历史查看、筛选、预览与导出界面。需满足鉴权、MCP 与 Provider 等前置条件，且 mentorId 需为真实值。资料未提供收费、价格或效果相关信息。