@vrs-soft/wecom-aibot-mcp 1.0.0 → 1.0.2

package/README.md

@@ -58,6 +58,12 @@ PermissionRequest Hook 拦截
       执行或拒绝操作
 ```
 
+### 审批卡片示例
+
+![审批卡片](docs/approval-card.png)
+
+用户在企业微信中收到审批卡片，点击按钮即可远程决策：
+
 ## 安装
 
 ### 前置要求
@@ -142,6 +148,7 @@ npm link
    - 检查配置完整性
    - 注册权限预授权
    - 生成审批 Hook 脚本
+   - 安装 headless-mode skill 文件
 
 ### 第五步：验证连接
 

package/dist/client.js

@@ -175,8 +175,8 @@ class WecomClient {
                 main_title: { title },
                 sub_title_text: description,
                 button_list: [
-                    { text: '允许一次', key: 'allow-once', style: 1 },
-                    { text: '永久允许', key: 'allow-always', style: 1 },
+                    { text: '允许', key: 'allow-once', style: 1 },
+                    { text: '默认', key: 'allow-always', style: 1 },
                     { text: '拒绝', key: 'deny', style: 2 },
                 ],
                 task_id: taskId,

package/dist/config-wizard.js

@@ -139,12 +139,10 @@ if [[ -z "$TASK_ID" ]]; then
   exit 0
 fi
 
-# 轮询审批结果
-MAX_POLL=300
-POLL_COUNT=0
-while [[ $POLL_COUNT -lt $MAX_POLL ]]; do
+# 轮询审批结果（无限等待，适合 headless 模式）
+while true; do
   sleep 2
-  STATUS=$(curl -s "http://127.0.0.1:$PORT/approval_status/$TASK_ID" 2>/dev/null)
+  STATUS=$(curl -s -m 5 "http://127.0.0.1:$PORT/approval_status/$TASK_ID" 2>/dev/null)
   RESULT=$(echo "$STATUS" | jq -r '.result // empty')
 
   if [[ "$RESULT" == "allow-once" || "$RESULT" == "allow-always" ]]; then
@@ -154,11 +152,7 @@ while [[ $POLL_COUNT -lt $MAX_POLL ]]; do
     printf '%s\\n' '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"用户拒绝"}}}'
     exit 0
   fi
-
-  POLL_COUNT=$((POLL_COUNT + 1))
 done
-
-exit 0
 `;
     ensureConfigDir();
     fs.writeFileSync(HOOK_SCRIPT_PATH, script, { mode: 0o755 });
@@ -214,6 +208,44 @@ function writeMcpServerConfig(config) {
         return false;
     }
 }
+// 安装 skill 文件到 ~/.claude/skills/
+function installSkills() {
+    try {
+        const claudeSkillsDir = path.join(os.homedir(), '.claude', 'skills', 'headless-mode');
+        const skillFile = path.join(claudeSkillsDir, 'SKILL.md');
+        // 检查是否已存在
+        if (fs.existsSync(skillFile)) {
+            console.log('[config] skill 文件已存在，跳过安装');
+            return;
+        }
+        // 确保目录存在
+        if (!fs.existsSync(claudeSkillsDir)) {
+            fs.mkdirSync(claudeSkillsDir, { recursive: true });
+        }
+        // 从包内复制 skill 文件
+        // 包安装后 skills 目录在包根目录下
+        const packageDir = path.dirname(require.main?.filename || __dirname);
+        const sourceSkillFile = path.join(packageDir, '..', 'skills', 'headless-mode', 'SKILL.md');
+        if (fs.existsSync(sourceSkillFile)) {
+            fs.copyFileSync(sourceSkillFile, skillFile);
+            console.log(`[config] skill 文件已安装: ${skillFile}`);
+        }
+        else {
+            // 开发模式：从源码目录复制
+            const devSkillFile = path.join(process.cwd(), 'skills', 'headless-mode', 'SKILL.md');
+            if (fs.existsSync(devSkillFile)) {
+                fs.copyFileSync(devSkillFile, skillFile);
+                console.log(`[config] skill 文件已安装: ${skillFile}`);
+            }
+            else {
+                console.log('[config] ⚠️  skill 文件未找到，请手动创建 ~/.claude/skills/headless-mode/SKILL.md');
+            }
+        }
+    }
+    catch (err) {
+        console.error('[config] 安装 skill 文件失败:', err);
+    }
+}
 // 写入 MCP 工具权限 + 注册 PermissionRequest hook 到 Claude settings
 function writeMcpPermissions() {
     try {
@@ -259,6 +291,7 @@ function writeMcpPermissions() {
 // 确保 hook 已安装（幂等，可多次调用）
 export function ensureHookInstalled() {
     writeMcpPermissions();
+    installSkills();
 }
 // 保存配置（并自动写入 MCP 权限和 Server 配置）
 export function saveConfig(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrs-soft/wecom-aibot-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "企业微信智能机器人 MCP 服务 - Claude Code 审批通道",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",

package/skills/headless-mode/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: headless-mode
+description: 当用户说「现在开始通过微信联系」、「我要离开电脑前」、「切换到微信模式」时触发。进入微信模式，不间断轮询 get_pending_messages，只有审批时阻塞。
+---
+
+# Headless 微信交互模式
+
+**触发条件**：「现在开始通过微信联系」、「我要离开电脑前」、「切换到微信模式」
+
+## 激活后立即执行（必须按顺序）
+
+**Step 1**：进入 headless 模式（写入状态文件，让 hook 知道要发微信审批）
+```
+mcp__wecom-aibot__enter_headless_mode
+```
+
+**Step 2**：发送确认消息，明确已进入微信模式
+```
+mcp__wecom-aibot__send_message:
+  content: "【进度】已进入微信模式，所有交互将通过企业微信进行。请直接发消息给我。"
+```
+
+**Step 3**：立即进入不间断轮询循环
+```
+loop (永不退出):
+  调用 mcp__wecom-aibot__get_pending_messages
+  有消息 → 处理 → 汇报结果 → 继续轮询
+  无消息 → sleep（间隔动态调整）→ 继续轮询
+```
+
+## 核心规则
+
+1. **不间断轮询** `get_pending_messages`，间隔动态调整：
+   - **正常模式**：5 秒间隔（用户活跃时）
+   - **省电模式**：用户无响应超过 20 分钟后，间隔逐渐放大到 2 分钟
+   - 用户发新消息后，恢复 5 秒间隔
+2. **只有审批时阻塞**：hook 自动拦截敏感操作推送审批卡片，Clause 阻塞等待
+3. **审批结束后立即恢复轮询**
+4. 轮询永不退出，除非收到结束指令
+
+### 轮询间隔策略
+
+```
+开始轮询（5秒间隔）
+    ↓
+记录最后一次消息时间
+    ↓
+每次轮询检查：
+  - 有新消息 → 处理 → 重置计时 → 继续 5 秒间隔
+  - 无消息 → 检查空闲时间
+      - 空闲 < 20分钟 → 5 秒间隔
+      - 空闲 20-30分钟 → 30 秒间隔
+      - 空闲 30-60分钟 → 1 分钟间隔
+      - 空闲 > 60分钟 → 2 分钟间隔
+```
+
+**Why**：用户可能在休息、开会、睡觉，降低轮询频率减少 token 消耗，同时保持响应能力。
+
+## 处理用户消息
+
+1. 理解用户意图
+2. 直接执行所需工具（Bash、Edit、Write 等）
+   - hook 自动处理审批
+3. 执行完毕后用 `send_message` 汇报结果
+4. **立即继续轮询**
+
+## 群聊消息处理
+
+`get_pending_messages` 返回的消息包含：
+- `chattype`: "single"（单聊）或 "group"（群聊）
+- `chatid`: 单聊=用户ID，群聊=群ID
+
+**回复群聊消息**：
+```
+mcp__wecom-aibot__send_message:
+  content: "回复内容"
+  target_user: "消息中的chatid"  # 群聊时传入 chatid，回复会发到群里
+```
+
+**注意**：群聊消息回复到群里，所有人可见。
+
+## 通讯工具
+
+- **发消息**：`mcp__wecom-aibot__send_message`
+- **接消息**：`mcp__wecom-aibot__get_pending_messages`（动态间隔轮询）
+- **不要**手动调用 `send_approval_request`
+
+## 消息格式
+
+- `【需要确认】` — 需要决策
+- `【问题】` — 阻塞错误
+- `【进度】` — 里程碑
+- `【完成】` — 当前任务完成，继续等待新消息（**不是退出轮询**）
+
+## 结束模式
+
+### 用户意图识别
+
+在轮询过程中，如果收到用户消息，需判断是否要结束微信模式：
+
+| 用户消息 | 判断 | 动作 |
+|---------|------|------|
+| 「结束微信模式」、「停止微信模式」、「退出微信模式」 | 明确终止 | 直接停止 |
+| 「我回来了」、「我回电脑了」 | 明确终止 | 直接停止 |
+| 「我已经回到电脑旁了」、「我在电脑前了」 | 可能终止 | **询问确认** |
+| 「休息一下」、「暂停一下」 | 不终止 | 继续轮询 |
+
+### 询问确认格式
+
+如果用户消息暗示可能在电脑前但不确定：
+
+```
+【需要确认】检测到您可能在电脑前了，是否结束微信模式？
+- 回复「是」或「结束」→ 退出微信模式
+- 回复「否」或「继续」→ 保持微信模式
+```
+
+### 结束流程
+
+确认结束后：
+- 调用 `mcp__wecom-aibot__exit_headless_mode`（删除状态文件）
+- 发送：`【进度】已退出微信模式，恢复终端交互。`
+- 停止轮询