叁 · 通知

通知渠道

ctx.notify

通知入口：业务包通过 ctx.notify.send() 发送，默认发往配置的默认渠道，也可按调用指定渠道。

接口

const r = await ctx.notify.send({
  text: '需要人工复核',
  targets: { dingtalk: { chatId: 'cid...' } },
  at: { dingtalk: { openDingtalkIds: ['...'] } },
  idempotencyKey: 'evt_...',
  traceId: 'evt_...',
  signal,
})
// r: { deliveries: Array<{ channel: 'dingtalk' | 'feishu' | 'wecom', results: Array<{ ok, messageId?, error? }> }> }

// 钉钉发往配置的默认群，飞书、企业微信发往指定群
await ctx.notify.send({ text: '库存告警', targets: { dingtalk: 'default', feishu: { chatId: 'oc_xxx' }, wecom: { chatId: 'wrk…' } } })

业务包只需 inject notify。启用 agent-kit-notify 与要用的渠道行（agent-kit-dingtalk、agent-kit-feishu、agent-kit-wecom）；notify 的 channel 是默认渠道，可选 dingtalk、feishu 或 wecom。不写 targets 时发往默认渠道并使用其默认目标，写了哪些渠道就只发这些渠道。默认渠道未运行时抛出 channel_unavailable；指定的渠道未运行或发送失败，在该渠道的 results[i].error 中返回。企业微信只能向已给机器人发过消息的会话主动发送，否则该渠道的结果为 not_interacted。

status() 返回默认渠道与每个渠道的运行、登录状态；login(channel) / logout(channel) 必须指定渠道，渠道不需要登录时抛出 login_unsupported。notify 不 inject 渠道 Service，而是在发送时查找它，因此停用渠道不会卸载只依赖 notify 的业务插件。

配置

在 Profile 的 cordis.patch.yml 中按 id agent-kit-notify 启用并给出配置。按 id 修改 config 时整段替换，未给出的字段使用默认值。下表由本包源码中的配置 schema 生成。

- id: agent-kit-notify
  disabled: false
  config:
    # 只写需要改的字段，其余使用下表的默认值

约束与说明

• channel 是默认渠道（dingtalk 或 feishu）；默认渠道的行需要启用，否则未指定 targets 的 send() 抛出 channel_unavailable。
• 本 Service 不 inject 钉钉，而是在发送时查找：启用、停用渠道行也不会重新加载 notify。
• status() 返回默认渠道与各渠道的实时登录状态；login(channel) / logout(channel) 必须指定渠道。

错误码

所有错误都是 KitError：用 isKitError(e) 判断，按 code 与 retryable 决定是否重试。