下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-o0lff848--wenear-scrm-mcp-skill.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md，安装 @org-o0lff848/wenear-scrm-mcp-skill。阅读全文 （展开查看完整说明）
概述
微纳 SCRM 操作技能
通过 MCP 接口操作企业微信 SCRM 系统。
当前仅启用 4 个工具：count_follow_customers、filter_customers、create_gather_code、list_members。服务端虽然还注册了群发、朋友圈、群活码、客户群等工具，但本 skill 不启用，客户端白名单会直接拦截相关调用。如需扩展，见 references/tools.md 末尾说明。
快速开始
所有脚本在 scripts/ 目录，必须在该目录下执行（脚本间互相 import）：
cd C:/Users/mo/.workbuddy/skills/wenear-scrm/scripts
PY="C:/Users/mo/.workbuddy/binaries/python/envs/default/Scripts/python.exe"
$PY members.py list # 查成员，拿 userId
$PY customers.py count --status 3 # 统计已转化客户
$PY customers.py filter --limit 100 # 筛选客户导出 Excel 需要 openpyxl（已装在上方 venv）。用系统 python 跑则自动降级为 CSV。
核心规则（务必遵守）
1. 人名 → userId 必须先解析
所有涉及员工的参数（负责人、接待员工、执行成员）只接受 userId，不接受昵称。业务描述里给的是人名，第一步永远是用 members.py 解析：
$PY members.py find 张三 # → 输出该成员的 userId
$PY members.py id 张三 # 只输出 userId，便于串联customers.py 与 gather_code.py 支持 --owner-name / --employees 直接传昵称，内部自动解析。若一个昵称命中多人，脚本会报错退出并列出候选，此时必须让用户确认，不要自行猜测。
2. 单次最多 100 条，取全量要用分片
filter_customers 的 maxResults 上限 100，且接口没有分页游标（无 offset/page）。要拿超过 100 条的数据，用 customers.py fetch 按时间自动分片去重合并：
$PY customers.py fetch --start 2026-01-01 --end 2026-08-31 --chunk month --out all.xlsx粒度选择：数据稀疏用 month，密集用 week，日增超 100 用 day。若某分片返回正好 100 条，脚本会警告该段可能被截断，应改用更细粒度重拉。
3. 写操作必须预演，确认后才提交
create_gather_code 会真实创建渠道码，不可撤回。脚本默认只打印参数预览，必须显式加 --confirm 才提交。执行前把渠道码名称、接待员工、欢迎语复述给用户确认。
工具与脚本对照
| 需求 | 脚本命令 |
|---|---|
| 查在职成员 / 解析 userId | members.py list / find / id |
| 统计跟进客户数 | customers.py count [条件] |
| 筛选客户（≤100 条） | customers.py filter --limit 100 |
| 全量拉取客户 | customers.py fetch --start --end --chunk |
| 客户结构分析 | customers.py filter --summary 或 fetch --summary |
| 客户分析 HTML 报表 | report.py --start --end --out report.html |
| 导出客户名单 | 加 --out xxx.xlsx / --out xxx.csv |
| 创建渠道码 | gather_code.py create --name --employees --confirm |
| 任意已启用工具底层调用 | wenear_client.py call <tool> '<json>' |
| 查看已启用工具定义 | wenear_client.py list-tools |
群发消息、发朋友圈、创建群活码、查询客户群均不在本 skill 能力范围内，用户提出这类需求时应说明当前未启用，而不是尝试调用。
完整参数字典见 references/tools.md，典型业务场景见 references/recipes.md。
常用筛选参数
customers.py 的 count / filter / fetch 共用同一套条件：
| 参数 | 说明 |
|---|---|
--status | 客户状态：1未转化 2无效 3已转化 |
--gender | 性别：0未知 1男 2女 |
--keyword | 模糊匹配客户名称/备注/手机号 |
--tel | 联系电话模糊匹配 |
--tag-ids / --exclude-tag-ids | 包含/排除标签ID，逗号分隔 |
--tag-match | 1任一（默认） 2全部 |
--start / --end | 添加时间范围 yyyy-MM-dd（结束日含当天） |
--owner-ids / --owner-name | 负责人 userId / 昵称（可重复传） |
--source / --channel / --level | 客户来源 / 来源渠道 / 客户级别 |
不传负责人时默认统计/筛选当前用户（即令牌持有者）的客户，这是最容易踩的坑：想查全公司数据，必须先 members.py list 拿全部成员，再用 --owner-ids 逐个指定。
字段语义速查
customerStatus：1未转化 / 2无效 / 3已转化（空字符串表示未设置，脚本显示为"未知"）gender：0未知 / 1男 / 2女relationId：客户关系ID，导出 CSV 里带这一列tagIds：返回的是{tagId, tagName}对象数组，导出时会自动拼成标签名字符串termOfValidity：渠道码有效期，-1 为永久
生成客户分析报表
需要给业务方或存档一份可视化报告时，用 report.py（自包含 HTML，内联 SVG 图表，断网可打开）：
$PY report.py --start 2026-01-01 --end 2026-08-31 --chunk month --out 客户分析报表.html
$PY report.py --start 2026-01-01 --end 2026-08-31 --owner-name 张三 --out report.html
$PY report.py --json 已导出数据.json --out report.html # 从 JSON 回读，不重复请求接口包含 KPI 概览、状态/性别环形图、来源与标签 TOP 榜、按月新增趋势、客户明细表。生成后用 present_files 展示给用户。样本量太小（如个位数）时不要过度解读百分比。
排错
| 现象 | 原因与处理 |
|---|---|
HTTP 400 空响应 | 缺少 MCP 要求的 Accept 头。用本技能的 wenear_client.py，不要用通用 MCP 模板脚本 |
HTTP 401/403 | 令牌失效或缺失，见下方凭证配置 |
缺少接口令牌 | 未配置 WENEAR_SCRM_TOKEN 且配置文件不存在 |
工具 xxx 未在本 skill 中启用 | 命中白名单拦截，该工具当前不可用 |
网络不可达 / SSL EOF | 偶发抖动，客户端已内置 3 次重试；持续失败再检查网络 |
| 返回数量总是偏少 | 未传负责人，默认只查当前用户；或单次 100 条上限，改用 fetch |
| 昵称解析报"命中多人" | 让用户确认具体是哪位成员，勿自行选择 |
凭证配置
skill 内不存放任何令牌（便于分享与版本管理）。按以下顺序读取，命中即止：
- 环境变量
WENEAR_SCRM_TOKEN（优先级最高） - 配置文件
~/.workbuddy/wenear_scrm.json：{"token": "...", "endpoint": "..."}
接口地址可用环境变量 WENEAR_SCRM_ENDPOINT 覆盖，默认 https://console.goodscrm.cn/api/mcp。
数据脱敏约定
本 skill 的所有文件（SKILL.md、scripts、references）中不得出现真实人名、userId、手机号、令牌等业务敏感数据。示例统一使用「张三」「李四」等占位昵称、<userId> <标签ID> 等尖括号占位符。新增脚本或文档时沿用此约定。
