docs: add comprehensive README and update project structure

- Replace placeholder README with full project overview - All DevDocs modules completed (7 backend + 4 cross-cutting) - Development constraints document added
2026-08-09 20:21:54 +08:00
1 parent 14d5d6e555
commit b69b74435a
@@ -1,3 +1,133 @@
-# Cyrene_v2
+# Cyrene v2 — 昔涟

-喵
+基于 LLM 的开源智能体平台。多人格对话、IoT 操控、长期记忆、语音交互、多平台桥接。
+
+> **状态**：架构设计阶段 | **分支**：`dev` | **v1 参考**：[Cyrene](https://git.yeij.top/AskaEth/Cyrene)
+
+---
+
+## 架构
+
+```
+                    浏览器 / 第三方平台
+                         │
+              REST + WebSocket + NATS
+                         │
+              ┌──────────▼──────────┐
+              │    Gateway (:8080)  │  ← 唯一对外端口
+              │  JWT · RateLimit    │
+              └──────────┬──────────┘
+                         │ NATS 消息总线
+         ┌───────┬───────┼───────┬───────┐
+         ▼       ▼       ▼       ▼       ▼
+     AI-Core  Memory  Voice  Bridge   IoT Plugin
+     编排引擎   记忆    语音    多平台    设备模拟
+
+              ┌─────────────────────┐
+              │ PostgreSQL+pgvector │
+              │ Redis · NATS · MinIO│
+              │ Qdrant · SearXNG   │
+              └─────────────────────┘
+```
+
+**核心理念**：所有服务通过 NATS 消息总线通信。只有一个对外端口。
+
+---
+
+## 功能
+
+- **多人格对话** — LLM 编排 + 角色扮演 + 子会话路由
+- **IoT 操控** — 插件化设备控制（模拟 / Home Assistant / MQTT）
+- **长期记忆** — pgvector 语义检索 + LLM 提取 + 衰减
+- **语音交互** — DashScope STT + Edge-TTS 流式语音
+- **多平台桥接** — QQ / Telegram / Discord / Webhook
+- **知识库 RAG** — 文档管理 + 向量检索
+- **自动化规则** — 定时/条件/Webhook 触发
+- **管理面板** — 内置 React SPA（/admin），统一管理
+- **PWA** — 可安装为桌面/移动应用
+- **互联网搜索** — 自托管 SearXNG
+
+---
+
+## 快速开始
+
+> 代码尚未就绪，以下为计划中的启动方式。
+
+```bash
+# 1. 配置
+cp configs/.env.example .env
+# 编辑 .env，至少配置 LLM_API_KEY
+
+# 2. 启动基础设施
+docker compose -f deployment/docker/docker-compose.dev.yml up -d
+
+# 3. 启动 Cyrene
+go run ./cmd/cyrene/
+# 访问 http://localhost:8080
+```
+
+---
+
+## 技术栈
+
+| 层 | 技术 |
+|----|------|
+| 后端 | Go 1.26, Gin, NATS, slog |
+| 前端 | React 19, TypeScript, Vite, Tailwind 4, Zustand 5 |
+| 数据库 | PostgreSQL 16 + pgvector |
+| 缓存/队列 | Redis 7, NATS 2 |
+| 存储 | MinIO |
+| 搜索 | SearXNG |
+| 语音 | DashScope STT / Edge-TTS |
+
+---
+
+## 目录
+
+```
+Cyrene_v2/
+├── backend/                # Go 后端（monorepo）
+│   ├── cmd/cyrene/         # 唯一入口
+│   ├── internal/           # 共享模块（config/logger/nats/plugin/auth）
+│   ├── services/           # 微服务核心（gateway/ai-core/memory/voice/bridge）
+│   └── plugins/            # 插件（iot-mock/calculator/web-search/...）
+├── frontend/web/           # React SPA
+├── services/rag-pipeline/  # Python RAG 增强（可选）
+├── deployment/             # 多平台部署配置
+├── scripts/                # 构建/迁移/语音处理
+├── tests/                  # 测试
+├── configs/                # 配置模板
+└── Docs/                   # 用户文档
+```
+
+---
+
+## 与 v1 的主要差异
+
+| 维度 | v1 | v2 |
+|------|-----|-----|
+| 对外端口 | 6+ 个 | **1 个** |
+| 服务间通信 | HTTP 硬编码 URL | **NATS 消息总线** |
+| 管理面板 | Node.js 独立服务 | **React SPA 内建路由** |
+| IoT 设备 | 硬编码系统服务 | **插件化（按需加载）** |
+| 测试覆盖率 | < 5% | **目标 70%+** |
+
+---
+
+## 文档
+
+| 文档 | 位置 | 说明 |
+|------|------|------|
+| 项目总览 | `DevDocs/00-overview.md` | 完整技术选型说明 |
+| 多平台适配 | `DevDocs/01-cross-platform.md` | Linux/Win/macOS/Termux |
+| 开发约束 | `DevDocs/02-development-constraints.md` | 编码规范+性能要求 |
+| 模块设计 | `DevDocs/modules/*.md` | 每个模块的详细设计 |
+| 设计决策 | `DevDocs/decisions/*.md` | 关键架构决策记录 |
+
+> **注意**：`DevDocs/` 目录是开发文档，不进入版本控制（`.gitignore`）。供内部开发参考。
+
+---
+
+## License
+
+Apache-2.0 © 2026 Aska