MioChat —— 不仅仅是对话转发，更是下一代 Agent 操作系统
开源的、模型无关的 Agent 运行时：Agent / Session / SubAgent 三级上下文模型、V3 Hook 切面、MCP 与 Skills 双标准工具生态、多渠道接入，以及可无人值守长跑的定时自治。
在线演示 | 文档中心 | QQ 交流群 | English
🖥️ Mio-Chat Frontend · 🎨 Mio-Previewer (MD 渲染器) · 🔌 插件市场
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 集合仓库 |
Agent = 模型 + Harness —— 这个项目立起来的立场
传统的 AI 对话平台仅仅是简单的"API 搬运工"。MioChat 是专为复杂生产环境设计的 Agent 操作系统。它通过精密的上下文管理、双向安全授权、Multi-Agent 多智能体协同和面向切面的 Hook 拦截机制，让 AI 能够真正地、自主地、安全可控地操作物理世界。
大家都在用的核心 agent 循环只有五行 ReAct。可感知的差异全部发生在循环之外：上下文管理、权限、工具契约、流式可靠性、记忆。MioChat 想做的，是把这些层全部握在自己手里——模型无关、自托管、中间没有任何黑盒。前后端两个仓库合计约 17 万行代码（含测试，不含构建产物），正是"能演示"与"能无人值守跑任务而不丢上下文、不丢消息、不丢信任"之间的全部差距。
提供企业级的全局配置管理与全链路可观测性，告别黑盒与繁琐的配置文件。
- 全局系统与存储中心：支持在本地存储 (Local) 与 S3 兼容对象存储 (AWS S3 / Cloudflare R2 / MinIO) 之间零重启热切换；系统配置统一持久化至 SQLite，通过界面与 REST API 即时热生效。
- 动态模型管理：内置 LiteLLM 数据库动态同步引擎（覆盖 3,200+ 种主流及开源模型规格），支持自定义 Provider、API Key、Base URL、上下文窗口及 Temperature 动态调优。
- 可观测性仪表盘：实时可视化监控系统吞吐量、Token 消耗统计（Prompt / Completion 细分）、调用延迟分布以及各 Agent 的会话活跃度。
兼顾跨语言标准生态与运行时极速扩展，打造零停机维护的工具生态。
- 规范化插件目录：清晰解耦元数据、工具函数与拦截切面：
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。
把 QQ 生态接进同一套 Agent 运行时。
- 主动长连接与状态可视化：后端按配置直接连接 OneBot 应用端（go-cqhttp / NapCat / Lagrange 等），管理面板实时展示连接阶段（已连接 / 连接中 / 未连接 / 配置不完整）、上次发起连接的时间与结果、尝试次数与失败原因。
- 保存即生效：修改配置保存后立即按新配置重建连接（旧连接优雅关闭），也可在面板上手动重连。
- 消息贯通：群聊 / 私聊消息、图片、合并转发、撤回等事件与 Web 端共用同一套联系人、消息链与工具体系。
让 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 交互命令。
把"一个机器人绑一个窗口"升级为可编排、可隔离、可长跑的智能体运行时。
① 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 孤岛，实现异构 LLM 与多元人格的集群智慧。
- 支持在同一个群聊中加入多个不同 Channel 驱动的 Agent 本尊。
- 支持 @指定 Agent 响应或多 Agent 顺序/条件触发讨论，实现复杂工程问题下的多视角交叉审核与协作。
- 一条共享消息链、N 个成员各自的上下文视图（见前端）。
解决长对话 Token 暴增与上下文溢出的行业痛点。
- 5 大 XML 结构化分区：将用户画像、短期目标、当前计划、工程结构增量与全局约束规范化隔离。
- 无状态结晶与前缀缓存：动态判定 Token 水位线，扫描对话轮次边界，自动将冗余历史提炼为只读 Memory Fragment，极限命中 Gemini / Claude 的 Prompt Cache，降低 80%+ Token 开销，首字延迟缩短至毫秒级。
解决 AI 自主执行危险工具（如 Shell 命令、文件删除、公网发布）时的安全失控难题。
- 面向切面挂载：在 LLM 推理与 ReAct 工具循环的生命周期中暴露核心拦截切面。
- Deferred Promise 异步挂起：判定为敏感操作时，后端创建 Deferred Promise 暂停 ReAct 循环，并通过 WebSocket 向前端推送二次确认卡片；待管理员点击放行后，唤醒 Promise 继续推进流程。
赋予 Agent 离线自治与可视化巡检能力。
- 灵活调度：支持标准 Cron 表达式、相对时间与单次触发（
once），内置防重复执行闭环。 - 可视化面板与安全沙盒：前端提供专用的 Task 管理面板，可直观查看执行日志与手动唤醒；后端支持设置任务专属 Prompt 与 shell 命令白名单，防止 Agent 陷入无意义的用户交互等待。
- 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 |
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 devpnpm 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 的演进由社区驱动：
- 贡献 Plugin：赋予 Agent 操作新领域工具的能力。
- 贡献 Skill：沉淀特定领域的专家经验指南。
- 贡献 Hook：完善系统的防御与审计体系。
本项目使用 JetBrains 开源项目开发许可证进行开发——感谢 JetBrains 为本开源项目提供的免费专业 IDE 许可证。
MIT —— © 2026 MioChat contributors