4.9 KiB
4.9 KiB
ReplyPier 开发与维护指引
日常登录、操作和启停见 LOCAL_DEPLOY.md，开发排期见 FROM_ZERO_PLAN.md。
产品目标
- 网站右下角悬浮按钮，点击展开聊天。
- 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/compose.yaml | PostgreSQL/pgvector 与 Redis 容器、数据卷 |
| deploy/local/init_env.py | 仅生成缺失配置，保留现有密钥 |
| deploy/local/requirements.lock.txt | 后端依赖锁定 |
| deploy/local/seed_test.py | 使用已有管理员及账号文件准备演示配置，不是空环境初始化器 |
| deploy/local/demo.template.html | 演示页模板 |
会话权限与接待规则
会话管理必须统一检查角色、组织边界和会话可见性。普通客服不能读取、接管、重新分配或订阅其他人负责的会话；合法转交后应同步更新访问权限。
- 管理操作：session_to_agent.py。
- Widget 与客服连接、房间、消息和评价：widget_chat.py。
- 人工路由：human_routing.py。
- 定向回归：test_session_to_agent.py。
RAG 与 Agent 实现位置
- knowledge_base.py：资料导入、切分、向量索引。
- embedder.py：本地 FastEmbed / ONNX 嵌入，按进程缓存模型；默认模型为
BAAI/bge-small-en-v1.5。 - knowledge_search_byagent.py：限定关联知识源，补充相邻块并收集来源。
- chat_agent.py：Agno Agent、模型调用、工具与结构化回复。
- history_memory.py：裁剪交给模型的近期历史，保留数据库中的会话记录。
- transfer_agent.py：接待时间、人员可用性及转接说明。
- workflow_execution.py：消息、LLM、条件、表单与转人工等节点执行。
知识检索使用向量搜索；不要将其描述为已配置混合检索或 reranker。知识更新不是微调模型，多个人工客服也不等于多个自治 AI Agent。
待接入与待配置项
- 真实网站、HTTPS、CORS 和 Widget 的部署地址，需要对应网站与部署权限。
- 固定客户长期负责人的身份映射与自动路由，需要独立定制。
- 中文知识效果需要真实业务资料评估，不能用虚构示例替代。
- 邮件邀请、重置密码、Firebase 离线推送和生产容量需在相应任务中处理。