📦 deps(tsl): sync tsl-playbook from a71480a4

Source-Commit: a71480a4ae

skills/tsl-syntax-reference/references/05_functions_and_calls.md

@@ -4,12 +4,18 @@
 
 ## 本篇职责
 
+<!-- section-id: syntax-05-001 -->
+
 回答“如何正确声明 `function` 和 `procedure`、`.tsl` 脚本语句区如何调用后置函数声明、怎样使用参数修饰、普通函数默认参数与可变参数，以及哪些函数写法会直接编译失败”。
 
 ## 核心规则
 
+<!-- section-id: syntax-05-002 -->
+
 - 最稳妥的函数骨架仍然是 `function Name(...); begin ... end;`。
+<!-- quickstart-rule: function-default -->
 - 用户提示词里的“函数”默认对应 `function`，不要自动改写成 `procedure`。
+<!-- quickstart-rule: procedure-explicit -->
 - `procedure Name(...); begin ... end;` 只在用户明确要求 `procedure` / 过程时生成；不要因为没有返回值就自动改用 `procedure`。
 - `procedure` 头后不允许写返回类型；返回类型注解只用于 `function`。
 - 在 `.tsl` 文件模型层，脚本语句后可以接函数声明；语句区在前顺序执行，声明区在后提供函数/过程定义。见 [02_core_model.md](02_core_model.md)。
@@ -29,8 +35,10 @@
 - 如果不确定任务是否需要写回语义，优先显式用 `const` 形参，或先切到 `{$varByRef-}`；不要依赖未修饰参数的运行时默认行为。
 - `return expr;` 会直接返回当前函数结果。
 - `exit;` 会立即结束当前函数；在本页最小样例里，如果此前没有写入返回结果，调用方观察到的是默认值 `0`。
+<!-- quickstart-rule: named-arguments -->
 - 调用时支持命名参数，写法是 `name: value`。
 - 命名参数也支持 `call(...)` 这类按函数名或函数指针转调的模型。
+<!-- quickstart-rule: named-argument-order -->
 - 一旦某次调用里开始使用命名参数，后面的参数就不能再退回位置参数。
 - 对二进制函数 / 系统函数直接使用命名参数，会报 `named parameter mode can't support here`；这类函数要先用 TSL 再封一层。
 - 函数参数支持默认值。
@@ -50,6 +58,8 @@
 
 ## 可直接照写示例
 
+<!-- section-id: syntax-05-003 -->
+
 使用这些示例时遵守：
 
 - 普通运行示例默认按 `.tsl` 脚本语句区书写；入口语句放前面，函数 / 过程 / 类型声明放在后置声明区。
@@ -59,6 +69,8 @@
 
 ### 基础函数 / 过程骨架
 
+<!-- section-id: syntax-05-004 -->
+
 <!-- tags: 定义函数, 怎么写函数, 函数骨架, 最少几行, procedure 怎么写, 函数放哪里, 先调用后声明 -->
 
 `.tsl` 语句区调用后置函数声明：
@@ -141,6 +153,8 @@ end;
 
 ### 签名增强：参数类型与返回值类型注解
 
+<!-- section-id: syntax-05-005 -->
+
 <!-- tags: 返回值类型, 声明返回类型, 参数标类型, 类型注解, 函数签名 -->
 
 带参数类型和返回值类型：
@@ -200,6 +214,8 @@ end;
 
 ### 参数传递方式
 
+<!-- section-id: syntax-05-006 -->
+
 <!-- tags: 传引用, 按引用传, 引用传递, 传值, 按值传递, 改形参影响外面, 写回调用方, 出参, 入参, 只读参数, 不让函数改 -->
 
 未修饰参数默认写回调用方：
@@ -317,6 +333,8 @@ end;
 
 ### `return` 与 `exit`
 
+<!-- section-id: syntax-05-007 -->
+
 <!-- tags: 返回值, 怎么返回结果, 结果返回, 提前结束, 提前返回, 中途退出函数, 无返回值退出 -->
 
 代码块身份：可直接照写示例
@@ -349,6 +367,8 @@ end;
 
 ### 调用增强：命名参数与混用规则
 
+<!-- section-id: syntax-05-008 -->
+
 <!-- tags: 按参数名传, 命名实参, 关键字参数, 指定参数名, 位置参数混用 -->
 
 命名参数调用：
@@ -428,6 +448,8 @@ end;
 
 ### 默认参数
 
+<!-- section-id: syntax-05-009 -->
+
 <!-- tags: 默认值, 可选参数, 参数省略, 不传就用默认 -->
 
 默认值参数：
@@ -514,6 +536,8 @@ function F(a, b = 100, c = default_value);
 
 ### 可变参数 `...`
 
+<!-- section-id: syntax-05-010 -->
+
 <!-- tags: 任意多个参数, 不定参数, 变长参数, 参数个数不固定, 参数转发 -->
 
 尾部可变参数：
@@ -652,6 +676,8 @@ end;
 
 ### 匿名函数与函数指针
 
+<!-- section-id: syntax-05-011 -->
+
 <!-- tags: lambda, 闭包, 函数当变量, 函数当参数, 回调, 函数指针, 把函数存起来 -->
 
 匿名函数变量：
@@ -775,6 +801,8 @@ writeLn(a(7, 8));
 
 ### `::` 指向全局函数
 
+<!-- section-id: syntax-05-012 -->
+
 <!-- tags: 重名, 同名函数, 调全局的那个, 作用域冲突, 指定全局函数 -->
 
 当当前作用域里有同名局部函数时，可以用 `::FuncName(...)` 指定去调全局/系统函数：
@@ -813,10 +841,14 @@ end;
 
 ### 系统交互专题
 
+<!-- section-id: syntax-05-013 -->
+
 `external`、原生函数指针包装、`makeInstance` / C 回调和线程调用，统一见 [17_external_calls_and_threads.md](17_external_calls_and_threads.md)。这一篇只保留“普通函数怎样定义和调用”的主线。
 
 ## 默认生成模板
 
+<!-- section-id: syntax-05-014 -->
+
 如果你只是要写一个能被智能体稳定续写的 `.tsl` 脚本，从语句区起步，需要函数时把声明区放在后面：
 
 代码块身份：可直接照写示例
@@ -853,6 +885,8 @@ end;
 
 ## 禁止项
 
+<!-- section-id: syntax-05-015 -->
+
 - 在 `.tsl` 的声明区后面继续写脚本语句。
 - 用户只说“写一个函数”时，默认改成 `procedure`。
 - 因为任务没有返回值，就自动改成 `procedure`。