@vrs-soft/wecom-aibot-mcp 2.4.12 → 2.4.16

package/README.md

@@ -1,149 +1,201 @@
-# @vrs-soft/wecom-aibot-mcp
+# wecom-aibot-mcp
 
-中文 | [English](README_EN.md)
+English | [中文文档](README_ZH.md)
 
-企业微信智能机器人 MCP 服务 - 让 Claude Code 通过微信远程审批和交互。
+Enterprise WeChat AI Bot MCP Service - Remote Approval Channel for Claude Code
 
-**核心功能**：
-- 远程审批敏感操作（Bash/Write/Edit），微信卡片一键通过/拒绝
-- 离开电脑后通过微信下达任务，实时接收进度通知
-- 支持群聊 @机器人，多机器人、多用户并发
-- 代理企业微信文档 MCP，支持文档和智能表格操作
+> Handle Claude Code approval requests via WeChat, even when away from your computer.
 
----
+## Features
 
-## 效果预览
+- 🔐 **Remote Approval**: Approve/deny sensitive operations (Bash/Write/Edit) via WeChat cards
+- 🔍 **Full Command View**: Approval cards include a detail link — open in browser to view the complete command
+- 💬 **Bidirectional Communication**: Real-time task progress notifications
+- 📱 **Headless Mode**: Switch to WeChat interaction when leaving terminal
+- 🤖 **Multi-bot Support**: Multiple bots for team and group chat scenarios
+- 🌐 **Remote Deployment**: MCP server can be deployed on a remote host with Bearer Token auth
+- 🔄 **Auto-reconnect**: Channel mode automatically reconnects after network interruption or server restart
 
-<img src="docs/approval-card.png" width="320" alt="微信审批卡片" />
+## Architecture
 
-每次 Claude 执行敏感操作（Bash 命令、编辑文件等）时，企业微信会推送审批卡片，点击**允许**或**拒绝**即可实时控制执行权限。超时未响应时，根据配置自动代批（允许项目内操作，拒绝删除命令）。
+```
+┌─────────────────┐      MCP (stdio)      ┌──────────────────────┐
+│  Claude Code    │  ──────────────────▶  │  Channel MCP Proxy   │
+│  (MCP Client)   │  ◀──────────────────  │  (local, SSE client) │
+└─────────────────┘                       └──────────────────────┘
+                                                    │ SSE
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │  wecom-aibot-mcp    │
+                                          │  HTTP MCP Server    │
+                                          │  (local or remote)  │
+                                          └─────────────────────┘
+                                                    │
+                                            WebSocket Connection
+                                                    ↓
+                                          ┌─────────────────────┐
+                                          │  Enterprise WeChat  │
+                                          └─────────────────────┘
+                                                    │
+                                                    ↓
+                                          ┌─────────────────────┐
+                                          │  User WeChat Client │
+                                          │  (Mobile/Desktop)   │
+                                          └─────────────────────┘
+```
 
----
+## Installation
 
-## 使用场景
+### Prerequisites
 
-### 场景一：离开电脑，微信远程监督
+- **Node.js >= 18**
+- Enterprise WeChat account (with bot creation permission)
+- Claude Code
 
-出门开会或离开座位时，告诉 Claude「现在开始通过微信联系」，进入微信模式后：
+### Step 1: Create Enterprise WeChat Bot
 
-- Claude 执行每一步操作前发送审批请求到微信
-- 你在手机上点击**允许 / 拒绝**，Claude 实时响应
-- 设置超时自动审批（`autoApproveTimeout`），无人值守时自动处理项目内操作
+1. Login to WeChat Work admin portal: https://work.weixin.qq.com
+2. Go to "Management Tools" → "Smart Bot"
+3. Click "Create Bot" → "Manual Creation"
+4. Fill in bot name (e.g., "Claude Approval Assistant")
+5. In "API Configuration":
+   - Select "Use Long Connection"
+   - Click "Get Secret"
+6. Record **Bot ID** and **Secret**
 
-### 场景二：微信直接下达任务
+### Step 2: Run Configuration Wizard
 
-不在电脑前，直接在企业微信给机器人发消息：
+```bash
+npx @vrs-soft/wecom-aibot-mcp --setup
+```
 
-- 「帮我跑一下单元测试，把结果发给我」
-- 「把 src/index.ts 里的 TODO 都处理掉」
-- 「最近有什么错误日志？」
+Choose the appropriate role flag:
 
-Claude 执行完成后自动回复进度和结果到微信。
+| Command | Role | Description |
+|---------|------|-------------|
+| `--setup` | Interactive | Guides through local or remote setup |
+| `--setup --server` | Server-side | Configure bot + Token, no local MCP config |
+| `--setup --channel` | Channel client | Connect to remote server, write Channel MCP config |
+| `--setup --server --channel` | Full local | HTTP + Channel full install |
 
-### 场景三：团队共享机器人，群聊协作
+**Start server after setup**:
 
-在企业微信群中 @机器人，多个成员可以同时：
+```bash
+npx @vrs-soft/wecom-aibot-mcp --http-only --start
+```
 
-- 查询项目状态
-- 触发 CI 任务
-- 审批自己负责的操作（审批请求精确路由到对应 Claude 窗口）
+## Commands
 
----
+| Command | Description |
+|---------|-------------|
+| `--start / --stop` | Start/stop background service |
+| `--status` | View service status and bot list |
+| `--config` | Modify default bot configuration |
+| `--add / --delete` | Add/delete bot |
+| `--set-token [token]` | Set Auth Token (for remote deployment) |
+| `--set-token --clear` | Clear Auth Token |
+| `--debug` | Start in foreground with debug output |
+| `--http-only` | Start HTTP MCP Server only (server-side use) |
+| `--channel-only` | Configure Channel MCP only (requires `MCP_URL`) |
+| `--clean-cache` | Clear CC registry cache |
+| `--upgrade` | Force upgrade global configs |
+| `--uninstall` | Complete uninstall |
 
-## 前置条件
+## Run Modes
 
-企业微信管理后台创建智能机器人，连接方式选「使用长连接」，记录 **Bot ID** 和 **Secret** 以及 **DocURL**（文档url）。
+| | Channel Mode | HTTP Mode |
+|-|-------------|-----------|
+| Message delivery | SSE push (instant) | `/loop` heartbeat polling |
+| Latency | Immediate | ≤1 minute |
+| Claude account | claude.ai direct only | Any (including API relay) |
+| Reconnect | Auto (including server restart) | Auto via heartbeat |
 
----
+To enter WeChat mode, tell Claude: **"Now contact me via WeChat"** — this triggers the `headless-mode` skill automatically.
 
-## 安装
+**Claude startup command for Channel mode**:
 
 ```bash
-npx @vrs-soft/wecom-aibot-mcp --setup
+claude --dangerously-load-development-channels server:wecom-aibot-channel
 ```
 
-根据部署角色选择参数：
-
-| 命令 | 角色 | 说明 |
-|------|------|------|
-| `--setup` | 交互式 | 询问本地 / 远程，自动引导 |
-| `--setup --server` | 服务器端 | 配置机器人 + Token，不写本机 MCP 配置 |
-| `--setup --channel` | Channel 客户端 | 连接远程 Server，写入 Channel MCP |
-| `--setup --server --channel` | 本地完整 | HTTP + Channel 全安装 |
+## Usage Example
 
-**Server 端安装后启动**：
+### Headless Mode (Remote Approval)
 
-```bash
-npx @vrs-soft/wecom-aibot-mcp --http-only --start
 ```
+You: Now contact me via WeChat
 
-**后台启动 / 停止（本地或 Server 端）**：
-
-```bash
-npx @vrs-soft/wecom-aibot-mcp --start   # 后台启动
-npx @vrs-soft/wecom-aibot-mcp --stop    # 停止
-```
+Claude: Entered WeChat mode. All interactions will go through Enterprise WeChat.
 
----
+[You leave the computer. Claude needs to run a command.]
 
-## 运行模式对比
+WeChat receives approval card:
+┌──────────────────────────────┐
+│ 【Pending Approval】Bash      │
+│ Command: npm run build...    │
+│ 📋 TaskID: approval_xxx      │
+│ [Allow Once] [Default] [Deny]│
+│ Details: View full command   │
+└──────────────────────────────┘
 
-| | Channel 模式 | HTTP 模式 |
-|-|-------------|----------|
-| 消息接收 | SSE 自动推送唤醒 | `/loop` 心跳轮询 |
-| 响应延迟 | 即时 | ≤1 分钟 |
-| 账号要求 | claude.ai 直连 | 任意（含 API 中转）|
+[Tap "Allow Once" on phone, or open "View full command" to see complete output]
 
-使用微信模式时告诉 Claude「**现在开始通过微信联系**」，会自动触发 `headless-mode` skill。
+Claude continues execution and sends the result to WeChat.
 
-**Channel 模式下 Claude 的启动命令**：
+You: I'm back
 
-```bash
-claude --dangerously-load-development-channels server:wecom-aibot-channel
+Claude: Exited WeChat mode.
 ```
 
----
+### Timeout Auto-Approval
 
-## 常用命令
+Configure in the bot config file or via `wecom-aibot.json`:
 
-| 命令 | 说明 |
-|------|------|
-| `--start / --stop` | 启动/停止后台服务 |
-| `--status` | 查看服务状态和机器人列表 |
-| `--config` | 修改默认机器人配置 |
-| `--add / --delete` | 添加/删除机器人 |
-| `--set-token [token]` | 设置 Auth Token（远程部署用） |
-| `--set-token --clear` | 清除 Auth Token |
-| `--debug` | 前台启动，输出调试日志 |
-| `--http-only` | 仅启动 HTTP MCP Server（服务器端用） |
-| `--channel-only` | 仅配置 Channel MCP（需 `MCP_URL` 环境变量） |
-| `--clean-cache` | 清空 CC 注册表缓存 |
-| `--upgrade` | 强制升级全局配置 |
-| `--uninstall` | 完全卸载 |
-
-超时自动审批（默认 10 分钟）：在机器人配置中设置 `"autoApproveTimeout": 600`。
+```json
+{
+  "autoApproveTimeout": 600
+}
+```
 
----
+- `autoApproveTimeout`: Timeout in seconds (default 600s = 10 minutes)
+- After timeout: operations **within** the project directory are auto-allowed; operations outside or delete commands are auto-denied
 
-## 故障排查
+## Troubleshooting
 
 ```bash
-# 检查服务是否运行
+# Check if service is running
 curl http://127.0.0.1:18963/health
 
-# Channel 不可用（"Channels are not currently available"）
-# → 使用 API Key 或中转服务，改用 HTTP 模式
+# Channel unavailable ("Channels are not currently available")
+# → Using API key or relay service? Switch to HTTP mode instead.
+
+# Channel fails to reconnect after server restart
+# → Auto-reconnect triggers within 5 seconds; no manual action needed.
+#    Requires v2.4.13 or later.
 
-# 端口占用
+# Approval detail page shows "Unauthorized"
+# → Upgrade to v2.4.14 or later; the /approval/ path is now auth-exempt.
+
+# Port conflict
 lsof -i :18963 | grep LISTEN
 kill <PID>
 
-# 清理断线残留的 ccId 注册
+# Clean up stale ccId registrations after disconnect
 npx @vrs-soft/wecom-aibot-mcp --clean-cache
 ```
 
----
+## MCP Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `send_message` | Send message to WeChat | `content`, `cc_id`, `target_user` |
+| `get_pending_messages` | Get pending messages (long poll) | `cc_id`, `timeout_ms` |
+| `enter_headless_mode` | Enter WeChat mode | `cc_id`, `robot_id`, `mode` |
+| `exit_headless_mode` | Exit WeChat mode | `cc_id` |
+| `check_connection` | Check WebSocket connection status | - |
+| `list_robots` | List all configured bots | - |
+| `get_connection_stats` | Get connection stats and logs | `recent_logs` |
 
 ## License
 
-MIT · [企业微信机器人文档](https://developer.work.weixin.qq.com/document/path/101039) · [Channels 文档](https://code.claude.com/docs/en/channels-reference)
+MIT · [Enterprise WeChat Bot Docs](https://developer.work.weixin.qq.com/document/path/101039) · [Channels Reference](https://code.claude.com/docs/en/channels-reference)

package/dist/channel-server.js

@@ -205,6 +205,23 @@ function connectSSE(ccId) {
         if (!res.ok) {
             logChannel('SSE connect failed', { status: res.status });
             sseConnected = false;
+            // server 重启后 ccId 注册丢失（404），需重新注册再重连
+            if (!sseAbortController?.signal.aborted) {
+                const delay = res.status === 404 ? 5000 : 3000;
+                logChannel(`SSE 连接失败(${res.status})，${delay / 1000} 秒后重连`, { ccId });
+                setTimeout(async () => {
+                    httpSessionId = null; // 重置 session，防止使用 server 重启前的旧 session
+                    if (ccId) {
+                        // 重新调 enter_headless_mode 恢复 server 端 ccId 注册
+                        await forwardToHttpMcp('enter_headless_mode', {
+                            cc_id: ccId,
+                            mode: 'channel',
+                            project_dir: process.cwd(),
+                        }).catch((e) => logChannel('重注册 ccId 失败', { error: String(e) }));
+                    }
+                    connectSSE(ccId);
+                }, delay);
+            }
             return;
         }
         logChannel('SSE connected, waiting for messages', { status: res.status });
@@ -230,7 +247,7 @@ function connectSSE(ccId) {
                 // 非主动断开时自动重连
                 if (!sseAbortController?.signal.aborted) {
                     logChannel('SSE 断线，3 秒后重连', { ccId });
-                    setTimeout(() => connectSSE(ccId), 3000);
+                    setTimeout(() => { httpSessionId = null; connectSSE(ccId); }, 3000);
                 }
                 break;
             }
@@ -305,7 +322,7 @@ function connectSSE(ccId) {
         // 非主动断开时自动重连
         if (!sseAbortController?.signal.aborted) {
             logChannel('SSE 出错，3 秒后重连', { ccId });
-            setTimeout(() => connectSSE(ccId), 3000);
+            setTimeout(() => { httpSessionId = null; connectSSE(ccId); }, 3000);
         }
     });
 }

package/dist/client.js

@@ -252,8 +252,9 @@ class WecomClient extends EventEmitter {
                 : eventKey === 'allow-always' ? '✅ 已允许（永久）'
                     : '❌ 已拒绝';
             const toolInfo = approval.toolName ? `: ${approval.toolName}` : '';
-            const descInfo = approval.description ? `\n\n> ${approval.description}` : '';
-            const content = `**审批结果**${toolInfo}\n\n${resultText}${descInfo}`;
+            const desc = approval.description || '';
+            const descSnippet = desc ? `\n执行命令: ${desc.slice(0, 100)}${desc.length > 100 ? '…' : ''}` : '';
+            const content = `**审批结果**${toolInfo}\n\n${resultText}${descSnippet}`;
             this.sendText(content).catch(err => {
                 logger.error('wecom', `发送审批确认失败: ${err}`);
             });
@@ -461,8 +462,9 @@ class WecomClient extends EventEmitter {
         const resultText = result === 'deny' ? '❌ 已拒绝' : '✅ 已允许';
         const reasonText = reason ? `\n\n原因：${reason}` : '';
         const toolInfo = approval.toolName ? `: ${approval.toolName}` : '';
-        const descInfo = approval.description ? `\n\n> ${approval.description}` : '';
-        this.sendText(`**审批结果（超时自动决策）**${toolInfo}\n\n${resultText}${reasonText}${descInfo}`).catch(err => {
+        const desc = approval.description || '';
+        const descBlock = desc ? `\n\n**执行命令**\n\`\`\`\n${desc}\n\`\`\`` : '';
+        this.sendText(`**审批结果（超时自动决策）**${toolInfo}\n\n${resultText}${reasonText}${descBlock}`).catch(err => {
             logger.error('[wecom] 发送审批确认失败:', err);
         });
         logger.log(`[wecom] 超时自动决策已设置: ${taskId} → ${result}`);

package/dist/http-server.js

@@ -204,9 +204,9 @@ function initMcpServer() {
     subscribeWecomMessage((msg) => {
         handleWecomMessage(msg);
     });
-    // 定时清理过期审批条目（每 5 分钟清理超过 15 分钟的条目）
+    // 定时清理过期审批条目（每 5 分钟清理超过 30 分钟的条目）
     setInterval(() => {
-        const cutoff = Date.now() - 15 * 60 * 1000;
+        const cutoff = Date.now() - 30 * 60 * 1000;
         let cleaned = 0;
         for (const [id, entry] of pendingApprovals) {
             if (entry.createdAt < cutoff) {
@@ -506,9 +506,9 @@ export async function startHttpServer(_server, port = HTTP_PORT, httpsConfig) {
                 return;
             }
             const url = req.url || '/';
-            // Auth token 校验（排除 /health）
+            // Auth token 校验（排除 /health 和 /approval/ 详情页，后者由浏览器直接访问）
             const authToken = getAuthToken();
-            if (authToken && url !== '/health') {
+            if (authToken && url !== '/health' && !url.startsWith('/approval/')) {
                 const authHeader = req.headers['authorization'];
                 if (authHeader !== `Bearer ${authToken}`) {
                     res.writeHead(401, { 'Content-Type': 'application/json' });
@@ -996,7 +996,7 @@ function handleApprovalDetail(_req, res, url) {
 </div>
 <h3>完整参数</h3>
 <pre>${escapeHtml(inputPretty)}</pre>
-<footer>此页面随审批记录自动过期清理 · 请回到企业微信卡片点击审批按钮</footer>
+<footer>审批记录保留 30 分钟后自动清理 · 请回到企业微信卡片点击审批按钮</footer>
 </body>
 </html>`;
     respondHtml(200, html);
@@ -1056,7 +1056,11 @@ async function handleApprovalTimeout(req, res, url) {
         const success = client.setApprovalResult(taskId, result, reason);
         if (success) {
             entry.status = result;
-            pendingApprovals.delete(taskId); // 处理完立即删除
+            // 保留 30 分钟供事后查看详情，不立即删除
+            setTimeout(() => {
+                pendingApprovals.delete(taskId);
+                logger.log(`[http] 超时审批条目已清理: taskId=${taskId}`);
+            }, 30 * 60 * 1000);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true, taskId, result }));
         }

package/package.json

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