YunTaiHua/illusion-agent

IllusionAgent

PyPI Python Platform GitHub

幻想与实用，于此交融。融合多个开源项目精华，构建统一智能代理。

📖 项目简介

IllusionAgent 是一款开源的 AI 智能体平台。它将多模型语言模型网关、
中英双语命令行、浏览器端 Web 界面与可扩展的插件生态融为一体，
在 Windows、macOS、Linux 之上皆能从容运行。

无论你习惯终端的克制，还是偏爱浏览器的舒展，IllusionAgent 都能与你的工作流共振：
丰富的内置工具集、专业子代理、2 种压缩方法、MCP 服务器支持、
钩子、插件，以及面向无人值守场景的 Cron 调度器，贯通飞书、微信、QQ 三大渠道。

站在巨人之肩 —— Claude Code 提示词体系、OpenHarness 架构理念、
OpenClaw 调度设计、kimi-cli 基础设施、hermes-agent 渠道模式、cc-switch 路由方案。

核心特性

- 🤖 多 AI 提供商支持 - Anthropic Claude、OpenAI、GitHub Copilot、OpenAI Codex 及任意 OpenAI 兼容端点
- 🧠 多智能体协作 - 内置通用、探索、验证等专业子代理，支持任务编排
- 🛠️ 丰富的工具集 - 完整的基础 + 渠道工具集 + MCP 动态工具扩展
- 📦 上下文压缩 - 微压缩（清除旧工具结果）+ 全压缩（LLM 摘要），上下文占满时自动触发
- 🌐 Web UI 界面 - 通过 illusion web 启动浏览器聊天界面，与终端界面相互独立、同等可用
- 🌍 中英双语支持 - 所有 CLI 输出根据 ui_language 设置自动切换中英文
- 📝 全面 Markdown 渲染 - 直角边框表格、圆角卡片代码块、多色富文本
- 🔌 灵活扩展系统 - 插件、钩子、技能、MCP 服务器
- 🔐 完善权限控制 - 三种模式 + 细粒度规则 + Always Allow 一键放行
- 🎯 推理强度控制 - 支持 low/medium/high/xhigh/max 五种推理强度级别
- 🪟 Windows 系统深度优化 - 自动查找 Git、PowerShell 支持
- 🖥️ 终端渲染零闪烁 - 基于 Ink Static 组件的稳定渲染
- 📦 桌面版 - Electron 壳内置 Python/Node.js 运行时，三端安装包分发，零环境配置，支持应用内自动更新

界面展示

欢迎界面 & 富文本渲染

演示视频

📺 B站观看演示视频

🚀 快速开始

环境要求

- Python >= 3.10
- 支持 Windows、macOS、Linux
- Node.js 18+（仅源码安装需要，pip install illusion-agent 无需 Node.js）

安装

推荐方式：从 PyPI 安装（无需 Node.js）
pip install illusion-agent

备选方式：从源码安装（需要 Node.js 18+）
git clone https://github.com/YunTaiHua/illusion-agent.git
cd illusion-agent
pip install .

桌面版

不想安装 Python 或 Node.js？直接下载对应平台的安装包，内置运行时，零环境配置：

| 平台 | 下载文件 |
|------|----------|
| Windows | IllusionAgent-Setup-.exe（NSIS 安装器） |
| macOS | IllusionAgent--arm64.dmg |
| Linux | IllusionAgent--amd64.deb 或 IllusionAgent--x86_64.AppImage |

👉 从 GitHub Release 下载

桌面版内置 Python 3.12 和 Node.js 24 运行时，详见桌面版文档。

基本使用

首次使用：配置认证（登录后会引导设置工作目录）
illusion auth login

启动交互式会话（推荐）
illusion

启动 Web UI 浏览器界面
illusion web

非交互式打印模式
illusion -p "帮我分析这个项目的结构"

设置或更新工作目录
illusion set "E:\Projects\my-project"

Print 模式说明

-p / --print 以非交互方式执行单次请求并立即退出：

只读分析（安全，默认权限模式）
illusion -p "帮我分析这个项目的结构"

允许写入文件 / 执行命令，无需交互式审批
illusion --permission-mode full_auto -p "修复失败的测试"

进程以退出码 2 结束后，继续回答待处理的问题 / 权限 / 计划
illusion -c -p "Y"

指定模型和 effort 等级用于 print 模式
illusion -m env_1.model_2 -e high -p "重构此模块"

重要细节：

- 提示词值必须放在 最后一个参数，因为 typer 会贪婪解析 -p。
- 默认权限模式下，变更类工具会以退出码 2 退出并保留待审批项；使用 illusion -c -p "Y"、"F" 或 "N" 继续回答。
- 退出码：0 成功，1 错误，2 等待跨轮次输入。

界面说明

终端（illusion）与 Web UI（illusion web）是两个相互独立、同等重要的界面。它们共享同一个后端运行时、设置和会话存储，按你的工作流选择即可。

📚 详细文档

| 主题 | English | 中文 |
|------|---------|------|
| 项目简介 | docs/en/introduction.md | docs/zh-CN/introduction.md |
| 快速开始 | docs/en/getting-started.md | docs/zh-CN/getting-started.md |
| 命令系统 | docs/en/commands.md | docs/zh-CN/commands.md |
| Goal 自动续跑目标 | docs/en/goal.md | docs/zh-CN/goal.md |
| 设置与凭据 | docs/en/settings.md | docs/zh-CN/settings.md |
| 项目文件与记忆 | docs/en/project-files.md | docs/zh-CN/project-files.md |
| 扩展系统 (MCP, 插件, 技能, 钩子) | docs/en/extensions.md | docs/zh-CN/extensions.md |
| 项目架构 | docs/en/architecture.md | docs/zh-CN/architecture.md |
| Web UI 安全 | docs/en/security.md | docs/zh-CN/security.md |
| Token 计量与压缩 | docs/en/token-metering.md | docs/zh-CN/token-metering.md |
| 消息渠道 | docs/en/channels.md | docs/zh-CN/channels.md |
| @ 提及（技能 / 会话 / 文件） | docs/en/mentions.md | docs/zh-CN/mentions.md |
| 桌面版 | docs/en/desktop.md | docs/zh-CN/desktop.md |

📄 许可证

本项目采用 MIT 许可证开源。

🤝 贡献

欢迎提交 Issue 和 Pull Request！