docs: 新增 README + 更新 Deploy.md + 整理 .gitignore

- 新增 README.md 完整项目概览（架构、功能、快速开始） - 更新 Deploy.md 修正过时的服务状态和端口信息 - 整理 .gitignore 补充缺失规则并移除无效项 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-22 19:59:47 +08:00
parent e83f28d646
commit 8c19b79a02
5 changed files with 349 additions and 328 deletions
@@ -0,0 +1,173 @@
+# Cyrene (昔涟) — AI 伙伴平台
+
+昔涟是一个开源的 AI 伙伴平台，提供多人格对话、IoT 设备操控、记忆管理、自动化规则、知识库、语音交互等功能。
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      Frontend (React + Vite)             │
+│                      localhost:5173                      │
+└─────────────────────┬───────────────────────────────────┘
+                      │ HTTP + WebSocket
+┌─────────────────────▼───────────────────────────────────┐
+│                   Gateway (Go/Gin)                       │
+│                   localhost:8080                         │
+│   JWT Auth · Rate Limit · WS Hub · API 路由              │
+└──┬────────┬────────┬────────┬────────┬────────┬────────┘
+   │        │        │        │        │        │
+   ▼        ▼        ▼        ▼        ▼        ▼
+┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
+│ AI   │ │Memory│ │Tool  │ │Voice │ │ IoT  │ │ Infra    │
+│ Core │ │Svc   │ │Engine│ │Svc   │ │Debug │ │          │
+│:8081 │ │:8091 │ │:8092 │ │:8093 │ │:8083 │ │ PG:5432  │
+│      │ │      │ │      │ │      │ │      │ │ Redis    │
+│ LLM  │ │CRUD  │ │执行  │ │STT/  │ │模拟  │ │  :6379   │
+│ 编排 │ │检索  │ │工具  │ │TTS   │ │设备  │ │ Qdrant   │
+│ 人设 │ │      │ │调用  │ │      │ │管理  │ │  :6333   │
+│ 工具 │ │      │ │      │ │      │ │      │ │ MinIO    │
+│ 后台 │ │      │ │      │ │      │ │      │ │  :9000   │
+│ 思考 │ │      │ │      │ │      │ │      │ │ NATS     │
+└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────────┘
+```
+
+## 功能
+
+- **多人格对话** — 可配置的角色扮演系统，带上下文构建和子会话路由
+- **IoT 操控** — 模拟智能家居设备（灯、空调、窗帘、传感器、门锁），支持语音/文本控制
+- **记忆管理** — LLM 驱动的长期记忆提取、存储和检索（PostgreSQL + pgvector）
+- **自动化** — 规则引擎 + 场景执行（定时、条件触发、Webhook）
+- **每日简报** — 定时生成当日汇总
+- **提醒** — 创建/管理定时提醒，到期 WebSocket 推送
+- **知识库** — 文档管理 + 向量检索
+- **文件管理** — 上传、下载、缩略图、图片 AI 分析
+- **语音交互** — 浏览器端 STT（Web Speech API）+ TTS，服务端支持 Whisper
+- **WebSocket** — 实时消息推送、IoT 状态广播、通知
+- **PWA** — 可安装为桌面/移动应用，离线支持
+- **后台思考** — AI 在对话间隙自主进行反思和记忆整理
+- **Webhook 接入** — 支持 Discord、通用 Webhook 第三方平台接入
+
+## 项目结构
+
+```
+Cyrene/
+├── frontend/
+│   ├── web/              # React 前端 (Vite + TypeScript + Tailwind)
+│   └── packages/shared/  # 共享类型/工具
+├── backend/
+│   ├── ai-core/          # AI 推理核心 (LLM 编排、人设注入、工具调用、后台思考)
+│   ├── gateway/          # API 网关 (JWT 认证、路由、限流、WebSocket Hub)
+│   ├── memory-service/   # 记忆服务 (CRUD、检索、LLM 提取)
+│   ├── tool-engine/      # 工具引擎 (计算器、HTTP、IoT、文件操作等)
+│   ├── voice-service/    # 语音服务 (TTS/STT，基于 Edge-TTS + Whisper)
+│   ├── iot-debug-service/# IoT 调试服务 (模拟智能家居设备)
+│   └── proto/            # Protobuf 定义 (预留)
+├── devtools/             # 开发管理面板 (Express，服务管理/日志/性能)
+├── scripts/              # 辅助脚本 (Whisper 安装、SSH 隧道、数据迁移)
+├── test/                 # E2E 测试脚本 (CDP/Chromium)
+├── docs/                 # 项目文档与调试记录
+├── debug/                # 诊断与缓存脚本
+├── docker-compose.dev.db.yml   # 开发环境基础设施 (仅 DB)
+├── docker-compose.dev.yml      # 开发环境一键启动
+├── docker-compose.yml          # 生产环境 (含 Caddy)
+└── Caddyfile             # 反向代理配置
+```
+
+## 快速开始
+
+### 前提条件
+
+- Go 1.21+
+- Node.js 20+
+- Docker & Docker Compose
+
+### 1. 启动基础设施
+
+```bash
+docker compose -f docker-compose.dev.db.yml up -d
+```
+
+启动 PostgreSQL (pgvector)、Redis、Qdrant、MinIO、NATS。
+
+### 2. 启动后端服务
+
+使用 DevTools 一键管理：
+
+```bash
+./devtools.sh start all    # 编译并启动所有后端 + 前端
+./devtools.sh status       # 查看服务状态
+./devtools.sh logs ai-core # 查看 AI-Core 日志
+```
+
+或手动逐个启动：
+
+```bash
+# 编译并运行各服务
+cd backend/memory-service && go run ./cmd/main.go &
+cd backend/tool-engine    && go run ./cmd/main.go &
+cd backend/iot-debug-service && go run ./cmd/main.go &
+cd backend/voice-service  && go run ./cmd/main.go &
+cd backend/ai-core        && go run ./cmd/main.go &
+cd backend/gateway        && go run ./cmd/main.go &
+```
+
+### 3. 启动前端
+
+```bash
+cd frontend/web && npm install && npm run dev
+```
+
+访问 `http://localhost:5173`，默认管理员账户 `admin` / `cyrene-dev-admin`。
+
+### 4. 配置环境变量
+
+```bash
+cp backend/.env.example backend/.env
+# 编辑 backend/.env，填入 LLM API Key 等必要配置
+```
+
+## 服务端口
+
+| 端口 | 服务 |
+|------|------|
+| 5173 | 前端 (Vite dev server) |
+| 8080 | Gateway API |
+| 8081 | AI-Core (LLM 推理) |
+| 8083 | IoT 调试服务 |
+| 8091 | 记忆服务 |
+| 8092 | 工具引擎 |
+| 8093 | 语音服务 |
+| 9090 | DevTools 管理面板 |
+| 5432 | PostgreSQL |
+| 6379 | Redis |
+| 6333 | Qdrant HTTP |
+| 6334 | Qdrant gRPC |
+| 9000 | MinIO S3 |
+| 9001 | MinIO Console |
+| 4222 | NATS |
+| 8222 | NATS Monitoring |
+
+## 技术栈
+
+| 层 | 技术 |
+|----|------|
+| 前端 | React 18, TypeScript, Vite, Tailwind CSS, Zustand |
+| 后端 | Go, Gin, net/http |
+| 数据库 | PostgreSQL + pgvector |
+| 缓存 | Redis |
+| 向量库 | Qdrant |
+| 对象存储 | MinIO |
+| 消息队列 | NATS |
+| 反向代理 | Caddy (生产环境) |
+| 语音 | Edge-TTS / Whisper.cpp |
+
+## 部署
+
+- 开发环境：`docker compose -f docker-compose.dev.yml up -d`
+- 生产环境：`docker compose up -d`（含 Caddy 反向代理 + 自动 TLS）
+
+详见 [Deploy.md](Deploy.md) 和 [Migration.md](Migration.md)（Linux → Windows 迁移指南）。
+
+## License
+
+MIT