Zihuan-Next：Rust构建的多层AI Agent开发与运行时框架

一个基于Rust的全栈AI Agent框架，统一本地推理和云端API，提供可视化节点图编排引擎和持久化Agent服务运行时，支持QQ机器人、HTTP流式Agent等实际部署场景。

• 原作者/维护者：FredYakumo
• 来源平台：github
• 原始标题：zihuan-next
• 原始链接：https://github.com/FredYakumo/zihuan-next
• 来源发布时间/更新时间：2026-06-08T12:16:04Z

原作者与来源

• 原作者/维护者：FredYakumo
• 来源平台：github
• 原始标题：zihuan-next
• 原始链接：https://github.com/FredYakumo/zihuan-next
• 来源发布时间/更新时间：2026-06-08T12:16:04Z 原作者与来源\n\n- 原作者/维护者：FredYakumo\n- 来源平台：GitHub\n- 原始标题：zihuan-next\n- 原始链接：https://github.com/FredYakumo/zihuan-next\n- 来源发布时间/更新时间：2026-06-08\n\n---\n\n引言：AI Agent开发的复杂性挑战\n\n随着大语言模型技术的成熟，AI Agent（智能代理）正在成为自动化任务、智能客服、内容生成等场景的核心技术。然而，构建一个生产级的AI Agent系统并非易事——开发者需要处理模型调用、工具编排、状态管理、服务持久化、多租户隔离等一系列复杂问题。\n\n传统的Agent开发往往采用脚本式或对话式的方式，难以应对复杂的业务流程和长时间运行的服务需求。而现有的工作流编排工具又往往缺乏与AI模型的深度集成。今天，我们要介绍一个开源项目——zihuan-next，它通过创新的架构设计，将可视化工作流编排与持久化Agent服务有机结合，为AI Agent开发提供了一个全栈解决方案。\n\n---\n\n项目概述：四层架构的统一框架\n\nzihuan-next是一个基于Rust语言构建的多层AI Agent开发与运行时框架。它的核心设计理念是"服务即运行时"——Agent不是一次性脚本，而是长期运行的托管服务。框架围绕两个核心概念构建：\n\n- Agent作为持久化服务运行\n- 节点图定义可复用的工作流和工具\n\n整个框架分为四个层次：\n\n推理层（Inference）\n\n框架统一了本地推理（基于Candle和Llama.cpp）和云端API（OpenAI、Anthropic等）的访问方式。开发者可以定义可复用的llm_refs配置，然后在Agent和图节点中引用这些配置。这种设计允许在一个部署中混合使用：\n\n- 本地推理以控制成本或保护隐私\n- 自托管推理用于内部服务\n- 托管API用于通用推理任务\n\nAgent运行时层（Agent Runtime）\n\n这是框架的核心，托管具有共享Brain工具调用循环的持久化Agent。Agent可以通过管理界面启用、禁用、启动、停止和自动启动。框架支持Harness模式扩展，允许开发者自定义Agent行为。\n\n编排层（Orchestration）\n\n提供DAG图引擎和可视化节点图编辑器，用于设计可复用的工作流和工具。图引擎同步执行DAG，适用于数据转换、消息处理、检索存储、模型调用、准备工具结果等场景。\n\n集成层（Integration）\n\n提供IMS原生机器人适配器、REST API和WebSocket事件流，支持真实世界的部署场景。目前支持QQ聊天机器人和HTTP流式Agent等运行时类型。\n\n---\n\n核心设计哲学：图与服务的分离\n\nzihuan-next的一个重要设计决策是将"图"与"服务"明确分离：\n\n节点图专注于数据流：\n- 图执行是同步的DAG执行\n- 适合数据转换、消息处理、检索步骤等\n- 不适合长期监听器或服务生命周期管理\n\n长期行为由服务层托管：\n- 聊天Agent、HTTP-facing Agent、任务托管\n- 连接复用、运行时编排\n\n这种分离使得图拓扑保持简单，同时允许复杂行为存在于节点、子图和Agent工具循环中。\n\n---\n\n工作流即工具：可复用的设计模式\n\nzihuan-next的一个核心设计点是：同一个节点图逻辑可以在两种角色中使用：\n\n1. 直接作为工作流运行\n2. 挂载到Agent中作为可调用的工具\n\nAgent可以通过共享的Brain/工具循环调用图支持的工具。这使得工作流可以在交互式Agent、服务端点和图驱动自动化之间复用，无需重复编写相同的逻辑。\n\n这种设计模式解决了AI Agent开发中的一个常见问题：业务逻辑的重复实现。开发者只需在可视化编辑器中定义一次工作流，就可以在多种场景中使用。\n\n---\n\n统一连接与资源管理\n\n在zihuan-next中，连接是一等公民的系统配置，而不是隐藏在单个工作流中的临时值。开发者在管理界面中定义连接配置一次，然后可以从Agent和节点图中复用。\n\n目前支持的资源类型包括：\n\n- MySQL：关系型数据库连接\n- Redis：内存数据存储\n- Weaviate：向量数据库\n- RustFS/S3：对象存储\n- IMS Bot Adapter：即时通讯机器人适配器\n- Tavily：搜索API\n- Tokenizer：NLP文本分词器\n\n运行时区分两种概念：\n- 由config_id标识的持久化连接配置\n- 由instance_id标识的实时运行时连接实例\n\n图和Agent引用config_id，运行时在需要时创建或复用实时实例。这使得数据库和服务连接可以集中管理，同时仍然可以被图节点和Agent运行时直接使用。\n\n---\n\n文本分词与QQ聊天Agent\n\n项目特别关注了中文场景的支持，提供了QQ聊天Agent的完整实现。在文本分词方面，框架引入了新的tokenizer连接类型。\n\n推荐的Tokenizer模型选项：\n\n快速启动方案（无需额外下载）：\n- 复用现有的models/text_embedding/Qwen3-Embedding-0.6B/tokenizer.json\n- 复制到models/tokenizer/qwen3-embedding-0.6b/tokenizer.json\n\n高精度推荐方案（当前优先）：\n- 使用Qwen/Qwen3-235B-A22B的Tokenizer\n- 下载命令：huggingface-cli download Qwen/Qwen3-235B-A22B tokenizer.json --local-dir models/tokenizer/qwen3-235b-a22b\n\n配置完成后，在管理界面创建Tokenizer连接，然后在QQ聊天Agent设置中指定Tokenizer连接即可使用。\n\n---\n\n技术实现亮点\n\nRust语言的优势\n\n选择Rust作为开发语言带来了多方面的优势：\n\n- 性能：Rust的零成本抽象和内存安全保证使得框架能够高效处理高并发场景\n- 可靠性：编译时内存安全检查消除了大量的运行时错误\n- 并发：Rust的所有权模型使得编写安全的并发代码变得更加容易\n- 生态系统：Rust拥有 growing 的AI/ML生态系统，包括Candle等本地推理框架\n\n前端技术栈\n\n管理界面和图编辑器采用现代前端技术栈：\n- Node.js 18+ 运行时\n- pnpm 包管理器\n- 前端资源被打包嵌入到主二进制文件中\n\n模块化架构\n\n项目采用清晰的模块化结构：\n\n| 包名 | 职责 |\n|------|------|\n| zihuan_next | 主二进制，嵌入前端资源，托管Agent和API |\n| zihuan_graph_cli | 命令行图执行器 |\n| zihuan_graph_engine | 核心图执行引擎（DAG、节点、边、变量） |\n| zihuan_graph_editor | 可视化节点图编辑器 |\n| zihuan_brain | Agent工具调用循环和推理抽象 |\n| zihuan_harness | Agent运行时扩展接口 |\n| model_inference | Candle和Llama.cpp本地推理封装 |\n| ims_bot_adapter | QQ、Discord等即时通讯机器人适配器 |\n| storage_handler | 统一存储抽象（RustFS/S3） |\n| general_wheel_cpp | 通用C++工具库 |\n\n---\n\n使用场景与部署模式\n\n场景一：QQ聊天机器人\n\n通过IMS Bot Adapter，开发者可以快速部署QQ聊天机器人。Agent持续运行，接收消息，调用LLM生成回复，并通过图工作流处理复杂的业务逻辑（如查询数据库、调用外部API等）。\n\n场景二：HTTP流式Agent\n\n框架支持HTTP流式响应，适合构建Web应用的后端服务。Agent可以处理用户请求，通过图编排执行多步骤任务，并以流式方式返回结果。\n\n场景三：定时任务自动化\n\n结合CLI图执行器，可以将工作流作为定时任务运行。例如，定时抓取数据、生成报告、发送通知等。\n\n场景四：混合推理部署\n\n对于需要数据隐私保护的场景，可以将敏感任务路由到本地推理模型；对于通用任务，则使用云端API。框架的统一抽象使得这种混合部署变得透明。\n\n---\n\n快速入门指南\n\n环境要求\n\n- Rust stable\n- Node.js 18+\n- pnpm\n\n可选服务（根据配置）：\n- MySQL\n- Redis\n- Weaviate\n- RustFS\n\n构建步骤\n\nbash\ngit clone https://github.com/FredYakumo/zihuan-next.git\ncd zihuan-next\ngit submodule update --init --recursive\n\ncd webui\npnpm install\ncd ..\n\ncargo build --release\n\n\n运行\n\nbash\ndocker compose -f docker/docker-compose.yaml up -d\n./target/release/zihuan_next\n\n\n默认地址：http://127.0.0.1:9951\n\n自定义绑定：./target/release/zihuan_next --host 0.0.0.0 --port 9000\n\n---\n\n管理界面功能\n\n框架提供了功能丰富的Web管理界面：\n\n- 主页 (/)：系统概览和状态监控\n- 图编辑器 (/editor)：可视化工作流设计\n- 连接管理：配置MySQL、Redis、Weaviate等资源连接\n- 模型引用：配置LLM和嵌入模型的访问方式\n- Agent管理：创建、配置、启动、停止Agent服务\n- 任务监控：查看任务执行状态和日志\n- 运行时检查：查看连接实例和Agent运行状态\n\n---\n\n结语：AI Agent开发的新范式\n\nzihuan-next代表了一种新兴的AI Agent开发范式：将可视化工作流编排与持久化服务运行时相结合，通过清晰的架构分层和统一的资源管理，降低生产级Agent系统的开发复杂度。\n\n它的设计理念——"服务即运行时"、"工作流即工具"、"连接即配置"——为AI Agent开发提供了新的思考角度。对于需要构建复杂Agent系统的开发者来说，zihuan-next提供了一个值得深入研究的参考实现。\n\n随着AI技术的持续发展，我们可以期待看到更多类似的框架出现，帮助开发者更轻松地构建智能、可靠、可扩展的AI Agent应用。