Cue

代码审查 Agent、日志分类 Agent 和账单 Agent 都可能在凌晨 2 点通知同一位工程师。LangGraph 的 interrupt() 或 Slack 的批准按钮可以暂停某个 Agent；但它们都不知道其他 Agent 已经发送了什么。Cue 位于所有这些 Agent 之前，充当出站把关器：

• 按 Agent、按个人设置预算。 每个 Agent 使用自己的密钥发送消息。其 frequency_caps 限制每个周期内可以向某人发送的消息数量，超出预算的消息 会以 suppressed 状态存储，原因为 agent_budget。类别上限则统计某人从所有发送方 收到的消息总数。
• 按个人所在时区设置静默时段。 在某人静默时段内到期的消息会等待，直到时段结束。 只有类别不可退订的 critical 消息可以突破限制；每个 Agent 的 max_importance 会限制其可声明的重要性级别，因此只有你信任的 Agent 才能使用 critical。
• 其余消息使用摘要。 摘要规则可将一系列 Agent 事件合并为每个时间窗口一条消息，或按本地时间每天发送一条。
• 对高风险消息进行审批。 匹配 Agent 的 approval 条件的消息会以 pending_approval 状态等待；审核者通过自己收到的通知中的一次性链接作出决定。Agent 密钥永远不能用于审批。
• 每种处理结果都有原因。 每条消息都有状态和 status_reason，每个事件都会记录匹配了哪些规则以及原因。Agent 可通过 HTTP、SDK 或 MCP 服务进行连接。

将其用作库

无需服务器：运行 pip install cue-notify，然后选择在进程内使用，并将状态保存在 SQLite 文件中。消息由你自己发送。

from cue_notify.embedded import Gate

gate = Gate("sqlite:///cue.db", quiet_hours=("22:00", "08:00"), caps={"marketing": [("P1D", 1)]})
decision = gate.check("user-42", category="marketing", timezone="Europe/Berlin", key="sale-42")
if decision.action == "send":
    print("sending now")
    gate.sent(decision)
else:
    print(decision.action, decision.at, decision.reason)
for due in gate.due():
    print("sending", due.key)
    gate.sent(due)

check() 会根据原因返回 send、defer（直到 decision.at）、suppress 或 digest；due() 会返回到期的延迟消息和摘要批次。每个人所在时区的静默时段、上限、冷却时间、按发送方设置的预算、摘要和幂等键，其工作方式与服务端一致；此模式不包含模板、渠道和偏好设置页面。请参阅将 Cue 用作库。

顶部的录屏展示了 examples/agents-demo：在检出代码后，运行 uv run python examples/agents-demo/demo.py，即可使用 SQLite 和控制台连接器运行示例。

快速开始

使用 Docker Compose（PostgreSQL、一个 API 和一个 worker；消息会写入 worker 的日志）：

git clone https://github.com/murtazox04/Cue && cd Cue
docker compose up --build -d
docker compose exec api cuectl keys create admin
docker compose logs -f worker

或者在虚拟环境中使用 Python 3.12+ 和 SQLite：

python -m venv .venv && . .venv/bin/activate
pip install cue-notify
export CUE_WORKER__EMBEDDED=true
export CUE_CHANNELS__PUSH__PROVIDER=console CUE_CHANNELS__SMS__PROVIDER=console
cuectl db upgrade && cuectl keys create admin && cuectl serve

keys create 会显示一次 API 密钥；请将其保存为 CUE_API_KEY。然后按照 入门指南创建模板和规则，并发送一个会出现在日志中的事件；再参阅 Agent，为 Agent 设置专属密钥 和限额。

使用 uv 即可尝试，无需安装任何内容：

CUE_WORKER__EMBEDDED=true CUE_CHANNELS__PUSH__PROVIDER=console \
  CUE_CHANNELS__SMS__PROVIDER=console uvx cue-notify serve --migrate

然后在同一目录中打开第二个终端（两者都使用 ./cue.db），运行 uvx cue-notify keys create admin。

面向 Agent 的更多功能

• Agent 作为发送方。 每个 Agent 都有自己的密钥，以及个人注意力预算、重要性上限，还可以按需设置任何消息发出前都必须经过人工审批。 Agent 密钥无法读取或更改用户的个人资料，也无法审批任何内容。请参阅 Agent。
• 先征求人工同意。 对于有风险的操作（退款、删除、群发邮件），Agent 会调用 POST /v1/approvals 或 request_approval MCP 工具。Cue 会通过一次性链接，在审核者各自的渠道通知他们，并将决定返回给 Agent；同时提供适用于 LangGraph、Pydantic AI、CrewAI Flows 和 Dapr Agents 的桥接。请参阅 审批请求。
• MCP 服务。 uvx cue-notify mcp 可为 Claude、Cursor 或你自己的 Agent 提供通知用户和查看投递情况的工具，并遵循相同的策略和审计记录。请参阅 AI Agent（MCP）。
• 筛查（可选，默认关闭，实验性功能）。 设置 [screening] enabled = true 并提供 TypeSafe API 密钥后，决策模型（Jev）会在发送前读取每条 Agent 消息：若发现施压、欺骗或泄露的机密，会暂缓发送并交由人工处理；若重要性被夸大，则会降低其重要性。此功能基于 TypeSafe 发布的 API 构建，尚未经过生产环境验证。你自己的后端发送的消息永远不会经过筛查。
• 编码 Agent。 cue-hook 可让 OpenHands 和 Claude Code 在任务完成或等待输入时通知你。请参阅编码 Agent。
• Claude Code 插件。 运行 /plugin marketplace add murtazox04/Cue，然后运行 /plugin install cue@cue，即可添加一项将 Cue 集成到应用程序中的技能。

来自你自己的后端的通知

同一套策略也适用于你产品自身的通知。你的后端报告发生了什么（order.shipped、payment.failed）。Cue 会判断是否值得发送通知，以用户所用的语言呈现通知，选择发送时间和渠道，然后将处理完成的消息交给你连接的投递服务：通过带签名的 webhook 使用你自己的发送服务，或使用捆绑的连接器。

• 规则和策略集中管理。 JSON Logic 规则会将事件映射到模板；无论消息由规则触发、直接发送还是广播，都要经过相同的检查：取消订阅、静音渠道、频率上限、冷却时间，以及按接收者所在时区设置的免打扰时段；发送前还会再次检查。
• 减少消息数量。 摘要会将一系列突发事件整合为每个时间窗口一条消息，或在每天本地时间发送一条消息；对于不再互动的用户，疲劳控制机制会逐步减少发送频率。
• 用户掌控。 提供托管的偏好设置页面（也可使用自有页面的 JSON API）、RFC 8058 一键取消订阅功能，以及记录每次变更的同意记录。
• 有据可查。 每个事件都会记录匹配的规则及原因；每条消息都会记录其状态，以及被抑制或发送失败的原因。

curl -X POST https://cue.example.com/v1/events \
  -H "Authorization: Bearer $CUE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "order.shipped", "recipient": "customer-42",
       "data": {"order_id": "1001"}, "idempotency_key": "order-1001-shipped"}'

然后，你的投递端点会收到一条已签名、完全渲染的消息：

{
  "id": "01a1…",
  "channel": "push",
  "address": "<device token>",
  "locale": "en",
  "importance": "normal",
  "expires_at": null,
  "content": {"title": "Your order is on its way", "body": "Order 1001 ships today.",
              "url": "https://shop.example/orders/1001"},
  "metadata": {"cue_message_id": "01a1…", "cue_tracking_token": "…"},
  "links": {"preferences": "https://cue.example.com/preferences/…"}
}

适用对象

适合这样的团队：其 Agent、后台任务或产品代码会向用户发送推送、电子邮件、短信或聊天消息，并希望将相关决策（是否发送、何时发送、发送频率、通过哪种渠道、使用哪种语言）集中在一处制定、存储并说明原因，同时运行在自己的基础设施上。

暂时不适合有以下需求的团队：

• 应用内收件箱或通知动态：已列入计划，但尚未实现；
• 管理界面：目前通过 HTTP API、命令行和 cue.toml 配置 Cue；
• Cue 尚不支持的连接器。目前支持 FCM、APNs、Twilio、SMTP、Amazon SES、Resend、Slack、Telegram、带签名的 webhook 和 console，也支持自行编写连接器；
• 托管服务：Cue 仅支持可自托管；
• 用于营销活动的可视化旅程构建器：暂无计划。

参见路线图。

自行选择发送方式

每个渠道（push、sms、email、ops-alerts……）都由一个连接器提供支持：

连接器	适用场景
webhook	你已有发送服务，或希望完全掌控发送过程。Cue 会向其发送带签名的 JSON POST 请求。
fcm、twilio、smtp、telegram	你希望使用这些服务提供商的现成连接器。
console	本地开发：消息会记录到日志中。
自定义连接器	编写一个小型类并将其注册为插件；参见自定义连接器。

连接器通过配置设置，而无需修改代码：无需改动规则即可更换短信服务商。

其他功能

• SDK。 使用 pip install cue-notify-client 和 npm install cue-client 安装，二者都支持 webhook 签名验证。参见 SDK。
• 互动跟踪。 跟踪送达、打开、点击和转化；客户端应用使用每条消息对应的令牌进行上报，无需 API 密钥。
• 群发。 支持受众筛选、可恢复的批次处理，以及暂停、恢复和取消，避免重复发送。
• 合规。 支持美国营销短信的发送时段和州级上限、STOP/START 回复，以及记录展示过的披露内容的选择加入记录。参见合规。
• 使用你自己的数据库运行。 由 API 进程和工作进程组成（小型部署也可将工作进程嵌入 API 中），支持 PostgreSQL 或 SQLite。无需 Redis 或消息代理：持久化任务队列存储在数据库中。保留期限需要自行安排 cuectl prune。
• 可观测。 支持按规则统计事件结果、状态原因、Prometheus 指标和 JSON 日志。
• 面向工具的文档。 llms.txt 和 AGENTS.md。

Cue 的对比

	它是什么	与 Cue 的区别
Novu	可自托管的通知基础设施。	其自托管指南列出了 MongoDB、Redis 和兼容 S3 的存储。Cue 只需要一个数据库：PostgreSQL 或 SQLite。
Knock、Courier、OneSignal	托管式通知服务。	你需要注册使用它们的服务；Cue 则运行在你的基础设施上。
Apprise、ntfy	将消息发送到多个服务或设备的工具。	它们会发送你交给它们的内容；是否以及何时应该通知某个人（偏好设置、上限、其所在时区的安静时段、摘要）由你的代码决定。Cue 会做出这个决定，然后将消息交给发送器。
Agent 框架中的人工审批（LangGraph interrupt()、Slack 审批按钮）	暂停单个 Agent 的运行，直到有人作出答复。	它只涵盖一个 Agent 和一个决策；某个人今晚已经从你的其他 Agent 收到多少条消息，不在它的考虑范围内。Cue 会跨所有这些 Agent 应用上限、安静时段和摘要，其审批请求还可以恢复 LangGraph、Pydantic AI、CrewAI Flows 和 Dapr Agents 的执行。
框架通知库（Laravel、Rails、Django……）	在应用程序中负责格式化并发送通知的代码。	每个应用程序都需要自行构建策略、偏好设置和历史记录；Cue 则将它们集中在一个服务中，供每个应用程序和 Agent 调用。

工作原理

flowchart LR
    E[POST /v1/events] --> R{Rules}
    R --> P[Policy<br/>unsubscribe · caps · cooldown · quiet hours]
    P --> T[Template<br/>locale · route variants]
    T --> Q[(Queue)]
    Q --> A[AI rewording<br/>optional]
    A --> C{Your delivery<br/>webhook · connectors}

概念	简述
事件	收件人发生的某件事。具备幂等性，并会按规则存储处理结果。
规则	当事件 X（及其条件）发生时 → 通过路由 [A、B] 发送模板 Y。
模板	本地化内容，包含针对不同路由的变体。
类别	策略集合：频率上限、安静时段、是否允许取消订阅。
渠道	一个命名路由（push、sms……），由连接器提供支持。
消息	发给一位收件人的一条通知，包含完整的状态记录。
广播	使用一个模板向受众发送通知，并分批处理，支持恢复。

配置

环境变量（CUE_SECTION__KEY）或 cue.toml：

[database]
url = "postgresql+asyncpg://cue:secret@db/cue"

[api]
public_url = "https://cue.example.com"   # needs CUE_API__SECRET_KEY

[channels.push]
provider = "webhook"
url = "https://notifications.internal.example/push"   # secret from CUE_CHANNELS__PUSH__SECRET

[channels.sms]
provider = "twilio"
account_sid = "AC…"
from_number = "+15550100"   # auth token from CUE_CHANNELS__SMS__AUTH_TOKEN

请参阅配置参考、 部署指南和 examples/cue.toml。

项目状态

Cue 仍处于早期开发阶段（0.x）：模型和 API 的基本形态已经稳定，但在 1.0 发布前仍可能发生变化；每个版本的变更日志 都会说明升级时的操作方法。有关后续计划，请参阅 路线图。 欢迎提供反馈和贡献；请参阅 CONTRIBUTING.md。

许可证

MIT