From 0d8a7592ad43c0ac4f40cbf5b0b04882183c0757 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 12 Apr 2026 16:42:44 +0800 Subject: [PATCH] Docs: sync all docs with actual code implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - README.md: Fix executable download wording (not pre-built) - 架构.md: Remove Cypher references (no Cypher in SQLite mode), note cypher_query_box is display-only - 一键启动指南.md: Remove deleted scripts (start.bat, install.bat), remove made-up startup timings --- README.md | 11 +-- docs/一键启动指南.md | 203 ++++++++++--------------------------------- docs/架构.md | 176 ++++++++++++++++--------------------- 3 files changed, 129 insertions(+), 261 deletions(-) diff --git a/README.md b/README.md index 441b93c..79abf3e 100644 --- a/README.md +++ b/README.md @@ -28,16 +28,13 @@ TrulyMEM (TrueHumanMEM) 是一个让 AI 拥有长期记忆能力的图记忆系 ## 快速开始 -### 方式一：使用可执行文件（推荐） +### 方式一：打包后的可执行文件 -**Windows:** -```bash -# 下载 TrulyMEM.exe -./TrulyMEM.exe -``` +打包后会生成独立可执行文件，可直接运行： -**Linux:** ```bash +# Windows: TrulyMEM.exe +# Linux/macOS: TrulyMEM chmod +x TrulyMEM ./TrulyMEM ``` diff --git a/docs/一键启动指南.md b/docs/一键启动指南.md index 3f4bf81..6ec57d1 100644 --- a/docs/一键启动指南.md +++ b/docs/一键启动指南.md @@ -1,127 +1,50 @@ -# TrulyMEM 一键启动指南 +# TrulyMEM 启动指南 -## 快速开始 +## 运行方式 -### Windows +### 从源码运行 ```bash -# 方法1: 双击运行 -双击 start.bat +# 克隆仓库 +git clone +cd TrulyMEM-TrueHumanMEM -# 方法2: 命令行 -start.bat +# 安装依赖 +pip install -r requirements.txt -# 方法3: Python +# 运行 python trulymem_entry.py ``` -### Linux / macOS +### 打包后运行 + +打包后会生成可执行文件（Windows: TrulyMEM.exe, Linux/macOS: TrulyMEM）： ```bash -# 方法1: Python直接运行 -python3 trulymem_entry.py - -# 方法2: 打包后的可执行文件 +# Linux/macOS chmod +x TrulyMEM ./TrulyMEM + +# Windows +TrulyMEM.exe ``` -## 启动流程 - -``` -[Step 1/3] 检查 Python - ↓ -[Step 2/3] 安装依赖 - - 安装 requirements.txt 中的依赖 - ↓ -[Step 3/3] 启动应用 - ↓ -✅ 系统初始化成功！ -``` - -## 启动时间 - -- **首次启动**: 约1-2分钟（安装依赖） -- **后续启动**: 约30秒 - ## 系统要求 -### 必需 - - **Python 3.8+** -- **DeepSeek API Key** (或 OpenAI 兼容 API Key) +- **API Key**（DeepSeek、OpenAI 或其他兼容 API） -### 可选 +## 首次配置 -- **Git** - 用于克隆仓库 - -## 首次使用 - -### 1. 启动应用 - -```bash -python trulymem_entry.py -``` - -### 2. 配置 API Key - -1. 按 **F2** 展开侧边栏 -2. 在 API Key 输入框输入密钥 -3. 按 **Enter** 保存 - -### 3. 开始对话 - -- 在底部输入框输入消息 -- 按 **Enter** 发送 - -## 获取 API Key - -### DeepSeek - -1. 访问：https://platform.deepseek.com/ -2. 注册账号 -3. 创建 API Key -4. 复制密钥 - -### 其他兼容API - -- OpenAI -- 其他兼容OpenAI格式的API（如 Azure OpenAI） - -## 常见问题 - -### Q: Python 未找到 - -**A:** 安装 Python 3.8+ -- Windows: https://www.python.org/downloads/ -- Linux: `sudo apt install python3` -- macOS: `brew install python3` - -### Q: 依赖安装失败 - -**A:** 手动安装 -```bash -python -m venv venv -source venv/bin/activate # Linux/macOS -venv\Scripts\activate # Windows -pip install -r requirements.txt -``` - -### Q: API Key 无效 - -**A:** 检查API Key格式 -- 应以 `sk-` 开头（DeepSeek/OpenAI） -- 无多余空格 -- 正确复制 - -### Q: 提示"请先配置API Key" - -**A:** 按 F2 展开侧边栏，在 API Key 输入框中输入密钥后按 Enter +1. 运行应用 +2. 按 **F2** 展开侧边栏 +3. 输入 **API Key** +4. 按 **Enter** 保存 ## 快捷键 -| 快捷键 | 功能 | -|--------|------| +| 按键 | 功能 | +|------|------| | F1 | 帮助 | | F2 | 切换侧边栏 | | F3 | 工具详情 | @@ -131,69 +54,39 @@ pip install -r requirements.txt ## 数据存储 -- **数据库**: `graph_memory.db` -- **位置**: 应用目录 -- **格式**: SQLite（内嵌，无需外部数据库） -- **可备份**: 是，直接复制文件即可 +- **数据库**: `graph_memory.db`（应用目录） +- **配置**: `config.json`（应用目录） +- **格式**: SQLite -## 更新应用 +## 常见问题 + +### Python 未找到 + +安装 Python 3.8+：https://www.python.org/downloads/ + +### 依赖安装失败 ```bash -# 拉取最新代码 -git pull - -# 重新安装依赖（如有更新） +python -m venv venv +source venv/bin/activate # Linux/macOS +venv\Scripts\activate # Windows pip install -r requirements.txt - -# 重新启动 -python trulymem_entry.py ``` -## 清理数据 +### API Key 无效 + +检查 API Key 格式，确保无多余空格。 + +## 开发命令 ```bash -# 删除数据库 -rm graph_memory.db - -# 重新启动会创建新数据库 -python trulymem_entry.py -``` - -## 提示 - -- 首次启动需要安装依赖，请耐心等待 -- API Key 只需配置一次（自动保存） -- 数据自动保存，无需手动操作 -- 可以随时按 F6 退出 - -## 从源码运行 - -```bash -# 克隆仓库 -git clone https://github.com/yourusername/trulymem.git -cd trulymem - # 安装依赖 pip install -r requirements.txt -# 运行 -python -m graph_memory_tui.main -# 或 -python trulymem_entry.py +# 运行测试 +pytest tests/ + +# 打包（需 PyInstaller） +python build_windows.bat # Windows +bash build_linux.sh # Linux ``` - -## 打包应用 - -### Windows - -```bash -python build_windows.bat -``` - -### Linux - -```bash -bash build_linux.sh -``` - -开始使用吧！ diff --git a/docs/架构.md b/docs/架构.md index 1319f85..71d1e90 100644 --- a/docs/架构.md +++ b/docs/架构.md @@ -10,8 +10,8 @@ ``` TrulyMEM-TrueHumanMEM/ -├── trulymem_entry.py # 打包入口（独立可执行文件） -├── graph_memory_tui/ # 核心应用包 +├── trulymem_entry.py # 打包入口 +├── graph_memory_tui/ # 核心应用包 (38 个 Python 文件) │ ├── app.py # TUI 主应用 (GraphMemoryApp) │ ├── main.py # 模块入口 │ ├── __init__.py @@ -19,54 +19,54 @@ TrulyMEM-TrueHumanMEM/ │ │ ├── __init__.py │ │ ├── imports.py # 动态导入（内嵌DB vs Neo4j） │ │ ├── embedded_db.py # SQLite 图数据库实现 -│ │ ├── graph_client.py # Neo4j 客户端（可选） +│ │ ├── graph_client.py # Neo4j 客户端（可选，未使用） │ │ ├── optimized_operations.py -│ │ ├── prompts/ # 提示词管理 +│ │ ├── prompts/ # 提示词管理 │ │ │ ├── __init__.py │ │ │ ├── prompt_manager.py │ │ │ └── templates/ │ │ │ └── system_prompt.md -│ │ └── tools/ # 工具定义与执行 +│ │ └── tools/ # 工具定义与执行 │ │ ├── __init__.py -│ │ ├── memory_tools.py # 6个记忆工具 + 人设/任务工具 +│ │ ├── memory_tools.py # 工具定义 │ │ ├── tool_executor.py # 工具执行器 │ │ └── tool_limiter.py # 调用限制器 -│ ├── models/ # 数据模型 +│ ├── models/ # 数据模型 │ │ ├── __init__.py -│ │ ├── message.py # Message, ToolCall, ToolResult -│ │ ├── config.py # AppConfig -│ │ └── log_entry.py # LogEntry -│ ├── services/ # 服务层 +│ │ ├── message.py # Message, ToolCall, ToolResult +│ │ ├── config.py # AppConfig +│ │ └── log_entry.py # LogEntry +│ ├── services/ # 服务层 │ │ ├── __init__.py -│ │ ├── config_manager.py # 配置持久化 +│ │ ├── config_manager.py # 配置持久化 │ │ ├── config_service.py │ │ ├── chat_service.py │ │ └── tool_service.py -│ ├── handlers/ # 事件处理 +│ ├── handlers/ # 事件处理 │ │ ├── __init__.py │ │ ├── focus_handler.py │ │ ├── key_handler.py │ │ └── message_handler.py -│ ├── widgets/ # TUI 组件 +│ ├── widgets/ # TUI 组件 │ │ ├── __init__.py -│ │ ├── left_panel.py # 左侧主对话区 -│ │ ├── right_panel.py # 右侧边栏 +│ │ ├── left_panel.py # 左侧主对话区 +│ │ ├── right_panel.py # 右侧边栏 │ │ ├── message_history.py # 消息历史列表 │ │ ├── message_widget.py # 单条消息组件 -│ │ ├── input_box.py # 底部输入框 -│ │ ├── config_section.py # 配置区 -│ │ ├── operation_log.py # 图操作日志 -│ │ ├── cypher_query_box.py # Cypher 查询 +│ │ ├── input_box.py # 底部输入框 +│ │ ├── config_section.py # 配置区 +│ │ ├── operation_log.py # 图操作日志 +│ │ ├── cypher_query_box.py # 查询框（注：无实际 Cypher 支持） │ │ └── status_bar.py # 状态栏 │ └── styles/ # 样式文件 │ ├── __init__.py │ ├── app.css │ ├── components.css │ └── messages.css -├── tests/ # 测试 -├── docs/ # 文档 -├── requirements.txt # 依赖 -└── build_*.{bat,sh} # 打包脚本 +├── tests/ # 测试（pytest） +├── docs/ # 文档 +├── requirements.txt # 依赖 +└── build_*.{bat,sh} # 打包脚本 ``` ## 布局结构 @@ -76,22 +76,16 @@ TrulyMEM-TrueHumanMEM/ ``` ┌─────────────────────────────────────┬─────────────────────┐ │ │ F2:隐藏侧边栏 │ -│ ┌─────────────────────────────┐ │ ────────────────────│ -│ │ 🟠 用户: 量子力学是什么？ │ │ API Key: *** │ -│ └─────────────────────────────┘ │ 模型: deepseek-chat ▼│ -│ │ Base URL: ... │ -│ ┌─────────────────────────────┐ │ ────────────────────│ -│ │ 🔵 模型: 根据记忆... │ │ [图操作日志] │ -│ │ │ │ ▼ 14:32:15 recall │ -│ │ 是的！根据记忆... │ │ 实体: 量子力学... │ -│ │ │ │ 关系: 3条 │ -│ │ [工具:2次] (F3展开) │ │ ───────────────────│ -│ └─────────────────────────────┘ │ >[查询图...] │ -│ │ F4:执行 │ -│ ┌─────────────────────────────┐ └─────────────────────┘ -│ │ 🟠 [输入框...] │ -│ └─────────────────────────────┘ -│ F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出│ +│ 🟠 14:30:25 │ ────────────────────│ +│ 用户: 量子力学是什么？ │ API Key: *** │ +│ │ 模型: deepseek-chat │ +│ 🔵 14:30:26 │ Base URL: ... │ +│ 是的！根据记忆... │ ────────────────────│ +│ [工具:2次] (F3展开) │ [操作日志] │ +│ │ 14:30:26 recall │ +│ ┌─────────────────────────────┐ │ 实体: 量子力学 │ +│ │ 🟠 [输入框...] │ │ ───────────────────│ +│ └─────────────────────────────┘ │ >[查询...] │ └─────────────────────────────────────┴─────────────────────┘ ``` @@ -99,101 +93,85 @@ TrulyMEM-TrueHumanMEM/ ``` ┌─────────────────────────────────────┐ +│ 🟠 14:30:25 │ +│ 用户: 量子力学是什么？ │ │ │ -│ ┌─────────────────────────────┐ │ -│ │ 🟠 用户: 量子力学是什么？ │ │ -│ └─────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────┐ │ -│ │ 🔵 模型: 根据记忆... │ │ -│ │ │ │ -│ │ 是的！根据记忆... │ │ -│ │ │ │ -│ │ [工具:2次] (F3展开) │ │ -│ └─────────────────────────────┘ │ +│ 🔵 14:30:26 │ +│ 是的！根据记忆... │ +│ [工具:2次] (F3展开) │ │ │ │ ┌─────────────────────────────┐ │ │ │ 🟠 [输入框...] │ │ │ └─────────────────────────────┘ │ -│ F1:帮助 F2:展开侧边栏 F5:清屏 F6:退出│ -│ │ +│ F1:帮助 F2:展开 F5:清屏 F6:退出 │ └─────────────────────────────────────┘ ``` -## 快捷键映射 +## 快捷键 | 按键 | 功能 | |------|------| -| `F1` | 显示帮助面板（快捷键列表） | -| `F2` | 切换右侧边栏 展开/折叠 | -| `F3` | 展开/折叠当前模型回复的工具调用详情 | -| `F4` | 右侧 Cypher 查询框获得焦点（若侧边栏折叠则自动展开） | -| `F5` | 清屏（保留记忆，清空显示） | -| `F6` / `Ctrl+C` | 退出程序 | - -## 焦点管理 - -- **默认焦点**: 启动后焦点自动位于底部输入框 -- **F4 特殊行为**: 按下 F4 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至 Cypher 查询框 - -## 视觉样式 - -| 元素 | 样式 | -|------|------| -| 用户消息 | 🟠 橙色头部标识 | -| 模型消息 | 🔵 蓝色头部标识 | -| 底部输入框 | 橙色边框，聚焦时高亮 | -| 工具调用摘要 | 灰色括号 `[工具:N次]` | -| 右侧边栏 | 深色背景，宽度 70 字符 | -| 右侧日志区 | 格式化文本，最新在上 | +| F1 | 显示帮助 | +| F2 | 切换侧边栏 | +| F3 | 工具详情 | +| F4 | 聚焦查询框 | +| F5 | 清屏 | +| F6 | 退出 | ## 组件职责 -### 左侧区域（主对话区） -- **MessageHistory**: 滚动容器，显示消息历史 -- **InputBox**: 固定底部，消息输入 -- **LeftPanel**: 左上面板容器 +### 左侧区域 +- **MessageHistory**: 消息历史容器 +- **InputBox**: 底部输入框 -### 右侧区域（侧边栏） -- **RightPanel**: 侧边栏容器，可折叠（宽度 70） +### 右侧区域 +- **RightPanel**: 侧边栏容器（宽度 70） - **ConfigSection**: 配置区（API Key、模型选择、Base URL） -- **OperationLog**: 图操作日志，只读 -- **CypherQueryBox**: 直接执行 Cypher 查询 +- **OperationLog**: 操作日志 +- **CypherQueryBox**: 查询框（注：目前仅作展示，无 Cypher 查询功能） ## 数据流 ``` -用户输入 → InputBox.on_input_box_send_message +用户输入 → InputBox → app.on_input_box_send_message ↓ GraphMemoryClient.send_message_with_history() ↓ OpenAI API / DeepSeek API ↓ -检查 tool_calls → execute_tool() → EmbeddedGraphDB / Neo4jGraph +检查 tool_calls → execute_tool() → EmbeddedGraphDB ↓ 循环调用 API 直到无 tool_calls ↓ -最终回复 → MessageHistory (左侧) - ↓ -工具记录 → OperationLog (右侧) +最终回复 → MessageHistory + OperationLog ``` -## 技术实现 +## 技术栈 -- **框架**: textual（Python TUI 框架） -- **布局**: CSS-like 样式，右侧固定宽度 70 字符 -- **状态管理**: App 实例持有配置、数据库连接、API 客户端 -- **数据库**: SQLite（默认内嵌）或 Neo4j（可选） -- **LLM 接口**: OpenAI SDK，兼容 DeepSeek 等 +| 技术 | 用途 | +|------|------| +| Python 3.8+ | 编程语言 | +| Textual 0.47+ | TUI 框架 | +| SQLite | 图数据库（默认内嵌） | +| OpenAI SDK | API 调用（兼容 DeepSeek） | +| Neo4j | 可选数据库（需 Docker） | +| PyInstaller | 打包 | -## 数据库双模式 +## 数据库模式 + +### 默认：SQLite 内嵌 ```python # core/imports.py if USE_EMBEDDED_DB: - from .embedded_db import EmbeddedGraphDB as Neo4jGraph # SQLite -else: - from .graph_client import Neo4jGraph # Neo4j + from .embedded_db import EmbeddedGraphDB as Neo4jGraph +``` + +### 可选：Neo4j + +```bash +export USE_EMBEDDED_DB=false +docker run -d --name neo4j -p 7474:7474 -p 7687:7687 neo4j:latest ``` ## 工具系统