@zov-chatui/feedback-agent

基于 @zov-chatui/base 构建的一站式、即插即用型智能反馈中心解决方案。它集成了 AI 对话、自动上下文采集、结构化报告生成及 Premium UI 视觉效果，旨在为第三方应用提供极致的反馈集成体验。

✨ 核心特性

• 🤖 智能多轮对话：内置意图识别逻辑，AI 主动追问细节，自动区分 Bug 反馈或功能建议。
• 📋 结构化报告：对话结束自动生成包含环境信息、问题描述、期望状态的报告，用户一键确认提交。
• 🔍 零代码上下文采集：自动探测 URL、版本号、产品名及模块路径，无需手动传入。
• 🎤 全能输入：内置 Web Speech API 实时转写，支持私有 ASR 服务接入。
• 🎨 Premium UI：提供极光背景 (Aurora)、闪耀文本 (ShinyText) 及平滑的 Framer Motion 交互动画。

📦 安装

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

同時需要安装 peer dependencies：

npm install react react-dom styled-components @zov-chatui/base

🚀 极简集成指南

只需三步，即可在你的项目中启用完整的反馈系统。

第一步：初始化 API 配置 (推荐在应用载入时执行)

反馈智能体内部通过 setApiConfig 统一管理后端连接。

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

setApiConfig({
  baseURL: 'https://api.your-system.com', // 你的后端服务基础地址
  chatEndpoint: '/api/v1/chat',           // 流式对话接口 (可选，有默认值)
});

第二步：组件集成 (FeedbackAgentModal)

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

function App() {
  const [open, setOpen] = useState(false);

  const handleSendMessage = async (content, type, metadata) => {
    // 调用内置服务或自定义逻辑
    const res = await chatService.sendMessageWithResponse(content, type, metadata);
    return res; // 需返回包含 reply 和 complete 字段的对象
  };

  return (
    <>
      <button onClick={() => setOpen(true)}>我要反馈</button>
      
      <FeedbackAgentModal
        open={open}
        onClose={() => setOpen(false)}
        title="智感反馈助手"
        config={{
          onSendMessage: handleSendMessage,
          onReportConfirm: (report) => console.log('报告提交:', report),
        }}
      />
    </>
  );
}

🛠️ 第三方集成：可自定义配置项指南

针对不同的集成场景，我们标注了 [开放配置] 项，开发者可以根据品牌视觉和业务需求进行深度定制。

1. 业务逻辑与数据通道 [必选/开放]

| 配置路径 | 类型 | 是否必选 | 说明与自定义建议 | | :--- | :--- | :--- | :--- | | config.onSendMessage | Function | 是 | 核心通道。对接你内部的 AI 网关，返回流式或全文响应。 | | config.onReportConfirm | Function | 否 | 提交终点。用户点击“确认提交报告”时触发，用于将结构化 XML/JSON 存入数据库。 | | config.onError | Function | 否 | 异常监控。建议对接公司内部的日志采集系统 (如 Sentry)。 |

2. 身份与上下文识别 [开放配置]

若你的应用已经登录或有明确的项目划分，应通过此部分进行标记。

| 属性名称 | 类型 | 默认值 | 自定义建议 | | :--- | :--- | :--- | :--- | | userId / userName | string | - | 强烈建议传入。让 AI 知道正在和谁对话，生成的报告会自动带上此身份。 | | tenantName | string | - | 用于多租户/B端场景下的租户标识。 | | config.productName | string | document.title | 覆盖自动检测到的产品名称。 | | config.version | string | window.__APP_VERSION__ | 指定应用版本号，便于 Bug 复现。 | | config.moduleDetector | Function | 内置算法 | 进阶。若你的 URL 规则特殊，可提供函数返回当前模块名 (如 "购物车-支付页")。 |

3. 多语言与文案定制 [开放配置]

| 属性名称 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | locale | 'zh-CN' \| 'en-US' | 'zh-CN' | 一键切换。支持简体中文和英文。 | | title | string | '智能客服助手' | 弹窗顶部的品牌名称（如 "ZOV 智能专家"）。 | | inputProps.placeholder | string | '请描述您遇到的问题...' | 输入框内的引导文案。 |

4. 视觉方案与容器调整 [开放配置]

| 属性名称 | 类型 | 默认值 | 自定义建议 | | :--- | :--- | :--- | :--- | | modalStyle | CSSProperties | - | 调整弹窗主体的圆角、背景色或阴影。 | | overlayStyle | CSSProperties | - | 调整反馈按钮在屏幕上的定位层。 | | listProps.avatars | Object | 内置 SVG | 品牌化。传入公司 Logo 或特定的机器人头像 URL | | right / bottom | number \| string | 20px | 专门用于微调弹窗在右下角的偏移量，支持百分比。 |

5. 功能组件开关 [开放配置]

| 属性名称 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | config.showFeedback | boolean | true | 点赞点踩。是否显示消息底部的赞成/反对按钮。 | | config.showUpload | boolean | true | 附件上传。是否允许用户上传图片或文件（包含粘贴上传）。 |

📍 自定义弹窗位置 (Modal Positioning)

FeedbackAgentModal 默认固定在页面右下角，您可以通过多种方式自定义其位置：

1️⃣ 基础微调 (right & bottom)

最简单的方法，直接传入距离右侧和底部的数值（支持 px、%、vh 等单位）。

<FeedbackAgentModal
  open={open}
  onClose={() => setOpen(false)}
  // 💡 设置为距离右侧 40px，底部 10vh
  right={40}
  bottom="10vh" 
  config={{ ... }}
/>

2️⃣ 深度布局定制 (overlayStyle)

如果您想将弹窗移至左下角或页面中心，可以通过覆盖 overlayStyle 的 Flex 布局来实现：

// 示例：将弹窗移至左下角
<FeedbackAgentModal
  open={open}
  overlayStyle={{
    justifyContent: 'flex-start', // 水平靠左
    paddingLeft: '40px',          // 左边距
  }}
  config={{ ... }}
/>

// 示例：将弹窗在页面中央居中显示
<FeedbackAgentModal
  open={open}
  overlayStyle={{
    alignItems: 'center',    // 垂直居中
    justifyContent: 'center', // 水平居中
    padding: 0                // 清除默认边距
  }}
  config={{ ... }}
/>

🔍 FeedbackAgentModal 完整参数表

基础属性

| 属性 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | open | boolean | false | 控制显示状态 | | onClose | () => void | - | 关闭回调 | | showFullscreenButton | boolean | true | 是否显示全屏切换按钮 | | showClearButton | boolean | true | 是否显示清空历史按钮 | | onClearConversation | () => void | - | 点击清空后的回调 | | config.showFeedback | boolean | true | 是否显示点赞点踩反馈按钮 | | config.showUpload | boolean | true | 是否显示附件上传按钮及功能 |

语音配置 (config.voice)

| 属性 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | enabled | boolean | false | 是否显示麦克风。由于涉及权限，默认不开启。 | | onVoiceData | (blob) => string | - | 服务端识别。若不传，则默认尝试调用浏览器 Web Speech API。 |

🎨 开发与调试

# 进入 package 目录
cd packages/feedback-agent

# 安装依赖
yarn

# 启动研发 Demo
yarn dev

📄 License

MIT © [ZOV Team]