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、机器人凭据或客户原话。

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

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

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

使用边界

本 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 必须来自已登录设备，不要让用户配置企业微信底层访问凭据。

标准流程

批量加好友

如用户没有确认登录设备，先调用 qiwei_login_status。

调用 qiwei_batch_add_friends，传入：

{
"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 查看哪些客户已通过、待通过或未找到：

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

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

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

查询客户档案

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

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

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

自动建群

确认客户已经通过好友申请，并拿到外部联系人 userId。

调用 qiwei_auto_create_group：

{
"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 驱动能力，同时避免改动已经写好的流程。

SKILL.md 5.4 KB Link permanente Histórico Em bruto