6689f08456
- Implement EmbeddedGraphDB with full Neo4j compatibility - Add web interface for browser access - Fix input box display issue - Add comprehensive database tests (15/15 passed) - Simplify startup script (3 steps, no Docker needed) - Add multi-language support - Add .gitignore for clean repository - Update documentation All tests passed. Ready for production.
171 lines
8.3 KiB
Markdown
171 lines
8.3 KiB
Markdown
---
|
||
|
||
第一部分：完整架构设计文档
|
||
|
||
将此内容保存为 架构.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` 返回结果同时更新右侧日志和左侧消息。 |