# p-agent

**Repository Path**: alan_lw/p-agent

## Basic Information

- **Project Name**: p-agent
- **Description**: p-agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# p-agent

AI Agent Backend — FastAPI + LangChain。支持多 Agent 聊天、RAG 知识库、SSE 实时推送、Agent 中间件机制。

## 截图

![import](image/README/import.png)

![import-2](image/README/import-2.png)

![import-3](image/README/import-3.png)

![key-query](image/README/key-query.png)

![tools_call](image/README/tools_call.png)

![tool-hilt](image/README/tool-hilt.png)

![tool_think_hilt](image/README/tool_think_hilt.png)

![tool_think_hilt_ok](image/README/tool_think_hilt_ok.png)

![tool_call_think](image/README/tool_call_think.png)

![rag101](image/README/rag101.png)

![chunks](image/README/chunks.png)

![file_00](image/README/file_00.png)

![file_01](image/README/file_01.png)

<!-- TODO: 聊天界面 -->

<!-- TODO: 知识库管理 -->

<!-- TODO: Agent 配置 -->

<!-- TODO: SSE 实时流效果 -->

## 技术

| 层       | 技术                                             |
| -------- | ------------------------------------------------ |
| 后端框架 | FastAPI + uvicorn + SSE-Starlette                |
| AI 框架  | LangChain + LangGraph + LangChain-OpenAI         |
| 数据库   | SQLite (SQLAlchemy + aiosqlite, 同步/异步双引擎) |
| 向量库   | Milvus Lite（Dense + BM25 混合检索, RRF 融合）   |
| 前端     | Vue 3 + Vite + TypeScript + Element Plus + Pinia |
| 包管理   | uv（Python）/ npm（Node.js）                     |

## 快速开始

### 环境要求

- Python >= 3.11
- Node.js >= 18

### 安装

```bash
# 后端
uv sync

# 前端
npm install
```

### 运行

```bash
# 后端（端口 3847）
python main.py

# 前端（Vite dev server，默认端口 5173）
npm run dev
```

后端启动后访问 http://localhost:3847/docs 可查看 Swagger API 文档。

## 项目结构

```
p-agent/
├── backend/
│   ├── app.py                  # FastAPI 应用入口
│   ├── llm_model.py            # LLM 工厂函数（含 reasoning_content 补丁）
│   ├── utils.py                # 响应格式工具（ok/fail/dt_to_ts）
│   ├── routers/                # 薄路由，只负责请求解析和响应包装
│   │   ├── chat.py             # POST /api/chat/send, resume, cancel
│   │   ├── chats.py            # 会话 CRUD
│   │   ├── messages.py         # 消息 CRUD
│   │   ├── events.py           # SSE 长连接
│   │   ├── health.py           # 健康检查
│   │   ├── knowledge.py        # 知识库（解析/分块/保存/检索/CRUD）
│   │   ├── files.py            # 文件浏览器
│   │   ├── modelConfig.py      # 模型配置管理
│   │   └── global_config.py    # 全局 key-value 配置
│   ├── services/               # 业务编排层
│   │   ├── chat_service.py     # 聊天核心：Agent 创建/调度/流式处理/持久化
│   │   ├── event_bus.py        # SSE EventBus（客户端管理/事件推送）
│   │   ├── knowledge_service.py # 知识库：文件解析/分块/Milvus 存储/检索
│   │   ├── rag_service.py      # RAG：意图识别/查询改写/混合检索
│   │   ├── rag_agent_01_graph.py # RAG Agent 01 — LangGraph StateGraph 实现
│   │   ├── rag_evaluator.py    # RAG 评估（faithfulness/relevance/sufficiency）
│   │   ├── agent_tools.py      # Agent 工具（get_system_time）
│   │   └── middlewares/        # Agent 中间件
│   │       ├── agent_context.py    # Agent 上下文数据类
│   │       ├── auto_title.py       # 自动标题生成
│   │       ├── rag.py              # RAG 注入（意图+改写+检索）
│   │       └── evaluation.py       # 回答质量评估
│   ├── db/
│   │   ├── database.py         # 引擎/会话（同步 + 异步）
│   │   └── models.py           # ORM 模型（Chat/Message/ModelConfig/GlobalConfig/Knowledge/KnowledgeChunk）
│   └── schemas/                # Pydantic 请求/响应模型
├── web/                        # Vue 3 前端
├── data/                       # SQLite + Milvus 数据文件（git ignored）
├── main.py                     # 启动入口
├── pyproject.toml
└── package.json
```

## 核心功能

### 多 Agent 聊天

支持 4 种 Agent 模式，通过 `agentId` 切换：

| agentId               | 实现方式                                           | 说明                                    |
| --------------------- | -------------------------------------------------- | --------------------------------------- |
| `defaultChat`       | `create_agent(middleware=[..., HumanInTheLoop])` | 默认聊天，带 HumanInTheLoop 工具审批    |
| `defaultAgent`      | `create_deep_agent()`                            | 文件系统操作 Agent（deepagents 框架）   |
| `defaultRagAgent01` | LangGraph StateGraph（4节点 + 条件边）             | RAG：意图识别→检索→生成→评估         |
| `defaultRagAgent02` | `create_agent(middleware=[RAG, Evaluation])`     | RAG：中间件式意图识别→检索→生成→评估 |

所有 Agent 通过 SSE 流式推送结果，支持取消、断点恢复。

### RAG 知识库

完整的知识库管理流程：

1. **文件上传与解析** — 支持 PDF / DOCX / TXT / MD / CSV / JSON
2. **分块预览** — 支持 character / token / markdown / regex 四种分块策略
3. **向量化存储** — 使用 Milvus Lite，同时存储 Dense 向量和 BM25 全文索引
4. **混合检索** — 支持 vector / keyword / hybrid 三种检索模式，hybrid 模式下 Dense + BM25 经 RRF 融合排序
5. **知识库 CRUD** — 文档级和分块级的增删改查

### Agent 中间件机制

基于 LangChain `AgentMiddleware`，在 `abefore_model` / `aafter_agent` 等钩子中扩展：

- **AutoTitleAgentMiddleware** — `aafter_agent` 中异步生成会话标题，不阻塞主流程
- **RAGMiddleware** — `abefore_model` 中完成意图识别 → 查询改写 → 混合检索 → 上下文注入
- **EvaluationMiddleware** — 对回答进行 faithfulness / relevance / sufficiency 评分
- **HumanInTheLoopMiddleware** — 工具调用前拦截，等待用户审批

### SSE 实时推送

EventBus 架构管理 SSE 客户端连接，支持事件类型：

`connected` → `user_message` → `message_chunk`(流式) / `tool_call` / `tool_call_interrupt` → `message_done`

### 文件浏览

参考 opencode 的文件接口设计，支持目录列表、忽略模式过滤（node_modules/.git 等）。

### 模型配置管理

多模型 CRUD，`type_bit` 按位标识模型能力（文本生成 / 图片 / 视频 / 音频 / 3D / 向量），支持设为默认。

## API 概览

| 方法     | 路由                                   | 说明                                     |
| -------- | -------------------------------------- | ---------------------------------------- |
| GET      | `/api/health`                        | 健康检查                                 |
| GET      | `/api/events`                        | SSE 长连接                               |
| POST     | `/api/chat/send`                     | 发送消息                                 |
| POST     | `/api/chat/cancel`                   | 取消生成                                 |
| POST     | `/api/chat/resume`                   | 恢复中断的对话                           |
| GET      | `/api/chats`                         | 会话列表                                 |
| GET/POST | `/api/chats/get` / `/api/chats`... | 会话 CRUD                                |
| GET      | `/api/chat-messages/list?chatId=`    | 按会话查询消息                           |
| GET/POST | `/api/chat-messages/**`              | 消息 CRUD                                |
| GET/POST | `/api/knowledge/**`                  | 知识库全流程（解析/分块/保存/检索/CRUD） |
| GET/POST | `/api/model-configs/**`              | 模型配置管理                             |
| GET/POST | `/api/global-config/**`              | 全局 key-value 配置                      |
| GET      | `/api/files/list?directory=`         | 文件浏览器                               |

所有响应统一格式：`{ success: true, data: ... }` / `{ success: false, error: "..." }`。

## 开发指南

### 添加新 Agent

在 `ChatService._get_or_create_agent` 中新增分支，返回 `CompiledStateGraph` 即可：

```python
elif agent_id == "myNewAgent":
    self._agents[key] = create_agent(
        model=llm, tools=[...],
        middleware=[...],
        checkpointer=...,
    )
```

### 添加新中间件

继承 `AgentMiddleware`，实现 `abefore_model` / `aafter_model` / `abefore_agent` / `aafter_agent` 钩子：

```python
from langchain.agents.middleware import AgentMiddleware

class MyMiddleware(AgentMiddleware):
    async def abefore_model(self, state, runtime):
        # 在 LLM 调用前注入上下文
        return state
```

注册到 `create_agent(middleware=[MyMiddleware()])` 即可。