Fix: F3 tool details toggle, sidebar width, and sync docs with code

- 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
2026-10-15 12:15:32 +00:00 · 2026-04-12 16:01:21 +08:00
parent b7a6a3c1a9
commit b4f509de50
8 changed files with 398 additions and 399 deletions
--- a/docs/架构.md
+++ b/docs/架构.md
@ -1,43 +1,103 @@
---
-
-第一部分：完整架构设计文档
-
-将此内容保存为 架构.md。
-
-```markdown
-# Graph Memory TUI 架构设计
+# 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▼│
-│                                     │ Base URL: ... │
-│  ┌─────────────────────────────┐   │ ───────────── │
-│  │ 🔵 模型: 根据记忆...          │   │ [图操作日志]   │
-│  │                             │   │ ▼ recall     │
-│  │ 是的！根据记忆...              │   │   实体:...    │
-│  │                             │   │   关系:...    │
-│  │ [工具:2次] (F3展开)           │   │ ───────────── │
-│  └─────────────────────────────┘   │ >[查询图...]  │
-│                                     │ F4:执行Cypher │
-│  ┌─────────────────────────────┐   └───────────────┘
+```
+┌─────────────────────────────────────┬─────────────────────┐
+│                                     │ F2:隐藏侧边栏        │
+│  ┌─────────────────────────────┐   │ ────────────────────│
+│  │ 🟠 用户: 量子力学是什么？      │   │ API Key: ***       │
+│  └─────────────────────────────┘   │ 模型: deepseek-chat ▼│
+│                                     │ Base URL: ...       │
+│  ┌─────────────────────────────┐   │ ────────────────────│
+│  │ 🔵 模型: 根据记忆...          │   │ [图操作日志]         │
+│  │                             │   │ ▼ 14:32:15 recall  │
+│  │ 是的！根据记忆...              │   │   实体: 量子力学... │
+│  │                             │   │   关系: 3条         │
+│  │ [工具:2次] (F3展开)          │   │ ───────────────────│
+│  └─────────────────────────────┘   │ >[查询图...]       │
+│                                     │ F4:执行            │
+│  ┌─────────────────────────────┐   └─────────────────────┘
 │  │ 🟠 [输入框...]               │
 │  └─────────────────────────────┘
-│  F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出 │
-└─────────────────────────────────────┴───────────────┘
+│  F1:帮助 F2:隐藏侧边栏 F5:清屏 F6:退出│
+└─────────────────────────────────────┴─────────────────────┘
+```

 ### F2后（右侧折叠）

+```
 ┌─────────────────────────────────────┐
 │                                     │
 │  ┌─────────────────────────────┐   │
@ -49,7 +109,7 @@
 │  │                             │   │
 │  │ 是的！根据记忆...              │   │
 │  │                             │   │
-│  │ [工具:2次] (F3展开)           │   │
+│  │ [工具:2次] (F3展开)          │   │
 │  └─────────────────────────────┘   │
 │                                     │
 │  ┌─────────────────────────────┐   │
@ -58,6 +118,7 @@
 │  F1:帮助 F2:展开侧边栏 F5:清屏 F6:退出│
 │                                     │
 └─────────────────────────────────────┘
+```

 ## 快捷键映射

@ -69,103 +130,88 @@
 | `F4` | 右侧 Cypher 查询框获得焦点（若侧边栏折叠则自动展开） |
 | `F5` | 清屏（保留记忆，清空显示） |
 | `F6` / `Ctrl+C` | 退出程序 |
-| `Tab` | 在左侧输入框和右侧可聚焦控件间循环切换焦点 |
-| `↑/↓` | 浏览历史消息（仅在输入框聚焦时生效） |
-| `Enter` | 发送消息（输入框聚焦时） |
-| `Shift+Enter` | 输入框换行 |

 ## 焦点管理

- **默认焦点**：启动后焦点自动位于左侧底部输入框。
- **焦点切换**：`Tab` 键在输入框、配置区控件（输入框/下拉框）、Cypher 查询框之间循环切换。
- **焦点指示**：当前聚焦的输入框边框高亮（例如亮橙色或加亮背景），状态栏最左侧显示当前焦点位置标识（如 `[Input]`、`[Config]`、`[Cypher]`）。
- **F4 特殊行为**：按下 `F4` 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至右侧的 Cypher 查询输入框。
- **非输入组件按键处理**：当焦点位于消息历史等非输入区域时，按下字母键可自动将焦点切回输入框并插入字符（可选实现，提升体验）。
+- **默认焦点**: 启动后焦点自动位于底部输入框
+- **F4 特殊行为**: 按下 F4 时，若侧边栏处于折叠状态，先自动展开侧边栏，再将焦点移至 Cypher 查询框

 ## 视觉样式

 | 元素 | 样式 |
 |------|------|
-| 用户消息 | 橙色边框 (`border: solid orange`) |
-| 模型消息 | 蓝色边框 (`border: solid blue`) |
-| 底部输入框 | 橙色边框，聚焦时加亮显示 |
+| 用户消息 | 🟠 橙色头部标识 |
+| 模型消息 | 🔵 蓝色头部标识 |
+| 底部输入框 | 橙色边框，聚焦时高亮 |
 | 工具调用摘要 | 灰色括号 `[工具:N次]` |
-| 右侧配置区 | 可折叠，默认折叠 |
+| 右侧边栏 | 深色背景，宽度 70 字符 |
 | 右侧日志区 | 格式化文本，最新在上 |

 ## 组件职责

 ### 左侧区域（主对话区）
- **消息历史**：滚动容器，支持 Markdown 渲染。
- **输入框**：固定底部，橙色边框，支持焦点切换与高亮指示。
- **状态栏**：底部显示当前快捷键提示，以及焦点位置标识（如 `[Input]`）。
+- **MessageHistory**: 滚动容器，显示消息历史
+- **InputBox**: 固定底部，消息输入
+- **LeftPanel**: 左上面板容器

 ### 右侧区域（侧边栏）
- **标题栏**：显示 `F2:隐藏侧边栏`。
- **配置区**：可折叠，包含 API Key、模型选择、Base URL 输入框。
- **图操作日志**：只读，显示最近 N 次工具调用结果（格式化文本），支持滚动。
- **快捷查询**：输入框 + 执行按钮，支持直接执行 Cypher 语句。
-
-## 交互流程
-
-1. 用户输入 → 左侧底部输入框 → `Enter` 发送。
-2. 模型回复 → 左侧消息区，蓝色边框包裹。
-3. 工具调用 → 后台异步执行，左侧显示 `[工具:N次]` 摘要。
-4. 工具详情 → 按 `F3` 展开/折叠，显示完整调用参数和结果。
-5. 右侧日志 → 实时更新，显示格式化后的图操作记录，最新记录置顶。
-6. 侧边栏切换 → `F2` 折叠后完全消失，左侧全屏。
-7. 焦点切换 → `Tab` 循环移动焦点，`F4` 快速定位到 Cypher 查询框。
+- **RightPanel**: 侧边栏容器，可折叠（宽度 70）
+- **ConfigSection**: 配置区（API Key、模型选择、Base URL）
+- **OperationLog**: 图操作日志，只读
+- **CypherQueryBox**: 直接执行 Cypher 查询

 ## 数据流

 ```
-
-用户输入 → ChatInput → GraphMemoryClient.send_message()
-↓
-模型响应 ← OpenAI API
-↓
-有 tool_calls? → execute_tool() → Neo4j
-↓
+用户输入 → 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 (左侧)
-↓
-工具记录 → GraphOpsLog (右侧)
-
+    ↓
+工具记录 → OperationLog (右侧)
 ```

 ## 技术实现

- **框架**：textual（Python TUI 框架）
- **布局**：响应式 CSS-like，右侧固定宽度 40 列
- **状态管理**：全局状态对象，包含当前会话、消息历史、工具调用记录
- **Neo4j 操作**：复用现有 `Neo4jGraph` 类，异步执行
- **LLM 接口**：复用现有 `GraphMemoryClient`，支持流式响应
+- **框架**: 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
 ```

-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 样式定义
+## 工具系统

-```
+### 记忆工具 (6个)
+- `memory_recall` - 检索记忆
+- `memory_commit` - 写入记忆
+- `memory_purge` - 删除记忆
+- `memory_introspect` - 查看状态
+- `memory_archive` - 归档记忆
+- `memory_cleanup` - 清理数据

-## 与现有 Demo 的关系
+### 人设工具 (2个)
+- `persona_update` - 更新人设
+- `persona_clear` - 清除人设

- 保留所有核心逻辑：`Neo4jGraph`、`GraphMemoryClient`、`TOOLS` 定义、`system_prompt`。
- 移除：命令行 `input`/`print` 交互，改为 TUI 组件。
- 新增：异步事件循环、组件状态管理、键盘快捷键处理、焦点管理系统。
- 适配：`execute_tool` 返回结果同时更新右侧日志和左侧消息。
+### 任务工具 (4个)
+- `task_create` - 创建任务
+- `task_set_state` - 设置状态
+- `task_delete` - 删除任务
+- `task_link_info` - 关联信息