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

package/skills/headless-mode/SKILL.md

@@ -5,257 +5,212 @@ description: 当用户说「现在开始通过微信联系」时触发，进入
 
 # Headless 微信交互模式
 
-## 重要说明
+**触发词**：「现在开始通过微信联系」「我要离开电脑前」「切换到微信模式」
 
-**本模式使用 `wecom-aibot` MCP 服务器与企业微信通信，不使用其他任何通信方式。**
+## 进入微信模式流程
 
-MCP 服务器地址：`http://127.0.0.1:18963/mcp`
+> **关键原则**：模式决定 MCP 前缀。Channel 模式全程用 `mcp__wecom-aibot-channel__`，HTTP 模式全程用 `mcp__wecom-aibot__`。**必须先确定模式，再进行后续操作。**
 
-所有消息收发、长轮询、审批通知均通过 wecom-aibot MCP 工具完成。
+### 1. 确定运行模式
 
-## 触发词
+**必须首先用 AskUserQuestion 让用户选择**（或读取 `.claude/wecom-aibot.json` 中已保存的 mode）：
 
-「现在开始通过微信联系」「我要离开电脑前」「切换到微信模式」
+- **Channel 模式**：消息自动推送唤醒，需要用以下命令启动 Claude（研究预览阶段）：
+  `claude --dangerously-load-development-channels server:wecom-aibot-channel`
+- **HTTP 模式**：心跳轮询，兼容所有环境（API Key、中转服务均可）
 
----
-
-## 启动时自动恢复
-
-**检查文件**：`项目目录/.claude/wecom-aibot.json`
+> 如果当前会话是通过 `--dangerously-load-development-channels` 启动的，默认选 Channel 模式。
 
-如果该文件存在且 `autoApprove: true`，说明用户期望通过微信交互：
-
-```
-1. 读取 wecom-aibot.json 获取 robotName（用于选择机器人）
-2. 调用 enter_headless_mode(agent_name, robot_id=robotName)
-3. 服务端返回新的 ccId（如 cc-1）
-4. 发送消息：【进度】已自动恢复微信模式
-5. 开始长轮询
-```
+根据选择，确定后续所有工具调用的 **MCP 前缀**：
+- Channel 模式 → `MCP = mcp__wecom-aibot-channel__`
+- HTTP 模式 → `MCP = mcp__wecom-aibot__`
 
-**注意**：ccId 由服务端生成，每次进入微信模式都会获得新的 ccId。
+### 2. 检查配置文件
 
----
+检查项目目录 `.claude/wecom-aibot.json`：
 
-## MCP 协议说明
+**a) 文件存在**
+- 读取 robotName 和 ccId，直接跳到步骤 4
 
-**重要**：所有 wecom-aibot 工具通过 MCP (Model Context Protocol) HTTP Transport 调用，**不是直接 HTTP 请求**。
+**b) 文件不存在**
+- 执行以下准备步骤：
 
-### 工具调用方式
+#### 2.1 生成 ccId
 
-Claude Code 调用 MCP 工具时，会自动处理以下细节：
-- **sessionId**: MCP HTTP Transport 要求在 `initialize` 请求时获取 sessionId，后续所有请求必须在 `mcp-session-id` header 中传递。Claude Code **自动处理** sessionId，智能体无需手动管理。
-- **工具命名**: 所有工具名称格式为 `mcp__wecom-aibot__<tool_name>`（例如 `mcp__wecom-aibot__send_message`）
+格式：`${项目名}`（如 `wecom-aibot-mcp`）
 
-### 智能体无需关心的事项
+**禁止自动编号**，如有冲突提示用户改名。
 
-- ❌ 不需要手动获取 sessionId
-- ❌ 不需要手动传递 HTTP headers
-- ❌ 不需要了解 MCP 协议细节
-- ✅ 只需调用 MCP 工具，Claude Code 自动处理底层通信
+#### 2.2 选择机器人
 
----
+调用 `${MCP}list_robots`：
 
-## MCP 工具调用方式
+- 机器人数量 = 1 → 直接使用
+- 机器人数量 > 1 → **必须用 AskUserQuestion 让用户选择**
 
-| 功能 | MCP 工具名称 | 必需参数 |
-|------|-------------|----------|
-| 进入微信模式 | `mcp__wecom-aibot__enter_headless_mode` | agent_name, project_dir |
-| 发送消息 | `mcp__wecom-aibot__send_message` | cc_id, content |
-| 获取消息（长轮询默认30秒间隔） | `mcp__wecom-aibot__get_pending_messages` | cc_id |
-| 退出微信模式 | `mcp__wecom-aibot__exit_headless_mode` | cc_id, project_dir |
+### 3. 调用 enter_headless_mode
 
----
+使用步骤 1 确定的 MCP 前缀：
 
-## 进入流程
+```
+${MCP}enter_headless_mode(
+  cc_id="<项目名>",
+  robot_id="<机器人名称>",
+  mode="<channel 或 http>",
+  project_dir="<项目目录>"
+)
+```
 
-### 1. 检查配置文件和机器人选择（必须首先执行）
+例如 Channel 模式：
+```
+mcp__wecom-aibot-channel__enter_headless_mode(cc_id="知识库", robot_id="CC", mode="channel", project_dir="...")
+```
 
-**第一步：检查项目配置文件**
+例如 HTTP 模式：
+```
+mcp__wecom-aibot__enter_headless_mode(cc_id="知识库", robot_id="CC", mode="http", project_dir="...")
+```
 
-检查项目目录下的 `.claude/wecom-aibot.json`：
-- **文件存在且有 robotName** → 直接使用该 robotName，跳过机器人选择
-- **文件不存在或没有 robotName** → 需要用户选择机器人
+### 2. 处理返回结果
 
-**第二步：获取机器人列表**
+**返回字段**：
+- `status: 'entered'` → 进入成功（重连时直接覆盖，无需改名）
 
-调用 `mcp__wecom-aibot__list_robots` 获取所有可用机器人。
+### 3. HTTP 模式：立即执行心跳
 
-**第三步：处理机器人选择**
+**强制步骤，必须执行**：
 
-- **机器人数量 = 1** → 直接使用该机器人
-- **机器人数量 > 1 且配置文件中没有 robotName** → **必须使用 AskUserQuestion 让用户选择**
+1. 执行定时任务：
+   ```
+   /loop 1m mcp__wecom-aibot__heartbeat_check
+   ```
 
-```
-使用 AskUserQuestion 让用户选择机器人:
-    question: "检测到多个机器人，请选择要使用的机器人"
-    options: 每个机器人的名称（从 list_robots 返回的 robots 数组获取）
-```
+   返回示例：
+   ```
+   已创建定时任务，job ID: abc12345
+   每 1 分钟执行一次
+   ```
 
-**完整流程示例**：
-```
-1. 检查项目目录下的 .claude/wecom-aibot.json 是否存在
-   - 存在 → 读取 robotName
-   - 不存在 → robotName = null
-2. 调用 list_robots 获取机器人列表
-3. 判断：
-   - 如果 robotName 存在 → 使用该 robotName
-   - 如果机器人数量 = 1 → 使用该机器人
-   - 如果机器人数量 > 1 且没有 robotName → 使用 AskUserQuestion 让用户选择
-4. 调用 enter_headless_mode(agent_name, robot_id=确定的机器人名称)
-```
+2. 提取返回中的 job ID（如 `abc12345`）
 
-**禁止的行为**：
-- ❌ 在多机器人场景下自动选择第一个
-- ❌ 直接调用 enter_headless_mode 不传 robot_id
-- ❌ 假设只有一个机器人而不检查
-- ❌ 忽略项目配置文件中的 robotName
+3. 调用 MCP 工具保存 job ID：
+   ```
+   mcp__wecom-aibot__update_heartbeat_job_id(cc_id="<ccId>", job_id="abc12345")
+   ```
 
-### 2. 调用 enter_headless_mode
+**注意**：此步骤必须在进入微信模式后立即执行，否则无法接收消息。
 
-**重要**：`agent_name` 和 `project_dir` 必须由智能体生成，格式为项目名称或任务名称，不要让 MCP 生成。
+### 4. 开始轮询
 
+**HTTP 模式**：
 ```
-mcp__wecom-aibot__enter_headless_mode(agent_name="<项目名称>", robot_id="<机器人名称>", project_dir="<项目目录>")
+while (true):
+  result = mcp__wecom-aibot__get_pending_messages(timeout_ms=30000)
+  if result.messages → 处理消息，回复，继续轮询
+  if result.timeout → 立即重新调用
 ```
 
-**参数说明**：
-- `agent_name`: **必填**，智能体名称（使用当前项目名称或任务名称，如 "wecom-aibot-mcp"、"ModuleStudio"）
-- `robot_id`: **必填**（多机器人场景），指定机器人名称
-- `project_dir`: **必填**，项目目录路径（用于写入 `.claude/wecom-aibot.json` 配置文件）
+**Channel 模式**：等待推送，无需轮询。消息到达时 Claude 会被自动唤醒。
 
-**处理返回值**：
-- `entered` → 返回 `ccId`（服务端生成），继续下一步
-
-**注意**：
-- ccId 由 MCP Server 自动生成（如 `cc-1`），无需手动指定
-- 如果正确执行了步骤 1（机器人选择），不会收到 `select_robot` 状态
-- **进入微信模式时，MCP 会自动写入 `.claude/wecom-aibot.json`，设置 `wechatMode: true` 和 `robotName`**
+---
 
-### 3. 写入项目级 Hook（可选）
+## 消息处理
 
-**注意**：VSCode 扩展可能不完全支持 PermissionRequest Hook。如果审批不生效，可跳过此步骤。
+### 收到消息后
 
-读取当前工作目录的 `.claude/settings.json`（不存在则创建），合并写入：
+**HTTP 模式**：
+1. 立即发送确认：`mcp__wecom-aibot__send_message(cc_id, "收到...", target_user=<chatid>)`
+2. 执行操作（Bash/Edit/Write）
+3. 发送结果：`mcp__wecom-aibot__send_message(cc_id, "【完成】...", target_user=<chatid>)`
+4. 继续轮询
 
-```json
-{
-  "hooks": {
-    "PermissionRequest": [
-      {
-        "matcher": "",
-        "hooks": [{ "type": "command", "command": "~/.wecom-aibot-mcp/permission-hook.sh" }]
-      }
-    ]
-  }
-}
-```
+**Channel 模式**（收到 `<channel>` 标签时）：
+1. 立即发送确认：`mcp__wecom-aibot-channel__send_message(cc_id, "收到...", target_user=<chatid>)`
+2. 执行操作（Bash/Edit/Write）
+3. 发送结果：`mcp__wecom-aibot-channel__send_message(cc_id, "【完成】...", target_user=<chatid>)`
 
-保留文件中已有的其他配置，只合并 `hooks.PermissionRequest` 字段。
+### 回复路由
 
-**重要**：不要添加 `timeout` 字段，VSCode 扩展不支持该配置。超时控制由 hook 脚本内部的轮询机制处理。
+`get_pending_messages` 返回的每条消息包含：
+- `from`：发送者用户 ID
+- `chatid`：会话 ID（单聊=用户ID，群聊=群ID，如 `wr0Q...`）
+- `chattype`：`single` 或 `group`
 
-### 4. 发确认消息
+**回复时必须将 `chatid` 作为 `target_user` 传入**，确保回复到正确的会话：
 
 ```
-mcp__wecom-aibot__send_message("【进度】已进入微信模式，所有交互将通过企业微信进行。")
+msg = messages[0]
+send_message(cc_id, content, target_user=msg.chatid)
 ```
 
-### 5. 开始长轮询
+- 单聊：`chatid` = 发送者的用户 ID，等同于默认目标，可省略
+- 群聊：`chatid` = 群 ID，**必须传入**，否则会发到默认的单聊用户
 
-**核心原则**：轮询永不退出，除非收到明确结束指令（「结束微信模式」「我回来了」）。
+### 消息格式
 
-```
-while (true):
-  result = mcp__wecom-aibot__get_pending_messages(timeout_ms=30000)
-  if result.messages → 处理消息，然后继续轮询
-  if result.timeout  → 立即重新调用（不需要 sleep，不需要任何等待）
-```
-
-**timeout 不是停止信号**：
-- `timeout: true` 只表示"这 30 秒内没有消息"
-- 收到 timeout 后立即重新调用 `get_pending_messages`
-- 长轮询会阻塞等待，有消息立即唤醒，无消息等满超时后才消耗 token
-- 比短轮询节省约 6 倍 token
+- `【进度】` - 里程碑汇报
+- `【完成】` - 任务完成
+- `【问题】` - 需用户决策
+- `【需要确认】` - 二次确认
 
 ---
 
-## 处理用户消息
+## 任务完成检查
 
-1. **收到指令后先应答**：立即发送简短确认（如「收到，开始处理...」），让用户知道指令已被接收
-2. 理解意图
-3. 执行操作（Bash/Edit/Write 等）— Hook 自动处理审批，Claude 阻塞等待用户点击
-4. 用 `mcp__wecom-aibot__send_message` 汇报结果
-5. 继续轮询
+**每次完成任务后必须执行**：
 
-**群聊回复**：`mcp__wecom-aibot__send_message(content, target_user=chatid)`
+1. 检查 `.claude/wecom-aibot.json`
+2. 如果 `autoApprove: true`：
+   - 发送结果到微信
+   - 恢复轮询（HTTP 模式）
 
 ---
 
-## 任务完成检查（必须执行）
-
-**每次完成用户任务后，必须执行以下检查：**
-
-```python
-def on_task_complete():
-    # 步骤 1: 检查配置文件
-    config = read_file(".claude/wecom-aibot.json")
-    
-    if config and config.get("autoApprove") == True:
-        # 步骤 2: 必须通过 MCP 发送结果
-        send_message("【完成】任务结果...")
-        
-        # 步骤 3: 必须恢复轮询
-        while True:
-            msg = get_pending_messages(timeout_ms=60000)
-            if msg:
-                handle_message(msg)
-            # timeout 后立即重新调用，不需要 sleep
-```
+## 退出微信模式
 
-**为什么必须执行**：
-- 配置文件存在且 `autoApprove: true` = 用户期望通过微信接收结果
-- 不执行 = 用户收不到结果，CC 被判定为离线
+**触发词**：「结束微信模式」「我回来了」
 
-**注意**：即使是"compact"、"compacting"等内部任务，完成后也必须检查配置文件并恢复轮询。系统自动触发的 compacting 操作结束后，同样需要执行此检查。
+1. **停止心跳定时任务**（HTTP 模式）
+   
+   a) 读取 `.claude/wecom-aibot.json` 中的 `heartbeatJobId`
+   
+   b) 执行删除：
+   ```
+   /loop stop <heartbeatJobId>
+   ```
+   
+   c) 删除配置文件中的 `heartbeatJobId` 字段
 
----
+2. 调用 `mcp__wecom-aibot__exit_headless_mode(cc_id, project_dir)`
 
-## 退出流程
+3. 删除 PermissionRequest hook
 
-**触发词**：「结束微信模式」「我回来了」「我回电脑了」
+4. 发送退出通知
 
-1. 调用 `mcp__wecom-aibot__exit_headless_mode(cc_id, project_dir)`
-2. **MCP 自动更新 `.claude/wecom-aibot.json` 的 `wechatMode` 为 `false`**
-3. 从 `.claude/settings.json` 删除 `hooks.PermissionRequest` 字段（如果之前配置了）
-4. 发送 `mcp__wecom-aibot__send_message("【进度】已退出微信模式，恢复终端交互。")`
 5. 停止轮询
 
-**「我已经回到电脑旁了」** → 先确认：
-```
-mcp__wecom-aibot__send_message("【需要确认】是否结束微信模式？回复「是」退出，「否」继续。")
-```
-
 ---
 
-## 消息格式
-
-**正确格式**：`【标签】消息内容`
+## MCP 工具列表
 
-| 标签 | 用途 |
-|------|------|
-| `【进度】` | 里程碑汇报、收到指令确认 |
-| `【完成】` | 任务完成，继续等待 |
-| `【问题】` | 需用户决策 |
-| `【需要确认】` | 二次确认 |
-
-**ccId 路由**：
-- 消息前缀由 MCP Server 自动添加（格式：`【ccId】`）
-- 多 CC 场景下，用户引用回复时需包含 ccId（如 `【cc-1】`）
+| 工具 | 用途 | 参数 |
+|------|------|------|
+| `get_setup_requirements` | 获取配置需求 | 无 |
+| `enter_headless_mode` | 进入微信模式 | cc_id, robot_id, mode, project_dir |
+| `send_message` | 发送消息 | cc_id, content, target_user(可选) |
+| `get_pending_messages` | 获取消息(HTTP模式) | cc_id, timeout_ms |
+| `heartbeat_check` | 心跳检查(HTTP模式) | 无 |
+| `update_heartbeat_job_id` | 保存心跳 job ID(HTTP模式) | cc_id, job_id |
+| `get_skill` | 获取 skill 文件 | 无(远程部署用) |
+| `exit_headless_mode` | 退出微信模式 | cc_id, project_dir |
 
 ---
 
-## 多 CC 消息路由
+## 运行模式对比
 
-- **单 CC**：消息直接推送
-- **多 CC**：用户需引用回复（引用内容含 `【cc-1】` 等标记路由）
+| 特性 | Channel 模式 | HTTP 模式 |
+|------|-------------|----------|
+| 消息接收 | SSE 自动推送 | 主动轮询 |
+| 唤醒方式 | notification 自动 | heartbeat + 轮询 |
+| 启动要求 | `--dangerously-load-development-channels server:wecom-aibot-channel` | 无特殊要求 |
+| 适用 LLM | 仅 Claude | 所有 LLM |