From 14ab28e242e495736a11400d2c6f9df0847de3a2 Mon Sep 17 00:00:00 2001
From: jianf <2198972886@qq.com>
Date: Thu, 9 Apr 2026 05:57:18 +0000
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20=E6=9E=B6=E6=9E=84.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 架构.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 171 insertions(+)
 create mode 100644 架构.md

diff --git a/架构.md b/架构.md
new file mode 100644
index 0000000..c195f86
--- /dev/null
+++ b/架构.md
@@ -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` 返回结果同时更新右侧日志和左侧消息。
\ No newline at end of file