@vrs-soft/wecom-aibot-mcp 1.5.0 → 2.3.0

package/dist/tools/index.js

@@ -20,11 +20,12 @@
  * - 从 Session 自动获取 robotName
  */
 import { z } from 'zod';
-import { listAllRobots } from '../config-wizard.js';
-import { connectRobot, disconnectRobot, getClient, getConnectionState, isRobotOccupied, getRobotOccupiedBy, } from '../connection-manager.js';
-import { generateCcId, registerCcId, unregisterCcId, getRobotByCcId, getCCRegistryEntry, } from '../http-server.js';
-import { subscribeWecomMessageByRobot } from '../message-bus.js';
-import { updateWechatModeConfig, addPermissionHook, removePermissionHook } from '../project-config.js';
+import { listAllRobots, installSkill } from '../config-wizard.js';
+import { connectRobot, disconnectRobot, getClient, getConnectionState, } from '../connection-manager.js';
+import { registerCcId, unregisterCcId, getRobotByCcId, getProjectDirByCcId, generateCcId, } from '../http-server.js';
+import { subscribeWecomMessageByCcId } from '../message-bus.js';
+import { updateWechatModeConfig, loadWechatModeConfig, addPermissionHook, removePermissionHook, addTaskCompletedHook, removeTaskCompletedHook } from '../project-config.js';
+import { logger } from '../logger.js';
 // 辅助函数：从 ccId 获取客户端
 async function getConnectedClient(ccId) {
     if (!ccId) {
@@ -47,15 +48,49 @@ export function registerTools(server) {
     server.tool('send_message', '向企业微信发送消息（用于通知用户）。群聊时传入 chatid 可回复到群里。', {
         content: z.string().describe('消息内容（支持 Markdown）'),
         target_user: z.string().optional().describe('目标用户/群 ID（可选）'),
-        cc_id: z.string().optional().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
+        cc_id: z.string().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
     }, async ({ content, target_user, cc_id }, extra) => {
         const { error, client } = await getConnectedClient(cc_id);
         if (error || !client) {
             return { content: [{ type: 'text', text: JSON.stringify({ error }) }] };
         }
-        const success = await client.sendText(content, target_user);
+        // 自动在消息头部添加 ccId 标识（多对一场景区分）
+        const prefixedContent = `【${cc_id}】${content}`;
+        const success = await client.sendText(prefixedContent, target_user);
+        return {
+            content: [{
+                    type: 'text',
+                    text: success
+                        ? '✅ 消息已发送，继续轮询，继续等待'
+                        : '发送失败，请检查连接状态',
+                }],
+        };
+    });
+    // ============================================
+    // 工具 2: 心跳检查（HTTP 模式）
+    // ============================================
+    server.tool('heartbeat_check', '心跳检查，提示智能体继续轮询（仅 HTTP 模式使用）', {}, async () => {
         return {
-            content: [{ type: 'text', text: success ? '消息已发送' : '发送失败，请检查连接状态' }],
+            content: [{
+                    type: 'text',
+                    text: '心跳检查：如有执行结果请发送，如果没有应继续轮询 get_pending_messages 接口！',
+                }],
+        };
+    });
+    // ============================================
+    // 工具 3: 保存心跳 job ID（HTTP 模式）
+    // ============================================
+    server.tool('update_heartbeat_job_id', '保存心跳定时任务 job ID 到配置文件（HTTP 模式用，/loop 创建后调用）', {
+        cc_id: z.string().describe('CC 唯一标识'),
+        job_id: z.string().describe('由 /loop 命令返回的 job ID'),
+    }, async ({ cc_id, job_id }) => {
+        const projectDir = getProjectDirByCcId(cc_id) || process.cwd();
+        updateWechatModeConfig(projectDir, { heartbeatJobId: job_id });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ success: true, projectDir, job_id }),
+                }],
         };
     });
     // ============================================
@@ -77,10 +112,10 @@ export function registerTools(server) {
     // ============================================
     // 工具 6: 获取待处理消息
     // ============================================
-    server.tool('get_pending_messages', '获取待处理的微信消息。支持长轮询：传入 timeout_ms 后阻塞等待，有消息立即返回，无消息等到超时。', {
+    server.tool('get_pending_messages', '获取待处理的微信消息。支持长轮询：传入 timeout_ms 后阻塞等待，有消息立即返回，无消息等到超时。超时后继续轮询，不要停止。', {
         clear: z.boolean().optional().default(true).describe('是否清除已获取的消息'),
-        timeout_ms: z.number().optional().default(0).describe('长轮询超时（毫秒），0 表示立即返回，最大 60000'),
-        cc_id: z.string().optional().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
+        timeout_ms: z.number().optional().default(30000).describe('长轮询超时（毫秒），默认 30000，最大 60000'),
+        cc_id: z.string().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
     }, async ({ clear, timeout_ms = 0, cc_id }) => {
         const { error, client, robotName } = await getConnectedClient(cc_id);
         if (error || !client) {
@@ -91,12 +126,21 @@ export function registerTools(server) {
                     }],
             };
         }
+        // 消息格式化：返回给智能体的数据结构
+        // 字段说明：
+        // - content: 用户发送的消息内容
+        // - from: 发送者用户 ID
+        // - chatid: 会话 ID（单聊=用户ID，群聊=群ID）
+        // - chattype: 会话类型（single/group）
+        // - time: 消息时间（ISO 格式）
+        // - quoteContent: 用户引用的消息内容（可选，用户回复时引用的上一条消息）
         const formatMessages = (msgs) => msgs.map(m => ({
             content: m.content,
             from: m.from_userid,
             chatid: m.chatid,
             chattype: m.chattype,
             time: new Date(m.timestamp).toISOString(),
+            quoteContent: m.quoteContent,
         }));
         // 先检查是否已有积压消息
         const existing = client.getPendingMessages(false);
@@ -110,20 +154,27 @@ export function registerTools(server) {
                     }],
             };
         }
-        // 无积压且不等待，立即返回空
+        // 无积压且不等待，立即返回空（timeout_ms 传 0 时）
         const waitMs = Math.min(timeout_ms, 60000);
         if (waitMs <= 0) {
             return {
-                content: [{ type: 'text', text: JSON.stringify({ count: 0, messages: [] }) }],
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            count: 0,
+                            messages: [],
+                            hint: 'timeout_ms=0 仅用于检查积压消息，请传入 timeout_ms=30000 开始长轮询'
+                        }),
+                    }],
             };
         }
-        // 长轮询：订阅消息总线，等待该机器人的消息
+        // 长轮询：订阅消息总线，等待该机器人且匹配 ccId 的消息
         const arrived = await new Promise(resolve => {
             const timer = setTimeout(() => {
                 sub.unsubscribe();
                 resolve(null);
             }, waitMs);
-            const sub = subscribeWecomMessageByRobot(robotName, (msg) => {
+            const sub = subscribeWecomMessageByCcId(robotName, cc_id, (msg) => {
                 clearTimeout(timer);
                 sub.unsubscribe();
                 resolve(msg);
@@ -131,7 +182,15 @@ export function registerTools(server) {
         });
         if (arrived === null) {
             return {
-                content: [{ type: 'text', text: JSON.stringify({ count: 0, messages: [], timeout: true }) }],
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            count: 0,
+                            messages: [],
+                            waiting: true,
+                            hint: '继续等待，继续轮询'
+                        }),
+                    }],
             };
         }
         // 消息到了，取出所有积压（含刚到的）
@@ -183,6 +242,69 @@ npx @vrs-soft/wecom-aibot-mcp
         return { content: [{ type: 'text', text: guide }] };
     });
     // ============================================
+    // 工具: 获取配置需求（供 skill 自动配置）
+    // ============================================
+    server.tool('get_setup_requirements', '获取 MCP 配置需求，用于 skill 自动配置本地环境（权限、Hook、skill）。启动时调用检查配置是否完整。', {}, async () => {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        version: '2.0.0',
+                        requirements: {
+                            // 权限配置需求
+                            permissions: {
+                                file: '~/.claude/settings.local.json',
+                                allow: [
+                                    'mcp__wecom-aibot__send_message',
+                                    'mcp__wecom-aibot__heartbeat_check',
+                                    'mcp__wecom-aibot__get_pending_messages',
+                                    'mcp__wecom-aibot__check_connection',
+                                    'mcp__wecom-aibot__list_robots',
+                                    'mcp__wecom-aibot__enter_headless_mode',
+                                    'mcp__wecom-aibot__exit_headless_mode',
+                                    'mcp__wecom-aibot__get_connection_stats',
+                                    'mcp__wecom-aibot__get_setup_requirements',
+                                    'mcp__wecom-aibot__get_skill',
+                                    'mcp__wecom-aibot__update_heartbeat_job_id',
+                                ],
+                            },
+                            // Hook 配置需求
+                            hooks: {
+                                file: '~/.claude/settings.local.json',
+                                PermissionRequest: {
+                                    script: '~/.wecom-aibot-mcp/permission-hook.sh',
+                                    description: '审批请求通过微信发送',
+                                },
+                            },
+                            // Skill 安装需求
+                            skills: {
+                                projectDir: '.claude/skills/headless-mode',
+                                files: ['SKILL.md'],
+                                skillUrl: `${process.env.MCP_URL || 'http://127.0.0.1:18963'}/skill`, // 远程部署下载 URL
+                            },
+                        },
+                        // 检查命令（供 skill 验证）
+                        checkCommands: {
+                            permissions: '检查 ~/.claude/settings.local.json 是否包含 mcp__wecom-aibot__ 权限',
+                            hook: '检查 ~/.claude/settings.local.json 是否包含 PermissionRequest hook',
+                            skill: '检查 ~/.claude/skills/headless-mode/SKILL.md 是否存在',
+                        },
+                        // 模式说明
+                        modes: {
+                            channel: {
+                                description: 'SSE 推送模式，微信消息自动唤醒 Agent',
+                                capability: 'claude/channel',
+                            },
+                            http: {
+                                description: '轮询模式，Agent 需调用 get_pending_messages 和 heartbeat_check',
+                                capability: null,
+                            },
+                        },
+                    }, null, 2),
+                }],
+        };
+    });
+    // ============================================
     // 工具 7: 添加新机器人配置
     // ============================================
     server.tool('add_robot_config', '添加新机器人配置', {
@@ -204,43 +326,40 @@ npx @vrs-soft/wecom-aibot-mcp
     // ============================================
     // 工具 8: 列出所有机器人
     // ============================================
-    server.tool('list_robots', '列出配置中的所有机器人及其状态', {}, async () => {
+    server.tool('list_robots', '列出配置中的所有机器人。多 CC 可共享同一机器人，直接选择使用即可。', {}, async () => {
         const allRobots = listAllRobots();
-        const state = getConnectionState();
-        const robots = allRobots.map(robot => {
-            const occupied = isRobotOccupied(robot.name);
-            const occupiedBy = occupied ? getRobotOccupiedBy(robot.name) : null;
-            const connected = state.robotName === robot.name && state.connected;
-            return {
-                name: robot.name,
-                botId: robot.botId,
-                targetUser: robot.targetUserId,
-                status: connected ? 'connected' : (occupied ? 'occupied' : 'available'),
-                occupiedBy,
-            };
-        });
+        // 返回完整信息，包括 botId 用于区分同名机器人
+        const robotList = allRobots.map((robot, index) => ({
+            index: index + 1,
+            name: robot.name,
+            botId: robot.botId?.slice(0, 12) + '...', // 只显示前12位
+            targetUser: robot.targetUserId,
+        }));
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify({
-                        robots,
-                        total: robots.length,
-                        connected: robots.filter(r => r.status === 'connected').length,
-                        occupied: robots.filter(r => r.status === 'occupied').length,
-                    }, null, 2),
+                    text: JSON.stringify({ robots: robotList }, null, 2),
                 }],
         };
     });
     // ============================================
-    // 工具 10: 进入 headless 模式
+    // 工具 9: 进入 headless 模式
     // ============================================
     server.tool('enter_headless_mode', '进入微信模式，建立 WebSocket 连接。当用户说「现在开始通过微信联系」时调用。', {
-        agent_name: z.string().describe('智能体名称'),
+        agent_name: z.string().optional().describe('智能体/项目名称（用于生成 ccId，如项目名）'),
+        cc_id: z.string().optional().describe('CC 唯一标识（可选，未传入时服务端自动生成）'),
         robot_id: z.string().optional().describe('指定机器人名称或序号'),
         project_dir: z.string().optional().describe('项目目录路径（用于写入配置文件）'),
+        mode: z.enum(['channel', 'http']).optional().default('http')
+            .describe('运行模式：channel=SSE推送(推荐)，http=轮询(兼容)'),
         auto_approve: z.boolean().optional().default(true).describe('超时自动审批（默认 true）'),
         auto_approve_timeout: z.number().optional().default(600).describe('自动审批超时时间（秒，默认 600 即 10 分钟）'),
-    }, async ({ agent_name, robot_id, project_dir, auto_approve, auto_approve_timeout }, extra) => {
+    }, async ({ agent_name, cc_id, robot_id, project_dir, mode, auto_approve, auto_approve_timeout }, extra) => {
+        // 获取项目目录
+        const projectDir = project_dir || process.cwd();
+        // 智能体名称（用于生成 ccId）
+        // 优先级：agent_name > cc_id > 项目目录名 > 'cc'
+        const effectiveAgentName = agent_name || cc_id || projectDir.split('/').pop() || 'cc';
         const allRobots = listAllRobots();
         if (allRobots.length === 0) {
             return {
@@ -282,7 +401,7 @@ npx @vrs-soft/wecom-aibot-mcp
             }
         }
         // 连接机器人
-        const result = await connectRobot(selectedRobot.name, agent_name);
+        const result = await connectRobot(selectedRobot.name, effectiveAgentName);
         if (!result.success || !result.client) {
             return {
                 content: [{
@@ -294,22 +413,30 @@ npx @vrs-soft/wecom-aibot-mcp
                     }],
             };
         }
-        // 生成 ccId 并注册到 CC 注册表
-        const ccId = generateCcId();
-        registerCcId(ccId, selectedRobot.name, agent_name);
+        // 如果用户传入 cc_id，直接使用；否则自动生成
+        const finalCcId = cc_id || generateCcId(effectiveAgentName);
+        // 检查 wecom-aibot.json 是否已有匹配的 ccId（重连场景）
+        const existingConfig = loadWechatModeConfig(projectDir);
+        const isReconnect = existingConfig?.ccId === finalCcId;
+        // 注册 ccId 到 CC 注册表（重连直接覆盖，首次注册清理超时条目）
+        registerCcId(finalCcId, selectedRobot.name, effectiveAgentName, mode, projectDir, isReconnect);
         // 更新项目配置文件中的 wechatMode 为 true
-        const projectDir = project_dir || process.cwd();
         updateWechatModeConfig(projectDir, {
             wechatMode: true,
             robotName: selectedRobot.name,
-            ccId,
+            ccId: finalCcId,
             autoApprove: auto_approve,
             autoApproveTimeout: auto_approve_timeout,
         });
+        // 安装 skill 到项目本地（支持远程部署 MCP）
+        const skillResult = installSkill(projectDir);
         // 添加 PermissionRequest hook 到项目 settings.json
         const hookResult = addPermissionHook(projectDir);
-        // 发送确认消息（包含 ccId 标识）
-        await result.client.sendText(`【${ccId}】已进入微信模式，使用机器人「${selectedRobot.name}」。`);
+        // HTTP 模式添加 TaskCompleted hook（Channel 模式不需要，消息自动推送）
+        const taskCompletedHookResult = mode === 'http' ? addTaskCompletedHook(projectDir) : { added: false, message: 'Channel 模式不需要 TaskCompleted hook' };
+        // 发送确认消息（头部标注来源 ccId 和 mode）
+        const modeDesc = mode === 'channel' ? 'Channel模式，消息自动推送' : 'HTTP模式，请定期轮询获取消息';
+        await result.client.sendText(`【${finalCcId}】已进入微信模式(${modeDesc})，使用机器人「${selectedRobot.name}」。`);
         return {
             content: [{
                     type: 'text',
@@ -317,9 +444,16 @@ npx @vrs-soft/wecom-aibot-mcp
                         status: 'entered',
                         headless: true,
                         robotName: selectedRobot.name,
-                        ccId,
+                        ccId: finalCcId,
+                        agentName: effectiveAgentName, // 返回使用的 agentName
+                        mode,
                         hook: hookResult,
-                        message: '用户消息通过 SSE 实时推送，审批请求通过微信发送',
+                        taskCompletedHook: taskCompletedHookResult,
+                        skill: skillResult, // skill 安装结果（如果 success=false，包含 skillUrl）
+                        sseEndpoint: mode === 'channel' ? `http://127.0.0.1:18963/sse/${finalCcId}` : undefined,
+                        message: mode === 'channel'
+                            ? `连接 SSE endpoint: http://127.0.0.1:18963/sse/${finalCcId} 接收推送消息`
+                            : '已进入微信模式(HTTP)',
                     }),
                 }],
         };
@@ -328,10 +462,9 @@ npx @vrs-soft/wecom-aibot-mcp
     // 工具 11: 退出 headless 模式
     // ============================================
     server.tool('exit_headless_mode', '退出微信模式，断开连接。当用户说「结束微信模式」或「我回来了」时调用。', {
-        agent_name: z.string().optional().describe('智能体名称'),
-        cc_id: z.string().optional().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
+        cc_id: z.string().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
         project_dir: z.string().optional().describe('项目目录路径（用于更新配置文件）'),
-    }, async ({ agent_name, cc_id, project_dir }) => {
+    }, async ({ cc_id, project_dir }) => {
         const { error, client, robotName } = await getConnectedClient(cc_id);
         if (error || !client || !robotName) {
             return {
@@ -341,10 +474,8 @@ npx @vrs-soft/wecom-aibot-mcp
                     }],
             };
         }
-        // 发送退出通知
-        const entry = cc_id ? getCCRegistryEntry(cc_id) : null;
-        const name = agent_name || entry?.agentName || '智能体';
-        await client.sendText(`【${name}】已退出微信模式，恢复终端交互。`);
+        // 发送退出通知（使用 ccId 作为标识）
+        await client.sendText(`【${cc_id}】已退出微信模式，恢复终端交互。`);
         // 注销 ccId
         if (cc_id) {
             unregisterCcId(cc_id);
@@ -356,6 +487,8 @@ npx @vrs-soft/wecom-aibot-mcp
         updateWechatModeConfig(projectDir, { wechatMode: false });
         // 删除 PermissionRequest hook 从项目 settings.json
         const hookResult = removePermissionHook(projectDir);
+        // 删除 TaskCompleted hook 从项目 settings.json
+        const taskCompletedHookResult = removeTaskCompletedHook(projectDir);
         return {
             content: [{
                     type: 'text',
@@ -364,6 +497,7 @@ npx @vrs-soft/wecom-aibot-mcp
                         headless: false,
                         robotName,
                         hook: hookResult,
+                        taskCompletedHook: taskCompletedHookResult,
                         message: '审批将使用默认 UI',
                     }),
                 }],
@@ -429,5 +563,40 @@ npx @vrs-soft/wecom-aibot-mcp
                 }],
         };
     });
-    console.log('[mcp] 已注册 11 个工具');
+    // ============================================
+    // 工具 14: 获取 skill 文件内容
+    // ============================================
+    server.tool('get_skill', '获取 headless-mode skill 文件内容，用于写入本地项目目录。远程部署 HTTP MCP 时使用此工具获取 skill 文件。', {}, async () => {
+        const { fileURLToPath } = await import('url');
+        const fs = await import('fs');
+        const path = await import('path');
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const skillPath = path.join(__dirname, '..', '..', 'skills', 'headless-mode', 'SKILL.md');
+        if (!fs.existsSync(skillPath)) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: 'Skill 文件不存在',
+                            skillUrl: `${process.env.MCP_URL || 'http://127.0.0.1:18963'}/skill`,
+                        }),
+                    }],
+            };
+        }
+        const content = fs.readFileSync(skillPath, 'utf-8');
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        content,
+                        filename: 'SKILL.md',
+                        installPath: '.claude/skills/headless-mode/SKILL.md',
+                    }),
+                }],
+        };
+    });
+    logger.log('[mcp] 已注册 14 个工具');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrs-soft/wecom-aibot-mcp",
-  "version": "1.5.0",
+  "version": "2.3.0",
   "description": "企业微信智能机器人 MCP 服务 - Claude Code 审批通道",
   "type": "module",
   "main": "dist/index.js",