通用智能体框架：对话 + RAG 知识库 + 可视化工作流 + 定时自动化 + 对外 API，开箱即用。
基于 LangChain 1.x + LangGraph 1.x，数据层为 SQLite（向量 + 全文检索，零外部服务依赖），前端 Vue 3（暖砂石主题，顶部标签栏 + 对话侧栏 + 产物面板）。本项目可作为 Agent 项目的基座，也可作为其它系统的 AI 能力后端（稳定 /v1 API + Python SDK），供新手学习参考。
对话（智能体/工具/知识库） ── 知识库（RAG） ── 工作流（画布 + 定时任务）
└────────── 扩展中心（智能体 / 渠道 / 语音 / MCP / 技能 / 插件）──────────┘
对外 API（OpenAI 兼容 + /v1 门面 + Python SDK）
顶栏只有 3 个一级入口：对话 / 知识库 / 工作流。对话页侧栏「新建对话」下方还挂着 扩展 与 设置 两个入口，点击后以**全屏弹层（二级界面）**打开：扩展中心包含智能体、定时任务、消息渠道、语音、MCP/技能/插件与对外 API；设置包含模型与向量、文件、SSH、Git、用量、日志、账号与系统。设置也可从右上角头像菜单进入。旧链接（
/extensions、/agents、/automation、/channels、/voice、/settings、/logs、/usage）会自动重定向并打开对应弹层，/workflows保持独立页面。
- 流式输出（正文 / 推理过程 / 工具调用实时卡片），可停止、重新生成（非破坏式，被替换消息可回看）、编辑重发
- 会话绑定智能体：系统提示词 / 工具白名单 / 模型 / 最大步数全部生效；支持**多套提示词（人设）**保存与一键切换
- 上下文窗口管理：token 实时计量（状态环）、超限自动压缩为摘要
- 产物面板：代码 / HTML / SVG 预览、图片、引用溯源、文件下载
- 侧栏搜索、消息时间戳、导出 Markdown、斜杠命令、深浅色主题（跟随系统）
| 类别 | 工具 | 说明 |
|---|---|---|
| 知识库 | 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 安全计算 / 用户标识 / 系统信息 / 产物保存与发送 / 语音发送 |
- 解析：PDF / DOCX / XLSX / PPTX / Markdown / HTML / 代码，标题感知分块
- 向量：内置零依赖哈希向量器，或任意 OpenAI 兼容 embedding（建库时可选）
- 检索调试面板：向量 / 全文 / 融合三路命中率与耗时实时可见
- 文档全文预览、分块查看、重建索引、拖拽上传（进度实时反馈）
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等）
- 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，示例见
examples/
# 后端依赖
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 匹配）：
.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
对话 /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，示例见 examples/。
# 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 同步返回结果）。
cd backend && .venv/Scripts/python -m pytest tests -q # 后端测试（939 项）
cd web && npm run build # 前端构建（含 vue-tsc 类型检查）本项目采用 Apache License 2.0 开源，版权人：bucai241793。 详见 LICENSE 与 NOTICE。
欢迎在 Gitee / GitHub 提交 Issue 或 PR：