playbook/docs/tsl/modules/wechat_message.md

发送微信消息使用说明

文档类型：模块 API 事实页 是否可直接用于生成代码：是，但 userid、username、模板标题、模板关键字含义和真实通知内容必须来自用户需求或项目上下文 遇到不确定时：index.md、调用侧账户体系文档、项目实际接口说明、天软科技服务号模板列表

本页整理通过“天软科技服务号”发送微信模板消息的接口事实。它负责告诉智能体“该调用哪个函数、参数顺序是什么、同步和异步怎么选择、状态如何查询”，不负责替用户创造账户、授权关系、模板映射或通知内容。

智能体微信消息决策规则

• 用户要“发送微信通知 / 微信消息 / 微信告警 / 微信模板消息 / 查询微信发送状态”时，优先使用本页。
• 紧急通知、需要立刻知道发送结果时，默认使用 send_wechat_message(...)。
• 非紧急通知、批量通知、发送后可稍后查询状态时，默认使用 send_wechat_message_async(...)。
• 用户要求查询异步状态时，生成 get_wechat_message_status(userid, username, wechat_message_id)；三个实参必须来自参数、已知变量或项目上下文。
• 参数必须严格按接口顺序传入；所有参数按字符串处理。
• url 是固定位置参数；无详情地址时传空字符串 ""。
• k1 到 k6 的含义由模板标题决定；只按模板映射或用户输入填充，不要发明关键字含义。
• 用户要求“通知第一眼看到”的内容时，放入带字段名的 kN 参数；first 和 remark 只作为点入通知后的详情文本。
• 给他人发消息时，必须使用接收者授权给发送者的 userid，不要把发送者自己的 userid 当成接收者标识。
• 不要发明 userid、username、项目封装函数、模板标题、模板关键字、授权关系或账号映射。

前置条件

条件	说明
已绑定服务号	首次使用需要关注并绑定“天软科技服务号”，绑定后取得 userid
已取得 userid	userid 与用户账户和微信绑定关系相关，应由调用侧提供
给他人发送时已授权	接收者绑定后在服务号 userid 页面授权发送者账号，发送者使用接收者提供的 userid 发送
查询异步状态时已取得 username	username 是账号名，脚本查询发送状态时需要；来源以项目账户体系为准

接口总览

函数	用途	返回值
send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])	同步发送模板消息	成功返回字符串 success；失败返回错误信息
send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])	异步发送模板消息	返回 16 位字符串消息 ID
get_wechat_message_status(userid, username, wechat_message_id)	查询异步发送结果	成功返回字符串 成功；否则返回状态信息或错误信息

同步发送

签名：

send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])

参数表：

参数位置	参数名	必填	接收类型	说明
1	userid	是	字符串	绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 userid
2	url	是	字符串	详情地址；没有详情地址时传 ""
3	title	是	字符串	模板消息标题，例如 监控报告通知
4	first	是	字符串	详情页开头文本；不作为通知列表首屏字段
5	remark	是	字符串	详情页结尾备注；不作为通知列表首屏字段
6	k1	条件必填	字符串	模板关键字 1；带字段名的 kN 行属于首屏展示字段
7	k2	条件必填	字符串	模板关键字 2；带字段名的 kN 行属于首屏展示字段
8	k3	否	字符串	模板关键字 3；部分模板需要
9	k4	否	字符串	模板关键字 4；部分模板需要
10	k5	否	字符串	模板关键字 5；部分模板需要
11	k6	否	字符串	模板关键字 6；部分模板需要

返回值：

返回值	含义
success	同步发送成功
其他字符串	错误信息

使用规则：

• 同步发送会阻塞当前程序，必须等待发送函数执行完毕后才进入下一步。
• 紧急通知优先使用同步发送。
• 返回值不是 success 时，按错误信息处理。

异步发送

签名：

send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])

参数表：

参数位置	参数名	必填	接收类型	说明
1	userid	是	字符串	绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 userid
2	url	是	字符串	详情地址；没有详情地址时传 ""
3	title	是	字符串	模板消息标题
4	first	是	字符串	详情页开头文本；不作为通知列表首屏字段
5	remark	是	字符串	详情页结尾备注；不作为通知列表首屏字段
6	k1	条件必填	字符串	模板关键字 1；带字段名的 kN 行属于首屏展示字段
7	k2	条件必填	字符串	模板关键字 2；带字段名的 kN 行属于首屏展示字段
8	k3	否	字符串	模板关键字 3；部分模板需要
9	k4	否	字符串	模板关键字 4；部分模板需要
10	k5	否	字符串	模板关键字 5；部分模板需要
11	k6	否	字符串	模板关键字 6；部分模板需要

返回值：

返回值	含义
16 位字符串	异步消息 ID；前 10 位为 1900 年以来的秒数，后 6 位为随机数

使用规则：

• 异步发送把命令提交给服务器后立即返回，不等待最终发送结果。
• 非紧急通知优先使用异步发送。
• 需要最终结果时，保存返回的 wechat_message_id，再调用 get_wechat_message_status(...) 查询。

查询异步发送状态

签名：

get_wechat_message_status(userid, username, wechat_message_id)

参数表：

参数位置	参数名	必填	接收类型	说明
1	userid	是	字符串	发送时使用的用户标识
2	username	是	字符串	账号名；脚本执行查询时需要，来源以项目账户体系为准
3	wechat_message_id	是	字符串	send_wechat_message_async(...) 返回的 16 位消息 ID

返回值：

返回值	含义
成功	异步消息发送成功
其他字符串	状态信息或错误信息

调用规则：

• 状态查询用于异步发送后的结果确认。
• username 按账号名参数、已知变量或项目上下文传入，不写字面量 "username"。
• wechat_message_id 使用 send_wechat_message_async(...) 的返回值。

模板展示规则

模板片段	展示位置	生成规则
字段名：{{kN}}	通知列表首屏可见	用户要求“第一眼看到”的信息放到对应 kN
{{first}}	点入通知后的详情页开头	放说明、背景、摘要引导；不承载首屏必须展示的信息
{{remark}}	点入通知后的详情页结尾	放补充说明、处理建议、联系人等尾部信息
字面标题行，例如 监控报告通知	模板固定内容	不作为接口参数；接口参数 title 仍使用模板标题
动态标签行，例如 {{k5}}幅：{{k6}}	通知列表首屏可见	k5 填字段标签的一部分，k6 填对应数值

生成规则：

• title 决定模板，k1 到 k6 按模板字段名依次填入。
• 有名称的 kN 行是首屏展示字段；需要首屏展示的信息优先放入 kN。
• first 和 remark 是详情页内容；不要把“第一眼必须看到”的核心字段放入 first 或 remark。
• 模板未列出的 kN 不主动传入；需要扩展字段时先换模板或由用户提供模板映射。

模板关键字映射

系统监控类

模板标题	k1	k2	k3	k4	k5	k6
系统运行简报	系统名称	简报内容	发布时间
监控报告通知	运行状态	时间
监控结果通知	监控项目	内容	时间
告警通知	告警内容	告警发生时间
故障恢复通知	故障信息	恢复时间
服务器异常监控通知	监控通知	监控通知类型	监控通知内容
服务器宕机通知	故障时间	故障原因
服务器恢复通知	故障停止时间	故障持续时间

交易通知类

模板标题	k1	k2	k3	k4	k5	k6
交易成功通知	交易金额	交易类型	交易时间	交易单号
交易完成通知	股票简称	股票代码	股票价格	交易状态	股票数量
交易下单通知	交易品种	下单方向	下单价格	止损价格	下单时间
成交回报提示	证券名称	证券代码	买卖标识	成交价格	成交数量	成交时间
委托成交提醒	数量	价格	时间

策略通知类

模板标题	k1	k2	k3	k4	k5	k6
投资策略更新提醒	策略名称	操作风格	目前策略收益
股票调仓通知	股票名称	操作类型	调仓时间	调仓价格	调仓仓位
实时建仓提醒	品种	方向	仓位	价格	止盈止损
个股到价通知	股票名	当前成交价	预警价
个股涨跌幅通知	股票名	当前成交价	对比日期	对比收盘价	动态标签，组成 {{k5}}幅	动态值

其他通知类

模板标题	k1	k2	k3	k4	k5	k6
账号绑定成功通知	账号名称	绑定时间
服务开启通知
授权请求通知	申请人	请求权限

服务开启通知 当前只记录模板标题，未固定 k1 到 k6 的字段映射。

发送示例

同步发送系统运行简报：

function SendSystemBrief(user_id);
begin
    url := "";
    title := "系统运行简报";
    first := "系统运行情况如下。";
    k1 := "风控服务";
    k2 := "运行正常";
    dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now());
    remark := "如有疑问请联系值班人员。";

    return send_wechat_message(user_id, url, title, first, remark, k1, k2, k3);
end;

异步发送并保留消息 ID：

function SendSystemBriefAsync(user_id);
begin
    url := "";
    title := "系统运行简报";
    first := "系统运行情况如下。";
    k1 := "风控服务";
    k2 := "运行正常";
    dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now());
    remark := "如有疑问请联系值班人员。";

    return send_wechat_message_async(user_id, url, title, first, remark, k1, k2, k3);
end;

查询异步发送结果：

function QueryWechatMessageStatus(user_id, username, wechat_message_id);
begin
    return get_wechat_message_status(user_id, username, wechat_message_id);
end;