replypier/README.md

<div align="center">
  <img src="frontend/src/assets/logo.svg" width="56" height="42" alt="ReplyPier 纸舟标志" />
  <h1>ReplyPier</h1>
  <p><strong>AI 先答疑，人工接得住；一段会话，服务有始有终。</strong></p>
  <p>面向个人与公司网站的 AI 客服，把知识问答、人工协作和服务评价连在一起。</p>

  <p>
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-2E6A5C?style=flat-square&logo=apache&logoColor=white" alt="Apache 2.0 License" /></a>
    <a href="backend/requirements.txt"><img src="https://img.shields.io/badge/Python-FastAPI-2E6A5C?style=flat-square&logo=fastapi&logoColor=white" alt="Python and FastAPI" /></a>
    <a href="frontend/package.json"><img src="https://img.shields.io/badge/Vue_3-TypeScript-568B73?style=flat-square&logo=vue.js&logoColor=white" alt="Vue 3 and TypeScript" /></a>
  </p>

  <p>
    <a href="#产品预览">产品预览</a> ·
    <a href="#核心能力">核心能力</a> ·
    <a href="#快速开始">快速开始</a> ·
    <a href="#技术结构">技术结构</a> ·
    <a href="AGENT_HANDOFF.md">开发指引</a>
  </p>
</div>

## 产品预览

客服工作台是每天停留最久的一屏：左边是会话列表，中间是完整对话，右边是访客信息、接待状态和服务评价。

<p align="center">
  <img src=".github/readme-assets/replypier-conversations.jpg" width="860" alt="ReplyPier 会话工作台：访客提问、AI 依据知识库作答，转人工后由人工客服接管" />
</p>

<p align="center">
  <sub>会话工作台 · AI 依据知识库作答 → 转人工保留上下文 → 接待结束邀请访客评价</sub>
</p>

AI 客服的外观、知识与接待方式都在同一页配置，右侧预览与访客看到的窗口一致。

<p align="center">
  <img src=".github/readme-assets/replypier-agent-customization.jpg" width="860" alt="ReplyPier AI 客服配置页：左侧选择聊天外观，右侧即时预览访客窗口" />
</p>

<p align="center">
  <sub>AI 客服配置 · 左侧挑选聊天外观，右侧即时预览访客窗口</sub>
</p>

访客侧只在网站右下角露出一枚悬浮按钮，点开就是带纸舟标志的聊天窗口。

<p align="center">
  <img src=".github/readme-assets/replypier-visitor-chat.png" width="320" alt="ReplyPier 网站右下角的访客聊天窗口，纸舟标志显示在客服头像与页脚" />
</p>

<p align="center">
  <sub>访客窗口 · 悬浮展开，纸舟标志贯穿头像与页脚</sub>
</p>

## 核心能力

- **知识库问答**：为 AI 客服关联知识资料，回答时在 Widget 中展示来源。
- **同会话转人工**：保留完整聊天上下文，支持客服组接待、人工接管与授权转交。
- **评价与回看**：收集星级和文字反馈，管理员可查看完整会话与接待情况。
- **多客服协作**：按角色、组织、分组和会话可见范围控制访问。
- **可配置 Agent 与 Widget**：管理 AI 客服、知识关联、外观和网站嵌入。
- **知识任务与工作流**：处理知识导入，并编排客服消息的处理步骤。

## 快速开始

本机已具备 PostgreSQL + pgvector、Redis、Python 3.12 与 Node 环境时，在项目根目录执行：

```bash
./deploy/local/local.sh setup   # 首次运行：安装依赖并构建前端
./deploy/local/local.sh up      # 启动数据库、后端与前端
./deploy/local/local.sh status  # 查看各服务状态
```

启动后可访问：

- [客服工作台](http://127.0.0.1:3018/)：登录后处理会话、配置 AI 客服。
- [悬浮客服演示页](http://127.0.0.1:3018/local-demo.html)：从访客视角提问、转人工并提交评价。

账号、构建、日志、数据恢复与公网接入条件见 [LOCAL_DEPLOY.md](LOCAL_DEPLOY.md)。

## 技术结构

- **后端**：Python、FastAPI、SQLAlchemy、Alembic。
- **前端**：Vue 3、TypeScript、Vite。
- **实时通信**：Socket.IO。
- **知识检索**：FastEmbed、PostgreSQL/pgvector。
- **短期状态与事件分发**：Redis。
- **AI 编排**：Agno。

```text
backend/app/       API、业务模型、Agent、知识处理与后台任务
backend/tests/     后端测试
frontend/src/      管理后台、客服工作台与嵌入 Widget
e2e/               端到端测试
deploy/local/      本机环境与启停脚本
```

## 开发检查

- 后端测试位于 `backend/tests/`。
- 前端类型检查：在 `frontend/` 执行 `npm run type-check`。
- 前端单元测试：在 `frontend/` 执行 `npm run test:unit`。
- 端到端测试约定见 [e2e/AUTHORING.md](e2e/AUTHORING.md)。

## 许可与贡献

本项目使用 [Apache License 2.0](LICENSE)，声明见 [NOTICE](NOTICE)，贡献约定见 [CONTRIBUTING.md](CONTRIBUTING.md)。