Metadata-Version: 2.4
Name: wecom-ai-bot
Version: 0.1.0
Summary: Enterprise WeChat (WeCom) AI Bot Framework — Python-first, AI-native
Project-URL: Homepage, https://github.com/hi-xXX/wecombot
Project-URL: Documentation, https://github.com/hi-xXX/wecombot/tree/main/docs
Project-URL: Repository, https://github.com/hi-xXX/wecombot
Project-URL: Issues, https://github.com/hi-xXX/wecombot/issues
Project-URL: Sponsor, https://github.com/sponsors/hi-xXX
Author: WeComBot Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chatbot,customer-service,enterprise,wechat,wecom
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: cryptography>=41.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: all
Requires-Dist: redis[hiredis]>=5.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

<h1 align="center">WeComBot</h1>

<p align="center">
  <strong>企业微信 AI 智能客服机器人框架</strong><br>
  Python 原生 · AI 驱动 · 开箱即用
</p>

<p align="center">
  <a href="https://pypi.org/project/wecombot/"><img src="https://img.shields.io/pypi/v/wecombot?color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/wecombot/"><img src="https://img.shields.io/pypi/pyversions/wecombot" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
  <a href="https://github.com/hi-xXX/wecombot/stargazers"><img src="https://img.shields.io/github/stars/hi-xXX/wecombot?style=social" alt="Stars"></a>
</p>

<p align="center">
  <a href="#-快速开始">快速开始</a> ·
  <a href="docs/getting-started.md">Documentation</a> ·
  <a href="examples/">Examples</a> ·
  <a href="#-赞助支持">赞助支持</a>
</p>

---

## 和微信「龙虾」(OpenClaw) 有什么区别？

微信已开放 [ClawBot 插件](https://www.36kr.com/p/3734838062772736)，允许 AI Agent 接入个人微信。但 WeComBot 解决的是**完全不同的场景**：

| | 微信龙虾 (ClawBot) | WeComBot |
|---|---|---|
| **定位** | 个人 AI 助手 | **企业客服 / 商业场景** |
| **接入方式** | 微信个人聊天插件 | **企业微信官方客服 API** |
| **群聊支持** | ❌ 不支持 | ✅ 支持 |
| **多实例** | ❌ 只能连 1 个龙虾 | ✅ 多实例 + Redis 共享 |
| **数据归属** | 腾讯平台 | **自建服务器，数据完全自有** |
| **自定义程度** | 受限于 OpenClaw 生态 | **完全自由**：任意模型、任意逻辑 |
| **客户管理** | ❌ 无 | ✅ 企微客户体系打通 |
| **适合谁** | 个人用户玩 AI | **企业做智能客服、私域运营** |

**简单说：龙虾是给个人玩的，WeComBot 是给企业赚钱用的。**

## 为什么选 WeComBot？

| | 其他方案 | WeComBot |
|---|---|---|
| **企微支持** | 仅 Webhook 推送，或偏重个人微信 | **完整客服 API（kf API）全量封装** |
| **开发语言** | TypeScript 优先（Wechaty） | **Python 原生** — AI/ML 开发者首选 |
| **AI 能力** | 需自行集成 | **内置**：多模型路由、对话记忆、插件系统 |
| **部署难度** | 配置复杂 | **Docker 一键部署** |
| **成本** | SCRM SaaS 年费 ¥10,000+ | **免费开源** |

## 功能对比

| 功能 | 免费版 | <a href="#-赞助支持">赞助版</a> |
|------|:------:|:-------:|
| 企微客服 API 完整封装 | ✅ | ✅ |
| 消息加解密（AES-CBC） | ✅ | ✅ |
| Webhook 回调服务（FastAPI） | ✅ | ✅ |
| 消息去重 | ✅ | ✅ |
| 单模型 LLM 接入 | ✅ | ✅ |
| 本地对话记忆 | ✅ | ✅ |
| 插件系统 | ✅ | ✅ |
| Docker 部署 | ✅ | ✅ |
| **多模型智能路由**（自动降本） | | ✅ |
| **Redis 共享记忆**（多实例） | | ✅ |
| **RAG 知识库**插件 | | ✅ |
| **管理后台**（用量、成本、日志） | | ✅ |
| **预配置 Docker 镜像**（开箱即用） | | ✅ |
| **VIP 技术群 + 优先响应** | | ✅ |

## 🚀 快速开始

### 1. 安装

```bash
pip install wecombot
```

### 2. 配置

```bash
cp config.example.yaml config.yaml
# 填入你的企业微信凭证
```

```yaml
wecom:
  corp_id: "你的企业ID"
  secret: "你的应用Secret"
  kf_account: "你的客服账号"
  token: "你的回调Token"
  encoding_aes_key: "你的EncodingAESKey"

server:
  host: "0.0.0.0"
  port: 8000
```

### 3. 运行

```python
from wecombot import WeComBot

bot = WeComBot("config.yaml")

@bot.on_text
async def handle(bot, msg):
    await bot.reply(msg, f"收到：{msg.content}")

bot.run()
```

**搞定。** 你的企微 AI 客服已上线。

## 10 行代码接入 AI 助手

```python
from wecombot import WeComBot
from wecombot.ai import AIChatHandler
from wecombot.ai.providers import AnthropicProvider
from wecombot.memory import LocalMemory

bot = WeComBot("config.yaml")
provider = AnthropicProvider(api_key="sk-ant-xxx")
memory = LocalMemory("./history")
ai = AIChatHandler(provider=provider, memory=memory,
                   system_prompt="你是一个专业的客服助手。")

@bot.on_text
async def handle(bot, msg):
    reply = await ai.handle(msg.content, msg.external_userid)
    await bot.reply(msg, reply)

bot.run()
```

## 架构设计

```
┌─────────────────────────────────────────────┐
│                  WeComBot                    │
├──────────┬──────────┬───────────┬───────────┤
│  Webhook │  Client  │    AI     │  插件系统  │
│  回调服务 │  API客户端│  AI引擎   │  Plugins  │
├──────────┼──────────┼───────────┼───────────┤
│ FastAPI  │  httpx   │ 多模型路由 │ BasePlugin│
│ AES-CBC  │  自动重试 │ 对话记忆   │ 欢迎消息  │
│ 消息去重  │  Token   │ 智能降级   │ 网页搜索  │
│          │  缓存刷新 │  成本追踪  │ 自定义... │
└──────────┴──────────┴───────────┴───────────┘
        ↕                   ↕
  企微客服 API        Claude / GPT / DeepSeek
                      / 任意 OpenAI 兼容接口
```

## 支持的 AI 模型

| 模型服务 | 流式输出 | 用量追踪 | 接入方式 |
|---------|:-------:|:-------:|---------|
| **Anthropic** (Claude) | ✅ | ✅ | `AnthropicProvider(api_key="sk-ant-xxx")` |
| **OpenAI** (GPT) | ✅ | ✅ | `OpenAIProvider(api_key="sk-xxx")` |
| **DeepSeek** | ✅ | ✅ | `OpenAIProvider(api_key="xxx", base_url="https://api.deepseek.com/v1")` |
| **通义千问** | ✅ | ✅ | `OpenAIProvider(base_url="https://dashscope.aliyuncs.com/compatible-mode/v1")` |
| **本地模型** (Ollama, vLLM) | ✅ | ✅ | `OpenAIProvider(base_url="http://localhost:11434/v1")` |
| **任意 OpenAI 兼容接口** | ✅ | ✅ | `OpenAIProvider(base_url="你的地址")` |

## Docker 部署

```bash
# 快速启动
docker compose -f docker/docker-compose.yml up -d

# 启用 Redis（多实例共享记忆）
docker compose -f docker/docker-compose.yml --profile redis up -d
```

通过 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 暴露到公网：

```bash
cloudflared tunnel --url http://localhost:8000
```

## 插件系统

几分钟创建自定义插件：

```python
from wecombot.plugins import BasePlugin

class WeatherPlugin(BasePlugin):
    name = "weather"
    description = "查询天气"

    async def can_handle(self, message):
        return "天气" in message.content

    async def handle(self, bot, message):
        city = message.content.replace("天气", "").strip()
        # 调用天气 API
        return f"{city}天气：25°C，晴"

# 注册插件
bot.register_plugin(WeatherPlugin())
```

内置插件：`WelcomePlugin`（新用户欢迎）、`WebSearchPlugin`（网页搜索）

## 企微后台配置指引

1. 登录[企业微信管理后台](https://work.weixin.qq.com/)
2. 进入 **客服** → 创建客服账号
3. 记录 `corp_id`、`secret`、`kf_account`
4. 在 **回调配置** 中设置回调 URL，获取 `token` 和 `encoding_aes_key`
5. 填入 `config.yaml`，运行你的 Bot

详细文档：[docs/getting-started.md](docs/getting-started.md)

## 文档

- [Getting Started](docs/getting-started.md) — 企微配置、安装、第一个 Bot
- [AI Integration](docs/ai-integration.md) — LLM 接入、多模型路由、对话记忆
- [Plugin Development](docs/plugins.md) — 插件开发指南
- [Deployment Guide](docs/deployment.md) — Docker 部署、隧道、生产配置

## 开发计划

- [x] 企微客服 API 完整封装
- [x] 消息加解密（AES-CBC）
- [x] Webhook 回调服务 + 消息去重
- [x] 多 LLM Provider 支持（Anthropic、OpenAI、兼容接口）
- [x] 对话记忆（本地 + Redis）
- [x] 多模型智能路由
- [x] 插件系统 + 内置插件
- [x] Docker 部署方案
- [ ] RAG 知识库插件
- [ ] 管理后台（Web UI）
- [ ] 企微应用消息支持
- [x] 群聊支持
- [ ] 语音消息转文字
- [ ] 图片理解（多模态）
- [ ] 限流与配额管理

## 参与贡献

欢迎贡献！请参考 [Contributing Guide](CONTRIBUTING.md)。

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 编写测试
4. 确保所有测试通过 (`pytest`)
5. 提交 PR

所有 PR 在 48 小时内响应。

## 💰 赞助支持

WeComBot 完全免费开源。赞助支持项目持续开发，同时解锁高级功能和专属技术服务。

### 🔥 早鸟特惠（限前 50 名）

<table>
  <tr>
    <td align="center">
      <b>🎫 ¥9.9</b><br>
      <b>早鸟赞助</b><br>
      <sub>限前 50 名</sub><br>
      <sub>VIP 技术群</sub><br>
      <sub>预配置 Docker 镜像</sub><br>
      <sub>部署指导</sub><br>
      <sub>赞助版全部功能</sub><br><br>
      <img src="docs/assets/wechat-pay-9.9.png" width="150" />
    </td>
    <td align="center">
      <b>💎 ¥88</b><br>
      <b>赞助版</b><br>
      <sub>早鸟结束后价格</sub><br>
      <sub>VIP 技术群</sub><br>
      <sub>预配置 Docker 镜像</sub><br>
      <sub>部署指导</sub><br>
      <sub>赞助版全部功能</sub><br><br>
      <img src="docs/assets/wechat-pay-88.png" width="150" />
    </td>
    <td align="center">
      <b>🏢 ¥288</b><br>
      <b>定制版</b><br>
      <sub>赞助版全部权益</sub><br>
      <sub>1 对 1 部署支持</sub><br>
      <sub>定制化需求开发</sub><br>
      <sub>多账号解决方案</sub><br><br>
      <img src="docs/assets/wechat-pay-288.png" width="150" />
    </td>
  </tr>
</table>

> 支付后请添加开发者微信（备注「WeComBot」）获取权益：
>
> <img src="docs/assets/wechat-contact.png" width="150" />

### 权益对比

| 权益 | 免费版 | 早鸟 ¥9.9 / 赞助 ¥88 | 定制版 ¥288 |
|------|:------:|:-------------------:|:----------:|
| 完整框架源码 | ✅ | ✅ | ✅ |
| 基础文档 | ✅ | ✅ | ✅ |
| VIP 技术群 | | ✅ | ✅ |
| 预配置 Docker 镜像 | | ✅ | ✅ |
| 多模型路由 + Redis 记忆 | | ✅ | ✅ |
| 部署指导 | | ✅ | ✅ |
| RAG 知识库插件 | | ✅ | ✅ |
| 管理后台 | | ✅ | ✅ |
| 优先 Issue 响应 | | ✅ | ✅ |
| 1 对 1 部署支持 | | | ✅ |
| 定制化需求开发 | | | ✅ |
| 多账号解决方案 | | | ✅ |

<p align="center">
  <a href="https://github.com/sponsors/hi-xXX">
    <img src="https://img.shields.io/badge/GitHub_Sponsors-❤️-ea4aaa?style=for-the-badge" alt="Sponsor">
  </a>
</p>

## ⚖️ 法律声明

**本项目完全合法合规：**

- 仅使用[企业微信官方开放 API](https://developer.work.weixin.qq.com/)，不涉及任何逆向工程、协议破解或非授权接口
- 不使用任何微信个人号协议（如 Pad/Hook/Web 协议）
- 不包含任何绕过平台安全策略的代码
- 遵守《企业微信用户账号使用规范》和《微信外部链接内容管理规范》

> ⚠️ 使用微信非官方协议（如 WeChatPadPro、itchat 等）存在法律风险，包括但不限于账号封禁、民事赔偿（[已有判赔 500 万案例](https://www.055110.com/xs/4/16355.html)）甚至刑事责任。**本项目与此类方案无关。**

## License

[MIT](LICENSE) — 随便用。

---

<p align="center">
  为企微开发者社区而建<br>
  <sub>觉得有用？给个 ⭐ 或 <a href="#-赞助支持">赞助支持</a></sub>
</p>
