TrulyMEM-TrueHumanMEM/docs/架构.md

第一部分：完整架构设计文档 将此内容保存为 架构.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 返回结果同时更新右侧日志和左侧消息。