metame-cli 1.5.2 → 1.5.4

package/scripts/docs/maintenance-manual.md

@@ -59,7 +59,7 @@ feishu:
 - `/stop`：引擎中性，按 `activeProcesses.killSignal` 停止
 - `/compact`：
   - Claude 会话：正常压缩
-  - Codex 会话：返回“暂不支持，请继续同会话”
+  - Codex 会话：返回"暂不支持，请继续同会话"
 - `/engine`：
   - 查询当前默认引擎：`/engine`
   - 切换默认引擎：`/engine claude` 或 `/engine codex`
@@ -69,7 +69,7 @@ feishu:
   - 也支持严格自然语言：`把蒸馏模型改成 5.1mini`
 - `/doctor`：
   - 同时检查 Claude/Codex CLI 可用性
-  - 仅在“当前默认引擎对应 CLI 不可用”时判为故障
+  - 仅在"当前默认引擎对应 CLI 不可用"时判为故障
   - 自定义 provider 下允许任意合法模型名（不再强制 sonnet/opus/haiku）
 
 ## 5. Agent Soul 身份层
@@ -88,6 +88,9 @@ feishu:
 - 活跃子进程：`~/.metame/active_agent_pids.json`
 - 热重载备份：`~/.metame/.last-good/`（daemon 稳定运行 60s 后自动备份）
 - 崩溃计数：`~/.metame/.crash-count`（连续 2 次快速崩溃触发自动恢复）
+- Dispatch 队列：`~/.metame/dispatch/pending.jsonl`（本地 socket 降级）
+- 远端 Dispatch 队列：`~/.metame/dispatch/remote-pending.jsonl`（跨设备中继）
+- Dispatch 签名密钥：`~/.metame/.dispatch_secret`（自动创建）
 
 ## 7. 热重载安全机制（三层防护）
 
@@ -126,12 +129,25 @@ feishu:
 2. 若仍失败，手动 `/new` 新开会话
 3. 检查 `~/.metame/active_agent_pids.json` 是否残留异常进程
 
+### 远端 Dispatch 失败
+
+症状：`/dispatch to peer:project` 返回 `feishu bot not connected`
+
+处理：
+
+1. 确认 `daemon.yaml` 中 `feishu.remote_dispatch.enabled: true` 且 `self`/`chat_id`/`secret` 非空
+2. 确认飞书 bot 已连接：`/doctor` 查看飞书状态
+3. 确认 relay 群已加入 `allowed_chat_ids`（relay 群消息需被 daemon 接收）
+4. 两端的 `secret` 必须完全一致
+
 ## 9. 双平台/双引擎维护矩阵
 
 ### 统一维护（改一处即可）
 - agent-layer.js / daemon-agent-tools.js / daemon-agent-commands.js / daemon-user-acl.js
 - ENGINE_MODEL_CONFIG（daemon-engine-runtime.js 集中管理）
 - daemon-runtime-lifecycle.js 的语法检查和备份机制
+- daemon-remote-dispatch.js（纯逻辑，无平台差异）
+- team-dispatch.js（共享解析/hint/enrichment）
 
 ### 需分别维护（有平台/引擎特殊分支）
 
@@ -145,7 +161,202 @@ feishu:
 | daemon.js `spawnReplacementDaemon` | POSIX: `detached: true` / Windows: `detached: false` | 改 spawn 参数时注意平台分支 |
 | NL Mac 控制（command-router） | macOS only，`process.platform === 'darwin'` 守卫 | Windows 天然跳过 |
 
-## 10. 变更后维护动作
+## 10. 团队路由（Team Routing）
+
+### 概念
+
+一个项目可以有多个 team 成员（数字分身），共享同一个 `cwd`，通过虚拟 chatId 并行工作。
+
+### 创建团队成员（向导）
+
+在手机端（飞书/Telegram）发送以下任一方式触发创建向导：
+
+- 自然语言：`创建团队`、`新建工作组`、`建个团队` 等（`_detectTeamIntent` 识别，位于 `daemon-command-router.js`）
+- 命令：`/agent new team`
+
+向导分三步，全部在 `daemon-agent-commands.js` 中实现：
+1. **name**：输入团队名称
+2. **members**：输入成员列表，格式 `名称:icon:颜色`，一行或逗号分隔多个
+3. **cwd**：通过文件浏览器（`daemon-file-browser.js` `team-new` 模式）选择父目录
+
+目录确认（`/agent-team-dir` 回调）后：
+- 在 `<父目录>/team/<成员key>/` 下创建工作目录及 CLAUDE.md
+- 自动执行 `git init`（支持 checkpoint）
+- 若父目录对应已有项目，自动写入 `daemon.yaml` 的 `team` 数组；否则提示手动注册
+
+中间状态保存在 `pendingTeamFlows` Map（`daemon.js` 中定义）。
+
+### 配置
+
+在 `~/.metame/daemon.yaml` 的项目下添加 `team` 数组和 `broadcast: true`：
+
+```yaml
+  metame:
+    name: 超级总管 Jarvis
+    icon: 🤖
+    broadcast: true
+    team:
+      - key: jia
+        name: Jarvis · 甲
+        icon: 🤖
+        color: green
+        cwd: ~/AGI/MetaMe
+        nicknames:
+          - 甲
+        auto_dispatch: true
+      - key: hunter
+        name: 猎手
+        icon: 🎯
+        peer: windows          # ← 远端成员，运行在 Windows 设备上
+        nicknames:
+          - 猎手
+```
+
+### 路由规则（按优先级）
+
+1. **引用回复** → 路由到原 agent + 设置 sticky
+2. **显式昵称**（如"乙 帮我查下"）→ 路由到对应成员 + 设置 sticky
+3. **主项目昵称**（如"贾维斯"）→ 清除 sticky，路由到主项目
+4. **Sticky**：无昵称时 → 路由到上次显式指定的成员
+5. **Auto-dispatch**：主忙时自动分配给空闲的 `auto_dispatch` 成员
+
+**远端成员**：检测到 `member.peer` 时，bridges 自动走 `sendRemoteDispatch()` → relay 群 → 对端 daemon 接收执行，结果通过 relay 群回传。路由优先级不变，只是传输链路不同。
+
+### /stop 精准路由
+
+- `/stop 乙`：停止指定成员
+- `/stop`：停止 sticky 成员
+- 引用回复 `/stop`：停止对应成员
+
+### /msg — 团队直接消息
+
+格式：`/msg <agent昵称> <消息内容>`
+
+- 例如：`/msg 乙 帮我看看这个文件`
+- 按昵称解析目标（先查 team 成员，再查 projects）
+- 以 `type='message', priority='normal'` 调度
+- 实现文件：`daemon-admin-commands.js` resolveProjectKey 函数
+
+### Team Broadcast（团队广播 = 可观察模式）
+
+`broadcast: true` 时，team 成员之间通过 `dispatch_to` 互发消息会在群里用卡片广播。
+
+**这就是"观察模式"**：开启 broadcast 后，你在群里可以实时看到成员之间互相传递任务的全过程（哪个成员发给了哪个成员、发了什么内容），以飞书卡片形式展示。
+
+切换命令：`/broadcast on` / `/broadcast off`（实时生效，写入 daemon.yaml）
+
+实现入口：`daemon.js` `_findTeamBroadcastContext()` + `handleDispatchItem()` 的广播分支。
+
+### 虚拟 chatId
+
+team 成员使用 `_agent_{key}` 格式的虚拟 chatId，与物理群 chatId 隔离。
+
+### 卡片标题
+
+由 `icon + name` 拼成，如 `🤖 Jarvis · 乙`。
+
+## 11. 跨设备 Dispatch（Remote Peer Dispatch）
+
+### 概念
+
+team 成员可以通过 `peer` 字段标记为"远端成员"——运行在另一台机器上的 daemon。用户在飞书群里对远端成员的操作体验与本地成员完全一致（昵称路由、sticky follow 等），底层通过飞书 relay 群实现跨设备通信。
+
+### 配置
+
+两台设备的 `daemon.yaml` 需要配置相同的 relay 群和共享密钥，不同的 `self` 标识：
+
+```yaml
+# Mac 端
+feishu:
+  remote_dispatch:
+    enabled: true
+    self: mac                    # 本机标识（唯一）
+    chat_id: oc_relay_xxx        # 专用中继群（两端相同）
+    secret: shared-secret-key    # HMAC 签名密钥（两端相同）
+
+# Windows 端
+feishu:
+  remote_dispatch:
+    enabled: true
+    self: windows
+    chat_id: oc_relay_xxx        # 同一个 relay 群
+    secret: shared-secret-key    # 同一个密钥
+```
+
+team 成员添加 `peer` 字段指向远端设备：
+
+```yaml
+projects:
+  business:
+    team:
+      - key: writer
+        name: 编剧              # 无 peer → 本地执行
+      - key: hunter
+        name: 猎手
+        peer: windows            # 远端设备
+```
+
+### 数据流
+
+#### 用户消息 → 远端 team member
+
+```
+飞书群消息 "猎手 去调研竞品"
+→ bridges.js findTeamMember → { member: { key:'hunter', peer:'windows' } }
+→ _dispatchToTeamMember 检测 member.peer
+→ sendRemoteDispatch → encodePacket + HMAC 签名 → relay 群
+→ Windows daemon bridges 拦截 → decodePacket + verifyPacket + isDuplicate
+→ handleDispatchItem(local) → Claude 执行
+→ _replyFn → encode result → relay 群
+→ Mac daemon 拦截 → decode → sendMarkdown 到用户飞书群
+```
+
+#### Claude session 内跨设备 dispatch
+
+```
+Claude 看到 hook 注入:
+  - hunter（猎手 [远端:windows]）: `dispatch_to --from writer windows:hunter "消息"`
+→ dispatch_to 解析 peer:project 格式
+→ 写 remote-pending.jsonl → daemon heartbeat drain → bot 发 relay 群
+→ 对端 daemon 接收执行
+```
+
+### Packet 协议
+
+- 前缀：`[METAME_REMOTE_DISPATCH]`
+- 编码：Base64(JSON)
+- 签名：HMAC-SHA256，payload = packet body 去掉 sig 字段
+- 去重：5 分钟 TTL Map，按 packet.id 去重
+
+### 关键模块
+
+| 模块 | 职责 |
+|------|------|
+| `daemon-remote-dispatch.js` | 编解码、签名验签、去重、配置解析、`parseRemoteTargetRef` |
+| `daemon.js:sendRemoteDispatch()` | 构造签名 packet → 通过飞书 bot 发 relay 群 |
+| `daemon.js:handleRemoteDispatchMessage()` | 接收端：decode → verify → dedup → 执行或投递结果 |
+| `daemon-bridges.js` | Feishu bridge 拦截 relay 群消息 + `_dispatchToTeamMember` 远端分流 |
+| `daemon-admin-commands.js` | `/dispatch peers` 查看配置 + `/dispatch to peer:project` 手动派发 |
+| `scripts/bin/dispatch_to` | 支持 `peer:project` 格式 → 写 `remote-pending.jsonl` |
+| `team-dispatch.js` | `buildTeamRosterHint()` 为远端成员生成 `peer:key` 格式命令 |
+| `hooks/team-context.js` | intent hook 注入远端 `peer:key` dispatch 命令 |
+
+### 管理命令
+
+- `/dispatch peers`：查看远端配置（self peer、relay chat、所有远端成员列表）
+- `/dispatch to windows:hunter <任务>`：手动跨设备派发
+- `/dispatch to 猎手 <任务>`：按昵称解析，自动检测 `member.peer` 走远端
+
+## 12. 私人配置保护
+
+- `daemon.yaml` 是用户私人配置，包含 API keys、chat IDs、个人项目配置
+- **绝不上传**到代码仓库，已加入 `.gitignore`
+- 仓库只追踪 `scripts/daemon-default.yaml`（模板文件）
+- 部署流程（`node index.js`）不会覆盖用户的 `~/.metame/daemon.yaml`
+- 同样不应上传的文件：`MEMORY.md`、`SOUL.md`、`.env*`
+- Agent 在执行任务时，**绝不能** `cp scripts/daemon.yaml ~/.metame/daemon.yaml`，这会覆盖用户私人配置
+
+## 13. 变更后维护动作
 
 1. `npm test`
 2. `npm run sync:plugin`

package/scripts/docs/pointer-map.md

@@ -1,6 +1,6 @@
 # MetaMe 脚本/文档指针地图
 
-> 目的：回答“这段能力在哪个文件”“当前升级做到哪一步”“先看哪个脚本”。
+> 目的：回答"这段能力在哪个文件""当前升级做到哪一步""先看哪个脚本"。
 
 ## 快速入口
 
@@ -41,22 +41,71 @@
 - Agent 命令处理（新）：
   - `scripts/daemon-agent-commands.js`
   - 关键点：`createAgentCommandHandler()` 处理 `/agent`、`/activate`、`/resume`；
-    `/agent soul [repair|edit]`；`pendingActivations` 无 TTL（消费即删）；防止创建群自激活
+    `/agent soul [repair|edit]`；`pendingActivations` 无 TTL（消费即删）；防止创建群自激活；
+    `/agent new team` 三步向导（name → members → cwd）；
+    `/agent-team-dir` 回调处理目录选择并最终写入 daemon.yaml `team` 段；
+    `pendingTeamFlows` Map 维护向导中间状态
 
 - 路由与 Agent 创建：
   - `scripts/daemon-command-router.js`
   - `scripts/daemon-agent-tools.js`
   - 关键点：自然语言提取 `codex` 关键词；默认 `claude` 不写 `engine` 字段，仅 `codex` 持久化 `engine: codex`；
-    `bindAgentToChat()` 自动调用 `ensureAgentMetadata()` 建立 soul 层
+    `bindAgentToChat()` 自动调用 `ensureAgentMetadata()` 建立 soul 层；
+    `_detectTeamIntent()` 自然语言意图识别（含负样本过滤），识别"建团队"意图后自动路由到 `/agent new team` 向导
 
 - 会话命令与兼容边界：
   - `scripts/daemon-exec-commands.js`
-  - 关键点：`/stop` 引擎中性；`/compact` 在 codex 会话返回“暂不支持”
+  - 关键点：`/stop` 引擎中性；`/compact` 在 codex 会话返回"暂不支持"
 
 - 运行时引擎切换与诊断：
   - `scripts/daemon-admin-commands.js`
   - 关键点：`/engine` 切换默认引擎；`/doctor` 按默认引擎检查 CLI 可用性（Claude/Codex）并兼容自定义 provider 模型名
 
+## 团队 Dispatch 与跨设备通信定位
+
+- 共享 Dispatch 工具：
+  - `scripts/team-dispatch.js`
+  - 关键点：`resolveProjectKey()` 名称/昵称解析（含 team member `parent/member` 复合键）；
+    `findTeamMember()` 文本前缀匹配团队成员昵称；
+    `buildTeamRosterHint()` 生成团队上下文块（远端成员自动带 `peer:key` 前缀）；
+    `buildEnrichedPrompt()` 注入共享上下文（now.md + _latest.md + inbox）
+
+- 远端 Dispatch 协议：
+  - `scripts/daemon-remote-dispatch.js`
+  - 关键点：`normalizeRemoteDispatchConfig()` 解析 `feishu.remote_dispatch` 配置；
+    `parseRemoteTargetRef()` 解析 `peer:project` 格式；
+    `encodePacket()`/`decodePacket()` Base64 + HMAC-SHA256 编解码；
+    `verifyPacket()` 签名验证；
+    `isDuplicate()` 5 分钟 TTL 去重；
+    `isRemoteMember()` 检测 `member.peer` 字段
+
+- Daemon 远端 Dispatch 入口：
+  - `scripts/daemon.js`
+  - 关键点：`sendRemoteDispatch()` 构造签名 packet → 飞书 bot 发 relay 群；
+    `handleRemoteDispatchMessage()` 接收端逻辑（decode → verify → dedup → 按 type 路由）；
+    `remote-pending.jsonl` drain（heartbeat 中处理 dispatch_to CLI 写入的远端队列）
+
+- Bridge 集成：
+  - `scripts/daemon-bridges.js`
+  - 关键点：Feishu bridge `startReceiving` 回调最前面拦截 relay 群消息 → `handleRemoteDispatchMessage`；
+    `_dispatchToTeamMember` 检测 `isRemoteMember(member)` → 走 `sendRemoteDispatch` 而非本地 handleCommand
+
+- Dispatch CLI：
+  - `scripts/bin/dispatch_to`
+  - 关键点：支持 `peer:project` 格式 → `sendRemoteViaRelay()`；
+    `--team` broadcast 自动分流远端成员写 `remote-pending.jsonl`；
+    本地走 Unix socket / `pending.jsonl` 降级
+
+- 管理命令：
+  - `scripts/daemon-admin-commands.js`
+  - 关键点：`/dispatch peers` 查看远端配置；
+    `/dispatch to peer:project` 手动远端派发；
+    按昵称解析到远端 member 时自动走 `sendRemoteDispatch`
+
+- Intent Hook：
+  - `scripts/hooks/team-context.js`
+  - 关键点：检测通信意图 → 注入 dispatch_to 命令提示；远端成员自动带 `peer:key` 前缀
+
 ## Mentor Mode（Step 1-4）定位
 
 - Step 1 数据基建：
@@ -90,6 +139,11 @@
 - 夜间反思文档：`~/.metame/memory/decisions/`、`~/.metame/memory/lessons/`
 - 知识胶囊：`~/.metame/memory/capsules/`
 - 复盘文档：`~/.metame/memory/postmortems/`
+- Dispatch 队列：`~/.metame/dispatch/pending.jsonl`（本地 socket 降级）
+- 远端 Dispatch 队列：`~/.metame/dispatch/remote-pending.jsonl`（跨设备中继）
+- 共享进度白板：`~/.metame/memory/now/shared.md`
+- Agent 最新产出：`~/.metame/memory/agents/{key}_latest.md`
+- Agent 收件箱：`~/.metame/memory/inbox/{key}/`（未读），`read/`（已归档）
 - **Agent Soul 层**：`~/.metame/agents/<agent_id>/`
   - `agent.yaml` — id / name / engine / aliases
   - `soul.md` — 身份定义（主文件，项目目录的 SOUL.md 是其链接）
@@ -102,7 +156,8 @@
 1. 先看配置：`~/.metame/daemon.yaml` 与 `scripts/daemon-default.yaml`
 2. 再看命令入口：`scripts/daemon-admin-commands.js`、`scripts/daemon-command-router.js`、`scripts/daemon-exec-commands.js`
 3. 再看执行链路：`scripts/daemon-engine-runtime.js` → `scripts/daemon-claude-engine.js` → `scripts/mentor-engine.js`
-4. 最后看离线任务：`scripts/distill.js`、`scripts/memory-extract.js`、`scripts/memory-nightly-reflect.js`
+4. 团队/跨设备：`scripts/team-dispatch.js` → `scripts/daemon-remote-dispatch.js` → `scripts/daemon-bridges.js`
+5. 最后看离线任务：`scripts/distill.js`、`scripts/memory-extract.js`、`scripts/memory-nightly-reflect.js`
 
 ## 同步提示
 

package/scripts/feishu-adapter.js

@@ -97,11 +97,14 @@ function createBot(config) {
     const res = await withTimeout(client.im.message.create({
       params: { receive_id_type: 'chat_id' },
       data: { receive_id: chatId, msg_type: 'interactive', content: JSON.stringify(card) },
-    }));
+    }), 30000); // 30s: large card content can be slow; timeout must not fire after delivery
     const msgId = res?.data?.message_id;
     return msgId ? { message_id: msgId } : null;
   }
 
+  let _editBroken = false;      // closure var — safe against destructured calls
+  let _editBrokenAt = 0;        // timestamp when broken; auto-resets after 10min
+
   return {
     /**
      * Send a plain text message
@@ -120,22 +123,26 @@ function createBot(config) {
       return msgId ? { message_id: msgId } : null;
     },
 
-    _editBroken: false, // Set to true if patch API consistently fails
-    async editMessage(chatId, messageId, text) {
-      if (this._editBroken) return false;
+    async editMessage(chatId, messageId, text, header = null) {
+      if (_editBroken && Date.now() - _editBrokenAt < 10 * 60 * 1000) return false;
+      if (_editBroken) _editBroken = false; // auto-reset after 10min
       try {
         // Feishu patch API only works on card (interactive) messages
-        // Update card content with markdown element
-        const card = { schema: '2.0', body: { elements: [{ tag: 'markdown', content: text }] } };
+        // Update card content with markdown element; preserve header if provided
+        const card = { schema: '2.0', body: { elements: [{ tag: 'markdown', content: text, text_size: 'x-large' }] } };
+        if (header && header.title) {
+          card.header = { title: { tag: 'plain_text', content: header.title }, template: header.color || 'blue' };
+        }
         await withTimeout(client.im.message.patch({
           path: { message_id: messageId },
           data: { content: JSON.stringify(card) },
-        }));
+        }), 30000); // 30s: must not timeout after Feishu has applied the patch
         return true;
       } catch (e) {
         const code = e?.code || e?.response?.data?.code;
         if (code === 230001 || code === 230002 || /permission|forbidden/i.test(String(e))) {
-          this._editBroken = true;
+          _editBroken = true;
+          _editBrokenAt = Date.now();
         }
         return false;
       }
@@ -316,7 +323,7 @@ function createBot(config) {
           },
         });
 
-        console.log('[Feishu] Upload response:', JSON.stringify(uploadRes));
+        // Upload response logged at debug level if needed
 
         // Response is { code, msg, data: { file_key } }
         const fileKey = uploadRes?.data?.file_key || uploadRes?.file_key;
@@ -357,42 +364,50 @@ function createBot(config) {
     },
 
     /**
-     * Start WebSocket long connection to receive messages
+     * Start WebSocket long connection to receive messages (with auto-reconnect)
      * @param {function} onMessage - callback(chatId, text, event)
-     * @returns {Promise<{stop: function}>}
+     * @param {object} [opts]
+     * @param {function} [opts.log] - logger function(level, msg)
+     * @returns {Promise<{stop: function, reconnect: function, isAlive: function}>}
      */
-    startReceiving(onMessage) {
-      return new Promise((resolve, reject) => {
-        const wsClient = new Lark.WSClient({
-          appId: app_id,
-          appSecret: app_secret,
-          loggerLevel: Lark.LoggerLevel.info,
-        });
-
-        // Dedup: track recent message_ids (Feishu may redeliver on slow ack)
-        const _seenMsgIds = new Map(); // message_id → timestamp
-        const DEDUP_TTL = 60000; // 60s window
-        function isDuplicate(msgId) {
-          if (!msgId) return false;
-          const now = Date.now();
-          // Cleanup old entries
-          if (_seenMsgIds.size > 200) {
-            for (const [k, t] of _seenMsgIds) {
-              if (now - t > DEDUP_TTL) _seenMsgIds.delete(k);
-            }
+    startReceiving(onMessage, opts = {}) {
+      const _log = opts.log || ((lvl, msg) => console.log(`[feishu] [${lvl}] ${msg}`));
+      let stopped = false;
+      let currentWs = null;
+      let healthTimer = null;
+      let reconnectTimer = null;
+      let reconnectDelay = 5000; // start 5s, doubles up to 60s
+      const MAX_RECONNECT_DELAY = 60000;
+      const HEALTH_CHECK_INTERVAL = 90000; // check every 90s
+      const SILENT_THRESHOLD = 300000; // 5 min no SDK activity → suspect dead
+
+      // Track last SDK activity (any event received = alive)
+      let _lastActivityAt = Date.now();
+      function touchActivity() { _lastActivityAt = Date.now(); }
+
+      // Dedup: track recent message_ids (Feishu may redeliver on slow ack)
+      const _seenMsgIds = new Map(); // message_id → timestamp
+      const DEDUP_TTL = 60000; // 60s window
+      function isDuplicate(msgId) {
+        if (!msgId) return false;
+        const now = Date.now();
+        if (_seenMsgIds.size > 200) {
+          for (const [k, t] of _seenMsgIds) {
+            if (now - t > DEDUP_TTL) _seenMsgIds.delete(k);
           }
-          if (_seenMsgIds.has(msgId)) return true;
-          _seenMsgIds.set(msgId, now);
-          return false;
         }
+        if (_seenMsgIds.has(msgId)) return true;
+        _seenMsgIds.set(msgId, now);
+        return false;
+      }
 
-        const eventDispatcher = new Lark.EventDispatcher({}).register({
+      function buildDispatcher() {
+        return new Lark.EventDispatcher({}).register({
           'im.message.receive_v1': async (data) => {
+            touchActivity();
             try {
               const msg = data.message;
               if (!msg) return;
-
-              // Dedup by message_id
               if (isDuplicate(msg.message_id)) return;
 
               const chatId = msg.chat_id;
@@ -408,35 +423,30 @@ function createBot(config) {
                   text = msg.content || '';
                 }
               } else if (msg.message_type === 'file' || msg.message_type === 'image' || msg.message_type === 'media') {
-                // File, image or media (video) message
                 try {
                   const content = JSON.parse(msg.content);
                   fileInfo = {
                     messageId: msg.message_id,
                     fileKey: content.file_key || content.image_key,
                     fileName: content.file_name || (content.image_key ? `image_${Date.now()}.png` : `file_${Date.now()}`),
-                    msgType: msg.message_type, // 'file', 'image', or 'media'
+                    msgType: msg.message_type,
                   };
                 } catch {}
               }
 
-              // Strip @mention prefix if present
               text = text.replace(/@_user_\d+\s*/g, '').trim();
 
               if (text || fileInfo) {
-                // Fire-and-forget: don't block the event loop (SDK needs fast ack)
                 Promise.resolve().then(() => onMessage(chatId, text, data, fileInfo, senderId)).catch((err) => {
                   try { console.error(`[feishu-adapter] onMessage error: ${err && err.message || err}`); } catch { }
                 });
               }
-            } catch (e) {
-              // Non-fatal
-            }
+            } catch (e) { /* Non-fatal */ }
           },
           'card.action.trigger': async (data) => {
+            touchActivity();
             try {
               const action = data.action;
-              // Try multiple possible chatId fields
               const chatId = data.open_chat_id || data.chat_id
                 || (data.context && data.context.open_chat_id)
                 || (data.event && data.event.open_chat_id);
@@ -449,27 +459,86 @@ function createBot(config) {
                 const cmd = action.value && action.value.cmd;
                 if (cmd) {
                   Promise.resolve().then(() => onMessage(chatId, cmd, data, null, senderId)).catch((err) => {
-                  try { console.error(`[feishu-adapter] card action error: ${err && err.message || err}`); } catch { }
-                });
+                    try { console.error(`[feishu-adapter] card action error: ${err && err.message || err}`); } catch { }
+                  });
                 }
               }
-            } catch (e) {
-              // Non-fatal
-            }
+            } catch (e) { /* Non-fatal */ }
             return {};
           },
         });
+      }
 
-        wsClient.start({ eventDispatcher });
+      function connect() {
+        if (stopped) return;
+        try {
+          currentWs = new Lark.WSClient({
+            appId: app_id,
+            appSecret: app_secret,
+            loggerLevel: Lark.LoggerLevel.info,
+          });
+          const eventDispatcher = buildDispatcher();
+          currentWs.start({ eventDispatcher });
+          touchActivity();
+          reconnectDelay = 5000; // reset backoff on successful start
+          _log('INFO', 'Feishu WebSocket connecting...');
+        } catch (err) {
+          _log('ERROR', `Feishu WSClient.start failed: ${err.message}`);
+          scheduleReconnect();
+        }
+      }
 
-        // SDK doesn't provide a clean "connected" callback,
-        // resolve immediately — errors will show in logs
-        resolve({
-          stop() {
-            // SDK doesn't expose a clean shutdown method
-            // Process exit will clean up
-          },
-        });
+      function scheduleReconnect() {
+        if (stopped) return;
+        clearTimeout(reconnectTimer);
+        _log('INFO', `Feishu reconnecting in ${reconnectDelay / 1000}s...`);
+        reconnectTimer = setTimeout(() => {
+          _log('INFO', 'Feishu reconnecting now...');
+          connect();
+        }, reconnectDelay);
+        reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
+      }
+
+      // Health check: detect silent WebSocket death via API probe
+      function startHealthCheck() {
+        clearInterval(healthTimer);
+        healthTimer = setInterval(async () => {
+          if (stopped) return;
+          const silentMs = Date.now() - _lastActivityAt;
+          if (silentMs < SILENT_THRESHOLD) return; // recently active, skip
+          // Probe: try a lightweight API call to verify token + connectivity
+          try {
+            await withTimeout(client.im.chat.list({ params: { page_size: 1 } }), 10000);
+            // API works — connection might still be alive, just quiet. Reset activity.
+            touchActivity();
+          } catch (err) {
+            _log('WARN', `Feishu health check failed after ${Math.round(silentMs / 1000)}s silence: ${err.message} — reconnecting`);
+            try { currentWs?.stop?.(); } catch { /* ignore */ }
+            currentWs = null;
+            connect();
+          }
+        }, HEALTH_CHECK_INTERVAL);
+      }
+
+      // Initial connect
+      connect();
+      startHealthCheck();
+
+      return Promise.resolve({
+        stop() {
+          stopped = true;
+          clearTimeout(reconnectTimer);
+          clearInterval(healthTimer);
+          currentWs = null;
+        },
+        reconnect() {
+          _log('INFO', 'Feishu manual reconnect triggered');
+          reconnectDelay = 5000;
+          connect();
+        },
+        isAlive() {
+          return !stopped && (Date.now() - _lastActivityAt) < SILENT_THRESHOLD;
+        },
       });
     },