docs: Update README and clean up documentation

- Rewrite README with clear structure - Remove redundant documentation files - Update startup guide - Add API documentation - Add FAQ section - Simplify project structure
2026-04-10 15:55:07 +08:00
parent 46c58bccc5
commit e9df29a988
6 changed files with 306 additions and 1124 deletions
--- a/README.md
+++ b/README.md
@ -4,127 +4,24 @@
 一个让 AI 拥有自知、可塑、有分寸感长期记忆的图记忆系统，配备现代化终端用户界面。
 ## ✨ 特性
 - 🖥️ **现代化TUI界面** - 基于Textual框架的终端界面
 - 💾 **内嵌数据库** - SQLite实现，无需Docker/Neo4j
 - 🌐 **Web接口** - 支持浏览器访问
 - 🚀 **一键启动** - 3步骤完成，30秒启动
 - 🌍 **跨平台** - 支持Windows/Linux/macOS
 - 📊 **实时可视化** - 消息、工具调用实时显示
 - 🔧 **完整功能** - 记忆检索、写入、删除、归档
 ## 📖 目录
 - [背景与理念](#背景与理念)
 - [核心特性](#核心特性)
 - [架构设计](#架构设计)
 - [快速开始](#快速开始)
- [工具说明](#工具说明)
+- [使用方法](#使用方法)
- [图数据库模式](#图数据库模式)
+- [功能说明](#功能说明)
- [与传统方案的对比](#与传统方案的对比)
+- [API接口](#api接口)
- [路线图](#路线图)
+- [配置说明](#配置说明)
- [限制与注意事项](#限制与注意事项)
+- [开发指南](#开发指南)
 ---
 ## 背景与理念
 ### 传统 AI 记忆的三大困境
 | 困境 | 表现 | 根源 |
 |------|------|------|
 | 上下文窗口天花板 | 对话越长，记忆越模糊，成本越高 | 依赖原始对话历史传递信息 |
 | "录音机式"记忆 | 仅能复述原文，无法理解关系与联想 | 向量检索只做语义匹配，缺乏结构 |
 | "不懂认错"的固执 | 错误信息无法修正，矛盾记录并存 | 记忆只有"写入"和"读取"，没有"更新"和"删除" |
 ### 我们的答案：像人一样记忆
 TrueHumanMEM 的设计哲学不是做一个更"精准"的记忆数据库，而是让 AI 具备以下四种人类记忆的本质特征：
 1. **选择性** —— 只记录有价值的关系，不记流水账。
 2. **模糊性** —— 能推断，也能坦诚地表达不确定性。
 3. **可塑性** —— 允许修正、覆盖旧记忆，认知随对话演化。
 4. **自明性** —— 能区分"用户陈述"与"模型推断"，记忆自知来源。
 TrueHumanMEM 不是更强大的搜索引擎，而是更像人的记忆伙伴。
 ---
 ## 核心特性
 ### 🧠 最小化上下文窗口依赖
 上下文仅用于协议适配，不承载对话记忆。
 表面上，系统仍通过 messages 列表与 LLM API 交互——这是当前 Function Calling 接口的标准要求。但实际上：
 - **不传递历史对话**：每轮请求的 messages 仅包含系统提示、当前用户输入、上一轮的工具调用结果。
 - **不累积轮次**：过去的用户消息和助手回复不会被追加到后续请求中。模型无法通过翻看聊天记录来回忆信息。
 - **记忆外置**：所有需要跨轮次保留的事实、关系、偏好，全部写入 Neo4j 图数据库。当需要时，模型必须显式调用 memory_recall 工具，主动从图库中检索。
 这种设计确保了：上下文长度不随对话轮次线性增长，记忆能力不囿于窗口上限。
 ### 🔗 结构化关系推理
 - 以三元组 (主体, 关系, 客体) 存储事实，天然支持多跳路径查询。
 - 即使信息未被用户直接陈述，系统也可通过路径组合进行推断。
 ### ✍️ 自主记忆决策
 - 模型通过函数调用机制自主触发检索、写入或修正操作，避免硬编码管道。
 - 基于对话语境判断"什么值得记"、"何时该查"。
 ### 🔄 完整的记忆生命周期管理
 | 状态 | 含义 | 操作 |
 |------|------|------|
 | active | 当前有效记忆 | 写入时创建 |
 | deleted | 软删除，逻辑失效 | 软删除操作 |
 | superseded | 已被新关系替代 | 替代模式操作 |
 | archived | 归档，低频访问 | 归档操作 |
 | 物理删除 | 彻底清理 | 清理操作 |
 ### 🎯 置信度与来源标记
 - 每条关系携带数值置信度，存储层区分"确凿"与"推测"。
 - 表达层将不确定性转化为自然语言语气，实现从存储到表达的完整自知闭环。
 ### 🔒 隐私友好，数据可本地化
 - 图库可部署于本地或私有环境，记忆数据由用户掌控。
 ### 🖥️ 现代化终端界面
 - 基于 Textual 框架的 TUI 界面
 - 实时消息显示与工具调用可视化
 - 侧边栏配置与操作日志
 - 跨平台支持（Windows/Linux/macOS）
 ---
 ## 架构设计
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                        用户输入                              │
 └─────────────────────────┬───────────────────────────────────┘
                            ▼
 ┌─────────────────────────────────────────────────────────────┐
 │              LLM API (with Function Calling)                │
 │  ┌───────────────────────────────────────────────────────┐  │
 │  │              System Prompt: 记忆助手角色               │  │
 │  │  + 当前用户输入 + 上一轮工具调用结果（极简上下文）      │  │
 │  └───────────────────────────────────────────────────────┘  │
 └─────────────────────────┬───────────────────────────────────┘
                            │ 模型自主决策调用工具
            ┌───────────────┼───────────────┬───────────────┐
            ▼               ▼               ▼               ▼
      ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
      │   recall   │  │   commit   │  │   purge    │  │ introspect │
      └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘
            │               │               │               │
            └───────────────┴───────┬───────┴───────────────┘
                                    ▼
                        ┌─────────────────────────┐
                        │      Neo4j 图数据库      │
                        │  (实体节点 + 关系边)     │
                        └─────────────────────────┘
 ```
 - **轻量级上下文**：每轮仅包含系统提示、上一轮工具调用结果、当前用户输入。过往对话历史不累积。
 - **持续工具调用循环**：模型可在一次回复中调用多个工具，直至给出最终文本回复。
 - **可观测性支持**：所有工具调用记录于会话日志，支持审计追踪与调试回溯。
 ---
@ -133,10 +30,9 @@ TrueHumanMEM 不是更强大的搜索引擎，而是更像人的记忆伙伴。
 ### 前置要求
 - **Python 3.8+**
- **Docker** (用于 Neo4j 数据库)
+- **DeepSeek API Key**（或兼容OpenAI格式的API）
 - **DeepSeek API Key**（或兼容 OpenAI 格式的任意 LLM API）
-### 一键启动（推荐）
+### 一键启动
 #### Windows
 ```bash
@ -157,188 +53,227 @@ chmod +x start.sh
 python3 start.py
 ```
-启动脚本会自动：
+### 启动流程
 1. ✅ 启动 Docker (优先WSL，回退到Docker Desktop)
 2. ✅ 启动 Neo4j 数据库
 3. ✅ 创建虚拟环境
 4. ✅ 安装依赖
 5. ✅ 启动 TUI 应用
-### 手动启动
+```
 [Step 1/3] 检查 Python
 [Step 2/3] 设置虚拟环境
 [Step 3/3] 启动应用
-#### 1. 克隆仓库
+✅ 系统初始化成功！
-```bash
+• 数据库: 内嵌SQLite (graph_memory.db)
-git clone https://github.com/your-org/TrueHumanMEM.git
+• API Key: 未配置
 cd TrueHumanMEM
 ```
-#### 2. 安装依赖
+---
 ## 使用方法
 ### 1. 配置 API Key
 1. 按 **F2** 展开侧边栏
 2. 点击 **"配置"**
 3. 输入你的 **DeepSeek API Key**
 4. 按 **Enter** 保存
 ### 2. 开始对话
 - 输入消息
 - 按 **Enter** 发送
 - 查看AI响应和工具调用
 ### 3. 快捷键
 | 快捷键 | 功能 |
 |--------|------|
 | F1 | 帮助 |
 | F2 | 切换侧边栏 |
 | F3 | 工具详情 |
 | F4 | 查询框 |
 | F5 | 清屏 |
 | F6 | 退出 |
 ---
 ## 功能说明
 ### 记忆管理工具
 | 工具 | 功能 | 参数 |
 |------|------|------|
 | memory_recall | 检索记忆 | query_intent, depth |
 | memory_commit | 写入记忆 | triplets, confidence |
 | memory_purge | 删除记忆 | criteria, mode |
 | memory_introspect | 查看状态 | - |
 | memory_archive | 归档记忆 | days |
 | memory_cleanup | 清理数据 | dry_run |
 ### 数据库
 **内嵌SQLite数据库：**
 - 文件：`graph_memory.db`
 - 无需配置
 - 自动创建
 - 本地存储
 **数据结构：**
 - 实体（entities）：name, type, mention_count
 - 关系（relations）：source, target, type, confidence, status
 ---
 ## API接口
 ### Web接口
 启动后访问：`http://localhost:5000`
 ### REST API
 ```bash
 # 检索记忆
 POST /api/memory/recall
 {
  "query_intent": "Python,AI"
 }
 # 写入记忆
 POST /api/memory/commit
 {
  "triplets": [
    {"subject": "用户", "relation": "喜欢", "object": "Python"}
  ]
 }
 # 查看状态
 GET /api/memory/introspect
 # 获取配置
 GET /api/config
 ```
 ---
 ## 配置说明
 ### 环境变量
 创建 `.env` 文件：
 ```bash
 # API配置
 DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxx
 DEEPSEEK_BASE_URL=https://api.deepseek.com
 MODEL_NAME=deepseek-chat
 # 数据库配置（可选）
 USE_EMBEDDED_DB=true
 ```
 ### 切换数据库
 **使用内嵌数据库（默认）：**
 ```bash
 USE_EMBEDDED_DB=true
 ```
 **使用Neo4j（需要Docker）：**
 ```bash
 USE_EMBEDDED_DB=false
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USER=neo4j
 NEO4J_PASSWORD=graphmemory123
 ```
 ---
 ## 开发指南
 ### 项目结构
 ```
 graph_enable_ability/
 ├── graph_memory_tui/      # TUI应用
 │   ├── core/              # 核心逻辑
 │   │   ├── embedded_db.py # 内嵌数据库
 │   │   └── imports.py
 │   ├── web/               # Web接口
 │   ├── widgets/           # UI组件
 │   ├── styles/            # 样式
 │   └── app.py
 ├── tests/                 # 测试
 ├── docs/                  # 文档
 ├── start.bat              # Windows启动
 ├── start.sh               # Linux/macOS启动
 └── start.py               # 跨平台启动
 ```
 ### 运行测试
 ```bash
 # 安装依赖
 pip install -r requirements.txt
 # 运行测试
 pytest tests/
 ```
-#### 3. 启动 Neo4j
+### 开发模式
 ```bash
 # 使用Docker
 docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/graphmemory123 \
  neo4j:latest
 ```
 #### 4. 配置环境变量
 ```bash
-export DEEPSEEK_API_KEY="your-api-key"
+# 创建虚拟环境
-export NEO4J_URI="bolt://localhost:7687"
+python -m venv venv
-export NEO4J_USER="neo4j"
+source venv/bin/activate  # Linux/macOS
-export NEO4J_PASSWORD="graphmemory123"
+venv\Scripts\activate     # Windows
 ```
-#### 5. 运行应用
+# 安装依赖
 pip install -r requirements.txt
-**TUI 界面（推荐）**
+# 运行应用
 ```bash
 python -m graph_memory_tui.main
 ```
-**命令行 Demo**
+---
 ```bash
 python graph_memory_demo.py
 ```
-### 使用 TUI 界面
+## 常见问题
-1. **配置 API Key**
+### Q: 启动时显示"API Key 未配置"？
   - 按 F2 展开侧边栏
   - 点击"配置"
   - 输入你的 DeepSeek API Key
   - 按 Enter 保存
-2. **开始对话**
+**A:** 按F2打开侧边栏，在配置区输入API Key，按Enter保存。
   - 输入消息
   - 按 Enter 发送
   - 查看工具调用和AI响应
-3. **快捷键**
+### Q: 数据保存在哪里？
-   - F1: 帮助
+
-   - F2: 切换侧边栏
+**A:** 数据保存在 `graph_memory.db` 文件中，可以备份或迁移。
-   - F3: 工具详情
+
-   - F5: 清屏
+### Q: 如何查看数据库内容？
-   - F6: 退出
+
 **A:** 使用SQLite工具打开 `graph_memory.db`，或使用 `memory_introspect` 工具。
 ### Q: 支持哪些API？
 **A:** 支持所有兼容OpenAI格式的API，如DeepSeek、OpenAI等。
 ---
-## 工具说明
+## 技术栈
-系统向模型暴露 6 个记忆管理工具，由模型根据对话需求自主调用。
+- **Python 3.8+** - 编程语言
-
+- **Textual** - TUI框架
-| 工具名 | 描述 | 关键参数 |
+- **SQLite** - 内嵌数据库
-|--------|------|----------|
+- **Flask** - Web框架
-| memory_recall | 检索相关子图 | query_intent (str): 关键词意图<br>seed_entities (List[str]): 起始实体<br>depth (int): 遍历深度<br>time_range (str, 可选): 时间范围 |
+- **OpenAI SDK** - API调用
 | memory_commit | 写入三元组 | triplets (List[Dict]): 每项含 subject, relation, object, confidence (float, 0.0-1.0) |
 | memory_purge | 删除或替代记忆 | criteria (Dict): 匹配条件<br>mode (str): soft / supersede<br>new_relation (Dict, 可选): 替代关系 |
 | memory_introspect | 查看当前会话元数据 | session_id (str, 可选) |
 | memory_archive | 归档旧关系 | days (int): 归档天数阈值 |
 | memory_cleanup | 物理清理已删除数据 | dry_run (bool): 预览模式 |
 ---
 ## 图数据库模式
 ### 节点（Entity）
 | 属性 | 类型 | 描述 |
 |------|------|------|
 | name | String | 实体唯一标识 |
 | type | String | 实体类型（模型动态提议） |
 | created_at | DateTime | 创建时间 |
 | updated_at | DateTime | 最后更新时间 |
 | mention_count | Integer | 被提及次数 |
 ### 关系（RELATES）
 | 属性 | 类型 | 描述 |
 |------|------|------|
 | type | String | 关系类型 |
 | created_at | DateTime | 关系创建时间 |
 | session_id | String | 所属会话 ID |
 | turn_id | Integer | 会话内轮次编号 |
 | status | String | active / deleted / superseded / archived |
 | confidence | Float | 置信度 0.0 ~ 1.0 |
 | date_bucket | String | 日期分桶 (YYYY-MM-DD) |
 | supersedes | Integer | （可选）指向替代关系 ID |
 **索引与约束**：实体名与会话 ID 唯一约束；关系属性建立索引以确保查询性能。
 ---
 ## 与传统方案的对比
 | 维度 | 传统上下文窗口 | 向量 RAG | TrueHumanMEM |
 |------|----------------|----------|--------------|
 | 记忆跨度 | 受窗口长度限制 | 检索精度随数据量下降 | 跨会话持久化，图结构保证精度 |
 | 关系推理 | 依赖模型上下文推理 | 仅语义相似匹配 | 原生多跳路径查询 |
 | 记忆修正 | 只能追加新消息 | 旧向量无法更新 | 完整状态机（软删除、替代） |
 | 不确定性表达 | 无 | 无 | 置信度 + 语气标记 |
 | 数据主权 | 全部上传 API | 向量库常为云端 | 图库可本地化部署 |
 | 可解释性 | 黑盒 | 难以解释召回原因 | 显式关系路径，可审计 |
 ---
 ## 路线图
 ### Phase 1: 核心稳定（当前）
 - [X] 核心六工具 + Neo4j 集成
 - [X] 函数调用驱动自主决策
 - [X] 软删除与替代模式
 - [X] TUI 界面
 - [X] 一键启动脚本
 - [X] 多语言支持
 ### Phase 2: 体验优化
 - [ ] 来源标记增强：存储层显式区分"用户陈述"与"模型推断"
 - [ ] 端侧轻量化：适配轻量级图存储，支持资源受限环境
 - [ ] 全文索引优化：提升大规模数据检索性能
 - [ ] 人工干预接口：支持显式记忆编辑与强制检索指令
 ### Phase 3: 能力扩展
 - [ ] 多模态记忆：支持非文本记忆关联
 - [ ] 可视化界面：图形化展示个人知识图谱
 - [ ] 流式输出：实时显示AI响应
 ---
 ## 限制与注意事项
 - **事实准确性依赖底层模型能力**：系统通过 LLM 进行关系抽取与推断，可能产生错误事实，建议关键信息人工复核。
 - **函数调用能力依赖**：模型需支持稳定的 function calling 接口，不同 LLM 表现可能存在差异。
 - **性能基准待补充**：当前版本未针对超大规模图谱（千万级节点）进行优化，极端场景下查询延迟可能上升。
 - **隐私边界**：本地部署仅保证数据存储位置可控，LLM API 调用仍受服务商条款约束。
 ---
 ## 文档
 详细文档请查看 `docs/` 目录：
 - [架构设计](docs/架构.md)
 - [一键启动指南](docs/一键启动指南.md)
 - [API配置指南](docs/API配置指南.md)
 ---
 ## 贡献
 欢迎任何形式的贡献！请先阅读贡献指南。
 ---
 ## 许可证
-本项目采用 MIT License。
+MIT License
 ---
 ## 贡献
 欢迎提交Issue和Pull Request！
 ---
--- a/docs/API配置指南.md
+++ b/docs/API配置指南.md
@ -1,243 +0,0 @@
 # API Key 配置指南
 ## ❌ 连接错误原因
 **错误信息：** `Connection error`
 **可能原因：**
 1. ❌ API Key 未配置
 2. ❌ API Key 无效
 3. ❌ 网络无法访问 API
 4. ❌ API 服务器暂时不可用
 ## ✅ 解决方法
 ### 方法1：在 TUI 中配置（推荐）
 **步骤：**
 1. **按 F2** - 展开右侧边栏
 2. **点击"配置"** - 展开配置区域
 3. **输入 API Key** - 在输入框输入你的密钥
 4. **按 Tab** - 保存并应用
 **详细操作：**
 ```
 启动应用
    ↓
 看到欢迎消息
    ↓
 按 F2 键
    ↓
 右侧出现侧边栏
    ↓
 点击"配置"标题
    ↓
 看到三个输入框：
 ┌─────────────────────┐
 │ API Key:            │
 │ [******************]│ ← 输入你的 Key
 │                     │
 │ 模型:               │
 │ [deepseek-chat    ] │
 │                     │
 │ Base URL:           │
 │ [https://api...    ]│
 └─────────────────────┘
    ↓
 输入 API Key: sk-xxxxxxxxxxxxx
    ↓
 按 Tab 键
    ↓
 看到通知："✅ 配置已更新并应用"
    ↓
 配置完成！
 ```
 ### 方法2：环境变量配置
 **Windows:**
 ```cmd
 setx DEEPSEEK_API_KEY "sk-xxxxxxxxxxxxx"
 ```
 **Linux/macOS:**
 ```bash
 export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxx"
 ```
 **注意：** 设置环境变量后需要重启终端。
 ### 方法3：配置文件
 **创建配置文件：**
 **Windows:**
 ```
 C:\Users\<你的用户名>\.graph_memory_tui\config.json
 ```
 **Linux/macOS:**
 ```
 ~/.graph_memory_tui/config.json
 ```
 **文件内容：**
 ```json
 {
  "api_key": "sk-xxxxxxxxxxxxx",
  "model": "deepseek-chat",
  "base_url": "https://api.deepseek.com"
 }
 ```
 ## 🔑 获取 API Key
 ### DeepSeek API Key
 1. 访问：https://platform.deepseek.com/
 2. 注册/登录账号
 3. 进入 API Keys 页面
 4. 创建新的 API Key
 5. 复制密钥（以 `sk-` 开头）
 ### 其他兼容 API
 如果使用其他 OpenAI 兼容 API：
 - 修改 Base URL
 - 使用对应的 API Key
 ## 🧪 验证配置
 ### 测试步骤
 1. **配置 API Key** - 按上述方法配置
 2. **发送测试消息** - 输入"你好"
 3. **查看响应** - 应该收到 AI 回复
 ### 成功标志
 ```
 ✅ 配置已更新并应用
 [你的消息] 你好
 [AI回复] 你好！我是图数据库记忆助手...
 ```
 ### 失败标志
 ```
 ❌ 错误: Connection error
 网络连接错误！可能的原因：
 1. API Key 未配置或无效
 2. 网络无法访问 API 服务器
 ...
 ```
 ## 🔧 故障排除
 ### 问题1：API Key 格式错误
 **检查：**
 - ✅ 以 `sk-` 开头
 - ✅ 没有空格
 - ✅ 完整复制
 **示例：**
 ```
 ✅ sk-1234567890abcdef...
 ❌ 1234567890abcdef...  (缺少 sk- 前缀)
 ❌ sk-1234 5678...      (包含空格)
 ```
 ### 问题2：网络问题
 **检查：**
 - 网络连接是否正常
 - 能否访问 https://api.deepseek.com
 - 是否需要代理/VPN
 **测试网络：**
 ```bash
 curl https://api.deepseek.com/v1/models
 ```
 ### 问题3：API Key 无效
 **检查：**
 - API Key 是否过期
 - 账号是否有余额
 - 是否有权限访问 API
 **解决：**
 - 重新生成 API Key
 - 检查账号状态
 - 充值或升级套餐
 ### 问题4：配置未生效
 **检查：**
 - 是否按 Tab 保存
 - 是否看到配置更新通知
 - 重启应用测试
 **解决：**
 - 重新配置
 - 检查配置文件
 - 清除缓存重试
 ## 📊 配置优先级
 1. **TUI 页面配置**（最高优先级）
   - 实时生效
   - 自动保存
 2. **环境变量**
   - 全局生效
   - 需要重启终端
 3. **配置文件**
   - 持久化保存
   - 自动加载
 ## 💡 最佳实践
 ### 安全建议
 - ✅ 不要分享 API Key
 - ✅ 定期更换密钥
 - ✅ 使用环境变量或配置文件
 - ❌ 不要在代码中硬编码
 - ❌ 不要提交到版本控制
 ### 使用建议
 - ✅ 使用 TUI 配置（最方便）
 - ✅ 配置后立即测试
 - ✅ 保存配置文件备份
 - ✅ 记录 API Key 获取日期
 ## 🎯 快速配置清单
 - [ ] 获取 API Key
 - [ ] 启动应用
 - [ ] 按 F2 展开侧边栏
 - [ ] 点击"配置"
 - [ ] 输入 API Key
 - [ ] 按 Tab 保存
 - [ ] 发送测试消息
 - [ ] 验证响应正常
 ## 🎉 配置成功后
 你就可以：
 - ✅ 与 AI 对话
 - ✅ 使用图数据库记忆
 - ✅ 执行工具调用
 - ✅ 管理长期记忆
 开始你的图记忆对话之旅吧！
 🎯
--- a/docs/一键启动指南.md
+++ b/docs/一键启动指南.md
@ -1,252 +1,164 @@
-baoliu1# Graph Memory TUI - 一键启动指南
+# 一键启动指南
 ## 🚀 快速开始
 ### Windows
-**方法 1: 双击启动（推荐）**
+```bash
-```
+# 方法1: 双击运行
 双击 start.bat
 ```
-**方法 2: 命令行启动**
+# 方法2: 命令行
 ```bash
 start.bat
 ```
-**方法 3: Python启动**
+# 方法3: Python
 ```bash
 python start.py
 ```
 ### Linux / macOS
 **方法 1: Shell脚本**
 ```bash
 # 方法1: Shell脚本
 chmod +x start.sh
 ./start.sh
 ```
-**方法 2: Python启动**
+# 方法2: Python
 ```bash
 python3 start.py
 ```
-## 📋 一键启动脚本功能
+## 📋 启动流程
-启动脚本会自动完成以下步骤：
+```
 [Step 1/3] 检查 Python
    ↓
 [Step 2/3] 设置虚拟环境
    - 创建venv（如果不存在）
    - 安装依赖
    ↓
 [Step 3/3] 启动应用
    ↓
 ✅ 系统初始化成功！
 ```
-### Step 1: 启动 Docker
+## ⏱️ 启动时间
 - ✅ 检查 Docker 是否安装
 - ✅ 自动启动 Docker Desktop (Windows) / Docker daemon (Linux/macOS)
 - ✅ 等待 Docker 就绪（最多60秒）
-### Step 2: 启动 Neo4j
+- **首次启动**: 约1-2分钟（安装依赖）
- ✅ 检查 Neo4j 容器是否存在
+- **后续启动**: 约30秒
 - ✅ 自动创建容器（如果不存在）
 - ✅ 启动 Neo4j 数据库
 - ✅ 等待数据库就绪
 ### Step 3: 检查 Python
 - ✅ 验证 Python 版本
 - ✅ 显示 Python 信息
 ### Step 4: 设置虚拟环境
 - ✅ 创建虚拟环境（如果不存在）
 - ✅ 激活虚拟环境
 - ✅ 安装依赖包
 ### Step 5: 启动应用
 - ✅ 启动 Graph Memory TUI
 - ✅ 显示连接信息
 ## 🔧 系统要求
-### 必需软件
+### 必需
-1. **Docker Desktop**
+- **Python 3.8+**
-   - Windows: https://www.docker.com/products/docker-desktop
+- **DeepSeek API Key**
   - Linux: https://docs.docker.com/get-docker/
   - macOS: https://docs.docker.com/docker-for-mac/install/
-2. **Python 3.8+**
+### 可选
   - https://www.python.org/downloads/
-### 硬件要求
+- **Git** - 用于克隆仓库
- 内存: 至少 4GB (推荐 8GB)
+## 📝 首次使用
 - 磁盘: 至少 5GB 可用空间
 - CPU: 2核心以上
-## 📊 启动流程
+### 1. 启动应用
-```
+```bash
-start.bat / start.sh / start.py
+start.bat  # Windows
-         ↓
+./start.sh # Linux/macOS
    [1/5] 检查 Docker
         ↓
    [2/5] 启动 Neo4j
         ↓
    [3/5] 检查 Python
         ↓
    [4/5] 设置虚拟环境
         ↓
    [5/5] 启动应用
         ↓
    Graph Memory TUI 运行中
 ```
-## 🎯 使用方法
+### 2. 配置 API Key
-### 首次启动
+1. 按 **F2** 展开侧边栏
 2. 点击 **"配置"**
 3. 输入 **DeepSeek API Key**
 4. 按 **Enter** 保存
-1. **双击 `start.bat` (Windows) 或运行 `./start.sh` (Linux/macOS)**
+### 3. 开始对话
-2. **等待所有步骤完成**（约1-2分钟）
+- 输入消息
 - 按 **Enter** 发送
-3. **看到以下信息表示成功：**
+## 🌐 获取 API Key
   ```
   ========================================
     All systems ready!
   ========================================
   Neo4j Connection:
     - Browser: http://localhost:7474
     - Bolt:    bolt://localhost:7687
     - User:    neo4j
     - Pass:    graphmemory123
   Starting TUI application...
   ```
-4. **配置 API Key**
+### DeepSeek
   - 按 F2 展开侧边栏
   - 点击"配置"
   - 输入你的 DeepSeek API Key
   - 按 Enter 保存
-5. **开始对话**
+1. 访问：https://platform.deepseek.com/
-   - 输入消息
+2. 注册账号
-   - 按 Enter 发送
+3. 创建 API Key
 4. 复制密钥
-### 后续启动
+### 其他兼容API
-直接运行启动脚本即可，所有服务会自动启动。
+- OpenAI
 - 其他兼容OpenAI格式的API
 ## ⚠️ 常见问题
-### 问题 1: Docker 启动失败
+### Q: Python 未找到
-**错误：** `Docker Desktop failed to start`
+**A:** 安装 Python 3.8+
 - Windows: https://www.python.org/downloads/
 - Linux: `sudo apt install python3`
 - macOS: `brew install python3`
-**解决：**
+### Q: 依赖安装失败
 1. 手动启动 Docker Desktop
 2. 等待 Docker 完全启动（托盘图标显示绿色）
 3. 重新运行启动脚本
-### 问题 2: Neo4j 连接失败
+**A:** 手动安装
 **错误：** `Couldn't connect to localhost:7687`
 **解决：**
 ```bash
 # 检查容器状态
 docker ps -a | grep neo4j
 # 重启容器
 docker restart neo4j
 # 查看日志
 docker logs neo4j
 ```
 ### 问题 3: Python 依赖安装失败
 **错误：** `Failed to install dependencies`
 **解决：**
 ```bash
 # 手动安装
 python -m venv venv
 venv\Scripts\activate  # Windows
 source venv/bin/activate  # Linux/macOS
 pip install -r requirements.txt
 ```
-### 问题 4: 端口被占用
+### Q: API Key 无效
-**错误：** `port 7474 or 7687 already in use`
+**A:** 检查API Key格式
 - 应以 `sk-` 开头
 - 无多余空格
 - 正确复制
-**解决：**
+## 🎯 快捷键
 ```bash
 # 停止旧容器
 docker stop neo4j
 docker rm neo4j
-# 重新运行启动脚本
+| 快捷键 | 功能 |
-```
+|--------|------|
 | F1 | 帮助 |
 | F2 | 侧边栏 |
 | F3 | 工具详情 |
 | F5 | 清屏 |
 | F6 | 退出 |
-## 🌐 访问 Neo4j 浏览器
+## 📊 数据存储
-启动成功后，可以访问 Neo4j 浏览器界面：
+- **数据库**: `graph_memory.db`
 - **位置**: 应用目录
 - **格式**: SQLite
 - **可备份**: 是
-1. 打开浏览器访问: http://localhost:7474
+## 🔄 更新应用
 2. 登录信息:
   - 用户名: `neo4j`
   - 密码: `graphmemory123`
 ## 📝 配置文件
 ### 环境变量
 创建 `.env` 文件配置：
 ```bash
-# API配置
+# 拉取最新代码
-DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxx
+git pull
 DEEPSEEK_BASE_URL=https://api.deepseek.com
 MODEL_NAME=deepseek-chat
-# Neo4j配置
+# 重新启动
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USER=neo4j
 NEO4J_PASSWORD=graphmemory123
 ```
 ## 🔄 停止服务
 ### 停止应用
 - 按 F6 或 Ctrl+C
 ### 停止 Neo4j
 ```bash
 docker stop neo4j
 ```
 ### 停止 Docker Desktop
 - Windows: 右键托盘图标 → Quit Docker Desktop
 - Linux: `sudo systemctl stop docker`
 - macOS: 右键托盘图标 → Quit Docker
 ## 📚 更多信息
 - 架构设计: `架构.md`
 - API文档: `specs/` 目录
 - 问题反馈: GitHub Issues
 ## 🎉 开始使用
 现在就运行启动脚本，开始使用 Graph Memory TUI 吧！
 ```bash
 # Windows
 start.bat
 # Linux/macOS
 ./start.sh
 # 或使用 Python
 python start.py
 ```
-🎯
+## 🗑️ 清理数据
 ```bash
 # 删除数据库
 rm graph_memory.db
 # 重新启动会创建新数据库
 start.bat
 ```
 ## 💡 提示
 - 首次启动需要安装依赖，请耐心等待
 - API Key 只需配置一次
 - 数据自动保存，无需手动操作
 - 可以随时按F6退出
 开始使用吧！
--- a/docs/打包说明.md
+++ b/docs/打包说明.md
@ -1,132 +0,0 @@
 a# 打包说明
 ## 🎯 打包为可执行文件
 ### 方法1: 使用打包脚本（推荐）
 ```bash
 # 安装PyInstaller
 pip install pyinstaller
 # 运行打包脚本
 python build.py
 ```
 打包完成后，会在 `dist/` 目录生成：
 - `GraphMemoryTUI.exe` - 可执行文件
 ### 方法2: 手动打包
 ```bash
 # 安装PyInstaller
 pip install pyinstaller
 # 打包为单个可执行文件
 pyinstaller graph_memory_tui/main.py \
    --name=GraphMemoryTUI \
    --onefile \
    --windowed \
    --add-data="graph_memory_tui/styles;graph_memory_tui/styles" \
    --hidden-import=textual \
    --hidden-import=neo4j \
    --hidden-import=openai
 ```
 ## 📦 打包选项说明
 | 选项 | 说明 |
 |------|------|
 | --onefile | 打包为单个可执行文件 |
 | --windowed | 无控制台窗口 |
 | --add-data | 添加数据文件 |
 | --hidden-import | 添加隐式导入 |
 | --exclude-module | 排除模块 |
 ## 🚀 使用打包后的应用
 ### 直接运行
 1. 双击 `GraphMemoryTUI.exe`
 2. 应用会自动启动
 3. 无需Python环境
 ### 分发给他人
 1. 将 `GraphMemoryTUI.exe` 复制给他人
 2. 对方直接双击运行
 3. 无需安装任何依赖
 ## 📋 注意事项
 ### 首次运行
 首次运行时，需要：
 1. 启动Docker
 2. 启动Neo4j
 3. 配置API Key
 ### 系统要求
 - Windows 10/11
 - Docker Desktop（或WSL2 + Docker）
 - 至少4GB内存
 ### 文件大小
 打包后的可执行文件约：
 - 50-100MB（包含所有依赖）
 ## 🔧 创建安装程序
 ### 使用Inno Setup
 1. 安装 [Inno Setup](https://jrsoftware.org/isinfo.php)
 2. 运行 `build.py` 并选择创建安装程序
 3. 编译生成的 `setup.iss`
 4. 生成 `GraphMemoryTUI-Setup.exe`
 ### 安装程序功能
 - ✅ 自动安装应用
 - ✅ 创建桌面快捷方式
 - ✅ 创建开始菜单项
 - ✅ 包含文档
 - ✅ 支持卸载
 ## 📊 对比
 | 方式 | 优点 | 缺点 |
 |------|------|------|
 | Python源码 | 灵活、可修改 | 需要Python环境 |
 | 可执行文件 | 无需Python、易分发 | 文件较大、不可修改 |
 | 安装程序 | 专业、完整 | 需要额外工具 |
 ## 💡 建议
 **开发阶段：**
 - 使用Python源码运行
 - 方便调试和修改
 **分发给用户：**
 - 打包为可执行文件
 - 或创建安装程序
 - 提供完整的使用说明
 ## 🎉 开始打包
 ```bash
 # 1. 安装依赖
 pip install -r requirements.txt
 pip install pyinstaller
 # 2. 运行打包
 python build.py
 # 3. 测试可执行文件
 dist/GraphMemoryTUI.exe
 # 4. 分发给他人
 # 复制 dist/GraphMemoryTUI.exe
 ```
 🎯
--- a/docs/数据库测试报告.md
+++ b/docs/数据库测试报告.md
@ -1,174 +0,0 @@
 # 内嵌数据库测试报告
 ## 测试概览
 **测试时间：** 2026-04-10
 **测试对象：** EmbeddedGraphDB (SQLite实现)
 **测试结果：** ✅ 全部通过 (15/15)
 ## 测试详情
 ### ✅ Test 1: 写入记忆 (Commit Memory)
 - **功能：** 写入三元组数据
 - **输入：** 4条关系，包含实体类型和置信度
 - **结果：** 成功创建8个实体，4条关系
 - **状态：** PASS
 ### ✅ Test 2: 单关键词检索 (Recall - Single Keyword)
 - **功能：** 使用单个关键词检索
 - **输入：** "Python"
 - **结果：** 找到1个实体，2条关系
 - **状态：** PASS
 ### ✅ Test 3: 多关键词检索 (Recall - Multiple Keywords)
 - **功能：** 使用多个关键词检索
 - **输入：** "Python,AI,用户"
 - **结果：** 找到3个实体，4条关系
 - **状态：** PASS
 ### ✅ Test 4: 会话过滤 (Session Filter)
 - **功能：** 按会话ID过滤检索结果
 - **输入：** session_id="test-session-001"
 - **结果：** 只返回该会话的关系
 - **状态：** PASS
 ### ✅ Test 5: 查看状态 (Introspect)
 - **功能：** 查看数据库统计信息
 - **结果：** 正确返回实体数和关系数
 - **状态：** PASS
 ### ✅ Test 6: 软删除 (Purge - Soft Delete)
 - **功能：** 标记关系为deleted状态
 - **输入：** criteria={"source": "用户", "relation": "喜欢"}
 - **结果：** 成功删除1条关系
 - **状态：** PASS
 ### ✅ Test 7: 添加更多数据 (Add More Data)
 - **功能：** 继续添加数据
 - **结果：** 成功添加新数据
 - **状态：** PASS
 ### ✅ Test 8: 归档 (Archive)
 - **功能：** 归档旧关系
 - **输入：** days=0 (归档所有)
 - **结果：** 归档功能正常
 - **状态：** PASS
 ### ✅ Test 9: 清理预览 (Cleanup - Dry Run)
 - **功能：** 预览将要删除的数据
 - **输入：** dry_run=True
 - **结果：** 返回预览信息，不实际删除
 - **状态：** PASS
 ### ✅ Test 10: 实际清理 (Cleanup - Execute)
 - **功能：** 执行实际清理
 - **输入：** dry_run=False
 - **结果：** 清理功能正常
 - **状态：** PASS
 ### ✅ Test 11: 约束检查 (Ensure Constraints)
 - **功能：** 确保数据库约束
 - **结果：** 无错误执行
 - **状态：** PASS
 ### ✅ Test 12: 重复实体处理 (Duplicate Entity Handling)
 - **功能：** 处理重复实体
 - **输入：** 再次添加"用户学习Python"
 - **结果：** mention_count增加，不创建重复实体
 - **状态：** PASS
 ### ✅ Test 13: 空查询 (Empty Query)
 - **功能：** 处理空查询
 - **输入：** query_intent=""
 - **结果：** 返回空结果，不报错
 - **状态：** PASS
 ### ✅ Test 14: 不存在的实体 (Non-existent Entity)
 - **功能：** 查询不存在的实体
 - **输入：** "不存在的实体xyz123"
 - **结果：** 返回空结果，不报错
 - **状态：** PASS
 ### ✅ Test 15: 硬删除 (Purge - Hard Delete)
 - **功能：** 物理删除关系
 - **输入：** criteria={"relation": "是"}, mode="hard"
 - **结果：** 成功删除2条关系
 - **状态：** PASS
 ## 功能覆盖
 | 功能 | 测试状态 | 备注 |
 |------|---------|------|
 | 写入记忆 | ✅ PASS | 支持三元组、置信度、实体类型 |
 | 检索记忆 | ✅ PASS | 支持单/多关键词、会话过滤 |
 | 软删除 | ✅ PASS | 标记为deleted状态 |
 | 硬删除 | ✅ PASS | 物理删除 |
 | 归档 | ✅ PASS | 按时间归档 |
 | 清理 | ✅ PASS | 支持预览和执行 |
 | 状态查看 | ✅ PASS | 返回统计信息 |
 | 约束检查 | ✅ PASS | 兼容接口 |
 | 重复处理 | ✅ PASS | 自动去重 |
 | 异常处理 | ✅ PASS | 空查询、不存在实体 |
 ## 性能测试
 | 操作 | 数据量 | 耗时 |
 |------|--------|------|
 | 写入 | 4条关系 | <10ms |
 | 检索 | 3个关键词 | <5ms |
 | 删除 | 1条关系 | <5ms |
 | 归档 | 全部 | <5ms |
 | 清理 | 预览 | <5ms |
 ## 兼容性测试
 ### ✅ 接口兼容性
 - `recall()` - 完全兼容Neo4j接口
 - `commit()` - 完全兼容Neo4j接口
 - `purge()` - 完全兼容Neo4j接口
 - `introspect()` - 完全兼容Neo4j接口
 - `archive()` - 完全兼容Neo4j接口
 - `cleanup()` - 完全兼容Neo4j接口
 - `ensure_constraints()` - 完全兼容Neo4j接口
 ### ✅ 数据格式兼容性
 - 实体格式：`{name, type, mention_count}`
 - 关系格式：`{source, target, type, confidence, ...}`
 - 返回格式：与Neo4j完全一致
 ## 结论
 ### ✅ 测试通过率：100% (15/15)
 ### 功能完整性
 - ✅ 所有核心功能正常
 - ✅ 所有接口兼容
 - ✅ 所有异常处理正确
 ### 数据正确性
 - ✅ 写入数据正确
 - ✅ 检索结果正确
 - ✅ 删除操作正确
 - ✅ 统计信息正确
 ### 性能表现
 - ✅ 操作响应快速 (<10ms)
 - ✅ 无明显性能问题
 - ✅ 适合中小规模数据
 ### 建议
 1. **可以使用** - 功能完整，测试通过
 2. **适合场景** - 开发、测试、个人使用
 3. **注意事项** - 大规模数据建议使用Neo4j
 ## 测试命令
 ```bash
 # 运行完整测试
 python test_embedded_db.py
 # 测试结果
 # All Tests Passed! ✅
 ```
 🎯
--- a/docs/项目结构.md
+++ b/docs/项目结构.md
@ -1,116 +0,0 @@
 # 项目结构
 ```
 graph_enable_ability/
 ├── docs/                      # 文档目录
 │   ├── 架构.md               # 架构设计文档
 │   ├── 一键启动指南.md       # 启动脚本使用指南
 │   └── API配置指南.md        # API Key配置说明
 │
 ├── graph_memory_tui/         # TUI应用主目录
 │   ├── widgets/              # UI组件
 │   ├── models/               # 数据模型
 │   ├── core/                 # 核心逻辑
 │   ├── styles/               # 样式文件
 │   └── app.py                # 主应用
 │
 ├── tests/                    # 测试目录
 ├── scripts/                  # 脚本目录
 ├── docker/                   # Docker配置
 │
 ├── graph_memory_demo.py      # 命令行Demo
 ├── start.bat                 # Windows启动脚本
 ├── start.sh                  # Linux/macOS启动脚本
 ├── start.py                  # 跨平台Python启动脚本
 ├── start_neo4j.bat           # Neo4j启动脚本
 ├── quick_start.bat           # 快速启动脚本
 │
 ├── requirements.txt          # Python依赖
 ├── README.md                 # 项目说明
 └── 图数据库结构设计          # 数据库设计文档
 ```
 ## 核心文件说明
 ### 启动脚本
 - **start.bat** - Windows一键启动脚本
  - 自动启动Docker (优先WSL)
  - 自动启动Neo4j
  - 自动安装依赖
  - 启动TUI应用
 - **start.sh** - Linux/macOS启动脚本
  - 功能同start.bat
  - 支持systemctl启动Docker
 - **start.py** - 跨平台Python启动脚本
  - 自动检测系统语言
  - 自动选择最佳Docker启动方式
  - 支持Windows/Linux/macOS
 ### 应用文件
 - **graph_memory_tui/** - TUI应用目录
  - 基于Textual框架
  - 现代化终端界面
  - 实时消息显示
  - 工具调用可视化
 - **graph_memory_demo.py** - 命令行Demo
  - 简单的命令行界面
  - 用于测试和调试
 ### 文档
 - **docs/** - 文档目录
  - 架构设计
  - 使用指南
  - 配置说明
 - **README.md** - 项目主文档
  - 项目介绍
  - 快速开始
  - 功能说明
 ## 使用流程
 1. **首次使用**
   ```bash
   # Windows
   start.bat
   # Linux/macOS
   ./start.sh
   ```
 2. **配置API Key**
   - 按F2打开侧边栏
   - 输入API Key
   - 按Enter保存
 3. **开始对话**
   - 输入消息
   - 按Enter发送
   - 查看响应
 ## 开发相关
 ### 运行测试
 ```bash
 python run_tests.py
 ```
 ### 安装依赖
 ```bash
 pip install -r requirements.txt
 ```
 ### 手动启动Neo4j
 ```bash
 # Windows
 start_neo4j.bat
 # Linux/macOS
 docker start neo4j
 ```