docs: update README with project overview and usage guide

2026-05-05 11:49:26 +08:00
parent f0a32712b4
commit d2b20a9f91
1 changed files with 104 additions and 1 deletions
@@ -1,2 +1,105 @@
-# eino-test
+# 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
+```