# knowledge-agent

**Repository Path**: sjsjssj/knowledge-agent

## Basic Information

- **Project Name**: knowledge-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人知识库 Agent 助手（软件应用开发实践 · 实验4：软件基础功能开发）

本地文档智能问答与知识梳理系统的**非 AI 基础功能闭环**：上传 PDF/TXT → 解析 → 切片 → SQLite 入库 → 列表/详情 → 关键词检索 → 导出 Markdown。

## 技术栈

| 层次 | 技术 |
|---|---|
| 后端 | Python 3.12 · FastAPI · SQLite（内置 sqlite3）· PyMuPDF |
| 前端 | Vue 3 · Vite · Vue Router |
| 测试 | pytest + httpx（TestClient） |

## 项目结构

```
knowledge-agent/
├─ backend/                 # FastAPI 后端
│  ├─ app/
│  │  ├─ main.py            # 应用入口与路由注册、日志
│  │  ├─ db.py              # SQLite 初始化（建表/清空/恢复）
│  │  ├─ models.py          # 数据模型与常量
│  │  ├─ controllers/       # 控制层：接口定义与参数校验
│  │  ├─ services/          # 业务层：解析、切片、检索、导出、样例导入
│  │  └─ repositories/      # 数据访问层：SQLite 读写
│  ├─ tests/                # 8 个测试用例（test_basic.py）
│  ├─ tools/make_sample.py  # 生成样例数据
│  └─ requirements.txt
├─ frontend/                # Vue 3 前端
│  └─ src/
│     ├─ pages/             # 页面：Home（上传）/ Docs（列表）/ Detail（详情）
│     ├─ components/        # 复用组件（StatusTag）
│     ├─ router/            # 路由
│     └─ api/               # 接口调用封装
├─ docs/sample/             # 样例数据（课程笔记.pdf、论文摘录.txt）
└─ logs/                    # 运行日志（app.log）
```

## 快速启动

### 1. 后端

```bash
cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --port 8000
```

启动后：接口文档 http://127.0.0.1:8000/docs ；数据库为空时自动导入 docs/sample 样例数据。

### 2. 前端

```bash
cd frontend
npm install
npm run dev
```

访问 http://localhost:5173 。开发环境下 /api 请求由 Vite 代理到 8000 端口。

## 接口清单

| 接口 | 说明 | 校验 |
|---|---|---|
| POST /api/documents/upload | 上传 PDF/TXT，解析切片入库 | 扩展名白名单；≤100MB；非空；重复检测 |
| GET /api/documents | 文档列表 | — |
| GET /api/documents/{id} | 文档详情（含片段） | id 存在 |
| GET /api/search?q= | 关键词检索 | q 非空且 ≤50 字 |
| POST /api/export | 导出 Markdown | 文档存在且有内容 |
| DELETE /api/documents/{id} | 删除文档（级联删片段） | id 存在 |

## 测试

```bash
cd backend
python -m pytest tests/ -v
```

共 8 个用例（T1—T8），覆盖：TXT 中文解析、多页 PDF 解析、格式拒绝、重复上传、空文件、空数据列表、检索无命中、导出无内容。

## 样例数据

- `docs/sample/课程笔记.pdf`：3 页中文文档（软件工程/设计模式/知识库系统）
- `docs/sample/论文摘录.txt`：需求分析摘要

重新生成：`python backend/tools/make_sample.py`。清空数据恢复初始状态：删除 `backend/data/` 目录后重启后端。

## 版本历史

- `v0.1`（可运行初版）：项目骨架 + 上传解析切片入库 + 列表接口 + 首页/列表页
- `v0.2`（测试修订版）：详情/检索/导出/删除 + 异常处理与日志完善 + 8 个测试用例全部通过

## Windows 运行注意
- 测试用例的中文子集字体路径已做跨平台适配（Windows 自动使用 msyh.ttc）。
- 后端启动：cd backend && python -m uvicorn app.main:app --port 8000。