mcpField
S
sending-notifications

sending-notifications

github.com/posthog开发40.5k171 次安装今天更新
代码仓库

关于 sending-notifications

面向 PostHog 功能开发者的实时通知技能，介绍通过统一 facade 创建通知、设置接收对象和优先级，并说明访问控制与投递流程。

主要功能

  1. 01通过统一接口创建通知
  2. 02配置目标、资源与优先级
  3. 03按资源访问权限筛选接收者
  4. 04说明实时通知投递链路
  5. 05提供新增通知类型步骤

适用场景

  1. 01用户被评论提及时发送通知
  2. 02告警阈值触发时通知相关人员
  3. 03审批请求或结果变化时通知
  4. 04数据管道失败时发送通知

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/posthog --skill sending-notifications

安装后在 Claude Code 中输入/sending-notifications确认已加载。

详细介绍

发送实时通知

何时使用

你正在为某个 PostHog 功能添加通知支持——例如，当用户在评论中被提及时、当告警触发时，或当有人请求审批时，向该用户发送通知。

Facade API

所有通知的创建都通过一个函数完成。请从 facade 导入，而不是从内部模块导入：

from products.notifications.backend.facade.api import (
    create_notification,
    NotificationData,
    NotificationType,
    Priority,
    TargetType,
)

构建一个 NotificationData 并调用 create_notification：

event = create_notification(
    NotificationData(
        team_id=team.id,
        notification_type=NotificationType.ALERT_FIRING,
        priority=Priority.CRITICAL,
        title="Event ingestion latency > 30s",
        body="Events are queuing up. Ingestion pipeline is degraded.",
        target_type=TargetType.USER,
        target_id=str(user.id),
        resource_type="dashboard",
        resource_id="42",
        source_url="/dashboard/42",
    )
)

成功时返回一个 NotificationEvent，如果该功能开关已禁用、未解析出任何接收者，或该团队不存在，则返回 None。在任何上下文中调用都是安全的。

NotificationData 字段

必填：

字段类型描述
team_idint团队上下文——用于查找组织并检查功能开关
notification_typeNotificationType决定 UI 中的图标
titlestr通知标题（建议约 100 个字符）
bodystr展开时显示的较长描述。可以是空字符串
target_typeTargetType谁接收此通知：user、team、organization 或 role
target_idstr目标的 ID（用户 ID、团队 ID、组织 UUID 或以字符串表示的角色 UUID）

可选：

字段类型默认值描述
resource_typeNotificationResourceType | NoneNone受访问控制的类型（例如 "dashboard"）会自动过滤掉没有查看权限的接收者
resource_idstr""用于链接的资源的 ID
source_urlstr""相对 URL 路径（例如 /dashboard/42），在 UI 中显示为链接图标
priorityPriorityNORMALnormal = 仅弹出框；critical = 弹出框 + 持久 toast
archivableboolFalse选择启用按接收者的“归档”（忽略）操作，该操作会将通知移动到接收者的“已归档”标签页。当为 False 时，接收者只能将其标记为已读/未读（默认模式）
resolverRecipientsResolver | NoneNone自定义接收者解析器。默认处理 user/team/org/role 定位

选择参数

通知类型
类型使用场景
comment_mention用户在评论或讨论中被 @ 提及
alert_firing监控告警阈值被突破
approval_requested某项变更需要用户审批
approval_resolved用户请求的审批已解决
pipeline_failure数据管道或批量导出失败
issue_assigned错误跟踪 issue 被分配给了该用户
优先级

使用 critical 时务必非常谨慎。 它会触发一个持续显示、覆盖用户屏幕的 toast 弹窗，且必须手动关闭。这是刻意设计的侵入性行为——请将其保留给真正的紧急情况，例如服务中断、安全告警或 SLA 违约。滥用 critical 会让用户逐渐完全忽略通知。如有疑问，请使用 normal。

目标类型
目标target_id 值接收者
user用户 ID仅该用户
team团队 ID该团队所属组织的所有成员
organization组织 ID所有组织成员
role角色 ID所有拥有该 RBAC 角色的用户
资源类型与访问控制

当 resource_type 匹配一个受访问控制的资源（dashboard、feature_flag、experiment 等）时，不具备 viewer 访问权限的接收者会被自动排除。对于仅通知类型（pipeline、approval、comment），不应用任何 AC 过滤。

投递管道

Django (create_notification)
  → Postgres (NotificationEvent row)
  → Kafka (notification_events topic, on transaction commit)
  → Go livestream service (Kafka consumer)
  → Redis SPUBLISH (sharded pub/sub, keyed by org ID)
  → SSE (/notifications endpoint)
  → Browser (popover + optional toast)

Kafka 发布发生在 transaction.on_commit 上——如果事务回滚则不会触发。

添加新的通知类型

  1. 在 products/notifications/backend/facade/enums.py 中添加枚举值
  2. 在 frontend/src/lib/components/NotificationsMenu/notificationToasts.tsx 中添加图标映射（NOTIFICATION_TYPE_ICONS）——这是唯一的图标来源，由 getNotificationIcon 读取，而只有 NotificationRow 会调用它；侧边面板通过渲染该行来获取图标
  3. 在 frontend/src/lib/components/NotificationsMenu/NotificationRow.tsx 中添加标签 + 描述条目（REALTIME_NOTIFICATION_TYPE_META）——驱动按类型划分的通知偏好设置 UI
  4. 运行 python manage.py makemigrations notifications

测试

在测试中 mock 该 feature flag：

from unittest.mock import patch

with patch("posthoganalytics.feature_enabled", side_effect=lambda flag, *a, **kw: flag == "real-time-notifications"):
    event = create_notification(data)

评论

支持 Markdown