Mio Chat Backend MCP Server

<div align="center"> <h1>MioChat</h1> <img src="https://s3.krumio.com/file/web/eadf69/miochat-logo.gif" width="600" alt="MioChat Logo" />

MioChat —— 不仅仅是对话转发，更是下一代 Agent 操作系统

开源的、模型无关的 Agent 运行时：Agent / Session / SubAgent 三级上下文模型、V3 Hook 切面、MCP 与 Skills 双标准工具生态、多渠道接入，以及可无人值守长跑的定时自治。

在线演示 | 文档中心 | QQ 交流群 | English

🖥️ Mio-Chat Frontend · 🎨 Mio-Previewer (MD 渲染器) · 🔌 插件市场

</div>

---

Mio-Chat 是一个由多个模块构成的完整 Agent 生态系统：

模块	仓库地址	说明
Backend	Pretend-to/mio-chat-backend	(当前仓库) 核心运行环境、Hook 架构、插件系统
Frontend	Pretend-to/mio-chat-frontend	基于 Vue 3 + Element Plus 的沉浸式 Agent 交互界面
Renderer	Pretend-to/mio-previewer	专为 AI 深度定制的 Markdown 渲染引擎，支持 Artifacts
Plugins	Pretend-to/awesome-miochat-plugins	官方及社区维护的插件、Skill、Hook 集合仓库

为什么做它

<details> <summary><b>Agent = 模型 + Harness —— 这个项目立起来的立场</b></summary>

传统的 AI 对话平台仅仅是简单的"API 搬运工"。MioChat 是专为复杂生产环境设计的 Agent 操作系统。它通过精密的上下文管理、双向安全授权、Multi-Agent 多智能体协同和面向切面的 Hook 拦截机制，让 AI 能够真正地、自主地、安全可控地操作物理世界。

大家都在用的核心 agent 循环只有五行 ReAct。可感知的差异全部发生在循环之外：上下文管理、权限、工具契约、流式可靠性、记忆。MioChat 想做的，是把这些层全部握在自己手里——模型无关、自托管、中间没有任何黑盒。前后端两个仓库合计约 17 万行代码（含测试，不含构建产物），正是"能演示"与"能无人值守跑任务而不丢上下文、不丢消息、不丢信任"之间的全部差距。

</details>

演示

<img src="./docs/assets/demo/demo.gif" width="720" alt="MioChat 演示 — 一句话 → 多模型路由 → 工具执行 → 渲染 UI" />

架构

<img src="./.github/diagrams/architecture-zh.svg" width="860" alt="MioChat — Agent Ecosystem architecture" />

特性亮点

📊 统一后台设置与可视化 Dashboard

提供企业级的全局配置管理与全链路可观测性，告别黑盒与繁琐的配置文件。

• 全局系统与存储中心：支持在本地存储 (Local) 与 S3 兼容对象存储 (AWS S3 / Cloudflare R2 / MinIO) 之间零重启热切换；系统配置统一持久化至 SQLite，通过界面与 REST API 即时热生效。
• 动态模型管理：内置 LiteLLM 数据库动态同步引擎（覆盖 3,200+ 种主流及开源模型规格），支持自定义 Provider、API Key、Base URL、上下文窗口及 Temperature 动态调优。
• 可观测性仪表盘：实时可视化监控系统吞吐量、Token 消耗统计（Prompt / Completion 细分）、调用延迟分布以及各 Agent 的会话活跃度。

<img src="./docs/assets/screenshots/dashboard.png" width="800" alt="MioChat 后台设置与可视化 Dashboard 监控界面" />

🔌 工具热插拔与现代化插件架构

兼顾跨语言标准生态与运行时极速扩展，打造零停机维护的工具生态。

• 规范化插件目录：清晰解耦元数据、工具函数与拦截切面：

  my-plugin/
  ├── plugin.json       # 插件元信息（名称、版本、依赖权限等）
  ├── index.js          # 插件入口（继承 MioPlugin，定义生命周期）
  ├── tools/            # 工具集（继承 MioFunction，带 Zod 参数校验与 final run 安全守卫）
  └── hooks/            # 挂载在全系统 16 个生命周期切面上的 Hook 拦截器
  

• 零停机动态热插拔 (Zero-Downtime Hot-Reload)：无需重启后端服务即可动态加载、卸载或更新插件代码；前端支持 Tools Manager，允许在特定会话中按需启用或禁用具体工具。
• 三层生态深度融合：全面兼容开放标准 Agent Skills 专家经验（自动扫描 .claude/ / .cursor/ / .gemini/）+ MCP (Model Context Protocol) 协议接入 + 原生高响应 Native Tools。

🤖 OneBot (QQ) 接入

把 QQ 生态接进同一套 Agent 运行时。

• 主动长连接与状态可视化：后端按配置直接连接 OneBot 应用端（go-cqhttp / NapCat / Lagrange 等），管理面板实时展示连接阶段（已连接 / 连接中 / 未连接 / 配置不完整）、上次发起连接的时间与结果、尝试次数与失败原因。
• 保存即生效：修改配置保存后立即按新配置重建连接（旧连接优雅关闭），也可在面板上手动重连。
• 消息贯通：群聊 / 私聊消息、图片、合并转发、撤回等事件与 Web 端共用同一套联系人、消息链与工具体系。

📱 全平台多渠道接入 (Channels - Beta 测试阶段)

让 Agent 无缝融入微信等日常即时通讯工具，赋予专属灵魂与全模态感知。当前处于 Beta 测试阶段，首发完整对接微信 (WeChat iLink Bot)，后续将陆续扩展更多渠道平台。

• 微信 iLink 极速接入：前端生成登录二维码，手机扫码确认后后端自动建立凭证并秒级拉起长轮询服务，实现零手动干预的无缝开箱即用。
• 全模态解密与消费：
  • 🖼️ 图片解密：AES-128-ECB 密文下载解密 -> 转存存储 -> 自动组装为多模态消息数组，支持多轮对话图文历史回溯。
  • 📄 文件支持：PDF / Word / Excel / 代码文件密文解密 -> 自动生成 Markdown 访问链接并驱动 parse 工具自主解析。
  • 🎙️ 极速语音：直接读取腾讯原生服务端 ASR 语音转写文本，毫秒级流式响应。
• 1.2s 智能防抖聚合队列：专为微信高频连续推送场景打造，自动聚合用户连发的「多张图片」、「先发文件再发字」等碎片化消息，杜绝 AI 抢答与并发乱序。
• 独立灵魂与记忆持久化：每个渠道独立绑定 AgentId，拥有专属灵魂设定（Soul）、长期记忆（GlobalMem）、会话结晶（Crystal），并支持 /soul、/model、/sessions 等全套 Slash 交互命令。

<img src="./docs/assets/screenshots/channels.png" width="800" alt="MioChat 微信渠道管理与多渠道接入界面" />

🧬 Agent · Session · SubAgent：三级上下文模型

把"一个机器人绑一个窗口"升级为可编排、可隔离、可长跑的智能体运行时。

① Agent 是主体，Channel 只是入口

• Agent 拥有名称、头像、人格（Soul）、模型、工具、技能与长期记忆；Message、Chunk、ToolCall、Crystal、PendingMemory 全部通过 Session 归属到 Agent。
• Channel 只保存平台、账号凭据、连接状态与协议能力，不拥有 Agent、不拥有模型、不拥有人格、也不拥有聊天记录。
• 二者是多对多：同一个 Agent 可以同时出现在 Web、微信等多个入口；同一个入口也可以挂载多个 Agent —— 这正是下面「多 Agent 混合群组」的地基。

② Session 是上下文单位，子 Session 构成一棵树

一个 Agent 可以有多个 Session，Session 通过 parentSessionId 派生出有向树。子 Session 承载 SubAgent 与任意隔离执行上下文，与父 Session 共享同一个 Agent 与 Channel，但各自独立持有 MessageChain、运行 FIFO 与锁、LLM 调用历史、工具调用记录、超时与取消信号。

Agent
└── Session（主）              ← 用户可见的主消息链
    ├── Session（子）：行情调研   ← 自有上下文，不占主窗口
    │   └── Run: 09-05 / 09-06 / 09-07
    └── Session（子）：日报编辑
        └── Run: 09-05 / 09-06 / 09-07

③ SubAgent 是两级编排：RunGroup / Run

• RunGroup 是一次编排事务，Run 是其中单个执行单元；多个 Run 默认并行，用 dependsOn 声明 DAG 依赖即可串行。
• 每个 Run 使用独立 child Session，不会创建永久 Agent；工具权限是当前 Agent 有效工具集的子集，并在创建 Run 时冻结。
• sessionPolicy 控制上下文延续：fresh 每次全新隔离；persistent 复用同一个 child Session，后续用 continue 把新一轮追加在尾部 —— 长周期任务因此能"越跑越懂"。
• 完成后只唤醒主 Agent 并汇报 groupId / runId，不注入结果正文；主 Agent 主动 read_result 拉取。父 Session 默认只看到最终摘要或产物引用，看不到子任务的搜索与工具调用全过程。

为什么这样切：主 Session 的消息链保持稳定，才能持续命中 Prompt Cache；重活与脏活留在子上下文中，主窗口不被噪声挤占 —— 这是"能演示"与"能无人值守跑一周而不丢上下文"之间的差别。

🧠 多 Agent 混合群组

打破单 Agent 孤岛，实现异构 LLM 与多元人格的集群智慧。

• 支持在同一个群聊中加入多个不同 Channel 驱动的 Agent 本尊。
• 支持 @指定 Agent 响应或多 Agent 顺序/条件触发讨论，实现复杂工程问题下的多视角交叉审核与协作。
• 一条共享消息链、N 个成员各自的上下文视图（见前端）。

<img src="./docs/assets/screenshots/group-chat.png" width="800" alt="Multi-Agent 群聊讨论示意图" />

❄️ 上下文工程：记忆结晶

解决长对话 Token 暴增与上下文溢出的行业痛点。

• 5 大 XML 结构化分区：将用户画像、短期目标、当前计划、工程结构增量与全局约束规范化隔离。
• 无状态结晶与前缀缓存：动态判定 Token 水位线，扫描对话轮次边界，自动将冗余历史提炼为只读 Memory Fragment，极限命中 Gemini / Claude 的 Prompt Cache，降低 80%+ Token 开销，首字延迟缩短至毫秒级。

<img src="./docs/assets/screenshots/crystallization.png" width="800" alt="记忆结晶与上下文压缩示意图" />

🛡 安全：交互式工具挂起

解决 AI 自主执行危险工具（如 Shell 命令、文件删除、公网发布）时的安全失控难题。

• 面向切面挂载：在 LLM 推理与 ReAct 工具循环的生命周期中暴露核心拦截切面。
• Deferred Promise 异步挂起：判定为敏感操作时，后端创建 Deferred Promise 暂停 ReAct 循环，并通过 WebSocket 向前端推送二次确认卡片；待管理员点击放行后，唤醒 Promise 继续推进流程。

<img src="./docs/assets/screenshots/tool-suspend.png" width="800" alt="敏感工具二次确认与授权挂起卡片" />

⏰ 定时任务与后台巡检

赋予 Agent 离线自治与可视化巡检能力。

• 灵活调度：支持标准 Cron 表达式、相对时间与单次触发（once），内置防重复执行闭环。
• 可视化面板与安全沙盒：前端提供专用的 Task 管理面板，可直观查看执行日志与手动唤醒；后端支持设置任务专属 Prompt 与 shell 命令白名单，防止 Agent 陷入无意义的用户交互等待。

<img src="./docs/assets/screenshots/cron-task.png" width="800" alt="定时任务与后台 Agent 巡检界面" />

🎨 Artifacts 与动态工具管理

• Artifacts 画板交互：结合 mio-previewer，实现代码、HTML 网页、SVG 矢量图、Mermaid 流程图及动态 UI 组件的独立画板预览与分屏交互。
• Tools Manager 动态调配：前端支持在会话中实时感知与开关指定的工具或插件组，随心所欲调配 Agent 技能库。

类型与规模

数字取自当前仓库，改代码时顺手同步这一节。开发约定与红线见 AGENTS.md。

维度	数量	说明
内置插件	9	lib/plugins/：ai / agent-manager / anyui / config / edge-tts / file-editor / mcp / terminal-pty / web
独立包插件	3	plugins/（pnpm workspace）：custom / email-plugin / note-plugin
声明式工具	43	lib/plugins/*/tools/；MCP 动态工具与 Skill 不计在内
Hook 挂载点	16	其中内置 hook 9 个（lib/hooks/builtins/）
LLM 适配器实现	7	openai / openai-responses / anthropic / gemini / gemini-oauth / xai / agent-platform（内含多家 OpenAI 兼容厂商）
搜索适配器	5	baidu / bing / duckduckgo / tavily / volcengine，另有浏览器桥（browserBridge）
图片生成适配器	6	openai / google / sd-webui / siliconflow / tukuai / volcengine
渠道适配器	1	微信 iLink（native + onebots 双运行时），注册表按定义扩展
Prisma 模型	40	prisma/schema.prisma
HTTP 路由	126	lib/server/http/index.js
Socket 协议	4	llm / onebot / system / logs

Agent 自我管理工具按资料、长期人格和默认投递拆分；后台 Agent 可沿用默认外部渠道安排下一次工作。详见 自我管理与默认投递。

Hooks 机制

Mio-Chat V3 采用面向切面编程的设计理念。通过一系列生命周期钩子，你可以精准控制 Agent 的每一步操作。7 个核心挂载点（全系统共 16 个）：

挂载点	作用	典型应用场景
LLM_BEFORE_CHAT	对话拦截	敏感词过滤、余额预扣费、Context 注入
LLM_BEFORE_RECURSION	递归轮次拦截	按工具调用轮次动态调整工具列表、注入轮次上下文
TOOL_BEFORE_LOAD	加载审计	校验工具名称安全性、防止插件冲突
TOOL_BEFORE_EXECUTE	执行干预	权限动态校验 (RBAC)、参数自动修复、挂起拦截
LLM_AFTER_CHAT	结果审计	Token 用量落库、响应内容脱敏
LLM_TOOL_RESULTS	工具调用审计	批量工具执行完成后记录工具参数与出参详情
TOOL_NOT_FOUND	智能纠错	剥离 MD5 后缀自动寻址、用户引导提示

另有 9 个内置 hook（审计、限流、响应长度上限、权限校验、模型权限、参数校验…）。所有工具都走 MioFunction.run()——带守卫、内容哈希命名、超时兜底，且该方法是 final，无法通过子类覆写绕过校验。详情参考：📖 Hooks 开发指南。

前端与插件

• 前端——harness 的渲染层（流式可靠性、群聊上下文隔离、客户端记忆、手写 PWA）在独立的 mio-chat-frontend 仓库。
• 插件 / Skill / Hook 集合——官方及社区维护：awesome-miochat-plugins。

快速开始

git clone --depth 1 https://github.com/Pretend-to/mio-chat-backend.git
cd mio-chat-backend
pnpm install
pnpm start
pm2 logs mio-chat-backend

首次启动会自动完成数据库与 schema 初始化（内置在 app.js 初始化链路中）。随后打开 Web UI，在管理面板中配置你的 LLM 适配器 / OneBot / 插件即可——所有设置结构化存储于 SQLite，通过界面与 API 管理。

前端（独立仓库，自动同步后端模型列表）：

git clone https://github.com/Pretend-to/mio-chat-frontend.git
cd mio-chat-frontend && pnpm install && pnpm dev

测试

pnpm test:unit         # 日常开发：单元测试（隔离运行，不动你的真库）
pnpm test:integration  # 集成 / OneBot 用例，需后端跑在 http://localhost:3080
pnpm test              # 完整套件

pnpm test:unit 会把单测跑在一个隔离工作区里，并把当前数据库的副本交给测试进程 —— 不会污染你的 data/app.db。集成用例默认访问 http://localhost:3080，可用 BASE_URL 与 ADMIN_CODE 覆盖目标地址与管理码。

文档

分类	内容大纲
🚀 快速开始	完整部署与玩法 | PM2 部署 | Docker 部署 | 配置指南
🧠 核心机制	上下文压缩原理 | Hooks 拦截机制 | Socket 协议
🛠️ 开发指南	插件开发手册 | Skill 编写规范 | Adapter 模板
🗄️ 归档资料	架构迁移历史 | 常见问题 Q&A

贡献

我们欢迎任何形式的贡献。Mio-Chat 的演进由社区驱动：

1. 贡献 Plugin：赋予 Agent 操作新领域工具的能力。
2. 贡献 Skill：沉淀特定领域的专家经验指南。
3. 贡献 Hook：完善系统的防御与审计体系。

🙏 致谢

本项目使用 JetBrains 开源项目开发许可证进行开发——感谢 JetBrains 为本开源项目提供的免费专业 IDE 许可证。

许可证

MIT —— © 2026 MioChat contributors