csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(tsl): restructure agent-facing reference

Browse Source 
Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation.

Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
This commit is contained in:
csh
2026-06-09 17:24:30 +08:00
parent 9c194170a1
commit 540b3c0a1b
192 changed files with 32929 additions and 13533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tsl/modules/wechat_message.md
+230 -74
View File
@@ -1,90 +1,246 @@
# 发送微信消息使用说明
文档类型：模块摘要
是否可直接用于生成代码：仅部分
遇到不确定时跳转到：调用侧账户体系文档、项目实际接口说明、[index.md](index.md)
文档类型：模块 API 事实页
是否可直接用于生成代码：是，但 `userid`、`username`、模板标题、模板关键字含义和真实通知内容必须来自用户需求或项目上下文
遇到不确定时：[index.md](index.md)、调用侧账户体系文档、项目实际接口说明、天软科技服务号模板列表
本页用于确认接口名称、参数含义和风险边界，不替代项目级接入文档。
本页整理通过“天软科技服务号”发送微信模板消息的接口事实。它负责告诉智能体“该调用哪个函数、参数顺序是什么、同步和异步怎么选择、状态如何查询”，不负责替用户创造账户、授权关系、模板映射或通知内容。
## Agent 微信消息边界规则
## 智能体微信消息决策规则
- 先确认调用侧已经提供 `userid`、模板类型、关键字含义和必要的账户字段。
- 本页只给接口外形和参数含义；账户体系、授权关系和模板映射以项目实际接口说明为准。
- 不要发明 `username` 来源、模板关键字含义、项目封装函数或账户映射。
## 适用场景
- 通过“天软科技服务号”向微信客户端发送模板消息。
- 支持同步/异步发送，异步可用消息 ID 查询状态。
- 用户要“发送微信通知 / 微信消息 / 微信告警 / 微信模板消息 / 查询微信发送状态”时，优先使用本页。
- 紧急通知、需要立刻知道发送结果时，默认使用 `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` 与用户账户和微信绑定关系相关，应由调用侧提供 |
| 给他人发送时已授权 | 接收者绑定后在服务号 `userid` 页面授权发送者账号，发送者使用接收者提供的 `userid` 发送 |
| 查询异步状态时已取得 `username` | `username` 是账号名，脚本查询发送状态时需要；来源以项目账户体系为准 |
## 核心接口
## 接口总览
- `send_wechat_message(userid, url, title, first, remark[, k1..k6])`
- 同步发送；成功返回 `success`，否则返回错误信息。
- `send_wechat_message_async(userid, url, title, first, remark[, k1..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])` | 同步发送模板消息 | 成功返回字符串 `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)` | 查询异步发送结果 | 成功返回字符串 `成功`；否则返回状态信息或错误信息 |
## 参数说明（模板消息）
## 同步发送
- `userid`：绑定账户后获取的用户标识（必需）。
- `username`：查询异步发送状态时使用的用户名 / 账户标识；当前页只确认查询接口需要它，具体来源以项目实际账户体系或调用侧约定为准。如果调用侧拿不到该值，当前页不支持生成状态查询代码。
- `url`：详情地址（必需，可为空字符串）。
- `title`：模板消息标题（必需）。
- `first`：副标题（一般需要）。
- `remark`：备注（一般需要）。
- `k1..k6`：模板关键字参数（根据模板类型变化）。常见模板示例：
- 监控报告通知：运行状态/时间
- 系统运行简报：系统名称/简报内容/发布时间
- 告警通知：告警内容/发生时间
签名：
## 同步 vs 异步
- 同步：阻塞等待结果，适合紧急通知。
- 异步：立即返回，适合非紧急通知；用 `get_wechat_message_status` 查询。
- 如果你无法确认 `username` 的来源，不要自行猜测；先回调用侧或账户体系文档确认。
## 当前只确认的范围
- 当前页已经确认的范围是：发送接口名、异步发送会返回消息 ID、状态查询接口需要 `userid` + `username` + `wechat_message_id`。
- 当前页没有确认的范围是：`username` 的正式来源、不同模板关键字的完整映射、项目侧的统一封装方式。
## 不要猜的部分
- 不要把 `"username"` 当成可用实参，也不要凭空拼接账户名。
- 如果调用侧没有提供 `username`，当前页只支持生成发送代码，不支持生成状态查询代码。
- `k1..k6` 的含义随模板类型变化；需要和具体模板一起核对。
## 发送示例（配置片段，可参考参数组织）
下面代码只表示参数组织方式；真实账户、模板关键字和调用侧封装以项目实际接口说明为准。
```tsl
// 定义参数
url := "http://tinysoft.com.cn";
user_id := "190F1826267E0EB45658FB81836636A7";
title := "监控报告通知";
first := "运行状态";
keyword_1 := "运行正常";
keyword_2 := "";
DateTimeToString(keyword_2, "YYYY-MM-DD HH:NN:SS", Now());
remark := "如有疑问请与技术人员联系！";
// 同步发送
echo send_wechat_message(user_id, url, title, first, remark, keyword_1, keyword_2);
// 异步发送
wechat_message_id := send_wechat_message_async(user_id, url, title, first, remark, keyword_1, keyword_2);
```text
send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])
```
## 状态查询示例
参数表：
- 当前页不提供状态查询代码块。
- 只有在调用侧已经明确提供 `username` 来源时，才继续生成 `get_wechat_message_status(...)` 调用。
| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- |
| 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` 时，按错误信息处理。
## 异步发送
签名：
```text
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(...)` 查询。
## 查询异步发送状态
签名：
```text
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` 的字段映射。
## 发送示例
同步发送系统运行简报：
```tsl
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：
```tsl
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;
```
查询异步发送结果：
```tsl
function QueryWechatMessageStatus(user_id, username, wechat_message_id);
begin
return get_wechat_message_status(user_id, username, wechat_message_id);
end;
```