完善文档

docs/architecture/README.md

@@ -0,0 +1,3 @@
+# Architecture
+
+总体架构文档目录。详见 `overview.md`、`system.md`、`data-flow.md`、`event-flow.md`、`runtime.md`、`security.md`。

docs/architecture/data-flow.md

@@ -0,0 +1,22 @@
+# 数据流
+
+## Agent Run
+
+```mermaid
+flowchart TD
+    A["Request"] --> B["Create Run"]
+    B --> C["Build Context"]
+    C --> D["Memory Retrieval"]
+    D --> E["Planning"]
+    E --> F["Model"]
+    F --> G["Tool"]
+    G --> H["Observation"]
+    H --> I["Evaluation"]
+    I -->|continue| E
+    I -->|finish| J["Result"]
+    H --> K["Memory Consolidation"]
+```
+
+## 数据原则
+
+短期状态进入 Redis；需要长期保存的数据进入 PostgreSQL；语义检索数据进入 VectorStore；关系型知识进入 GraphStore；二进制内容进入 FileStorage。

docs/architecture/event-flow.md

@@ -0,0 +1,29 @@
+# 事件流
+
+## 事件模型
+
+推荐事件：
+
+- `run_start`
+- `run_status`
+- `text_delta`
+- `plan_created`
+- `plan_updated`
+- `memory_recall`
+- `tool_call`
+- `tool_result`
+- `reflection`
+- `error`
+- `finish`
+
+## 传输
+
+SSE 是默认 Agent 流式通道；WebSocket 用于双向实时场景。
+
+事件必须包含：
+
+- event_id
+- run_id
+- event_type
+- timestamp
+- payload

docs/architecture/overview.md

@@ -0,0 +1,50 @@
+# 总体架构
+
+## 目标
+
+构建一个可长期运行、可扩展、可观测、可替换基础设施的 Agent 平台。
+
+## 分层
+
+```mermaid
+flowchart TB
+    U["User / Environment"] --> C["Web / Desktop"]
+    C --> B["BFF / API"]
+    B --> A["Agent Runtime"]
+    A --> M["Memory"]
+    A --> P["Planning & Reasoning"]
+    A --> T["Tool Runtime"]
+    A --> R["RAG"]
+    A --> L["Model Gateway"]
+    T --> X["MCP / External Tools"]
+    A --> E["Event System"]
+    M --> D["Data Layer"]
+    R --> D
+    D --> PG["PostgreSQL"]
+    D --> RD["Redis"]
+    D --> VS["VectorStore"]
+    D --> GS["GraphStore"]
+    D --> FS["FileStorage"]
+```
+
+## 核心原则
+
+1. Agent 能力与基础设施解耦。
+2. 外部能力通过统一 Tool Runtime 接入。
+3. 长任务必须可观测、可恢复。
+4. 所有关键执行路径必须可审计。
+5. 采用渐进式基础设施。
+
+## 技术栈
+
+Web：Next.js 16 / React 19 / TypeScript。
+
+BFF：Node.js / TypeScript。
+
+Agent Runtime：Python 3.12+ / FastAPI。
+
+Desktop：Rust / Tauri v2。
+
+高并发 I/O：Go 1.25+。
+
+数据：PostgreSQL / Redis / VectorStore / GraphStore / Object Storage。

docs/architecture/runtime.md

@@ -0,0 +1,31 @@
+# Runtime 架构
+
+Agent Runtime 负责生命周期管理，不直接承担所有业务能力。
+
+核心对象：
+
+- Agent
+- Session
+- Run
+- Task
+- Plan
+- Step
+- ToolCall
+- Observation
+- Memory
+- Result
+
+生命周期：
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created
+    Created --> Running
+    Running --> Waiting
+    Waiting --> Running
+    Running --> Completed
+    Running --> Failed
+    Failed --> Retrying
+    Retrying --> Running
+    Completed --> [*]
+```

docs/architecture/security.md

@@ -0,0 +1,17 @@
+# 架构安全边界
+
+安全边界：
+
+```mermaid
+flowchart TB
+    User --> Auth
+    Auth --> RBAC
+    RBAC --> ToolPermission
+    ToolPermission --> Sandbox
+    Sandbox --> Execution
+    Execution --> Audit
+```
+
+Tauri Capabilities 保护桌面本地能力；服务端 RBAC 和 Tool Permission 控制用户及 Agent 的服务能力。
+
+禁止把任何单一机制视为完整安全方案。

docs/architecture/system.md

@@ -0,0 +1,32 @@
+# 系统架构
+
+## 核心模块
+
+- Client
+- BFF
+- Agent Runtime
+- Model Gateway
+- Memory Manager
+- Planning Engine
+- Tool Runtime
+- RAG
+- Event System
+- Data Layer
+- Observability
+
+## 调用关系
+
+```mermaid
+flowchart LR
+    Client --> BFF
+    BFF --> Runtime
+    Runtime --> Model
+    Runtime --> Memory
+    Runtime --> Planner
+    Planner --> Tools
+    Tools --> External
+    Runtime --> Events
+    Runtime --> Observability
+```
+
+模块之间优先使用明确接口，不允许跨层直接访问内部实现。