# Personal Knowledge Assistant

基于 [EINO](https://github.com/cloudwego/eino) 框架的个人知识助手 Agent，融合 RAG（检索增强生成）与 Tool Calling（工具调用），采用 Supervisor 多 Agent 编排模式。

## 架构

```
用户提问 → Supervisor Agent（路由）
               ├── Retrieval Agent → 语义搜索 / 关键词搜索
               ├── Writer Agent   → 创建笔记 / 生成摘要
               └── Organizer Agent → 标签推荐 / 关联发现
```

**技术栈**：Go + Gin + Eino（后端）| React + Vite + Tailwind CSS（前端）

## 快速开始

### 1. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env`，填入你的 API 配置：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_API_KEY` | API Key | (必填) |
| `OPENAI_BASE_URL` | API Base URL | `https://api.openai.com/v1` |
| `OPENAI_MODEL` | Chat Model | `gpt-4o` |
| `OPENAI_EMBED_MODEL` | Embedding Model | `text-embedding-3-small` |
| `DATA_DIR` | 笔记目录 | `./data` |
| `PORT` | HTTP 端口 | `8080` |

> `OPENAI_BASE_URL` 支持任意 OpenAI 兼容的 API 接入商。

### 2. 启动后端

```bash
go run .
```

启动时会自动扫描 `data/` 目录下的 `.md` 文件并建立向量索引。

### 3. 启动前端

```bash
cd web
npm install
npm run dev
```

访问 `http://localhost:5173`。

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/chat` | 发送消息，SSE 流式返回 Agent 响应 |
| `GET` | `/api/notes` | 获取笔记列表 |
| `GET` | `/api/notes/:id` | 获取笔记详情 |
| `POST` | `/api/notes` | 创建笔记 |
| `DELETE` | `/api/notes/:id` | 删除笔记 |
| `POST` | `/api/index` | 重建向量索引 |

## 项目结构

```
├── main.go                    # 入口：组件装配 + 启动服务
├── config/config.go           # 环境变量配置
├── internal/
│   ├── store/                 # 笔记存储（内存实现）
│   ├── embedding/             # OpenAI Embedding 封装
│   ├── index/                 # 内存向量索引（cosine similarity）
│   ├── rag/                   # Markdown 分块 + RAG Pipeline
│   ├── tools/                 # 6 个 Agent 工具
│   ├── agent/                 # Supervisor + 3 个子 Agent
│   └── api/                   # Gin HTTP 路由 + SSE
├── data/                      # 笔记目录（Markdown）
└── web/                       # React 前端
```

## Agent 工具

| 工具 | Agent | 说明 |
|------|-------|------|
| `semantic_search` | Retrieval | 语义相似度搜索 |
| `keyword_search` | Retrieval | 关键词精确匹配 |
| `create_note` | Writer | 创建新笔记 |
| `generate_summary` | Writer | 生成笔记摘要 |
| `suggest_tags` | Organizer | 自动推荐标签 |
| `find_related` | Organizer | 发现关联笔记 |

## 开发

```bash
# 构建
go build ./...

# 运行测试
go test ./...

# 前端构建
cd web && npm run build
```