@vrs-soft/wecom-aibot-mcp 3.4.2 → 3.4.4

package/dist/channel-server.js

@@ -208,6 +208,9 @@ let sseConnected = false;
 let sseAbortController = null;
 let mcpServer = null;
 let sseCurrentCcId = undefined;
+// v3.4.3: 暴露给 verify_sse_health 工具，判断"是否假在线"
+let sseLastChunkAt = 0;
+let sseWatchdogActive = false;
 // 保存首次 enter_headless_mode 的参数，重连时原样复用
 let sseRobotId = undefined;
 let sseProjectDir = undefined;
@@ -361,6 +364,7 @@ function connectSSE(ccId) {
             clearInterval(watchdogTimer);
             watchdogTimer = null;
         }
+        sseWatchdogActive = false; // v3.4.3
     };
     // SSE fetch 配置：添加 keep-alive headers 确保连接稳定
     fetch(sseUrl, {
@@ -407,6 +411,7 @@ function connectSSE(ccId) {
         let buffer = '';
         let messageCount = 0;
         let lastChunkAt = Date.now();
+        sseLastChunkAt = lastChunkAt; // v3.4.3: 暴露到模块作用域
         let currentEvent = 'message'; // SSE event type，由 `event: xxx` 行设置；空行复位
         // Watchdog：>45s 没收到任何 chunk（含 daemon 端的 `: heartbeat` 注释）
         // 视为单向 TCP 死链，主动 abort 让 catch 分支触发 reconnect。
@@ -421,11 +426,13 @@ function connectSSE(ccId) {
                 catch { /* ignore */ }
             }
         }, 15000);
+        sseWatchdogActive = true; // v3.4.3
         while (true) {
             const { done, value } = await reader.read();
             if (done) {
                 logChannel('SSE stream ended');
                 clearWatchdog();
+                sseWatchdogActive = false; // v3.4.3
                 sseConnected = false;
                 // 非主动断开时自动重连
                 if (!sseAbortController?.signal.aborted) {
@@ -435,6 +442,7 @@ function connectSSE(ccId) {
                 break;
             }
             lastChunkAt = Date.now();
+            sseLastChunkAt = lastChunkAt; // v3.4.3
             const chunk = decoder.decode(value, { stream: true });
             logChannel('SSE chunk received', { bytes: chunk.length, preview: chunk.slice(0, 100) });
             buffer += chunk;
@@ -609,6 +617,108 @@ function registerChannelTools(server) {
         return forwardToHttpMcp('check_connection', {});
     });
     // ============================================
+    // 工具 4b: verify_sse_health（v3.4.3）—— 比对本地 SSE 状态 vs daemon 注册表
+    // 用于 "CC 自己以为还连着但 daemon 已经看不到" 的 split-brain 诊断
+    // ============================================
+    server.tool('verify_sse_health', '比对本地 channel-server 的 SSE 状态和远端 daemon 注册表，诊断"假在线/假离线"问题。auto_fix=true 时检测到 split-brain 自动 abort 触发重连。', {
+        cc_id: z.string().describe('要检查的 CC 标识（必填，多 CC 部署下唯一确认目标）'),
+        auto_fix: z.boolean().optional().default(false).describe('为 true 时若发现 stale_local 自动 abort SSE 触发重连'),
+    }, async ({ cc_id, auto_fix }) => {
+        const now = Date.now();
+        const localIdleMs = sseLastChunkAt ? now - sseLastChunkAt : -1;
+        const localView = {
+            sseConnected,
+            idleMs: localIdleMs,
+            watchdogActive: sseWatchdogActive,
+            ccId: sseCurrentCcId || null,
+        };
+        // 调 daemon list_active_ccs 看注册表里有没有 ccId（/state 没暴露 ccIdRegistry，
+        // 但 list_active_ccs 走 MCP 转发，返回结构含 lastOnline）
+        let remoteView = { reachable: false, error: 'unknown' };
+        try {
+            const listRes = await forwardToHttpMcp('list_active_ccs', { cc_id });
+            const text = listRes?.content?.[0]?.text;
+            const data = text ? JSON.parse(text) : {};
+            // list_active_ccs.self 是 caller 自己，data.ccs 是其他在线 CC
+            // 检查 cc_id 是不是 self（caller 在 registry 自然没问题，复用本地心跳新鲜度）
+            // 或者在 ccs 列表里
+            const isSelf = data.self === cc_id;
+            const otherEntry = (data.ccs || []).find((e) => e?.ccId === cc_id);
+            if (isSelf) {
+                remoteView = {
+                    reachable: true,
+                    inRegistry: true,
+                    note: 'cc_id is self — daemon 注册表里一定有，参考 local.idleMs 判断新鲜度',
+                    lastOnlineMs: localIdleMs,
+                };
+            }
+            else if (otherEntry) {
+                remoteView = {
+                    reachable: true,
+                    inRegistry: true,
+                    lastOnlineMs: otherEntry.lastOnline ? now - otherEntry.lastOnline : -1,
+                    robotName: otherEntry.robotName,
+                    mode: otherEntry.mode,
+                };
+            }
+            else {
+                remoteView = {
+                    reachable: true,
+                    inRegistry: false,
+                    knownCcs: [data.self, ...(data.ccs || []).map((e) => e?.ccId)].filter(Boolean),
+                };
+            }
+        }
+        catch (e) {
+            remoteView = { reachable: false, error: e?.message || String(e) };
+        }
+        // verdict
+        let verdict;
+        let message;
+        if (!remoteView.reachable) {
+            verdict = 'remote_unreachable';
+            message = `daemon 不可达：${remoteView.error}。channel-server 本地 sseConnected=${sseConnected}，但无法验证 daemon 视角。`;
+        }
+        else if (!localView.ccId) {
+            verdict = 'never_entered';
+            message = 'channel-server 这个进程从未调过 enter_headless_mode，没建 SSE。让 LLM 跑一次 enter_headless_mode 即可。';
+        }
+        else if (!remoteView.inRegistry) {
+            verdict = 'stale_remote';
+            message = `daemon 注册表里看不到 ${cc_id}（被 stale-clean 掉了，或从未注册）。需要重新调 enter_headless_mode 让 daemon 重新认你。`;
+        }
+        else if (!sseConnected || (localIdleMs > 0 && localIdleMs > 60000)) {
+            verdict = 'stale_local';
+            message = `channel-server 本地 SSE 死了（connected=${sseConnected}, idleMs=${localIdleMs}）但 daemon 还以为你在线。watchdog 应该 45s 触发但显然没。需要重连。`;
+        }
+        else if (remoteView.lastOnlineMs > 60000) {
+            verdict = 'split_brain';
+            message = `本地心跳活（idleMs=${localIdleMs}ms）但 daemon 上 lastOnline 是 ${Math.round(remoteView.lastOnlineMs / 1000)}s 前——路由可能有 bug，但你的 SSE 应该还在工作。`;
+        }
+        else {
+            verdict = 'ok';
+            message = `健康：本地 idleMs=${localIdleMs}ms，daemon 上 lastOnline=${Math.round(remoteView.lastOnlineMs / 1000)}s 前。`;
+        }
+        let autoFixed = false;
+        if (auto_fix && (verdict === 'stale_local')) {
+            try {
+                logger.info('verify_sse_health auto_fix: aborting SSE to trigger reconnect', { ccId: cc_id });
+                sseAbortController?.abort();
+                autoFixed = true;
+                message += ' [auto_fix] 已触发 SSE abort，约 3 秒后 channel-server 自动重连。';
+            }
+            catch (e) {
+                message += ` [auto_fix 失败：${String(e)}]`;
+            }
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ local: localView, remote: remoteView, verdict, message, autoFixed }, null, 2),
+                }],
+        };
+    });
+    // ============================================
     // 工具 4a: CC 间通信 — send_to_cc / list_active_ccs（v2.6.0+）
     // ============================================
     server.tool('send_to_cc', '向同一 daemon 上的另一个 CC 发送消息。目标 CC 收到时会作为 <channel source="cc:..."> 推送唤醒。仅支持同 daemon 间互通。支持 attachments 内联小文档（每个 < 16 KB）；大文档请改用 upload_document。', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrs-soft/wecom-aibot-mcp",
-  "version": "3.4.2",
+  "version": "3.4.4",
   "description": "企业微信智能机器人 MCP 客户端 - 连接 wecom-aibot-server daemon",
   "type": "module",
   "main": "dist/index.js",

package/skills/headless-mode/SKILL.md

@@ -50,27 +50,34 @@ description: 当用户说「现在开始通过微信联系」时触发，进入
 
 ### 3. 调用 enter_headless_mode
 
+**强制前置校验**（避免错绑机器人）：
+- `cc_id` 必须取自步骤 2 读到的配置文件 / 步骤 2.1 生成的项目名
+- `robot_id` 必须取自步骤 2 读到的 `robotName` / 步骤 2.2 用户选定的机器人
+- **禁止用字面量或默认值**填这两个参数。下面所有示例里的 `${...}` 都是占位符，**不是常量**
+
 使用步骤 1 确定的 MCP 前缀：
 
 ```
 ${MCP}enter_headless_mode(
-  cc_id="<项目名>",
-  robot_id="<机器人名称>",
-  mode="<channel 或 http>",
-  project_dir="<项目目录>"
+  cc_id="${步骤 2 / 2.1 得到的 ccId}",
+  robot_id="${步骤 2 / 2.2 得到的 robotName}",
+  mode="${步骤 1 确定的模式}",
+  project_dir="${当前项目目录}"
 )
 ```
 
-例如 Channel 模式：
+例如 Channel 模式（假设步骤 2 已读到 `ccId="知识库", robotName="公司助理"`）：
 ```
-mcp__wecom-aibot-channel__enter_headless_mode(cc_id="知识库", robot_id="CC", mode="channel", project_dir="...")
+mcp__wecom-aibot-channel__enter_headless_mode(cc_id="知识库", robot_id="公司助理", mode="channel", project_dir="...")
 ```
 
-例如 HTTP 模式：
+例如 HTTP 模式（同前提）：
 ```
-mcp__wecom-aibot__enter_headless_mode(cc_id="知识库", robot_id="CC", mode="http", project_dir="...")
+mcp__wecom-aibot__enter_headless_mode(cc_id="知识库", robot_id="公司助理", mode="http", project_dir="...")
 ```
 
+> ⚠️ **示例里的 `公司助理` 是占位文案**，不要照抄。真实值来自 `.claude/wecom-aibot.json` 的 `robotName`，或本次会话中用户用 AskUserQuestion 选定的机器人名。配置存在但读出 `robotName` 与示例不符是正常的 —— 用配置里的，不要用示例里的。
+
 ### 2. 处理返回结果
 
 **返回字段**：