Skip to content

🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.

20.3 KB
Raw Blame
/**
 * 持久化的出站队列:最终回复、文件、审批提示和重要通知先写进 sqlite,再发送。
 * - 每条消息有确定的 id(由入站消息 id 推出来),同一 id 只写一次、只发一次;
 * - 同一会话按写入顺序一条一条发,前一条没发完,后面的等着;
 * - 临时失败按退避重试(5 秒起,翻倍到 5 分钟),渠道没在运行时等它上线;
 * - 要等对方先发消息才能发的(微信:超过 24 小时没说话、本轮配额用完)留着(held),对方下次发消息时按原来的顺序先发出去,
 *   能合并的合成一条「你不在时:…」,排在这次的回复前面;
 * - 主动消息(任务结果等,规则见 delivery.ts)可以排到某个时间再发(scheduled:免打扰、每天上限、合并),不挡同一会话里的回复;
 *   到时间时同一会话一起到期的交给 planner 合成一条摘要;对方先发了消息就和留着的一起先发;
 * - 再也发不出去了(平台多次拒绝、等待太久)标记 gone 并记下原因,只记在日志和诊断信息里;
 * - 应用重启后接着发。流式的中间内容和"正在输入"不经过这里。
 *
 * 设计改编自 deepseek-ai/dsh-superagent-prototype(MIT,© 2026 DeepSeek Harness Team):src/app/outbox.ts 的回执 +
 * src/app/effects.ts 的持久化副作用队列(按会话排队、Later 不计失败、指数退避、关机时留到下次启动),见 THIRD_PARTY_NOTICES.md。
 */
import crypto from "node:crypto";
import type { OutboxBody, OutboxKind, OutboxPurpose, OutboxRow, Store } from "../store/db.js";
import type { PushChannel } from "./types.js";
import { logger } from "../log.js";
import { t as tr } from "../i18n/index.js";

const log = logger("outbox");

/** 暂时不能发(渠道没上线、登录过期等):稍后再试,不算失败 */
export class Later extends Error {}
/** 再也发不出去了:标记 gone,message 是原因(日志、诊断信息) */
export class Gone extends Error {}
/** 要等对方先发消息才能发(微信 24 小时窗口已过、本轮配额用完):留着,对方下次发消息时再发(见 release);code 是原因 */
export class Held extends Error {
  constructor(
    message: string,
    readonly code: "window_closed" | "quota" | "no_token" = "window_closed",
  ) {
    super(message);
  }
}

/** 定时器最长睡多久:电脑睡眠时定时器不走,醒来后最多这么久就会重新看一遍 */
const MAX_SLEEP_MS = 5 * 60_000;

/** 普通消息最长等多久(微信的会话凭证 24 小时有效,飞书也不该再补发一天前的回复) */
export const OUTBOX_TTL_MS = 24 * 3600_000;
/** 平台明确拒绝(有错误码)的,试这么多次就放弃 */
export const REJECTIONS_BEFORE_GONE = 5;
/** 留着等对方发消息的,最多留多久(ack、审批提示这类短命的照旧按自己的期限) */
export const HOLD_TTL_MS = 7 * 86400_000;

export interface OutboxInput {
  id: string;
  botId: string;
  /** 走哪个渠道账号;不给就用这个会话最近的账号(主动消息:任务结果、规则提醒) */
  account?: string;
  channel: PushChannel;
  /** 微信:用户 id;飞书和其他平台:单聊的 chat id */
  peerId: string;
  kind: OutboxKind;
  body: OutboxBody;
  /** 飞书:回复的消息 id */
  replyTo?: string;
  /** 多久之后不再发(默认 24 小时;ack、审批提示更短);排着的从到期时算起 */
  ttlMs?: number;
  /** 主动推送的用途(见 delivery.ts);不给 = 对话里的回复 */
  purpose?: OutboxPurpose;
  subject?: string;
  ref?: string;
  /** 什么时候发:晚于现在就先排着(scheduled),不挡同一会话里的回复 */
  due?: number;
  /** 排着的原因 */
  reason?: string;
}

/**
 * 一起发的一组消息:body 给了就合成这一条发(kind、replyTo 给了也换掉,比如飞书的摘要改成直接发到会话),
 * 否则这组只有一条、照原样发
 */
export interface HeldGroup {
  rows: OutboxRow[];
  body?: OutboxBody;
  kind?: OutboxKind;
  replyTo?: string;
}

/** 排着的消息到时间了(同一会话的一批):返回 later 就再排到那时,否则返回怎么合成 */
export interface OutboxPlanner {
  promote(rows: OutboxRow[], now: number): { later: number; reason: string } | HeldGroup[];
  /** 这条现在不能发、对方发消息时也不放(机器人的后台工作暂停了):返回原因,排着等 */
  waits?(row: OutboxRow): string | undefined;
}

/** 渠道的发送函数:成功返回;Later / Gone / 其他错误(临时失败,会重试)。progress 记下长文本已发出的分段数 */
export type Deliver = (row: OutboxRow, progress: (n: number) => void) => Promise<void>;

/** 平台给的确定 id(微信 client_id、飞书 uuid):同一条消息的同一段每次都一样,平台去重时不会重复 */
export function stableId(id: string, part: number, len = 32): string {
  return crypto.createHash("sha256").update(`${id}#${part}`).digest("hex").slice(0, len);
}

/** 发出去的文字:text 后面接上 hint(正文没有句末标点时补一个,中文「。」,英文「. 」) */
export function sentText(b: Pick<OutboxBody, "text" | "hint">): string {
  const text = b.text ?? "";
  if (!b.hint) return text;
  const head = text.trimEnd();
  const cjk = /^[\u2e80-\u9fff\uff00-\uffef]/.test(b.hint);
  if (!head) return b.hint;
  if (/[。!?!?.…]$/.test(head)) return head + (cjk ? "" : " ") + b.hint;
  return head + (cjk ? "。" : ". ") + b.hint;
}

/**
 * 一次回复里每条出站消息 id 的最后一段:最终回复按"第几个"(同一条入站只有一个最终回复,平台重复投递、模型答得不一样时也不会再发一遍),
 * 其余按内容(不同的消息不会因为先后顺序不同撞上同一个 id 而被吞掉)。
 */
export class ReplyIds {
  private finals = 0;
  final(): string {
    return `final${this.finals++ || ""}`;
  }
  of(kind: string, content: string): string {
    return `${kind}-${stableId(content, 0, 12)}`;
  }
}

export class Outbox {
  private handlers = new Map<string, Deliver>();
  /** 会话 → 正在进行的那次发送 */
  private inflight = new Map<string, { id: string; done: Promise<void> }>();
  private timer: NodeJS.Timeout | undefined;
  private scheduled = false;
  private started = false;
  private stopped = false;
  private listeners = new Set<(row: OutboxRow) => void>();
  /** 排着的消息到时间时怎么办(delivery.ts 设);没有就一条一条照原样发 */
  planner: OutboxPlanner | undefined;

  constructor(
    private store: Store,
    private opts: { now?: () => number; retry?: readonly [number, number] } = {},
  ) {}

  /** 消息的状态变了(发出去、留着、放弃、排着的放出来):「需要你」据此刷新 */
  onChange(fn: (row: OutboxRow) => void): () => void {
    this.listeners.add(fn);
    return () => this.listeners.delete(fn);
  }

  private changed(id: string): void {
    if (!this.listeners.size) return;
    const row = this.store.getOutbox(id);
    if (!row) return;
    for (const fn of this.listeners) {
      try {
        fn(row);
      } catch (e) {
        log.warn("outbox listener failed", { message: (e as Error).message });
      }
    }
  }

  /** 时间可能跳了(电脑睡醒、改了时钟):马上再看一遍 */
  wake(): void {
    this.kick();
  }

  private now(): number {
    return (this.opts.now ?? Date.now)();
  }

  /** 渠道上线时登记自己的发送函数(按渠道账号),返回注销函数(渠道停下时调用;没登记的消息等着) */
  register(account: string, channel: string, deliver: Deliver): () => void {
    const key = `${account}:${channel}`;
    this.handlers.set(key, deliver);
    this.kick();
    return () => {
      if (this.handlers.get(key) === deliver) this.handlers.delete(key);
    };
  }

  /**
   * 先写库再发。同一 id 已经写过就不再写(也不会再发一遍)。
   * 等到这条消息的第一次发送结束(成功、失败待重试或放弃)才返回;排在同一会话前一条后面时立即返回。不抛错。
   */
  async send(input: OutboxInput): Promise<OutboxRow | undefined> {
    const now = this.now();
    const conversationId = `${input.botId}:${input.channel}:${input.peerId}`;
    const due = Math.max(now, input.due ?? now);
    const later = due > now;
    const fresh = this.store.insertOutbox({
      id: input.id,
      botId: input.botId,
      account: input.account ?? this.store.getConversation(conversationId)?.account ?? "",
      channel: input.channel,
      conversationId,
      peerId: input.peerId,
      kind: input.kind,
      body: input.body,
      replyTo: input.replyTo ?? "",
      due,
      createdAt: now,
      expiresAt: due + (input.ttlMs ?? OUTBOX_TTL_MS),
      status: later ? "scheduled" : "pending",
      purpose: input.purpose ?? "",
      subject: input.subject ?? "",
      ref: input.ref ?? "",
      reason: later ? (input.reason ?? "") : "",
    });
    if (later) {
      if (fresh) this.changed(input.id);
      this.kick();
      return this.store.getOutbox(input.id);
    }
    this.pump();
    const f = this.inflight.get(conversationId);
    if (f?.id === input.id) await f.done;
    return this.store.getOutbox(input.id);
  }

  /** 开始发送(含上次没发完的);清理旧记录 */
  start(): void {
    this.started = true;
    this.stopped = false;
    try {
      for (const st of ["held", "scheduled"] as const) for (const r of this.store.listOutbox({ status: st, limit: 500 })) if (r.expiresAt <= this.now()) this.gone(r, tr("delivery.goneTooLong"));
      this.store.pruneOutbox(this.now());
      // 重启了:等着退避的不用再等,马上试一次
      this.store.resumeOutbox(this.now());
    } catch (e) {
      log.warn("prune failed", { message: (e as Error).message });
    }
    const left = this.store.pendingOutbox().length;
    if (left) log.info(`resuming ${left} unsent message(s)`);
    this.kick();
  }

  /** 不再开始新的发送,等正在发的结束(最多 waitMs);没发完的留在库里,下次启动接着发 */
  async stop(waitMs = 5000): Promise<void> {
    this.stopped = true;
    clearTimeout(this.timer);
    this.timer = undefined;
    const running = [...this.inflight.values()].map((f) => f.done);
    if (!running.length) return;
    let t: NodeJS.Timeout | undefined;
    await Promise.race([Promise.allSettled(running), new Promise((r) => (t = setTimeout(r, waitMs)))]);
    clearTimeout(t);
  }

  /** 等到没有正在进行的发送(到期待重试的不等) */
  async idle(): Promise<void> {
    for (;;) {
      this.pump();
      const running = [...this.inflight.values()].map((f) => f.done);
      if (!running.length) return;
      await Promise.allSettled(running);
    }
  }

  /**
   * 对方又发消息了:留着给他的消息和排着的主动消息放回队列,按原来的顺序排在这次回复的前面。
   * combine 决定哪几条合成一条发(每组第一条换成合并后的内容,其余标记 merged);不给就一条一条发。过期的不再发。
   */
  release(botId: string, channel: string, peerId: string, combine?: (rows: OutboxRow[]) => HeldGroup[]): number {
    const conv = `${botId}:${channel}:${peerId}`;
    // 还没发出去的续期提醒:对方已经发消息了,不用再提醒
    for (const r of this.store.pendingOutbox().filter((x) => x.conversationId === conv && x.purpose === "nudge")) if (!this.inflight.has(conv)) this.gone(r, tr("delivery.goneReplied"));
    const waiting = this.store.waitingOutbox(conv);
    if (!waiting.length) return 0;
    const now = this.now();
    const live = waiting.filter((r) => (r.expiresAt > now || (this.gone(r, tr("delivery.goneTooLong")), false)) && !this.planner?.waits?.(r));
    if (!live.length) return 0;
    this.apply(combine ? combine(live) : live.map((r): HeldGroup => ({ rows: [r] })), now, "inbound");
    if (live.length) log.info(`releasing ${live.length} waiting message(s)`, { bot: botId, channel });
    this.kick();
    return live.length;
  }

  /** 对方发消息了:他和所有机器人的留言都放回队列(用 /bot 切换过的话,留言可能属于别的机器人)。account 也试一遍:单元测试里可能没有机器人 */
  releasePeer(channel: string, peerId: string, combine: ((rows: OutboxRow[]) => HeldGroup[]) | undefined, account: string): number {
    let n = 0;
    for (const id of new Set([...this.store.listBots().map((b) => b.id), account])) n += this.release(id, channel, peerId, combine);
    return n;
  }

  /** 每组第一条放回队列(换成合并后的内容),其余标记 merged;排着的从现在起重新算有效期 */
  private apply(groups: HeldGroup[], now: number, reason: string): void {
    for (const g of groups) {
      const [first, ...rest] = g.rows;
      if (!first) continue;
      this.store.updateOutbox(
        first.id,
        {
          status: "pending",
          due: now,
          error: "",
          reason,
          ...(first.status === "scheduled" ? { expiresAt: now + Math.max(OUTBOX_TTL_MS, first.expiresAt - first.due) } : {}),
          ...(g.body ? { body: g.body, progress: 0 } : {}),
          ...(g.kind ? { kind: g.kind } : {}),
          ...(g.replyTo !== undefined ? { replyTo: g.replyTo } : {}),
        },
        now,
      );
      for (const r of rest) this.store.updateOutbox(r.id, { status: "merged", mergedInto: first.id, reason }, now);
      this.changed(first.id);
    }
  }

  /** 排着的主动消息到时间了:同一会话的一批交给 planner(再排到以后 / 合成一条),放回队列 */
  private promote(now: number): void {
    const due = this.store.dueScheduledOutbox(now);
    if (!due.length) return;
    const byConv = new Map<string, OutboxRow[]>();
    for (const r of due) byConv.set(r.conversationId, [...(byConv.get(r.conversationId) ?? []), r]);
    for (const rows of byConv.values()) {
      const live = rows.filter((r) => r.expiresAt > now || (this.gone(r, tr("delivery.goneTooLong")), false));
      if (!live.length) continue;
      let plan: ReturnType<OutboxPlanner["promote"]> = live.map((r) => ({ rows: [r] }));
      try {
        if (this.planner) plan = this.planner.promote(live, now);
      } catch (e) {
        log.warn("outbox planner failed", { message: (e as Error).message });
      }
      if ("later" in plan) {
        const at = Math.max(plan.later, now + 1000);
        for (const r of live) this.store.updateOutbox(r.id, { due: at, reason: plan.reason, expiresAt: Math.max(r.expiresAt, at + OUTBOX_TTL_MS) }, now);
        continue;
      }
      this.apply(plan, now, live[0].reason);
    }
  }

  private kick(): void {
    if (this.scheduled) return;
    this.scheduled = true;
    queueMicrotask(() => {
      this.scheduled = false;
      this.pump();
    });
  }

  /** 每个会话只看最早的一条没发出去的:到期且渠道在线就发,否则记下最早什么时候再看 */
  private pump(): void {
    if (!this.started || this.stopped) return;
    clearTimeout(this.timer);
    this.timer = undefined;
    const now = this.now();
    this.promote(now);
    let next = this.store.nextScheduledDue() || Infinity;
    const heads = new Set<string>();
    for (const row of this.store.pendingOutbox()) {
      if (heads.has(row.conversationId)) continue;
      heads.add(row.conversationId);
      if (this.inflight.has(row.conversationId)) continue;
      // 主动消息现在不能发(机器人的后台工作暂停了):改成排着,不挡这个会话后面的回复
      const wait = row.purpose ? this.planner?.waits?.(row) : undefined;
      if (wait) {
        this.store.updateOutbox(row.id, { status: "scheduled", due: now + MAX_SLEEP_MS, reason: wait }, now);
        this.changed(row.id);
        this.kick();
        continue;
      }
      if (row.expiresAt <= now) {
        this.gone(row, row.error ? tr("delivery.goneKeptFailing", { error: row.error }) : tr("delivery.goneTooLong"));
        this.kick();
        continue;
      }
      const deliver = this.handlers.get(`${row.account || row.botId}:${row.channel}`);
      if (row.due > now || !deliver) {
        // 渠道没上线:等它注册;到了过期时间也要醒来标记 gone
        next = Math.min(next, deliver ? row.due : row.expiresAt);
        continue;
      }
      this.attempt(row, deliver);
    }
    if (next < Infinity) {
      this.timer = setTimeout(() => this.pump(), Math.min(MAX_SLEEP_MS, Math.max(20, next - now)));
      this.timer.unref?.();
    }
  }

  private attempt(row: OutboxRow, deliver: Deliver): void {
    const conv = row.conversationId;
    const done = (async () => {
      try {
        await deliver(row, (n) => this.store.updateOutbox(row.id, { progress: n }, this.now()));
        this.store.updateOutbox(row.id, { status: "sent", sentAt: this.now(), error: "" }, this.now());
      } catch (e) {
        this.failed(row, e);
      }
      this.changed(row.id);
    })().finally(() => {
      if (this.inflight.get(conv)?.done === done) this.inflight.delete(conv);
      this.kick();
    });
    this.inflight.set(conv, { id: row.id, done });
  }

  private failed(row: OutboxRow, e: unknown): void {
    const msg = String((e as Error)?.message ?? e).slice(0, 300);
    const now = this.now();
    if (e instanceof Gone) return this.gone(row, msg);
    if (e instanceof Held) return this.hold(row, msg, e.code);
    // 关机中:留到下次启动
    if (this.stopped) return;
    const [base, max] = this.opts.retry ?? [5000, 300_000];
    if (e instanceof Later) {
      this.store.updateOutbox(row.id, { due: now + base, error: msg }, now);
      return;
    }
    const attempts = row.attempts + 1;
    const rejected = (e as { rejected?: boolean })?.rejected === true;
    if ((rejected && attempts >= REJECTIONS_BEFORE_GONE) || now >= row.expiresAt) return this.gone(row, tr("delivery.goneFailed", { error: msg }));
    const delay = Math.min(max, base * 2 ** Math.min(attempts - 1, 16));
    log.warn("send failed, will retry", { id: row.id, channel: row.channel, attempts, inMs: delay, message: msg });
    this.store.updateOutbox(row.id, { attempts, error: msg, due: now + delay }, now);
  }

  /**
   * 留着等对方发消息:不算失败;普通消息和主动消息从现在起最多留 HOLD_TTL_MS,短命的(ack、审批提示)照旧按自己的期限。
   * 续期提醒发不出去就算了
   */
  private hold(row: OutboxRow, reason: string, code = ""): void {
    if (row.purpose === "nudge") return this.gone(row, reason);
    const long = row.purpose !== "" || row.expiresAt - row.createdAt >= OUTBOX_TTL_MS;
    const expiresAt = long ? Math.max(row.expiresAt, (row.purpose ? this.now() : row.createdAt) + HOLD_TTL_MS) : row.expiresAt;
    this.store.updateOutbox(row.id, { status: "held", error: reason, reason: code, expiresAt }, this.now());
    log.info("message held until the user writes again", { id: row.id, channel: row.channel, kind: row.kind, reason });
  }

  private gone(row: OutboxRow, reason: string): void {
    this.store.updateOutbox(row.id, { status: "gone", error: reason }, this.now());
    log.warn("message gone", { id: row.id, channel: row.channel, kind: row.kind, reason });
    this.changed(row.id);
  }

  /**
   * 不用再发了(任务的提问已经在别处回答了、任务停了):还没发出去的(排着、留着、等着重试)标记 gone,记作看过(不算没送到);
   * 正在发的不管。返回撤回了没有
   */
  withdraw(id: string, reason: string): boolean {
    const row = this.store.getOutbox(id);
    if (!row || (row.status !== "pending" && row.status !== "scheduled" && row.status !== "held")) return false;
    if (this.inflight.get(row.conversationId)?.id === id) return false;
    const now = this.now();
    this.store.updateOutbox(id, { status: "gone", error: reason, seenAt: now }, now);
    log.info("message withdrawn", { id, channel: row.channel, reason });
    this.changed(id);
    return true;
  }

  /** 「需要你」里点了重试:放弃了的从现在起再试,一直失败的马上再试一次 */
  retry(id: string): boolean {
    const row = this.store.getOutbox(id);
    if (!row || (row.status !== "gone" && row.status !== "pending")) return false;
    const now = this.now();
    this.store.updateOutbox(id, { status: "pending", due: now, attempts: 0, error: "", expiresAt: Math.max(row.expiresAt, now + OUTBOX_TTL_MS) }, now);
    this.changed(id);
    this.kick();
    return true;
  }
}