xuanji 1.0.1

具身智能多Agent框架 — 让AI像人一样使用电脑

XuanJi (玄机)

Embodied AI Multi-Agent Framework — An open-source AI agent that actually uses your computer.

See screen · Control mouse/keyboard · Talk across 30+ platforms · 19 LLM models · Zero mandatory dependencies

---

XuanJi is a fully embodied AI agent framework. Unlike LLMs that only chat, XuanJi can see your screen, control the mouse and keyboard, browse the web, and communicate across 30+ platforms (WeChat, QQ, Telegram, Discord, email, and more). It coordinates multiple AI agents with process isolation and resource arbitration, so they work in parallel without conflicts.

Key highlights:

• 🖥️ Embodied AI — Screen capture, OCR, mouse/keyboard control, browser automation, voice STT/TTS
• 🤖 Multi-Agent — Process-isolated agents with resource arbitration, parallel execution
• 💬 30+ Channels — WeChat, QQ, DingTalk, Feishu, Telegram, Discord, Email, Slack, and more
• 🧠 31+ LLM Models — DeepSeek, Qwen, GLM, GPT, Claude, Gemini, Ollama local models
• 💾 Persistent Memory — 3-level cache + WAL anti-loss + context management
• 🔒 7-Layer Security — Sandbox, operation grading, input sanitization, audit, secret management
• 📦 Extensible — Skill (markdown), MCP protocol, Plugin (Python) — three extension mechanisms
• 🌍 Cross-Platform — Windows / Linux / macOS / ARM, C core for cross-platform performance
• 🚀 Zero Dependencies — Core runs with no external packages; optional backends installed on demand

pip install xuanji
xuanji init my-project
xuanji run

---

中文文档

玄机 (XuanJi) — 具身智能多Agent框架，让AI像人一样使用电脑、与世界交流。

👆 English summary above — click here for full Chinese documentation

---

pip install xuanji
xuanji init my-project
xuanji run

🌟 核心特性

能力	说明
🖥️ 具身智能	截屏/鼠标/键盘/浏览器/语音，像人一样操作电脑
🤖 多Agent协作	进程隔离+资源仲裁，多Agent并行不冲突
💬 全平台通信	微信/QQ/钉钉/飞书/Telegram/Discord/邮件...30+平台
🧠 全模型接入	DeepSeek/通义/智谱/GPT/Claude/Gemini/本地...31+模型
💾 记忆永不丢	三级缓存+WAL防丢失+上下文管理
🔒 安全内置	七层防护+沙盒+RBAC+审计+密钥管理
📦 可扩展	Skill/MCP/Plugin三种扩展机制
🌍 全平台	Windows/Linux/macOS/ARM，C底座跨平台

🚀 快速开始

安装

pip install xuanji

创建项目

xuanji init my-bot
cd my-bot

配置（一行一个API）

# config.toml
[llm]
deepseek = "sk-xxx"        # DeepSeek
dashscope = "sk-xxx"       # 通义千问
zhipu = "sk-xxx"           # 智谱GLM
ollama = "localhost"       # 本地模型

[channels]
telegram = "bot_token"     # Telegram
qq = "app_id:secret"       # QQ
email = "user:[e-mail]"  # 邮件

写一个Agent

from xuanji import AgentPlugin

class MyBot(AgentPlugin):
    name = "我的助手"
    
    async def on_message(self, msg, ctx):
        reply = await ctx.llm.chat([
            {"role": "user", "content": msg.content}
        ])
        await ctx.channels.reply(msg, reply)
    
    async def on_task(self, task, ctx):
        # 操作电脑
        await ctx.hands.open_app("Chrome")
        await ctx.hands.type_text("https://github.com")
        screen = ctx.perception.screenshot()
        return "done"

运行

xuanji run

📖 文档

• 架构设计 — 四大引擎+安全+扩展
• API配置 — 一行配一个API
• 扩展机制 — Skill/MCP/Plugin
• 安全设计 — 七层防护
• 开发路线 — 开发计划

🧪 测试

# 集成测试（51项）
python tests/test_full.py

# 端到端测试（Ollama本地）
python tests/test_full_ollama.py

# 真实任务测试
python tests/test_real_task.py        # TODO应用开发
python tests/test_hard_task.py        # PyPI分析器
python tests/test_movie_analysis.py   # 电影行业分析
python tests/test_stock_dashboard.py  # 股票分析仪表盘

🆚 为什么选玄机？

能力	玄机 XuanJi	AutoGPT	CrewAI	LangChain
操控电脑（截屏/鼠标/键盘）	✅	❌	❌	❌
全平台通信（微信/QQ/钉钉/Telegram/Discord）	✅	❌	❌	❌
多Agent协作+资源仲裁	✅	⚠️	✅	❌
30+ LLM适配器	✅	⚠️	⚠️	✅
七层安全防护	✅	❌	❌	❌
零强制依赖	✅	❌	❌	❌
全平台（Win/Linux/macOS）	✅	⚠️	✅	✅
进化系统（失败学习/模式复用）	✅	❌	❌	❌
pip install 直接运行	✅	⚠️	✅	✅

📊 项目统计

指标	数值
Python文件	169
代码行数	~55,000
通讯渠道	29个
LLM适配器	19个
Agent工具	24个
安全模块	12个
测试通过	17/17架构审查 + 5/5全量审计
外部依赖	零强制依赖

🏗️ 架构

┌─────────────────────────────────────────────┐
│            插件层（用户写的）                  │
│  Skill / MCP / Agent插件 / Tool插件          │
├─────────────────────────────────────────────┤
│          安全系统（七层防护）                  │
│  沙箱 / 操作分级 / 输入消毒 / 审计 / 密钥     │
├─────────────────────────────────────────────┤
│          四大内置引擎                         │
│                                              │
│  多Agent引擎        具身引擎                  │
│  ├ 消息总线        ├ 感知(截屏/OCR)           │
│  ├ 资源仲裁        ├ 操控(鼠标/键盘)          │
│  ├ 进程隔离        ├ 语音(STT/TTS)            │
│  └ 运行时          └ 具身协调                 │
│                                              │
│  通信引擎            智能引擎                  │
│  ├ 28个渠道        ├ LLM适配(31+模型)         │
│  ├ 智能路由        ├ 记忆(三级缓存)            │
│  └ 消息统一        └ Token治理                │
├─────────────────────────────────────────────┤
│          C底座 (跨平台)                       │
│  消息总线 / 调度器 / 资源管理 / 进程隔离       │
│  Windows / Linux / macOS / ARM               │
└─────────────────────────────────────────────┘

📝 真实任务示例

股票分析仪表盘（60秒完成）

任务: "帮我做一个股票市场分析"
→ 玄机自动: 组队(架构师+开发+分析师) → 请求Yahoo Finance API
→ 计算MA/RSI/MACD → LLM分析 → 生成可视化代码 → 写报告 → 沉淀经验
→ 产出: stock_data.json + dashboard.py + stock_report.md

电影行业调查（38秒完成）

任务: "调查2024-2026电影趋势"
→ 玄机自动: 检索历史记忆 → 团队分工 → 数据收集
→ LLM深度分析(趋势+投资) → 生成完整报告 → 经验沉淀
→ 产出: movie_data.json + movie_report.md

🔌 扩展机制

Skill（技能）— 一个markdown文件

# SKILL.md — 翻译技能
## 触发条件: 用户要求翻译
## 执行步骤: 1.识别源语言 2.确认目标语言 3.调用LLM翻译

MCP（工具协议）— 标准协议接入

[mcp]
filesystem = "npx -y @modelcontextprotocol/server-filesystem /home"
github = "npx -y @modelcontextprotocol/server-github"

Plugin（插件）— 深度扩展

from xuanji import ToolPlugin

class StockTool(ToolPlugin):
    name = "stock_price"
    async def execute(self, params, ctx):
        return await self.fetch_price(params["symbol"])

🎬 演示

任务: "截个屏，告诉我现在屏幕上有什么"
→ 玄机: 截屏 → LLM分析画面 → 描述屏幕内容 → 回复

任务: "帮我搜索XXX并总结结果"
→ 玄机: 打开浏览器 → 输入搜索 → 读取结果 → 提取信息 → 生成摘要

📜 许可证

MIT License

🙏 致谢

本项目吸收了OpenClaw、Claw Code、deer-flow等项目的工程精华， 并融入了灵明（LingMing）数字生命体的核心技术方法论。

---