WePush

README

<a href="https://gitee.com/zhoubochina/WePush">
 <img alt="WePush-Logo" src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/819b8a1fb5eed4247afa0f44.png">
</a>
  
# WePush 
> 专注批量推送的小而美的工具  

[![star](https://gitee.com/zhoubochina/WePush/badge/star.svg?theme=gvp)](https://gitee.com/zhoubochina/WePush/stargazers)
[![GitHub stars](https://img.shields.io/github/stars/rememberber/WePush.svg)](https://github.com/rememberber/WePush)
[![GitHub release](https://img.shields.io/github/release/rememberber/WePush.svg)](https://github.com/rememberber/WePush/releases)
[![GitHub license](https://img.shields.io/github/license/rememberber/WePush.svg)](https://github.com/rememberber/WePush/blob/master/LICENSE.txt)

<a href="https://hellogithub.com/repository/dd22b383e37a4dedb7d2774363796c74" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=dd22b383e37a4dedb7d2774363796c74&claim_uid=0UhXFJvP9ndHtiB" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>

## 产品线与版本选择

WePush 采用 Classic 与 Next 双轨发展。两条产品线彼此独立，允许按各自需要演进和拥有重复代码；Next 不会影响 Classic 的安装与使用。

| 产品线 | 当前定位 | 适合场景 | 入口 |
| --- | --- | --- | --- |
| WePush Classic | 稳定桌面客户端 | 微信、短信、邮件、HTTP 等成熟批量推送场景 | [Classic 下载](https://gitee.com/zhoubochina/WePush/releases) |
| WePush Next | `1.1.0` Stable | 三平台离线自部署、1.x 兼容承诺、Service/Agent、资源治理、可恢复运维、WebUI/Desktop 与可扩展 Provider | [Next 1.1.0 下载](https://github.com/rememberber/WePush/releases/tag/next-v1.1.0) |

### AI 助手接入：Codex、MCP 与 Skill

Classic 和 Next 均支持让 Codex 等 AI 助手使用 WePush。可一键安装 Codex MCP + Skill、仅安装 Skill，或生成通用 stdio MCP 配置给其他兼容客户端。两版独立实现，安装名称不同，可以同时使用。

此功能已在当前源码实现；Classic 旧安装包及已发布的 `next-v1.1.0` 附件尚不包含相应入口，请使用包含此功能的新构建。

| 版本 | 接入入口 | MCP / Skill 名称 | 主要能力 |
| --- | --- | --- | --- |
| Classic | **应用 → AI 助手接入** | `wepush-classic` | 查询已有任务、查看发送预览、空跑、授权发送、查询进度与历史 |
| Next | **设置 → AI 助手接入** | `wepush` | 发现渠道与 Schema、查询资源、创建消息/受众/任务、空跑、授权发送、查询结果与控制运行 |

**快速开始：**

1. 在 WePush 中配置渠道账号。Classic 还需保存消息、人群和任务；Next 需启动 Service 并核对 Service URL 与 Workspace。
2. 在 Classic 或 Next Desktop 的接入页面点击 **一键接入 Codex**，再重新连接 Codex MCP，必要时重启 Codex。两版桌面安装均使用各自自带的运行时，无需额外安装 Node.js 或 Java。
3. 让助手先查询并空跑任务，例如：“用 WePush Classic 列出任务，空跑任务 1，并告诉我结果。”正式发送前核对预览中的消息与人群，按用户授权执行，再查询实际运行结果。

使用 Next WebUI 时，在接入页面下载安装器并执行页面生成的命令，需要 Node.js 24+。仅使用 Skill 可点击 **仅安装 Skill**；其他支持 stdio MCP 的客户端可使用 Classic 的 **复制通用 MCP 配置** 或 Next Desktop 的 **导出通用 MCP 配置**。

- **Classic 执行范围：**已保存的手动固定线程任务，线程数 1～100，关闭任务的结果邮件提醒；使用期间保持 Classic 运行。账号、消息、人群及任务的编辑仍在 Classic 界面完成。
- **Next 运行要求：**保持 Service 可达；启用认证后，在 AI 客户端环境中设置 `WEPUSH_API_TOKEN`。安装器不复制登录 Token，调用遵循已有 Workspace 权限。
- **发送防重：**正式发送使用预览确认令牌和请求编号；超时后查询原运行，重试时复用原请求编号与参数，结果不明时不自动重发。

安装目录、客户端配置、完整工具列表及排错说明见 [Classic 接入指南](https://gitee.com/zhoubochina/WePush/blob/master/docs/classic-ai-integration.md) 和 [Next 接入指南](https://gitee.com/zhoubochina/WePush/blob/master/next/docs/ai-integration.md)。

### WePush Next Stable

Next 是位于 [`next/`](https://gitee.com/zhoubochina/WePush/blob/master/next) 的完整新架构产品线，包含 Core Engine、Provider SPI、可安装 Service、远程 Agent、Remote/Embedded Java SDK、React WebUI 和 Electron Desktop。`1.1.0` 是兼容 `1.0.0` 的稳定 Minor 发行版，在 1.x API、配置、数据库和 Agent 协议兼容承诺之上，补齐运营商短信插件、Workspace 资源治理、自建运维、跨 Run 可靠性、大 Artifact 与 WebUI 可用性。

Next 的长期定位是由用户自行下载、安装、部署和运维的开源产品。项目不建设承载用户业务数据的官方公共 SaaS，不提供注册、计费、订阅或公共租户平台，也不规划云 KMS/Secret Manager 集成。用户可以在自己的环境中运行 Standalone，或自行搭建 Server/HA 和远程 Agent。

#### `1.1.0` 重点更新

- CMPP、SMGP、SGIP、SMPP 作为四个源码独立、Ed25519 签名的 Agent Provider 插件交付。
- Workspace 可限制 Agent 数、活动 Run、总发送并发、Artifact 容量和默认保留期；相同账号的认证失败可跨 Run 熔断。
- 提供结构化脱敏诊断包、Nginx/Traefik/Kubernetes 自建模板和仅由用户手动触发的版本检查。
- PostgreSQL `LISTEN/NOTIFY` 加速 Run、Agent Outbox 与 SSE 唤醒；数据库轮询、持久 Outbox 和事件游标继续保证正确性。
- Agent Artifact 支持 Presigned Multipart，单文件上限扩展到 5 TiB；WebUI 增加暗色/跟随系统主题并改善低分辨率与可访问性。

#### Next 组件

| 组件 | 主要职责 | 形态与边界 |
| --- | --- | --- |
| [Core / Engine](https://gitee.com/zhoubochina/WePush/blob/master/next/core) | 执行批量任务，管理并发、重试、暂停、恢复、取消、结果与运行事件 | 纯 Java 无界面执行内核，不直接提供网络 API，也不依赖 Service、UI 或具体 Provider |
| [Provider SPI / Provider](https://gitee.com/zhoubochina/WePush/blob/master/next/providers) | 定义消息渠道扩展契约，负责账号校验、消息渲染和实际发送 | Core 只面向 SPI；内置 HTTP 和 8 个标准渠道，另有 [CMPP/SMGP/SGIP/SMPP 独立签名插件](https://gitee.com/zhoubochina/WePush/blob/master/next/plugins) |
| [Service](https://gitee.com/zhoubochina/WePush/blob/master/next/service) | 提供配置、调度、运行控制、Secret、Artifact、审计、REST/SSE、OpenAPI 和 Agent 控制面 | 可前台运行或安装为 Linux systemd、macOS launchd、Windows Service；本机模式可内嵌 Core Engine |
| [Agent](https://gitee.com/zhoubochina/WePush/blob/master/next/agent) | 在独立主机接收 Lease，使用 Core Engine 执行任务并回传事件、结果和 Artifact | 可独立安装，通过 gRPC 主动连接 Service；本机内嵌执行时不需要 Agent |
| [Remote Java SDK](https://gitee.com/zhoubochina/WePush/blob/master/next/sdk/sdk-java) | 让 Java 应用通过强类型客户端调用远程 Service API | 已实现；只依赖公开的 `service-api` 契约，不依赖 Core、Engine 或具体 Provider |
| [Embedded Java SDK](https://gitee.com/zhoubochina/WePush/blob/master/next/sdk/embedded-java) | 让 Java 应用在自己的进程内直接装配 Core Engine 和选定 Provider，无需启动 Service | `1.1.0` Java SDK 附件包含 HTTP 与标准渠道 Provider；业务应用仍须显式选择 |
| [WebUI](https://gitee.com/zhoubochina/WePush/blob/master/next/ui/apps/web) | 提供可视化配置、任务与调度、运行中心、Agent 观察和动态调试 API 文档 | TypeScript + Vite + React，可由 Service 直接托管，也可在开发环境独立运行 |
| [Desktop UI](https://gitee.com/zhoubochina/WePush/blob/master/next/ui/apps/desktop) | 提供与 WebUI 一致的桌面管理体验和安全 Electron 外壳 | 连接并管理已安装的本机 Service，使用系统安全存储保存 Token；不把 Service 内嵌进 UI |

当前典型调用关系为：`WebUI / Desktop UI / Remote Java SDK → Service API → Service → 内嵌 Core Engine`；远程执行时则由 `Service → Agent → Core Engine → Provider` 完成发送。进程内集成使用 `业务 Java 应用 → Embedded Java SDK → Core Engine → Provider`，不经过 Service。

第一次使用请从[《WePush Next 对外使用指南》](https://gitee.com/zhoubochina/WePush/blob/master/next/docs/user-guide.md)开始。macOS/Windows 发行物按项目约定不使用商业代码签名，请只从 [`next-v1.1.0` GitHub Release](https://github.com/rememberber/WePush/releases/tag/next-v1.1.0) 下载，并使用同一 Release 中的 [`SHA256SUMS`](https://github.com/rememberber/WePush/releases/download/next-v1.1.0