Skip to content

YellowDi/AlertBridge

BranchesTags

Repository files navigation

AlertBridge

一个本地运行在 macOS 上的桌面工具，用来读取网页报警列表，整理成消息，并通过企业微信自动发送。

当前版本是 SwiftUI macOS 壳层 + 内置 Python 子进程服务。构建后的 .app 会把 Python worker 和依赖一起放进 App bundle，支持打包成 .dmg 给内部用户分发。

1. 这个工具现在能做什么

  • 持续轮询目标网页，按单条串行方式处理报警
  • 从页面表格读取报警字段，按报警类型白名单过滤，并结合项目内规则表与详情浮窗字段生成企业微信消息
  • 自动切换到企业微信，搜索群聊并发送消息
  • 可选地在发送前后回到网页处理同一条报警
  • 把真正完成闭环的报警写入归档
  • 把失败条目标记为 需人工介入，避免后续轮询反复撞同一条

当前自动流程的固定顺序是：

抓取 1 条 -> 按报警类型白名单过滤 -> 按规则表匹配报警规则 -> 打开详情读取报警信息并拼文案 -> 正式执行时先确认处理 -> 发送企业微信 -> 正式执行时再关闭同条 -> 满足条件时归档

2. 运行前准备

环境要求

  1. macOS
  2. 已安装 Google Chrome
  3. 已安装企业微信

内部分发安装

推荐分发文件是：

dist/AlertBridge.dmg

用户双击打开 DMG 后，把 AlertBridge.app 拖到 Applications 即可。

如果 macOS 第一次打开时提示无法验证开发者，右键 AlertBridge.app 选择 打开，再按系统提示确认。

开发机器初始化

如果这台机器需要改代码或重新打包，先在项目目录执行：

  1. 打开终端，进入项目目录
  2. 执行：
chmod +x ./scripts/setup_mac.sh
./scripts/setup_mac.sh

这个脚本会自动处理下面这些事：

  • 检查 macOS 开发工具是否可用
  • 检查 Homebrew 是否已安装
  • 检查 python3 是否已安装，不存在时自动安装
  • 创建项目内 .venv
  • 安装 requirements.txt 里的依赖
  • 构建当前机器可用的 AlertBridge.app

如果脚本提示缺少 Homebrew 或 Xcode Command Line Tools，按它打印的命令先安装，再重新执行一次同一个脚本即可。

开启 Chrome 远程调试

程序通过 Chrome DevTools 远程调试接口读取页面，默认连接地址是：

http://127.0.0.1:9222

使用前先完整退出 Chrome，然后执行：

open -na "Google Chrome" --args --remote-debugging-port=9222

如果你更习惯直接执行 Chrome 二进制，也可以用：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222

启动后，在浏览器里打开下面地址，如果能看到 JSON 响应，就说明远程调试已经开启：

http://127.0.0.1:9222/json/version

也可以打开下面这个页面查看 Chrome 是否已经暴露远程调试目标：

chrome://inspect/#remote-debugging

注意：

  • 如果 Chrome 之前没有完全退出，新的远程调试参数可能不会生效
  • 如果你把调试端口改成了别的值，需要在应用的 Chrome 调试地址 里同步修改
  • 如果目标页面需要登录，请在这个已开启远程调试的 Chrome 窗口里先完成登录

必开权限

企业微信自动输入和窗口切换依赖 macOS 辅助功能权限。

打开路径：

系统设置 -> 隐私与安全性 -> 辅助功能

把 AlertBridge.app 加入允许列表。

如果这个权限没开，企业微信自动化大概率不能正常工作。

3. 启动应用

也可以直接在 Finder 里双击：

仓库根目录下的 AlertBridge.app

如果是第一次打开，macOS 可能会要求你右键应用后选择“打开”。

4. 界面怎么用

当前不是旧版的“左边表单 + 右边日志”布局，而是单窗口主视图配三个底部抽屉。

主界面

窗口顶部中间有两个页签：

  • 抓取
  • 归档

默认进入 抓取 页。

第一次打开且还没有抓取记录时，中间会看到空状态卡片：

  • 配置：打开配置抽屉
  • 开始：启动自动监控

启动过一次后，右上角会常驻 开始 / 停止 按钮，用来控制自动监控。

抓取页

抓取 页按状态分组展示当前记录：

  • 需人工介入
  • 已抓取
  • 已发送

每条记录会尽量按结构化字段显示，优先展示：

  • 车牌号
  • 所属企业
  • 报警规则

项目根目录固定有一份规则表：

./alarm_rule_mapping.csv

程序会按里面的 报警规则 匹配发送文案、通知人、处理模版和处理方式。

项目根目录还有一份企业共享群路由表：

./enterprise_group_mapping.csv

表头为：

企业名称,目标群聊

当目标群模式选择 企业名称 时，程序会先用报警里的 所属企业 精确匹配这张表。命中后发送到 目标群聊；未命中时仍按原逻辑发送到同名企业群。

如果某条记录进入 需人工介入，会显示失败阶段和原因，并带一个 标记已处理 按钮。

点 标记已处理 后：

  • 这条人工介入记录会从列表里移除
  • 这条报警的冻结状态会解除
  • 后续轮询如果再次读到它，会重新按正常流程处理

归档页

归档 页按日期分组展示历史归档。

只有同时满足下面两个条件，报警才会进入这里：

  1. 已开启 读取后自动处理告警条目
  2. 执行模式是 正式执行

也就是只有真正完成网页里的 确认处理 和 关闭 后，才会写入归档。

右上角三个按钮

右上角从左到右是：

  • 配置
  • 调试
  • 日志

三个按钮互斥，同一时间只会展开一个底部抽屉。

5. 配置抽屉

点右上角 配置 按钮后，会展开配置抽屉。

这里包含当前版本真正生效的配置项：

  • 抓取页面地址
  • 抓取字段
  • 报警类型白名单
  • 目标群名称
  • 读取后自动处理告警条目
  • 执行模式
  • 通知人
  • 处理方式

点右上角 保存 才会把当前修改同步给后端服务。

每个配置项是什么意思

抓取页面地址

应用会带一个内置默认地址，但文档里不展示具体值。

程序会优先确保 Chrome 已连接并打开这里填写的目标页面。实际使用时，请改成你自己的业务页面地址。

抓取字段

默认值：

车牌号, 所属企业, 报警规则

这是读取表格时优先抽取和展示的字段名。字段名最好和页面表头基本一致。

发送企业微信时，真正参与拼文案的占位符值会从“查看详情”浮窗左侧报警信息里读取，不直接依赖这里的展示字段。

报警类型白名单

默认值：

疲劳驾驶报警, 超速报警, 离线报警, 离线位移

只有 报警类型 命中这里配置的条目才会进入后续发送和处理流程，其他报警会被直接忽略。

目标群名称

这里其实是一个目标群匹配模式，不是手输群名输入框。当前有两个选项：

  • 测试
  • 企业名称

含义如下：

  • 测试：固定发送到企业微信群 测试
  • 企业名称：先按报警里的 所属企业 精确匹配 enterprise_group_mapping.csv，命中则发送到表内目标群；未命中则搜索同名企业微信群

读取后自动处理告警条目

  • 是：会继续处理刚才那一条报警。正式执行时顺序是先打开详情并确认处理，再发送企业微信，发送成功后回网页点击关闭
  • 否：只发送企业微信，不回网页处理

执行模式

  • 安全演练：会打开详情并读取报警信息来生成消息，但会跳过 确认处理 的识别与点击，也不会点击 关闭
  • 正式执行：会真正点击 确认处理 和 关闭，并且只有两步都完成后才会归档

通知人

发送后如果继续处理网页告警，会把这里的内容填进对应表单。

默认值：

安全负责人

如果 alarm_rule_mapping.csv 里命中了对应报警规则，这里的默认值会被规则表中的 通知人 覆盖。

处理方式

发送后如果继续处理网页告警，会把这里的内容填进对应表单。

默认值：

微信/企业微信

如果 alarm_rule_mapping.csv 里命中了对应报警规则，这里的默认值会被规则表中的 处理方式 覆盖。

配置里的数据管理

配置抽屉底部有 3 个危险操作：

  • 清空记录：清空抓取记录和抓取日志，不删配置
  • 清空归档：删除全部归档内容和归档文件
  • 清空人工介入：删除全部 需人工介入 条目并解除冻结

这些操作都有确认弹层。

6. 调试抽屉

点右上角 调试 按钮后，会展开调试抽屉。

这里有一个 Chrome 调试地址 输入框，默认是：

http://127.0.0.1:9222

下面是当前版本实际可用的调试动作：

启动监控 / 停止监控

和主界面的 开始 / 停止 是同一件事。

启动后，程序会按固定间隔持续轮询目标页面。当前轮询间隔是 15 秒。

每轮会：

  1. 读取当前页面
  2. 去重并锁定待处理报警
  3. 一条一条串行发送
  4. 按配置决定是否继续网页处理

已经发送过的条目会跳过；已经进入 需人工介入 的条目也会跳过，直到你手动清理或标记完成。

读取网页测试

作用：

  • 连接 Chrome
  • 打开目标页
  • 读取 1 条报警
  • 发送企业微信消息
  • 按当前配置决定是否继续处理同一条网页报警

特点：

  • 这是单条串行联调
  • 会写抓取日志
  • 不会写入 归档 页
  • 过程中失败会转成 需人工介入

测试发送消息

作用：

  • 不读网页
  • 直接向目标群发送一条固定样例消息

固定样例内容是：

报警通知
车牌号：测试车牌
所属企业：测试企业
报警规则：测试规则

特点：

  • 用来验证企业微信自动化链路
  • 不读取 Chrome
  • 不写抓取归档

操作页面测试

作用：

  • 打开目标页
  • 测试页面侧边栏的展开和收回

这个动作只验证页面交互链路，不发消息。

测试告警处理

作用：

  • 读取 1 条报警
  • 打开详情
  • 填写 通知人 和 处理方式

特点：

  • 不发送企业微信消息
  • 固定按安全方式执行
  • 不会点击 确认处理
  • 不会写入 归档 页

7. 日志抽屉

点右上角 日志 按钮后，会展开操作日志抽屉。

这里有几个常用控制：

  • 清空：清空当前界面里的日志显示
  • Debug: 开/关：控制是否收集普通操作日志
  • 全部 / 仅错误：切换日志过滤条件

注意当前实现里：

  • Debug: 关 时，默认主要收集错误日志
  • Debug: 开 时，普通操作过程日志也会进入这里

如果你要排查完整执行链路，先把 Debug 打开。

8. 推荐使用顺序

只验证企业微信发送

  1. 打开应用
  2. 在 配置 里确认 目标群名称 模式
  3. 打开 调试
  4. 点击 测试发送消息
  5. 去企业微信确认是否发出

验证网页读取和串行流程

  1. 打开 配置
  2. 确认 抓取页面地址 和 抓取字段
  3. 先把 执行模式 设为 安全演练
  4. 按需要设置 通知人 和 处理方式
  5. 打开 调试
  6. 点击 读取网页测试
  7. 在 抓取 页和 日志 抽屉观察结果

正式跑自动流程

  1. 先完成上面的单步联调
  2. 在 配置 里确认是否要开启 读取后自动处理告警条目
  3. 只有确认网页处理链路已经稳定后，再切到 正式执行
  4. 点击主界面 开始 或调试抽屉里的 启动监控

9. 数据和日志位置

抓取日志

~/Library/Application Support/AlertBridge/captures

归档目录

~/Library/Application Support/AlertBridge/archive

人工介入记录

~/Library/Application Support/AlertBridge/manual_review

配置

~/Library/Application Support/AlertBridge/settings.json

登录密码不写入 settings.json，由 macOS Keychain 保存。

10. 常见问题

点了“测试发送消息”没反应

先检查：

  • 企业微信是否已安装并可正常启动
  • macOS 辅助功能权限是否已打开
  • 企业微信窗口是否能被正常切到前台

读取网页失败

先检查：

  • Chrome 是否安装在默认位置
  • 目标页面是否已经登录
  • 抓取页面地址 是否正确
  • 抓取字段 是否和页面表头名称基本一致
  • Chrome 调试地址 是否可用

一直看不到详细日志

去 日志 抽屉，把 Debug 打开。

归档页没有数据

这是正常的，只有真正完成网页里的 确认处理 和 关闭 才会归档。下面任一情况都不会写归档：

  • 只做 测试发送消息
  • 只做 读取网页测试
  • 关闭了 读取后自动处理告警条目
  • 当前还是 安全演练

11. 开发相关

这一节面向需要改代码和重新编译应用的开发者。普通使用者可以直接跳过。

安装开发依赖

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt

构建脚本默认使用仓库内的 .venv/bin/python。如果你要改用别的 Python，可以在编译前设置环境变量：

ALERTBRIDGE_PYTHON_BIN=/your/python/path

当前构建流程会复用仓库里的 assets/app_icon.png 生成 AppIcon.icns，并把 Python worker 与依赖复制进 App bundle。

构建 .app

./scripts/build_swiftui_app.sh

编译完成后，应用产物位于仓库根目录：

./AlertBridge.app

构建脚本会把下面内容一起打进 App bundle：

  • Contents/Resources/python
  • Contents/Resources/alertbridge-python
  • Contents/Resources/AppIcon.icns

App 启动时会优先使用 bundle 内的 Python worker；开发调试时仍保留本地项目路径 fallback。

打包 .dmg

./scripts/package_dmg.sh

打包完成后，分发产物位于：

./dist/AlertBridge.dmg

DMG 里包含：

  • AlertBridge.app
  • Applications 快捷方式

手动构建完整流程

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./scripts/build_swiftui_app.sh
./scripts/package_dmg.sh

分发注意事项

当前构建目标是 Apple Silicon macOS 13+：

arm64-apple-macos13.0

内部使用时不需要上架 App Store。当前签名是 ad-hoc 签名，所以首次打开可能需要右键选择 打开。

开发时主要目录

  • swiftui-shell/：SwiftUI macOS 壳层和界面
  • alertbridge_service/：SwiftUI 与 Python 服务之间的 JSON 桥接入口
  • app/：状态管理、控制器、日志、归档、人工介入存储
  • browser/：Chrome 页面连接、读取和页面操作
  • wecom/：企业微信自动发送逻辑
  • scripts/：初始化、构建和 DMG 打包脚本

12. 当前边界

当前版本重点已经切到可用性和串行闭环，暂时没有做这些：

  • 系统托盘
  • 数据库持久化
  • 更复杂的调度策略
  • 更细粒度的业务去重规则

About

Local macOS alert bridge that reads web alarm lists, formats rule-based WeCom notifications, and automates sending, archiving, and manual review.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

AlertBridge 0.2.0 Latest
May 7, 2026

Packages

 
 
 

Contributors

Languages