📝 docs(tsl-syntax-reference): document external and remote calls

2026-08-10 18:22:35 +08:00
parent a23f688b01
commit 2938300acb
5 changed files with 233 additions and 69 deletions
@@ -0,0 +1,67 @@
+# TSL 客户端远程调用
+
+这一篇只处理 `RDo` / `RDo2` 调用客户端本地函数的语法外形、等待行为、系统参数后缀和超时后缀。
+
+## 本篇职责
+
+<!-- section-id: syntax-24-001 -->
+
+回答“怎样从平台调用客户端本地函数、`RDo` 与 `RDo2` 有什么区别、`With` 与 `TimeOut` 写在哪里，以及为什么不能写成 `RDo(...)` / `RDo2(...)`”。
+
+## 核心规则
+
+<!-- section-id: syntax-24-002 -->
+
+<!-- tags: 客户端远程调用 本地函数 不等待 等待返回 rdo rdo2 -->
+
+- `RDo` 和 `RDo2` 是客户端远程调用关键字，不是普通函数。
+- 两者都写在被调用的本地函数之前；圆括号属于本地函数调用，不属于 `RDo` / `RDo2`。
+- `RDo` 只提交任务，不等待本地函数执行完成，也不取得函数返回值。
+- `RDo2` 等待本地函数执行完成，并把该函数的结果作为整个表达式的值。
+- 本地函数需要系统参数时，在调用后追加 `With SysParams`。
+- `RDo2` 默认超时为 300 秒；需要自定义时，在末尾追加 `TimeOut Seconds`。文档定义的后缀顺序是先 `With`、后 `TimeOut`。
+- `RDo2` 在客户机执行时需要用户权限许可；依赖客户端资源的函数不能在无 GUI 的命令行解释器中验证其交互结果。
+- 被调用函数的精确签名、参数写回、返回值及运行时 scope 必须使用 `tsl-api-reference` skill 单独查询；本页只拥有 `RDo` / `RDo2` 的语法形态。
+
+## `RDo` / `RDo2` 语法与示例
+
+<!-- section-id: syntax-24-003 -->
+
+<!-- tags: RDo写法 RDo2写法 InputQuery 客户端输入 对话框 远程调用超时 With系统参数 -->
+
+原文定义使用下面的元语法；方括号表示可选部分，不是需要写进 TSL 源码的字符：
+
+代码块身份：配置片段 / 概念骨架
+
+```text
+RDo LocalFunctionName(P1; P2; …) [With SysParams];
+RDo2 LocalFunctionName(P1; P2; …) [With SysParams] [TimeOut Seconds]: Any;
+```
+
+`RDo2` 调用客户端 `InputQuery` 的原文范例可整理为：
+
+代码块身份：可直接照写示例
+代码块说明：需要平台客户端交互环境、用户权限许可，并要求目标环境提供 `InputQuery`；无 GUI 的命令行解释器不能验证弹窗结果。
+
+```tsl
+value := "";
+if rdo2 InputQuery("Input", "Hint", value) then
+    return value;
+else
+    return "Canceled";
+```
+
+结果说明：
+
+- 用户确认时，`InputQuery` 返回真，输入内容写回 `value`，脚本返回该字符串。
+- 用户取消时，`InputQuery` 返回假，脚本返回 `Canceled`。
+- 这段代码证明的是前缀形态 `rdo2 InputQuery(...)`；`InputQuery` 的 API 事实仍需按目标 scope 单独查询。
+
+## 禁止项
+
+<!-- section-id: syntax-24-004 -->
+
+- 把关键字建模成 `RDo()` 或 `RDo2(...)` 普通函数。
+- 把被调用本地函数的参数误写成 `RDo2` 自身的参数表。
+- 声称 `RDo` 会返回客户端函数结果。
+- 忽略 `RDo2` 的客户端权限与交互环境要求。