叁 · 推送

飞书推送

ctx.feishu

通过飞书官方 CLI lark-cli 发送文本 / Markdown 消息，支持 bot / user 身份、群聊 / 单聊 / 多群、@ 人、幂等键和 dryRun。

接口

const r = await ctx.feishu.send({
  markdown: '正文',                      // 或 text: '纯文本'，二选一
  title: '标题',                         // 可选，作为加粗首行发送
  target: { chatId: 'oc_...' },          // 或 { userId: 'ou_...' } / { chatIds: ['oc_...', ...] }
  at: { userIds: ['ou_...'], all: false },
  idempotencyKey: 'evt_...',
  traceId: 'evt_...',
  signal,                                // 可选，中止时终止 lark-cli 子进程
})
// r.results: Array<{ target, ok, messageId?, error? }>

本 Service 通过子进程调用飞书官方 CLI lark-cli（npm 包 @larksuite/cli，已验证 1.0.96）的 lark-cli im +messages-send：

• 不经过 shell，参数统一写成 --key=value 形式，以 - 开头的正文也不会被当成选项。
• 固定附加 --format=json，并关闭 lark-cli 的更新与 skills 提示，避免它们混入输出。
• 子进程只继承环境变量白名单；应用凭据与令牌类变量不在其中，本包的其他密钥也不会传给 lark-cli。
• 配置了 profile 时附加 --profile=<名字>，使用 lark-cli 的对应命名配置。
• 超时或卸载时先发 SIGTERM，宽限 killGraceMs 后发 SIGKILL，连同孙进程一起回收（Windows 上用 taskkill /T /F）。

身份

身份	需要的准备	适用
bot	lark-cli config init，填写飞书应用的 App ID / App Secret	服务器环境推荐，无需用户登录
user	在 bot 的基础上再登录：运行 lark-cli auth login --scope "im:message.send_as_user im:message"，或由业务包调用 ctx.feishu.login()（见下文）	以登录用户的名义发送

两种身份都以 --as=<身份> 传给 lark-cli。凭据由 lark-cli 自己的配置与系统钥匙串保存，本包不读取、不保存。

目标

target 省略时使用配置的 defaultTarget；单次调用的 target 会覆盖它，多个业务包共用本包时互不影响。

目标	格式	说明
{ chatId }	群 chat_id，oc_ 开头	发到群
{ userId }	用户 open_id，ou_ 开头	发单聊
{ chatIds }	多个 chat_id，最多 100 个	去重后逐个发送

目标、@ 列表与幂等键在拼装参数前做格式校验，格式不符或以 - 开头的值会被拒绝（invalid_target）。lark-cli 一次只发一个目标，所以多群时逐个调用：单个群失败不中断其余的群，也不抛错，体现在 results 中；只有中止（aborted）会立即抛出。单目标时失败直接抛出。

正文、标题与 @

• markdown 与 text 二选一。
• 飞书的 markdown 消息没有独立标题：给了 title 时，markdown 作为加粗首行，text 作为首行。
• at.userIds 是被 @ 用户的 open_id，at.all 表示 @ 所有人，追加在正文末尾。

幂等与重试

• idempotencyKey 透传为 lark-cli 的 --idempotency-key，同一个键在 1 小时内只发送一次。
• lark-cli 的幂等键最长 50 个字符。单目标且不超长时原样使用，便于在飞书侧对账；多目标或超长时，按「原始键 + 目标」派生一个逐目标的键，否则只有第一个目标能收到。
• 只有给出 idempotencyKey 时，才会对可重试的失败（超时，或 lark-cli 错误类别为 network / timeout / rate_limit / server / internal / unavailable）最多重试 retry.maxAttempts 次，间隔从 500ms 起指数增长。没有幂等键时不自动重试，避免重复发送。

登录状态与登录

const st = await ctx.feishu.status()
// { channel: 'feishu', identity: 'user', online: false, account?: '张三', detail, checkedAt }

const s = await ctx.feishu.login()     // 仅 user 身份；{ channel, verificationUrl, userCode?, expiresAt, completed, cancel() }
await postToOps(s.verificationUrl)      // 由业务包决定怎么把链接交给要登录的人
const after = await s.completed         // 授权完成后的状态

await ctx.feishu.logout()               // 仅 user 身份；返回退出后的状态

• status()：执行 lark-cli auth status --json 实时检查所配身份是否可用；account 在 user 身份下是用户名或 open_id，在 bot 身份下是应用 App ID。dryRun 时只报告，不改变 health()。
• login({ signal? })：运行 lark-cli auth login --scope=im:message.send_as_user im:message --no-wait --json 立即拿到授权链接并返回，随后在后台运行 lark-cli auth login --device-code=<code> 等待授权。对方授权后 completed 以新的状态 resolve；链接过期（15 分钟，lark-cli 给出有效期时以它为准）、被拒绝、cancel() 或 signal 中止时同样 resolve，online 为 false。登录进行中再次调用返回同一个会话。第一步失败时抛出 login_failed。
• logout()：运行 lark-cli auth logout，退出 user 身份的登录，返回退出后的状态。
• 配置了 profile 时，以上命令都带 --profile=<名字>。
• bot 身份没有用户登录：它使用 lark-cli config init 配置的应用凭据，status() 照常报告应用是否可用，login() / logout() 抛出 unsupported。更换应用凭据请重新运行 lark-cli config init。

身份检查与 dryRun

• 启动时以及每隔 preflightIntervalMs 执行 lark-cli auth status --json，检查所配身份是否可用。不可用时 health() 返回 failed，并触发 agent-kit/service-failed 事件。
• dryRun: true 时附加 --dry-run，只做参数解析与日志、不真实发送，适合本地开发与测试；此时不检查身份。

larkPath 与 Windows

larkPath 必须是绝对路径；省略时启动时从 PATH 解析。Windows 上 npm 全局安装的是 lark-cli.cmd，本包会自动定位到它背后的 run.js 并用 node 运行。手动配置 larkPath 时，请指向可执行文件、.exe 或 .js，不要指向 .cmd / .bat。

配置

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

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

约束与说明

• bot 身份只需要用 lark-cli config init 配好应用的 App ID / App Secret；user 身份还需要登录：lark-cli auth login --scope "im:message.send_as_user im:message"，或由业务包调用 ctx.feishu.login()。
• status() 实时检查所配身份是否可用；user 身份的 login() 发起设备流登录，拿到授权链接即返回，logout() 退出登录。bot 身份的 login() / logout() 报 unsupported。
• 应用凭据与令牌由 lark-cli 自己的配置和系统钥匙串管理，本包不保存，也不把它们传给子进程。
• 自动重试只在给出 idempotencyKey 时进行，避免重复发送；lark-cli 的幂等键最长 50 个字符，多目标时逐目标派生。
• larkPath 必须是绝对路径，指向可执行文件、.exe 或 .js，不支持 Windows 的 .cmd / .bat。

错误码

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