mirror of
https://gitcode.com/JianFeeeee/TrulyMEM-TrueHumanMEM.git
synced 2026-10-15 12:15:32 +00:00
cad39b9ec2
- Fix F3 tool details: use display:none/block instead of re-compose - Increase sidebar width from 40 to 70 for readability - Sync 一键启动指南.md with actual entry points (trulymem_entry.py) - Rewrite 工作记忆链机制说明.md with actual task_* tool APIs - Rewrite 架构.md with actual file structure (38 Python files) - Update docs/README.md with complete feature list
218 lines
9.3 KiB
Markdown
218 lines
9.3 KiB
Markdown
# TrulyMEM 架构设计
|
||
|
||
## 核心原则
|
||
|
||
- 键盘驱动，零鼠标依赖
|
||
- 极简视觉，信息密度优先
|
||
- 工具痕迹默认隐藏，需要时可展开
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
TrulyMEM-TrueHumanMEM/
|
||
├── trulymem_entry.py # 打包入口（独立可执行文件）
|
||
├── graph_memory_tui/ # 核心应用包
|
||
│ ├── app.py # TUI 主应用 (GraphMemoryApp)
|
||
│ ├── main.py # 模块入口
|
||
│ ├── __init__.py
|
||
│ ├── core/ # 核心逻辑
|
||
│ │ ├── __init__.py
|
||
│ │ ├── imports.py # 动态导入（内嵌DB vs Neo4j）
|
||
│ │ ├── embedded_db.py # SQLite 图数据库实现
|
||
│ │ ├── graph_client.py # Neo4j 客户端（可选）
|
||
│ │ ├── optimized_operations.py
|
||
│ │ ├── prompts/ # 提示词管理
|
||
│ │ │ ├── __init__.py
|
||
│ │ │ ├── prompt_manager.py
|
||
│ │ │ └── templates/
|
||
│ │ │ └── system_prompt.md
|
||
│ │ └── tools/ # 工具定义与执行
|
||
│ │ ├── __init__.py
|
||
│ │ ├── memory_tools.py # 6个记忆工具 + 人设/任务工具
|
||
│ │ ├── tool_executor.py # 工具执行器
|
||
│ │ └── tool_limiter.py # 调用限制器
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── __init__.py
|
||
│ │ ├── message.py # Message, ToolCall, ToolResult
|
||
│ │ ├── config.py # AppConfig
|
||
│ │ └── log_entry.py # LogEntry
|
||
│ ├── services/ # 服务层
|
||
│ │ ├── __init__.py
|
||
│ │ ├── config_manager.py # 配置持久化
|
||
│ │ ├── config_service.py
|
||
│ │ ├── chat_service.py
|
||
│ │ └── tool_service.py
|
||
│ ├── handlers/ # 事件处理
|
||
│ │ ├── __init__.py
|
||
│ │ ├── focus_handler.py
|
||
│ │ ├── key_handler.py
|
||
│ │ └── message_handler.py
|
||
│ ├── widgets/ # TUI 组件
|
||
│ │ ├── __init__.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 查询
|
||
│ │ └── status_bar.py # 状态栏
|
||
│ └── styles/ # 样式文件
|
||
│ ├── __init__.py
|
||
│ ├── app.css
|
||
│ ├── components.css
|
||
│ └── messages.css
|
||
├── tests/ # 测试
|
||
├── docs/ # 文档
|
||
├── requirements.txt # 依赖
|
||
└── build_*.{bat,sh} # 打包脚本
|
||
```
|
||
|
||
## 布局结构
|
||
|
||
### 默认视图（右侧展开）
|
||
|
||
```
|
||
┌─────────────────────────────────────┬─────────────────────┐
|
||
│ │ F2:隐藏侧边栏 │
|
||
│ ┌─────────────────────────────┐ │ ────────────────────│
|
||
│ │ 🟠 用户: 量子力学是什么？ │ │ API Key: *** │
|
||
│ └─────────────────────────────┘ │ 模型: deepseek-chat ▼│
|
||
│ │ Base URL: ... │
|
||
│ ┌─────────────────────────────┐ │ ────────────────────│
|
||
│ │ 🔵 模型: 根据记忆... │ │ [图操作日志] │
|
||
│ │ │ │ ▼ 14:32:15 recall │
|
||
│ │ 是的！根据记忆... │ │ 实体: 量子力学... │
|
||
│ │ │ │ 关系: 3条 │
|
||
│ │ [工具:2次] (F3展开) │ │ ───────────────────│
|
||
│ └─────────────────────────────┘ │ >[查询图...] │
|
||
│ │ F4:执行 │
|
||
│ ┌─────────────────────────────┐ └─────────────────────┘
|
||
│ │ 🟠 [输入框...] │
|
||
│ └─────────────────────────────┘
|
||
│ F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出│
|
||
└─────────────────────────────────────┴─────────────────────┘
|
||
```
|
||
|
||
### F2后（右侧折叠）
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ │
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ 🟠 用户: 量子力学是什么？ │ │
|
||
│ └─────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ 🔵 模型: 根据记忆... │ │
|
||
│ │ │ │
|
||
│ │ 是的！根据记忆... │ │
|
||
│ │ │ │
|
||
│ │ [工具:2次] (F3展开) │ │
|
||
│ └─────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ 🟠 [输入框...] │ │
|
||
│ └─────────────────────────────┘ │
|
||
│ F1:帮助 F2:展开侧边栏 F5:清屏 F6:退出│
|
||
│ │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
## 快捷键映射
|
||
|
||
| 按键 | 功能 |
|
||
|------|------|
|
||
| `F1` | 显示帮助面板（快捷键列表） |
|
||
| `F2` | 切换右侧边栏 展开/折叠 |
|
||
| `F3` | 展开/折叠当前模型回复的工具调用详情 |
|
||
| `F4` | 右侧 Cypher 查询框获得焦点（若侧边栏折叠则自动展开） |
|
||
| `F5` | 清屏（保留记忆，清空显示） |
|
||
| `F6` / `Ctrl+C` | 退出程序 |
|
||
|
||
## 焦点管理
|
||
|
||
- **默认焦点**: 启动后焦点自动位于底部输入框
|
||
- **F4 特殊行为**: 按下 F4 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至 Cypher 查询框
|
||
|
||
## 视觉样式
|
||
|
||
| 元素 | 样式 |
|
||
|------|------|
|
||
| 用户消息 | 🟠 橙色头部标识 |
|
||
| 模型消息 | 🔵 蓝色头部标识 |
|
||
| 底部输入框 | 橙色边框，聚焦时高亮 |
|
||
| 工具调用摘要 | 灰色括号 `[工具:N次]` |
|
||
| 右侧边栏 | 深色背景，宽度 70 字符 |
|
||
| 右侧日志区 | 格式化文本，最新在上 |
|
||
|
||
## 组件职责
|
||
|
||
### 左侧区域（主对话区）
|
||
- **MessageHistory**: 滚动容器，显示消息历史
|
||
- **InputBox**: 固定底部，消息输入
|
||
- **LeftPanel**: 左上面板容器
|
||
|
||
### 右侧区域（侧边栏）
|
||
- **RightPanel**: 侧边栏容器，可折叠（宽度 70）
|
||
- **ConfigSection**: 配置区（API Key、模型选择、Base URL）
|
||
- **OperationLog**: 图操作日志，只读
|
||
- **CypherQueryBox**: 直接执行 Cypher 查询
|
||
|
||
## 数据流
|
||
|
||
```
|
||
用户输入 → InputBox.on_input_box_send_message
|
||
↓
|
||
GraphMemoryClient.send_message_with_history()
|
||
↓
|
||
OpenAI API / DeepSeek API
|
||
↓
|
||
检查 tool_calls → execute_tool() → EmbeddedGraphDB / Neo4jGraph
|
||
↓
|
||
循环调用 API 直到无 tool_calls
|
||
↓
|
||
最终回复 → MessageHistory (左侧)
|
||
↓
|
||
工具记录 → OperationLog (右侧)
|
||
```
|
||
|
||
## 技术实现
|
||
|
||
- **框架**: textual（Python TUI 框架）
|
||
- **布局**: CSS-like 样式，右侧固定宽度 70 字符
|
||
- **状态管理**: App 实例持有配置、数据库连接、API 客户端
|
||
- **数据库**: SQLite（默认内嵌）或 Neo4j（可选）
|
||
- **LLM 接口**: OpenAI SDK，兼容 DeepSeek 等
|
||
|
||
## 数据库双模式
|
||
|
||
```python
|
||
# core/imports.py
|
||
if USE_EMBEDDED_DB:
|
||
from .embedded_db import EmbeddedGraphDB as Neo4jGraph # SQLite
|
||
else:
|
||
from .graph_client import Neo4jGraph # Neo4j
|
||
```
|
||
|
||
## 工具系统
|
||
|
||
### 记忆工具 (6个)
|
||
- `memory_recall` - 检索记忆
|
||
- `memory_commit` - 写入记忆
|
||
- `memory_purge` - 删除记忆
|
||
- `memory_introspect` - 查看状态
|
||
- `memory_archive` - 归档记忆
|
||
- `memory_cleanup` - 清理数据
|
||
|
||
### 人设工具 (2个)
|
||
- `persona_update` - 更新人设
|
||
- `persona_clear` - 清除人设
|
||
|
||
### 任务工具 (4个)
|
||
- `task_create` - 创建任务
|
||
- `task_set_state` - 设置状态
|
||
- `task_delete` - 删除任务
|
||
- `task_link_info` - 关联信息
|