@zov-chatui/feedback-agent

基于 @zov-chatui/base 和 @zov-chatui/chat-parsers 构建的一站式反馈智能体解决方案。它不仅提供 AI 对话交互，还包含反馈列表展示、管理后台以及自动场景化信息采集。

✨ 功能特性

1. 🤖 智能对话反馈

• 情景化捕捉：自动采集产品名称、版本号、所在 URL 及功能模块，降低用户输入成本。
• 意图识别：智能区分用户是在反馈 "缺陷 (Issue)" 还是提出 "建议 (Suggestion)"。
• 主动追问：AI 会根据用户描述主动挖掘细节，如复现步骤、期望状态等。
• 自动生成报告：对话结束时根据上下文自动生成结构化报告草稿，用户一键确认即可提交。

2. 📋 全方位反馈管理

• 个人中心 (MyFeedback)：用户可查看自己提交的所有反馈记录，追踪反馈状态（待处理、处理中、已解决）。
• 管理后台 (FeedbackManagement)：提供给管理员的报表视图，支持关键词搜索、状态过滤以及详情查看。

3. 🎨 极致 UI 体验

• Premium 设计：内置 Aurora 极光背景、ShinyText 闪耀文字等高级视觉特效。
• 流畅交互：基于 Framer Motion 实现的平滑过渡动作。
• 多端适配：响应式布局，完美适配 Web 及 H5 场景。

4. 🛠️ 深度服务集成

• 内置 chatService：支持 SSE 流式响应、多段式 JSON 解析，开箱即用的 AI 接口对接。
• 全局 API 配置：通过 setApiConfig 统一管理所有接口地址和超时时间。

📦 安装

npm install @zov-chatui/feedback-agent
# 或
yarn add @zov-chatui/feedback-agent

🚀 快速开始

1. 初始化 API 配置

在应用入口文件（如 main.tsx）中配置后端接口地址。

import { setApiConfig } from '@zov-chatui/feedback-agent';

setApiConfig({
  baseURL: 'https://api.your-service.com',
  chatEndpoint: '/api/v1/agent/chat',
  timeout: 30000,
});

2. 使用对话机器人 (FeedbackAgent)

import { FeedbackAgent, chatService } from '@zov-chatui/feedback-agent';

function App() {
  return (
    <div style={{ height: '80vh' }}>
      <FeedbackAgent
        config={{
          onSendMessage: async (content, type, metadata, history) => {
            // 使用内置服务直接对接 AI
            return await chatService.sendMessage(content, type, metadata, history);
          },
          onReportConfirm: async (report) => {
            console.log('用户确认报告:', report);
          }
        }}
      />
    </div>
  );
}

3. 使用弹窗模式 (FeedbackAgentModal)

import { FeedbackAgentModal } from '@zov-chatui/feedback-agent';

// ...
<FeedbackAgentModal
  open={isOpen}
  onClose={() => setIsOpen(false)}
  config={{
    onSendMessage: handleSendMessage,
    onReportConfirm: handleReportConfirm
  }}
/>

📂 高级组件

我的反馈列表 (MyFeedback)

用于在个人中心或设置页面展示用户的反馈历史。

import { MyFeedback } from '@zov-chatui/feedback-agent';

function PersonalCenter() {
  return <MyFeedback onBack={() => history.back()} />;
}

反馈管理后台 (FeedbackManagement)

用于管理员进行反馈处理和状态流转。

import { FeedbackManagement } from '@zov-chatui/feedback-agent';

function AdminDashboard() {
  return <FeedbackManagement onBack={() => history.back()} />;
}

🔍 功能详情

场景信息自动提取

组件会自动从以下位置提取上下文，无需手动配置：

• 产品名称：<meta name="product"> -> document.title -> data-product
• 版本号：<meta name="version"> -> window.__APP_VERSION__ -> data-version
• 模块识别：智能解析 URL Path、面包屑、导航菜单及 data-module 属性。

报告生成逻辑

报告会在以下情况自动触发生成并弹出确认框：

1. AI 指令：AI 返回数据中包含 complete: true 或 type: 'feedback_report'。
2. 对话轮次：单次对话超过 3 轮（可配置）。
3. 关键词触发：用户表达了结束意图。

⚙️ 配置参考

FeedbackAgentConfig

| 属性 | 类型 | 必填 | 说明 | | :--- | :--- | :--- | :--- | | onSendMessage | Function | 是 | 核心对话回调，接收内容并返回 AI 回复 | | onReportConfirm | Function | 否 | 最终报告确认提交后的回调 | | productName | string | 否 | 覆盖自动提取的产品名称 | | version | string | 否 | 覆盖自动提取的版本号 | | moduleDetector | () => string | 否 | 自定义模块识别逻辑 | | tts | TTSSettings | 否 | 语音播报设置 |

接口配置 (setApiConfig)

| 配置项 | 说明 | 默认值 | | :--- | :--- | :--- | | baseURL | 接口基础路径 | - | | chatEndpoint | 对话接口路径 | /agent/chat | | submitEndpoint | 报告提交路径 | /agent/feedback/submit | | historyEndpoint | 反馈历史路径 | /agent/feedback/list |

🛠️ 本地开发

# 启动 Demo 环境
yarn dev

# 构建包
yarn build

# 核心自检
yarn type-check
yarn lint

📄 License

MIT © [ZOV Team]