@xmanrui/dsh-im 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmanrui/dsh-im",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "把九种 IM 机器人和公网 AI Office 接入本机 DeepSeek Harness。 Connect nine IM channels and a public AI Office to a local DeepSeek Harness.",
   "keywords": [
     "deepseek-harness",

package/src/channels/discord/discord-api.mjs

@@ -108,7 +108,7 @@ export class DiscordApi {
         headers: {
           authorization: `Bot ${this.#token}`,
           'content-type': 'application/json',
-          'user-agent': 'DeepSeek-Harness-dsh-im (https://github.com/xmanrui/dsh-im, 0.16.0)',
+          'user-agent': 'DeepSeek-Harness-dsh-im (https://github.com/xmanrui/dsh-im, 0.17.0)',
         },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
         signal: requestSignal(signal, timeoutMs),

package/src/channels/feishu/bridge.mjs

@@ -32,11 +32,14 @@ import { runWorkspaceCommand, resolveSessionListWorkspace, workspacePathSnapshot
 import { askInWorkspaceSession } from '../shared/workspace-session.mjs';
 import {
   MENU_PAGE_SIZE,
+  completionCard,
   menuCard,
   menuHelpText,
   sessionListCard,
+  watchListCard,
   workspaceListCard,
 } from './feishu-cards.mjs';
+import { MAX_WATCHES_PER_KEY } from './state-store.mjs';
 
 const INTERACTION_RESOLVED_TEXT = '这个问题已在其他客户端处理，无需再次回答。';
 const RESOLVED_REPLY_TTL_MS = 30 * 60_000;
@@ -44,6 +47,9 @@ const RESOLVED_REPLY_TTL_MS = 30 * 60_000;
 const MENU_COMMAND = /^\/m(?:enu)?$/i;
 const REPAIR_COMMAND_PREFIX = /^\/repair(?:\s|$)/i;
 const REPAIR_COMMAND = /^\/repair(?:\s+(qr|status|cancel|verify))?\s*$/i;
+const WATCH_COMMAND = /^\/watch(?:\s+([^\s]+))?$/i;
+const UNWATCH_COMMAND = /^\/unwatch(?:\s+([^\s]+))?$/i;
+const WATCHLIST_COMMAND = /^\/watchlist$/i;
 const SESSION_LIST_PREFIX = /^\/sessionlist(?:\s|$)/i;
 const WORKSPACE_LIST_COMMAND = /^\/workspacelist$/i;
 const NUMBER_REPLY = /^\d{1,2}$/;
@@ -83,9 +89,15 @@ const HELP_TEXT = [
   '/status  检查连接状态',
   '/repair  修复卡片按钮回调',
   '/m（或 /menu）  打开交互卡片菜单',
+  '/watch [Session ID 或序号]  关注会话，任务完成自动推送',
+  '/unwatch [Session ID 或序号]  取消关注',
+  '/watchlist  查看关注列表',
+  '/archived on|off  会话列表是否包含归档会话',
   '/help  显示本帮助',
 ].join('\n');
 
+const ARCHIVED_COMMAND = /^\/archived(?:\s+(on|off))?$/i;
+
 /** Safe user-facing text for bind/workspace failures (no raw messages). */
 function safeErrorText(error) {
   switch (error?.code) {
@@ -106,6 +118,13 @@ function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+function orderedHistoryEvents(history) {
+  return (Array.isArray(history?.events) ? history.events : [])
+    .map((entry) => entry?.event ?? entry)
+    .filter((entry) => entry && typeof entry === 'object' && Number.isFinite(entry.seq))
+    .sort((left, right) => left.seq - right.seq);
+}
+
 function senderOpenId(event) {
   return nonEmptyString(event?.sender?.sender_id?.open_id)
     ?? nonEmptyString(event?.sender?.sender_id?.user_id);
@@ -240,6 +259,12 @@ export class FeishuHarnessBridge {
   #menus = new Map();
   /** Interactive-card message id → route context for button callbacks. */
   #cardKeys = new Map();
+  /** The global event-mux watcher (one per bridge). */
+  #eventWatcher = null;
+  /** Serializes live completions and reconnect compensation. */
+  #eventTail = Promise.resolve();
+  /** Earliest completion that still needs delivery for each watch. */
+  #failedWatchSeqs = new Map();
 
   constructor({
     client,
@@ -295,6 +320,11 @@ export class FeishuHarnessBridge {
     this.#approvals = new HarnessApprovalQueue({ label: 'Feishu', logger });
     this.#signal = signal;
     ensureStatus(this.#status);
+    // Persisted watches must resume at runtime start, not on the first
+    // message. Older hosts without the mux watcher simply skip this.
+    if (typeof this.#harness?.watchHarnessEvents === 'function') {
+      queueMicrotask(() => this.#ensureEventWatcher());
+    }
   }
 
   accept(event) {
@@ -519,6 +549,7 @@ export class FeishuHarnessBridge {
       )),
       ...this.#interactionTasks,
       ...this.#commandTasks,
+      this.#eventTail,
     ]);
   }
 
@@ -604,6 +635,36 @@ export class FeishuHarnessBridge {
       await this.#showWorkspaces({ chatId: event.message.chat_id, key });
       return;
     }
+    if (WATCH_COMMAND.test(commandText)) {
+      const target = (WATCH_COMMAND.exec(commandText)?.[1] ?? '').trim() || null;
+      await this.#runWatch(key, event.message.chat_id, target);
+      return;
+    }
+    if (UNWATCH_COMMAND.test(commandText)) {
+      const target = (UNWATCH_COMMAND.exec(commandText)?.[1] ?? '').trim() || null;
+      await this.#runUnwatch(key, event.message.chat_id, target);
+      return;
+    }
+    if (WATCHLIST_COMMAND.test(commandText)) {
+      await this.#showWatchList(key, event.message.chat_id);
+      return;
+    }
+    if (ARCHIVED_COMMAND.test(commandText)) {
+      const match = ARCHIVED_COMMAND.exec(commandText);
+      const value = match[1]?.toLowerCase();
+      if (value !== 'on' && value !== 'off') {
+        await this.#send(event.message.chat_id, '用法：/archived on（包含归档会话）或 /archived off（隐藏归档会话）');
+        return;
+      }
+      if (typeof this.#state?.setIncludeArchivedSessions === 'function') {
+        await this.#state.setIncludeArchivedSessions(value === 'on');
+      }
+      await this.#send(
+        event.message.chat_id,
+        value === 'on' ? '已开启：会话列表包含归档会话。' : '已关闭：会话列表隐藏归档会话。',
+      );
+      return;
+    }
     if (NUMBER_REPLY.test(commandText)) {
       const menu = this.#takeMenu(key);
       if (menu) {
@@ -991,7 +1052,15 @@ export class FeishuHarnessBridge {
     if (!action) return Promise.resolve();
     const messageId = nonEmptyString(event?.context?.open_message_id);
     const entry = messageId ? this.#cardKeys.get(messageId) : null;
-    if (!entry) return Promise.resolve();
+    if (!entry) {
+      // The card predates this process (the in-memory mapping resets on
+      // restart) or never came from us: nudge instead of staying silent.
+      const chatId = nonEmptyString(event?.context?.open_chat_id);
+      if (chatId) {
+        this.#send(chatId, '这个菜单已过期，请回复 /m 重新打开。').catch(() => undefined);
+      }
+      return Promise.resolve();
+    }
     // The promise is returned so tests (and future callers) can await the
     // action; the runtime dispatcher ignores it.
     return this.#handleCardAction(action, entry).catch((error) => {
@@ -1009,6 +1078,10 @@ export class FeishuHarnessBridge {
       await this.#showWorkspaces({ chatId, key });
       return;
     }
+    if (action === 'watchlist') {
+      await this.#showWatchList(key, chatId);
+      return;
+    }
     if (action === 'new') {
       await this.#state.clearSession(key);
       await this.#send(chatId, '已开启全新 Harness 会话。');
@@ -1029,6 +1102,14 @@ export class FeishuHarnessBridge {
     }
     if (action.startsWith('workspace:')) {
       await this.#switchWorkspace(key, chatId, action.slice('workspace:'.length));
+      return;
+    }
+    if (action.startsWith('unwatch:')) {
+      await this.#runUnwatch(key, chatId, action.slice('unwatch:'.length));
+      return;
+    }
+    if (action.startsWith('watch:')) {
+      await this.#runWatch(key, chatId, action.slice('watch:'.length));
     }
   }
 
@@ -1053,7 +1134,7 @@ export class FeishuHarnessBridge {
 
   async #handleMenuPick(menu, number, { chatId, key, event }) {
     if (menu.kind === 'menu') {
-      const action = ['sessions', 'workspaces', 'new', 'status', 'help', 'repair'][number - 1];
+      const action = ['sessions', 'workspaces', 'new', 'status', 'help', 'repair', 'watchlist'][number - 1];
       if (!action) {
         await this.#send(chatId, '菜单没有这个编号，回复 /m 重新打开。');
         return;
@@ -1071,6 +1152,7 @@ export class FeishuHarnessBridge {
         await this.#send(chatId, `本页只有 ${menu.sessions.length} 个会话，回复 /sessionlist 重新查看。`);
         return;
       }
+      // The number label sits on the session (bind) button of the row.
       await this.#handleCardAction(`use:${session.sessionId}`, { chatId, key });
       return;
     }
@@ -1081,9 +1163,26 @@ export class FeishuHarnessBridge {
         return;
       }
       await this.#handleCardAction(`workspace:${workspace}`, { chatId, key });
+      return;
+    }
+    if (menu.kind === 'watches') {
+      const entry = menu.entries[number - 1];
+      if (!entry?.sessionId) {
+        await this.#send(chatId, `关注列表只有 ${menu.entries.length} 个会话。`);
+        return;
+      }
+      await this.#handleCardAction(`unwatch:${entry.sessionId}`, { chatId, key });
     }
   }
 
+  /** The sessions visible under the bot's archived policy. */
+  #visibleSessions(sessions) {
+    if (this.#state?.includesArchivedSessions?.() === false) {
+      return sessions.filter((session) => session.archived !== true);
+    }
+    return sessions;
+  }
+
   async #showSessions({ chatId, key }, selector, page = 0) {
     try {
       const resolved = await resolveSessionListWorkspace(selector ?? '', this.#harness);
@@ -1092,7 +1191,7 @@ export class FeishuHarnessBridge {
         return;
       }
       const listed = await this.#harness.listWorkspaceSessions(resolved.workspace);
-      const sessions = Array.isArray(listed?.sessions) ? listed.sessions : [];
+      const sessions = this.#visibleSessions(Array.isArray(listed?.sessions) ? listed.sessions : []);
       const workspace = listed?.workspace ?? resolved.workspace;
       if (sessions.length === 0) {
         await this.#send(chatId, `工作区：${workspace}\n该工作区暂无会话。`);
@@ -1100,16 +1199,24 @@ export class FeishuHarnessBridge {
       }
       const pageCount = Math.ceil(sessions.length / MENU_PAGE_SIZE);
       const safePage = Number.isSafeInteger(page) && page > 0 ? Math.min(page, pageCount - 1) : 0;
+      const watchedSet = new Set(
+        (this.#state.watchEntries?.(key) ?? []).map((entry) => entry.sessionId),
+      );
+      const pageSlice = sessions.slice(safePage * MENU_PAGE_SIZE, (safePage + 1) * MENU_PAGE_SIZE);
       this.#rememberMenu(key, {
         kind: 'sessions',
-        sessions: sessions.slice(safePage * MENU_PAGE_SIZE, (safePage + 1) * MENU_PAGE_SIZE),
-      });
-      await this.#sendCard(chatId, sessionListCard(workspace, sessions, safePage, sessions.length), {
-        key,
-        // Keep the canonical selector result for later page callbacks. The
-        // list response's workspace is display data and is not authoritative.
-        sessionWorkspace: resolved.workspace,
+        sessions: pageSlice.map((session) => ({ ...session, watched: watchedSet.has(session.sessionId) })),
       });
+      await this.#sendCard(
+        chatId,
+        sessionListCard(workspace, sessions, safePage, sessions.length, watchedSet),
+        {
+          key,
+          // Keep the canonical selector result for later page callbacks. The
+          // list response's workspace is display data and is not authoritative.
+          sessionWorkspace: resolved.workspace,
+        },
+      );
     } catch (error) {
       this.#logger.warn?.('[dsh-feishu] session list failed:', error.message);
       await this.#send(chatId, '暂时无法获取会话列表，请稍后重试。');
@@ -1171,6 +1278,256 @@ export class FeishuHarnessBridge {
     return messageId;
   }
 
+  // ── Watches: read-only session tracking + completion pushes ─────────────
+
+  #ensureEventWatcher() {
+    if (this.#eventWatcher) return;
+    if (typeof this.#harness?.watchHarnessEvents !== 'function') return;
+    if (this.#signal?.aborted) return;
+    const signal = this.#signal ?? new AbortController().signal;
+    try {
+      this.#eventWatcher = this.#harness.watchHarnessEvents({
+        signal,
+        onSessionEvent: (payload) => this.#onHarnessEvent(payload),
+        onReconnect: () => {
+          void this.#queueEventTask(() => this.#compensateMissedEvents());
+        },
+      });
+      Promise.resolve(this.#eventWatcher).catch((error) => {
+        if (!signal.aborted) {
+          this.#logger.warn?.('[dsh-feishu] event watcher stopped:', error.message);
+        }
+      });
+    } catch (error) {
+      this.#eventWatcher = null;
+      this.#logger.warn?.('[dsh-feishu] event watcher failed to start:', error.message);
+    }
+  }
+
+  #queueEventTask(task) {
+    const next = this.#eventTail.then(task, task).catch((error) => {
+      if (!this.#signal?.aborted) {
+        this.#logger.warn?.('[dsh-feishu] completion event failed:', error.message);
+      }
+    });
+    this.#eventTail = next;
+    return next;
+  }
+
+  /**
+   * Resolve a /watch target READ-ONLY: a session id is validated against
+   * the registered workspaces' listings, an index against the current
+   * workspace. Nothing is bound and no workspace is switched.
+   */
+  async #resolveWatchTarget(target) {
+    if (typeof target !== 'string' || target === '') {
+      return { error: '用法：/watch <Session ID 或当前工作区序号>' };
+    }
+    const numeric = /^\d{1,4}$/.test(target) ? Number(target) : null;
+    const currentPath = typeof this.#harness?.currentWorkspace === 'function'
+      ? this.#harness.currentWorkspace()
+      : null;
+    const listSessions = async (workspace) => {
+      const listed = await this.#harness.listWorkspaceSessions(workspace);
+      return Array.isArray(listed?.sessions) ? listed.sessions : [];
+    };
+    if (numeric !== null) {
+      if (!currentPath) return { error: '当前机器人没有可用的工作区，无法按序号解析会话。' };
+      const sessions = this.#visibleSessions(await listSessions(currentPath));
+      const session = sessions[numeric - 1];
+      if (!session?.sessionId) {
+        return { error: `当前工作区只有 ${sessions.length} 个会话。` };
+      }
+      return { sessionId: session.sessionId, title: session.title ?? '暂无标题' };
+    }
+    const extraPaths = typeof this.#harness?.listWorkspaces === 'function'
+      ? (await this.#harness.listWorkspaces()).filter((path) => path !== currentPath)
+      : [];
+    const paths = [currentPath, ...extraPaths].filter(Boolean);
+    for (const workspace of paths) {
+      const sessions = await listSessions(workspace);
+      const session = sessions.find((candidate) => candidate.sessionId === target);
+      if (session) return { sessionId: target, title: session.title ?? '暂无标题' };
+    }
+    return { error: '没有找到这个会话，请用 /sessionlist 查看可用会话。' };
+  }
+
+  async #latestSessionSeq(sessionId) {
+    if (typeof this.#harness?.rpc !== 'function') return null;
+    const history = await this.#harness.rpc(
+      'session.history',
+      { sessionId, maxMessages: 20 },
+      30_000,
+      { signal: this.#signal },
+    );
+    return orderedHistoryEvents(history).at(-1)?.seq ?? -1;
+  }
+
+  async #runWatch(key, chatId, target) {
+    this.#ensureEventWatcher();
+    if (typeof this.#state?.setWatch !== 'function') {
+      await this.#send(chatId, '当前状态存储不支持关注。');
+      return;
+    }
+    let resolved;
+    try {
+      resolved = await this.#resolveWatchTarget(target);
+    } catch (error) {
+      await this.#send(chatId, `无法解析会话：${safeErrorText(error)}`);
+      return;
+    }
+    if (resolved.error) {
+      await this.#send(chatId, resolved.error);
+      return;
+    }
+    const existing = this.#state.watchEntries?.(key) ?? [];
+    const existingEntry = existing.find((entry) => entry.sessionId === resolved.sessionId);
+    if (!existingEntry && existing.length >= MAX_WATCHES_PER_KEY) {
+      await this.#send(chatId, `每个聊天最多关注 ${MAX_WATCHES_PER_KEY} 个会话。`);
+      return;
+    }
+    try {
+      const lastSeq = typeof existingEntry?.lastSeq === 'number'
+        ? existingEntry.lastSeq
+        : await this.#latestSessionSeq(resolved.sessionId);
+      await this.#state.setWatch(key, {
+        sessionId: resolved.sessionId,
+        title: resolved.title,
+        chatId,
+        lastSeq,
+      });
+      await this.#send(chatId, `已关注会话「${String(resolved.title).replace(/\s+/gu, ' ')}」，任务完成会推送结果。`);
+      await this.#queueEventTask(() => this.#compensateSession(resolved.sessionId));
+    } catch (error) {
+      await this.#send(chatId, `关注失败：${safeErrorText(error)}`);
+    }
+  }
+
+  async #runUnwatch(key, chatId, target) {
+    if (typeof this.#state?.removeWatch !== 'function') return;
+    const entries = this.#state.watchEntries?.(key) ?? [];
+    const entry = typeof target === 'string' && /^\d{1,4}$/.test(target)
+      ? entries[Number(target) - 1]
+      : entries.find((candidate) => candidate.sessionId === target);
+    if (!entry) {
+      await this.#send(chatId, '关注列表里没有这个会话，回复 /watchlist 查看。');
+      return;
+    }
+    try {
+      await this.#state.removeWatch(key, entry.sessionId);
+      this.#failedWatchSeqs.delete(`${key}\0${entry.sessionId}`);
+      await this.#send(chatId, `已取消关注「${String(entry.title ?? '').replace(/\s+/gu, ' ')}」。`);
+    } catch (error) {
+      await this.#send(chatId, `取消失败：${safeErrorText(error)}`);
+    }
+  }
+
+  async #showWatchList(key, chatId) {
+    const entries = this.#state.watchEntries?.(key) ?? [];
+    this.#rememberMenu(key, { kind: 'watches', entries });
+    await this.#sendCard(chatId, watchListCard(entries), { key });
+  }
+
+  /** Queue live turn completions behind any reconnect compensation. */
+  #onHarnessEvent({ sessionId, event }) {
+    if (this.#signal?.aborted
+      || !sessionId
+      || !event
+      || typeof event !== 'object'
+      || event.type !== 'turn/end'
+      || !Number.isFinite(event.seq)) return;
+    void this.#queueEventTask(async () => {
+      const hasFailedDelivery = (this.#state.keysWatching?.(sessionId) ?? [])
+        .some((key) => this.#failedWatchSeqs.has(`${key}\0${sessionId}`));
+      if (hasFailedDelivery) await this.#compensateSession(sessionId);
+      await this.#deliverCompletion(sessionId, event);
+    });
+  }
+
+  async #deliverCompletion(sessionId, event) {
+    if (this.#signal?.aborted || typeof this.#state?.keysWatching !== 'function') return;
+    const reason = event?.data?.reason?.kind ?? event?.data?.reason ?? null;
+    for (const key of this.#state.keysWatching(sessionId)) {
+      if (this.#signal?.aborted) return;
+      const entry = this.#state.watchEntry?.(key, sessionId);
+      const deliveryKey = `${key}\0${sessionId}`;
+      let failedSeq = this.#failedWatchSeqs.get(deliveryKey);
+      if (typeof failedSeq === 'number'
+        && typeof entry?.lastSeq === 'number'
+        && entry.lastSeq >= failedSeq) {
+        this.#failedWatchSeqs.delete(deliveryKey);
+        failedSeq = undefined;
+      }
+      if (!entry?.chatId
+        || (typeof entry.lastSeq === 'number' && entry.lastSeq >= event.seq)
+        || (typeof failedSeq === 'number' && event.seq > failedSeq)) continue;
+      try {
+        await this.#sendCard(
+          entry.chatId,
+          completionCard(sessionId, entry.title, reason),
+          { key },
+        );
+        const current = this.#state.watchEntry?.(key, sessionId);
+        if (!current
+          || current.chatId !== entry.chatId
+          || (typeof current.lastSeq === 'number' && current.lastSeq >= event.seq)) continue;
+        await this.#state.setWatch(key, { ...current, lastSeq: event.seq });
+        if (failedSeq === event.seq) this.#failedWatchSeqs.delete(deliveryKey);
+      } catch (error) {
+        this.#failedWatchSeqs.set(
+          deliveryKey,
+          typeof failedSeq === 'number' ? Math.min(failedSeq, event.seq) : event.seq,
+        );
+        this.#logger.warn?.('[dsh-feishu] completion push failed:', error.message);
+      }
+    }
+  }
+
+  async #compensateSession(sessionId) {
+    if (this.#signal?.aborted || typeof this.#harness?.rpc !== 'function') return;
+    try {
+      const history = await this.#harness.rpc(
+        'session.history',
+        { sessionId, maxMessages: 20 },
+        30_000,
+        { signal: this.#signal },
+      );
+      const events = orderedHistoryEvents(history);
+      const latestSeq = events.at(-1)?.seq ?? -1;
+      const keys = typeof this.#state?.keysWatching === 'function'
+        ? this.#state.keysWatching(sessionId)
+        : [];
+
+      // Watches created by older versions have no baseline. Establish one
+      // without replaying completions that predate the watch.
+      for (const key of keys) {
+        const entry = this.#state.watchEntry?.(key, sessionId);
+        if (entry && typeof entry.lastSeq !== 'number') {
+          await this.#state.setWatch(key, { ...entry, lastSeq: latestSeq });
+        }
+      }
+
+      for (const event of events) {
+        if (event.type === 'turn/end') await this.#deliverCompletion(sessionId, event);
+      }
+    } catch (error) {
+      if (!this.#signal?.aborted) {
+        this.#logger.warn?.(`[dsh-feishu] watch compensation failed for ${sessionId}:`, error.message);
+      }
+    }
+  }
+
+  /** Replay recent turn completions missed while the mux was disconnected. */
+  async #compensateMissedEvents() {
+    const sessionIds = typeof this.#state?.watchedSessionIds === 'function'
+      ? this.#state.watchedSessionIds()
+      : [];
+    for (const sessionId of sessionIds) {
+      if (this.#signal?.aborted) return;
+      await this.#compensateSession(sessionId);
+    }
+  }
+
   #interactionAskOptions(event, key) {
     return {
       timeoutMs: this.#replyTimeoutMs,

package/src/channels/feishu/feishu-cards.mjs

@@ -4,10 +4,14 @@
  * `im.message.create` API expects as `content` for `msg_type: interactive`
  * (card schema 2.0; callback buttons live inside a column_set/column layout).
  *
- * Buttons carry a small `{ action }` callback behavior that
- * `card.action.trigger` events echo back (when the app subscribes that
- * callback); every button also carries a numeric label so the number-reply
- * fallback stays usable without button callbacks.
+ * The session list lays each row out as a `column_set` (fixed-width ⭐
+ * watch-toggle column + weighted session-button column), which is how V2
+ * expresses a row of buttons.
+ *
+ * Buttons carry a small `{ action }` value object that `card.action.trigger`
+ * events echo back (when the app subscribes that event); every numbered
+ * button also has a numeric label so the number-reply fallback stays usable
+ * without button callbacks.
  */
 
 export const MENU_PAGE_SIZE = 10;
@@ -39,6 +43,17 @@ function button(content, actionValue) {
   };
 }
 
+/** The raw button element (without the full-width column_set wrapper). */
+function buttonElement(content, actionValue) {
+  return {
+    tag: 'button',
+    text: plainText(content),
+    type: 'default',
+    width: 'fill',
+    behaviors: [{ type: 'callback', value: { action: actionValue } }],
+  };
+}
+
 function safeTitle(value) {
   const title = String(value ?? '').replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ').replace(/\s+/gu, ' ').trim();
   return title || '暂无标题';
@@ -65,6 +80,7 @@ export function menuCard() {
     // have card.action.trigger yet, so rendering it as a callback button would
     // send the user straight back to Feishu's broken callback setup popup.
     { tag: 'div', text: markdown('**6 · 修复卡片按钮**（请直接回复数字 **6**）') },
+    button('7 · 关注列表', 'watchlist'),
   ]);
 }
 
@@ -101,23 +117,43 @@ export function cardActionProbeCard(nonce) {
 }
 
 /**
- * One page of the workspace's sessions. Each row is a bind button; the
- * number label equals the reply-number for the same action (fallback).
+ * One page of the workspace's sessions. Each row is a `column_set` pair:
+ * the fixed-width ⭐ watch toggle (`⭐关注` / `⭐取关` for already-watched
+ * sessions) followed by the session button that carries the page-local
+ * number label (reply-number fallback = bind). Archived sessions are marked
+ * in the label. `watchedSessionIds` is a Set-like of ids this conversation
+ * already watches.
  */
-export function sessionListCard(workspace, sessions, page, total) {
+export function sessionListCard(workspace, sessions, page, total, watchedSessionIds = new Set()) {
   const start = page * MENU_PAGE_SIZE;
   const slice = sessions.slice(start, start + MENU_PAGE_SIZE);
   const pageCount = Math.max(1, Math.ceil(total / MENU_PAGE_SIZE));
+  const watched = (id) => typeof watchedSessionIds?.has === 'function' && watchedSessionIds.has(id);
+  /** One row: fixed 90px watch toggle + the session button filling the rest. */
+  const row = (watchButton, sessionButton) => ({
+    tag: 'column_set',
+    flex_mode: 'none',
+    horizontal_spacing: 'default',
+    columns: [
+      { tag: 'column', width: '90px', vertical_align: 'center', elements: [watchButton] },
+      { tag: 'column', width: 'weighted', weight: 1, vertical_align: 'center', elements: [sessionButton] },
+    ],
+  });
   const elements = [
     { tag: 'div', text: markdown(`**工作区**：\`${workspace}\`\n共 **${total}** 个会话${total > MENU_PAGE_SIZE ? `（第 ${page + 1}/${pageCount} 页）` : ''}`) },
-    ...slice.map((session, offset) => button(
-      `${offset + 1}. ${safeTitle(session.title)}`,
-      `use:${session.sessionId}`,
-    )),
+    ...slice.map((session, offset) => {
+      // Page-local numbering: number replies resolve against this page.
+      const label = `${offset + 1}. ${safeTitle(session.title)}${session.archived === true ? '（已归档）' : ''}`;
+      const watching = watched(session.sessionId);
+      return row(
+        buttonElement(watching ? '⭐取关' : '⭐关注', watching ? `unwatch:${session.sessionId}` : `watch:${session.sessionId}`),
+        buttonElement(label, `use:${session.sessionId}`),
+      );
+    }),
   ];
   if (page > 0) elements.push(button('◀ 上一页', `sessions:${page - 1}`));
   if (page + 1 < pageCount) elements.push(button('下一页 ▶', `sessions:${page + 1}`));
-  elements.push({ tag: 'div', text: markdown('回复数字（1~N）同样可以绑定本页会话。') });
+  elements.push({ tag: 'div', text: markdown('回复数字（1~N）绑定本页会话。') });
   return cardWith('📂 会话列表', elements);
 }
 
@@ -146,10 +182,49 @@ export function menuHelpText() {
     '4 · /status  连接状态',
     '5 · /help  本帮助',
     '6 · /repair  修复卡片按钮（请回复数字 6）',
+    '7 · /watchlist  关注列表',
     '',
     '直接发送文字/图片即继续当前会话。',
     '/session ID 或序号  绑定已有会话',
+    '/watch ID 或序号  关注会话（完成后推送）',
     '/compact  压缩上下文',
     '/workspace 绝对路径  切换工作区',
   ].join('\n');
 }
+
+/** The watch list for one conversation (unwatch buttons + reply fallback). */
+export function watchListCard(entries) {
+  const elements = entries.length === 0
+    ? [{ tag: 'div', text: markdown('当前没有关注的会话。\n`/watch <ID|序号>` 关注后，任务完成会自动推送。') }]
+    : [
+        { tag: 'div', text: markdown('任务完成会自动推送，回复数字或点按钮取消关注：') },
+        ...entries.map((entry, index) => button(
+          `${index + 1}. ${safeTitle(entry.title)}`,
+          `unwatch:${entry.sessionId}`,
+        )),
+      ];
+  return cardWith('👁 关注列表', elements);
+}
+
+/**
+ * The completion push card. `title` is the session title, `reason` the
+ * turn-end kind (completed / stopped / aborted).
+ */
+export function completionCard(sessionId, title, reason) {
+  const reasonText = reason === 'completed'
+    ? '已完成'
+    : reason === 'stopped'
+      ? '已停止'
+      : reason === 'aborted'
+        ? '已中止'
+        : reason === 'cancelled'
+          ? '已取消'
+          : '已结束';
+  return cardWith('✅ 任务完成', [
+    { tag: 'div', text: markdown(`**${safeTitle(title)}**\n\`${sessionId}\``) },
+    { tag: 'div', text: markdown(`**状态**：${reasonText}`) },
+    button('打开会话列表', 'sessions'),
+    button('工作区', 'workspaces'),
+    { tag: 'div', text: markdown('绑定该会话后可继续追问，输入文字即可。') },
+  ]);
+}