README

WePush 
 专注批量推送的小而美的工具  








 产品线与版本选择

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

| 产品线 | 当前定位 | 适合场景 | 入口 |
| --- | --- | --- | --- |
| WePush Classic | 稳定桌面客户端 | 微信、短信、邮件、HTTP 等成熟批量推送场景 | Classic 下载 |
| WePush Next | 1.2.0 Stable | 三平台离线自部署、1.x 兼容承诺、Service/Agent、资源治理、AI 助手接入、可恢复运维、WebUI/Desktop 与可扩展 Provider | Next 1.2.0 下载 |

当前源码的 Classic 与 Next 均要求 JDK 25+ 构建；不含运行时的发行包及 Java SDK 要求 Java 25+。完整安装包内置 Java 25 运行时。

 AI 助手接入：Codex、MCP 与 Skill

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

此功能随 Classic 当前发行版和 Next 1.2.0 提供。更早的 Next 1.1.0 及不含该入口的旧 Classic 安装包需要升级后再使用。

| 版本 | 接入入口 | 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 接入指南 和 Next 接入指南。

 WePush Next Stable

Next 是位于 next/ 的完整新架构产品线，包含 Core Engine、Provider SPI、可安装 Service、远程 Agent、Remote/Embedded Java SDK、React WebUI 和 Electron Desktop。1.2.0 是兼容 1.1.0 的稳定 Minor 发行版，在既有 1.x 兼容承诺之上提供 Codex MCP/Skill 接入，并把 Java 运行基线升级到 25。

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

 1.2.0 重点更新

- Desktop 一键安装 Codex MCP 与 Skill；WebUI 和发行包提供 wepush-ai.mjs。正式发送仍使用预览确认、幂等键和 Workspace 权限。
- Java 运行基线升级到 25。完整包携带 Java 25 运行时；精简包和 Java SDK 需要系统 Java 25+。
- 不新增数据库迁移。运营商插件、Workspace 资源治理、脱敏诊断、跨 Run 熔断、PostgreSQL 通知、Multipart Artifact 和 WebUI 主题继续可用。

 Next 组件

| 组件 | 主要职责 | 形态与边界 |
| --- | --- | --- |
| Core / Engine | 执行批量任务，管理并发、重试、暂停、恢复、取消、结果与运行事件 | 纯 Java 无界面执行内核，不直接提供网络 API，也不依赖 Service、UI 或具体 Provider |
| Provider SPI / Provider | 定义消息渠道扩展契约，负责账号校验、消息渲染和实际发送 | Core 只面向 SPI；内置 HTTP 和 8 个标准渠道，另有 CMPP/SMGP/SGIP/SMPP 独立签名插件 |
| Service | 提供配置、调度、运行控制、Secret、Artifact、审计、REST/SSE、OpenAPI 和 Agent 控制面 | 可前台运行或安装为 Linux systemd、macOS launchd、Windows Service；本机模式可内嵌 Core Engine |
| Agent | 在独立主机接收 Lease，使用 Core Engine 执行任务并回传事件、结果和 Artifact | 可独立安装，通过 gRPC 主动连接 Service；本机内嵌执行时不需要 Agent |
| Remote Java SDK | 让 Java 应用通过强类型客户端调用远程 Service API | 已实现；只依赖公开的 service-api 契约，不依赖 Core、Engine 或具体 Pro