MCP 工具
21 个工具 + 权限矩阵
这是什么
一句话：给 AI 助手的一份「操作菜单」——菜单上有 21 道菜，AI 点哪道，系统就做哪件事。
市场部同事用 AI 助手（WorkBuddy、豆包这类）时，不需要先登录后台、再一页页翻。他可以直接问： 「上周那个活动报名了多少人？」「把 A 级线索里北京的找出来」—— AI 会自己去调下面这 21 个动作里的某一个，把结果讲给他听。
怎么接到 AI 助手里
拿一份「出厂技能包」装上就行——里面已经写好了所有配置，同事不用自己填参数。 安装手册见「技能包」那一页。
# 同事跟 AI 说的话，会被翻译成某一次工具调用 「帮我看看这个月 A 级线索里北京的有多少」 ↓ cgl_leads_search(grade="A", city="北京", start="2026-10-01") ↓ # 它背后调的是同一个接口： GET https://scrm.jxccwx.com/api/v1/leads?grade=A&city=北京&start=2026-10-01
全部 21 个动作
| AI 看到的名字 | 干什么 | 背后其实是哪个接口 | 需要什么权限 |
|---|---|---|---|
| cgl_event_get | 读取单个活动的详情：统计、报名表单字段、分享码。 | GET /api/v1/events/{aid} | event:read |
| cgl_event_signup | 替某人在活动上报一次名。会自动创建/匹配线索、算分、写归因。重复报名默认会被拒；确实要重复报名传 allow_duplicate=true。 | POST /api/v1/events/{aid}/signups | event:write |
| cgl_event_signups | 列出某活动的报名记录（含审核状态、顾问、渠道、报名时间）。 | GET /api/v1/events/{aid}/signups | event:read |
| cgl_events_list | 列出活动及其报名数、浏览量、状态。 | GET /api/v1/events | event:read |
| cgl_lead_add_behavior | 记录一次行为（如参加活动、下载资料），会按评分规则自动算分。 | POST /api/v1/leads/{uid}/behaviors | lead:write |
| cgl_lead_add_remark | 给线索追加一条跟进备注。⚠️ 写之前先 cgl_lead_get 确认这条线索就是用户说的那条 —— 1.1 万条存量里同名同姓很常见。 | POST /api/v1/leads/{uid}/remark | lead:write |
| cgl_lead_find_duplicates | 用手机号/邮箱/openid 任一键查是否已有同名同号的线索，返回命中的线索。新建线索前应该先查一次，避免重复入库。 | GET /api/v1/leads/duplicates | lead:read |
| cgl_lead_get | 读取单条线索的完整信息：基本资料、标签、最近行为、跟进备注、归因链。⚠️ 手机号/邮箱默认脱敏（138****9999），这是权限设计不是数据坏了。 | GET /api/v1/leads/{uid} | lead:read |
| cgl_lead_set_status | 变更线索跟进状态。状态码是原站的 1/2/4/6/7（不连续）：1=未跟进 2=已拒绝 4=跟进中 6=转化成功 7=无效线索。 | POST /api/v1/leads/{uid}/status | lead:write |
| cgl_lead_set_tags | 给线索打标签或取消标签。 | POST /api/v1/leads/{uid}/tags | lead:write |
| cgl_leads_export_csv | 导出线索明细为 CSV 文本。条数可能很大，先想清楚是否真需要全量；要精确统计优先用 cgl_stats_* 系列。 | GET /api/v1/leads/export.csv | lead:read |
| cgl_leads_search | 按关键词/状态/分级/渠道/行业/城市/时间范围搜索线索列表。关键词会模糊匹配姓名、公司、手机、邮箱、职位。默认每页 20 条。 | GET /api/v1/leads | lead:read |
| cgl_qrcodes_list | 列出已生成的带参二维码及其扫码数、带来的线索数。 | GET /api/v1/qrcodes | qrcode:read |
| cgl_stats_funnel | 各线索状态的数量分布（按状态码升序，返回 status/label/count）。状态码 1/2/4/6/7 不连续：1=未跟进 2=已拒绝 4=跟进中 6=转化成功 7=无效线索。⚠️ 它不代表任何递进关系，而是当前全量线索的状态快照。 | GET /api/v1/stats/funnel | stats:read |
| cgl_stats_leaderboard | 顾问业绩榜 + 活动排行 + 问卷排行。做「谁做得好」类问题用这个。 | GET /api/v1/stats/leaderboard | stats:read |
| cgl_stats_overview | 看板总览：线索总量/新增、报名数、答卷数、高价值线索占比等，含环比。 | GET /api/v1/stats/overview | stats:read |
| cgl_stats_trend | 新增线索 / 报名 / 答卷的按日趋势。 | GET /api/v1/stats/trend | stats:read |
| cgl_survey_answers | 列出某问卷的答卷记录。 | GET /api/v1/surveys/{qid}/answers | survey:read |
| cgl_survey_schema | 读取问卷的题目结构（题目、选项、类型），用于理解答卷里的字段含义。 | GET /api/v1/surveys/{qid}/schema | survey:read |
| cgl_surveys_list | 列出问卷及其答卷数、访问量。 | GET /api/v1/surveys | survey:read |
| cgl_whoami | 确认当前 API Key 有效，并列出它的权限范围和数据可见量。任何其他操作之前先跑这个：确认 key 能用、有没有写权限，避免误判「系统没数据」。 | GET /api/v1/meta/scopes | 有效钥匙即可 |
每条动作背后都对应着上一页那个接口清单里的一个真实接口—— 这一层没有另开一套逻辑，只是换个说法讲给 AI 听。 所以「AI 能做的事」和「接口能做的事」永远一致，不会各说各话。
每个动作要吃哪些参数
下面就是 AI 看到的说明书原文——每个参数是必填还是可选、什么类型、什么意思，全部从代码里读出来。
（参数名里有 pageindex 这种拼法的，是照搬老系统的命名，故意没改，免得老脚本用不了。）
cgl_event_get 1 个参数 必填 1event:read 读取单个活动的详情：统计、报名表单字段、分享码。
读取单个活动的详情：统计、报名表单字段、分享码。
对应接口：
GET
/api/v1/events/{aid}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| aid | integer | 必填 | 活动 ID（注意主键叫 aid，不是 id） |
cgl_event_signup 10 个参数 必填 3event:write 替某人在活动上报一次名。会自动创建/匹配线索、算分、写归因。重复报名默认会被拒；确实要重复报名传...
替某人在活动上报一次名。会自动创建/匹配线索、算分、写归因。重复报名默认会被拒；确实要重复报名传 allow_duplicate=true。
对应接口：
POST
/api/v1/events/{aid}/signups
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| aid | integer | 必填 | 活动 ID |
| allow_duplicate | boolean | 可省 | 是否允许重复报名，默认 false |
| answers | object | 可省 | 额外报名题答案，键为字段名 |
| channel | string | 可省 | 渠道标识，默认 api |
| company | string | 可省 | 公司 |
| consultant_id | integer | 可省 | 归属顾问 ID，默认归给当前 Key 的归属人 |
| corpemail | string | 可省 | 企业邮箱 |
| jobtitle | string | 可省 | 职位 |
| mobile | string | 必填 | 手机号（必填） |
| name | string | 必填 | 姓名（必填） |
cgl_event_signups 1 个参数 必填 1event:read 列出某活动的报名记录（含审核状态、顾问、渠道、报名时间）。
列出某活动的报名记录（含审核状态、顾问、渠道、报名时间）。
对应接口：
GET
/api/v1/events/{aid}/signups
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| aid | integer | 必填 | 活动 ID |
cgl_events_list 2 个参数 event:read 列出活动及其报名数、浏览量、状态。
列出活动及其报名数、浏览量、状态。
对应接口：
GET
/api/v1/events
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | 可省 | 活动名模糊搜索 |
| status | string | 可省 | 活动状态，如 draft / published |
cgl_lead_add_behavior 4 个参数 必填 2lead:write 记录一次行为（如参加活动、下载资料），会按评分规则自动算分。
记录一次行为（如参加活动、下载资料），会按评分规则自动算分。
对应接口：
POST
/api/v1/leads/{uid}/behaviors
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| behavior_type | string | 必填 | 行为类型标识，如 signup_event / download / visit |
| score | integer | 可省 | 不传则由评分规则计算 |
| target_title | string | 可省 | 行为对象标题，如活动名 |
| uid | integer | 必填 | 线索 ID |
cgl_lead_add_remark 2 个参数 必填 2lead:write 给线索追加一条跟进备注。⚠️ 写之前先 cgl_lead_get 确认这条线索就是用户说的那条 —— 1.1 万条存量里同名同姓很常见。
给线索追加一条跟进备注。⚠️ 写之前先 cgl_lead_get 确认这条线索就是用户说的那条 —— 1.1 万条存量里同名同姓很常见。
对应接口：
POST
/api/v1/leads/{uid}/remark
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| content | string | 必填 | 备注正文，如「电话沟通，考虑中」 |
| uid | integer | 必填 | 线索 ID |
cgl_lead_find_duplicates 3 个参数 lead:read 用手机号/邮箱/openid 任一键查是否已有同名同号的线索，返回命中的线索。新建线索前应该先查一次，避免重复入库。
用手机号/邮箱/openid 任一键查是否已有同名同号的线索，返回命中的线索。新建线索前应该先查一次，避免重复入库。
对应接口：
GET
/api/v1/leads/duplicates
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| corpemail | string | 可省 | 企业邮箱 |
| mobile | string | 可省 | 手机号 |
| openid | string | 可省 | 微信 openid |
cgl_lead_get 3 个参数 必填 1lead:read 读取单条线索的完整信息：基本资料、标签、最近行为、跟进备注、归因链。⚠️...
读取单条线索的完整信息：基本资料、标签、最近行为、跟进备注、归因链。⚠️ 手机号/邮箱默认脱敏（138****9999），这是权限设计不是数据坏了。
对应接口：
GET
/api/v1/leads/{uid}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| behaviors | integer | 可省 | 附带最近 N 条行为，默认 20，0 表示不带 |
| remarks | integer | 可省 | 附带最近 N 条跟进备注，默认 20，0 表示不带 |
| uid | integer | 必填 | 线索 ID |
cgl_lead_set_status 3 个参数 必填 2lead:write 变更线索跟进状态。状态码是原站的 1/2/4/6/7（不连续）：1=未跟进 2=已拒绝 4=跟进中 6=转化成功 7=无效线索。
变更线索跟进状态。状态码是原站的 1/2/4/6/7（不连续）：1=未跟进 2=已拒绝 4=跟进中 6=转化成功 7=无效线索。
对应接口：
POST
/api/v1/leads/{uid}/status
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| remark | string | 可省 | 变更说明（会进审计） |
| status | integer | 必填 | 目标状态码：1/2/4/6/7 |
| uid | integer | 必填 | 线索 ID |
cgl_lead_set_tags 3 个参数 必填 2lead:write 给线索打标签或取消标签。
给线索打标签或取消标签。
对应接口：
POST
/api/v1/leads/{uid}/tags
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mode | string | 可省 | add=增加（默认）/ remove=移除 / replace=整体替换 |
| tag_ids | array | 必填 | 标签 ID 列表 |
| uid | integer | 必填 | 线索 ID |
cgl_leads_export_csv 5 个参数 lead:read 导出线索明细为 CSV 文本。条数可能很大，先想清楚是否真需要全量；要精确统计优先用 cgl_stats_* 系列。
导出线索明细为 CSV 文本。条数可能很大，先想清楚是否真需要全量；要精确统计优先用 cgl_stats_* 系列。
对应接口：
GET
/api/v1/leads/export.csv
直接返回原始文件
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| end | string | 可省 | 登记时间止 |
| keyword | string | 可省 | 模糊关键词 |
| limit | integer | 可省 | 最多导出条数，默认 20000 |
| start | string | 可省 | 登记时间起 |
| status | string | 可省 | 状态码，逗号分隔 |
cgl_leads_search 11 个参数 lead:read 按关键词/状态/分级/渠道/行业/城市/时间范围搜索线索列表。关键词会模糊匹配姓名、公司、手机、邮箱、职位。默认每页 20 条。
按关键词/状态/分级/渠道/行业/城市/时间范围搜索线索列表。关键词会模糊匹配姓名、公司、手机、邮箱、职位。默认每页 20 条。
对应接口：
GET
/api/v1/leads
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| channel | string | 可省 | 来源渠道 |
| city | string | 可省 | 城市 |
| consultant_id | integer | 可省 | 归属顾问 ID |
| end | string | 可省 | 登记时间止（YYYY-MM-DD） |
| grade | string | 可省 | 分级，逗号分隔，如 'A,B' |
| industry | string | 可省 | 行业 |
| keyword | string | 可省 | 模糊关键词（姓名/公司/手机/邮箱/职位） |
| pageindex | integer | 可省 | 页码，从 1 开始（原站命名，不是 page） |
| pagesize | integer | 可省 | 每页条数，默认 20 |
| start | string | 可省 | 登记时间起（YYYY-MM-DD） |
| status | string | 可省 | 状态码，逗号分隔，如 '1,2'。1=未跟进 2=已拒绝 4=跟进中 6=转化成功 7=无效线索 |
cgl_qrcodes_list 2 个参数 qrcode:read 列出已生成的带参二维码及其扫码数、带来的线索数。
列出已生成的带参二维码及其扫码数、带来的线索数。
对应接口：
GET
/api/v1/qrcodes
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| biz_type | string | 可省 | 业务类型，如 event / survey |
| limit | integer | 可省 | 最多返回条数，默认 50 |
cgl_stats_funnel 0 个参数 stats:read 各线索状态的数量分布（按状态码升序，返回 status/label/count）。状态码 1/2/4/6/7...
各线索状态的数量分布（按状态码升序，返回 status/label/count）。状态码 1/2/4/6/7 不连续：1=未跟进 2=已拒绝 4=跟进中 6=转化成功 7=无效线索。⚠️ 它不代表任何递进关系，而是当前全量线索的状态快照。
对应接口：
GET
/api/v1/stats/funnel
这个动作不需要任何参数。
cgl_stats_leaderboard 2 个参数 stats:read 顾问业绩榜 + 活动排行 + 问卷排行。做「谁做得好」类问题用这个。
顾问业绩榜 + 活动排行 + 问卷排行。做「谁做得好」类问题用这个。
对应接口：
GET
/api/v1/stats/leaderboard
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| days | integer | 可省 | 统计窗口天数，默认 30 |
| limit | integer | 可省 | 每榜取前 N 名，默认 20 |
cgl_stats_overview 1 个参数 stats:read 看板总览：线索总量/新增、报名数、答卷数、高价值线索占比等，含环比。
看板总览：线索总量/新增、报名数、答卷数、高价值线索占比等，含环比。
对应接口：
GET
/api/v1/stats/overview
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| days | integer | 可省 | 统计窗口天数，默认 30 |
cgl_stats_trend 1 个参数 stats:read 新增线索 / 报名 / 答卷的按日趋势。
新增线索 / 报名 / 答卷的按日趋势。
对应接口：
GET
/api/v1/stats/trend
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| days | integer | 可省 | 统计窗口天数，默认 30 |
cgl_survey_answers 1 个参数 必填 1survey:read 列出某问卷的答卷记录。
列出某问卷的答卷记录。
对应接口：
GET
/api/v1/surveys/{qid}/answers
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qid | integer | 必填 | 问卷 ID |
cgl_survey_schema 1 个参数 必填 1survey:read 读取问卷的题目结构（题目、选项、类型），用于理解答卷里的字段含义。
读取问卷的题目结构（题目、选项、类型），用于理解答卷里的字段含义。
对应接口：
GET
/api/v1/surveys/{qid}/schema
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| qid | integer | 必填 | 问卷 ID |
cgl_surveys_list 1 个参数 survey:read 列出问卷及其答卷数、访问量。
列出问卷及其答卷数、访问量。
对应接口：
GET
/api/v1/surveys
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | 可省 | 问卷名模糊搜索 |
cgl_whoami 0 个参数 确认当前 API Key 有效，并列出它的权限范围和数据可见量。任何其他操作之前先跑这个：确认 key...
确认当前 API Key 有效，并列出它的权限范围和数据可见量。任何其他操作之前先跑这个：确认 key 能用、有没有写权限，避免误判「系统没数据」。
对应接口：
GET
/api/v1/meta/scopes
这个动作不需要任何参数。
不同的人，能看到的菜单不一样
钥匙分四种角色。给市场部同事发的一般是 manager，
给只读用途的发 viewer。
| 角色 | 几个权限 | 具体是哪些 | 定义在哪（改权限要改这里） |
|---|---|---|---|
| consultant | 7 | event:read lead:read lead:write qrcode:read qrcode:write stats:read survey:read | app/routers/api/v1.py |
| manager | 9 | event:read event:write lead:read lead:write qrcode:read qrcode:write stats:read survey:read survey:write | app/routers/api/v1.py |
| viewer | 4 | event:read lead:read stats:read survey:read | app/routers/api/v1.py |
| admin | 11 | event:read event:write lead:read lead:read_pii lead:write qrcode:read qrcode:write stats:read survey:read survey:write token:admin | scripts/issue_token.py |
viewer（最小权限）处理——
猜不出来就往严的方向猜，不会因为写错一个角色名就把权限放大。
admin 比 manager 多两样：
看真实手机号（lead:read_pii）和管理钥匙本身（token:admin）。
签发钥匙的工具在 scripts/issue_token.py。