mirror of
https://gitcode.com/JianFeeeee/TrulyMEM-TrueHumanMEM.git
synced 2026-09-21 09:28:19 +00:00
添加 架构.md
This commit is contained in:
171
架构.md
Normal file
171
架构.md
Normal file
@ -0,0 +1,171 @@
|
||||
---
|
||||
|
||||
第一部分：完整架构设计文档
|
||||
|
||||
将此内容保存为 架构.md。
|
||||
|
||||
```markdown
|
||||
# Graph Memory TUI 架构设计
|
||||
|
||||
## 核心原则
|
||||
- 键盘驱动，零鼠标依赖
|
||||
- 极简视觉，信息密度优先
|
||||
- 工具痕迹默认隐藏，需要时可展开
|
||||
|
||||
## 布局结构
|
||||
|
||||
### 默认视图（右侧展开）
|
||||
|
||||
┌─────────────────────────────────────┬───────────────┐
|
||||
│ │ F2:隐藏侧边栏 │
|
||||
│ ┌─────────────────────────────┐ │ ───────────── │
|
||||
│ │ 🟠 用户: 量子力学是什么？ │ │ API Key: *** │
|
||||
│ └─────────────────────────────┘ │ 模型: deepseek▼│
|
||||
│ │ Base URL: ... │
|
||||
│ ┌─────────────────────────────┐ │ ───────────── │
|
||||
│ │ 🔵 模型: 根据记忆... │ │ [图操作日志] │
|
||||
│ │ │ │ ▼ recall │
|
||||
│ │ 是的！根据记忆... │ │ 实体:... │
|
||||
│ │ │ │ 关系:... │
|
||||
│ │ [工具:2次] (F3展开) │ │ ───────────── │
|
||||
│ └─────────────────────────────┘ │ >[查询图...] │
|
||||
│ │ F4:执行Cypher │
|
||||
│ ┌─────────────────────────────┐ └───────────────┘
|
||||
│ │ 🟠 [输入框...] │
|
||||
│ └─────────────────────────────┘
|
||||
│ F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出 │
|
||||
└─────────────────────────────────────┴───────────────┘
|
||||
|
||||
### F2后（右侧折叠）
|
||||
|
||||
┌─────────────────────────────────────┐
|
||||
│ │
|
||||
│ ┌─────────────────────────────┐ │
|
||||
│ │ 🟠 用户: 量子力学是什么？ │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────┐ │
|
||||
│ │ 🔵 模型: 根据记忆... │ │
|
||||
│ │ │ │
|
||||
│ │ 是的！根据记忆... │ │
|
||||
│ │ │ │
|
||||
│ │ [工具:2次] (F3展开) │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────┐ │
|
||||
│ │ 🟠 [输入框...] │ │
|
||||
│ └─────────────────────────────┘ │
|
||||
│ F1:帮助 F2:展开侧边栏 F5:清屏 F6:退出│
|
||||
│ │
|
||||
└─────────────────────────────────────┘
|
||||
|
||||
## 快捷键映射
|
||||
|
||||
| 按键 | 功能 |
|
||||
|------|------|
|
||||
| `F1` | 显示帮助面板（快捷键列表） |
|
||||
| `F2` | 切换右侧边栏 展开/折叠 |
|
||||
| `F3` | 展开/折叠当前模型回复的工具调用详情 |
|
||||
| `F4` | 右侧 Cypher 查询框获得焦点（若侧边栏折叠则自动展开） |
|
||||
| `F5` | 清屏（保留记忆，清空显示） |
|
||||
| `F6` / `Ctrl+C` | 退出程序 |
|
||||
| `Tab` | 在左侧输入框和右侧可聚焦控件间循环切换焦点 |
|
||||
| `↑/↓` | 浏览历史消息（仅在输入框聚焦时生效） |
|
||||
| `Enter` | 发送消息（输入框聚焦时） |
|
||||
| `Shift+Enter` | 输入框换行 |
|
||||
|
||||
## 焦点管理
|
||||
|
||||
- **默认焦点**：启动后焦点自动位于左侧底部输入框。
|
||||
- **焦点切换**：`Tab` 键在输入框、配置区控件（输入框/下拉框）、Cypher 查询框之间循环切换。
|
||||
- **焦点指示**：当前聚焦的输入框边框高亮（例如亮橙色或加亮背景），状态栏最左侧显示当前焦点位置标识（如 `[Input]`、`[Config]`、`[Cypher]`）。
|
||||
- **F4 特殊行为**：按下 `F4` 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至右侧的 Cypher 查询输入框。
|
||||
- **非输入组件按键处理**：当焦点位于消息历史等非输入区域时，按下字母键可自动将焦点切回输入框并插入字符（可选实现，提升体验）。
|
||||
|
||||
## 视觉样式
|
||||
|
||||
| 元素 | 样式 |
|
||||
|------|------|
|
||||
| 用户消息 | 橙色边框 (`border: solid orange`) |
|
||||
| 模型消息 | 蓝色边框 (`border: solid blue`) |
|
||||
| 底部输入框 | 橙色边框，聚焦时加亮显示 |
|
||||
| 工具调用摘要 | 灰色括号 `[工具:N次]` |
|
||||
| 右侧配置区 | 可折叠，默认折叠 |
|
||||
| 右侧日志区 | 格式化文本，最新在上 |
|
||||
|
||||
## 组件职责
|
||||
|
||||
### 左侧区域（主对话区）
|
||||
- **消息历史**：滚动容器，支持 Markdown 渲染。
|
||||
- **输入框**：固定底部，橙色边框，支持焦点切换与高亮指示。
|
||||
- **状态栏**：底部显示当前快捷键提示，以及焦点位置标识（如 `[Input]`）。
|
||||
|
||||
### 右侧区域（侧边栏）
|
||||
- **标题栏**：显示 `F2:隐藏侧边栏`。
|
||||
- **配置区**：可折叠，包含 API Key、模型选择、Base URL 输入框。
|
||||
- **图操作日志**：只读，显示最近 N 次工具调用结果（格式化文本），支持滚动。
|
||||
- **快捷查询**：输入框 + 执行按钮，支持直接执行 Cypher 语句。
|
||||
|
||||
## 交互流程
|
||||
|
||||
1. 用户输入 → 左侧底部输入框 → `Enter` 发送。
|
||||
2. 模型回复 → 左侧消息区，蓝色边框包裹。
|
||||
3. 工具调用 → 后台异步执行，左侧显示 `[工具:N次]` 摘要。
|
||||
4. 工具详情 → 按 `F3` 展开/折叠，显示完整调用参数和结果。
|
||||
5. 右侧日志 → 实时更新，显示格式化后的图操作记录，最新记录置顶。
|
||||
6. 侧边栏切换 → `F2` 折叠后完全消失，左侧全屏。
|
||||
7. 焦点切换 → `Tab` 循环移动焦点，`F4` 快速定位到 Cypher 查询框。
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
|
||||
用户输入 → ChatInput → GraphMemoryClient.send_message()
|
||||
↓
|
||||
模型响应 ← OpenAI API
|
||||
↓
|
||||
有 tool_calls? → execute_tool() → Neo4j
|
||||
↓
|
||||
最终回复 → MessageHistory (左侧)
|
||||
↓
|
||||
工具记录 → GraphOpsLog (右侧)
|
||||
|
||||
```
|
||||
|
||||
## 技术实现
|
||||
|
||||
- **框架**：textual（Python TUI 框架）
|
||||
- **布局**：响应式 CSS-like，右侧固定宽度 40 列
|
||||
- **状态管理**：全局状态对象，包含当前会话、消息历史、工具调用记录
|
||||
- **Neo4j 操作**：复用现有 `Neo4jGraph` 类，异步执行
|
||||
- **LLM 接口**：复用现有 `GraphMemoryClient`，支持流式响应
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
|
||||
graph-memory-tui/
|
||||
├── main.py # 程序入口
|
||||
├── app.py # Textual App 主类
|
||||
├── widgets/
|
||||
│ ├── chat_history.py # 左侧消息历史
|
||||
│ ├── chat_input.py # 底部输入框
|
||||
│ ├── sidebar.py # 右侧边栏容器
|
||||
│ ├── config_panel.py # 配置区（可折叠）
|
||||
│ ├── ops_log.py # 图操作日志
|
||||
│ ├── cypher_input.py # 快捷查询输入
|
||||
│ └── help_modal.py # 帮助弹窗
|
||||
├── core/
|
||||
│ ├── neo4j_graph.py # 现有 Neo4jGraph 类迁移
|
||||
│ ├── llm_client.py # 现有 GraphMemoryClient 迁移
|
||||
│ └── state.py # 全局状态管理
|
||||
└── styles.css # Textual 样式定义
|
||||
|
||||
```
|
||||
|
||||
## 与现有 Demo 的关系
|
||||
|
||||
- 保留所有核心逻辑：`Neo4jGraph`、`GraphMemoryClient`、`TOOLS` 定义、`system_prompt`。
|
||||
- 移除：命令行 `input`/`print` 交互，改为 TUI 组件。
|
||||
- 新增：异步事件循环、组件状态管理、键盘快捷键处理、焦点管理系统。
|
||||
- 适配：`execute_tool` 返回结果同时更新右侧日志和左侧消息。
|
||||
Reference in New Issue
Block a user