# Agent Framework

**Repository Path**: bucai241793/agent-framework

## Basic Information

- **Project Name**: Agent Framework
- **Description**: 10/28，原GitHub仓库被莫名封禁，本仓库为备份仓库。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Framework

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Gitee](https://img.shields.io/badge/Gitee-bucai241793-c71d23.svg)](https://gitee.com/bucai241793/agent-framework)
[![GitHub](https://img.shields.io/badge/GitHub-241793-181717.svg)](https://github.com/241793/Agent-Framework)

通用智能体框架：**对话 + RAG 知识库 + 可视化工作流 + 定时自动化 + 对外 API**，开箱即用。
基于 **LangChain 1.x + LangGraph 1.x**，数据层为 **SQLite**（向量 + 全文检索，零外部服务依赖），前端 **Vue 3**（暖砂石主题，顶部标签栏 + 对话侧栏 + 产物面板）。本项目可作为 Agent 项目的基座，也可作为其它系统的 AI 能力后端（稳定 `/v1` API + Python SDK），供新手学习参考。

```
对话（智能体/工具/知识库） ── 知识库（RAG） ── 工作流（画布 + 定时任务）
        └────────── 扩展中心（智能体 / 渠道 / 语音 / MCP / 技能 / 插件）──────────┘
                    对外 API（OpenAI 兼容 + /v1 门面 + Python SDK）
```
<img width="1910" height="873" alt="a0b8ff93-30fb-4e32-8a54-15336b9026b5" src="https://github.com/user-attachments/assets/46f596d2-aa61-49f0-92f4-dc8f0acb0710" />


## 功能总览

> 顶栏只有 3 个一级入口：**对话 / 知识库 / 工作流**。对话页侧栏「新建对话」下方还挂着 **扩展** 与 **设置** 两个入口，点击后以**全屏弹层（二级界面）**打开：扩展中心包含智能体、定时任务、消息渠道、语音、MCP/技能/插件与对外 API；设置包含模型与向量、文件、SSH、Git、用量、日志、账号与系统。设置也可从右上角头像菜单进入。旧链接（`/extensions`、`/agents`、`/automation`、`/channels`、`/voice`、`/settings`、`/logs`、`/usage`）会自动重定向并打开对应弹层，`/workflows` 保持独立页面。

### 💬 对话
- 流式输出（正文 / 推理过程 / 工具调用实时卡片），可停止、重新生成（非破坏式，被替换消息可回看）、编辑重发
- **会话绑定智能体**：系统提示词 / 工具白名单 / 模型 / 最大步数全部生效；支持**多套提示词（人设）**保存与一键切换
- 上下文窗口管理：token 实时计量（状态环）、超限自动压缩为摘要
- 产物面板：代码 / HTML / SVG 预览、图片、引用溯源、文件下载
- 侧栏搜索、消息时间戳、导出 Markdown、斜杠命令、深浅色主题（跟随系统）

### 🧰 内置工具（58 个，LLM 自主决定调用）

| 类别 | 工具 | 说明 |
|---|---|---|
| 知识库 | `search_knowledge` | 混合检索（向量 + FTS5 + RRF 融合） |
| 联网 | `web_search` | DuckDuckGo → 必应自动兜底；可配 Tavily / SearXNG |
| 联网 | `web_fetch` / `http_get` / `http_request` | 网页正文提取 / GET 快捷调用 / 任意 HTTP 方法 |
| 浏览器 | `browser_navigate / click / type / press / scroll / extract / screenshot` | Playwright 自动化，新标签页自动跟随（可选依赖） |
| 代码 | `run_python` | 子进程沙箱执行（隔离模式 + 超时 + 输出截断） |
| 代码 | `run_shell` | 工作区内执行开发命令（白名单 + 危险模式拦截，不走 shell，需确认） |
| 远程服务器 | `list_ssh_hosts / ssh_run / ssh_read_file / ssh_write_file / ssh_upload / ssh_download` | 连用户自配的服务器执行命令、读写与传输文件；凭据加密存储，ssh_run 需确认 |
| 办公 | `create_docx / edit_docx / create_xlsx / edit_xlsx / format_xlsx / create_pptx / beautify_office / read_office / convert_file` | 生成 Word（含表格）/追加编辑 Word/Excel（支持公式与格式）/PPT（封面+要点页）/统一视觉风格，读取四类办公文件；convert_file 转 PDF、PDF 转文本/图片、音频互转与视频抽音轨 |
| 文件 | `read_file / write_file / list_files / delete_file / file_manage` | 每用户隔离的工作区沙箱；file_manage 支持复制/移动/重命名/建目录/打包解压 zip |
| 技能 | `read_skill_file / run_skill_script / create_skill / install_skill_from_url / search_skills_online` | 读取/执行技能包，在线搜索与安装技能 |
| 工作流 / 定时（管理员） | `list_workflows / run_workflow / create_schedule / list_schedules / delete_schedule` | 运行工作流、创建与查询定时任务 |
| 系统 / 渠道 / 模型（管理员） | `list_models / switch_model / token_usage / list_channels / list_skills / list_mcp / list_plugins` | 查询用量、切换模型、查看渠道与扩展能力 |
| 其他 | `get_current_time / calculate / get_my_id / get_system_info / create_artifact / send_artifact / send_voice` | 时间 / AST 安全计算 / 用户标识 / 系统信息 / 产物保存与发送 / 语音发送 |

### 📚 知识库（RAG）
- 解析：PDF / DOCX / XLSX / PPTX / Markdown / HTML / 代码，标题感知分块
- 向量：内置零依赖哈希向量器，或任意 OpenAI 兼容 embedding（建库时可选）
- 检索调试面板：向量 / 全文 / 融合三路命中率与耗时实时可见
- 文档全文预览、分块查看、重建索引、拖拽上传（进度实时反馈）

### 🔀 可视化工作流（对标 Coze）

27 种节点，拖拽连线、双击/选中+Delete/右键删线、撤销重做（Ctrl+Z）、小地图、导入导出 JSON、一键复制、运行历史、SSE 实时进度。节点元数据由后端注册表提供，前端 schema 驱动配置表单，新增节点只需注册 handler 与字段：

| 节点 | 说明 |
|---|---|
| 开始 / 结束 | 入口 / 出口（结束支持输出模板 `{input}/{last}/{context}`） |
| **LLM** | 大模型；**默认"自动"模式 = 拥有全部内置工具自主调用**（也可手动细选/禁用）；输出可存变量 |
| 检索 | 知识库混合检索 → `{context}` |
| 智能体 | 调用智能体页配置（浏览器自动化交给它） |
| **分类** | 意图识别多分支（Coze question-classifier），每类别一个出口 |
| **提取** | LLM 抽取结构化字段，每个字段自动成为变量 |
| 代码 | Python 沙箱（不耗 token），`_wf['WF_INPUT']` 等变量注入 |
| HTTP | 调外部 API，URL/请求体支持插值 |
| 模板 | 零成本变量拼接 |
| 循环 | 列表批量迭代调子工作流（`{item}`/`{item_index}`，上限 30） |
| 子工作流 | 复用其他工作流（最多嵌套 3 层） |
| 条件 | 非空/包含/等于/正则/长度比较 7 种表达式，真假双出口 |
| **HTTP/API** | 支持 Bearer/Basic/API Key 认证、Query/Header/Body、超时、重试、分页、JSON 路径提取 |
| **网页 / RSS** | 网页正文抓取、RSS/Atom 条目拉取 |
| **数据处理** | JSON 解析、字段映射、设置变量、聚合（计数/求和/平均/拼接/去重）、分支合并 |
| **办公** | 读取/写入 CSV、Excel；Word/PPT 生成与文件转换通过「工具」节点调用内置办公工具 |
| **工具** | 统一调用内置工具、插件、MCP 工具与技能脚本 |
| **流程控制** | 等待、节点级超时/重试、失败继续或走 error 错误分支 |

**变量系统**：任意节点可命名输出变量，下游 `{变量名}` 跨节点引用；**并行分支**：一节点多条出边真并发，状态自动合并，汇合节点拿到全部分支结果。
**运行轨迹**：运行时可看到当前节点高亮、连线上的流动标记沿着实际执行路线移动；结束后保留完整路径高亮。
**Webhook 触发**：每个工作流可生成独立 URL + Token，外部系统 POST 即可触发并拿到 run_id。
**教程中心**：核心节点用法说明 + 智能客服路由 / 个性化客服 RAG / 自动化办公周报 / 数据流水线 4 个一键创建模板。

### 📨 消息渠道
- 接入 QQ 官方 Bot（WebSocket 网关）、微信 wxclaw/ilink Bot（轮询）等外部消息平台
- 收到消息走完整对话链路（智能体绑定/知识库/内置工具/插件），回复自动发回渠道
- 每渠道+发送者独立会话隔离；支持文件/图片/视频/语音收发（平台能力范围内）
- 管理界面：连接测试、启停/重启、消息计数、错误显示；支持同类型多渠道实例

### ⏰ 自动化中心
- **定时工作流**：任意工作流按 cron 定时运行（自研 5 段 cron 调度器，支持 `*/n`、范围、列表）
- **AI 定时回答**：定时用一段提示词走完整对话链路（可绑定智能体，默认全工具），**结果自动写入专属对话会话**，随时翻阅历史回答；卡片直接看最近输出
- **✨ AI 生成**：一句话描述（"每天早上 9 点总结科技新闻成日报"）→ AI 出方案（工作流或纯提示词）→ 预览 → 一键创建
- 任务管理：启停、立即运行、运行输入支持 `{date}` `{time}`

### 🔌 扩展
- **MCP**：stdio / streamable_http / sse 三种传输，连接测试、工具发现、可编辑
- **Skill**：SKILL.md 渐进式披露（索引进提示词，正文按需加载）
- **插件**：自定义 Python 插件与钩子（`on_chat_start` / `on_chat_end` 等）

### 🔐 对外 API 与 SDK
- **OpenAI 兼容**：`/v1/chat/completions`、`/v1/models`，任何 OpenAI SDK 改 `base_url` 即可接入
- **稳定门面 `/v1`**：会话、知识库检索/上传、智能体只读、工作流运行与 SSE、定时任务、产物下载、用量汇总
- **API Key 作用域授权**：`chat / knowledge / agents / workflow / files / usage`，支持过期时间、每分钟限流、启用/停用、随时编辑；管理类接口不对 Key 开放
- **Python SDK**：`sdk/agent_framework`（同步/异步、SSE、重试与错误分类）
- 完整契约见 [docs/EXTERNAL_API.md](docs/EXTERNAL_API.md)，示例见 `examples/`

## 快速开始

### 首次准备（只需一次）

```bash
# 后端依赖
cd backend
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt

# 前端依赖
cd ../web
npm install

# Python SDK（可选，供其它项目对接）
cd ../sdk && ../backend/.venv/Scripts/pip install -e .
```

可选：浏览器自动化工具（版本需与本机 chromium 匹配）：

```bash
.venv/Scripts/pip install playwright==1.63.0
.venv/Scripts/python -m playwright install chromium
```

### 启动

**双击根目录的 `start.bat`**：检查依赖 → 自动构建前端（如需）→ 启动单进程 uvicorn 并打开浏览器。

访问 **http://127.0.0.1:8000**（前后端同端口）。首次打开进入初始化引导，设置管理员账号后，所有配置（API Key、知识库、会话）都在同一界面完成。

开发模式（热重载）：`dev.bat`（后端 8000，前端 5173）。

> 搜索工具默认零配置（DuckDuckGo → 必应兜底）；需要更稳定可在系统设置配 `tavily_api_key` 或 `searxng_url`。

## 技术栈

| 层 | 选型 |
|---|---|
| Web | FastAPI + uvicorn，SSE 流式（对话 + 工作流进度双通道） |
| ORM | SQLAlchemy 2.0 async + aiosqlite，WAL 模式，含表结构自动迁移 |
| 认证 | PyJWT + bcrypt；Provider Key / SSH 凭据 Fernet 加密；对外 API Key 支持作用域、过期与限流 |
| Agent | langchain 1.4 / langgraph 1.2：手写 ReAct 图（步数上限/循环检测/并行工具/超时）+ 多套提示词（人设）切换 + 每日 token 配额 |
| 对外 API | OpenAI 兼容 `/v1` + 稳定业务门面；API Key 作用域守卫；独立 Python SDK（httpx） |
| 调度 | 自研 5 段 cron 解析 + asyncio 调度循环（随服务启动） |
| 向量 | sqlite-vec（vec0 虚表）+ 内置哈希向量器（零依赖）或远端 embedding |
| 全文 | SQLite FTS5（中文 bigram 短语查询） |
| 前端 | Vue 3.5 + TS + Vite 6 + Pinia + Vue Flow + markdown-it + highlight.js |

## 目录结构

```
agent框架/
├── backend/app/
│   ├── main.py / bootstrap.py     入口 / 初始化（含调度器启停）
│   ├── core/                      config, db(迁移), security, scheduler,
│   │                              auth(JWT/API Key), api_scopes, rate_limit
│   ├── api/v1/                    auth/chat/conversations/knowledge/agents/
│   │                              workflows/schedules/automation/mcp/skills/
│   │                              api_keys/facade(对外门面)/openai_compat/...
│   ├── providers/                 多 provider 适配（含 reasoning 模型）
│   ├── ingest/ retrieval/         解析分块 / 向量+FTS+RRF 混合检索
│   ├── agents/                    ReAct 图 / runner 一次性执行器
│   ├── tools/builtin/             内置工具（core/web/office/sandbox/browser/files/shell/ssh）
│   ├── services/                  外部服务封装（ssh_client 等）
│   ├── workflows/                 schema 校验（12 种节点/环检测）+ 引擎（变量/并行/循环）
│   └── skills/                    SKILL.md 解析 + 渐进式披露
├── web/src/
│   ├── layouts/AppShell.vue       顶部标签栏 + 主体框架
│   ├── components/                chat（消息流/工具卡/状态环）/ artifact / TopBar / Sidebar
│   ├── pages/                     Chat / Knowledge / Workflows（画布·教程）/
│   │                              Extensions（智能体·定时任务·渠道·语音）/
│   │                              Settings（用量·日志）/ Login
│   └── stores/ api/               Pinia 状态 / axios + SSE 客户端
├── data/                          运行时生成：SQLite / 上传文件 / 产物 / 工作区沙箱
├── sdk/                           独立 Python SDK（agent_framework）
├── examples/                      curl / Python SDK / OpenAI SDK 示例
├── docs/ tools/                   文档 / 验证脚本
└── start.bat dev.bat
```

## SSE 事件协议

对话 `/api/v1/chat/stream`：

| 事件 | 含义 |
|---|---|
| `start` / `end` / `error` | 轮次起止与错误（含 conversation_id、latency） |
| `reasoning` / `content` | 推理 / 正文增量 |
| `tool_call` / `tool_result` | 工具调用与结果 |
| `citation` / `artifact` | RAG 引用 / 新产物 |
| `context` / `compact_start` / `compacted` | 上下文计量与自动压缩 |

工作流 `GET /api/v1/workflows/runs/{id}/stream`：`start` → `step`（每节点）→ `done`（含全部步骤与输出），支持断线重连补发。

## 数据与安全

- SQLite WAL + foreign_keys + busy_timeout；表结构启动时自动增量迁移
- 密码 bcrypt；JWT 7 天；Provider Key / SSH 凭据 Fernet 加密；接口只返回脱敏值
- 数据按 user_id 隔离；工具内置 SSRF 防护与工作区沙箱（路径逃逸拒绝）
- `run_python` / `run_shell` / `ssh_run` / 浏览器工具标记"需确认"风险级，供白名单管控
- SSH 主机密钥默认自动接受（`AutoAddPolicy`），面向不可信网络时请改为已知 hosts 校验

## 对外接入

稳定对外契约：`/v1`（API Key 认证，按作用域授权）。完整说明见 [docs/EXTERNAL_API.md](docs/EXTERNAL_API.md)，示例见 `examples/`。

```python
# OpenAI 兼容端点（任何 OpenAI SDK 可用）
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="ak-...")
resp = client.chat.completions.create(model="...", messages=[...])

# Python SDK（对话 / 流式 / 会话 / 知识库 / 工作流 / 文件 / 用量）
from agent_framework import AgentClient
client = AgentClient("http://127.0.0.1:8000", api_key="ak-...")
print(client.chat("你好").content)

# 兼容旧门面（内部已改走 /v1，ak- 可直接使用）
from app.service_api import AgentClient
```

能力范围：对话（原生 SSE + OpenAI 兼容）、会话、知识库检索与上传、智能体只读列表、工作流运行与进度、定时任务触发、产物下载、用量汇总。
API Key 可设置作用域（chat/knowledge/agents/workflow/files/usage）、过期时间与每分钟限流；管理类接口不对 Key 开放。
工作流还支持 Webhook：在画布工具栏生成独立 URL + Token，外部系统 `POST /api/v1/hooks/{token}` 即可触发并拿到 run_id（`?wait=true` 同步返回结果）。

## 开发说明

```bash
cd backend && .venv/Scripts/python -m pytest tests -q   # 后端测试（939 项）
cd web && npm run build                                  # 前端构建（含 vue-tsc 类型检查）
```

## 开源协议

本项目采用 **Apache License 2.0** 开源，版权人：**bucai241793**。
详见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。

欢迎在 Gitee / GitHub 提交 Issue 或 PR：
- Gitee: https://gitee.com/bucai241793/agent-framework
- GitHub: https://github.com/241793/Agent-Framework