@vrs-soft/wecom-aibot-mcp 2.4.11 → 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/bin.js

@@ -9,7 +9,7 @@
  * - robotName 作为连接索引
  * - 不再使用 projectDir
  */
-import { spawn } from 'child_process';
+import { spawn, execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -164,43 +164,81 @@ function isServerRunning() {
         return false;
     }
 }
+// 通过端口查找进程 PID（fallback，当 PID 文件不存在时）
+function findPidByPort(port) {
+    try {
+        // Linux: ss -tlnp | grep :18963
+        const output = execSync(`ss -tlnp 2>/dev/null | grep ':${port}'`, { encoding: 'utf-8' });
+        const match = output.match(/pid=(\d+)/);
+        if (match)
+            return parseInt(match[1]);
+    }
+    catch { /* ignore */ }
+    try {
+        // macOS: lsof -ti :18963
+        const output = execSync(`lsof -ti :${port} 2>/dev/null`, { encoding: 'utf-8' }).trim();
+        if (output)
+            return parseInt(output.split('\n')[0]);
+    }
+    catch { /* ignore */ }
+    return null;
+}
 // 停止服务
 function stopServer() {
-    if (!fs.existsSync(PID_FILE)) {
-        console.log('[mcp] 服务未运行');
-        return false;
+    let pid = null;
+    // 优先从 PID 文件获取
+    if (fs.existsSync(PID_FILE)) {
+        pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
+        // 检查进程是否存在
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            // PID 文件残留但进程已死，清理 PID 文件
+            console.log('[mcp] PID 文件残留，进程已退出，清理中...');
+            fs.unlinkSync(PID_FILE);
+            pid = null;
+        }
+    }
+    // PID 文件不存在或残留：通过端口查找
+    if (pid === null) {
+        pid = findPidByPort(HTTP_PORT);
+        if (pid === null) {
+            console.log('[mcp] 服务未运行');
+            return false;
+        }
+        console.log(`[mcp] 通过端口 ${HTTP_PORT} 找到进程 PID: ${pid}`);
     }
+    // 发送 SIGTERM
     try {
-        const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
         process.kill(pid, 'SIGTERM');
-        // 等待进程退出
-        let attempts = 0;
-        while (attempts < 10) {
-            try {
-                process.kill(pid, 0);
-                // 进程还存在，等待
-                setTimeout(() => { }, 500);
-                attempts++;
-            }
-            catch {
-                // 进程已退出
-                break;
-            }
-        }
-        // 进程退出后删除 PID 文件（如果还存在）
-        if (fs.existsSync(PID_FILE)) {
+    }
+    catch {
+        // ESRCH: 进程不存在，清理即可
+        if (fs.existsSync(PID_FILE))
             fs.unlinkSync(PID_FILE);
-        }
         console.log('[mcp] 服务已停止');
         return true;
     }
-    catch (err) {
-        logger.error('[mcp] 停止服务失败:', err);
-        if (fs.existsSync(PID_FILE)) {
-            fs.unlinkSync(PID_FILE);
+    // 等待进程退出（最多 5 秒）
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(pid, 0);
+            // 进程还在，同步等待 100ms
+            const waitUntil = Date.now() + 100;
+            while (Date.now() < waitUntil) { /* busy wait */ }
         }
-        return false;
+        catch {
+            break;
+        }
+    }
+    // 清理 PID 文件
+    if (fs.existsSync(PID_FILE)) {
+        fs.unlinkSync(PID_FILE);
     }
+    console.log('[mcp] 服务已停止');
+    return true;
 }
 // 等待连接验证（用于配置向导验证凭证）
 async function waitForConnection(client, timeoutMs = 10000) {
@@ -318,10 +356,13 @@ async function main() {
     // --channel: 作为 Channel MCP 代理运行，不应改写全局配置
     // --reinstall / --http-only: 有自己的处理逻辑
     // --version / -v: 只查版本，不写配置
+    // --stop / --status / --list / --clean-cache / --set-token / --config: 管理命令，不应改写配置
     const skipEnsure = args.includes('--reinstall') || args.includes('--http-only') ||
         args.includes('--setup') || args.includes('--channel') ||
         args.includes('--version') || args.includes('-v') ||
-        args.includes('--start') || args.includes('--debug');
+        args.includes('--start') || args.includes('--debug') ||
+        args.includes('--stop') || args.includes('--status') || args.includes('--list') ||
+        args.includes('--clean-cache') || args.includes('--set-token') || args.includes('--config');
     if (!skipEnsure) {
         // 强制覆盖所有全局配置（不依赖智能体）
         ensureGlobalConfigs(installMode);

package/dist/channel-server.js

@@ -16,7 +16,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { VERSION } from './config-wizard.js';
-import { addPermissionHook } from './project-config.js';
+import { addPermissionHook, registerActiveProject, unregisterActiveProject } from './project-config.js';
 const MCP_URL = process.env.MCP_URL || 'http://127.0.0.1:18963';
 const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN;
 // 构建带 auth 的 fetch headers
@@ -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);
         }
     });
 }
@@ -399,9 +416,8 @@ function registerChannelTools(server) {
         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, cc_id, robot_id, project_dir, mode, auto_approve, auto_approve_timeout }) => {
+        auto_approve_timeout: z.number().optional().default(600).describe('超时自动决策等待时间（秒，默认 600 即 10 分钟）'),
+    }, async ({ agent_name, cc_id, robot_id, project_dir, mode, auto_approve_timeout }) => {
         // 转发请求
         const result = await forwardToHttpMcp('enter_headless_mode', {
             agent_name,
@@ -409,7 +425,6 @@ function registerChannelTools(server) {
             robot_id,
             project_dir: project_dir || process.cwd(),
             mode,
-            auto_approve,
             auto_approve_timeout,
         });
         // 拦截响应，提取 ccId，建立 SSE 连接
@@ -425,6 +440,9 @@ function registerChannelTools(server) {
                         const localProjectDir = project_dir || process.cwd();
                         const hookResult = addPermissionHook(localProjectDir);
                         logChannel('本地 PermissionRequest hook 已写入', { path: hookResult.path, success: hookResult.success });
+                        // 注册本地 PID → projectDir（供本地 permission-hook.sh 通过进程树匹配项目）
+                        registerActiveProject(process.ppid ?? process.pid, localProjectDir);
+                        logChannel('本地 active-projects 已注册', { pid: process.ppid ?? process.pid, projectDir: localProjectDir });
                         // Channel 模式：过滤 heartbeat 信息，简化消息
                         if (mode === 'channel' || parsed.mode === 'channel') {
                             delete parsed.heartbeat; // Channel 模式不需要 heartbeat loop
@@ -448,6 +466,7 @@ function registerChannelTools(server) {
         cc_id: z.string().describe('CC 唯一标识（enter_headless_mode 返回的 ccId）'),
         project_dir: z.string().optional().describe('项目目录路径（用于更新配置文件）'),
     }, async ({ cc_id, project_dir }) => {
+        const localProjectDir = project_dir || process.cwd();
         // 断开 SSE 连接（abort 后重连逻辑不会触发）
         if (sseAbortController) {
             sseAbortController.abort();
@@ -456,7 +475,10 @@ function registerChannelTools(server) {
             sseCurrentCcId = undefined;
             logChannel('SSE disconnected', { cc_id });
         }
-        return forwardToHttpMcp('exit_headless_mode', { cc_id, project_dir: project_dir || process.cwd() });
+        // 注销本地 active-projects 记录
+        unregisterActiveProject(localProjectDir);
+        logChannel('本地 active-projects 已注销', { projectDir: localProjectDir });
+        return forwardToHttpMcp('exit_headless_mode', { cc_id, project_dir: localProjectDir });
     });
     // ============================================
     // 工具 11: 从消息识别用户

package/dist/client.d.ts

@@ -14,6 +14,7 @@ interface ApprovalRecord {
     operationHash?: string;
     consumed?: boolean;
     ccId?: string;
+    detailUrl?: string;
 }
 interface MessageRecord {
     seq: number;
@@ -61,7 +62,8 @@ declare class WecomClient extends EventEmitter {
     }>;
     sendText(content: string, targetUser?: string): Promise<boolean>;
     sendApprovalRequest(title: string, description: string, requestId: string, targetUser?: string, toolInput?: Record<string, unknown>, // v3.0: 用于去重
-    ccId?: string): Promise<string>;
+    ccId?: string, // v3.0: 参与哈希，防止跨 CC 复用审批
+    detailUrlBase?: string): Promise<string>;
     sendQueuedApproval(taskId: string, title: string, description: string, targetUser?: string): Promise<boolean>;
     getApprovalResult(taskId: string): 'pending' | 'allow-once' | 'allow-always' | 'deny';
     setApprovalResult(taskId: string, result: 'allow-once' | 'deny', reason?: string): boolean;

package/dist/client.js

@@ -19,6 +19,30 @@ import { logger } from './logger.js';
 const MAX_PENDING_MESSAGES = 100;
 // 全局消息序号计数器
 let globalMessageSeq = 0;
+// 审批卡片正文长度上限；超过则截断，余下由详情链接承接
+const APPROVAL_DESC_MAX = 200;
+// 构建审批卡片 payload（发首次审批 + 排队重发共用）
+function buildApprovalCard(title, description, taskId, detailUrl) {
+    const truncated = description.length > APPROVAL_DESC_MAX
+        ? description.slice(0, APPROVAL_DESC_MAX) + '…（已截断，点击「详情」查看完整内容）'
+        : description;
+    const subTitle = truncated + `\n\n📋 TaskID: ${taskId}`;
+    const card = {
+        card_type: 'button_interaction',
+        main_title: { title },
+        sub_title_text: subTitle,
+        button_list: [
+            { text: '允许', key: 'allow-once', style: 1 },
+            { text: '默认', key: 'allow-always', style: 1 },
+            { text: '拒绝', key: 'deny', style: 2 },
+        ],
+        task_id: taskId,
+        ...(detailUrl
+            ? { horizontal_content_list: [{ keyname: '详情', value: '查看完整命令', type: 1, url: detailUrl }] }
+            : {}),
+    };
+    return { msgtype: 'template_card', template_card: card };
+}
 class WecomClient extends EventEmitter {
     wsClient;
     approvals = new Map();
@@ -228,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}`);
             });
@@ -344,7 +369,8 @@ class WecomClient extends EventEmitter {
     }
     // 发送审批请求（带按钮的模板卡片）
     async sendApprovalRequest(title, description, requestId, targetUser, toolInput, // v3.0: 用于去重
-    ccId // v3.0: 参与哈希，防止跨 CC 复用审批
+    ccId, // v3.0: 参与哈希，防止跨 CC 复用审批
+    detailUrlBase // 详情页 h5 链接的 base（最终 URL = base/taskId）
     ) {
         const userId = targetUser || this.targetUserId;
         // 从 title 中提取工具名称（格式: 【待审批】Bash）
@@ -360,6 +386,7 @@ class WecomClient extends EventEmitter {
         }
         const taskId = `approval_${requestId}_${Date.now()}`;
         const operationHash = toolInput && toolName ? hashOperation(ccId ?? '', toolName, toolInput) : undefined;
+        const detailUrl = detailUrlBase ? `${detailUrlBase}/${taskId}` : undefined;
         // 始终存储审批记录（断线时也需要，让 Hook 能轮询到）
         this.approvals.set(taskId, {
             taskId,
@@ -370,6 +397,7 @@ class WecomClient extends EventEmitter {
             description, // 保存审批请求原文
             operationHash,
             ccId, // 保存 ccId，用于 SSE 推送审批结果
+            detailUrl, // 供排队重发时复用
         });
         // 断线时将审批请求加入队列，等待重连后发送
         if (!this.connected) {
@@ -383,22 +411,7 @@ class WecomClient extends EventEmitter {
             // 返回 taskId，审批记录已创建，等待重连后发送
             return taskId;
         }
-        // 发送模板卡片（在 description 中显示 taskId 便于用户识别）
-        const displayDesc = description + `\n\n📋 TaskID: ${taskId}`;
-        await this.wsClient.sendMessage(userId, {
-            msgtype: 'template_card',
-            template_card: {
-                card_type: 'button_interaction',
-                main_title: { title },
-                sub_title_text: displayDesc,
-                button_list: [
-                    { text: '允许', key: 'allow-once', style: 1 },
-                    { text: '默认', key: 'allow-always', style: 1 },
-                    { text: '拒绝', key: 'deny', style: 2 },
-                ],
-                task_id: taskId,
-            },
-        });
+        await this.wsClient.sendMessage(userId, buildApprovalCard(title, description, taskId, detailUrl));
         logger.log(`[wecom] 已发送审批请求到 ${userId}: ${taskId}`);
         return taskId;
     }
@@ -415,22 +428,7 @@ class WecomClient extends EventEmitter {
             return false;
         }
         const userId = targetUser || this.targetUserId;
-        // 发送模板卡片（在 description 中显示 taskId 便于用户识别）
-        const displayDesc = description + `\n\n📋 TaskID: ${taskId}`;
-        await this.wsClient.sendMessage(userId, {
-            msgtype: 'template_card',
-            template_card: {
-                card_type: 'button_interaction',
-                main_title: { title },
-                sub_title_text: displayDesc,
-                button_list: [
-                    { text: '允许', key: 'allow-once', style: 1 },
-                    { text: '默认', key: 'allow-always', style: 1 },
-                    { text: '拒绝', key: 'deny', style: 2 },
-                ],
-                task_id: taskId,
-            },
-        });
+        await this.wsClient.sendMessage(userId, buildApprovalCard(title, description, taskId, approval.detailUrl));
         logger.log(`[wecom] 已发送排队审批请求到 ${userId}: ${taskId}`);
         return true;
     }
@@ -464,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/config-wizard.js

@@ -413,7 +413,7 @@ function writeHookScript() {
 # HTTP Transport 版本
 #
 # 固定端口: 18963
-# 检查 $(pwd)/.claude/wecom-aibot.json 的 wechatMode 和 autoApprove 字段
+# 通过 PID 树查 ~/.wecom-aibot-mcp/active-projects.json 匹配项目，读 wechatMode 开关
 
 MCP_PORT=18963
 
@@ -594,37 +594,10 @@ while [[ $POLL_COUNT -lt $MAX_POLL ]]; do
   fi
 done
 
-log_debug "[$(date)] Timeout reached, checking autoApprove setting"
+log_debug "[$(date)] Timeout reached, executing smart auto-approval"
 
-# 超时处理：根据 autoApprove 决定行为
-# autoApprove: false → 继续等待（无限轮询）
-# autoApprove: true → 智能代批
-
-AUTO_APPROVE=$(jq -r '.autoApprove // false' "$CONFIG_FILE" 2>/dev/null)
-log_debug "[$(date)] autoApprove: $AUTO_APPROVE"
-if [[ "$AUTO_APPROVE" != "true" ]]; then
-  log_debug "[$(date)] autoApprove off, entering infinite wait"
-  # autoApprove 关闭，继续无限等待用户响应
-  while true; do
-    sleep 2
-    STATUS=$(curl -s -m 3 "\${AUTH_ARGS[@]}" "$MCP_BASE_URL/approval_status/$TASK_ID" 2>/dev/null)
-    RESULT=$(echo "$STATUS" | jq -r '.result // empty')
-
-    if [[ "$RESULT" == "allow-once" || "$RESULT" == "allow-always" ]]; then
-      log_debug "[$(date)] Approved by user (infinite wait)"
-      printf '%s\\n' '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}'
-      exit 0
-    elif [[ "$RESULT" == "deny" ]]; then
-      log_debug "[$(date)] Denied by user (infinite wait)"
-      printf '%s\\n' '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"用户拒绝"}}}'
-      exit 0
-    fi
-  done
-fi
-
-# autoApprove: true，执行智能代批
+# 超时处理：必须立即决策，Claude Code 的 hook timeout 会杀掉阻塞进程。
 # 规则：删除命令→拒绝，项目内操作→允许，项目外操作→拒绝
-log_debug "[$(date)] Executing smart auto-approval"
 
 # 检查是否是删除命令（仅匹配命令行本身，不匹配 heredoc 内容）
 IS_DELETE=0
@@ -726,7 +699,7 @@ function writeStopHookScript() {
 # HTTP 模式使用：阻止 Claude 停止，提示调用 get_pending_messages 恢复轮询
 #
 # 固定端口: 18963
-# 检查 $(pwd)/.claude/wecom-aibot.json 的 wechatMode 和 autoApprove 字段
+# 只检查 $(pwd)/.claude/wecom-aibot.json 的 wechatMode 字段
 
 MCP_PORT=18963
 
@@ -763,14 +736,6 @@ if [[ "$WECHAT_MODE" != "true" ]]; then
   exit 0
 fi
 
-# 检查 autoApprove 是否为 true（需要恢复轮询的模式）
-AUTO_APPROVE=$(jq -r '.autoApprove // false' "$CONFIG_FILE" 2>/dev/null)
-log_debug "[$(date)] autoApprove: $AUTO_APPROVE"
-if [[ "$AUTO_APPROVE" != "true" ]]; then
-  log_debug "[$(date)] autoApprove not true, exit 0 (allow stop)"
-  exit 0
-fi
-
 # 确定 MCP Server 地址（本地优先，失败则尝试远程 channel 配置）
 MCP_BASE_URL="http://127.0.0.1:$MCP_PORT"
 AUTH_ARGS=()
@@ -810,7 +775,7 @@ if [[ -z "$CC_ID" ]]; then
   exit 0
 fi
 
-# 处于微信模式且 autoApprove 为 true，需要恢复轮询
+# 处于微信模式，需要恢复轮询
 # 使用 exit code 2 阻止停止，并提示 Claude 调用 MCP 工具
 log_debug "[$(date)] ✅ WeChat mode active, blocking stop to resume polling"
 log_debug "[$(date)] ccId=$CC_ID, will prompt Claude to call get_pending_messages"

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' });
@@ -622,6 +622,10 @@ export async function startHttpServer(_server, port = HTTP_PORT, httpsConfig) {
                 handleApprovalStatus(req, res, url);
                 return;
             }
+            if (req.method === 'GET' && url.startsWith('/approval/')) {
+                handleApprovalDetail(req, res, url);
+                return;
+            }
             if (req.method === 'POST' && url.startsWith('/approval_timeout/')) {
                 await handleApprovalTimeout(req, res, url);
                 return;
@@ -877,7 +881,7 @@ async function handleApprovalRequest(req, res) {
             res.end(JSON.stringify({ error: '未连接机器人，请先进入微信模式' }));
             return;
         }
-        const { tool_name, tool_input } = request;
+        const { tool_name, tool_input, projectDir } = request;
         let description = '';
         if (tool_name === 'Bash') {
             description = `执行命令: ${tool_input?.command || '(unknown)'}`;
@@ -890,8 +894,12 @@ async function handleApprovalRequest(req, res) {
         }
         const title = `【待审批】${tool_name}`;
         const requestId = `hook_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        const taskId = await client.sendApprovalRequest(title, description, requestId, undefined, tool_input, ccId);
-        logger.log(`[http] 审批请求已发送: ${taskId} (机器人: ${robotName})`);
+        // 构建卡片"详情"链接的 base（同源，从本请求的 Host/scheme 推断）
+        const scheme = req.socket.encrypted ? 'https' : 'http';
+        const host = req.headers.host || `127.0.0.1:${HTTP_PORT}`;
+        const detailUrlBase = `${scheme}://${host}/approval`;
+        const taskId = await client.sendApprovalRequest(title, description, requestId, undefined, tool_input, ccId, detailUrlBase);
+        logger.log(`[http] 审批请求已发送: ${taskId} (机器人: ${robotName}) 详情页: ${detailUrlBase}/${taskId}`);
         // 存储审批并启动超时计时器
         const entry = {
             taskId,
@@ -902,6 +910,8 @@ async function handleApprovalRequest(req, res) {
             tool_input,
             description,
             robotName,
+            ccId,
+            projectDir,
         };
         pendingApprovals.set(taskId, entry);
         res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -913,6 +923,84 @@ async function handleApprovalRequest(req, res) {
         res.end(JSON.stringify({ error: err.message }));
     }
 }
+function escapeHtml(raw) {
+    return raw
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function handleApprovalDetail(_req, res, url) {
+    const taskId = url.replace('/approval/', '');
+    const entry = pendingApprovals.get(taskId);
+    const respondHtml = (status, body) => {
+        res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(body);
+    };
+    if (!entry) {
+        respondHtml(404, `<!doctype html><meta charset="utf-8"><title>审批不存在</title>
+<body style="font-family:-apple-system,system-ui,sans-serif;padding:24px;color:#333">
+<h2>审批已过期或不存在</h2>
+<p>TaskID: <code>${escapeHtml(taskId)}</code></p>
+<p>此条记录可能已被清理（用户已决策或超时）。</p>
+</body>`);
+        return;
+    }
+    const inputPretty = (() => {
+        try {
+            return JSON.stringify(entry.tool_input ?? {}, null, 2);
+        }
+        catch {
+            return String(entry.tool_input);
+        }
+    })();
+    const statusLabel = {
+        'pending': '⏳ 待审批',
+        'allow-once': '✅ 已允许',
+        'deny': '❌ 已拒绝',
+    }[entry.status] ?? entry.status;
+    const html = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>审批详情 · ${escapeHtml(entry.tool_name)}</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+         max-width: 780px; margin: 0 auto; padding: 16px; color: #222; background: #f7f7f9; }
+  h1 { font-size: 20px; margin: 8px 0 16px; }
+  .meta { background: #fff; border-radius: 8px; padding: 12px 16px; margin-bottom: 12px;
+          box-shadow: 0 1px 2px rgba(0,0,0,.04); }
+  .meta .row { display: flex; padding: 4px 0; border-bottom: 1px dashed #eee; }
+  .meta .row:last-child { border-bottom: none; }
+  .meta .k { width: 96px; color: #888; flex-shrink: 0; }
+  .meta .v { flex: 1; word-break: break-all; }
+  pre { background: #fff; border-radius: 8px; padding: 12px 16px;
+        overflow-x: auto; font-size: 13px; line-height: 1.5;
+        box-shadow: 0 1px 2px rgba(0,0,0,.04); white-space: pre-wrap; word-break: break-all; }
+  .tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 12px;
+         background: #eef; color: #446; }
+  footer { color: #aaa; font-size: 12px; text-align: center; margin-top: 16px; }
+</style>
+</head>
+<body>
+<h1>审批详情</h1>
+<div class="meta">
+  <div class="row"><div class="k">状态</div><div class="v">${statusLabel}</div></div>
+  <div class="row"><div class="k">工具</div><div class="v"><span class="tag">${escapeHtml(entry.tool_name)}</span></div></div>
+  <div class="row"><div class="k">概要</div><div class="v">${escapeHtml(entry.description)}</div></div>
+  ${entry.projectDir ? `<div class="row"><div class="k">项目目录</div><div class="v">${escapeHtml(entry.projectDir)}</div></div>` : ''}
+  ${entry.ccId ? `<div class="row"><div class="k">CC</div><div class="v">${escapeHtml(entry.ccId)}</div></div>` : ''}
+  <div class="row"><div class="k">TaskID</div><div class="v"><code>${escapeHtml(taskId)}</code></div></div>
+</div>
+<h3>完整参数</h3>
+<pre>${escapeHtml(inputPretty)}</pre>
+<footer>审批记录保留 30 分钟后自动清理 · 请回到企业微信卡片点击审批按钮</footer>
+</body>
+</html>`;
+    respondHtml(200, html);
+}
 function handleApprovalStatus(_req, res, url) {
     const taskId = url.replace('/approval_status/', '');
     const entry = pendingApprovals.get(taskId);
@@ -968,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/dist/project-config.d.ts

@@ -17,7 +17,6 @@ export interface WechatModeConfig {
     robotName?: string;
     wechatMode: boolean;
     ccId?: string;
-    autoApprove?: boolean;
     autoApproveTimeout?: number;
     heartbeatJobId?: string;
     mode?: 'channel' | 'http';

package/dist/project-config.js

@@ -270,6 +270,14 @@ const STOP_HOOK = {
     matcher: '',
     hooks: [{ type: 'command', command: STOP_HOOK_SCRIPT_PATH }],
 };
+/**
+ * 进入微信模式时默认预批的 MCP 工具通配（避免每次都走 hook 增加延迟）
+ * hook 本身对 mcp__* 也会放行，加入 allow 只是让 Claude Code 跳过 hook。
+ */
+const DEFAULT_MCP_ALLOW = [
+    'mcp__wecom-aibot__*',
+    'mcp__wecom-aibot-channel__*',
+];
 /**
  * 添加 PermissionRequest hook 到项目 settings.json
  */
@@ -296,6 +304,16 @@ export function addPermissionHook(projectDir) {
         settings.hooks = {};
     }
     settings.hooks.PermissionRequest = [PERMISSION_HOOK];
+    // 合并默认 MCP 通配到 permissions.allow（去重保序）
+    const perms = settings.permissions ?? {};
+    const existingAllow = Array.isArray(perms.allow) ? perms.allow : [];
+    const merged = [...existingAllow];
+    for (const entry of DEFAULT_MCP_ALLOW) {
+        if (!merged.includes(entry))
+            merged.push(entry);
+    }
+    perms.allow = merged;
+    settings.permissions = perms;
     // 写入配置
     try {
         fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));

package/dist/tools/index.d.ts

@@ -1,23 +1,2 @@
-/**
- * MCP 工具注册入口
- *
- * 注册以下工具：
- * - send_message: 发送消息
- * - send_approval_request: 发送审批请求
- * - get_approval_result: 获取审批结果
- * - check_connection: 检查连接状态
- * - get_pending_messages: 获取待处理消息
- * - get_setup_guide: 获取安装指南
- * - add_robot_config: 添加机器人配置
- * - list_robots: 列出所有机器人
- * - get_robot_status: 获取机器人状态
- * - enter_headless_mode: 进入微信模式
- * - exit_headless_mode: 退出微信模式
- * - detect_user_from_message: 从消息识别用户
- *
- * v2.0 架构变更：
- * - 不再使用 projectDir 参数
- * - 从 Session 自动获取 robotName
- */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerTools(server: McpServer): void;

package/dist/tools/index.js

@@ -1,24 +1,4 @@
-/**
- * MCP 工具注册入口
- *
- * 注册以下工具：
- * - send_message: 发送消息
- * - send_approval_request: 发送审批请求
- * - get_approval_result: 获取审批结果
- * - check_connection: 检查连接状态
- * - get_pending_messages: 获取待处理消息
- * - get_setup_guide: 获取安装指南
- * - add_robot_config: 添加机器人配置
- * - list_robots: 列出所有机器人
- * - get_robot_status: 获取机器人状态
- * - enter_headless_mode: 进入微信模式
- * - exit_headless_mode: 退出微信模式
- * - detect_user_from_message: 从消息识别用户
- *
- * v2.0 架构变更：
- * - 不再使用 projectDir 参数
- * - 从 Session 自动获取 robotName
- */
+// MCP 工具注册入口。完整工具清单见 design/tools-api.md。
 import { z } from 'zod';
 import { listAllRobots, getDocMcpUrl, installSkill, VERSION } from '../config-wizard.js';
 import { callDocTool } from '../doc-proxy.js';
@@ -356,9 +336,8 @@ npx @vrs-soft/wecom-aibot-mcp
         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(300).describe('自动审批超时时间（秒，默认 300 即 5 分钟）'),
-    }, async ({ agent_name, cc_id, robot_id, project_dir, mode, auto_approve, auto_approve_timeout }, extra) => {
+        auto_approve_timeout: z.number().optional().default(300).describe('超时自动决策等待时间（秒，默认 300 即 5 分钟）'),
+    }, async ({ agent_name, cc_id, robot_id, project_dir, mode, auto_approve_timeout }, extra) => {
         // 获取项目目录
         const projectDir = project_dir || process.cwd();
         // 智能体名称（用于生成 ccId）
@@ -429,7 +408,6 @@ npx @vrs-soft/wecom-aibot-mcp
             wechatMode: true,
             robotName: selectedRobot.name,
             ccId: finalCcId,
-            autoApprove: auto_approve,
             autoApproveTimeout: auto_approve_timeout,
             mode,
         });

package/package.json

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