docs: 重构为 docs/zh/ + docs/en/ 子文件夹结构

- 拆分为 docs/zh/(中文) 和 docs/en/(英文) - README 索引对应语言子文件夹 - 保留所有文档内容
2026-04-14 13:25:53 +08:00
parent dd685485b5
commit 29d15707f5
18 changed files with 16 additions and 16 deletions
--- a/docs/en/architecture.md
+++ b/docs/en/architecture.md
@ -0,0 +1,179 @@
+# TrulyMEM Architecture
+
+## Core Principles
+
+- Keyboard-driven, zero mouse dependency
+- Minimalist visual, information density priority
+- Tool traces hidden by default, expandable when needed
+- TUI & backend separation, multi-threaded communication
+- **Everything is a graph**, AI reasoning runs entirely in backend
+
+## Project Structure
+
+```
+TrulyMEM-TrueHumanMEM/
+├── trulymem_entry.py    # Entry: start core → then ui
+├── core/               # Backend/business logic
+│   ├── __init__.py     # Export BackendServer, BackendClient, EmbeddedGraphDB
+│   ├── server.py       # BackendServer (Packet communication protocol)
+│   ├── client.py       # BackendClient (Packet protocol client)
+│   ├── embedded_db.py # SQLite graph database implementation
+│   ├── graph_client.py # OpenAI/DeepSeek API client
+│   ├── tool_executor.py # Tool executor
+│   ├── tool_limiter.py  # Tool call limiter
+│   ├── tools/          # Tool definitions
+│   │   ├── __init__.py
+│   │   └── memory_tools.py
+│   └── prompts/        # Prompt management
+├── ui/                 # TUI display layer (display only, no AI logic)
+│   ├── __init__.py     # Export GraphMemoryApp, AppConfig
+│   ├── app.py          # GraphMemoryApp (communicates via BackendClient)
+│   ├── widgets/        # TUI components
+│   ├── handlers/       # Event handlers
+│   ├── models/         # Data models
+│   ├── services/       # Service layer (config only)
+│   └── styles/         # Style files
+└── tests/              # Tests (42 tests)
+```
+
+## Architecture Diagram
+
+```
+trulymem_entry.py
+    │
+    ├─ BackendServer.start() → Runs in independent thread
+    │   ├─ Handle PROCESS_MESSAGE requests → AI reasoning + tool calls
+    │   ├─ Handle EXECUTE_TOOL requests → External tool calls (unlimited)
+    │   ├─ Handle GET/SET_CONFIG requests
+    │   └─ Manage GraphMemoryClient, EmbeddedGraphDB
+    │
+    └─ GraphMemoryApp(backend_server=server)
+            │
+            └─ BackendClient ← Packet communication → BackendServer
+```
+
+## Component Responsibilities
+
+### core/ (Backend)
+
+| Component | Responsibility |
+|------------|----------------|
+| `server.py` | Packet protocol, multi-threaded queue, AI reasoning, tool limits |
+| `client.py` | Client wrapper, UI-backend communication bridge |
+| `embedded_db.py` | SQLite graph database CRUD |
+| `graph_client.py` | OpenAI/DeepSeek API client |
+| `tool_executor.py` | Tool execution logic |
+| `tool_limiter.py` | Tool call rate limit (AI reasoning only) |
+
+### ui/ (Display Layer)
+
+| Component | Responsibility |
+|------------|----------------|
+| `app.py` | Textual app main class, communicates via BackendClient |
+| `services/` | Config management only, no AI logic |
+
+### Communication Protocol
+
+UI and backend interact via **Packet Communication Protocol**:
+
+```python
+from core import BackendServer, BackendClient, Packet, PacketType
+
+# Backend startup
+server = BackendServer(db_path="graph_memory.db", use_embedded_db=True)
+server.start(api_key="your-key")
+
+# Client communication
+client = BackendClient(server)
+result = client.process_message("hello")  # AI reasoning
+result = client.execute_tool("memory_introspect", {})  # Direct tool call
+```
+
+---
+
+## Data Flow
+
+```
+User input → InputBox → on_input_box_send_message
+    ↓
+BackendClient.process_message(user_input)
+    ↓
+Packet (type=PROCESS_MESSAGE) → queue.Queue
+    ↓
+BackendServer (independent thread)
+    <20><><EFBFBD>
+GraphMemoryClient.send_message_with_history()
+    ↓
+OpenAI API / DeepSeek API
+    ↓
+execute_tool() + ToolLimiter (limited during AI reasoning)
+    ↓
+EmbeddedGraphDB (graph database)
+    ↓
+Loop API calls until no tool_calls
+    ↓
+Packet response returns
+    ↓
+MessageHistory displays
+```
+
+---
+
+## Startup Flow
+
+```python
+# trulymem_entry.py
+def main():
+    # Config file saved in application root
+    config_file = application_path / "config.json"
+    
+    # Load config
+    config_service = ConfigService(config_file=config_file)
+    config = config_service.get_config()
+    
+    # Create backend
+    backend_server = BackendServer(db_path="graph_memory.db", use_embedded_db=True)
+    backend_server.start(api_key=config.api_key, base_url=config.base_url)
+    
+    # Create UI
+    app = GraphMemoryApp(backend_server=backend_server, config_service=config_service)
+    app.run()
+    
+    backend_server.shutdown()
+```
+
+---
+
+## Tool System
+
+### Memory Tools (6)
+- `memory_recall` - Retrieve memory
+- `memory_commit` - Write memory
+- `memory_purge` - Delete memory
+- `memory_introspect` - View status
+- `memory_archive` - Archive memory
+- `memory_cleanup` - Clean data
+
+### Persona Tools (2)
+- `persona_update` - Update persona
+- `persona_clear` - Clear persona
+
+### Task Tools (4)
+- `task_create` - Create task
+- `task_set_state` - Set state
+- `task_delete` - Delete task
+- `task_link_info` - Link information
+
+---
+
+## Error Handling Principle
+
+All APIs **do not throw exceptions**, errors are passed via return dictionary:
+
+```python
+result = client.process_message("hello")
+
+if result.get("success"):
+    print(result["content"])
+else:
+    print(result["error"])  # Error description