Everjoy/TECH_STACK.md

# Everjoy Tech Stack

> **Everjoy is not only an IDE but a completely fresh AI workflow.**
> 
> An ideal agent tool with a TUI interacting interface, divided into several workspaces:
> file editing, vibe interacting, and project/life management.

---

## 1. TUI 渲染与交互框架

| 库 | 用途 |
|----|------|
| **ratatui** | TUI 渲染核心，多工作区布局、面板分割、状态管理 |
| **crossterm** | 跨平台输入输出（键鼠事件、颜色、光标、屏幕缓冲） |
| **tui-textarea** | 编辑器工作区的文本编辑组件 |
| **tui-term** | 内置终端面板（Agent 执行命令时展示实时输出） |

### 为什么选 ratatui

- 工作区（Workspace）需要复杂布局：侧边栏 + 编辑区 + AI 对话面板 + 状态栏
- 支持鼠标点击切换面板、拖拽分割线
- 活跃的组件生态，适合快速组装多面板界面

```bash
cargo add ratatui crossterm tui-textarea tui-term
```

---

## 2. 异步运行时与网络通信

| 库 | 用途 |
|----|------|
| **tokio** | 异步运行时，同时处理 UI 事件、AI 流式响应、文件监听 |
| **reqwest** | HTTP 客户端，调用 LLM API（OpenAI、Claude、本地 Ollama 等） |
| **tokio-tungstenite** | WebSocket 客户端（实时连接、本地服务通信） |
| **futures** | 流处理工具 |

### AI 流式响应处理

```bash
cargo add tokio --features full
cargo add reqwest --features json,stream,rustls-tls
cargo add tokio-tungstenite
cargo add futures
```

---

## 3. Agent 核心引擎

这是 Everjoy 的灵魂。不依赖现有框架，自研一个轻量但可扩展的 Agent 循环。

### 核心架构

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Observer   │ --> │   Thinker   │ --> │   Actor     │
│  (观察环境)  │     │  (推理决策)  │     │  (执行动作)  │
└─────────────┘     └─────────────┘     └─────────────┘
       ^                                      |
       └────────────── Feedback <─────────────┘
```

### Agent 相关依赖

| 库 | 用途 |
|----|------|
| **serde** + **serde_json** | LLM API 请求/响应的结构化序列化 |
| **schemars** | 为工具函数生成 JSON Schema，供 LLM function calling 使用 |
| **async-trait** | Agent 组件的异步 trait 抽象 |

```bash
cargo add serde --features derive
cargo add serde_json
cargo add schemars
cargo add async-trait
```

### 工具系统（Tools）

Agent 需要能操作环境的工具集：

| 工具 | 实现方式 |
|------|---------|
| 文件读写 | `std::fs` + `ropey`（大文件） |
| 命令执行 | `tokio::process::Command` + `tui-term` 展示输出 |
| 代码搜索 | `regex` + `ignore`（支持 .gitignore） |
| 网络请求 | `reqwest`（Agent 自主查询文档/API） |
| 任务管理 | 调用 SQLite 存储层（见第 5 节） |

```bash
cargo add regex ignore
```

---

## 4. 记忆系统（Memory）

Agent 不能金鱼脑。需要短期对话记忆 + 长期知识记忆。

### 短期记忆：对话上下文

直接维护 `Vec<Message>`，按 token 限制滑动窗口截断。

### 长期记忆：向量检索

| 库 | 用途 |
|----|------|
| **rusqlite** | 主数据库（对话历史、任务、配置、笔记） |
| **sqlite-vec** 或 **pgvector 本地版** | 向量存储与相似度检索 |
| **fastembed-rs** | 本地文本 Embedding（不依赖外部 API） |

> 如果追求极简，可以先只用 SQLite 全文搜索（`fts5`），后期再上向量。

```bash
cargo add rusqlite --features bundled
# 向量检索后续按需添加
```

---

## 5. 数据持久化层

Everjoy 管理项目和人生，需要稳定的数据层。

| 库 | 用途 |
|----|------|
| **rusqlite** | 嵌入式数据库，存储一切 |
| **chrono** | 时间处理、截止日期、日历事件 |
| **uuid** | 任务/对话/项目的唯一标识 |

### 数据库表设计（初版）

```sql
-- 对话历史
CREATE TABLE conversations (
    id TEXT PRIMARY KEY,
    title TEXT,
    created_at DATETIME,
    updated_at DATETIME
);

CREATE TABLE messages (
    id TEXT PRIMARY KEY,
    conversation_id TEXT,
    role TEXT,  -- 'user' | 'assistant' | 'system' | 'tool'
    content TEXT,
    tool_calls TEXT,  -- JSON
    created_at DATETIME
);

-- 任务/项目管理
CREATE TABLE tasks (
    id TEXT PRIMARY KEY,
    title TEXT,
    description TEXT,
    status TEXT,  -- 'todo' | 'doing' | 'done' | 'archived'
    priority INTEGER,
    due_date DATETIME,
    project TEXT,
    tags TEXT,  -- JSON array
    created_at DATETIME
);

-- 笔记/知识
CREATE TABLE notes (
    id TEXT PRIMARY KEY,
    title TEXT,
    content TEXT,
    tags TEXT,
    linked_file TEXT,
    created_at DATETIME
);
```

```bash
cargo add chrono --features serde
cargo add uuid --features v4,serde
```

---

## 6. 内容渲染与解析

| 库 | 用途 |
|----|------|
| **pulldown-cmark** | 解析 AI 回复的 Markdown，渲染到 TUI 面板 |
| **syntect** | 代码块语法高亮（Markdown 中的 ```rust 块） |
| **syntect-tui** | syntect 与 ratatui 的桥接 |

> AI 回复基本是 Markdown，需要解析成 ratatui 的 `Text`/`Span` 结构渲染。

```bash
cargo add pulldown-cmark
cargo add syntect syntect-tui
```

---

## 7. 文件系统与项目感知

| 库 | 用途 |
|----|------|
| **ropey** | 大文件高效编辑（编辑工作区核心） |
| **notify** | 监听文件变化，Agent 实时感知项目改动 |
| **ignore** | 按 .gitignore 规则遍历文件树 |
| **walkdir** | 目录遍历 |

```bash
cargo add ropey notify ignore walkdir
```

---

## 8. 配置管理

| 库 | 用途 |
|----|------|
| **toml** | 用户配置（AI API key、主题、快捷键、Agent 人设） |
| **serde** | 配置反序列化 |
| **directories** | 跨平台定位配置目录 `~/.config/everjoy/` |

### 配置文件结构

```toml
# ~/.config/everjoy/config.toml
[ai]
provider = "openai"
api_key = "sk-..."
model = "gpt-4o"
stream = true

[agent]
personality = "你是一位高效且略带幽默的编程伙伴..."
auto_execute_tools = false  -- 危险操作需确认

[ui]
theme = "everforest"
sidebar_width = 30
editor_tab_size = 4

[keymap]
"ctrl+space" = "toggle_agent_panel"
"ctrl+shift+a" = "ask_agent"
```

```bash
cargo add toml serde --features derive directories
```

---

## 9. 实用工具库

| 库 | 用途 |
|----|------|
| **anyhow** | 快速原型期的错误处理 |
| **thiserror** | 后期结构化错误定义 |
| **parking_lot** | 更轻量的同步原语 |
| **indexmap** | 有序 HashMap（保持面板顺序、配置项顺序） |
| **which** | 查找系统命令路径（检查 git、node 等是否存在） |
| **tempfile** | 临时文件（Agent 编辑前备份） |
| **glob** | 文件通配匹配 |

```bash
cargo add anyhow thiserror parking_lot indexmap which tempfile glob
```

---

## 10. 完整 Cargo.toml

```toml
[package]
name = "everjoy"
version = "0.1.0"
edition = "2024"

[dependencies]
# TUI 渲染
ratatui = "0.29"
crossterm = "0.28"
tui-textarea = "0.7"
tui-term = "0.2"

# 异步 + 网络
tokio = { version = "1.4", features = ["full"] }
reqwest = { version = "0.12", features = ["json", "stream", "rustls-tls"] }
tokio-tungstenite = "0.26"
futures = "0.3"

# 序列化 + Agent 协议
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
schemars = "0.8"
async-trait = "0.1"

# 数据持久化
rusqlite = { version = "0.34", features = ["bundled", "chrono"] }
chrono = { version = "0.4", features = ["serde"] }
uuid = { version = "1.16", features = ["v4", "serde"] }

# 文本 + 文件
ropey = "1.6"
pulldown-cmark = "0.13"
syntect = "5.2"
# syntect-tui = "..."  # 视情况选择或自研桥接
notify = "8.0"
ignore = "0.4"
walkdir = "2.5"

# 配置 + 工具
toml = "0.8"
directories = "5.0"
regex = "1.11"
which = "7.0"
tempfile = "3.19"
glob = "0.3"

# 基础设施
anyhow = "1.0"
thiserror = "2.0"
parking_lot = "0.12"
indexmap = "2.7"

[dev-dependencies]
# 测试工具后续添加
```

---

## 12. 关键设计决策

| 维度 | 决策 | 理由 |
|------|------|------|
| **编辑模式** | **非模态**（直接打字） | 开箱即用，AI 随时可介入 |
| **Agent 架构** | **自研 ReAct 循环** | 现有框架太重，自研更灵活 |
| **LLM 接入** | **多 Provider 抽象** | 支持 OpenAI/Claude/Ollama/本地模型 |
| **流式响应** | **SSE 实时渲染** | AI 思考过程实时展示在对话面板 |
| **数据存储** | **SQLite 单文件** | 用户项目 + 人生数据一盘棋 |
| **工具执行** | **人工确认 + 自动执行分级** | 读文件自动，写文件/执行命令需确认 |
| **文件编辑** | **临时缓冲 + 用户确认写入** | Agent 的修改先预览，用户 OK 再落盘 |

---

## 13. 开发里程碑（建议）

| 阶段 | 目标 | 核心组件 |
|------|------|---------|
| **MVP** | TUI 多面板 + 基本编辑器 + 能聊天的 Agent | ratatui, tui-textarea, reqwest, 简单 ReAct |
| **v0.2** | 文件工具 + 项目内代码问答 | ropey, ignore, notify, 文件读写工具 |
| **v0.3** | 任务/笔记管理 + SQLite 持久化 | rusqlite, chrono, 任务面板 |
| **v0.4** | 内嵌终端 + Agent 自主执行命令 | tui-term, tokio-process, 命令工具 |
| **v0.5** | 记忆系统 + 跨对话上下文 | sqlite-vec, embedding, 长期记忆检索 |

---

*for Hoshu Chiu & Everjoy Chiu 🐕*
*Just have fun with Everjoy.*