openclaw-lark-multi-agent 0.1.15 → 1.0.0

package/README.md

@@ -32,10 +32,13 @@ All of them connect to the same OpenClaw Gateway while keeping sessions, queues,
 - Local SQLite message store for context, trigger tracking, and duplicate prevention
 - `pending_triggers` queue so restart recovery does not replay every context message
 - `delivered_replies` table so one trigger message gets at most one delivered reply per bot
+- Durable delivery outbox for assistant-visible output, with stable delivery keys, atomic claim-before-send dispatch, and short-window duplicate suppression
+- Message recall handling: recalled queued/pending user messages are removed before they reach OpenClaw and excluded from future context
 - Feishu image download and OpenClaw multimodal attachment forwarding
 - Bridge attachment marker protocol for generated files/images/documents
 - Feishu CardKit v2 Markdown rendering, including native table elements for pipe tables
 - Bridge-level slash commands and escaped OpenClaw slash commands
+- `/discuss` mode for barrier-style multi-bot group discussion, including per-round markers and no-reply status notices
 - Linux systemd installer with separate runtime and state directories
 
 ## Architecture
@@ -228,6 +231,7 @@ Bridge-level commands use a single slash and are handled by this project:
 - `/free` — toggle this bot's Free mode in the current group chat
 - `/mute` — toggle this bot's mute mode in the current group chat
 - `/mode` — show this bot's current mode in the current chat
+- `/discuss on|off|status|stop|rounds N` — control group-level multi-bot discussion mode
 
 OpenClaw-level slash commands can be sent by escaping with a double slash:
 
@@ -294,7 +298,54 @@ the mention-only message is treated as a trigger and is combined with the previo
 
 Bot messages do not trigger other bots unless they mention them. The anti-loop guard is counted per bot per chat: other bots' replies do not consume the current bot's streak budget, and a human message resets the streak.
 
-`/free` is not a full multi-agent discussion scheduler. Notes for a future explicit `/discuss` mode live in [`docs/ideas/discussion-mode.md`](docs/ideas/discussion-mode.md).
+### `/discuss` mode
+
+`/discuss` is an explicit group-level multi-agent discussion scheduler. It is separate from Free mode:
+
+- `/free` controls whether a single bot may answer plain human messages.
+- `/discuss on` lets one coordinator take over plain human messages and run all Free-mode bots in barrier-style rounds.
+- Targeted mentions still fall through to normal routing, so `@GPT hello` works even while discuss mode is enabled.
+- Each participant receives the same round prompt and does not see other participants' replies from the current round until the next round.
+- Each visible discussion reply is annotated with a round marker such as `—— 第 2/3 轮 · Claude`.
+- If some participants return `NO_REPLY` or an empty reply, the coordinator sends a lightweight status notice such as `💬 第 3/3 轮：Qwen、Gemini 无新增回复`.
+- When the configured maximum round count is reached, the coordinator sends a completion notice.
+
+Commands:
+
+```text
+/discuss on
+/discuss off
+/discuss status
+/discuss stop
+/discuss rounds 3
+```
+
+## Delivery outbox and duplicate prevention
+
+All user-visible assistant outputs go through the local `delivery_outbox` before being sent to Feishu. This includes normal chat final replies, proactive `session.message` replies, delayed runtime-error notices, provider-error notices, discussion replies, and attachment marker deliveries.
+
+The outbox provides several protections:
+
+- stable trigger-based delivery keys such as `trigger:<message_row_id>`;
+- `UNIQUE(bot_name, chat_id, delivery_key)` to prevent duplicate deliveries for the same logical output;
+- `pending -> delivering -> delivered/failed` claim-before-send dispatch to avoid concurrent resend races;
+- short-window content-hash dedupe for proactive-only outputs;
+- short-window containment dedupe for cases where `chat final` contains an intermediate note plus final answer while proactive contains only the final answer;
+- attachment-aware dedupe so file/image/document deliveries are not accidentally collapsed with text-only replies.
+
+This keeps normal replies, subagent/proactive completions, discussion messages, delayed runtime failures, provider errors, and generated attachments on one consistent delivery path.
+
+## Message recall
+
+The bridge subscribes to Feishu `im.message.recalled_v1` events. When a user recalls a message that is still pending or queued:
+
+1. the original message remains in the local `messages` ledger for audit;
+2. the message is recorded in `recalled_messages`;
+3. matching `pending_triggers` for each bot are removed;
+4. pending local reaction acknowledgements are removed;
+5. future context sync excludes the recalled message.
+
+Version 1 behavior intentionally does **not** abort an OpenClaw run that has already started processing the recalled message, and it does not recall bot replies that were already sent. The first goal is to make recall reliable for queued/not-yet-processed messages.
 
 
 ## Markdown, tables, and attachments
@@ -316,6 +367,8 @@ SQLite state lives in the configured data directory. Important tables:
 - `sync_state` — per-bot/per-chat sync cursor
 - `pending_triggers` — messages that should actively trigger a bot run
 - `delivered_replies` — delivered response markers for idempotency
+- `delivery_outbox` — durable user-visible delivery ledger with claim/dedupe state
+- `recalled_messages` — recalled user messages excluded from pending work and future context
 - `processed_events` — Feishu event de-duplication
 - `bot_chat_settings` — per-bot/per-chat settings such as verbose mode
 

package/README.zh-CN.md

@@ -32,10 +32,13 @@ Lark/飞书里每个机器人都有自己的 App 身份，但 OpenClaw 通常在
 - 本地 SQLite 消息存储，用于上下文、触发队列和重复投递防护
 - `pending_triggers` 队列，避免重启后把所有历史上下文都重新发给 OpenClaw
 - `delivered_replies` 表，保证同一个触发消息每个 bot 最多投递一次回复
+- 持久化 delivery outbox：所有用户可见输出先入库，再通过稳定 key、原子 claim 和短窗口去重后投递
+- 消息撤回处理：已撤回且仍在排队/待处理的用户消息会从 pending 队列移除，并从后续上下文中排除
 - 支持飞书图片下载，并以 OpenClaw multimodal attachment 形式转发
 - Bridge attachment marker 协议，用于发送生成的文件、图片和文档
 - Feishu CardKit v2 Markdown 渲染，并把 pipe table 转成原生 table 组件
 - 桥接层 slash command + 转义后的 OpenClaw slash command
+- `/discuss` 多 bot 结构化讨论模式，支持轮次标注和无新增回复提示
 - Linux systemd 安装脚本，运行产物和状态目录分离
 
 ## 架构
@@ -228,6 +231,7 @@ openclaw-lark-multi-agent install-windows-service
 - `/free` — 开关当前 bot 在当前群聊里的 Free 模式
 - `/mute` — 开关当前 bot 在当前群聊里的 mute 模式
 - `/mode` — 查看当前 bot 在当前聊天里的模式
+- `/discuss on|off|status|stop|rounds N` — 控制群级多 bot 讨论模式
 
 如果你想把 slash command 直接发给 OpenClaw，可以用双斜杠转义：
 
@@ -294,8 +298,55 @@ Free 模式是 per-bot 且保守的：
 
 bot 发出的消息默认不会触发其他 bot，除非明确 @。anti-loop 防护按 bot + chat 单独计算：其他 bot 的发言不会消耗当前 bot 的额度，人类发言会重置计数。
 
-`/free` 不是完整的多 Agent 讨论调度器。未来独立 `/discuss` 模式的设计草案在 [`docs/ideas/discussion-mode.md`](docs/ideas/discussion-mode.md)。
 
+## `/discuss` 讨论模式
+
+`/discuss` 是显式的群级多智能体讨论调度器，和 Free 模式分工不同：
+
+- `/free` 控制单个 bot 是否可以响应普通人类消息。
+- `/discuss on` 让一个 coordinator 接管普通人类消息，并按 barrier-style round 调度所有 Free 模式 bot。
+- 定向 @ 仍然走普通路由，所以 discuss 开启时 `@GPT hello` 仍会只触发 GPT。
+- 每个参与 bot 在同一轮拿到相同 prompt，本轮内看不到其他 bot 的回复，下一轮才会看到上一轮结果。
+- 每条可见讨论回复会自动追加轮次标注，例如 `—— 第 2/3 轮 · Claude`。
+- 如果某些 bot 返回 `NO_REPLY` 或空回复，coordinator 会发送轻量提示，例如 `💬 第 3/3 轮：Qwen、Gemini 无新增回复`。
+- 达到配置轮数后，coordinator 会发送讨论完成提示。
+
+命令：
+
+```text
+/discuss on
+/discuss off
+/discuss status
+/discuss stop
+/discuss rounds 3
+```
+
+## Delivery outbox 与重复投递防护
+
+所有用户可见 assistant 输出都会先进入本地 `delivery_outbox`，再统一投递到飞书。覆盖普通 chat final、proactive `session.message`、延迟 runtime error、provider error、discussion 回复和附件 marker。
+
+outbox 提供：
+
+- 稳定 trigger key，例如 `trigger:<message_row_id>`；
+- `UNIQUE(bot_name, chat_id, delivery_key)` 防止同一逻辑输出重复投递；
+- `pending -> delivering -> delivered/failed` 原子 claim，避免并发重复发送；
+- proactive-only 输出的短窗口 content hash 去重；
+- chat final 包含“中间说明 + 最终答案”、proactive 只包含“最终答案”时的短窗口包含关系去重；
+- 附件感知去重，避免把带文件/图片/文档的输出和纯文本误合并。
+
+这样普通回复、subagent/proactive 回传、讨论消息、延迟错误、provider 错误和生成附件都走同一条可靠投递链路。
+
+## 消息撤回
+
+桥接层订阅飞书 `im.message.recalled_v1` 事件。用户撤回一条仍在 pending/排队中的消息时：
+
+1. 原始消息仍保留在 `messages` 表，便于审计；
+2. 撤回记录写入 `recalled_messages`；
+3. 删除各 bot 对应的 `pending_triggers`；
+4. 移除本地 pending reaction ack；
+5. 后续同步上下文时排除这条撤回消息。
+
+v1 行为边界：如果消息已经进入 OpenClaw 正在处理，暂不 abort；如果 bot 回复已经发出，也不自动撤回 bot 回复。第一版目标是可靠取消“尚未处理/排队中”的撤回消息。
 
 ## Markdown、表格和附件
 

package/dist/feishu-bot.d.ts

@@ -34,6 +34,7 @@ export declare class FeishuBot {
     private adminOpenId;
     private static allBots;
     constructor(config: BotConfig, openclawClient: OpenClawClient, store: MessageStore, adminOpenId?: string);
+    private handleMessageRecalled;
     register(): void;
     /**
      * Get the session key for a specific chat.

package/dist/feishu-bot.js

@@ -56,8 +56,33 @@ export class FeishuBot {
         });
         this.eventDispatcher = new lark.EventDispatcher({}).register({
             "im.message.receive_v1": this.handleMessage.bind(this),
+            "im.message.recalled_v1": this.handleMessageRecalled.bind(this),
         });
     }
+    async handleMessageRecalled(data) {
+        console.log(`[${this.config.name}] Message recalled event:`, JSON.stringify(data));
+        const messageId = data?.message_id;
+        const chatId = data?.chat_id;
+        if (!messageId || !chatId)
+            return;
+        const rowId = this.store.getMessageId(messageId);
+        this.store.markMessageRecalled(messageId, chatId, Number(data?.recall_time) || Date.now(), data?.recall_type || '');
+        if (!rowId)
+            return;
+        this.store.clearPendingTrigger(this.config.name, chatId, rowId);
+        const pendingAcks = this.pendingAckMessages.get(chatId) || [];
+        const remainingAcks = [];
+        for (const ack of pendingAcks) {
+            if (ack.rowId === rowId) {
+                await this.removeReaction(ack.messageId, ack.emoji).catch(() => { });
+            }
+            else {
+                remainingAcks.push(ack);
+            }
+        }
+        this.pendingAckMessages.set(chatId, remainingAcks);
+        console.log(`[${this.config.name}] Recalled message ${messageId} row=${rowId}; pending trigger canceled if present`);
+    }
     register() {
         FeishuBot.allBots.set(this.config.appId, this);
     }

package/dist/message-store.d.ts

@@ -51,6 +51,8 @@ export declare class MessageStore {
      */
     insert(msg: ChatMessage): number;
     getMessageId(messageId: string): number | null;
+    markMessageRecalled(messageId: string, chatId: string, recalledAt?: number, recallType?: string): void;
+    isMessageRecalled(messageId: string): boolean;
     markPendingTrigger(botName: string, chatId: string, messageRowId: number): void;
     getPendingTriggerIds(botName: string, chatId: string): Set<number>;
     clearPendingTriggers(botName: string, chatId: string, upToId: number): void;

package/dist/message-store.js

@@ -51,6 +51,16 @@ export class MessageStore {
         PRIMARY KEY (bot_name, message_id)
       );
 
+      -- Tracks recalled human messages. Recalled messages are kept in the raw
+      -- message ledger for audit, but excluded from future OpenClaw context and
+      -- pending trigger processing.
+      CREATE TABLE IF NOT EXISTS recalled_messages (
+        message_id TEXT PRIMARY KEY,
+        chat_id TEXT NOT NULL,
+        recalled_at INTEGER NOT NULL,
+        recall_type TEXT NOT NULL DEFAULT ''
+      );
+
       -- Tracks messages that should actively trigger a bot reply.
       -- Other unsynced messages remain local context and are sent only when a trigger arrives.
       CREATE TABLE IF NOT EXISTS pending_triggers (
@@ -225,6 +235,17 @@ export class MessageStore {
         const row = this.db.prepare(`SELECT id FROM messages WHERE message_id = ?`).get(messageId);
         return row?.id || null;
     }
+    markMessageRecalled(messageId, chatId, recalledAt = Date.now(), recallType = '') {
+        this.db.prepare(`
+      INSERT INTO recalled_messages (message_id, chat_id, recalled_at, recall_type)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(message_id) DO UPDATE SET chat_id = excluded.chat_id, recalled_at = excluded.recalled_at, recall_type = excluded.recall_type
+    `).run(messageId, chatId, recalledAt, recallType || '');
+    }
+    isMessageRecalled(messageId) {
+        const row = this.db.prepare(`SELECT 1 FROM recalled_messages WHERE message_id = ?`).get(messageId);
+        return !!row;
+    }
     markPendingTrigger(botName, chatId, messageRowId) {
         this.db.prepare(`
       INSERT OR IGNORE INTO pending_triggers (bot_name, chat_id, message_row_id)
@@ -373,9 +394,10 @@ export class MessageStore {
     `).get(botName, chatId);
         const lastId = row?.last_synced_msg_id || 0;
         const rows = this.db.prepare(`
-      SELECT * FROM messages
-      WHERE chat_id = ? AND id > ?
-      ORDER BY timestamp ASC
+      SELECT messages.* FROM messages
+      LEFT JOIN recalled_messages ON recalled_messages.message_id = messages.message_id
+      WHERE messages.chat_id = ? AND messages.id > ? AND recalled_messages.message_id IS NULL
+      ORDER BY messages.timestamp ASC
       LIMIT ?
     `).all(chatId, lastId, maxCount);
         return rows.map((r) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-lark-multi-agent",
-  "version": "0.1.15",
+  "version": "1.0.0",
   "description": "Multi-bot Lark/Feishu bridge for OpenClaw, with per-bot model routing and isolated sessions",
   "type": "module",
   "scripts": {