使用场景

网站有了告警中心、问题反馈和友链申请后,总不能每次都打开星枢,挨个看看有没有需要处理的内容。

我本来就在用 AstrBot,希望这些事情能直接出现在聊天里。收到通知后,可以接着问具体原因,确认后再让机器人处理,而不是收到消息,又回到后台重新找记录。

整体介绍见 关于本站:微光集,网站结构见 微光集模块构成与实现思路。

微光集负责业务判断、状态和邮件,AstrBot 负责通知与对话,LLM 通过限定工具执行管理员明确要求的操作。

实现内容

功能实现方式
告警通知新告警、级别升级及任务/队列异常进入通知链路
问题反馈新反馈及处理状态变化时通知,支持查询原文、标记已解决
友链处理自动审核通过、失败达到阈值时通知,支持通过、失败邮件与弃用
任务重试查询任务状态、日志和队列,按需重试失败或中断的任务
通知模板告警、反馈、友链分别配置文本模板
对话上下文可把通知记入绑定会话,方便后续追问
投递记录本站记录向插件投递的结果,插件记录向聊天平台发送的结果

通知由 Go 主动推送。插件只在管理员查询或操作时请求本站 API。

对接入口与数据流

通知:
业务事务 → MySQL notification_outbox → Go 投递工作器
    → AstrBot 插件 Web API → SQLite 收件箱 → 绑定会话
 
处理:
管理员提出操作 → LLM 选择 MicroLight 工具
    → 插件校验管理员 UID → 本站受限 API
    → Go 校验业务条件 → 更新数据/邮件入队

插件仓库:astrbot_plugin_microlight。通过 AstrBot SDK 的 register_web_api 注册通知入口,由 AstrBot 统一提供 HTTP 服务。

默认接收地址:

http://astrbot:6185/api/v1/plugins/extensions/astrbot_plugin_microlight/webhook

这是 Go 容器访问 AstrBot 的内部地址。换部署方式时,需要调整主机名和端口。

插件反向访问本站使用网站根地址,例如 https://goblincwl.site,具体接口由客户端拼到 /api/microlight/v1/ 下。

两种密钥分别做什么

凭据来源用途
AstrBot 插件 API KeyAstrBot 创建,授予插件权限Go 请求 AstrBot,使用 X-API-Key
MicroLight API Token星枢 → 账户 → 本站 API 生成插件调用本站使用 Bearer;接收通知时使用 X-MicroLight-Token 校验来源

AstrBot 的 API Key 复用星枢「服务 → AstrBot → 插件 API Key」,对应 api.astrbot.token。

本站 Token 生成后只显示一次,复制到插件的 api_token。本站在数据库中加密保存,重置后旧 Token 失效,插件需要同步更新。

AstrBot API Key 让请求进入插件接口,MicroLight Token 确认双方使用的是同一套本站接入配置。。

本站 Token 只能访问固定开放的接口。

配置步骤

  1. 安装并加载 astrbot_plugin_microlight。
  2. 在星枢账户中生成本站 API Token,填写到插件 api_token。
  3. 插件 microlight_url 填本站根地址,admin_uids 填允许管理的平台 UID。
  4. 创建具有插件权限的 AstrBot API Key,填入星枢已有的 AstrBot 服务配置。
  5. 在星枢账户的本站 API 区域配置接收地址,开启通知类型及告警最低级别。
  6. 在目标会话发送 /microlight_bind,绑定接收位置。
  7. 发送 /microlight_check 检查 API 连接。

接收地址对应 notify.astrbot.url。总开关是 notify.astrbot.enabled,分类开关分别为 notify.astrbot.alerts、notify.astrbot.feedback、notify.astrbot.friends,最低级别为 notify.astrbot.minLevel。

命令用途
/microlight查看启用状态、会话与发送队列,不显示密钥
/microlight_check检查本站连接、鉴权和接口版本
/microlight_bind绑定当前通知会话
/microlight_retry重新排队插件中已达到重试上限的失败通知

这些命令同样检查 admin_uids,不是任意聊天用户都能绑定通知或执行管理操作。

通知投递

业务操作与通知事件在同一个数据库事务中保存,提交后由 Go 工作器读取 notification_outbox 投递。

插件校验事件后写入 notifications.sqlite3,返回事件 ID,Go 随后更新投递状态。同一事件重试时 ID 不变,插件按 ID 去重。

投递记录分为两处:

  • 星枢:Go 向插件投递的结果。
  • 插件:向聊天会话发送的结果。

两边各自最多尝试 10 次,从 30 秒开始指数退避,最长等待一小时。达到上限后,可以在星枢重试投递,或通过 /microlight_retry 重试消息发送。

通知模板与上下文

告警、反馈、友链分别配置纯文本模板,支持换行,留空使用默认格式。

变量含义
{title}事件标题
{summary}内容摘要,友链失败附具体原因
{status}业务状态
{recordId}业务记录标识
{occurredAt}北京时间,格式 yyyy-MM-dd HH:mm:ss
{category}中文通知分类
{level}中文告警级别
{id}通知事件 UUID
{kind}原始类型:alerts、feedback、friends

recordId 用于查询和操作业务记录,id 用于通知去重。友链卡片编号与内部 UUID 分开保存,操作时通过查询工具取得 UUID。

模板在发送时应用,修改后对尚未发送的通知生效。

通知默认记入绑定会话的上下文,方便后续追问。record_context 可以关闭记录。

LLM 操作

插件通过 AstrBot 注册 LLM 工具,调用时检查发送者的 admin_uids。

工具功能
microlight_records查询告警、反馈、友链、任务列表或详情
microlight_delete_alert删除单条告警
microlight_approve_friend人工审核通过友链
microlight_abandon_friend发送失败邮件并删除友链
microlight_send_friend_failure_mail只发送失败邮件
microlight_resolve_feedback标记反馈已解决,发送处理邮件
microlight_auto_review_friends提交回链自动审核
microlight_retry_task重试失败或中断的任务

收到通知后,可以直接接着处理:

看一下这条友链失败的原因
弃用这条友链
这条反馈已经解决了,标记一下
重试刚才失败的任务

插件先查询记录,再调用对应接口。弃用和发送失败邮件需要管理员明确确认,通知内容本身不作为操作指令。

角色工具配置

如果 AstrBot 角色设置了工具白名单,在 tool_persona 中填写角色名称。插件加载时通过 PersonaManager 追加 MicroLight 工具,保留原有工具;留空则不修改角色。

友链审核与巡检

友链有两组状态:

  • 已审/待审:审核状态,通过后进入公开列表。
  • 已验/未验:回链验证标记,可独立切换。

审核

自动审核先检查首页、头像和配置的 RSS,再检查回链页面中的本站首页链接。通过后设为已审、已验,发送成功邮件和 AstrBot 通知。

回链检查读取服务器返回的 HTML。通过 JavaScript 动态加载的友链暂时需要人工审核。

星枢点击待审,会提交一次人工检查队列。首页、头像、RSS 全部通过后设为已审、未验,失败则保留待审。插件的 microlight_approve_friend 用于直接通过已完成前置检查的记录。

申请失败

待审核申请失败后累计次数,由周期任务继续处理。默认从第 5 次开始,每次失败都通知 AstrBot,阈值可配置。通知包含失败原因。

收到通知后,可以选择:

  • 发送失败邮件,保留申请。
  • 弃用申请,发送失败邮件并删除记录。

手动弃用要求达到失败阈值,并有通知邮箱。邮件任务与删除记录在同一事务中提交。

已收录友链巡检

已通过的友链检查首页、头像和 RSS。只有首页失败累计巡检失败天数,北京时间同一天计一次,成功不清零。

默认累计 3 天置灰、7 天移除,均可在任务模块配置。头像和 RSS 刷新失败时沿用已有数据。

移除时发送邮件。没有邮箱的友链仍移除,并记录无法发送邮件的告警。

友链队列并行数量可设为 1–8,默认 1;头像压缩最多同时两个。

反馈处理与邮件

标记反馈已解决时,Go 将处理邮件写入队列。重复标记不重复发送,重新打开后再次解决会发送新的处理结果。

插件调用本站接口,SMTP 和邮件模板由本站维护。评论邮件见 Artalk评论系统对接,反馈与友链分别使用各自的邮件模板。

任务重试

先查询任务 key、日志和 retryable,再提交重试。支持失败或中断的任务,运行中或已排队的任务不能重复提交。

操作使用工具
全站友链巡检失败后重试microlight_retry_task,任务 key 为 friends-refresh
自动审核待审核申请microlight_auto_review_friends
查看执行结果microlight_records

使用的 API

接口根路径为 /api/microlight/v1,请求头使用 Authorization: Bearer <MicroLight API Token>。

方法与路径用途
GET /status连接、版本及权限检查
GET /alerts、/alerts/{id}告警列表和详情
GET /feedback、/feedback/{id}反馈列表和详情
GET /friends、/friends/{id}友链及待审申请
GET /tasks、/tasks/{key}任务、日志及重试条件
DELETE /alerts/{id}删除单条告警
POST /friends/{id}/approve人工通过已满足前置条件的友链
POST /friends/auto-review、/friends/{id}/auto-review批量或单条回链自动审核
POST /friends/{id}/failure-mail发送失败邮件
POST /friends/{id}/abandon邮件入队并删除友链
POST /feedback/{id}/resolve标记已解决,发送处理邮件
POST /tasks/{key}/retry提交任务重试

排查

情况检查位置
没有投递记录通知开关、分类、最低级别及通知时机;新增友链不通知
本站投递失败容器网络、插件加载状态、两种 Token
插件已接收但没消息绑定会话、插件发送队列
模型无法调用工具admin_uids、角色工具白名单、tool_persona
工具调用失败记录详情、审核条件、失败阈值、通知邮箱、任务状态
有回链却未通过服务器返回的 HTML 是否包含链接

星轨图