Agent Alerts 设置

设计自动化，配置托管的 webhook，并将运行时发送操作交给 $agent-alerts-execution。在设置期间不要发送，除非用户要求进行冒烟测试。

从这里开始

打开或引导用户访问：

https://www.andreas.ink/agent

按照页面上的当前连接流程，在 iPhone 上完成 Agent Alerts 设置。该流程会创建一个仅用于发布的令牌供运行时使用。不要要求用户在聊天中粘贴该令牌。

配置 Webhook

在公开设置页面上命名运行时并完成连接流程。
选择运行时的令牌存放位置：
- 托管运行时：将一次性令牌存储在该运行时的密钥管理器中，变量名为 AGENTALERTS_AGENT_TOKEN。
- 本地 Mac：将一行内容 AGENTALERTS_AGENT_TOKEN=<token> 保存到用户认可的 ~/.config/agent-alerts/token.env 文件中，并将其权限模式设为 0600。
让用户在选定的密钥存储中直接输入令牌，操作在 AI 对话之外进行。切勿要求他们将其粘贴到代理聊天中。
使用 ../agent-alerts-execution/scripts/send_webhook.sh 中内置的端点。仅当设置页面提供了不同的 HTTPS 端点时，才设置 AGENTALERTS_WEBHOOK_URL。
仅允许出站 HTTPS 连接到该端点。
授权 send_webhook.sh 的绝对路径用于无人值守运行。不要授予广泛的 shell 访问权限。

切勿将令牌放入提示、URL、查询字符串、日志、源文件、受跟踪的设置文件、shell 历史记录或命令参数中。

准备并验证测试

将 ../agent-alerts-execution/assets/compact-webhook-payload.json 复制到可写的负载文件中，并替换其中的示例值。为事件使用稳定且唯一的幂等键。

验证负载：

../agent-alerts-execution/scripts/send_webhook.sh --check payload.json

验证负载、令牌来源、权限和端点，但不进行发送：

../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json

然后发送一次非敏感的冒烟测试：

../agent-alerts-execution/scripts/send_webhook.sh payload.json

对于无人值守的自动化，请从实际的保存运行器处重复执行 --check-config 和冒烟发送。两者都必须完成且无需批准提示。如果运行器无法执行确切的辅助脚本或无法访问端点，则停止并返回 AGENTALERTS_SCRIPT_NOT_AUTHORIZED。

设计警报

定义：

信号、数据源和触发器。
good、warning 和 critical 的映射关系。
跳过条件、静默时间和排除项。
稳定的 activity_id 或通知标识符。
展示面：live_activity、widget 和/或 notification。
操作文本以及安全的 URL 或应用深度链接。
当警报稍后运行或重复运行时，使用持久的调度器。

Agent Alerts 负责投递更新；它不会保持代理会话的活动状态。未来或重复运行只有在当前会话关闭后调度器仍然保持注册状态时才算完成。否则返回 AGENTALERTS_SCHEDULER_NOT_DURABLE。

负载契约

对于普通警报，使用紧凑的 webhook 主体：

{
  "title": "构建完成",
  "summary": "所有测试通过。",
  "status": "good",
  "activity_id": "build-monitor",
  "source_name": "Codex",
  "surfaces": ["live_activity", "notification"],
  "idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}

Webhook 需要：

Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <与 idempotency_key 相同的值>

辅助脚本会在不将令牌暴露在进程参数中的情况下提供这些头信息。始终使用辅助脚本；不要手动重新创建请求。

紧凑发送默认使用一个名为 webhook 的 upserted 活动、生产交付，并在这些字段被省略时默认使用 live_activity 和 notification。当自动化需要不同结果时，请显式设置这些字段。

对于小组件、控制小组件状态、构建器布局或其他高级字段，请使用 webhook 的完整蛇形命名契约，并包含一个嵌套的 payload 对象。不要将完整的 payload 对象与紧凑字段 title、summary、status、source_name 或 deep_link 混用。

文案与交付规则

保持可见文案完整并符合以下限制：

字段	最大字符数
`source_name`	14
`title`	32
`summary`	96

不要依赖截断功能，也不要添加省略号。

live_activity 更新灵动岛或锁屏。
widget 需要其小组件标识符、小的非机密快照，并启用重新加载。
notification 需要稳定的线程标识符用于分组。
控制小组件状态在活动警告或关键状态下应为 true，在清除或已解决状态下应为 false。

运行时移交

编写一条精确的运行时指令：

使用 $agent-alerts-execution。首先评估配置的跳过条件。如果需要发送，则将准备好的 Agent Alerts JSON 写入经批准的负载路径，然后使用该文件调用经授权的绝对路径 send_webhook.sh。仅从 AGENTALERTS_AGENT_TOKEN 或经批准的 token.env 文件中读取令牌。报告返回的状态、目标、成功和失败计数，不要打印机密信息。

只有当实际运行器能在无需交互的情况下验证配置并发送、调度器在需要时持久化、并且结果在不夸大设备可见交付的情况下报告时，设置才算完成。

AgentAlerts 技能（iOS 推送）