SuperAPI AI 工具集

messaging

智能体与模型

查看项目

更新于 10-15 23:33

技能介绍

用途:该技能面向 Agent Comms Gateway,让生产者只上报“发生了什么”,由网关代理统一决定 Joel 听到什么、何时听到、如何措辞以及由哪个平台接收。传输层只负责平台机制:追加事件、运行单一平台监听器、执行已记录的投递决策、记录回执并提供原始兜底。

主要能力:发送消息使用 joelclaw notify send "...",纯文本仍受支持;缺少 --kind 会告警并默认 receipt,发送不会失败。旧字段与可选字段仍被接受,但只作为证据而非指令,包括 message text、--kind、--priority、--channel、--telegram-only 及生产者提供的结构化证据与引用。结构化 JSON 证据当前通过 --context 传入,例如 joelclaw notify send "The deploy failed." --context '{"runId":"01J...","url":"https://example.invalid/run/01J..."}'。--data <json> 与重复 --ref 属于生产者事实契约,但当前 CLI 尚未实现,不应作为可用选项调用。

追踪与保证:保留返回的 flowId,用 joelclaw messages trace <flowId> 追踪完整生命周期,关联回复、反应、按钮、决策与平台回执;平台消息 ID 只是查询数据,不是持久身份。每个消费的外部事件在推进游标前记录恰好一条 gateway.decision.recorded 回执,决策动词为 deliver、aggregate、escalate、fanout、route、drop。deliver 与 aggregate/close-deliver 由 gateway-decision-executor.ts 机械执行,判断留在网关代理;当前执行器只能投递到 Telegram,除非存在对应传输回执,否则不得声称其他平台已完成。

重复事件与入站:重复告警使用稳定 incident envelope,payload.evidence 提供 anomalyId、state(open/changed/resolved)、severity、observedAt、evidence;anomalyId 命名条件而非运行。网关从规范回执重建 latch,Redis 可缓存但非唯一副本。每个 (source, anomalyId) 每个太平洋日可花三个即时 Telegram 名额:open、一次实质变更、resolution。Joel 的入站事件(自由文本、回复、反应、按钮点击)走同一流契约,按钮点击是输入而非完成证明。

兜底与限制:若 notify 入口缺少 gateway:agent:heartbeat,传输层先追加 message.requested 再使用 Telegram 兜底,生产须保持 FALLBACK_CHANNEL=telegram;SMS 为潜伏状态,FALLBACK_CHANNEL=sms 当前会抛错。兜底消息以 ⚠️ fallback: 开头,首次立即发送来源计数摘要,后续输入并入十分钟滚动批次;Front、email、Slack 来源不贡献原始文本或主题。兜底无模型判断、Markdown、按钮、抑制或升级阶梯。单所有者原则要求恰好一个 slim 传输守护进程、一个网关代理会话、每平台一个监听器;禁止启动第二个 Telegram 轮询器、第二个 Slack socket、独立 Chat SDK 监听器、已退役的嵌入式网关代理或额外网关会话。Telegram 409 表示存在被禁止的第二个轮询器,应找到并停止重复者,而非添加租约、重试、影子或交接策略掩盖。运行时操作见 docs/gateway.md 或网关技能,活动入口为 packages/gateway/src/transport-daemon.ts 且 GATEWAY_TRANSPORT_SLIM_DOWN=1。回滚使用 scripts/gateway-cutover-rollback.sh,但不要直接调用,须按 docs/gateway.md 的受保护预检执行。不要清空 Redis 或在活动传输旁启动旧监听器。