Documentation
¶
Overview ¶
Package notify 是统一通知闸的核心:所有「要不要打扰你」的判断都在这里做一次。
本包只有纯逻辑(事件、偏好、决策)与一个很薄的 Gate(见 gate.go):它不依赖数据库、不依赖 ntfy, 也不关心浏览器怎么呈现——「值不值得通知你」由服务端决定,「在这台设备上怎么弹」由浏览器决定。 设计依据:#111 设计稿 07-notifications。
Index ¶
Constants ¶
const (
// MaxConversations 是会话级偏好条目的上限:偏好存在一个 JSON 值里,不能无限长大。
MaxConversations = 500
)
const (
// MaxPreviewRunes 是预览的最大字数(设计 §7:≤ 120 字)。
MaxPreviewRunes = 120
)
各字段的长度上限(按字符数)。
const SSEEventName = "notify"
SSEEventName 是通知闸向浏览器广播的 SSE 事件名;载荷见 Payload。
Variables ¶
var ErrInvalidPrefs = errors.New("通知偏好无效")
ErrInvalidPrefs 表示偏好内容不合法(数值越界、策略未知等)。
Functions ¶
func ConversationOf ¶
ConversationOf 返回 1:1 会话(按工作流)的会话 id。
func Excerpt ¶
Excerpt 取 Markdown 开头的一小段纯文本作为预览:最多取前 6 个非空行,折成一行,并按 MaxPreviewRunes 截断。 结果仍会在 Event.Normalize 里再规整一次,所以这里只负责「去掉标记」。
func ValidConversation ¶
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 是闸对一条事件的裁决。
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 至多通知一次。
type Gate ¶
type Gate struct {
// contains filtered or unexported fields
}
Gate 是统一通知闸:Publish 一条事件,它做幂等、按偏好决策,再分发到浏览器(SSE)与 ntfy 两条互不影响的通道。 任何一条通道出岔子(包括 panic)都不会传到调用方——通知永远不能拖垮发出它的那次工具调用。
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" // 卡住 / 出错 / 唤醒预算耗尽 // 受约束类:免打扰与会话策略都能让它安静。 KindAgentText Kind = "agent_text" // Agent 主动发的文本:notice、chat send、群文本 KindAskCard Kind = "ask_card" // async_ask 带默认值的提问 / 授权卡 KindRunEnd Kind = "run_end" // ExecMesh 运行结束(只有 ntfy 通道) // 永不通知:任务 / 进展更新与系统行只在界面里体现。 KindTaskUpdate Kind = "task_update" KindSystemEvent Kind = "system_event" )
func EffectiveKind ¶
EffectiveKind 返回事件实际生效的种类:点名了你的 agent_text 升格为 mention。
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)。
type Policy ¶
type Policy string
Policy 是某个会话的通知策略。
func DefaultPolicy ¶
DefaultPolicy 是会话没有显式设置时的策略:群只在被 @ 时通知,其余(1:1)全部通知。
type Prefs ¶
type Prefs struct {
DND bool `json:"dnd"`
NtfyPreview PreviewMode `json:"ntfy_preview"`
Conversations map[string]ConvPref `json:"conversations,omitempty"`
}
Prefs 是全部通知偏好。零值就是「出厂默认」:免打扰关、预览 auto、没有任何会话级设置。
func (Prefs) Normalize ¶
Normalize 返回规整后的副本(不改动接收者):补默认预览模式;丢掉非法条目、已过期的静音、 以及与默认策略相同且没有期限的冗余条目;muted 以外的策略不带期限。
func (Prefs) ShowPreview ¶
ShowPreview 报告 ntfy 的新消息类推送里能不能带预览正文。 老三类(阻塞待答 / 守护告警 / 运行结束)不看这里,仍由 ntfy 配置里的「附带摘要」决定。
type PreviewMode ¶
type PreviewMode string
PreviewMode 决定 ntfy 新消息类的推送里要不要带预览正文。
const ( PreviewAuto PreviewMode = "auto" // 默认:1:1 显示,跨项目群隐藏 PreviewAlways PreviewMode = "always" // 一律显示 PreviewNever PreviewMode = "never" // 一律隐藏,只写「有新消息」 )
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" // 会话只在被 @ 时通知,而这条没有 @ )