137 lines
6.9 KiB
Markdown
137 lines
6.9 KiB
Markdown
# Cyrene v2 — 昔涟
|
||
|
||
> 自托管的「人格化通用智能体运行时」。一个 Go 单二进制，默认以「全能小女友」的人格陪伴你；在聊天/开发/家庭/工作等模式间无感切换；像 OpenClaw 一样接入多个聊天平台（QQ/微信/Telegram…）；各人格独立记忆与情绪、共享同一套能力。
|
||
|
||
**状态**：M0–M11 已完成，M12 收尾中 ｜ **分支**：`dev` ｜ 设计文档见 `DevDocs/00-overview.md`
|
||
|
||
---
|
||
|
||
## 核心特性
|
||
|
||
- **单二进制、进程内协作** — 所有服务同进程打包，仅 gateway `:8080` 对外；模块间走进程内接口 + 事件总线，**零跨进程 IPC**
|
||
- **人格化陪伴** — 多人格 / 情绪状态机 / 好感度；per-persona 记忆隔离，能力全局共享
|
||
- **通用 Agent 运行时** — 多供应商 LLM（per-role 路由 + 降级）、工具调用（8 轮上限）、子代理编排、记忆/RAG（三类作用域 + 向量）、多模态（vision 分层路由 + voice 降级链）
|
||
- **多平台 IM（内置渠道插件）** — OneBot v11 QQ / ClawBot iLink 微信 / Telegram / Webhook，可配置、随二进制分发
|
||
- **语境感知 UI** — 同一会话上下文下切换 聊天/开发/家庭/工作/知识/语音/视觉/子代理监控/设置 模式（Miuix 设计语言）
|
||
- **超级详尽后台管理面板**（`/admin`）— 15 大模块统一管理（RBAC + 审计）
|
||
- **单二进制、多平台** — Linux / Windows / macOS / ARM / Termux
|
||
|
||
---
|
||
|
||
## 本地部署（用户侧）
|
||
|
||
### 1. 前置
|
||
- Go 1.26、Node 22（前端构建用）、Docker（**可选**，用于 PostgreSQL + pgvector / 本地 embedding）。
|
||
|
||
### 2. 配置 `.env`（复制 `.env.example`）
|
||
```bash
|
||
# 认证
|
||
JWT_SECRET=<≥32 字符随机串>
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=<你的密码>
|
||
|
||
# LLM（LLM_PROVIDER 显式声明协议：openai / anthropic）
|
||
LLM_PROVIDER=anthropic
|
||
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
|
||
ANTHROPIC_API_KEY=<key>
|
||
ANTHROPIC_MODEL=deepseek-chat
|
||
# 或 OpenAI 兼容：LLM_PROVIDER=openai + LLM_BASE_URL/API_KEY/MODEL
|
||
|
||
# 数据库（可选增强：PG + pgvector 向量检索）
|
||
DB_PG_URL=postgres://cyrene:cyrene_pass@localhost:5432/cyrene_ai?sslmode=disable
|
||
```
|
||
|
||
### 3. 可选依赖（Docker；PG+pgvector 必需可加，embedding 可选）
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up -d # PG + pgvector
|
||
docker compose -f docker-compose.dev.yml --profile embedding up -d embedding # 可选：本地 embedding(Ollama)
|
||
# 若用 embedding：docker exec -it cyrene-embedding ollama pull <model>
|
||
```
|
||
|
||
### 4. 构建并启动（单二进制，go:embed 前端）
|
||
```bash
|
||
cd frontend/web && npm ci && npm run build && cd ../.. # 产 dist（含拷到 internal/webui/dist）
|
||
go build -ldflags="-s -w" -trimpath -o cyrene ./cmd/cyrene/
|
||
./cyrene # 访问 http://localhost:8080（按 .env 的 PORT）
|
||
```
|
||
|
||
---
|
||
|
||
## Embedding 模型推荐
|
||
|
||
> 用于长记忆/知识库**语义向量检索**（默认不配 = 内置 n-gram 向量，dim=256，离线但质量一般）。
|
||
> 配了 `EMBEDDING_API_URL/MODEL` 后走**真语义**。维度 = 模型 dim，与向量索引一致的；**切换模型会改维度，需清空旧向量数据**。
|
||
|
||
| 模型 | dim | 大小 | 推理内存 | 质量 | 建议 |
|
||
|------|-----|------|---------|------|------|
|
||
| **bge-m3** | 1024 | ~2.2GB(fp16) / ~1.2GB(Q4) | ~2–3GB | ★★★★★（跨语言最强） | ⭐ **首选**（内存充足/GPU 时） |
|
||
| **bge-small-zh-v1.5** | 512 | ~30–100MB | ~几十MB | ★★★★ | ✅ **当前开发环境采用**（内存受限，轻且稳） |
|
||
| nomic-embed-text | 768 | ~270MB | ~400–600MB | ★★★☆ | 可 |
|
||
| mxbai-embed-large | 768 | ~350–670MB | ~0.8–1GB | ★★★★ | 可 |
|
||
|
||
> **说明**：bge-m3 质量最好、跨语言首推；但本开发机**可用内存仅 ~2.9GB（无 GPU、swap 已用 12G）**，跑 bge-m3 会明显 swap、偏慢。故**开发环境用 `bge-small-zh-v1.5`**（轻、快、稳，中文/多语言够用）——质量换性能，生产/有 GPU 再上 bge-m3。
|
||
|
||
`.env` 示例（本地 Ollama）：
|
||
```bash
|
||
EMBEDDING_API_URL=http://localhost:11434/v1
|
||
EMBEDDING_MODEL=bge-small-zh-v1.5
|
||
# EMBEDDING_API_KEY=
|
||
```
|
||
|
||
**llama.cpp 能替代 Ollama 吗？** —— 能。llama.cpp 的 `llama-server`（服务模式）同样暴露 **OpenAI 兼容 `/v1/embeddings`**，用单二进制 + 一个 GGUF 嵌入模型即可：
|
||
```bash
|
||
./llama-server -m bge-small-zh-v1.5-Q4.gguf --embedding --port 11434
|
||
# 然后 EMBEDDING_API_URL=http://localhost:11434/v1 照用
|
||
```
|
||
- **Ollama**：模型管理方便（`pull`）、开箱即用，但常驻偏重。
|
||
- **llama.cpp**：单文件更轻（内存更省，适合本机）、可离线自制 GGUF；但模型要自己下/转（无 registry）。
|
||
- 二者对上层代码**等价**（都是 OpenAI 兼容 embedding 端点）。本机内存吃紧时，llama.cpp 通常更划算。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| 后端 | Go 1.26（单二进制运行时）、进程内总线（可换 NATS）、slog（日志带 `source` 来源标注） |
|
||
| 前端 | React 19、TypeScript、Vite 6、Tailwind 4、Zustand 5、PWA（Miuix 设计语言） |
|
||
| 数据库 | **SQLite 默认**（纯 Go、单二进制）；PG + pgvector 可选增强（配置后真生效） |
|
||
| 多模态 | vision（分层路由：主/视觉/OCR）、async voice（STT→agent→TTS 降级链） |
|
||
| LLM | 多供应商（OpenAI 兼容/订阅/本地/网关）、per-role 路由 + 降级 |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
```
|
||
Cyrene_v2/
|
||
├── cmd/cyrene/ # 唯一入口（mapping 全部子系统 + go:embed 前端）
|
||
├── internal/ # config/logger/platform/db/bus/errors/auth/user/
|
||
│ # runtime(核心: model/agent/loop/tool/guardrail/trace/persist/
|
||
│ # memory/embedding/multimodal/orchestration/exec/task)
|
||
│ # persona/capability/channel/services(gateway/automations/backthink)/iot/webui
|
||
├── plugins/ # tools(basic/io) + channels(qq_obv11/weixin_ilink/telegram/webhook)
|
||
├── pkg/plugins/sdk/ # 插件 SDK（第三方）
|
||
├── frontend/web/ # React SPA（mode 系统）+ /admin 面板（Miuix）
|
||
├── Docs/ # 用户文档（含 api-client.md 客户端 API 契约）
|
||
├── DevDocs/ # 开发文档（本地，不入库）
|
||
└── configs/ # 配置模板（personas/ + users/ 主人档案）
|
||
```
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
| 文档 | 位置 | 说明 |
|
||
|------|------|------|
|
||
| 架构总览/重构蓝图 | `DevDocs/00-overview.md` | 产品定位、架构、渠道插件、后台面板、阶段计划 |
|
||
| 开发约束 | `DevDocs/02-development-constraints.md` | 编码规范 + 性能要求 |
|
||
| **客户端 API** | `Docs/api-client.md` | 跨平台客户端 API 契约（REST/WS/admin，版本化） |
|
||
| 开发铁律 | `AGENTS.md` | 每会话自动注入；含全球红线（单二进制/身份识别/前端 Miuix 等） |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Apache-2.0 © 2026 Aska
|