From b69b74435aea55dcc42c8017c863106d27afc693 Mon Sep 17 00:00:00 2001 From: Aska Date: Sun, 9 Aug 2026 20:21:54 +0800 Subject: [PATCH] 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 --- README.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 972ccb7..59bf34c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,133 @@ -# Cyrene_v2 +# Cyrene v2 — 昔涟 -喵 \ No newline at end of file +基于 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