Skip to content
BranchesTags

Repository files navigation

AstrBot Webhook Notifier

接收由 omp-config onebot post hook 发送的 oh-my-pi 会话结束通知，并向 AstrBot 私聊或普通 QQ 群发送纯文本通知或 HTML 图片卡片。

Release License Python AstrBot Plugin

OMP 原生提供 extension / hook 加载机制和 session_stop 生命周期事件；HTTP Webhook 发送、环境变量与 version 1 payload 由上述社区 hook 实现，并非 OMP 内建 Webhook。本插件支持 OMP、OpenCode 与通用 markdown provider；OpenCode 使用 V1 file Plugin 产生安全的四事件 envelope，markdown 用于 CPA 自动更新等受控运维通知。

版本状态： 当前已发布稳定版与当前源码版本均为 v1.3.0。正式 tag、GitHub Release 与远端正式 ZIP 已验证可用；插件市场安装/更新与生产 AstrBot 使用远端正式资产的 smoke 尚未验证。README 中原有 v1.2.0 条目继续描述历史能力；发布与安装边界见公共契约和发布流程。

功能亮点

  • 兼容社区 onebot post hook 产生的 omp.session_stop payload，展示会话、工作目录、模型、耗时与输入规模等常用信息。
  • v1.2.0 支持 OpenCode V1 file Plugin，将 session_idle、session_error、permission_asked 与 question_asked 转换为匿名、白名单 envelope。
  • 支持通用 markdown.message：复用 Endpoint Bearer、目标别名白名单、幂等、文本/HTML 图片与自动降级链路，不新增公开路由。
  • root session_idle 可选汇总匿名 subagent timeline：简单流程显示阶段卡，复杂流程可附同一消息链的横向时间线；不显示原始 Session ID。顶部提供覆盖统计（总任务时长、子任务覆盖时长与覆盖率），不完整数据标为“已观测”。
  • v1.2.0 统一用户等待时间线：OpenCode Question/Permission 的等待区间与 subagent 在同一张完整 root-cycle 甘特图中对齐展示，顶部固定“等待用户”轨道并给出未分类时间/占比；等待区间是匿名、有界的，原始 ID、正文与答案不出站。
  • metadataDiagnostics=anomaly 提供有界/匿名/fail-closed 的元数据诊断，用于捕获 root/unknown fallback 取证信号；不承诺定位根因。
  • 支持纯文本与 HTML 图片卡片两种全局渲染模式。
  • HTML 渲染或图片发送异常时，可自动降级为纯文本通知。
  • 通过聊天命令为个人私聊或普通 QQ 群创建、轮换、撤销和删除 endpoint。
  • Endpoint Path 与 Token 分开交付，聊天消息不会返回完整 Webhook URL。
  • 在认证后的 Plugin Page 中预览、复制、编辑、保存、应用和删除自定义 HTML 模板。
  • 为每次请求返回可观察的投递、跳过、降级与重试信息，便于调用方判断结果。
  • #24：全局最短完成通知时长阈值：成功完成的 Webhook 事件耗时低于阈值时跳过通知（默认 15 秒），减少短任务噪音。0 关闭过滤恢复旧行为。可靠耗时仅来自 Provider 特定字段，不对外暴露 task_duration_ms。通过 admin config min-duration 命令查询/设置/reset。

完整使用流程

flowchart LR
    A["oh-my-pi"] --> B["omp-config<br/>onebot.ts 社区 Hook"] --> C["HTTPS 反向代理<br/>Caddy（推荐参考）或其他方案<br/>非强依赖"]
    C --> D["Webhook Notifier<br/>HTTP Server"] --> E["Token 鉴权<br/>事件标准化"]
    E --> F["文本或 HTML 卡片"] --> G["AstrBot adapter"] --> H["私聊或普通 QQ 群"]
Loading
  1. 安装并重载 Webhook Notifier 插件。
  2. 配置 HTTP 监听地址、端口与 public_base_url；同机或可信内网可直接访问。
  3. 跨主机或公网接入时，按需部署 HTTPS 反向代理；Caddy 是推荐参考，也可使用其他方案。
  4. 通过聊天命令创建私聊或普通 QQ 群 Endpoint，分别保存 Base URL、Endpoint Path 与 Token。
  5. 使用 curl 验证 URL、Token 鉴权和实际投递或跳过结果。
  6. 部署社区 onebot post hook，并配置 OMP_SESSION_WEBHOOK_URL 与 OMP_SESSION_WEBHOOK_TOKEN。
  7. 触发真实 oh-my-pi 会话结束事件，确认目标私聊或普通 QQ 群收到通知。

完整教程： 请阅读端到端部署，其中集中说明 Caddy HTTPS 反代与社区 Hook 的完整配置，README 不重复展开运维细节。

快速开始

1. 安装插件

当前已发布稳定版与当前源码版本均为 v1.3.0。对应 GitHub Release 与正式 ZIP 已可用；插件市场搜索、安装和更新仍未完成验证，文件安装与源码安装的实际可用性仍取决于 AstrBot 运行环境。

方式 操作
Release ZIP（推荐） 从 v1.3.0 Release 下载 astrbot_plugin_webhook_notifier-v1.3.0.zip，在 WebUI 选择“从文件安装”
RC 验收包 v1.1.0-rc.1 与带 rc-smoke 标识的本地测试包仅用于稳定版发布前验收，不作为后续常规安装入口
资产核对 v1.3.0 tag、Release 与正式 ZIP 已核对；插件市场资产与安装/更新路径仍待验证；RC 资产仅用于候选版回溯
WebUI 仓库 URL 在 URL 安装入口填写 https://github.com/AsterleedsGuild0/astrbot_plugin_webhook_notifier
源码安装 将仓库克隆到 AstrBot/data/plugins，见下方命令

后两种方式同样不是官方插件市场搜索安装。源码安装命令：

git clone https://github.com/AsterleedsGuild0/astrbot_plugin_webhook_notifier.git \
  AstrBot/data/plugins/astrbot_plugin_webhook_notifier

安装后在 WebUI 中加载或重载插件。运行环境需要 Python >= 3.10。

2. 完成最小配置

进入 AstrBot WebUI → 插件管理 → Webhook Notifier → 配置：

  • 保持 enabled: true；默认文本模式无需额外配置。
  • 按部署方式配置 server.host、server.port 和包含 Webhook base path 的 server.public_base_url：同机或可信内网可直连，跨主机或公网建议通过 Caddy 等反向代理提供 HTTPS；不要公开真实值。
  • 本节使用私聊 endpoint 验证。只有在确认平台主动消息规则和风险后，才将 enable_private_notifications 设为 true，然后重载插件。

3. 创建第一个私聊 endpoint

<唤醒词>whn token new private demo

AstrBot 默认唤醒词为 /，因此默认命令是 /whn token new private demo。创建成功后，聊天返回 Endpoint Path，并在独立消息中交付一次 Token；不会返回完整 URL。请在认证后的插件详情 Plugin Page 复制 Base URL。

4. 模拟 onebot post hook 请求

先把三个值分别写入环境变量，不要把 Token 放进 URL：

export WHN_BASE_URL='<从认证 Plugin Page 复制>'
export WHN_ENDPOINT_PATH='<聊天返回的 Endpoint Path>'
export WHN_TOKEN='<聊天单独返回的 Token>'

curl --fail-with-body --silent --show-error \
  -X POST "${WHN_BASE_URL}/${WHN_ENDPOINT_PATH}" \
  -H 'Content-Type: application/json' \
  -H 'X-OMP-Event: session_stop' \
  -H "Authorization: Bearer ${WHN_TOKEN}" \
  --data-binary @- <<'JSON'
{
  "event": "omp.session_stop",
  "version": 1,
  "emittedAt": "2026-07-20T12:00:00Z",
  "session": {"name": "README smoke test", "model": "provider/model"},
  "round": {"turnId": "demo-1", "durationMs": 1200}
}
JSON

预期结果：

  • 私聊通知已开启时，HTTP 返回 200、code: 0、message: "ok"，Bot 私聊收到一条文本或图片通知。
  • 私聊通知保持默认关闭时，HTTP 仍返回 200，但 message: "skipped"，聊天不会收到通知；这是安全策略结果，不应重试。
  • 使用 html_image 且发生渲染问题时，默认会回退为文本，并在 HTTP 响应中给出降级原因。

接入自动通知

端到端部署见专题教程，客户端接入文档包含 onebot.ts 的 OMP 用户级/项目级目录、进程环境变量、加载验证和 session_stop 触发方法。从上游部署 onebot post hook 后，为其配置完整 URL 变量 OMP_SESSION_WEBHOOK_URL 和 Token 变量 OMP_SESSION_WEBHOOK_TOKEN。

ParticleG/omp-config 是独立维护的社区仓库，当前未明确 LICENSE；本项目仅链接上游源文件，不复制或分发其代码，也不代表该 hook 由本项目或 OMP 官方维护。

OpenCode 快速接入

  1. 先构建并安装包含 OpenCode provider 的 Webhook Notifier 测试包，然后在 AstrBot 中重载插件；未部署新服务端版本时，旧插件无法创建或处理 OpenCode Endpoint。
  2. 在 AstrBot 私聊创建 OpenCode Endpoint：<唤醒词>whn token new private <名称> --provider opencode。
  3. 分别保存 Plugin Page 的 Base URL、聊天返回的 Endpoint Path 和单独交付的 Bearer Token，并在受控环境中组成客户端所需的完整 Endpoint URL。
  4. 将 integrations/opencode/webhook-notifier.ts 放到运行 OpenCode 的机器，复制 integrations/opencode/opencode.jsonc 的 V1 plugin tuple，并用 {env:...} 或 {file:...} 提供 URL/Token。可选配置 instanceDisplayName 作为 OpenCode 实例标识；projectName 由客户端自动推导 worktree basename，不需要用户配置。actionContentMode 默认 strict；只有明确接受业务文本/目标路径泄露风险时才设置为 summary 或 full。
  5. 服务端升级并重载后再部署新版 Client；完全重启 OpenCode Desktop 或 CLI 进程，再触发完成、失败和权限请求事件并核对 Bot 通知。旧服务端严格 allowlist 不接受新 session.scope。

python scripts/smoke_opencode_plugin.py --cli 只验证 OpenCode CLI 会实际调用 V1 Plugin server，不能替代 AstrBot 测试包部署、Endpoint 创建和 Bot 端到端通知验收。完整流程见OpenCode 集成指南。

Markdown 信息推送

先创建独立的 Markdown Endpoint：<唤醒词>whn token new private ops --provider markdown。调用仍使用现有 POST {base_path}/{endpoint} 与 Endpoint Bearer Token：

curl --fail-with-body --silent --show-error \
  -X POST "${WHN_BASE_URL}/${WHN_ENDPOINT_PATH}" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${WHN_TOKEN}" \
  --data-binary @- <<'JSON'
{
  "event": "markdown.message",
  "id": "cpa-update-stable-id",
  "title": "CPA 自动更新",
  "markdown": "## 更新完成\n\n- CPA：`x → y`\n- 状态：**成功**",
  "target_alias": "default"
}
JSON

仅支持标题、段落、有序/无序列表、粗体/斜体、行内代码、fenced code 与普通 http(s) 链接。Raw HTML、图片语法、Jinja/模板语法与外部资源不会执行；不安全或不支持的语法按文本显示。target_alias 只能选择当前 Endpoint 已绑定的别名，调用方不能传入 UMO。

支持范围

平台声明表示对应路径已验证，不代表平台允许无限制主动发送消息。

平台 / 场景 状态 当前边界
aiocqhttp 已验证 命令、普通 QQ 群通知与 HTML 图片卡片
qq_official WebSocket 私聊 已验证 私聊命令、Webhook 鉴权、主动通知与 OMP 图片卡片
qq_official WebSocket 普通 QQ 群 已验证 群验证、主动 Webhook 与 OMP HTML 图片卡片
qq_official WebSocket QQ 频道（Guild） 不支持，无计划 当前身份与群验证流程不覆盖 QQ 频道
qq_official_webhook 不支持，无计划 未在插件元数据中声明，也未适配该接入方式

Webhook 私聊主动通知默认关闭；开启前请阅读平台投递策略，群聊通知不受此开关影响。

常用命令

文档统一使用 <唤醒词>；默认值为 /。完整说明见命令参考，管理员命令不在首页展开。

场景 命令
查看帮助 <唤醒词>whn help
创建私聊 endpoint <唤醒词>whn token new private [名称]
申请群聊 endpoint aiocqhttp: <唤醒词>whn token new group <数字群号> [名称]；qq_official: <唤醒词>whn token new group current [名称]
查看自己的 endpoint <唤醒词>whn token list
轮换 Token <唤醒词>whn token rotate <名称>
撤销 endpoint <唤醒词>whn token revoke <名称>
永久删除终态 endpoint <唤醒词>whn token delete <名称>

配置摘要

配置 默认值 作用
enabled true 启用插件；创建可投递 endpoint 后自动启动 HTTP 服务
render_mode text 选择 text 或 html_image 以使用纯文本或是HTML渲染模式
notification_mode focused focused 仅抑制成功完成的 subagent/auxiliary；all 发送全部通知
min_completion_duration_seconds 15 最短完成通知时长（秒）：成功完成的任务耗时低于此值跳过通知；0 关闭过滤恢复旧行为
enable_private_notifications false 是否允许 Webhook 主动投递到私聊目标
fallback_to_text true HTML 图片链路失败时是否降级为文本
server 本地监听 配置 host、port、base_path、public_base_url 与请求体上限

全量字段、默认值和编辑格式以 _conf_schema.json 为准；部署与运维说明见安全与运维。

HTML 模板与 Base URL

在 AstrBot 插件详情页打开 Plugin Page，可以查看只读内置模板，或创建副本后编辑、预览、保存、应用和删除自定义模板。模板变量与示例见 HTML 模板变量。

同一页面提供认证后的 Base URL 复制入口。调用方应将它与聊天返回的 Endpoint Path 组合；Base URL、Endpoint Path 和 Token 应分别保存，避免凭据随完整 URL 泄露。

安全提示

  • 公网接收 Webhook 时使用 HTTPS，并优先让 HTTP 服务监听本地地址、由反向代理转发。
  • Token 只放在 Authorization Header 的 Bearer <token> 中；泄露后立即执行 token rotate。
  • 私聊主动通知默认关闭；开启前核对 QQ 官方规则或 OneBot 实现的风控边界。
  • 社区 hook 可能发送截断 prompt、cwd、session 文件、模型和消息计数等元数据；部署前评估数据外发边界，提交 Issue、日志或截图时一并脱敏。
  • OpenCode 通知默认只发送 action 类别/计数；full 内容模式是显式 opt-in，虽有字段白名单和大小上限，仍可能外发问题、权限描述或目标路径。
  • Subagent timeline 只在 root session_idle 中可选发送，时间是相对 root busy→idle cycle 的观测偏移；卡片不展示匿名图引用、原始 Session ID、路径或工具参数，部分数据不会伪装成精确耗时。
  • actionContentMode 只控制 OpenCode Question/Permission 内容隐私，与服务端 notification_mode 正交；focused 只抑制成功完成的 subagent/auxiliary，unknown 会 fail-open 放行。
  • OpenCode Client 的会话上下文只按白名单发送匿名 session.ref、session.scope、会话名及（子会话可解析时）安全清洗的 session.rootName；父链只使用匿名 parentRef，不发送 raw parentID、ID、路径或原始对象，缺失/环路/超深时省略；部署必须服务端先升级、再部署并完全重启 OpenCode Client。
  • Markdown provider 不执行 raw HTML 或模板语法，不加载远程图片、字体、样式或其他外部资源；链接只允许 http:// 与 https://。
  • adapter 实例的 platform_id 发生变化时，不要直接编辑数据文件，按 rebind runbook 离线处理。

更多说明见安全与运维和平台投递策略。

文档索引

FAQ

这是 OMP 原生 Webhook 吗？

不是。OMP 提供 hook 机制和 session_stop 事件，HTTP 请求与 version 1 payload 来自独立维护的社区 onebot post hook；本插件兼容其请求格式。

OpenCode provider 如何启用？

创建 Endpoint 时追加 --provider opencode；不追加时默认 omp。provider 在创建后不可变，OpenCode Plugin 配置和排障见OpenCode 集成指南。

Markdown provider 如何启用？

创建 Endpoint 时追加 --provider markdown。该 Endpoint 只接受 event=markdown.message 的受限 Markdown payload，继续复用原有 Bearer 鉴权、目标白名单与投递策略。

私聊 endpoint 创建成功，为什么没有通知？

enable_private_notifications 默认是 false。此时请求会返回 HTTP 200 和 message: "skipped"；确认平台规则与风险后开启配置并重载插件。

HTML 图片失败后怎么办？

保持 fallback_to_text: true，插件会尝试回退文本。再检查 AstrBot html_render / T2I 服务、模板内容和响应中的 fallback_reason；截图裁剪与渲染排查见 docs/t2i-rendering-notes.md。

反馈与 License

发现缺陷或文档问题，请提交 GitHub Issue。公开反馈中请勿附带真实 Token、完整 Webhook URL 或未经脱敏的日志与截图。本项目采用 MIT License。

About

AstrBot plugin for receiving external webhooks and forwarding notifications as text or HTML card images to configured conversations.

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages