Skip to content

Latest commit

 

History

History
84 lines (54 loc) · 6.86 KB

classic-ai-integration.md

File metadata and controls

84 lines (54 loc) · 6.86 KB

Classic 的 MCP 与 Skill 接入

此功能随包含本次改动的 Classic 安装包提供;已发布的旧安装包不会自动获得该入口。Classic 的实现独立于 Next,不需要启动 Next Service,也不依赖 Next 的源码、Node.js 或构建产物。

一键接入

  1. 启动 Classic,先在界面中配置账号、消息、人群和任务。
  2. 打开 应用 → AI 助手接入。
  3. 点击 一键接入 Codex,安装器会写入 Codex MCP 配置和 wepush-classic Skill,同时开启本机桥接。重新启动 Codex 或新建会话加载接入。
  4. 对助手说:“用 WePush Classic 查看任务,空跑任务 1,告诉我校验结果。”

使用期间保持 Classic 运行。桥接默认关闭,首次开启后会在下次启动 Classic 时自动恢复。关闭本机接入会停止接受新调用,已启动的任务继续执行;退出 Classic 会中断本机任务。

安装名称均为 wepush-classic,与 Next 的 wepush 可以共存:

内容 位置
Codex MCP $CODEX_HOME/config.toml,未设置时为 ~/.codex/config.toml,表名 [mcp_servers.wepush-classic]
Skill ~/.agents/skills/wepush-classic/SKILL.md
Skill 启动脚本 Skill 目录中的 scripts/wepush-classic.sh / scripts/wepush-classic.ps1
通用 MCP JSON 安装后的 Skill 目录中的 mcp.json
本机连接与防重记录 ~/.WePush5/ai/

安装器保留其他 MCP、模型和 Profile 配置,并在修改已有 Codex 配置前生成 config.toml.wepush-classic-<UUID>.bak。遇到同名的手动 MCP 或非本安装器创建的 Skill 时停止,避免覆盖。重复安装会更新自己管理的文件;自定义 Skill 请使用另一个目录名称。

启动配置引用当前 Classic 的 Java 运行时和应用目录,发行版无需另装 Java。移动应用、切换开发目录或升级导致路径变化后,请在新位置再执行一次安装。

其他助手与 Skill 单独使用

支持 stdio MCP 的客户端:点击 复制通用 MCP 配置,把 JSON 中 mcpServers.wepush-classic 合并到客户端配置中,再重新连接。客户端可能有自己的配置格式,保留生成的 command 和 args。

仅使用 Skill:点击 仅安装 Skill。Codex 会从用户 Skill 目录发现它;其他支持 Skill 的助手可加载或复制整个目录。脚本使用与 MCP 相同的工具和本机桥接。使用 tools 查询参数,call <工具名> 从标准输入读取一个 UTF-8 JSON 对象:

sh ~/.agents/skills/wepush-classic/scripts/wepush-classic.sh tools
printf '%s' '{"taskId":1}' | sh ~/.agents/skills/wepush-classic/scripts/wepush-classic.sh call wepush_classic_get_task

Windows 示例:

'{"taskId":1}' | powershell -NoProfile -ExecutionPolicy Bypass -File "$HOME/.agents/skills/wepush-classic/scripts/wepush-classic.ps1" call wepush_classic_get_task

工具与执行范围

工具 能力
wepush_classic_system_info 检查连接与能力
wepush_classic_list_tasks 分页查询已保存的任务
wepush_classic_get_task 查看消息模板、账号名称、人群名称及数量
wepush_classic_prepare_run 返回发送预览与有效期 10 分钟的确认令牌,不投递消息
wepush_classic_dry_run 使用 Classic 原有渠道逻辑空跑校验
wepush_classic_send_run 执行已授权的正式发送
wepush_classic_get_run 按 runId 查询进度与结果
wepush_classic_list_history 分页查询指定任务的 Classic 历史

分页参数为 offset(默认 0)和 limit(默认 30,最大 100)。工具只操作已有资源,账号、消息、人群和任务的创建及编辑仍在 Classic 界面中完成。

当前执行范围为已保存的手动固定线程任务:线程数 1~100,已关闭任务的结果邮件提醒,每个 Classic 实例最多同时执行 4 个由 AI 启动的任务。计划、触发、变速任务和结果邮件提醒仍由 Classic 原有界面执行。各渠道的成功语义、限流和空跑行为沿用现有发送器;空跑不证明真实渠道认证或投递一定成功。

正式发送前,助手必须核对 prepare_run 的预览,确保已有用户授权覆盖内容、人群及发送时机,再传入 taskId、confirmationToken、新的标准小写 UUID idempotencyKey 和 userConfirmed: true。任务、消息、账号或人群在预览后变化时,旧预览失效。接入在同一个数据库锁内核对资源并准备发送器,接受运行后保留该次任务和人群快照。

本次 AI 接入的“发送预览”是只读操作。Classic 原有消息编辑界面中的“预览发送”仍按原行为向预览目标实际发送。

防重与结果

runId 与调用者提供的 idempotencyKey 相同。请求在启动发送前持久化,重复使用相同请求编号和相同参数会返回原运行记录。确认令牌只允许启动一次正式发送,但已接受请求的原样重试不受令牌过期影响。

超时或响应丢失时先查询原 runId,必要时原样重试;不要换 UUID 重发。Classic 进程退出或执行异常后可能返回 UNKNOWN,必须先核对 Classic 历史和渠道结果,不会自动恢复投递。防重记录长期保留在 ai/requests;删除这些记录会失去对应请求的防重保护。

FINISHED 只表示执行结束,应继续核对 totalCount、successCount 和 failCount。它不保证所有目标发送成功,也不等同于终端已送达。

本机边界

桥接只监听 127.0.0.1 随机端口,每次开启生成新的令牌;拒绝带 Origin 的浏览器请求。连接文件在支持 POSIX 权限的系统上仅当前用户可读写。MCP 和 Skill 配置只保存连接文件路径,不包含令牌或渠道凭据。不要共享 ~/.WePush5/ai/connection.json;同一系统用户下的可信本机客户端可以通过此文件调用桥接。

工具不返回账号配置、原始日志、完整人群记录或结果文件。消息模板里的常见凭据字段(如 Header、Cookie、Token)会隐藏;自定义正文中的敏感文本仍属于消息内容,应按实际使用范围处理。

开发验证

使用 Java 25+ 和 Maven 执行 mvn test。新增测试覆盖 TOML 保留与冲突、重复安装、脚本路径转义、MCP 协议、鉴权与令牌轮换、配置变化、确认过期、持久防重及并发重试。真实链路测试在隔离子进程中使用临时数据库与本机 HTTP 接收器,断言空跑零投递、正式发送使用已接受的消息快照、重复请求不增加投递。

配置依据:Codex MCP、Codex Skills、MCP 生命周期及工具协议。