---
name: qiwei-customer-ops
description: 迁移自 Qiwei 项目的客户群运营能力：批量搜索并添加企微好友、检查好友申请状态、查询客户档案、自动创建客户服务群、设置群名、邀请协作成员、发送欢迎语。所有企微调用必须通过 Fmode 网关，并以 mcp/catalog/qiwei-endpoints.json 的 method 与参数为准；不替换 qiwei-login、qiwei-api-catalog、订阅和官方 CLI 既有流程。
---

# 企微客户管理与运营

## 客户主档

4320 Dashboard 的“客户管理”首先展示真实企微会话沉淀的客户主档：

- 权威画像、标签、任务和预警保存在 `outputs/messages/agent-workbench.db`；
- Agent 从真实客户消息提取画像字段时，自动记录字段来源消息和更新时间；
- `qiwei-portrait-tags` 保存的画像与标签也回写同一主账，不另建冲突档案；
- 客户管理页可人工核对目标、需求、预算、计划时间、决策人和标签，修改只更新内部主档，不向客户发送消息；
- `outputs/customers/index.json` 是脱敏查询投影，不保存联系人原始 ID、机器人凭据或客户原话。

客户主档同时提供三类经营能力：

1. **客户时间线**：按时间统一展示真实消息、画像更新、内部任务和预警；
2. **下一步行动**：依据画像缺口、待办和预警生成内部建议，必须标明依据，不自动外发；
3. **证据追溯**：画像、任务和预警保留来源消息与更新时间，不能把模型推断写成已确认事实。

客户会话产生的内部任务可以从客户主档跳转到智能会话继续处理，但不能把内部任务或画像字段原样发送给客户。

## 使用边界

本 skill 只负责客户运营业务动作：

- 批量按手机号搜索并添加好友；
- 检查好友申请状态；
- 按手机号或 externalUserId 查询客户档案；
- 按外部联系人 `userId`/成员列表创建服务群；
- 可选设置群名、邀请协作成员、发送欢迎语。

以上网关动作位于客户主档之后；查看和维护已沉淀画像不要求重新调用网关。

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

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

## 接口规范

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

- 批量加好友与检查好友状态使用 `/contact/searchContact`；
- 自动建群使用 `/room/createRoom`、`/room/modifyRoomName`、`/room/inviteRoomMember`、`/msg/sendText`；
- 客户档案使用 `/contact/searchContact`、`/contact/getWxContactList`、`/room/getRoomList`；
- 请求信封固定为 `{ "uid": "...", "method": "...", "params": {...} }`；
- 鉴权固定走 `Authorization: Bearer <Fmode token>`；
- `guid` 必须来自已登录设备，不要让用户配置企业微信底层访问凭据。

## 标准流程

### 批量加好友

1. 如用户没有确认登录设备，先调用 `qiwei_login_status`。
2. 调用 `qiwei_batch_add_friends`，传入：

```json
{
  "guid": "<已登录设备 guid>",
  "customers": [
    { "phone": "13800000000", "name": "张三", "greeting": "你好，方便加您企业微信沟通。" }
  ],
  "addToAllowlist": true,
  "rateLimitPerMinute": 12
}
```

也可以传 `phones`，或传 `.xlsx` 格式的 `filePath` 读取 Excel。Excel 至少需要手机号列；旧版 `.xls` 请先另存为 `.xlsx`。

- 用户明确说“测试好友”“演示联系人”时传 `addToAllowlist=true`，成功后自动加入个人消息白名单并开启待审核监听。
- 普通批量拓客时省略该字段，避免扩大 AI 监听范围。

### 检查好友申请状态

批量加好友后，可调用 `qiwei_check_friend_status` 查看哪些客户已通过、待通过或未找到：

```json
{
  "guid": "<已登录设备 guid>",
  "phones": ["13800000000", "13900000000"]
}
```

返回每条手机号的 `searchStatus` 与 `statusText`：

- `already_friend`：已是双向好友；
- `already_added_by_other`：已被其他人添加；
- `not_added`：可发起好友申请；
- `not_found`：搜索不到该用户。

### 查询客户档案

拿到 externalUserId 或手机号后，调用 `qiwei_get_customer_profile`：

```json
{
  "guid": "<已登录设备 guid>",
  "phone": "13800000000"
}
```

返回联系人搜索结果、外部联系人列表匹配项、群列表，以及本地已保存的画像文件（如有）。

### 自动建群

1. 确认客户已经通过好友申请，并拿到外部联系人 `userId`。
2. 调用 `qiwei_auto_create_group`：

```json
{
  "guid": "<已登录设备 guid>",
  "customerUserId": "<客户 userId>",
  "supportMemberIds": ["<协作成员 userId>"],
  "groupName": "张三服务群",
  "welcomeText": "欢迎进群，我们会在这里同步服务进展。"
}
```

如有多个初始成员，传 `memberList` 代替 `customerUserId`。

## 迁移说明

原 Qiwei 项目中的 Express 路由、SQLite 业务表和本地任务记录没有接管目标包已有运行形态。本迁移保留核心企微动作，并改为 Claude Code MCP 工具：

- `qiwei_batch_add_friends`
- `qiwei_check_friend_status`
- `qiwei_get_customer_profile`
- `qiwei_auto_create_group`

这样可以复用目标包已有登录、订阅、鉴权、错误分层和 catalog 驱动能力，同时避免改动已经写好的流程。