Metadata-Version: 2.4
Name: xuanji
Version: 1.0.0
Summary: 具身智能多Agent框架 — 让AI像人一样使用电脑
License: MIT
Keywords: agent,ai,embodied,multi-agent,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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** — AI that uses computers like humans do.
> 
> *Embodied intelligence · Multi-agent collaboration · 30+ channels · 31+ 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  # 股票分析仪表盘
```

## 📊 项目统计

| 指标 | 数值 |
|------|------|
| 文件数 | 162 |
| 代码行数 | 50,996 |
| 通讯渠道 | 28个（国内10+国外14+通用4） |
| LLM适配器 | 27个（国内13+国外11+本地3） |
| 测试覆盖 | 51+集成 + 9+端到端 + 4个真实任务 |
| 外部依赖 | 零强制依赖 |

## 🏗️ 架构

```
┌─────────────────────────────────────────────┐
│            插件层（用户写的）                  │
│  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"])
```

## 📜 许可证

MIT License

## 🙏 致谢

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

---

</details>
