koishi-plugin-sentry-sentinel

作者：MuxYang

定时读取 Sentry Android 项目的新错误事件，按同一问题聚合，并将 crash / ANR 详情通过 Koishi 合并转发推送到配置的群或用户。

配置

在 Koishi 插件配置页设置：

| 配置 | 说明 | 默认值 | | --- | --- | --- | | Sentry 实例地址 | 官方版为 https://sentry.io；自建版填写实例根地址 | https://sentry.io | | Auth Token | 建议使用只读内部集成令牌，至少授予 project:read | 必填 | | Organization | 组织 slug，不是显示名称 | 必填 | | Projects | 一个或多个项目 slug | 必填 | | 轮询间隔 | 单位分钟，最小 1 分钟 | 5 | | 首次回看时间 | 首次启动读取最近多少分钟；之后使用持久化游标 | 60 | | 最少新事件数 | 同一问题累计到此数量才推送 | 3 | | 最少影响用户数 | 按 Sentry event 的用户身份去重，0 表示不限制 | 3 | | 同问题再次报告 | none 不报告；compact 只发标题和累计数；full 重新发完整详情 | compact | | 仅 Android | 根据 platform、OS 和设备上下文过滤 | 开启 | | 推送目标 | 设置 Koishi platform、可选 bot 账号、目标类型和群号/用户 ID | 无 |

群目标使用 Koishi bot.sendMessage()，私聊目标使用 bot.sendPrivateMessage()；消息内容是 Koishi 标准 message forward 元素。目标平台的适配器需要实现合并转发。OneBot 目标由 OneBot 适配器处理对应转发 API。

聚合和重复报告

• 插件每次仅读取上次成功游标之后的事件，并为查询起点保留 1 秒重叠；事件 ID 会去重。
• 插件按项目顺序串行请求，读取 Sentry 限流响应头；剩余额度耗尽时等到窗口重置再继续，收到 HTTP 429 时也会按重置时间暂停该项目。
• 同一问题未达到最少新事件数和最少影响用户数时，事件留在本地待推送队列，后续轮询继续累计。
• 影响人数只统计 Sentry 提供了 user.id、email、username 或 user 标签的事件；没有用户身份的事件不会被猜测为独立用户。
• 首次推送总是完整转发。后续同问题再次达到阈值时按 repeatIssue 配置处理。
• 成功推送后才清空该问题的本轮累计数据。推送目标暂时不可用时，待推送数据会保留，并在后续轮询重试。
• 完整详情包含事件 ID、Sentry 事件链接、时间、机型、Android 版本、内存和应用版本；每条转发的事件数由 maxEventsPerForward 限制。

持久化

默认状态文件为 Koishi baseDir 下的 data/sentry-sentinel/state.json。其中保存每项目游标、待推送事件摘要、近期事件 ID 和已报告问题 ID；不会保存 Auth Token 或原始用户身份。需要重装或迁移时，保留该文件即可继续此前的累计状态。

Sentry API 权限

插件读取 GET /api/0/projects/{organization}/{project}/events/，通过 Bearer Auth Token 认证，使用 start、end 查询窗口和 Sentry Link 响应头分页。建议给 token 最小所需的项目只读权限。

运行环境需要 Node.js 18 或更新版本。

• Sentry List a Project's Error Events
• Sentry API Authentication
• Sentry API Pagination
• Sentry API Rate Limits
• Koishi Message API
• Koishi Standard Message Elements