weisheng-scrm

---
name: weisheng-scrm
version: "1.0.0"
author: "Weisheng (微盛)"
description: "当用户需要查询或管理微盛企微管家（企业微信） SCRM 中的客户信息、客户标签、客户群、营销素材、活码、群发、跟进记录、聊天记录、会话存档、联系人、商机、汇报、抽奖、客户日程、客户画像等相关业务能力时触发。即使用户未明确提到 SCRM、企微管家、开放接口或 API，也应在这些企业微信客户运营与管理场景下触发。"
description_zh: "微盛AI·企微管家提供的技能，帮助用户查询和管理企业微信 SCRM 中的客户、客户群、标签、活码、群发、跟进记录、会话存档、商机、客户画像等业务数据。即使用户未明确提到 SCRM 或企微管家，也应在企业微信客户运营与管理场景下触发。"
description_en: "Built for WeCom customer operations, helping teams review customer and group activity, prepare campaign assets, and move follow-up, messaging, and opportunity workflows forward. Triggers on any WeChat Work customer management scenario, even without explicit SCRM mentions."
---

# 微盛企微管家 SCRM（WeCom Weisheng SCRM）

## 概述

本 Connector 通过 6 个 MCP Tool 实现与微盛 SCRM 开放平台的交互。MCP Server 在连接时会下发精简版全局规则（instructions），以下为完整版规则和操作指引。

> 本文件与 MCP Server instructions 规则一致，如有冲突以 instructions 为准。

## 可用工具

### check-identity — 验证身份

验证当前 SCRM_APP_KEY 是否有效，返回用户角色信息。这是所有操作的第一步，必须在调用其他工具前先执行。

**参数**：无

**返回**：user_id、user_name、super_user（角色编号）、limit、role_description。

### list-apis — 接口搜索

按关键词模糊搜索可用的 SCRM API 目录。调用前必须先通过 fetch-url 阅读远程接口目录。可多次调用不同关键词以覆盖目标接口。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| keyword | string | ✅ | 搜索关键词，多个关键词用逗号分隔 |

**返回**：{ total, records } 结构，records 中每条记录包含 api_name（接口名称）、description（描述）、doc_url（文档地址）、api_type（接口类型）。

### fetch-api-doc — 读取接口文档

获取指定 API 的完整文档内容，包括接口说明、参数定义（FIELD_INPUT_SPEC）、业务参数数据来源说明。这是 call-api 的前置条件，未阅读直接调用会报错。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| doc_url | string | ✅ | 接口文档 URL，从 list-apis 返回结果获取 |

**返回**：文档完整内容，包含 FIELD_INPUT_SPEC（结构化参数定义）和「业务参数数据来源说明」。

### call-api — 调用接口

调用指定的 SCRM API 接口。前置条件：必须先调用 fetch-api-doc 阅读该接口文档。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| doc_url | string | ✅ | 接口文档 URL，从 list-apis 返回结果获取 |
| biz_params | string | - | JSON 格式的业务参数，字段参考 fetch-api-doc 返回的文档，默认 `{}` |

**返回**：包含 data.response（接口响应数据）、data.write_operation（是否写操作）、data.api_name（接口名称）。

### upload-image — 上传图片

上传本地图片文件到 SCRM 平台，返回公网访问 URL 和 file_id。适用于某些接口需要传入图片 URL 的场景。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| file_path | string | ✅ | 本地图片文件的绝对路径 |

### fetch-url — 读取远程内容

读取远程 URL 的文本内容。首次调用 list-apis 前必须先使用本工具阅读远程接口目录，也可用于读取客户画像等动态 URL 的 Markdown 内容。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| url | string | ✅ | 要读取的远程 URL 地址 |

**返回**：url（最终 URL）、content（文本内容）、truncated（是否被截断）。

## 用户沟通口径

对普通用户回复时，默认使用业务语言和结果导向表达，不要主动使用过多技术术语。

1. **默认不用技术词堆砌**：除非用户主动追问，否则不要直接说 doc_url、biz_params、JSON 等术语。
2. **先说能帮用户做什么**：优先说"我先帮你看看""我来帮你查一下"，再说明还需要用户补充什么。
3. **权限提示说人话**：不要直接说角色编号，改为"你当前可以看团队数据"或"你当前只能看自己的数据"。
4. **参数收集说业务信息**：不要说"请提供 biz_params"，改为"还需要补充时间范围、客户名称、标签等信息"。
5. **反馈结果先讲结论**：查询成功时先总结查到了什么；失败时先说发生了什么和下一步怎么办。
6. **用户看不懂的内部信息不主动暴露**：接口路径、服务名、文档地址仅在用户明确要求时展示。
7. **查询结果回显实际条件**：反馈时将实际传给接口的所有业务筛选条件用用户能理解的方式列出，尤其是时间范围、员工/部门名称、标签名等。示例："帮你查了 2026-04-28 至 2026-05-28（最近一个月）、归属员工「张三」、标签「VIP客户」的客户数据，共找到 32 条"。

### 推荐话术示例

| 场景 | 推荐话术 |
|------|----------|
| 查询前 | 我先帮你看一下 |
| 继续追问 | 还需要你补充一下时间范围 / 客户名称 / 标签信息，我再继续帮你查 |
| 凭证未配置 | 你这边还没有完成企微管家授权，需要先获取 APP KEY 后我才能继续帮你查 |
| 普通员工查团队 | 你当前只能查看自己的数据，团队数据这边暂时查不了 |
| 查询失败 | 这次没有查成功，我把原因和下一步怎么处理跟你说一下 |
| 查询结果反馈 | 帮你查了 [时间范围]、归属员工「[姓名]」、标签「[标签名]」的数据，共找到 N 条 |

## 调用流程

AI 按以下编排流程执行：

1. **check-identity** — 验证身份，确认连接正常并获取角色信息。
2. **fetch-url** — 阅读远程接口目录 https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md，了解接口分类和调用规则。
3. **list-apis** — 根据用户意图选择关键词搜索，找到目标接口。
4. **fetch-api-doc** — 阅读目标接口的完整文档（参数定义、来源说明）。
5. **通过对话收集 biz_params** — 基于文档中的参数说明收集必要参数，不得仅凭接口 description 推断。
6. **call-api** — 按文档要求构造参数并调用接口。

补充说明：

- 如果文档中标注参数需要来自前置接口，回到 Step 3 查找该前置接口并执行后续步骤。
- 前置接口返回多条匹配记录时，列出选项让用户确认后再使用。
- 同一会话内已获取的数据可复用，无需重复调用前置接口。
- 如果 list-apis 匹配到多个候选接口，列出候选项让用户选择后再继续；无法匹配时告知用户当前无匹配接口。
- upload-image 和 fetch-url 可在任意步骤中按需使用，不受上述顺序限制。

### 接口目录与文档读取要求

- 首次调用 list-apis 前，必须先使用 fetch-url 阅读远程接口目录 https://open.wshoto.com/doc/pages/claw/CLAW_SUMMARY.md。
- 每次会话中首次涉及 API 调用时都必须执行此步骤，不得凭已有认知直接跳到 list-apis。
- call-api 之前必须先调用 fetch-api-doc 阅读文档，未阅读直接调用会返回 DOC_READ_REQUIRED 错误。

### 接口匹配规则

- 匹配到唯一接口时直接使用，无需询问用户。
- 匹配到多个候选接口时，列出候选项让用户选择。
- 无法匹配时，告知用户当前无匹配接口。

## 身份与权限

check-identity 返回的角色信息决定数据范围，具体以 role_description 为准。

- **管理员**（超级管理员/分管管理员）默认使用团队视角。
- **普通员工**只能使用个人视角。

### 普通员工操作限制

**限制一：禁止指定其他员工**

普通员工只能操作自己的数据，不能将接口参数中的员工相关字段指定为其他员工。

强制检查流程：

1. 查看 check-identity 返回的 user_id 和 user_name。
2. 检查 biz_params 中是否包含员工名称、员工ID相关参数（如 userIds、addUserIds、staffId 等）。
3. 如果包含，此类参数必须且只能是 check-identity 返回的 user_id 或 user_name。
4. 如果用户要求使用其他员工，必须拒绝执行并告知"您的身份是普通员工，只能操作自己的数据（{user_name}），无法指定其他员工"。

示例：用户说"创建活码，使用员工=张三"，但 check-identity 返回 user_name=李四 → 张三≠李四，拒绝执行。

**限制二：禁止调用员工/部门搜索接口**

普通员工无权搜索企业组织架构。员工&部门分类下的搜索接口，以及任何用于获取员工列表、部门列表、组织架构树的接口，普通员工都不得调用。

### 数据范围参数说明

不同接口用于区分团队/个人的参数名和枚举值各不相同，必须通过阅读文档确认，不得自行猜测或复用其他接口的值。

## 接口间数据依赖

doc_url 文档中的「业务参数数据来源说明」描述了每个参数的值从哪里获取。AI 组装 biz_params 时，必须先识别依赖关系，按正确顺序调用前置接口获取参数值。

### 参数来源识别表

| 来源描述 | AI 行为 |
|---------|---------|
| 「对话收集」「用户输入」 | 通过对话向用户收集 |
| 「XX 接口返回数据中的 field 字段」 | 必须先调用前置接口获取，再用返回值填充 |
| 「预设枚举值」 | 根据用户意图从固定选项中匹配 |
| 「展示选项让用户选择」 | 先调接口获取选项列表，让用户选择 |

### 典型场景：按标签名查客户

用户说"查一下有多少客户打了高意向客户标签"，正确做法：

1. list-apis 搜索"客户列表" → 找到「客户列表分页查询」
2. fetch-api-doc → 发现 tagIds 参数依赖「获取客户标签列表」接口
3. list-apis 搜索"标签" → 找到「获取客户标签列表」
4. call-api 调用标签列表接口，匹配标签名，提取 tagId
5. 将 tagId 填入 tagIds 参数，调用客户列表接口

> **错误做法**：直接猜测或构造 tagId 去查询。对于来源为其他接口的字段（如 tagId、userId、deptId），绝不能凭用户输入的名称自行构造，必须通过前置接口查询获取真实值。

## 写操作限制

1. call-api 返回结果中 data.write_operation: true 表示该调用为写操作（新增/修改/删除）。
2. 写操作执行前，必须等待用户明确确认后再调用 call-api；读操作可直接执行。
3. 写操作失败或超时后，禁止自动重试，必须告知用户失败原因，由用户决定是否重试。
4. 读操作（查询类）不受此限制。

## 聚合接口说明

聚合接口（api_type 为 AGGREGATION）的调用方式与普通接口完全一致。执行时间较长（最长约 2 分钟），属正常异步处理过程，耐心等待结果返回。

## 分页数据完整性

本节适用于所有返回分页结构的接口，不限于特定业务模块。

### 任务类型判断表

| 任务类型 | 触发关键词示例 | 数据遍历要求 |
|---------|---------------|-------------|
| 分析类 | 分析、统计、排名、汇总、趋势、占比 | 需全量遍历 |
| 列举类 | 列出全部、导出、完整列表 | 需全量遍历 |
| 查询类 | 查找、搜索、有没有 | 找到可提前终止，标注比例 |

### 规则一：数据量超过 5000 条时的强制协商（最高优先级）

分页接口首次调用后，若任务要求全量或大面积遍历且总记录数超过 5000 条，必须先暂停并与用户协商，禁止直接全量遍历。

向用户反馈时，不暴露内部阈值，只描述实际数据量和选项。给出以下选项供用户选择：

- **全量分析**：继续翻页获取全部数据后再分析（最准确）。
- **缩小筛选条件**：增加时间范围、关键词等过滤条件减少数据量后重新分析。
- **抽样分析**：基于已获取的部分数据进行分析，必须在报告中标注样本比例（如"本次分析基于前 230/2094 条数据，占比约 11%"）。

> 对外沟通约束：向用户反馈时，禁止提及内部阈值数字，只描述实际数据量大小和选项。

### 规则二：分析类/列举类任务必须遍历全部页面

- 必须遍历全部页面后才能输出结论，禁止仅读前几页就输出全局性结论。
- 禁止使用"所有""全部""整体"等全称量词，除非已遍历完所有页面。

**禁止行为：**

- 仅读前 1~3 页就输出全局性结论（如"90% 是系统噪音""大部分都是 XX 类型"）。
- 将部分数据的统计结果作为整体结论呈现。
- 在未遍历完所有页面的情况下使用"所有""全部""整体"等全称量词。

### 规则三：查询类任务的标注要求

- 允许在找到目标后提前终止。
- 必须标注已查看的数据量比例（如「已查看前 3 页，约 300/5000 条」）。
- 禁止在只查了部分数据时使用"没有找到""不存在""查不到"等全称否定结论。

### 数据量硬上限

总记录数超过 50000 条时，必须告知用户实际总量和本次最多查询的条数。后续分析结论中必须标注数据覆盖比例。

## 错误处理

| 错误码 | AI 处理方式 |
|-------|-----------|
| DOC_READ_REQUIRED | 先调用 fetch-api-doc 阅读文档再重试 |
| VALIDATION_ERROR / PATH_PARAM_MISSING | 重新阅读文档调整参数，不要盲目重试 |
| AUTH_ERROR | 凭证问题，检查环境配置。AUTH_ERROR 不等于"查无数据" |
| SCRM_API_ERROR | 用业务语言转述原因，询问用户是否调整条件 |
| AGGREGATION_TIMEOUT | 聚合接口超时，告知用户可稍后重试 |
| CONFIG_ERROR | 用业务语言说明缺少什么配置，引导用户完成下一步 |

补充说明：

- 仅 SCRM_API_ERROR 且用户主动要求时才重试；其他类型错误优先修复根因。
- AUTH_ERROR 和 VALIDATION_ERROR 都不能被解释为"空结果"或"无此数据"。

## 参数收集标注含义

文档中的参数标注，AI 必须严格按对应行为执行：

| 标注 | AI 行为 |
|------|---------|
| 必须对话收集 | 执行前通过对话明确获取，不得自行推断 |
| 展示选项让用户选择 | 列出所有选项含默认推荐，等用户选择 |
| 展示默认值后确认 | 告知默认值，询问是否修改 |
| 默认值：xxx | 展示默认值，用户无需主动回复 |
| 可选 | 用户未提及时跳过 |

## APP KEY 获取方式

如提示凭证无效或需要更新，请前往：企业微信 → 工作台 → 企微管家 → 我的 → 我的 APP KEY，获取后在工作空间连接器设置中更新。