安装

前置要求

依赖	说明
Python 3.10+	运行时
PostgreSQL 16+	数据存储
Ollama	本地 LLM 推理（可选，也可纯云端）

克隆项目并安装依赖

git clone https://github.com/wangjiake/JKRiver.git
cd JKRiver
python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt

配置 PostgreSQL

# 创建数据库（根据你的 PostgreSQL 用户名调整）
createdb -h localhost -U your_username Riverse

# 建表
psql -h localhost -U your_username -d Riverse -f agent/schema.sql

Note

Riverse 和 河流算法 — AI 对话历史特别篇 共享同一个数据库。任一项目的建表命令都会创建两个项目所需的全部表。如果你已经运行过另一个项目的建表命令，可以跳过此步骤。

验证建表成功：

psql -h localhost -U your_username -d Riverse -c "\dt"

应看到 conversation_turns、user_profile、observations、fact_edges、memory_clusters 等十五张表左右。

Tip

如需定时技能支持（Telegram Job Queue）：

pip install "python-telegram-bot[job-queue]"

拉取 Ollama 模型（可选）

如果使用本地 LLM：

ollama pull <your-model>         # 例如 qwen2.5:14b, llama3, mistral
ollama pull bge-m3              # 向量嵌入模型（可选）

启动

Web 仪表盘（推荐） — 一键同时启动 FastAPI 后端和 Flask 前端：

python scripts/start_local.py

或单独启动各服务：

uvicorn agent.api:app --host 127.0.0.1 --port 8400    # FastAPI 后端（Web 仪表盘必需）
python web.py                                           # Flask 前端 (http://localhost:1234)
python -m agent.main                                    # CLI 模式
python -m agent.telegram_bot                            # Telegram Bot
python -m agent.discord_bot                             # Discord Bot

Web 仪表盘需要两个服务同时运行。start_local.py 会自动处理。