当三只小猫成为你们关系的翻译官 🐱✨
有时候，我们明明很爱对方，却因为表达不当而让彼此受伤。 PawPact 就像三只温柔的小猫，它们会耐心倾听、温柔翻译、细心协调， 帮助你们把那些带着刺的话语，慢慢打磨成彼此都能接受的温柔约定。
那是一个普通的周末下午，小雨和小风因为一件很小的事情吵起来了。
小风临时加班，发消息说"今天去不了了"。小雨回了一句"你总是这样"，小风只回了一个"哦"。然后...就没有然后了。两个人都不说话了，但心里都憋着一股气。
就在这个时候，小雨偶然看到了一个链接："PawPact - 让 AI 帮你翻译那些说不出口的话"。
"三只小猫？"小雨有点好奇，也有点想试试。反正现在也不知道怎么和小风说话，不如...试试看？
她点开链接，遇到了一个叫 Coco 的小猫。Coco 就像她最好的闺蜜，陪着她一起吐槽，还帮她理清楚自己到底想要什么："所以，你其实不是生气他加班，而是生气他没有提前告诉你，让你觉得不被重视，对不对？"
小雨愣了一下，然后点了点头。对，她其实想要的是...被提前告知，被重视的感觉。
另一边，小风也收到了链接。他遇到了一个叫 Mochi 的小猫。Mochi 特别温柔，安静地听他说，然后轻轻地问："那你有没有想过，她为什么会说'你总是这样'？也许她真正想说的是...'我希望你能提前告诉我，让我觉得被重视'？"
小风愣住了。他从来没有从这个角度想过。
就在两个人都把自己的想法理清楚之后，一个叫 Chloe 的小猫出现了。
"OK，两位宝贝，Chloe 军师上线了！"她俏皮地说，"我发现，你们俩其实都超在乎对方，只是小雨需要'安心感'，小风需要'理解'。来，我有个小点子..."
就这样，在 PawPact 的帮助下，小雨和小风把那些带着情绪的话，慢慢翻译成了温柔的需求，然后找到了一份双方都能接受的共识。
他们发现，原来沟通可以这么简单——只要有人帮你把那些说不出口的话，翻译成对方能听懂的语言。
这就是 PawPact 的故事。它不是什么高深的技术，它只是...三只温柔的小猫，帮你翻译那些说不出口的话。
Coco（可可） - 你的元气小太阳 ✨ 她就像你最好的闺蜜，永远站在你这边，陪你一起吐槽，帮你理清楚自己到底想要什么。
Mochi（麻薯） - 你的灵魂知己 🍵 她特别温柔，能听懂你没说出口的话，帮你把那些藏在心里的情绪都挖出来。
Chloe（克洛伊） - 你的 Slay 军师 💡 她最聪明，会帮你们把双方的需求都分析一遍，然后给出超级具体的建议，找到那个让双方都满意的平衡点。
"欢迎来到 PawPact，让我们开始这段温柔的旅程吧~"
"收到邀请啦！点击这里，就能和你的另一半开始对话了"
"这是你的专属空间，想说什么都可以，Coco 会陪你一起吐槽的！"
"另一边也在认真思考呢，让我们一起找到那个平衡点吧"
| 技术 | 用途 | 版本要求 |
|---|---|---|
| FastAPI | Web 框架，提供 RESTful API 和 WebSocket 支持 | >=0.112.0 |
| SQLAlchemy | ORM 框架，管理数据库模型和关系 | >=2.0.30 |
| PostgreSQL/SQLite | 关系型数据库，存储用户数据、会话、记忆等 | - |
| Redis | 内存数据库，用于缓存和实时状态管理 | >=5.0.7 |
| WebSocket | 双向实时通信协议，支持多客户端连接 | - |
| LangChain | AI 应用开发框架，集成大语言模型 | >=0.2.6 |
| OpenAI/Gemini API | 大语言模型服务，提供 AI 对话能力 | >=1.35.10 |
| Alembic | 数据库迁移工具，管理 schema 变更 | >=1.13.1 |
| 技术 | 用途 | 版本要求 |
|---|---|---|
| Next.js 14 | React 框架，提供 SSR、路由、API 路由等功能 | 14.2.33 |
| TypeScript | 类型安全的 JavaScript 超集 | 5.4.5 |
| Framer Motion | 动画库，提供流畅的交互动画 | ^11.18.2 |
| SWR | 数据获取库，提供缓存、重新验证等功能 | ^2.2.5 |
| Zustand | 轻量级状态管理库 | ^4.5.5 |
| PWA | 渐进式 Web 应用，支持离线使用和安装 | - |
┌─────────────┐ ┌─────────────┐
│ Frontend │ ◄─────► │ Backend │
│ (Next.js) │ HTTP │ (FastAPI) │
└─────────────┘ WS └─────────────┘
│
┌────────────┼────────────┐
│ │ │
┌─────▼──┐ ┌────▼──┐ ┌────▼──┐
│Postgres│ │ Redis │ │ AI │
│ DB │ │ Cache │ │ API │
└────────┘ └───────┘ └───────┘
系统采用三代理架构，每个代理负责不同的角色：
- Coco Agent：负责与 User A 进行 1v1 私密对话，扮演"元气小太阳"和"第一 BFF"的角色
- Mochi Agent：负责与 User B 进行 1v1 私密对话，扮演"灵魂知己"和"心灵港湾"的角色
- Chloe Agent：作为协调者，接收 Coco 和 Mochi 的反馈，生成面向双方的共识草案
系统实现了一个五阶段状态机来管理共识达成流程：
LISTENING → TRANSLATING → DRAFTING → REVIEWING → APPLYING
- LISTENING：收集双方原始输入
- TRANSLATING：将情绪化表达转化为结构化需求
- DRAFTING：生成初始共识草案
- REVIEWING：双方审查并提出修改意见
- APPLYING：达成最终共识并保存到共享记忆
系统维护两种类型的记忆：
- 私有记忆（PrivateMemory）：每个用户与对应代理的私密对话记录，仅对应用户可见
- 共享记忆（SharedMemory）：双方共同认可的共识和重要时刻，保存在共享花园中
记忆支持向量嵌入和语义检索，可以基于相似度查找历史记忆。
- 使用 WebSocket 实现双向实时通信
- 支持多客户端同时连接（每个用户独立连接）
- 实现状态同步机制，确保双方看到一致的会话状态
- Docker >= 20.10
- Docker Compose >= 2.0
- 8GB+ 可用内存
- 10GB+ 可用磁盘空间
- 克隆仓库
git clone https://github.com/Lewis121025/PawPact.git
cd PawPact- 配置环境变量
在项目根目录创建 .env 文件：
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gemini-2.5-flash- 启动服务
docker-compose up -d- 运行数据库迁移
docker-compose exec backend alembic upgrade head- 访问应用
- 前端界面：http://localhost:3000
- 后端 API：http://localhost:8000
- API 文档：http://localhost:8000/docs
# 启动所有服务
docker-compose up -d
# 查看服务日志
docker-compose logs -f [service_name]
# 停止所有服务
docker-compose down
# 停止并删除数据卷（会清除所有数据）
docker-compose down -v
# 重建镜像
docker-compose build --no-cache [service_name]
# 进入容器
docker-compose exec backend bash
docker-compose exec frontend sh- Python 3.11+
- Node.js 20+
- PostgreSQL 15+（可选，默认使用 SQLite）
- Redis 7+（可选，用于缓存优化）
- 创建虚拟环境
cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate- 安装依赖
pip install -e .
pip install -r requirements.txt- 配置环境变量
在 backend 目录创建 .env 文件：
DATABASE_URL=sqlite:///./pawpact.db
REDIS_URL=redis://localhost:6379/0
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gemini-2.5-flash
ALLOWED_ORIGINS=["http://localhost:3000"]- 初始化数据库
alembic upgrade head- 启动后端服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000- 安装依赖
cd frontend
npm install- 配置环境变量
在 frontend 目录创建 .env.local 文件：
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_BACKEND_WS=ws://localhost:8000
NEXT_PUBLIC_APP_URL=http://localhost:3000- 启动前端服务
npm run devWindows:
start.batLinux/macOS:
chmod +x start.sh
./start.sh详细说明请参考 QUICK_START.md
PawPact/
├── backend/ # FastAPI 后端服务
│ ├── app/
│ │ ├── models/ # SQLAlchemy 数据模型
│ │ │ ├── user.py # 用户模型
│ │ │ └── memory.py # 记忆模型（私有/共享）
│ │ ├── schemas/ # Pydantic 数据验证
│ │ │ ├── user.py
│ │ │ ├── memory.py
│ │ │ └── draft.py
│ │ ├── routers/ # API 路由
│ │ │ ├── health.py # 健康检查
│ │ │ ├── sessions.py # 会话管理
│ │ │ ├── memory.py # 记忆管理
│ │ │ ├── drafts.py # 共识草案
│ │ │ ├── garden.py # 共享花园
│ │ │ └── ws.py # WebSocket 路由
│ │ ├── services/ # 业务逻辑层
│ │ │ ├── agents.py # 代理编排器
│ │ │ ├── agent_roles.py # 代理角色定义（Coco/Mochi/Chloe）
│ │ │ ├── embeddings.py # 向量嵌入服务
│ │ │ └── drafts.py # 草案状态机
│ │ ├── config.py # 配置管理
│ │ ├── database.py # 数据库连接
│ │ ├── dependencies.py # 依赖注入
│ │ └── main.py # 应用入口
│ ├── alembic/ # 数据库迁移
│ │ ├── versions/ # 迁移版本
│ │ └── env.py # Alembic 环境配置
│ ├── tests/ # 测试文件
│ ├── Dockerfile # 后端 Docker 镜像
│ ├── requirements.txt # Python 依赖
│ └── pyproject.toml # 项目配置
│
├── frontend/ # Next.js 前端应用
│ ├── src/
│ │ ├── app/ # Next.js App Router
│ │ │ ├── page.tsx # 首页
│ │ │ ├── join/ # 加入会话页面
│ │ │ ├── session/ # 会话页面
│ │ │ └── garden/ # 共享花园页面
│ │ ├── components/ # React 组件
│ │ │ ├── AgentChatPanel.tsx # 代理聊天面板
│ │ │ ├── ConsensusDraftPanel.tsx # 共识草案面板
│ │ │ ├── SharedGardenCard.tsx # 共享花园卡片
│ │ │ └── ...
│ │ ├── hooks/ # 自定义 Hooks
│ │ │ └── useAgentChannel.ts # WebSocket 连接
│ │ ├── lib/ # 工具函数
│ │ │ ├── api.ts # API 客户端
│ │ │ └── ws.ts # WebSocket 客户端
│ │ └── types/ # TypeScript 类型定义
│ ├── public/ # 静态资源
│ ├── Dockerfile # 前端 Docker 镜像
│ └── package.json # Node.js 依赖
│
├── Example/ # 示例图片和 GIF
├── docker-compose.yml # Docker Compose 配置
└── README.md # 项目文档
| 变量名 | 类型 | 必需 | 默认值 | 说明 |
|---|---|---|---|---|
DATABASE_URL |
string | 否 | sqlite:///./pawpact.db |
数据库连接字符串。支持 SQLite 和 PostgreSQL |
REDIS_URL |
string | 否 | redis://localhost:6379/0 |
Redis 连接字符串，用于缓存和实时状态 |
OPENAI_API_KEY |
string | 是 | - | OpenAI 或 Gemini API 密钥 |
OPENAI_API_BASE |
string | 否 | - | API 基础 URL（用于 OpenRouter 等代理服务） |
OPENAI_MODEL |
string | 否 | gemini-2.5-flash |
使用的 AI 模型名称 |
ALLOWED_ORIGINS |
JSON array | 否 | ["http://localhost:3000"] |
CORS 允许的来源列表 |
PROJECT_NAME |
string | 否 | PawPact Backend |
项目名称 |
ENVIRONMENT |
string | 否 | development |
运行环境（development/production） |
| 变量名 | 类型 | 必需 | 默认值 | 说明 |
|---|---|---|---|---|
NEXT_PUBLIC_BACKEND_URL |
string | 是 | - | 后端 API 基础 URL |
NEXT_PUBLIC_BACKEND_WS |
string | 是 | - | WebSocket 服务器地址 |
NEXT_PUBLIC_APP_URL |
string | 是 | - | 前端应用 URL（用于生成分享链接） |
cd backend
pytest运行特定测试文件：
pytest tests/test_sessions_flow.py
pytest tests/test_websocket_agents.pycd frontend
npm run lint启动后端服务后，可以通过以下地址访问 API 文档：
- Swagger UI: http://localhost:8000/docs
- 交互式 API 文档，支持在线测试接口
- ReDoc: http://localhost:8000/redoc
- 更美观的 API 文档展示
GET /api/v1/health- 健康检查POST /api/v1/sessions- 创建新会话GET /api/v1/sessions/{session_id}- 获取会话信息GET /api/v1/memories/private- 获取私有记忆GET /api/v1/memories/shared- 获取共享记忆POST /api/v1/drafts- 创建共识草案GET /api/v1/garden- 获取共享花园数据WS /ws/agent/{role}/{session_id}- WebSocket 连接
我们欢迎所有形式的贡献！无论是报告 bug、提出功能建议，还是提交代码，都是对我们的帮助。
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
- 后端：遵循 PEP 8，使用
ruff进行代码检查 - 前端：遵循 ESLint 规则，使用
prettier格式化代码 - 提交信息：使用清晰的提交信息，遵循 Conventional Commits
- 感谢所有使用和贡献这个项目的开发者
- 特别感谢 AI 模型提供商（OpenAI、Google Gemini）提供的强大能力
- 感谢每一个相信技术可以带来温暖的人
- GitHub: @Lewis121025
- 项目地址: https://github.com/Lewis121025/PawPact
- 问题反馈: 欢迎在 Issues 中提出
用 AI 的温柔，化解关系的坚冰 ❤️
有时候，我们需要的不是对错，而是理解 有时候，我们需要的不是改变，而是翻译 有时候，我们需要的不是完美，而是共识
Made with ❤️ by Lewis
愿每一段关系，都能在温柔中找到平衡 🌸