Metadata-Version: 2.4
Name: xuanji
Version: 1.0.2
Summary: 具身智能多Agent框架 — 让AI像人一样使用电脑
License-Expression: MIT
Keywords: agent,ai,embodied,multi-agent,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: dashscope
Requires-Dist: dashscope>=1.0; extra == "dashscope"
Provides-Extra: perception
Requires-Dist: mss>=9.0; extra == "perception"
Requires-Dist: Pillow>=10.0; extra == "perception"
Provides-Extra: hands
Requires-Dist: pyautogui>=0.9; extra == "hands"
Provides-Extra: voice
Requires-Dist: openai-whisper>=20230918; extra == "voice"
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == "browser"
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3; extra == "ocr"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=20.0; extra == "telegram"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3; extra == "discord"
Provides-Extra: sqlite
Provides-Extra: vector
Requires-Dist: chromadb>=0.4; extra == "vector"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: mss>=9.0; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Requires-Dist: pyautogui>=0.9; extra == "all"
Requires-Dist: playwright>=1.40; extra == "all"
Dynamic: license-file

# 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

```bash
pip install xuanji
xuanji init my-project
xuanji run
```

---

## 中文文档

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

<details>
<summary>👆 English summary above — click here for full Chinese documentation</summary>

---

```bash
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底座跨平台 |

## 🚀 快速开始

### 安装

```bash
pip install xuanji
```

### 创建项目

```bash
xuanji init my-bot
cd my-bot
```

### 配置（一行一个API）

```toml
# 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:pass@imap.gmail.com"  # 邮件
```

### 写一个Agent

```python
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"
```

### 运行

```bash
xuanji run
```

## 📖 文档

- [架构设计](docs/ARCHITECTURE.md) — 四大引擎+安全+扩展
- [API配置](docs/API_CONFIG.md) — 一行配一个API
- [扩展机制](docs/EXTENSION.md) — Skill/MCP/Plugin
- [安全设计](docs/SECURITY.md) — 七层防护
- [开发路线](docs/ROADMAP.md) — 开发计划

## 🧪 测试

```bash
# 集成测试（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文件

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

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

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

### Plugin（插件）— 深度扩展

```python
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）数字生命体的核心技术方法论。

---

</details>
