notify

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package notify 是统一通知闸的核心:所有「要不要打扰你」的判断都在这里做一次。

本包只有纯逻辑(事件、偏好、决策)与一个很薄的 Gate(见 gate.go):它不依赖数据库、不依赖 ntfy, 也不关心浏览器怎么呈现——「值不值得通知你」由服务端决定,「在这台设备上怎么弹」由浏览器决定。 设计依据:#111 设计稿 07-notifications。

Index

Constants

View Source
const (
	BoardStaleDefaultMinutes = 120
	BoardStaleMinMinutes     = 30
	BoardStaleMaxMinutes     = 24 * 60
)

「指派久无人接」的阈值范围(#180 B3d):指派派出后超过这么久还没人接取,就算「久无人接」—— 回执头 board: 行、任务页上「已等多久」转红、以及给用户的一次性提醒都按它算。

View Source
const (
	// MaxConversations 是会话级偏好条目的上限:偏好存在一个 JSON 值里,不能无限长大。
	MaxConversations = 500
)
View Source
const (
	// MaxPreviewRunes 是预览的最大字数(设计 §7:≤ 120 字)。
	MaxPreviewRunes = 120
)

各字段的长度上限(按字符数)。

View Source
const SSEEventName = "notify"

SSEEventName 是通知闸向浏览器广播的 SSE 事件名;载荷见 Payload。

Variables

View Source
var ErrInvalidPrefs = errors.New("通知偏好无效")

ErrInvalidPrefs 表示偏好内容不合法(数值越界、策略未知等)。

Functions

func ConversationOf

func ConversationOf(workflowID string) string

ConversationOf 返回 1:1 会话(按工作流)的会话 id。

func Excerpt

func Excerpt(markdown string) string

Excerpt 取 Markdown 开头的一小段纯文本作为预览:最多取前 6 个非空行,折成一行,并按 MaxPreviewRunes 截断。 结果仍会在 Event.Normalize 里再规整一次,所以这里只负责「去掉标记」。

func ValidBoardStaleMinutes added in v2.1.0

func ValidBoardStaleMinutes(m int) bool

ValidBoardStaleMinutes 报告用户提交的阈值是否可以接受:0(恢复默认)或 30~1440 分钟。

func ValidConversation

func ValidConversation(id string) bool

ValidConversation 检查会话 id 的形状:wf:<工作流> 或 grp:<群>,标识非空、不含控制字符、长度有限。

Types

type ConvPref

type ConvPref struct {
	Policy     Policy     `json:"policy"`
	MutedUntil *time.Time `json:"muted_until,omitempty"`
}

ConvPref 是一个会话的偏好。MutedUntil 只对 muted 有意义:到点之后静音自动失效,回到默认策略。

type Decision

type Decision struct {
	Kind      Kind   `json:"kind"`      // 实际生效的种类(agent_text 且点名了你时升格为 mention)
	Browser   bool   `json:"browser"`   // 发 SSE notify 给浏览器
	Ntfy      bool   `json:"ntfy"`      // 交给 ntfy 推送器
	Sound     bool   `json:"sound"`     // 浏览器可以响提示音(还要看本机开关)
	Badge     bool   `json:"badge"`     // 计入标题角标的未读数
	Penetrate bool   `json:"penetrate"` // 穿透类:浏览器侧也不做前台抑制
	Preview   bool   `json:"preview"`   // ntfy 新消息类报文能带预览正文
	Reason    Reason `json:"reason"`
}

Decision 是闸对一条事件的裁决。

func Decide

func Decide(ev Event, p Prefs, now time.Time) Decision

Decide 是闸里唯一的决策函数(纯函数)。顺序即设计稿 §5:

① 种类是否永不通知 / 是否穿透类 → 穿透类直接通知,不看任何偏好;
② 否则看免打扰;
③ 再看会话级策略(muted / mentions 抑制,all 放行)。

前台抑制与合并限速在两条通道各自的下游(浏览器 notifyBus、ntfy 聚合),不在这里。 Mention=true 的 agent_text 视同 mention(点名你,穿透);其余种类忽略 Mention。

func (Decision) Delivered

func (d Decision) Delivered() bool

Delivered 报告至少有一个通道要通知。

type Event

type Event struct {
	ID           string    `json:"id"`
	Kind         Kind      `json:"kind"`
	Conversation string    `json:"conversation"`            // 1:1 = "wf:<workflow_id>",群 = "grp:<id>"
	WorkflowID   string    `json:"workflow_id,omitempty"`   // 深链 / 回执定位用
	SessionID    string    `json:"session_id,omitempty"`    // 深链定位到具体那条
	Sender       string    `json:"sender,omitempty"`        // 发送者显示名(Agent 身份标签)
	Title        string    `json:"title,omitempty"`         // 会话名(项目名 / 群名)
	Mention      bool      `json:"mention,omitempty"`       // 这条消息点名了你(对 agent_text 生效,等同 mention)
	Preview      string    `json:"preview,omitempty"`       // 预览正文(已折成一行并截断)
	DeepLink     string    `json:"deep_link,omitempty"`     // 站内路径(以 / 开头),点击通知时打开
	CrossProject bool      `json:"cross_project,omitempty"` // 来自跨项目的群:ntfy 默认隐藏预览
	CreatedAt    time.Time `json:"created_at"`
}

Event 是一条要交给闸的通知。ID 全局唯一,是幂等键:同一个 ID 至多通知一次。

func (Event) Normalize

func (e Event) Normalize(now time.Time) Event

Normalize 返回规整后的事件:文本字段折成一行并按字符数截断,深链只接受站内路径,缺省字段补齐。 它不改 ID 与 Kind(它们由调用方保证,见 Valid)。

func (Event) Valid

func (e Event) Valid() bool

Valid 检查事件是否可以进闸:必须有 ID 与已登记的 Kind。

type Gate

type Gate struct {
	// contains filtered or unexported fields
}

Gate 是统一通知闸:Publish 一条事件,它做幂等、按偏好决策,再分发到浏览器(SSE)与 ntfy 两条互不影响的通道。 任何一条通道出岔子(包括 panic)都不会传到调用方——通知永远不能拖垮发出它的那次工具调用。

func NewGate

func NewGate(opts Options) *Gate

NewGate 创建通知闸。

func (*Gate) Publish

func (g *Gate) Publish(ev Event, ntfy func(Event, Decision)) Decision

Publish 处理一条事件并返回裁决。ntfy 是 ntfy 通道的投递回调:只有裁决要求推 ntfy 时才会被调用, 调用方在里面把事件交给 ntfy 推送器(它必须立即返回);传 nil 表示这个来源没有 ntfy 通道。 内容(预览等)不会写进日志,日志里只有种类与原因。

type Kind

type Kind string

Kind 是通知的种类,决定它是否穿透免打扰 / 会话静音,以及走哪些通道。

const (
	// 穿透类:没有你就停在那里,或点名找你,不受任何免打扰 / 静音影响。
	KindBlockingFeedback Kind = "blocking_feedback" // interactive_feedback 阻塞等你
	KindMention          Kind = "mention"           // 群里 @你 / @all(N-2:@all 也穿透)
	KindApprovalWaiting  Kind = "approval_waiting"  // 托管终端等你批准
	KindGuardAlert       Kind = "guard_alert"       // 不再自动续跑(#151)/ 群聊过密;取值沿用历史名(原「终端会话守护告警」)

	// 受约束类:免打扰与会话策略都能让它安静。
	KindAgentText Kind = "agent_text" // Agent 主动发的文本:notice、chat send、群文本
	KindAskCard   Kind = "ask_card"   // async_ask 带默认值的提问 / 授权卡
	KindRunEnd    Kind = "run_end"    // ExecMesh 运行结束(只有 ntfy 通道)
	// KindBoardStale 是共享任务板上「指派派出后很久没人接」的一次性提醒(#180 B3d):给用户看的,不属于任何会话。
	// 受免打扰约束;ntfy 通道默认不推(在「各类消息的优先级」里打开才推)。
	KindBoardStale Kind = "board_stale"

	// 永不通知:任务 / 进展更新与系统行只在界面里体现。
	KindTaskUpdate  Kind = "task_update"
	KindSystemEvent Kind = "system_event"
)

func EffectiveKind

func EffectiveKind(ev Event) Kind

EffectiveKind 返回事件实际生效的种类:点名了你的 agent_text 升格为 mention。

func (Kind) Known

func (k Kind) Known() bool

Known 报告 k 是不是已登记的种类。

func (Kind) Penetrates

func (k Kind) Penetrates() bool

Penetrates 报告 k 是否属于穿透类。

type Options

type Options struct {
	// Load 读取当前偏好;必填。每条事件现读一次(主键查询,很便宜),偏好一保存就立即生效。
	// 读取失败时按出厂默认决策——宁可多通知,也不因为读不出偏好就把关键通知吞掉。
	Load func(ctx context.Context) (Prefs, error)
	// Broadcast 把 SSE 事件推给所有浏览器;nil 表示不发浏览器通道。
	Broadcast func(eventType string, data any)
	// Now 只为测试存在:替换时钟。
	Now func() time.Time
}

Options 是 Gate 的依赖。

type Payload

type Payload struct {
	ID           string    `json:"id"`
	Kind         Kind      `json:"kind"`
	Conversation string    `json:"conversation"`
	WorkflowID   string    `json:"workflow_id,omitempty"`
	SessionID    string    `json:"session_id,omitempty"`
	Sender       string    `json:"sender,omitempty"`
	Title        string    `json:"title,omitempty"`
	Preview      string    `json:"preview,omitempty"`
	DeepLink     string    `json:"deep_link,omitempty"`
	Mention      bool      `json:"mention,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	Penetrate    bool      `json:"penetrate"` // 穿透类:浏览器侧也不做前台抑制
	Sound        bool      `json:"sound"`
	Badge        bool      `json:"badge"`
}

Payload 是 SSE notify 事件的载荷:事件本身加上闸的裁决。 Kind 是实际生效的种类(点名了你的 agent_text 已升格为 mention)。

func PayloadOf

func PayloadOf(ev Event, d Decision) Payload

PayloadOf 组装 SSE 载荷。

type Policy

type Policy string

Policy 是某个会话的通知策略。

const (
	PolicyAll      Policy = "all"      // 全部通知(1:1 默认)
	PolicyMentions Policy = "mentions" // 只在被 @ 时通知(群默认)
	PolicyMuted    Policy = "muted"    // 静音:只有穿透类能到达
)

func DefaultPolicy

func DefaultPolicy(conversation string) Policy

DefaultPolicy 是会话没有显式设置时的策略:群只在被 @ 时通知,其余(1:1)全部通知。

func (Policy) Valid

func (p Policy) Valid() bool

Valid 报告 p 是不是已登记的策略。

type Prefs

type Prefs struct {
	DND         bool        `json:"dnd"`
	NtfyPreview PreviewMode `json:"ntfy_preview"`
	// BoardStaleOff 为真表示不再发「指派久无人接」的提醒(网页与 ntfy 都不发;阈值本身仍然生效)。
	// 取反存放,是为了让「没有这个字段的旧偏好」自然落在出厂默认(提醒开)上。
	BoardStaleOff bool `json:"board_stale_off,omitempty"`
	// BoardStaleMinutes 是「久无人接」的阈值(分钟,30~1440);0 = 没设置过,按默认 120。
	// 存「用户选的值」而不是「生效的值」,这样以后调整默认值时,没改过的人跟着走,不会冻结在旧值上。
	BoardStaleMinutes int                 `json:"board_stale_minutes,omitempty"`
	Conversations     map[string]ConvPref `json:"conversations,omitempty"`
}

Prefs 是全部通知偏好。零值就是「出厂默认」:免打扰关、预览 auto、没有任何会话级设置、 「指派久无人接」提醒开且阈值 2 小时。

func (Prefs) BoardStaleAfter added in v2.1.0

func (p Prefs) BoardStaleAfter() time.Duration

BoardStaleAfter 返回生效的「久无人接」阈值。

func (Prefs) BoardStaleAfterMinutes added in v2.1.0

func (p Prefs) BoardStaleAfterMinutes() int

BoardStaleAfterMinutes 返回生效的「久无人接」阈值(分钟):没设置过的按默认。

func (Prefs) Normalize

func (p Prefs) Normalize(now time.Time) Prefs

Normalize 返回规整后的副本(不改动接收者):补默认预览模式;丢掉非法条目、已过期的静音、 以及与默认策略相同且没有期限的冗余条目;muted 以外的策略不带期限。

func (Prefs) PolicyFor

func (p Prefs) PolicyFor(conversation string, now time.Time) Policy

PolicyFor 返回会话当前生效的策略:显式设置优先;过期的静音视为没有设置。

func (Prefs) ShowPreview

func (p Prefs) ShowPreview(ev Event) bool

ShowPreview 报告 ntfy 的新消息类推送里能不能带预览正文。 老三类(阻塞待答 / 守护告警 / 运行结束)不看这里,仍由 ntfy 配置里的「附带摘要」决定。

func (Prefs) Validate

func (p Prefs) Validate() error

Validate 检查(已规整的)偏好是否在允许的范围内。

type PreviewMode

type PreviewMode string

PreviewMode 决定 ntfy 新消息类的推送里要不要带预览正文。

const (
	PreviewAuto   PreviewMode = "auto"   // 默认:1:1 显示,跨项目群隐藏
	PreviewAlways PreviewMode = "always" // 一律显示
	PreviewNever  PreviewMode = "never"  // 一律隐藏,只写「有新消息」
)

func (PreviewMode) Valid

func (m PreviewMode) Valid() bool

Valid 报告 m 是不是已登记的模式。

type Reason

type Reason string

Reason 说明一次决策为什么是这个结果,供测试断言与排查(不会展示给用户)。

const (
	ReasonPenetrate    Reason = "penetrate"     // 穿透类,直接通知
	ReasonDelivered    Reason = "delivered"     // 受约束类,偏好放行
	ReasonNever        Reason = "never"         // 永不通知的种类
	ReasonUnknownKind  Reason = "unknown_kind"  // 未登记的种类:不通知
	ReasonDND          Reason = "dnd"           // 被免打扰挡下
	ReasonMuted        Reason = "muted"         // 会话静音
	ReasonMentionsOnly Reason = "mentions_only" // 会话只在被 @ 时通知,而这条没有 @
)
const (
	ReasonInvalid   Reason = "invalid"   // 事件缺 ID 或种类未登记
	ReasonDuplicate Reason = "duplicate" // 同一个 ID 已经处理过
)

闸自己给出的两种「没有通知」的原因(决策函数里的原因见 decide.go)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL