---
name: qiwei-group-management
description: 迁移自 Qiwei 项目的群管理能力：扫描外部群目录、按关键词分析/识别客户群、确认或手动添加外部群，并通过公网 Relay 回调接收已确认群的新消息。所有调用通过 Fmode 网关，状态保存在 outputs/groups/ 和 outputs/messages/。
---

# 企微群管理

## 使用边界

本 skill 负责群的发现、识别、确认和回调接入：

- 扫描群列表（支持自建群和最近会话群两种来源）；
- 列出已同步群，并按状态/关键词/来源过滤；
- 分析群详情，按可配置关键词自动识别客户群；
- 手动确认某个群为客户群，并关联客户；
- 手动添加同步列表之外的 roomId；
- 手动拒绝某个群；
- 配置客户群识别关键词与匹配模式；
- 已确认群通过公网 Relay 回调持续接收新消息，不拉取历史消息。

不要在这里重新实现登录、订阅、通用 API 检索流程。遇到未登录、订阅不足、token 缺失时，转用已有工具：

- `qiwei_login_status`
- `qiwei_login_start`
- `qiwei_subscription_status`
- `qiwei_subscribe`
- `qiwei_api_search`
- `qiwei_api_doc`

## 接口规范

业务工具必须符合 `mcp/catalog/qiwei-endpoints.json`：

- 同步自建群列表使用 `/room/getRoomList`；
- 扫描最近会话群使用 `/session/getSessionPage`，`sessionType=1` 表示群；
- 分析群详情使用 `/room/batchGetRoomDetail`；
- 群新消息接收使用公网 Relay 回调，消息必须带有效 `fromRoomId` 和 `msgUniqueIdentifier`；
- 请求信封固定为 `{ "uid": "...", "method": "...", "params": {...} }`；
- 鉴权固定走 `Authorization: Bearer <Fmode token>`；
- `guid` 必须来自已登录设备。

## 标准流程

### 第 0 步：确认群创建方式

先询问用户："您要识别的客户群，是您自己创建的吗？"

- **是** → 调用 `qiwei_sync_external_groups`，`scope: "self"`（仅扫描 `/room/getRoomList`）。
- **否 / 不确定** → 调用 `qiwei_sync_external_groups`，`scope: "all"`，同时扫描自建群与最近会话群。

### 第 1 步：同步外部群

示例（用户不确定是否自建）：

```json
{
  "guid": "<已登录设备 guid>",
  "scope": "all",
  "maxPages": 50,
  "autoClassify": true,
  "matchMode": "threshold",
  "threshold": 2
}
```

结果写入：

- `outputs/groups/2026-07-15/142030-sync-external-groups/rooms-<timestamp>.json`
- `outputs/groups/rooms-latest.json`
- `outputs/groups/group-scan-manifest.json`

群记录包含：

- `source` / `sources`：群来自哪个目录来源（`roomList`、`session`；详情补全记录为 `roomDetail`）
- `roomExtType`：`0`=内部群，`2`=外部群
- `reviewStatus`：`IMPORTED` / `SUGGESTED` / `AUTO_CONFIRMED`
- `confidence`：置信度
- `reason`：识别原因
- `matchedKeywords`：命中关键词

### 第 2 步：列出并识别客户群

```json
{
  "status": "AUTO_CONFIRMED"
}
```

返回最近一次同步的群，每个群附带：

- `reviewStatus`: `IMPORTED` / `SUGGESTED` / `AUTO_CONFIRMED` / `CONFIRMED` / `REJECTED`
- `reason`: 识别原因
- `matchedKeywords`: 命中关键词

也可调用 `qiwei_analyze_group_members` 对指定 roomId 做更详细的群详情分析：

```json
{
  "guid": "<已登录设备 guid>",
  "roomIds": ["r-1", "r-2"],
  "updateSnapshot": true
}
```

### 第 3 步：确认或拒绝客户群

对最近一次同步列表中的 roomId 确认：

```json
{
  "roomId": "r-1",
  "externalUserId": "wx-u-1",
  "customerName": "张三"
}
```

映射写入 `outputs/groups/confirmed-mapping.json`。

如需拒绝：

```json
{
  "roomId": "r-2",
  "reason": "内部通知群"
}
```

写入 `outputs/groups/rejected-mapping.json`。

如需添加同步列表之外的群，使用 `qiwei_add_external_group`：

```json
{
  "roomId": "r-99",
  "roomName": "李四服务群",
  "externalUserId": "wx-u-2"
}
```

### 第 4 步：配置关键词（可选）

当自动分类效果不佳时，调优关键词：

```json
{
  "keywords": ["客户群", "服务群", "售后群", "VIP群"],
  "highConfidenceTerms": ["客户群", "服务群"],
  "matchMode": "threshold",
  "threshold": 2
}
```

配置持久化到 `outputs/groups/customer-keywords.json`，会立即影响后续 `qiwei_sync_external_groups` 和 `qiwei_list_external_groups` 的分类结果。

### 第 5 步：接收群回调新消息

群确认后无需执行消息同步。公网 Relay 会把带 `fromRoomId` 的新消息交给回调处理器；处理器仅接收已确认或已导入的客户群，按 `msgUniqueIdentifier` 去重，并写入 `outputs/messages/rooms/<roomId>/`。未知群不会进入客户运营和 Agent 流程。

## 状态说明

- `IMPORTED`：已扫描但未命中关键词
- `SUGGESTED`：低置信候选，建议人工确认
- `AUTO_CONFIRMED`：自动命中关键词或高置信度词
- `CONFIRMED`：经纪人手动确认
- `REJECTED`：经纪人手动拒绝

## 迁移说明

原 Qiwei 项目中的 `ExternalGroup` SQLite 表、群状态机和关键词识别逻辑改为文件化：

- 群列表 → `outputs/groups/rooms-*.json`
- 最新快照 → `outputs/groups/rooms-latest.json`
- 确认映射 → `outputs/groups/confirmed-mapping.json`
- 拒绝映射 → `outputs/groups/rejected-mapping.json`
- 关键词配置 → `outputs/groups/customer-keywords.json`
- 扫描摘要 → `outputs/groups/group-scan-manifest.json`
- 群回调新消息 → `outputs/messages/rooms/<roomId>/`

MCP 工具：

- `qiwei_sync_external_groups`
- `qiwei_list_external_groups`
- `qiwei_analyze_group_members`
- `qiwei_confirm_external_group`
- `qiwei_add_external_group`
- `qiwei_reject_external_group`
- `qiwei_configure_group_keywords`