# ReplyPier 开发与维护指引

## 产品目标

- 网站右下角悬浮按钮，点击展开聊天。
- AI 根据公司知识库回答，支持同会话转人工。
- 多个人工客服协作、会话分配与访问隔离。
- 服务星级评分和文字评价。
- 管理员查看聊天记录、接待情况和评价。

## 维护约定

- 不主动撰写或归档项目来源、旧 Git 状态、操作时间线、验收 JSON 或验收截图。
- 正常程序日志、业务聊天记录和测试代码按既有机制保留；功能测试按任务需要执行。
- 保护源码中的版权声明以及 `LICENSE`、`NOTICE`。
- 不公开环境密钥、账号文件或客户数据。

## 本机环境

项目目录：`/Users/a11/1020-1030/01-projects/replypier`。

后端使用 Python 3.12 虚拟环境，知识库 worker 独立运行，前端使用 Vite preview。数据库与缓存通过 Colima 中的独立容器提供。

| 入口 / 服务 | 地址 |
| --- | --- |
| 后台登录 | <http://127.0.0.1:3018/> |
| 悬浮客服演示页 | <http://127.0.0.1:3018/local-demo.html> |
| 会话工作台 | <http://127.0.0.1:3018/conversations> |
| API / Widget / Socket.IO | `127.0.0.1:8018` |
| PostgreSQL 16 + pgvector | `127.0.0.1:15432` |
| Redis | `127.0.0.1:16380` |

Docker context 为 `colima-bytedesk`，Compose 项目名为 `chattermate-local`，数据库卷为 `chattermate-local_postgres_data`。它们是运行配置，不能为整理名称而改动或删除。Colima 虚拟机承载数据库与缓存，不要单独关闭。

## 配置与数据保护

- 账号密码保存在 `deploy/local/.state/test-accounts.json`，日常使用见本机说明。
- `deploy/local/.state/test-environment.json` 保存组织、AI 客服、Widget、分组及人工客服 ID，构建脚本需要使用。
- `backend/.env`、`frontend/.env`、`deploy/local/.env` 是私有配置。
- 模型 Key 加密保存在数据库。不要为文档或排查而导出、解密或写入源码与日志。
- 恢复时同时保留数据库与后端加密配置；不要用重置管理员、覆盖密钥或删除卷的方式重新开始。

## 维护入口

| 文件 | 用途 |
| --- | --- |
| [deploy/local/local.sh](deploy/local/local.sh) | 启停、状态、依赖安装、构建与日志 |
| [deploy/local/compose.yaml](deploy/local/compose.yaml) | PostgreSQL/pgvector 与 Redis 容器、数据卷 |
| [deploy/local/init_env.py](deploy/local/init_env.py) | 仅生成缺失配置，保留现有密钥 |
| [deploy/local/requirements.lock.txt](deploy/local/requirements.lock.txt) | 后端依赖锁定 |
| [deploy/local/seed_test.py](deploy/local/seed_test.py) | 使用已有管理员及账号文件准备演示配置，不是空环境初始化器 |
| [deploy/local/demo.template.html](deploy/local/demo.template.html) | 演示页模板 |

## 会话权限与接待规则

会话管理必须统一检查角色、组织边界和会话可见性。普通客服不能读取、接管、重新分配或订阅其他人负责的会话；合法转交后应同步更新访问权限。

- 管理操作：[session_to_agent.py](backend/app/api/session_to_agent.py)。
- Widget 与客服连接、房间、消息和评价：[widget_chat.py](backend/app/api/widget_chat.py)。
- 人工路由：[human_routing.py](backend/app/services/human_routing.py)。
- 定向回归：[test_session_to_agent.py](backend/tests/api/test_session_to_agent.py)。

## RAG 与 Agent 实现位置

- [knowledge_base.py](backend/app/knowledge/knowledge_base.py)：资料导入、切分、向量索引。
- [embedder.py](backend/app/knowledge/embedder.py)：本地 FastEmbed / ONNX 嵌入，按进程缓存模型；默认模型为 `BAAI/bge-small-en-v1.5`。
- [knowledge_search_byagent.py](backend/app/tools/knowledge_search_byagent.py)：限定关联知识源，补充相邻块并收集来源。
- [chat_agent.py](backend/app/agents/chat_agent.py)：Agno Agent、模型调用、工具与结构化回复。
- [history_memory.py](backend/app/agents/history_memory.py)：裁剪交给模型的近期历史，保留数据库中的会话记录。
- [transfer_agent.py](backend/app/agents/transfer_agent.py)：接待时间、人员可用性及转接说明。
- [workflow_execution.py](backend/app/services/workflow_execution.py)：消息、LLM、条件、表单与转人工等节点执行。

知识检索使用向量搜索；不要将其描述为已配置混合检索或 reranker。知识更新不是微调模型，多个人工客服也不等于多个自治 AI Agent。

## 待接入与待配置项

- 真实网站、HTTPS、CORS 和 Widget 的部署地址，需要对应网站与部署权限。
- 固定客户长期负责人的身份映射与自动路由，需要独立定制。
- 中文知识效果需要真实业务资料评估，不能用虚构示例替代。
- 邮件邀请、重置密码、Firebase 离线推送和生产容量需在相应任务中处理。