Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/sms-vercode-latest-mcp-design.md
T
my_local_kimi_dev2 021cee37df feat(mcp): 新增短信验证码提取工具 sms.vercode.latest.query(REQ-20261113-0009)
按手机号提取 m0 sms_send_record 最近一条验证码(buss_type=验证码+soft_delete=0+id DESC
首条),正则提取 4-8 位数字码,send_state 不过滤并配文案,返回 ageSeconds 供判断 90s
redis 有效期。零行级权限,安全模型靠专用 scope 门禁:prod 只绑研发专用 scope 6、dev 只绑
测试专用 scope,显式排除业务 scope(全平台唯一)。王恒拍板 4 决策点全部按建议值执行。
测试:SmsToolsTest 10 例全绿;测试环境冒烟 4/4(有记录提取/无记录 notice/非法入参/
operation scope 拒绝)。
2026-11-13 17:41:41 +08:00

5.7 KiB
Raw Blame History

短信验证码提取工具 MCP 设计(REQ-20261113-0009,已批准 2026-11-13)

拍板结论(2026-11-13 王恒):§7 四个待拍板点全部按建议值执行—— ① buss_type 固定过滤"验证码";② send_state 不过滤、失败记录也返回并标注; ③ 不加时间窗、返回 ageSeconds;④ 工具名 sms.vercode.latest.query、category=admin。 (实现注:kind 按平台惯例为 read/write,本工具 kind=read,设计稿中"query"为笔误。)

1. 背景

研发/测试场景需要"按手机号提取最近一条短信验证码"(自动化登录、联调、测试账号验证)。 老系统没有现成查询接口,目前只能人工查库。本设计新增 1 个只读 MCP 工具。

敏感性说明:验证码 = 登录绕过原语。本工具按运维工具口径设计——零行级权限, 访问控制完全靠专用 scope 门禁(同 warehouse.order.handler.update 模式), 只绑研发专用/测试专用作用域,永不绑业务 scope(prod 1/2/3/5)。

2. 数据源调研结论

表:m0 sms_send_record(参考库 beans/b0/SmsSendRecord.java,m0 mapper)。

列 说明
user_mobile 手机号
sms_content 发送内容,验证码记录为 验证码=123456 或 【小趣智品】验证码=123456
buss_type 业务类型,验证码记录固定为 验证码(SendSmsController.java:84/97、LoginController.java:195/208、AccountController、ChargeController 均同)
send_state 0 成功 / 1 失败(失败记录 content 里也有码,但 redis 未写入,实际不可用)
report_state 验证码记录固定写 99(不过滤)
soft_delete 0 正常 / 99 停用
create_time 发送时间

验证码本体:RandomUtil.randomNumbers(6),6 位数字;redis 有效期 90 秒 (SendSmsController.java:93)。非生产/白名单环境直接返回 123456 且不落库, 所以测试环境查不到记录属正常现象。

3. 工具定义

项 值
工具名 sms.vercode.latest.query
category admin
kind read(只读)
工具类 新建 SmsTools(同域后续可加短信记录列表工具)
数据源 纯 MySQL m0,无 ES、无 Redis
行级权限 无(scope 门禁,见 §6)

4. 参数契约

参数 类型 必填 说明
mobile string 是 11 位手机号,精确匹配 user_mobile

查询口径(固定,全部保老系统写入口径):

  • user_mobile = mobile
  • buss_type = '验证码'
  • soft_delete = 0
  • 按 id DESC 取第一条(自增 id 等价于 create_time 最新,避免时间精度并列)

提取规则:对 sms_content 跑正则 验证码\s*[=::]\s*(\d{4,8}),命中取第一组; 不命中(历史脏数据/格式漂移)返回 vercode=null + 原始 smsContent,不报错。

5. 返回契约

统一 ToolResult 结构,record 对象:

{
  "record": {
    "id": 123456789,
    "mobile": "13800000000",
    "vercode": "483920",
    "smsContent": "验证码=483920",
    "sendState": 0,
    "sendStateText": "发送成功",
    "bussType": "验证码",
    "createTime": "2026-11-13 17:20:30",
    "ageSeconds": 45
  },
  "notice": null
}
  • 无记录:record=null + notice="该手机号暂无验证码短信记录"
  • ageSeconds = 当前时间 - createTime,供调用方判断 90 秒有效期(工具不做硬过期判断, 失败记录 sendState=1 也照样返回并配文案,由调用方决定可用性——待拍板点 2)
  • 错误码:INVALID_ARGUMENT(手机号为空/非 11 位),ToolCallException 透出文案

6. scope 绑定(安全核心)

环境 绑定 说明
prod 只绑 scope 6(研发专用,code=code) INSERT IGNORE scope_tool(6, tool_id);严禁绑 1/2/3/5
dev seed-dev 只加「测试专用」scope 绑定 不加 operation 等业务 scope

按 2026-11-07 王恒口径"所有工具默认绑研发专用 scope 6",本工具是唯一显式排除 其他所有 scope 的工具(其他查询工具是"默认绑 6",本工具是"只绑 6")。 服务 Token 只有 sync 作用域,天然调不到。

审计:每次调用落 svc audit_log(含调用方 token 身份、入参 mobile、request_id), 与现有工具审计链路一致。

7. 待拍板点(建议值)

  1. buss_type 固定过滤"验证码"(建议)vs 不过滤取任意短信最新一条。
  2. send_state 不过滤,最新一条即使是发送失败也返回、文案标注(建议——失败记录 同样能反映"系统生成了什么码",联调更有用)vs 只看 send_state=0。
  3. 不做时间窗硬限制,返回 ageSeconds(建议)vs 加 withinMinutes 参数只查近 N 分钟。
  4. 工具名 sms.vercode.latest.query(建议),category=admin。

8. 变更文件清单

  • 新增 entity/m0/SmsSendRecord.java(本地拷贝,全列对齐参考库——PR #31 教训)
  • 新增 mapper/m0/SmsSendRecordMapper.java
  • 新增 mcp/tool/SmsTools.java(1 个工具方法)
  • 新增 SmsToolsTest(参数校验/提取正则含【小趣智品】前缀格式/空记录/sendState 文案/soft_delete 过滤)
  • sql/seed-dev.sql:测试专用 scope 绑定
  • README.md + doc/agent-mcp-tools-reference.md:登记
  • 装配层零改动(ToolObject 扫描自动注册)

9. 测试与上线流程

按 AGENTS.md 标准流程:单测全绿 → ./deploy/test-up.sh 测试环境冒烟 (scopeCode=test 签 Token;注意 dev 库可能无验证码记录,空记录路径也要验)→ push main → remote-deploy → 确认 ToolSyncService 新增 tool → 绑 prod scope 6 → 生产只读核验(tools/list 可见 + 真实手机号查询)。ai-proj 走自审批闭环。