Documentation
¶
Overview ¶
Package ntfy 把 RelayMesh 里「需要你处理」的事件推送到 ntfy(https://ntfy.sh 或自建实例)。
浏览器里的声音与系统通知只在网页开着、事件流连着的时候才会响;智能体在等你回复,你却不在电脑前, 提醒就送不到。ntfy 是一个简单的推送服务:Hub 往一个「主题」发一条消息,手机或桌面上订阅了这个主题的 ntfy 应用立刻就会弹出通知——不依赖任何网页是否打开。
本包是叶子包(只依赖标准库与 model),职责分三层:
- config.go 配置的形状、校验、对外视图(凭据只写不读);
- sender.go 一次推送的 HTTP 细节:JSON 发布、认证头、重试、错误脱敏、目标地址防护;
- notifier.go 事件队列:去重、延迟、限流、状态统计,让「推送失败 / 变慢」永远拖不住智能体的请求。
Index ¶
- Constants
- Variables
- func KindLabel(id string) string
- func KnownKind(id string) bool
- func PriorityName(p int) string
- type AutoResumeInfo
- type Config
- func (c Config) ExceptionKindEnabled() bool
- func (c Config) Normalize() Config
- func (c Config) PriorityFor(kind string) (priority int, on bool)
- func (c Config) Public(envToken string) PublicConfig
- func (c Config) TestPriorityFor(kind string) int
- func (c Config) Validate(requireTopic bool) error
- func (c Config) WithEnvToken(envToken string) Config
- type EventInfo
- type ExceptionInfo
- type KindInfo
- type Message
- func BuildAutoResumeMessage(cfg Config, in AutoResumeInfo, host string, merged int) Message
- func BuildEventMessage(cfg Config, in EventInfo, count, merged int) Message
- func BuildExceptionMessage(cfg Config, in ExceptionInfo, repeats, merged int, now time.Time) Message
- func BuildKindTestMessage(cfg Config, kind string, now time.Time) (Message, int)
- func BuildRequestMessage(cfg Config, in RequestInfo, merged int) Message
- func BuildRunMessage(cfg Config, in RunInfo, host string, merged int) Message
- func BuildTestMessage(cfg Config, now time.Time) Message
- type Notifier
- func (n *Notifier) EffectiveConfig(ctx context.Context) (Config, error)
- func (n *Notifier) NotifyAutoResume(in AutoResumeInfo)
- func (n *Notifier) NotifyEvent(in EventInfo)
- func (n *Notifier) NotifyException(in ExceptionInfo)
- func (n *Notifier) NotifyRequest(s *model.FeedbackSession)
- func (n *Notifier) NotifyRun(in RunInfo)
- func (n *Notifier) SendKindTest(ctx context.Context, cfg Config, kind string) (Result, int, error)
- func (n *Notifier) SendTest(ctx context.Context, cfg Config) (Result, error)
- func (n *Notifier) SetTiming(delayUnit, mergeUnit time.Duration)
- func (n *Notifier) Status() Status
- func (n *Notifier) Stop()
- type Options
- type PublicConfig
- type RequestInfo
- type Result
- type RunInfo
- type SendError
- type Sender
- type Status
- type Update
Constants ¶
const ( // DefaultServer 是公共的 ntfy 服务;自建实例填自己的地址。 DefaultServer = "https://ntfy.sh" // DefaultPriority 对应 ntfy 的「high」:手机上会弹出并伴随较长的震动。1 最低、3 默认、5 紧急。 DefaultPriority = 4 // MaxDelaySeconds 是「延迟推送」的上限(15 分钟)。 MaxDelaySeconds = 900 // DefaultRunMinSeconds 是「模型运行结束」推送的默认门槛:运行得比这更短的命令不推送。 DefaultRunMinSeconds = 60 // MaxRunMinSeconds 是这个门槛的上限(24 小时)。 MaxRunMinSeconds = 86400 )
const ( SubAgentError = "error" // Agent 出错结束 SubAgentAborted = "aborted" // Agent 被中断 SubOAuthCodeReplay = "oauth_code_replay" // OAuth 授权码被重放 SubOAuthRefreshReplay = "oauth_refresh_replay" // OAuth 刷新令牌被重放 SubUnlockLocked = "unlock_locked" // 终端解锁尝试过多,被临时锁定 SubLoginLocked = "login_locked" // 登录尝试过多,来源被临时锁定 )
异常的细分(ExceptionInfo.Sub):同一类里更具体的情形,决定标题怎么写。
const ( // 需要你处理。 KindRequest = "request" // 智能体在等你回复(interactive_feedback 阻塞) KindMention = "mention" // 群里 @ 了你(或 @all) KindApproval = "approval_waiting" // 托管终端在等你批准 KindAskCard = "ask_card" // 新的待确认提问 / 方案 / 授权卡 KindAgentText = "agent_text" // Agent 主动发来的文本消息 KindAutoResume = "guard" // 不再自动续跑(#151)。取值沿用历史名 guard(原「终端会话守护告警」,#245 下线):推送设置里按它存开关与优先级 KindGroupCooling = "group_cooling" // 群里 Agent 之间的消息过密,已暂停互相投递 // 模型命令(ExecMesh)运行结束;总开关与最短运行时长另在「运行结束推送」里设。 KindRunTrouble = "run_trouble" // 失败 / 超时 / 结果丢失 / 被主机中断 KindRunOK = "run_ok" // 顺利完成 // 异常:默认都不推送,打开之前不会多出任何一条推送。 KindAgentError = "agent_error" // Agent 出错结束 / 被中断 KindAgentStalled = "agent_stalled" // Agent 疑似卡住 KindHostOffline = "host_offline" // ExecMesh 主机掉线 KindSecurityAlert = "security_alert" // 安全告警 KindBoardStale = "board_stale" // 共享任务板上有指派派出很久没人接(一次性提醒,#180 B3d) )
消息类型的稳定标识:它们存进配置(priority_by_kind 的键)、出现在接口里,只能新增,不要改名。
const ( GroupNeedYou = "need_you" GroupRun = "run" GroupException = "exception" )
表里的分组:只影响设置页怎么排版。
Variables ¶
var ErrInvalidConfig = errors.New("ntfy 配置不合法")
ErrInvalidConfig 表示配置取值不合法;错误信息面向用户,可以直接展示。
Functions ¶
func PriorityName ¶ added in v2.1.0
PriorityName 是 ntfy 优先级的中文名(ntfy 自己叫 min / low / default / high / max)。
Types ¶
type AutoResumeInfo ¶ added in v2.1.0
type AutoResumeInfo struct {
// Key 标识「同一次放弃的同一条推送」:预设编号 + 最后出事的运行。同一个 Key 在去重窗口内只推一次。
Key string
// Name 是预设的名字;Machine 是机器码(主机的显示名由 Notifier 在真正发送前解析)。
Name string
Machine string
// Reason 是一句人话的原因,如「24 小时内已经自动续跑 3 次,达到上限;这次的失败原因:……」。
Reason string
// WorkflowID 是预设里填的工作流编号(用来在推送里写项目名);可为空。
WorkflowID string
}
AutoResumeInfo 是一次「不再自动续跑」推送要用到的字段。纯数据,不依赖终端包:由接线处(api)把终端的事件翻译成它。
type Config ¶
type Config struct {
// Enabled 是总开关;关闭时事件被静默丢弃(配置仍保留)。
Enabled bool `json:"enabled"`
// Server 是 ntfy 服务地址,不带末尾斜杠;允许带路径前缀(反向代理场景)。
Server string `json:"server"`
// Topic 是主题名。公共的 ntfy.sh 上,知道主题名的人都能订阅,所以它相当于密码——请用足够长的随机名字。
Topic string `json:"topic"`
// Token 是 ntfy 访问令牌(Bearer);与 Username / Password 二选一,两者都有时令牌优先。
Token string `json:"token,omitempty"`
Username string `json:"username,omitempty"`
Password string `json:"password,omitempty"`
// ClickURL 是点击通知后打开的地址,一般填 RelayMesh 控制台的外部访问地址;留空则点击没有动作。
ClickURL string `json:"click_url,omitempty"`
// Priority 是「默认优先级」1~5:等你回复、守护告警、命令出状况、测试推送、以及表里没单独设的类型都用它。
Priority int `json:"priority"`
// PriorityByKind 是「各类消息的优先级」覆盖表(见 priority.go):消息类型 → 1~5,或 0 表示这一类不推送;
// 没有出现的类型走内置默认(逐项复刻升级前的行为,异常类默认不推送)。nil 与空表等价。
PriorityByKind map[string]int `json:"priority_by_kind,omitempty"`
// IncludeSummary 为真时,通知里附上智能体摘要的开头一小段;默认只发标题,避免内容经过第三方服务。
IncludeSummary bool `json:"include_summary"`
// DelaySeconds 大于 0 时延迟推送:这段时间里你在网页上处理掉了请求就不再推送(0 = 立即)。
DelaySeconds int `json:"delay_seconds"`
// RunNotify 为真时,模型发起的命令(ExecMesh)运行结束也推送一条:成功、失败、超时、结果丢失,
// 以及被主机侧中断(例如守护进程重启);你自己或模型主动取消的不推。默认关闭,需要明确打开。
RunNotify bool `json:"run_notify"`
// RunMinSeconds 是运行结束推送的门槛:运行得比这更短的命令不推送,免得每条小命令都响铃。1~86400;0 视为默认值。
RunMinSeconds int `json:"run_min_seconds"`
}
Config 是持久化的完整配置(含凭据);只存在于服务端,绝不整体返回给浏览器(见 Public)。
func (Config) ExceptionKindEnabled ¶ added in v2.1.0
ExceptionKindEnabled 报告配置里有没有任何一类异常被打开。巡检器据此决定要不要白白扫一遍: 没打开时一次库都不查。
func (Config) PriorityFor ¶ added in v2.1.0
PriorityFor 返回这一类消息此刻要用的优先级;on 为假表示这一类不推送。 取值顺序:priority_by_kind 里设了的(0 = 不推送,1~5 = 这个优先级)→ 该类的内置默认; 没登记的类型一律跟随默认优先级、不拦(它们不在表里,没法被关掉)。
func (Config) Public ¶
func (c Config) Public(envToken string) PublicConfig
Public 生成对外视图;envToken 是环境变量里的令牌(有值时 token_set 与 token_from_env 都为真)。
func (Config) TestPriorityFor ¶ added in v2.1.0
TestPriorityFor 是「试发这一类」用的优先级:设成 1~5 的用它;没设、或设成不推送的,用内置默认 (默认不推送的异常类用界面建议的值)——让人在打开一类推送之前,就能在手机上试出它的效果。
func (Config) WithEnvToken ¶
WithEnvToken 在环境变量提供了令牌时,让它盖过数据库里保存的令牌(令牌可以完全不进数据库)。
type EventInfo ¶
type EventInfo struct {
// ID 是事件的唯一标识;同一个 ID 在去重窗口内只推一次。
ID string
// Kind 是种类:agent_text / ask_card / mention / approval_waiting;决定没有预览时的那句话与图标。
Kind string
// Conversation 是聚合键:同一个会话的非穿透类消息合并成一条。留空表示不参与聚合。
Conversation string
// Title 是会话名;Sender 是发送者(与会话名相同时只写一个)。
Title string
Sender string
// Preview 是预览正文(已折成一行并截断);ShowPreview 为假时报文里不会出现它。
Preview string
ShowPreview bool
// Penetrate 为真表示穿透类:优先级 4、立即推送、不聚合。
Penetrate bool
// DeepLink 是站内路径(以 / 开头),拼到「点击打开的地址」后面。
DeepLink string
}
EventInfo 是新消息类推送要用到的字段。纯数据:由接线处(api)把通知闸的事件翻译成它, ntfy 因此仍然只依赖标准库与 model。
type ExceptionInfo ¶ added in v2.1.0
type ExceptionInfo struct {
// Kind 是表里的异常类型:KindAgentError / KindAgentStalled / KindHostOffline / KindSecurityAlert。
Kind string
// Sub 是细分,见上面的 Sub* 常量;可空。
Sub string
// Key 标识「同一件事」:同一个 Key 在去重窗口(10 分钟)内只推一次,期间重复发生的次数合并进下一条。
Key string
// Name 是对象的名字:Agent 所在项目的名字、主机的显示名;安全告警留空。
Name string
// Host 是 Agent 所在主机的显示名;没解析出来就留空——推送里宁可少一行,也不拿机器码凑数。
Host string
// Reason 是一句人话的原因;调用方保证里面没有终端内容、命令与任何凭据。
Reason string
// Since 是异常的起点(卡住 / 掉线开始的时间、出错发生的时间);零值表示不详。
Since time.Time
// DeepLink 是站内路径(以 / 开头),拼到「点击打开的地址」后面;可空。
DeepLink string
}
ExceptionInfo 是一条异常推送要用到的字段。纯数据:由接线处(api)翻译好交来,ntfy 因此仍只依赖标准库与 model。
type KindInfo ¶ added in v2.1.0
type KindInfo struct {
ID string `json:"id"`
Group string `json:"group"`
// Label 是一句话的名字;Desc 说明它什么时候会推送。
Label string `json:"label"`
Desc string `json:"desc"`
// DefaultOn 为假表示这一类默认不推送(异常类),此时 DefaultPriority 没有意义。
DefaultOn bool `json:"default_on"`
// DefaultPriority 是内置默认优先级 1~5;0 表示跟随「默认优先级」(Config.Priority)。
DefaultPriority int `json:"default_priority"`
// CapNormal 为真表示跟随默认优先级时最多按 3(顺利完成的长任务不是紧急事)。
CapNormal bool `json:"cap_normal,omitempty"`
// SuggestedPriority 是默认不推送的类型被打开时,界面建议用的优先级。
SuggestedPriority int `json:"suggested_priority,omitempty"`
}
KindInfo 描述表里的一行:它是什么、内置默认是什么。运行时取值与设置页展示用的是同一份, 界面里不另存默认值,免得两边悄悄漂移。
type Message ¶
Message 是一条要推送的内容。
func BuildAutoResumeMessage ¶ added in v2.1.0
func BuildAutoResumeMessage(cfg Config, in AutoResumeInfo, host string, merged int) Message
BuildAutoResumeMessage 生成「不再自动续跑」的推送内容。host 是主机的显示名(没解析出来就传空串); merged 是此前因限流而没发出去的通知条数。
func BuildEventMessage ¶
BuildEventMessage 生成新消息类的推送内容。count 是这一条代表的消息数(聚合后大于 1); merged 是此前因全局限流而没发出去的通知条数,大于 0 时在末尾说明一下。
func BuildExceptionMessage ¶ added in v2.1.0
func BuildExceptionMessage(cfg Config, in ExceptionInfo, repeats, merged int, now time.Time) Message
BuildExceptionMessage 生成异常的推送内容。repeats 是上一条同类推送之后又发生的次数; merged 是此前因全局限流而没发出去的通知条数;now 用来把起点写成「已持续多久」。
func BuildKindTestMessage ¶ added in v2.1.0
BuildKindTestMessage 生成「试发这一类」的测试推送:用这一类此刻要用的优先级发,正文里写明是哪一类、 用了几级——让人在手机上直接看到这一级是什么效果,再回来决定要不要改。kind 不认识时退回普通测试推送。 返回值的第二项是实际用的优先级(界面据此告诉用户「已按 N 级发出」)。
func BuildRequestMessage ¶
func BuildRequestMessage(cfg Config, in RequestInfo, merged int) Message
BuildRequestMessage 生成「新反馈请求」的推送内容。 merged 是此前因限流而没发出去的请求条数,大于 0 时在末尾说明一下,免得你以为只有这一条。
func BuildRunMessage ¶
BuildRunMessage 生成「模型运行结束」的推送内容。 host 是主机的显示名(没解析出来就传空串,推送里干脆不写主机,也不会拿机器码凑数); merged 是此前因限流而没发出去的通知条数,大于 0 时在末尾说明一下。
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier 把「新反馈请求」「模型运行结束」「不再自动续跑」与新消息类事件异步推送到 ntfy。 NotifyRequest / NotifyRun / NotifyAutoResume / NotifyEvent 永远不会阻塞调用方,推送失败或 ntfy 变慢也不会影响智能体的请求,更不会影响命令运行的收尾与自动续跑的下一轮判断。
func (*Notifier) EffectiveConfig ¶
EffectiveConfig 读取已保存的配置,并让环境变量里的令牌盖过去。
func (*Notifier) NotifyAutoResume ¶ added in v2.1.0
func (n *Notifier) NotifyAutoResume(in AutoResumeInfo)
NotifyAutoResume 登记一条「不再自动续跑」事件(#151)。立即返回;事件当场复制。 「同一次放弃只推一次」由自动续跑的登记保证,这里的去重(按 Key)只是进程内的第二道保险。
func (*Notifier) NotifyEvent ¶
NotifyEvent 登记一条新消息类事件。立即返回;事件当场复制,调用方之后随便改它。
func (*Notifier) NotifyException ¶ added in v2.1.0
func (n *Notifier) NotifyException(in ExceptionInfo)
NotifyException 登记一条异常。立即返回;事件当场复制。 这一类没打开时会在队列另一头被静默丢掉,调用方不必(也不该)自己判断开关。
func (*Notifier) NotifyRequest ¶
func (n *Notifier) NotifyRequest(s *model.FeedbackSession)
NotifyRequest 登记一条「智能体在等你回复」的事件。立即返回;会话内容当场复制,调用方之后随便改它。
func (*Notifier) NotifyRun ¶
NotifyRun 登记一条「模型运行结束」的事件。立即返回;事件当场复制,调用方之后随便改它。 要不要推送由配置决定(见 RunInfo.WorthNotifying),这里只挡掉一定不会推送的那一大批。
func (*Notifier) SendKindTest ¶ added in v2.1.0
SendKindTest 是「试发这一类」:kind 为空(或不认识)就是普通测试推送,否则按这一类此刻的优先级发一条, 正文写明是哪一类、几级。返回实际用的优先级,界面据此告诉用户。其余与 SendTest 相同(不排队、不限流、不看总开关)。
func (*Notifier) SendTest ¶
SendTest 用给定配置立刻发一条测试推送(不排队、不限流、不看总开关),并记入「最近一次推送」。 只试一次、不重试:人在界面上等着看结果,要的是马上知道通不通,而不是后台悄悄再试几轮。
type Options ¶
type Options struct {
// Load 读取已保存的配置;必填。每条事件现读一次(主键查询,很便宜),所以界面上一保存就立即生效。
Load func(ctx context.Context) (Config, error)
// StillPending 供延迟推送在真正发出前复核:这条请求是否仍在等人回复。nil 表示总是需要推送。
StillPending func(ctx context.Context, sessionID string) bool
// HostName 把机器码解析成主机的显示名,只在「运行结束」真要推送时才调用(不推送的短命令不会去查库)。
// nil 或返回空串都表示「不写主机」——推送里宁可少一行,也不拿机器码凑数。
HostName func(ctx context.Context, machineCode string) string
// EnvToken 是环境变量里的访问令牌,非空时盖过已保存的令牌。
EnvToken string
// Sender 为 nil 时用默认发送器。
Sender *Sender
}
Options 是 Notifier 的依赖。
type PublicConfig ¶
type PublicConfig struct {
Enabled bool `json:"enabled"`
Server string `json:"server"`
Topic string `json:"topic"`
Username string `json:"username"`
ClickURL string `json:"click_url"`
Priority int `json:"priority"`
IncludeSummary bool `json:"include_summary"`
DelaySeconds int `json:"delay_seconds"`
RunNotify bool `json:"run_notify"`
RunMinSeconds int `json:"run_min_seconds"`
// PriorityByKind 永远是对象(没有覆盖时是 {}):界面据此判断哪些行用了默认。
PriorityByKind map[string]int `json:"priority_by_kind"`
TokenSet bool `json:"token_set"`
PasswordSet bool `json:"password_set"`
// TokenFromEnv 为真时令牌来自环境变量 RELAYMESH_NTFY_TOKEN,界面里改不了也清不掉。
TokenFromEnv bool `json:"token_from_env"`
}
PublicConfig 是返回给浏览器的视图:凭据一律只给「是否已设置」,不给值。
type RequestInfo ¶
type RequestInfo struct {
SessionID string
WorkflowID string
Title string
Summary string
ProjectDirectory string
HostName string
}
RequestInfo 是「新反馈请求」推送要用到的字段。 取快照而不是持有会话指针:推送在别的协程里异步完成,而会话对象随后还会被修改。
func InfoFromSession ¶
func InfoFromSession(s *model.FeedbackSession) RequestInfo
InfoFromSession 复制出推送需要的字段。
type RunInfo ¶
type RunInfo struct {
RunID string
// State 是运行的终态,取值见 model.Run*。
State string
// Machine 是机器码;主机的显示名由接线处在真正发送前解析(见 Options.HostName),免得短命令也去查库。
Machine string
// Description 是模型写的一句话说明;Command 是脱敏后的命令文本。
Description string
Command string
ExitCode *int
Signal string
// Why 是终态原因的中文说明(如「主机重启,进程已丢失」),没有就空着。
Why string
// Duration 是命令实际运行的时长(不含等批准的时间);没跑起来的运行为 0。
Duration time.Duration
WorkflowID string
ProjectDirectory string
// CancelBy 是请求取消这次运行的来源(user / pause / revoked / system / model);空表示没有任何人要求取消。
CancelBy string
}
RunInfo 是一次模型运行结束时推送要用到的字段。 取快照而不是持有运行记录:推送在别的协程里异步完成。它是纯数据,不依赖终端包—— 由接线处(api)把终端的运行结束事件翻译成它,ntfy 因此始终是只依赖标准库与 model 的叶子包。
func (RunInfo) WorthNotifying ¶
WorthNotifying 判断这次运行结束要不要推送(总开关、主题等由 Notifier 另行检查)。
推送:成功、失败、超时、结果丢失,以及「没人要求取消、却被中断」(典型是主机上的守护进程停了或重启, 长任务因此被杀——这正是离开电脑的人最需要知道的)。 不推送:你或模型自己取消的(你已经知道了);被拒绝或被闸门拒绝的(根本没运行);运行得比门槛更短的。
type SendError ¶
type SendError struct {
// Status 是 HTTP 状态码;还没连上服务时为 0。
Status int
Msg string
Retryable bool
RetryAfter time.Duration
}
SendError 描述一次推送为什么失败:Msg 面向用户且已抹掉凭据;Retryable 说明值不值得再试一次。
type Sender ¶
type Sender struct {
// Backoff 是相邻两次尝试之间的等待;长度决定最多重试几次(总尝试数 = len(Backoff)+1)。
Backoff []time.Duration
// contains filtered or unexported fields
}
Sender 负责一次推送的 HTTP 细节。零值不可用,请用 NewSender。
type Status ¶
type Status struct {
LastAttemptAt *time.Time `json:"last_attempt_at,omitempty"`
LastOK bool `json:"last_ok"`
LastTest bool `json:"last_test"` // 最近一次是不是「测试推送」
LastHTTPStatus int `json:"last_http_status,omitempty"`
LastError string `json:"last_error,omitempty"`
Sent int `json:"sent"`
Failed int `json:"failed"`
// Dropped 是被限流合并或因队列已满而没发出的条数。
Dropped int `json:"dropped"`
}
Status 是自进程启动以来的推送情况(只在内存里,重启清零)。
type Update ¶
type Update struct {
Enabled bool `json:"enabled"`
Server string `json:"server"`
Topic string `json:"topic"`
Username string `json:"username"`
ClickURL string `json:"click_url"`
Priority int `json:"priority"`
IncludeSummary bool `json:"include_summary"`
DelaySeconds int `json:"delay_seconds"`
RunNotify bool `json:"run_notify"`
RunMinSeconds int `json:"run_min_seconds"`
// PriorityByKind 整张替换「各类消息的优先级」覆盖表;没带这个字段(nil)表示保持原样——
// 页面是旧版本缓存、或者别的客户端只改了其他项时,不会把已设好的表悄悄清掉。要清空就发 {}。
PriorityByKind map[string]int `json:"priority_by_kind"`
Token string `json:"token"`
ClearToken bool `json:"clear_token"`
Password string `json:"password"`
ClearPassword bool `json:"clear_password"`
}
Update 是界面保存时提交的整张表单:非凭据字段整体替换;凭据「只写不读」—— 留空表示保持原值,要换就填新值,要清掉就带上对应的 clear_ 标记。